SMOKEPING_CONFIG(1)         SmokePing         SMOKEPING_CONFIG(1)



OVERVIEW
       SmokePing takes its configuration from a single central
       configuration file.  Its location must be hardcoded in the
       smokeping script and smokeping.cgi.

       The contents of this manual is generated directly from the
       configuration file parser.

       The Parser for the Configuration file is written using
       David Schweikers ParseConfig module. Read all about it in
       the ISG::ParseConfig manpage.

       The Configuration file has a tree-like structure with sec-
       tion headings at various levels. It also contains variable
       assignements and tables.

REFERENCE
       The text below describes the syntax of the SmokePing con-
       figuration file.

       *** General *** (mandatory section)

       General configuration values valid for the whole SmokePing
       setup.

       The following variables can be set in this section:

       owner (mandatory setting)
           Name of the person responsible for this smokeping
           installation.

       imgcache (mandatory setting)
           A directory which is visible on your webserver where
           SmokePing can cache graphs.

       imgurl (mandatory setting)
           Either an absolute URL to the imgcache directory or
           one relative to the directory where you keep the
           SmokePing cgi.

       datadir (mandatory setting)
           The directory where SmokePing can keep its rrd files.

       piddir (mandatory setting)
           The directory where SmokePing keeps its pid when
           demonised.

       sendmail
           Path to your sendmail binary. It will be used for
           sending mails in connection with the support of
           DYNAMIC addresses.

       smokemail (mandatory setting)
           Path to the mail template for DYNAMIC hosts. This mail
           template must contain keywords of the form <##key-
           word##>. There is a sample template included with
           SmokePing.

       cgiurl (mandatory setting)
           Complete URL path of the SmokePing.cgi



       mailhost
           Instead of using sendmail, you can specify the name of
           an smtp server and use perl's Net::SMTP module to send
           mail to DYNAMIC host owners (see below).

       contact (mandatory setting)
           Mail address of the person responsible for this
           smokeping installation.

       *** Database *** (mandatory section)

       Describes the properties of the round robin database for
       storing the SmokePing data. Note that it is not possible
       to edit existing RRDs by changeing the entries in the cfg
       file.

       The following variables can be set in this section:

       step (mandatory setting)
           Duration of the base operation interval of SmokePing
           in seconds.  SmokePing will venture out every step
           seconds to ping your target hosts.

       pings (mandatory setting)
           How many pings should be sent to each target. Sug-
           gested: 20 pings.

       This section also contains a table describing the setup of
       the SmokePing database. Below are reasonable defaults.
       Only change them if you know rrdtool and its workings.
       Each row in the table describes one RRA.

        # cons   xff steps rows
        AVERAGE  0.5   1   1008
        AVERAGE  0.5  12   4320
            MIN  0.5  12   4320
            MAX  0.5  12   4320
        AVERAGE  0.5 144    720
            MAX  0.5 144    720
            MIN  0.5 144    720


       column 0
           Consolidation method.

       column 1
           What part of the consolidated intervals must be known
           to warrant a known entry.

       column 2
           How many steps to consolidate into for each RRA entry.

       column 3
           How many rows this RRA should have.

       *** Presentation *** (mandatory section)

       Defines how the SmokePing data should be presented.

       The following variables can be set in this section:

       template (mandatory setting)
           The webpage template must contain keywords of the form
           <##keyword##>. There is a sample template included
           with SmokePing; use it as the basis for your
           experiments. Default template contains a pointer to
           the SmokePing counter and homepage. I would be glad if
           you would not remove this as it gives me an indication
           as to how widely used the tool is.

       charset
           By default, SmokePing assumes the 'iso-8859-15' char-
           acter set. If you use something else, this is the
           place to speak up.

       The following sections are valid on level 1:

       +overview (mandatory section)
           The Overview section defines how the Overview graphs
           should look.

           The following variables can be set in this section:

           width (mandatory setting)
               Width of the Overview Graphs.

           height (mandatory setting)
               Height of the Overview Graphs.

           range
               How much time should be depicted in the Overview
               graph. Time must be specified as a number followed
               by a letter which specifies the unit of time.
               Known units are: seconds, minutes, hours, ddays,
               weeks, years.

           max_rtt
               Any roundtrip time larger than this value will
               cropped in the overview graph

           median_color
               By default the median line is drawn in red. Over-
               ride it here with a hex color in the format
               rrggbb.

           strftime
               Use posix strftime to format the timestamp in the
               left hand lower corner of the overview graph

       +detail (mandatory section)
           The following variables can be set in this section:

           width (mandatory setting)
               How many pixels wide should detail graphs be

           height (mandatory setting)
               How many pixels high should detail graphs be

           logarithmic
               should the graphs be shown in a logarithmic scale
               (yes/no)

           unison_tolerance
               if a graph is more than this factor of the median
               'max' it drops out of the unison scaling algo-
               rithm. A factor of two would mean that any graph
               with a max either less than half or more than
               twice the median 'max' will be dropped from unison
               scaling



           max_rtt
               Any roundtrip time larger than this value will
               cropped in the detail graph

           strftime
               Use posix strftime to format the timestamp in the
               left hand lower corner of the detail graph

           The detailed display can contain several graphs of
           different resolution. In this table you can specify
           the resolution of each graph.

           Example:

            "Last 3 Hours"    3h
            "Last 30 Hours"   30h
            "Last 10 Days"    10d
            "Last 400 Days"   400d


           column 0
               Description of the particular resolution.

           column 1
               How much time should be depicted. The format is
               the same as for the age  parameter of the Overview
               section.

           The following sections are valid on level 2:

           ++loss_colors
               In the Detail view, the color of the median line
               depends the amount of lost packets. SmokePing
               comes with a reasonable default setting, but you
               may choose to disagree. The table below lets you
               specify your own coloring.

               Example:

                Loss Color   Legend
                1    00ff00    "<1"
                3    0000ff    "<3"
                1000 ff0000    ">=3"


               column 0
                   Activate when the lossrate is larger of equal
                   to this number

               column 1
                   Color for this range.

               column 2
                   Description for this range.

           ++uptime_colors
               When monitoring a host with DYNAMIC addressing,
               SmokePing will keep track of how long the machine
               is able to keep the same IP address. This time is
               plotted as a color in the graphs background.
               SmokePing comes with a reasonable default setting,
               but you may choose to disagree. The table below
               lets you specify your own coloring

               Example:

                Uptime Color     Legend
                3600    00ff00   "<1h"
                86400   0000ff   "<1d"
                604800  ff0000   "<1w"
                1000000000000 ffff00   ">1w"

               Uptime is in days!

               column 0
                   Activate when uptime in days is larger of
                   equal to this number

               column 1
                   Color for this uptime range range.

               column 2
                   Description for this range.

       *** Probes *** (mandatory section)

       The Probes Section configures Probe modules. Probe modules
       integrate an external ping command into SmokePing. Check
       the documentation of the Ping module for configuration
       details.

       The following sections are valid on level 1:

       +/[-_0-9a-zA-Z]+/
           Each module can take specific configuration informa-
           tion from this area. The jumble of letters above is a
           regular expression defining legal module names.

           The following variables can be set in this section:

           /[-_0-9a-zA-Z]+/
               Each module defines which variables it wants to
               accept. So this expression here just defines legal
               variable names.

       *** Targets *** (mandatory section)

       The Target Section defines the actual work of SmokePing.
       It contains a hierarchical list of hosts which mark the
       endpoints of the network connections the system should
       monitor.  Each section can contain one host as well as
       other sections.

       The following variables can be set in this section:

       probe (mandatory setting)
           The name of the probe module to be used for this host.
           The value of this variable gets propagated

       menu (mandatory setting)
           Menu entry for this section

       title (mandatory setting)
           Title of the page when it is displayed.

       remark
           An optional remark on the current section. It gets
           displayed on the webpage.

       The following sections are valid on level 1:


       +PROBE_CONF
           Probe specific variables.

           The following variables can be set in this section:

           /[-_0-9a-zA-Z]+/
               Should be found in the documentation of the corre-
               sponding probe. The values get propagated. If a
               child node uses the same Probe as the parent.

       +/[-_0-9a-zA-Z]+/
           Each target section can contain information about a
           host to monitor as well as further target sections.
           Most variables have already been described above. The
           expression above defines legal names for target sec-
           tions.

           The following variables can be set in this section:

           probe
           menu (mandatory setting)
           title (mandatory setting)
           note
               Some information about this entry which does NOT
               get displayed on the web.

           email
               This is the contact address for the owner of the
               current host. In connection with the DYNAMIC
               hosts, the address will be used for sending the
               belowmentioned script.

           host
               Can either contain the name of a target host or
               the string DYNAMIC.

               In the second case, the target machine has a
               dynamic IP address and thus is required to regu-
               larly contact the SmokePing server to verify its
               IP address.  When starting SmokePing with the com-
               mandline argument --email it will add a secret
               password to each of the DYNAMIC host lines and
               send a script to the owner of each host. This
               script must be started regularly on the host in
               question to make sure SmokePing monitors the right
               box. If the target machine supports SNMP SmokePing
               will also query the hosts sysContact, sysName and
               sysLocation properties to make sure it is still
               the same host.

           remark

           The following sections are valid on level 2:

           ++PROBE_CONF
               Probe specific variables.

               The following variables can be set in this sec-
               tion:

               /[-_0-9a-zA-Z]+/
                   Should be found in the documentation of the
                   corresponding probe. The values get propa-
                   gated. If a child node uses the same Probe as
                   the parent.

           ++/[-_0-9a-zA-Z]+/
               Each target section can contain information about
               a host to monitor as well as further target sec-
               tions. Most variables have already been described
               above. The expression above defines legal names
               for target sections.

COPYRIGHT
       Copyright (c) 2001 by Tobias Oetiker. All right reserved.

LICENSE
       This program is free software; you can redistribute it
       and/or modify it under the terms of the GNU General Public
       License as published by the Free Software Foundation;
       either version 2 of the License, or (at your option) any
       later version.

       This program is distributed in the hope that it will be
       useful, but WITHOUT ANY WARRANTY; without even the implied
       warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU General Public License for more
       details.

       You should have received a copy of the GNU General Public
       License along with this program; if not, write to the Free
       Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
       02139, USA.

AUTHOR
       Tobias Oetiker <tobi@oetiker.ch>



2002-04-24                     1.8            SMOKEPING_CONFIG(1)
