tg_config - The ToGather configuration syntax


This document describes the syntax and semantics of a ToGather configuration file. It's syntax is modelled after the configuration file syntax of bind and dhcpd from the Internet Software Consortium ISC.

The file is an ASCII text file. ``Words'' of the configuration are separated by white space (space, tab, newline). A ``word'' consists of anything other than white space (space, newline, tab ...), curly braces ``{}'', a semicolon ``;'' or a has sign ``#''. If a word contains on of these characters it has to be surrounded by 'sinlge' or ``double'' quotes. There is currently no way to include a 'single' quote in a 'single' quoted string or a ``double'' quote in a ``double'' quoted string.

The config consists of a list of options and declarations which can contain other options. Declaration and option names are case insensitive. Values of options are case sensitive.

Options consist of the option name and values, separated by white space. An option is terminated by a semicolon ``;''. Some options don't require a value in which case the default value ``1'' will be used, like in this example:


Some options accept an arbitrary list of values:

  variables ds0 ds1 ds0max ds1max;

Some options accept ``sub options'': E.g.

  legend inbytes "Incoming Bytes per second";
  legend outbytes "Outgoing Bytes per second";

The word after the option name is the ``sub option''. In this example there is a legend for ``inbytes'' and one for ``outbytes''. The ``sub option'' can be ``*'' which serves as a default for every sub option without an explicit setting. Thus

  dstype * counter;

will set every datasource variable to type ``counter'' if there is no explicit ``dstype'' setting for this variable.

