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:
withlegends;
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 1.3.6.1.2.1.2.2.1.10;
object outbytes 1.3.6.1.2.1.2.2.1.10;
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.
Sets the author tag in HTML pages for default pages. [Default: empty]
Defines a base directory for the data files, the graph files and other config files. [Default: empty]
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]
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]
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.
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.
The same as footer_ad but the text is stored in file file.
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!
Defines a directory where some of the needed perl modules are installed. Currently this can only be used for the rrdool perl module 'RRDs.pm' (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]
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]
declaration: global option
Sets the mailprogram used to send threshold alert mails. [Default:
/usr/lib/sendmail -t]
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.
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]
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 1.3.6.1.2.1.2.2.1.16; # ifInOctets object ds1 1.3.6.1.2.1.2.2.1.10; # 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.
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]
declarations: page, target, global option
Sets the author tag of a generated HTML page. [Default: empty]
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]
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.
declarations: global option
Sets a base for other file or directory options. [Default empty]
declarations: page, target, global option
Defines the background color of web pages. [Default: white]
declaration: target
Sets a lower limit for the graph. See top and unscaled. [Default: empty]
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]
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.
An alias for color
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]
An alias for colors
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]
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]
declaration: datasource
The SNMP community, a kind of password. [Default: public]
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]
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]
declaration: global option
Set debugging level. See above.
declaration: global option
Displays the graph generation rrdtool calls instead of the graphs themself. Used for debugging. See above.
declaration: target
A description of the target. Is printed after banner on target web pages. [Default: empty]
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.
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.
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']
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.
declarations: target
Sets the file format of the graphs. Can be either GIF or PNG (i.e. any format rrdtool accepts). [Default: PNG]
An alias for format.
declarations: page, target
The string is printed at the end of the web page. [Default: empty]
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.
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]
declaration: target
Lists the graphs which should be displayed in a target web page. [Default: daily weekly monthly yearly]
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']
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>``]
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.
declaration: datasource
Defines the host for a datasource used for SNMP queries. [Required, no default]
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]
declaration: global option
Include another config file. See above.
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]
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 192.168.36.48; '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 '192.168.36.48' ('object-value'). In the example the instance would be the interface number of the interface with the IP address '192.168.36.48'.
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.
declaration: datasource
How often a datasource should be queried. Unit is seconds. [Default: 60]
declaration: target
Defines the legend for a variable. [Default: variable name]
This option can be given multiple times with different sub options.
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).
declaration: global option
A list of directories which contain perl modules. See above.
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.
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.
declaration: global option
The syslog facility that should be used. See above.
declaration: global option
Sets the mailprogram used to send threshold alert mails. [Default:
/usr/lib/sendmail -t]
declaration: datasource
The match mode for datasource type ``exec''. Can be REGEX, LINES,
FIELDS. [No default]
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]
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.
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.
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]
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.
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.
An alias for object.
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.
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.
declaration: datasource
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]
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]
declarations: graph
Sets the colors of the parts of a graph. part can be one of
BACK CANVAS SHADEA SHADEB GRID MGRID FONT FRAME ARROW (case insensitive)
(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.
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]
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+'']
An alias for ylegend.
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]
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
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.
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.
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.
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.
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.
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]
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]
declaration: datasource
The type of a datasource. Can be snmp for an SNMP datasource and exec for an external programs datasource. [Default: snmp]
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]
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).
declaration: global option
Redirect the error output of tgweb.cgi(1) to syslog. See above. [Default: 0]
declaration: datasource
Defines the variable names for the datasource. [Default: ds0 ds1]
declaration: target
Defines which of the protocolled variables (datasources) should be used for
a targets graph. A vardef has the format
name=[datasource]:dsvar[:cf]
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]
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]
declaration: graph
If set graphs will contain legends explaning the lines and containing maximal, minimal and average values of the shown variables. [Default: 1]
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]
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, Rainer.Bawidamann@rz.uni-ulm.de 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