# 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 <N>', such that the top N entries are displayed
    # second field: 'recent', 'area <interval>', '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
}