Other options can only appear once in a context:

 datasource one {
   host router1;
   host router2;
 datasource two {
   host router3;

The line ``host router2;'' will overwrite the line above it whereas the line ``host router3'' is in another declaration (another context) and does not affect the other host settings. The parser will warn you if you use such an option in a context twice.

If an option expects one string argument (like ``title'', ``legend'') a list of strings will be concatentad with a space (`` '') between them. So the next two lines are equivalent:

 title "An example of a string out of a string list";
 title An example of a string out of a string list;

Declarations consist of the declaration type, a declaration name and a list of options in curly braces ``{}'':

  target router-1-4 {
    host rt-42-1;
    variables inbytes outbytes;
    object inbytes;
    object outbytes;
    port 4;

``group'' declarations can be used to group some declarations together and to give defaults for them:

  group {
    host rt-42-1;
    variables inbytes outbytes;
    target router-1-4 { port 4; }
    target router-1-5 { port 5; }

Groups can be nested. Every option can be given outside of a declaration to give global defaults (e.g. in a group for other declarations, see example above).

If an option is given without values it will get the default value ``1''.

Options that expect a boolean value will accept ``0'', ``no'' and ``false'' as false, ``1'', ``yes'' and ``true'' as true.


author string

Sets the author tag in HTML pages for default pages. [Default: empty]

basedir directory

Defines a base directory for the data files, the graph files and other config files. [Default: empty]

bgcolor colspec

Background color of any default web pages (i.e. pages without a dedicated page or target declaration). Accepts anything a web browser might accept. [Default: white]

debug [parts]

Sets debugging level. ``0'' disables debugging. If parts contains some of the characters ``IPLCES'' this enables the appropriate debugging messages ( ``D'' = high level messages, ``P'' = messages from parser, ``C'' = watch the communication between main daemon and data gathering sub processes, ``S'' = messages from the SNMP query engine, ``E'' = messages from the ``EXEC'' query engine, ``T'' = messages from the task scheduler, [Default: 0]

debugrrdcall [boolean]

Used by tgweb.cgi(1): Instead of displaying the graphs the rrdtool commands to create the graphs are displayed. [Default: 0]

Caution: The rrdtool commands might contain information which should not be shown to everybody.

footer_ad text...

The ToGather web pages contain a default footer which mentions ToGather, rrdtool and the authors of both and hold links to the applications homepages. If you really need to change this you set footer_ad to any text you want.

footer_ad-file file

The same as footer_ad but the text is stored in file file.

include filename

Reads the given file as additional config file. The file is included varbatim, ie. if the include option is inside a ``group'' declaration the defaults set in the group (via some option settings) are used as defaults for the included file. The included file can have its own basedir and other global defaults. Mixing internal defaults and explicit settings for some predefined declarations (eg. the ``daily'' graph) might lead to unpredictable results!

libdir directory...

Defines a directory where some of the needed perl modules are installed. Currently this can only be used for the rrdool perl module '' (and the appropriate shared library). This is only needed if they are not in the default locations. The option can take multiple directories. The value is evaluated right after a config file has been loaded. This option has to be appear at global level, i.e. not inside a ``group'' declaration or a ``include''d file. [Default: empty]

logfacility facility

Defines which syslog facility togatherd will use. See syslog.conf(1) about the possible facilities. If use_syslog is true tgweb.cgi(1) will use this setting too. [Default: daemon]

mailprogram mailer options

declaration: global option

Sets the mailprogram used to send threshold alert mails. [Default: /usr/lib/sendmail -t]

showCGIerrors [boolean]

Used by tgweb.cgi(1): If a graph cannot be created or loaded a picture with an error message is displayed. If showCGIerrors is true the picture will contain a verbose message explaining the error. As default a simple message ``error: cannot create graph'' will be displayed. [Default: 0]

Caution: The verbose message might contain information which should not be shown to everybody.

startpage pagename

Used by tgweb.cgi(1): Defines the page to display as start page (if no page parameter is given to the CGI). Most likly this will be the starting page for your users. [Default: empty]

use_syslog [boolean]

The CGI script tgweb.cgi(1) normally log to stderr which will be captured by the web server and logged to the web servers error log. If use_syslog is true errors will be logged to syslog instead. The syslog facility can be configured with logfacility. [Default: 0]



A datasource defines a source for queries. This can be an SNMP device or an external program. The declaration options define the needed parameters. The queried data will be saved in one rrd file for each datasource declaration. The possible options are:

 type interval maxinterval rrdfile archive datadir
 variables dstype min max
 host community object oid instance port mibs
 snmpversion snmpretries snmptimeout
 command match matchlines ignorelines
 line field separator regex

See below in the alphabetic list of options for their meanings.

You need to give at least port/instance or oid. Defaults are:

  type snmp;
  host "localhost";
  community "public";
  interval 60;
  variables ds0 d1;
  object ds0; # ifInOctets
  object ds1; # ifOutOctets
  dstype * counter;
  archive average,max a:2d 30min:2w 2h:2mon 1d:2y;

A typical setup is to give host, community and port to log the transfer statistics of a device. If you want to log more than two values or want to name them other than ds0 and ds1 you need a variables option and for each variable an object (or oid) option. If you give a mibs option you can use symbolic names instead of numerical OIDs.

A datasource declaration does not define a web page by itself. Use a target declaration to combine any number of variables from any number of datasource declarations for one web page / statistics graphs. As a help for starters and for some common cases a ``virtual'' target can be constructed by ToGather from a datasource declaration with some default settings. See tgweb.cgi(1) for more about (default) web pages.


Defines a web page with information and graphs for one ``target''. A target can represent one datasource or any number of variables from any number of datasource declarations. The possible options are:

 vars calcvars datasource graphvars legend vartype linetype
 color colour colors colours
 top bottom unscaled ylegend short withunits
 bgcolor banner header title descr graphs footer
 banner-file header-file descr-file footer-file
 author graphdir indexgraph

The layout of a target web page is

 - banner (or banner-file)
 - header (or header-file)
 - title
 - descr (or descr-file)
 - statistic graphs as definde with "graphs"
 - footer (or footer-file)
 (- footer_ad) (or footer_ad-file)

``vars'' (and maybe ``datasource'') define which vars from which datasource declarations are used. ``calcvars'' define some variables that are calculated from other ``datasource'' variables. ``graphvars'' select which variables from ``vars'' and ``calcvars'' are used to draw the graph. If ``graphvars'' isn't given all variables from ``vars'' and ``calcvars'' are used. If ``vars'' isn't given all variables from the datasource named with the ``datasource'' option (or from a datasource with the same name as the target) are used.

If a target should be displayed which isn't defined in a declaration but a datasource declaration with the same name exists a default page will be generated for it (see tgweb.cgi(1) for more information).


Defines a web page which can contain a target, links to other page or target web pages (with index graphs for the latter) or arbitrary links to other web pages. The possible options are:

 banner header title pages targets footer
 banner-file header-file footer-file
 author bgcolor columns url page target

This options are used to define the link to the page and (sometimes) the page itself. A page declaration can define an index page which has the follwing layout:

  - banner (or banner-file)
  - header (or header-file)
  - links to pages from option "pages"
  - links to target pages from option "targets"
  - footer (or footer-file)

If one of the options ``page'' or ``target'' is given this page declaration serves as an ``alias'' or ``redirect'': If this page is requested the page or target given with the ``page'' or ``target'' option is shown instead.

If the option ``url'' is given this url is used whenever a link to this page should be shown. This page declaration itself does not define a web page in this case.

Links to targets can contain an indexgraph. The appropriate setting is in the referenced target declaration to allow different indexgraphs for different target links.


Defines datasource independent aspects of a graph. The possible options are:

 size length end withlegends rrdcolor format fileformat title

The information about what variables should be displayed has to be set in the appropriate target declaration.


archive archivetypes range...

declarations: datasource

Defines how much collected data of the variables show be archived for how long. The first argument contains a list of ``average'', ``min'', ``max'', ``last'', meaning that a archive of the mentioned type should be created. The remaining arguments define resolution/period pairs for archives. E.g.

  archive average,max a:2d 30min:2w 2h:2mon 1d:2y

defines an archive with every collected data for the period of two days, one archive with one value for every 30 minutes for two weeks, one archive with values for every two hours for two months and one archive with daily values for two years. [Default: see above]

author string

declarations: page, target, global option

Sets the author tag of a generated HTML page. [Default: empty]

banner string

declarations: page, target, global option

Value is printed at the beginning of the body of the generated HTML page. Useful for a coporate identity header. [Default: empty]

banner-file file

declarations: page, target, global option

The same as banner but the parameter of banner-file is a filename and the content of this file is used as banner.

basedir directory

declarations: global option

Sets a base for other file or directory options. [Default empty]

bgcolor colspec

declarations: page, target, global option

Defines the background color of web pages. [Default: white]

bottom number

declaration: target

Sets a lower limit for the graph. See top and unscaled. [Default: empty]

calcvars cvardef...

declaration: target

Defines calculated variables. The syntax of a cvardef is:

  <variable-name> "=" <rrdtool-cdef>

(may not contain any! spaces). rrdtool-cdef is a CDEF for rrdtool and will be parsed by rrdtool so the syntax check of ToGather cannot find errors in it. See rrdgraph(1) for a description of CDEFs. The defined variables can be used in the graphvar option. [Default: empty]

color variable colspec

declaration: target

Sets the color for a line in a graph. variable names a datasource variable or a calculated variable. colspec is a color definition of the form ``RRGGBB'' where the three two-letter parts define the hexadecimal value color parts red, green, blue respective. This is very similar to the values accepted in HTML (but you cannot use color names). See colors for some examples. [Default: empty, from colors]

This option can be given multiple times with different sub options.

colour ...

An alias for color

colors colspec...

declaration: target

Sets a list of default colors for the graph lines. This list is consulted if the color for a variable is not explicilty defined via the color option of the target declaration. As with color colspec is a RGB triple. The default list contains five colors so if you want to show more than five lines you have to use either color ... or colors to set more colors. Example:

 # colors red  green  blue   white  with-hash
 colors ff0000 00ff00 0000ff 000000 "#ccaa00";

If you write a color in HTML syntax with a leading hash sign '#' you have to quote the string (with `` or ') because '#' outside of quotes begins a comment.

[Default: green blue darkgreen magenta violet]

colours colspec...

An alias for colors

columns number

declaration: page

Normally the index pages show a list of links to other web pages. These links can be shown as table with as many columns as given in this option. [Default is 2]

command string...

declaration: datasource

Sets a command for an external datasource. The option can have multiple values which will be concatenated. See togatherd(1) for an explanation of how to use external datasources. [Default: empty]

community string

declaration: datasource

The SNMP community, a kind of password. [Default: public]

datadir directory

declaration: datasource

Sets the directory where the data files are. If relative basedir will be prepended. This can be used to put some rrd files in a sub directory with a group decalaration and datadir. [Default: empty]

datasource declarationname

declaration: target

(yes, there is a declaration with the same name)

Instead of specifing variables explicitly this defines a datasource to use for a target. All variables of the datasource will be shown in the graph. If a vars option is given too and the variable definitions are given without datasource name, the value of datasouce is used instead. [Default: empty]

debug [string]

declaration: global option

Set debugging level. See above.

debugrrdcall [boolean]

declaration: global option

Displays the graph generation rrdtool calls instead of the graphs themself. Used for debugging. See above.

descr string

declaration: target

A description of the target. Is printed after banner on target web pages. [Default: empty]

descr-file file

declaration: target

The same as descr but the parameter of descr-file is a filename and the content of this file is used as description.

dstype variable type

declaration: datasource

Defines the type of a datasource variable. Can be counter, gauge, absolute or derive (case insensitive). See rrdcreate(1) for a description of these types. [Default: counter]

This option can be given multiple times with different sub options.

end timespec

declaration: graph

The end of the time period a graph should show. timespec is an absolute or relative time/date in the rrdtool time syntax (see rrdfetch(1)). Can be used to show eg. ``yesterday'' graphs (``end -24h'', ``length 24h''). [Default: 'now']

field variable number

declaration: datasource

In match mode fields this defines for a variable which field of the external programs output contains its value. If no field option is given for a variable its position in the list of variables in the datasouce declaration (option variables) is used instead (first listed variable has number 1). [Default: variables position]

This option can be given multiple times with different sub options.

format GIF|PNG

declarations: target

Sets the file format of the graphs. Can be either GIF or PNG (i.e. any format rrdtool accepts). [Default: PNG]

fileformat GIF|PNG

An alias for format.

footer string

declarations: page, target

The string is printed at the end of the web page. [Default: empty]

footer-file file

declarations: page, target

The same as footer but the parameter of footer-file is a filename and the content of this file is used as footer.

graphdir directory

declaration: graph

The graphs will be created in the given directory. It should be accessible by the web server. If the directory is relative basedir is prepended. [Default: empty]

graphs graphdeclaration...

declaration: target

Lists the graphs which should be displayed in a target web page. [Default: daily weekly monthly yearly]

graphvars variable...

declaration: target

The variables which should be drawn in the graph. Can be omitted if all variables defined for this target should be drawn. Can be used to reorder the variables. [Default: all vars defined with 'var']

header string

declarations: target, page

Printed after banner. Useful for headers for some pages. Use banner to define a header for all pages. [Default: ``<H1>title</H1>``]

header-file file

declarations: page, target

The same as header but the parameter of header-file is a filename and the content of this file is used as header.

host hostname

declaration: datasource

Defines the host for a datasource used for SNMP queries. [Required, no default]

ignorelines number...

declaration: datasource

List of line numbers. These lines of the externals programs output will be ignored when extracting the data from the output. Ignored if matchlines is set. [Default: empty]

include configfile

declaration: global option

Include another config file. See above.

indexgraph graphdeclarationname

declaration: target

The name of a graph declaration. This graph will be shown in the page as a index graph. If the value is false (``0'' or ``false'') no index graph will be shown. You might want to make the graph smaller and without legends (see withlegends). [Default: daily.s]

instance variable def...

declaration: datasource

Usually this is the interface number which should be queried. In fact this is the instance number of an SNMP object. The instance must be in dotted numerical format (simple case: just a number), it cannot be a SNMP object name. The instance will be appended to object.

instance has two possible formats:

  instance var1 5;

This sets the instance of var1 to 5 (which could be an interface number).

The second format is:

  instance var2 where ipAdEntIfIndex;
  'instance' varname 'where' SNMP-table-object object-value

This sets the instance to the index of the object of the table ipAddrTable (the table where 'ipAdEntIfIndex', i.e. the given SNMP-table-object is in) which has the value '' ('object-value'). In the example the instance would be the interface number of the interface with the IP address ''.

In other words: The given object-value is searched in the SNMP table ``row'' SNMP-table-object. The instance of the value in this table is used as instance for the variable varname.

This option can be given multiple times with different sub options.

interval number

declaration: datasource

How often a datasource should be queried. Unit is seconds. [Default: 60]

legend variable string

declaration: target

Defines the legend for a variable. [Default: variable name]

This option can be given multiple times with different sub options.

length timespec

declaration: graph

Defines the length of the displayed time period of a graph. See the section below about the TIME SYNTAX. The position in time of the graph (the actual start and end times) is set with end which sets the end time (the start time is calculated as length - end). Typically end is set to ``now'' (for the current time) or probarly ``-24h'' (24 hours before now).

libdir directory...

declaration: global option

A list of directories which contain perl modules. See above.

line variable number

declaration: datasource

In match mode lines this defines for a variable which line of the external programs output contains its value. If no line option is given for a variable its position in the list of variables in the datasouce declaration (option variables) is used instead (first listed variable has number 1). [Default: variables position]

This option can be given multiple times with different sub options.

linetype variable LINE1|LINE2|LINE3|AREA|STACK

declaration: target

A ``line'' in a graph can be drawn in different ways: As a line of different thickness or as an ``area'', ie. the room under the line is filled.

Optionally data can be stacked on top of each other. Stacked data will inherit the line type from the 'bottom' variable. Linetype STACK cannot be used for the first variable in the variables option. Possible line types are LINE1, LINE2, LINE3, AREA and the magic STACK. [Default: LINE1]

This option can be given multiple times with different sub options.

logfacility facility

declaration: global option

The syslog facility that should be used. See above.

mailprogram mailer options

declaration: global option

Sets the mailprogram used to send threshold alert mails. [Default: /usr/lib/sendmail -t]

match mode

declaration: datasource

The match mode for datasource type ``exec''. Can be REGEX, LINES, FIELDS. [No default]

matchlines number...

declaration: datasource

List of line numbers. The match code will only look at these lines of the external programs output for the data. If this option is ommitted every line is matched and ignorelines is consulted, else ignorelines is ignored. [Default: all]

max variable number

declaration: datasource

The maximal value a variable can have. Use it to have rrdtool(1) detect counter overflows and device resets (if you get ``spikes'' in your graph you probably want to set this option). [Default: empty]

This option can be given multiple times with different sub options.

maxinterval variable timespec

declaration: datasource

The maximal time between successive queries of a variable of a datasource. If the time between two successive updates is bigger the value unknown will be inserted into the data log. Normally you shouldn't need to change this value. [Default: 2 * interval]

This option can be given multiple times with different sub options.

mibs mibmodule...

declaration: datasource

A list of MIB modules. If the oid for a variable is given with its name (instead of its identifier in dotted numerical form) the name is looked up in these MIB modules. [Default: empty]

min variable timespec

declaration: datasource

The minimal value a variable can have. Use it to have rrdtool(1) to detect counter overflows and device resets. [Default: empty]

This option can be given multiple times with different sub options.

object variable objectidentifier

declaration: datasource

Sets the SNMP object identifier (OID) for a variable. If the options port or instance are given they are appended (instance overrides port). If the mibbase is installed this can be a name of a SNMP object. [Default: none]

This option can be given multiple times with different sub options.

oid variable objectidentifier

An alias for object.

page pagedeclarationname

declaration: page

(yes, there is a declaration with the same name)

With this option a page can be an alias for another page with a different title.

pages pagedeclarationname...

declaration: page

The page will contain links to these pages. The links will point to a ToGather web page or to url and the text of the link is set with title.

port string

declaration: datasource

port portnum

declaration: datasource

The port or interface number of an SNMP variable. This option is ignored for all variables for which an instance option is given. portnum can be only a single number and not a complete SNMP instance number. Use instance instead. port affects all variables (without a instance option). [Default: empty]

regex string

declarations: datasource

Used for match mode ``regex''. Holds the regular expression which will be matched against the external programs output (after applying matchlines and ignorelines). Will be used in the perl expression

  @update_values = ($output =~ m/$regex/sg)

This expression should produce the needed number of values. See perlre(1) for the syntax of regular expressions. [No default]

rrdcolor part colspec

declarations: graph

Sets the colors of the parts of a graph. part can be one of


(see rrdgraph(1) for their meanings). colspec is a color definition of the form ``RRGGBB'' where the three two-letter parts define the hexadecimal value color parts red, green, blue respective. [Default: rrdtools defaults]

This option can be given multiple times with different sub options.

rrdfile file

declarations: datasource

Normally the rrd file name is build from the datasource name and the options basedir and datadir. With this option a different rrd file name can be given. If it's a relative file name the directory options (basedir/datadir) are applied. [Default: empty]

separator string

declarations: datasource

Used for match mode fields. Defines the separator for the external programs output. Can be a single character or any string.

The value is used in the perl expression

 split($separator, $prog_output)

so it can be anything ``split'' accepts. [Default: ``\s+'']

short string

An alias for ylegend.

showCGIerrors [boolean]

declaration: global option

Sets wether errors when creating the graph should be just mentioned or be displayed with full error message. See above. [Default: 0]

size xsize ysize

declarations: graph

Defines the size of a graph. The generated picture will be slightly bigger as the legends are added to this size. [Default: 400 120]


declarations: datasource

SNMP uses an unreliable transmission protocol. If a network packet is dropped on its way and doesn't reach the SNMP device this isn't reported. So there is no perfect way to detect a not working device. After sending an SNMP request ToGather waits some time for the answer (see snmptimeout). If no response is received ToGather resends the request. snmpretries set how often this is done. A ``0'' disables retries completly. If your network is really unreliable you might want to increase this value. [Default: 1]


declarations: datasource

Before retransmitting a query or declaring a device unreachable the daemon waits the specified time. Can be a floating point number. Default is 5 seconds which might be too high for a good network. [Default: 5]


ToGather can use SNMP version 1 or 2. Only some devices talk SNMP version 2 so 1 might be the better choice. [Default: 1]

declarations: datasource

startpage pagedeclarationname

declarations: page

Defines the startpage for a configuration file. If tgweb.cgi(1) is called without CGI parameters it will show this page. If ommitted a list of defined pages is shown or if there is only one page defined this page is shown. [Default: empty]


declaration: page

(yes, there is a declaration with the same name)

With this option a page can be an alias for a target page with a different title.

targets targetdeclarationname...

declaration: page

Defines for a web page which targets should be shown with a link. The target option indexgraph defines wether the target should be shown with an index graph.

threshold variable args

declaration: datasource

Define threshold checking. Takes one variable name and several key/value pairs. The possible settings (keys) are:

 over value      an alert is raised if the measured value is
                 over the given 'value'
 under value     an alert is raised if the measured value is
                 under the given 'value'
 repeat count    an alert is raised if the limit is exceeded
                 'count' times in a row
 duration sec    an alert is raised if the limit is exceeded
                 for 'sec' seconds continously
 quiettime sec   the minimal time between an "ok alert" and the
                 following "failure alert" (default is 24 hours)

At least one of 'over' or 'under' must be given. An alert is raised if a limit is exceeded 'repeat' times or 'duration' seconds (a failure alert is sent only if configured with thresh_action). If the measured value is inside the limits again an 'ok' alert is raised (if configured with thresh_okaction) if a corresponding failure alert was raised before.

After an 'ok alert' was raised a failure alert isn't raised for the next 'quiettime' seconds. The reason is that if a device exceeds its limits it might be inside and outside the limits at every other measurement cycle. Without 'quiettime' you would get a message upto every 'interval' seconds. With 'quiettime' failure alerts are suppressed for 'quiettime' seconds after an 'ok alert' was raised. If the values still exceed the limits at the next measurement a failure alert will be raised.

A failure message will tell you if there have been threshold violations in the 'quiettime' period and how often.

'Raising an alert' means to send a mail or to call an external program, depending on the setting of thresh_action or thresh_okaction.

See tg_threshold(1) for an example.

thresh_action variable mail-or-prog params
thresh_okaction variable mail-or-prog params

declaration: datasource

Set the actions for the threshold checks. The action defined with thresh_action will be executed if limits are exceeded, the action defined with thresh_okaction will be executed if measured values are inside the limits again (after exceeding them).

The first parameter selects a variable. This can be '*' to set the action for all checked variables.

The second parameter is either ``mail'' or ``prog'': ``mail'' will cause an alert mail send to the specified address. The program used to send the mails is set with the global option mailprogram.

``prog'' specifies an external program (with arguments). This program will called with the additional arguments

 datasource-name variable-name limit currentvalue

where ``limit'' is the upper or lower bound (configured with ``over'' or ``under'') that was exceeded and ``currentvalue'' is the measured value.

The action programs will get the environment variables ``TOGATHER'' (with the ToGather version), ``TOGATHER_CFG'' with the name of the config file and if the datasource declaration with this threshold check is from an included config file ``INCLUDE_CFG'' will be set to the name of the included config file. Additional arbitrary environment variables can be set with threshprogenv.

See tg_threshold(1) for an example.

threshprogenv variable var=value ...

Sets some environment variables for a threshold action program. The first param is a datasource variable name (or '*' of course). The remaining params are environment variables of the form ``name=value''.

See tg_threshold(1) for an example.

title string

declarations: page, target, graph

The title of a web page or a graph. Used as web page title and as text for links. [Default: target/page/graph name]

top number

declaration: target

The upper bound of a graph. The top of the graph will be at least number. As long as unscaled isn't set the top of the graph might be higher if the shown values are bigger. [Default: empty]

type snmp|exec

declaration: datasource

The type of a datasource. Can be snmp for an SNMP datasource and exec for an external programs datasource. [Default: snmp]

unscaled [boolean]

declaration: target

If defined the graphs for this target will be displayed unscaled. If unset the graph will be scaled so the biggest value is shown at top of the graph and the lowest value is at bottom. Options top and bottom can be used to adjust the graph. If unscaled/top/bottom are used all, the graph will have exactly the upper/lower bounds top/bottom. [Default: 0]

url string

declaration: page

If a page contains a link to another page via the pages option and the referenced page has the url option this url is used for the link (instead a link to a ToGather web page).

use_syslog [boolean]

declaration: global option

Redirect the error output of tgweb.cgi(1) to syslog. See above. [Default: 0]

variables varname...

declaration: datasource

Defines the variable names for the datasource. [Default: ds0 ds1]

vars vardef...

declaration: target

Defines which of the protocolled variables (datasources) should be used for a targets graph. A vardef has the format


name can be any string and defines a new (target) variable. datasource is the name of a datasource declaration and can be ommited if the datasource option is given or a datasource declaration with the same name as this target declaration exists. dsvar is a variable present in this datasource. cf is a consolidation function and defines the archive used. It can be ``MAX'', ``MIN'', ``AVERAGE'' or ``LAST''. Default cf is ``AVERAGE''. If no archive option is given only the archives ``AVERAGE'' and ``MAX'' are available, else the ones set in the archive option. [Default: from option variables]

vartype variable variable-type

declaration: target

Defines wether this variable should be displayed in the legends as integer or floating point number. The value ``float'' means floating point, ``int'' or ``integer'' is integer. See withunits too. [Default: float]

withlegends [boolean]

declaration: graph

If set graphs will contain legends explaning the lines and containing maximal, minimal and average values of the shown variables. [Default: 1]

withunits [boolean]

declaration: target

If set the maximal/minimal/average values in the graph legends will be shown with SI units appended, i.e. 100000 becomes 100k, 0.001 becomes 1m. See vartype too. [Default: 1]

ylegend string

declaration: target

Defines a short description of a target. Displayed in the graph as vertical label. [Default: empty]


ToGather uses its own format to define time intervals. In the somplest form this is just a number of seconds. Additionally years, months, weeks, days, houres and minutes can be given. The suffixes y mon w d h min s specify the ``unit'' of a value. E.g. ``2w3d'' is two weeks, 3 days - approximatly half a month. The value-unit pairs have to be given in the right order and without intervening space. The unit ``m'' is treated as month or minute depending on the context. Use ``mon'' and ``min'' to avoid problems (``5m'' is ambiguous so type ``5min'' or ``5mon'').

  "1s" or just "1" is one second
  "1min" is one minute = 60s
  "1h" is one hour = 60min = 3600s
  "1d" is one day = 24h = 1440min = 86400s
  "1w" is seven days = 168h = 10080min = 604800s
  "1mon" is one month = 30d = 4w2d = 720h = 43200min = 2592000s
  "1y" is one year = 365d = 12m5d = 52w1d = 8760h = 525600min = 31536000s


ToGather stores the configuration in a DBM file to speed up further accesses. It tries to use the best DBM implementation available. Sometimes the available DBM implementation has a size restriction of 1024 bytes per entry. This can be a problem for the ``text'' settings ``banner'', ``header'', ``descr'', ``footer''. togatherd(1) will tell if the value of these settings are too big for the used DBM implementation. In this case you can either install a better DBM implementation (eg. Berkeley DB or Gnu DBM, don't forget the perl modules) or store the texts that are too big in separate files and use the appropriate ``..-file'' settings, ie. ``banner-file'' for ``banner, ''header-file`` for ''header`` etc.


togather(1), togatherd(1), tgweb.cgi(1), tg_threshold(1).


 Rainer Bawidamann,
 University of Ulm, University Computer Centre


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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA