# This file is used by store_monitor_data, config_graphs and create_report # in order to generate all desired graphs and tables. # Comments must start with # before any non-whitespace. # All entries involve a key, colon, followed by arbitrary whitespace, and # one or more values separated by commas and optional whitespace. # Key and values must be on the same line; a linefeed will break parsing. # The 'name' key is used to identify unique stanzas and cannot be changed. # If required stanzas are missing or lack required keys, the behavior of # scripts that rely on them is undefined. # All directory paths can have trailing slashes, but they are not required. # General options. OPTIONAL shared { name: general # Output debugging information # OPTIONAL, defaults to 0. debug: 1 # Whether to use 2-letter or 3-letter country codes when converting. # OPTIONAL, defaults to 2. # country_abbr: 2 # Used solely by create_report. If this is non-zero, then a warning is # output when no monitors have new data and thus no new graphs are # generated. # OPTIONAL, defaults to 0. # non_creation_warning: 1 # Used solely by store_monitor_data. If this is non-zero, unknown ICMP # codes/types will be given a unique name when doing application # lookup. This generally leads to an unwieldy amount of RRD files and # is generally not recommended. # OPTIONAL, defaults to 0. # separate_icmp_codes: 0 } # The 'colors' and 'long_names' stanzas are passed verbatim to # create_graphs. # Colors are defined globally for consistency across graphs, by data source # name. There may potentially be a source name that is used by different # source types, for example 17 might be used by 'proto' and 'src_as'. In # this case, both would be colored with the same color. DEPRECATED #shared { # name: colors # UNKNOWN_TCP: #999999 # UNKNOWN_UDP: #777777 # HTTP: #FF0000 # SSH: #22FF22 # 6: #00FF00 # 17: #00FFFF # 1: #0000FF #} # Due to above-mentioned sharing of protocol/AS source names, # category-specific color mappings can be specified, and are recommended # for clarity. OPTIONAL. #shared { # name: proto_colors # 6: #00FF00 # 17: #00FFFF # 1: #0000FF #} #shared { # name: as_colors # 17: #AA1100 #} # ... etc (proto_colors, app_colors, country_colors, as_colors) # Pairs of data names and their full name expansions. This is used in # to write a different name on graphs than the source's filename. The # above problem with conflicts applies doubly here; one would not want # an AS number displayed as 'UDP', for instance. DEPRECATED. #shared { # name: long_names # HTTP: World Wide Web # FTP_DATA: FTP data # ICMP_ECHO: Ping #} # Due to above-mentioned sharing of protocol/AS source names, # category-specific name mappings can be specified, and are recommended # for clarity. OPTIONAL. #shared { # name: proto_names # 6: TCP # 17: UDP # 1: ICMP #} #shared { # name: app_names # FTP_DATA: FTP data # ICMP_ECHO: Ping #} # ... etc (proto_names, app_names, country_names, as_names) # Parameters used for creating RRD files, used only by store_monitor_data. # Once a specific RRD has been created, these cannot be changed. Mixing # RRDs with different creation parameters will not necessarily break the # software, but it may cause some unexpected results. REQUIRED shared { name: rrd_creation # Number of seconds that single data point spans. # REQUIRED step: 300 # Maximum number of seconds allowed between samples before interval is # considered 'unknown' data. # REQUIRED heartbeat: 600 # The 'xfiles-factor', this is the fraction of a consolidated interval # can be unknown and still allow a known aggregated value. # REQUIRED xff: 0.5 # A list of the number of primary data points used for different # granularities of archive. For example, with a step value of 300 (5 # minutes), these values represent granularities of 5 minute, 30 minute, # 2 hour, and 24 hours, respectively. # REQUIRED rra_steps: 1, 6, 24, 288 # A list of number of rows for each value above. Thus, 576 rows of # data are stored at 5 minute granularity (for a total of 2 days worth), # 672 rows of 30 minute granularity (2 weeks), etc. # REQUIRED rra_rows: 576, 672, 768, 760 } # Paths to different applications and files. # OPTIONAL, but highly recommended. shared { name: paths # The netacq application is a Caida-internal tool for quick IP->lat/lon # lookups. # OPTIONAL # netacq: ./netacq # Another Caida-internal file for quicker IP->country lookups. # country_table: ./prefix2country.txt # Parsed BGP dump file, suitable for ASFinder. # Created by running parse_bgp_dump -g on input from # http://archive.routeviews.org/oix-route-views/ # parse_bgp_dump is described at # https://www.caida.org/tools/measurement/coralreef/doc/doc/applications.html#parse_bgp_dump # REQUIRED for doing any AS/Country lookups. Absence will cause all # ASes and countries to be classified as UNKNOWN. # routes: ./prefix2as.txt # Port to application mapping file, used by AppPorts. # OPTIONAL, defaults to the ports file installed with CoralReef in # Coral/etc/Application_ports_Master.txt # ports: ./application_ports.txt } # Used by create_report for tranferring files to web server. # OPTIONAL, files will not be transferred without this stanza. #shared { # name: transfer # Command used to copy the files. # REQUIRED # cp_cmd: rsync -q -Cae 'ssh -c blowfish' # Web server hostname. Current assumption is that display_report will # be running on the same server that holds the generated image files. # OPTIONAL. If missing, the files will be copied on the same machine. # server: www # CGI directory on web server, where text files are sent. # These will be placed in a subdirectory for the corresponding monitor. # This directory must already exist. # REQUIRED # cgi_dir: ./cgi-bin # HTML directory on web server, where images are sent. # These will be placed in a subdirectory for the corresponding monitor. # This directory must already exist. # REQUIRED # html_dir: ./report_generator/images #} # The default stanza contains all the default values for the monitor # stanzas. When looking for information about a monitor, the default fields # will be used if there is no overriding field in the monitor stanza. # Thus, if all monitors have the same fields, those can be put here. The # monitor stanzas would then only require the 'name' field. #shared { # name: default #} # One entry for each monitor, which will generate multiple graph commands. # REQUIRED monitor { # The values for these particular 'name' keys are how the monitors are # referred to in all places. # REQUIRED name: monitor1 # Top N RRDs to save sorting order for. Used by store_monitor_data to # decrease search time over thousands of RRDs. NOT the same as the top # N in the graph commands. # OPTIONAL top_n: 100 # Counters are different data sets stored within the same RRD. # One set of graphs is created for each counter. # Available counters are bits, packets, and tuples. # REQUIRED counters: bits, packets, tuples # List of desired tables. store_monitor_data takes input in the form # of a Tuple_Table and converts into these tables for storage. # Categories are defined from these, for example Proto Table becomes # proto, or src AS Table becomes src_as. # NB: Capitalization matters. Future releases might be more # fault-tolerant of this. # Tables with lots of entries (such as AS tables) will create many RRD # files and should be used with caution. # Available table types are: Proto Table, App Table, src AS Table, dst AS Table, src Country Table, dst Country Table # REQUIRED tables: Proto Table, App Table # Mapping of categories to full names, used by config_graphs. # REQUIRED #cat_map: proto, Protocol, app, Application, src_as, Source AS, dst_as, Destination AS, src_country, Source Country, dst_country, Destination Country cat_map: proto, Protocol, app, Application # Determines what kinds of timeseries graphs to make. Can be 'abs' # (for absolute values), 'perc' (for percentage-based graphs), or 'both'. # OPTIONAL, defaults to 'abs'. # abs_or_perc: both # Number of hours to offset new data before graphing it. Effectively # make the endtime be the timestamp of most recent data, minus delay*3600. # OPTIONAL, defaults to 0. # delay: 0 # Booleans determining whether to make timeseries, big timeseries, pie, # table, or map output, respectively. # OPTIONAL, all default to 0 (creating no graphs). make_ts: 1 # make_big_ts: 1 make_pie: 1 make_table: 1 # make_map: 1 # Determines whether or not an 'other' value is shown in output # graph/table. # OPTIONAL, defaults to 0. use_other: 1 # Limits the total number of RRDs to be displayed. Usually used in # conjunction with the 'joint_area' option of to_graph, which can # produce a list longer than N. # OPTIONAL, defaults to unlimited number of RRDs. max_rrds: 15 # Specify what to graph. This can be either a list of specific RRDs # or a three-entry list with the following meanings: # first field: 'top ', such that the top N entries are displayed # second field: 'recent', 'area ', 'separate_area', or # 'joint_area'. 'recent' calculates the top N by the most recently # stored data, 'area' will use the graphed area in the same specified # interval for all graphs, 'separate_area' will use each interval's own # graphed area, and 'joint_area' will use all intervals to determine # a single top N list for all graphs. # third field: RRD consolidation function to sort by (defaults to # AVERAGE). # NB: Listing specific RRDs will only work when only a single category # type is used. This list is applied to all graphs, and thus a list of # countries would not work when graphing protocols, for instance. # REQUIRED to_graph: top 10, joint_area # Graphing function is an RRDtool function, can be MAX, MIN, or AVERAGE # Can be different than function used in to_graph. Thus, one could # graph the averages of value over an interval, but sorted by their # maxima. # REQUIRED graph_func: AVERAGE # Directories for storing output files on processing machine before # transferring to the web server. graph_dir holds all standard images, # big_dir is used when make_big_ts is true, to hold larger timeseries # graphs, and table_dir holds the text data necessary for the CGI # script. These directories will be created if necessary, but all # higher level directories will NOT be created. # REQUIRED graph_dir: ./graphs big_dir: ./big_graphs table_dir: ./tables # Top-level RRD directory on processing machine where all RRD files are # stored. Each monitor's data will be stored in a subdirectory of this # one. This directory will be created if necessary, but all higher # level directories will NOT be created. # REQUIRED rrd_dir: ./rrd_data # Width and height (in pixels) of output graphs. Ignored for text # output. Maps only use these values if no source image is used. # Timeseries graphs use them for the graph area, but add pixels for # borders and legend. big_dimensions is the width and height of the # large timeseries graphs, used when make_big_ts is true. # REQUIRED dimensions: 300, 300 # REQUIRED if make_big_ts is set to 1. big_dimensions: 600, 400 # Intervals, in hours, to display. # REQUIRED intervals: 24, 168, 672, 17520 # Default colors to be used before randomly allocating others. # OPTIONAL def_colors: #118F93, #26387F, #FF0101, #FFFF00 # Small 'watermark' text added to the bottom of timeseries graphs. # Requires RRDtool >= 1.2.12. # OPTIONAL watermark: created with CAIDA's CoralReef (c) 2007 UC Regents # Information needed to generate maps, used only by create_graphs. # REQUIRED if maps are being generated, ignored otherwise. # Background image that circles are plotted on. Must be PNG. # An example image would be the one that comes with plot-latlong in the # .mapimages directory, World100.png # REQUIRED # map: World.png # Path to plot-latlong program (available from Caida at # https://www.caida.org/tools/visualization/plot-latlong/). # NB: If any required libraries for plot-latlong (like GD) are not # installed globally and you need to specify the path to a local # installation, try something like: # pll_path: perl -I ~/lib_with_GD ~/bin/plot-latlong # REQUIRED # pll_path: ./bin/plot-latlong # Path to mapinfo file needed by plot-latlong. # OPTIONAL. If not defined, there must be a .mapinfo file in the # current directory or $HOME. # pll_data: ./mapinfo # Plot-latlon defines several maps and coordinate systems for plotting. # These are defined in the mapinfo file and describe how the points are # plotted. (For more information, see the documentation of # plot-latlong) # REQUIRED # pll_type: World # Color used for filling in circles on map. # OPTIONAL, defaults to #000000 (black). # circle_color: #00FF00 # Font size. Can be 'tiny', 'small', 'medium', 'large', or 'giant'. # OPTIONAL, defaults to 'giant' for background images larger than 540 # pixels wide, and 'small' otherwise. # font: giant # Parameter specifying the maximum diameter of drawn circles. # OPTIONAL, defaults to width of background image divided by 20. # max_diam: 40 }