--- /dev/null
+# xmlconfig.pod - Torrus configuration guide
+# Copyright (C) 2002 Stanislav Sinyagin
+#
+# 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.
+
+# $Id: xmlconfig.pod.in,v 1.1 2010-12-27 00:04:34 ivan Exp $
+# Stanislav Sinyagin <ssinyagin@yahoo.com>
+#
+#
+
+=head1 Torrus XML Configuration Guide
+
+=head2 Common rules
+
+The Torrus configuration consists of several XML files.
+Once the XML configuration is changed, it must
+be compiled into the database by executing C<torrus compilexml>.
+In addition, when I<Renderer>, I<Collector> and I<Monitor> processes
+notice the configuration changes, they refresh their information automatically.
+
+The top-level XML element is always C<E<lt>configurationE<gt>>, with
+sub-elements defining various sections, like datasources or views:
+
+ <configuration>
+
+ <!-- Optional inclusion of other XML files -->
+ <include filename="myconfig.xml"/>
+
+ <datasources>
+ <!-- Data sources tree definition -->
+ ...
+ </datasources>
+ <views>
+ <!-- View definitions -->
+ ...
+ </views>
+ <token-sets>
+ <!-- Token sets definitions ->
+ ...
+ </token-sets>
+ <monitors>
+ <!-- Monitor definitions ->
+ ...
+ </monitors>
+ </configuration>
+
+Multiple XML files are interpreted in additive matter, i.e.
+C<E<lt>datasourcesE<gt>> section from one file is concatenated with
+the corresponding sections of previous files. If the same
+parameter is defined for the same subtree in several input files,
+the last processed value gets into the configuration.
+
+Additional XML files may be added to the compilation list by means of
+C<E<lt>includeE<gt>> statement. They will be processed recursively
+before the content of the XML file they are referenced from.
+The argument C<filename> determines the
+name of the file in standard XML files directory.
+It is safe to include the same file several times,
+Torrus compiler guarantees that files are only processed once.
+
+Some kinds of sections, like C<E<lt>datasourcesE<gt>>, allow to
+define the same elements two or more times. In this case,
+the previous parameter values are overridden by the new values.
+
+Each component of the configuration is defined by the set of I<parameters>.
+They are specified in a common manner, differentiating in parameter names only:
+
+ <view name="default-rrd-html">
+ <param name="view-type" value="html" />
+ <param name="expires" value="300" />
+ <param name="html-template" value="default-rrd.html" />
+ </view>
+
+The parameter value can be specified either by C<value> XML attribute,
+or by the text contents of the C<E<lt>paramE<gt>> element.
+
+Some parameter values require other parameters to be defined, like in the
+above example: a view of type C<html> cannot exist without a template.
+
+After I<all> XML files are compiled, the parameters are checked for validity
+by the compiler.
+
+=head2 Character sets
+
+By default, all XML input is treated as UTF-8 (unicode). This is important
+because all the HTML output generated by Torrus is encoded UTF-8.
+
+However, you may use Latin1 (ISO-8859-1) encoding in your XML files.
+In order to ensure correct displaying of non-ASCII characters,
+the encoding must be specified in your XML files:
+
+ <?xml version="1.0" encoding="ISO-8859-1"?>
+
+You need this only in those files containing non-ASCII characters
+in Latin1 encoding.
+
+In addition, version C<1.54_3> or higher of C<XML::LibXML> is required, and
+Torrus version 0.0.16 or above.
+
+
+=head2 Macros
+
+In the top level of the configuration tree, a number of macros may be defined.
+Currently they are used in C<snmp-object> parameter only.
+Macros are specified with C<E<lt>defE<gt>> elements, being the direct
+children of C<E<lt>definitionsE<gt>> element:
+
+ <configuration>
+ <definitions>
+ <!-- IF-MIB:ifTable -->
+ <def name="ifDescr" value="1.3.6.1.2.1.2.2.1.2" />
+ <def name="ifPhysAddress" value="1.3.6.1.2.1.2.2.1.6" />
+ <def name="ifInOctets" value="1.3.6.1.2.1.2.2.1.10" />
+ <def name="ifInUcastPkts" value="1.3.6.1.2.1.2.2.1.11" />
+ <def name="ifInErrors" value="1.3.6.1.2.1.2.2.1.14" />
+ <def name="ifOutOctets" value="1.3.6.1.2.1.2.2.1.16" />
+ <def name="ifOutUcastPkts" value="1.3.6.1.2.1.2.2.1.17" />
+ <def name="ifOutErrors" value="1.3.6.1.2.1.2.2.1.20" />
+
+ <!-- Default Interface index lookup -->
+ <def name="IFIDX" value="M($ifDescr, %interface-name%)" />
+ </definitions>
+ ...
+
+These definitions are global across all XML configuration files,
+and are referenced with dollar sign and the definition name, e.g.:
+
+ <leaf name="ifInErrors">
+ <param name="snmp-object" value="$ifInErrors.$IFIDX" />
+ ...
+
+
+=head2 Parameter properties
+
+Some parameters require special handling during the compilation or
+at the runtime. The parameter properties define such behaviour in the
+XML configuration.
+
+Currently two properties are recognized: "remspace" and "expand".
+
+ <configuration>
+ <param-properties>
+ <!-- Parameters where space is removed from values -->
+ <prop param="action" prop="remspace" value="1"/>
+ <prop param="display-rpn-expr" prop="remspace" value="1"/>
+ <prop param="ds-names" prop="remspace" value="1"/>
+ ...
+ </param-properties>
+
+
+
+=head2 Datasource definitions
+
+Datasources are organized into a tree hierarchy. All parameters are inherited
+by the subtrees and leafs from their parents, and can be overridden on
+lower levels.
+
+The datasources tree consists of two key types of components:
+I<subtree> and I<leaf>. A subtree can have child subtrees or leaves.
+A leaf can never have children. A subtree represents logical aggregation,
+while the leaf always represends the actual datasource.
+
+In XML configuration, a child subtree or leaf belongs to the parent
+element, like the following:
+
+ <datasources>
+ <!-- This is the first child of the tree root -->
+ <subtree name="Netflow">
+ <param name="ds-type" value="rrd-file" />
+ <param name="comment"
+ value="Netfow data collected by FlowScan with CarrierIn.pm" />
+ <!-- All Flowscan-generated files reside here -->
+ <param name="data-dir" value="/var/local/flowscan/graphs" />
+ <subtree name="Exporters">
+ <param name="comment" value="Netflow exporting devices" />
+ ...
+ <!-- all exporters defined here -->
+ </subtree>
+ ...
+ <subtree name="Total">
+ <param name="data-file" value="total.rrd" />
+ <leaf name="bps">
+ <param name="comment" value="Bits per second" />
+ <param name="leaf-type" value="rrd-def" />
+ <param name="rrd-ds" value="bits" />
+ <param name="rrd-cf" value="AVERAGE" />
+ </leaf>
+ <leaf name="pps">
+ <param name="comment" value="Packets per second" />
+ <param name="leaf-type" value="rrd-def" />
+ <param name="rrd-ds" value="pkts" />
+ <param name="rrd-cf" value="AVERAGE" />
+ </leaf>
+ <leaf name="packlen">
+ <param name="comment" value="Average packet length in bytes" />
+ <param name="leaf-type" value="rrd-cdef" />
+ <param name="rpn-expr" value="{bps},8,/,{pps},/" />
+ </leaf>
+ </subtree>
+ </subtree>
+ </datasources>
+
+
+Each subtree or a leaf is identified by a I<path>, the symbolic
+notation similar to filesystem paths. In any path notation,
+subtree names always end with slash (/), and this trailing slash is
+the part of the name. In this case, any subtree is identified by a path
+ending with slash, while leaf paths always end with a word symbol.
+The top-level subtree is identified by a single slash.
+
+The other components of the datasouce definition are I<templates> and
+I<aliases>.
+
+=head3 Templates
+
+A template is used when it's needed to define multiple different pieces of
+the configuration in the same way. For instance, the definition for
+input/output octets and bits can be specified once in a template,
+and then applied where appropriate.
+
+The piece of XML configuration inside the C<E<lt>templateE<gt>>
+element is memorized under the template name, and reproduced
+in every occurrence of C<E<lt>apply-templateE<gt>> with the corresponding
+template name. The template definition must be the direct child
+element of C<E<lt>configurationE<gt>> XML element:
+
+ <datasources>
+ <!-- Default views must be defined -->
+ <param name="default-subtree-view" value="default-dir-html" />
+ <param name="default-leaf-view" value="default-rrd-html" />
+
+ <!-- Many of our RRDs have the field "bits" - let's define it here -->
+ <template name="bps">
+ <leaf name="bps">
+ <param name="comment" value="Bits per second" />
+ <param name="leaf-type" value="rrd-def" />
+ <param name="rrd-ds" value="bits" />
+ <param name="rrd-cf" value="AVERAGE" />
+ </leaf>
+ </template>
+ ...
+ <subtree name="Total">
+ <param name="data-file" value="total.rrd" />
+ <apply-template name="bps" />
+ <leaf name="pps">
+ <param name="comment" value="Packets per second" />
+ <param name="leaf-type" value="rrd-def" />
+ <param name="rrd-ds" value="pkts" />
+ <param name="rrd-cf" value="AVERAGE" />
+ </leaf>
+ <leaf name="packlen">
+ <param name="comment" value="Average packet length in bytes" />
+ <param name="leaf-type" value="rrd-cdef" />
+ <param name="rpn-expr" value="bps,8,/,pps,/" />
+ </leaf>
+ </subtree>
+
+
+=head3 Aliases
+
+Alias is the alternative symbolic name for a subtree or a leaf.
+It can be even a name from a different subtree hierarchy.
+If that alternative hierarchy does not exist, the corresponding
+subtrees are created:
+
+ <subtree name="62.3.44.55">
+ <alias>/Netflow/ExportersByName/rtrTelehouse1/</alias>
+ ...
+
+=head3 Compile-time variables
+
+Compile-time variables are those defined somewhere in datasource hierarchy,
+and valid within a given subtree and its children. It is possible to define
+pieces of XML configuration which are or are not compiled, depending on the
+value of corresponding variable.
+
+Variables are set by C<setvar> XML element, with mandatory attributes
+C<name> and C<value>.
+
+Variable values are used in C<iftrue> and C<iffalse> XML elements.
+Mandatory parameter C<var> specifies the variable name. The child XML elements
+are compiled if the variable value is true or false, correspondingly.
+A true value is C<true> or a nonzero number. Undefined variable is identified
+as false.
+
+Example:
+
+ <template name="cisco-cbqos-classmap-meters">
+ ...
+ <iftrue var="CiscoIOS_cbQoS::CMNoBufDrop">
+ <leaf name="Dropped_No_Buffer">
+ ...
+ </leaf>
+ </iftrue>
+ </template>
+
+ <subtree name="QoS_Stats">
+ <setvar name="CiscoIOS_cbQoS::CMNoBufDrop" value="true"/>
+ ....
+ </subtree>
+
+
+=head3 Parameter value substitution
+
+For any given leaf, some parameters may reference the other parameter values,
+by embracing the parameter name with percent signs:
+
+ <param name="data-file" value="%snmp-host%_hostaverages.rrd" />
+
+The parameter substitution is performed at runtime. The substitution formula
+may be defined at a higher subtree level, and the substitution itself will
+occur at leaf level.
+
+The parameter substitution is performed only to those paraneters
+which are defined with the property "expand".
+
+=head3 Common parameters
+
+=over 4
+
+=item * C<ds-type>
+
+Mandatory parameter for every datasource leaf. Currently, the following values
+are recongized:
+
+=over 8
+
+=item * C<rrd-file>
+
+The datasource is an RRD file generated by some external collector.
+Implies mandatory parameters: C<data-dir>, C<data-file>, C<leaf-type>.
+
+=item * C<collector>
+
+The datasource is generated by Torrus Collector.
+Implies mandatory parameters: C<collector-type>, C<storage-type>,
+C<collector-period>, C<collector-timeoffset>.
+
+=item * C<rrd-multigraph>
+
+This leaf is dedicated to displaying of multiple
+other datasources in one graph. It cannot be referenced for any
+other purpose, because there's no numeric value associated with it.
+
+=back
+
+=item * C<nodeid>
+
+Optional. If defined, it should contain a unique string identifying
+this particular leaf or subtree.
+
+
+=item * C<node-display-name>
+
+Optional. If defined, it overrides the subtree or leaf name for displaying.
+The subtree and leaf names are not allowed to have spaces and special
+characters, and this parameter helps to display strings as they are, such as
+router interface names.
+
+
+=item * C<comment>
+
+Optional. This is a string of text which is displayed when browsing through
+the tree.
+
+=item * C<help-text>
+
+Optional. This parameter is not inherited by child nodes. If defined,
+the user is offered a I<Help> shortcut in the given subtree or view.
+It allows to open a new window with the help text displayed, together with
+the current path. Some simple markup is allowed in the text, in a format
+of Template-Toolkit tool:
+C<[%em('some text')%]> would be displayed in italics, and
+C<[%strong('some text')%]> would be bold.
+
+=item * C<monitor>
+
+Optional. Comma-separated list of monitor names (spaces are allowed) that
+must be run upon periodic runs of monitor module (see I<Monitor definitions>
+section of this manual). Monitor schedule parameters must be defined
+for the monitor to run properly: C<monitor-period> and C<monitor-timeoffset>.
+
+=item * C<monitor-period>, C<monitor-timeoffset>
+
+Mandatory parameters for leaves that have C<monitor> defined.
+They define the monitor schedule for each individual datasource.
+The time for execution is determined by formula:
+
+ time + period - (time mod period) + timeoffset
+
+=item * C<monitor-vars>
+
+Required if one or more monitors requires the variables. In monitor's
+RPN expressions, the variables are referenced as C<#varname>. These
+variables are looked up in the leaf's C<monitor-vars> parameter.
+The syntax of this parameter is semicolon-delimited C<name=value> pairs:
+
+ <param name="monitor-vars" value="min=300000;max=1000000"/>
+
+=item * C<monitor-action-target>
+
+Optional. Specifies a reference to an alternative leaf which will be used
+for the monitor action. For example, you might need to see a multigraph
+leaf in the tokenset instead of one single datasource.
+
+=item * C<precedence>
+
+Optional. Default value: C<0>. When rendering, the subtree listing is
+sorted according to precedence and alphabetic order of names.
+The higher the precedence, the closer to the top of the list
+the child node is displayed.
+
+=item * C<legend>
+
+Optional. If given, produces a short listing at the top of the HTML output,
+with tabulated values. Format: C<Category1:Value1; Category2:Value2...>.
+Spaces around the delimiters are ignored.
+
+Example:
+
+ <subtree name="rtrZurich1">
+ <param name="legend">
+ Location:Zurich;
+ Contact: John Smith;
+ Telephone: 01 9911299
+ </param>
+
+=item * C<graph-title>
+
+A horizontal string at the top of the graph.
+
+=item * C<graph-legend>
+
+Optional. This legend text is printed inside the graph explaining
+the line color.
+
+=item * C<vertical-label>
+
+Optional. Text to print along Y axsis on the graph.
+
+=item * C<graph-lower-limit>, C<graph-upper-limit>
+
+Optional. Fix the upper and lower boundaries of the graph.
+
+=item * C<graph-rigid-boundaries>
+
+Optional. When set to "yes", the graph will not expand if the value is outside
+the lower or upper limit.
+
+=item * C<rrd-scaling-base>
+
+Optional. Valid values are: "1000" and "1024". Default: "1000".
+Determines the base for kilo-, mega-, and giga- scaling factor.
+Normally it should be 1000 for traffic counters, and 1024 for memory
+or storage sizes.
+
+=item * C<graph-logarithmic>
+
+Optional. When set to "yes", the graph is drawn in logarithmic y-axis scale.
+
+=item * C<line-style>, C<line-color>
+
+These optional parameters override the corresponding ones from the view
+definition.
+
+=item * C<default-subtree-view>, C<default-leaf-view>
+
+Mandatory. Determine the default view for a leaf or subtree, correspondingly.
+See I<View definitions> section of this manual.
+
+=item * C<rrgraph-views>
+
+Mandatory. Defines 5 views to display the graphs. Must contain 5
+comma-delimited view names for short-period, daily, weekly, monthly,
+and yearly view.
+
+=item * C<tokenset-member>
+
+Optional. Adds this leaf or this subtree child leaves to the specified
+token sets. Tokenset names are comma-separated, and must be defined in
+C<E<lt>token-setsE<gt>> part of configuration.
+
+=item * C<descriptive-nickname>
+
+Optional. If defined, it is used in tokenset members listing as a member
+identifier, instead of the leaf path.
+
+=item * C<hidden>
+
+Optional. Valid values: C<yes>, C<no>.
+When set to C<yes>, the leaf or subtree is not
+displayed in the subtree listing,
+unless C<SHOWHIDDEN> option is true. When C<SHOWHIDDEN> is enabled,
+the node name and comment are shown in italics.
+
+=item * C<has-overview-shortcuts>, C<overview-shortcuts>,
+C<overview-subleave-name-X>, C<overview-shortcut-text-X>,
+C<overview-shortcut-title-X>, C<overview-page-title-X>,
+C<overview-direct-link-X>, C<overview-direct-link-view-X>
+
+When C<has-overview-shortcuts> is set to C<yes> on a subtree level,
+default HTML templates expect the five parameters to be set.
+C<overview-shortcuts> is a comma-separated list of shortcut names,
+and for each name "X", C<overview-subleave-name-X> defines the
+current subtree's grandchild leaves name which would compose the overview page.
+When C<overview-direct-link-X> is set to C<yes>, the URL under the
+graph will point to the direct child subtree, and
+C<overview-direct-link-view-X> will define the view for that subtree.
+Usually this view would be C<expanded-dir-html>.
+
+=item * C<ignore-lower-limit>, C<ignore-upper-limit>, C<ignore-limits>
+
+Optional. When set to C<yes>, they make the renderer ignore
+C<graph-lower-limit>, C<graph-upper-limit>, or both, accordingly.
+In addition, C<ignore-limits> disables the C<graph-rigid-boundaries>
+parameter.
+
+=item * C<graph-ignore-decorations>
+
+Optional. When set to C<yes>, the view C<decorations> are ignored.
+
+=item * C<graph-disable-gprint>
+
+Optional. When set to C<yes>, the view parameter C<gprint-values> and other
+GPRINT-related parameters are ignored.
+
+=item * C<hrule-legend-I<name>>
+
+Optional. If a horizontal rule with the given name is defined, this parameter
+specifies the legend to be printed.
+
+=item * C<searchable>
+
+Optional. If set to C<yes>, the corresponding subtree or leaf is included
+in the search database.
+
+=back
+
+
+=head3 RRD-related parameters
+
+=over 4
+
+=item * C<data-dir>
+
+Mandatory. Specifies the filesystem directory
+path where the data files are resided.
+
+=item * C<data-file>
+
+Mandatory. Name of the data file.
+
+=item * C<leaf-type>
+
+Mandatory. Determines the type of RRD access. Recognized values are:
+
+=over 8
+
+=item * C<rrd-def>
+
+Corresponds to DEF specification in RRDgraph query. Implies two mandatory
+parameters: C<rrd-ds> and C<rrd-cf>, giving the DS name and consolidation
+function, correspondingly.
+
+=item * C<rrd-ds>
+
+Mandatory when a leaf refers to an RRD file (C<storage-type=rrd> in
+C<collector> leaves or C<leaf-type=rrd-def> in C<rrd-file> leaves). The
+parameter Specifies the RRD datasource name within a file.
+
+=item * C<rrd-ds>
+
+Mandatory when a leaf refers to an RRD file (C<storage-type=rrd> in
+C<collector> leaves or C<leaf-type=rrd-def> in C<rrd-file> leaves). The
+parameter Specifies the RRD datasource name within a file.
+
+=item * C<rrd-cf>
+
+Mandatory under the same conditios as C<rrd-ds>. Defines the default
+consolidation function which is used when retrieving the RRD data.
+
+=item * C<rrd-cdef>
+
+Supported for C<ds-type=rrd-file> only.
+Corresponds to CDEF specification in RRDgraph query. Implies one
+mandatory parameter: C<rpn-expr>, which gives the RPN expression.
+Other leaves' value references are specified in curly braces. These leaves
+can be specified as relative or absolute paths in the configuration tree.
+See I<RPN expressions in Torrus> manual for more details.
+
+=back
+
+=item * C<rrd-hwpredict>
+
+Optional. If equals to C<enabled>, then this RRD datasource
+is expected to have HWPREDICT and all the suite of
+Holt-Winters consolidation functions.
+In case of C<ds-type=collector>, C<rrd-hwpredict=enabled> indicates
+that the RRD file must be created with use of Holt-Winters RRAs.
+
+=item * C<rrd-create-dstype>
+
+Mandatory when C<ds-type=collector> and C<storage-type=rrd>.
+Specifies the datasource type for RRD creation. Valid values are:
+C<GAUGE>, C<COUNTER>, C<DERIVE>, C<ABSOLUTE>.
+
+=item * C<rrd-create-rra>
+
+Mandatory when C<ds-type=collector> and C<storage-type=rrd>.
+Space-separated list of RRA definitions for RRD creation, as they
+are passed to RRD Create command.
+Example:
+
+ <!-- Round-robin arrays to be created, separated by space.
+ In this example, we keep 5-minute details for 2 weeks,
+ 30-minute average and maximum details for 6 weeks,
+ and 1-day aggregated stats for 2 years -->
+ <param name="rrd-create-rra">
+ RRA:AVERAGE:0.5:1:4032
+ RRA:AVERAGE:0.5:6:2016 RRA:MAX:0.5:6:2016
+ RRA:AVERAGE:0.5:288:732 RRA:MAX:0.5:288:732
+ </param>
+
+=item * C<rrd-create-heartbeat>
+
+Mandatory when C<ds-type=collector> and C<storage-type=rrd>.
+Heartbeat parameter as defined in RRD Create manual page.
+
+=item * C<rrd-create-min>, C<rrd-create-max>
+
+Optional minimum and maximum parameters for RRD datasource.
+
+=item * C<rrd-create-hw-rralen>
+
+Mandatory when C<ds-type=collector> and C<storage-type=rrd>
+and C<rrd-hwpredict=enabled>. Specifies the RRA length for
+Holt-Winters archives. Recommended same length as main 5-minutes RRA.
+
+=item * C<rrd-create-hw-season>, C<rrd-create-hw-alpha>,
+ C<rrd-create-hw-beta>, C<rrd-create-hw-gamma>,
+ C<rrd-create-hw-winlen>, C<rrd-create-hw-failth>
+
+Optional Holt-Winters parameters. Default values are:
+
+ season=288
+ alpha=0.1, beta=0.0035, gamma=0.1,
+ window_length=9, failure_threshold=6
+
+=back
+
+=head3 Collector-related parameters
+
+=over 4
+
+=item * C<collector-type>
+
+Mandatory parameter for datasource type C<collector>. Currently supported
+values are: C<snmp> and C<cdef>. Other valid values may be added with plugins.
+
+=item * C<storage-type>
+
+Mandatory parameter for datasource type C<collector>. Comma-separated list
+of storage types. The collected value is duplicated on every storage listed.
+Supported values are: C<rrd>, C<ext>. For C<ext> (external storage),
+see the I<Reporting Setup Guide>.
+
+=item * C<collector-period>, C<collector-timeoffset>
+
+Mandatory parameters for datasource type C<collector>.
+They define the collector schedule for each individual datasource.
+The time for execution is determined by formula:
+
+ time + period - (time mod period) + timeoffset
+
+=item * C<collector-dispersed-timeoffset>
+
+Optional. When set to C<yes>, C<compilexml> spreads the collector offsets
+among values determined from C<collector-timeoffset-min>,
+C<collector-timeoffset-max>, C<collector-timeoffset-step>,
+and C<collector-timeoffset-hashstring>.
+
+=item * C<collector-timeoffset-min>,
+C<collector-timeoffset-max>, C<collector-timeoffset-step>
+
+Mandatory when C<collector-dispersed-timeoffset> is set to C<yes>.
+They define the limits and the step for collector timeoffset dispersion.
+
+=item * C<collector-timeoffset-hashstring>
+
+Mandatory when C<collector-dispersed-timeoffset> is set to C<yes>.
+Defines the string that is used as a hash for timeoffset dispersion.
+
+=item * C<collector-instance-hashstring>
+
+Mandatory.
+Defines the string that is used as a hash to calculate the collector
+instance number for a particular leaf.
+By default it is defined as C<%system-id%>, so that
+the same collector instance deals with every remote system.
+
+=item * C<collector-instance>
+
+Mandatiry. The parameter defines the collector instance number.
+This parameter is automatically calculated by the configuration compiler.
+
+=item * C<transform-value>
+
+Optional. Defines a piece of Perl code that will be used for value
+transformation. The keyword C<DOLLAR> is replaced with the dollar sign ($),
+and C<MOD> is replaced with the percent sign (%).
+The initial value is supplied in C<$_>, which should be referenced as
+C<DOLLAR_> in your Perl code.
+The code should return a numeric value or C<U> for an undefined
+value. The returned value is then passed to the storage.
+The parameter substititions are performed on the value of the
+parameter, therefore it should not contain the percent(%) and dollar ($) signs.
+
+=item * C<value-map>
+
+Optional. Collector may return values which need translation into
+numbers. This parameter defines the mapping for such values. The
+parameter value is a comma-separated list of C<value:number> pairs.
+
+
+=item * C<collector-scale>
+
+Optional. Specifies the translation RPN formula for the data before
+being passed to RRD database. Implicitly the datasource value is appended
+to the left of the given RPN. I<Warning:> the translation works I<before>
+the RRDtool processes the data, so it makes sence to scale only non-COUNTER
+values.
+
+=item * C<snmp-ipversion>
+
+Mandatory for C<collector-type=snmp>. Valid values are C<4> and C<6>. The
+parameter defines the IP protocol version. If C<snmp-host> contains a DNS
+name, the IP address is determined by looking up A or AAAA DNS records,
+according to IP version.
+
+=item * C<snmp-transport>
+
+Mandatory for C<collector-type=snmp>. Valid values are C<tcp> and C<udp>.
+
+
+=item * C<snmp-host>
+
+Mandatory when C<collector-type=snmp>. Specifies the hostname or IP address
+of the SNMP agent.
+
+=item * C<snmp-port>
+
+Mandatory when C<collector-type=snmp>. Specifies the UDP port of the
+SNMP agent.
+
+=item * C<domain-name>
+
+Optional DNS domain name. If given, and if C<snmp-host> does not contain
+dot symbol (.), this domain name is appended to C<snmp-host>.
+
+=item * C<snmp-localaddr> and C<snmp-localport>
+
+Optional parameters specifying the local socket binding address and port.
+
+=item * C<snmp-version>
+
+Mandatory when C<collector-type=snmp>. Specifies the SNMP version for the
+given device. Valid values are: C<1>, C<2c>, C<3>.
+
+=item * C<snmp-community>
+
+Mandatory when C<collector-type=snmp> and SNMP version is
+C<1> or C<2c>. Specifies the SNMP community for the given device.
+
+=item * C<snmp-username>
+
+Mandatory when C<collector-type=snmp> and SNMP version is C<3>.
+
+=item * C<snmp-authkey>
+
+Optional authentication key for SNMPv3. If not defined, the authentication
+level is set to C<noAuthNoPriv>. If only C<snmp-authkey> or
+C<snmp-authpassword> are specified, the security level is set to
+C<authNoPriv>. The security level is set to C<authPriv> if either
+of C<snmp-privkey> or C<snmp-privpassword> is defined.
+
+=item * C<snmp-authpassword>
+
+Optional authentication password for SNMPv3. See notes for C<snmp-authkey>
+parameter.
+
+=item * C<snmp-authprotocol>
+
+Optional authentication protocol for SNMPv3. Valid values: C<md5> or C<sha>.
+Default is C<md5>.
+
+=item * C<snmp-privkey>
+
+Optional privacy key for SNMPv3. If defined, C<snmp-authkey> or
+C<snmp-authpassword> must be defined too.
+
+=item * C<snmp-privpassword>
+
+Optional privacy password for SNMPv3. If defined, C<snmp-authkey> or
+C<snmp-authpassword> must be defined too.
+
+=item * C<snmp-privprotocol>
+
+Optional privacy protocol for SNMPv3. Valid values: C<des>, C<aes128cfb>,
+or C<3desede>. Default is C<des>.
+
+=item * C<snmp-timeout>
+
+Mandatory when C<collector-type=snmp>. Specifies the SNMP session timeout
+in seconds.
+
+=item * C<snmp-retries>
+
+Mandatory when C<collector-type=snmp>. Specifies the SNMP session retry count.
+
+=item * C<snmp-oids-per-pdu>
+
+Mandatory when C<collector-type=snmp>. Specifies the number of SNMP OIDs per
+one UDP packet.
+
+=item * C<snmp-object>
+
+Mandatory when C<collector-type=snmp>. Specifies the SNMP OID to be polled
+from the agent. The object must return a single numeric value.
+
+In order to reference the dynamic instances, i.e. interface counters,
+two mapping types are supported: reverse mapping and variable value
+substitution.
+
+Reverse mapping has syntax as follows:
+
+ M(baseoid, string)
+
+The result of reverse mapping is the tail of the OID which has the head
+C<baseoid> and whose value equals the string.
+
+Variable value substitution is defined by syntax:
+
+ V(oid)
+
+The returned value must be a numeric value which is substituted in place
+of this expression.
+
+=item * C<snmp-object-type>
+
+Optional. Supported values: C<COUNTER64>, C<OTHER>. When set to C<COUNTER64>,
+the SNMP variable value is treated as 64-bit integer. Not using this
+parameter may lead to loss of precision.
+
+=item * C<snmp-check-sysuptime>
+
+Optional. Default value: C<yes>. When set to C<no>, the collector does not
+query C<SNMPv2-MIB::sysUpTime> (C<1.3.6.1.2.1.1.3.0>). By default,
+the uptime counter is used to detect if the agent was rebooted between
+the collector cycles. In this case the dynamic maps for the given host
+are automatically rebuilt. This parameter is needed for compatibility
+with some non-standard agents which don't implement this OID.
+
+=item * C<snmp-max-msg-size>
+
+Optional. If defined, it sets the SNMP maximum message size different from
+default 1472 octets (true for UDP/IPv4, see Net::SNMP documentation for more
+information).
+
+=item * C<snmp-ignore-mib-errors>
+
+Optional. If set to C<yes>, the SNMP errors C<noSuchObject>, C<noSuchInstance>,
+C<endOfMibView> are ignored, and no action is performed when such errors
+occur.
+
+=item * C<system-id>
+
+Mandatory for every collector type.
+Default value for SNMP collector: C<%snmp-host%>.
+Unique identifier of the host.
+This parameter is used in various template definitions for
+C<data-file>, C<descriptive-nickname> and C<collector-timeoffset-hashstring>.
+
+=item * C<rpn-expr>
+
+Mandatory when C<collector-type=cdef>. The RPN defines an arithmetic expression
+that is used to create a new datasource from several other ones. For example,
+it may define the sum of traffic on several different interfaces.
+
+=item * C<cdef-collector-delay>
+
+Mandatory when C<collector-type=cdef>. Defines the delay time in collector
+periods. The collector will read the data from the RPN datasources with the
+specified delay from the current time. F<cdef-collector-defs.xml> sets
+the default value to 0.
+
+=item * C<cdef-collector-tolerance>
+
+Mandatory when C<collector-type=cdef>. Delay time in collector periods that
+the collector accepts when no recent data is available.
+F<cdef-collector-defs.xml> sets the default value to 2.
+
+=back
+
+
+=head3 RRD-Multigraph leaves
+
+The leaves with C<ds-type=rrd-multigraph> are dedicated for
+displaying of several datasource values in one graph.
+Such leaves cannot be referenced for a numerical value, hence
+cannot be monitored.
+
+Example:
+
+ <subtree name="SampleMulti">
+ <leaf name="sample1">
+ <param name="ds-type" value="rrd-multigraph" />
+ <param name="ds-names" value="in,out" />
+ <param name="foobarpath"
+ value="/SNMP/Routers/213.230.38.4/FastEthernet0_0" />
+
+ <!-- parameter name tail is formed by the DS name -->
+
+ <param name="ds-expr-in" value="{%foobarpath%/locIfInBitsSec}" />
+ <param name="graph-legend-in" value="Bits per second in" />
+ <param name="line-style-in" value="AREA" />
+ <param name="line-color-in" value="#00FF00" />
+ <param name="line-order-in" value="1" />
+
+ <param name="ds-expr-out" value="{%foobarpath%/locIfOutBitsSec}" />
+ <param name="graph-legend-out" value="Bits per second out" />
+ <param name="line-style-out" value="LINE2" />
+ <param name="line-color-out" value="#0000FF" />
+ <param name="line-order-out" value="2" />
+
+ </leaf>
+ </subtree>
+
+Parameters:
+
+=over 4
+
+=item * C<ds-names>
+
+Comma-separated list of symbolic DS names. These names are
+used for other DS-specific parameter names formation.
+In the parameter descriptions below, C<X> stands for the DS name.
+
+=item * C<ds-expr-X>
+
+Datasource leaf RPN expression.
+Any other parameter values may be substituted as C<%parameter_name%>.
+
+=item * C<graph-legend-X>
+
+Short description text used as the graph legend.
+
+=item * C<line-style-X>
+
+Line specification in RRD graph. May be I<C<LINE1>>, I<C<LINE2>> etc.
+Two hashes in the beginning and a name refer to the line style from
+the styling profile, e.g. C<##BpsIn>.
+
+=item * C<line-color-X>
+
+Line color. Must have the hash symbol in the beginning, like I<C<#0000FF>>.
+Two hashes in the beginning and a name refer to the color from
+the styling profile, e.g. C<##BpsIn>.
+
+=item * C<line-order-X>
+
+Numerical order of line drawing. The lines are drawn in accending order.
+If omitted, the XML compiler issues warning, and Renderer conciders
+the order of 100.
+
+=item * C<line-stack-X>
+
+Optional. When set to C<yes>, the line is stacked on top of a previous line.
+Both areas and lines are stackable.
+
+=item * C<line-alpha-X>
+
+Optional. If specified, must be two hexademical, uppercase digits. This
+parameter defines the line (or area) transparency. Value C<FF> is
+equivalent to solid colour. Value C<7F> gives 50% transparency which should
+be suitable for most applications.
+
+=item * C<ignore-views-X>
+
+Optional comma-separated list of view names. The graph for this DS name
+will not be drawn in the views specified. The validator does not check
+it, so it's up to you to guarantee that at least one DS is always displayed
+in a multigraph.
+
+=item * C<disable-gprint-X>
+
+Optional. When set to C<yes>, this datasource is not included in GPRINT output.
+
+=back
+
+=head2 View definitions
+
+In our context, I<view> means any kind of object representation.
+The same subtree or view can be displayed in different ways and in
+different formats: HTML, graph image, plain text, etc.
+
+I<Renderer> module handles these view definitions. For any subtree
+or leaf, it renders the specified view, and keeps the cache of rendered
+files.
+
+Each subtree or leaf must have a default view. This is controlled by
+two parameters that may be defined in the root subtree:
+C<default-subtree-view> and C<default-leaf-view>.
+
+The set of views is flat, though they can inherit the parameters
+one from another. Each view is referenced by its name, and is
+defined by the set of parameters. Same way as with datasources,
+certain parameter values imply the neccessaty to define certain other
+parameters:
+
+ <views>
+ <view name="default-rrgraph">
+ <param name="view-type" value="rrgraph" />
+ <param name="expires" value="300" />
+ <param name="width" value="500" />
+ <param name="height" value="250" />
+ <param name="width-hint" value="580" />
+ <param name="line-style" value="##SingleGraph" />
+ <param name="line-color" value="##SingleGraph" />
+
+ <!-- Daily graph, inherits parameters from the above -->
+ <view name="last24h">
+ <param name="start" value="-24h" />
+ </view>
+
+ <!-- Weekly graph -->
+ <view name="lastweek">
+ <param name="start" value="-7d" />
+ </view>
+ </view>
+ </views>
+
+Currently the view is defined by the configuration only.
+Probably, in the future additional parameters will be supplied dynamically.
+
+
+=head3 View parameters
+
+For every view, the mandatory parameters are:
+
+=over 4
+
+=item * C<view-type>
+
+Determines the processing procedure which interprets the other parameters.
+
+=item * C<expires>
+
+Gives the expiration time in seconds for the I<Renderer> cache.
+
+=back
+
+The following values of C<view-type> are recognized:
+
+=over 4
+
+=item * C<html>
+
+Defines the HTML representation of subtree or a leaf.
+One additional parameter is required: C<html-template> must contain a file
+name of the HTML template. Those templates are copied from F<templates>
+subdirectory of the installation package. We use Template-Toolkit
+E<lt>http://www.template-toolkit.orgE<gt> for HTML processing.
+The template file name is defined with the parameter C<html-template>.
+
+The following
+variables and functions are defined when the template is processed:
+
+=over 8
+
+=item * C<token>
+
+Returns the current node token.
+
+=item * C<view>
+
+Returns the name of the current view.
+
+=item * C<path(token)>
+
+Returns the full path name of the given node token.
+
+=item * C<pathToken(path)>
+
+Returns the token for the specified path.
+
+=item * C<nodeExists(path)>
+
+Returns true if the specified path points to a node.
+
+=item * C<children(path)>
+
+Returns the list of children for the given path.
+
+=item * C<isLeaf(token)>
+
+Returns true if the token is pointing to a leaf node.
+
+=item * C<sortTokens(array)>
+
+Returns the array of tokens, sorted according to C<precedence> parameter.
+
+=item * C<nodeName(token)>
+
+Returns the node name part of the node path.
+
+=item * C<parent(token)>
+
+Returns the parent's token for the specified node.
+
+=item * C<nodeParam(token, param_name)>
+
+Returns the value of the parameter for the given node.
+
+=item * C<param(entity_name, param_name)>
+
+Returns the value of the parameter for the given view, monitor, or action.
+
+=item * C<url(token, [view])>
+
+Returns the URL which displays the given node using the given view.
+If the view is omitted, use the default view.
+
+=item * C<persistentUrl(token, [view])>
+
+Same as above, but the URL is built from persistent information: nodeid
+(if available) or full path in the tree.
+
+=item * C<splitUrls(token, [view])>
+
+Returns a piece of HTML code representing the path with clickable
+node names, each referencing the corresponding view.
+
+=item * C<rrprint(token, view)>
+
+The specified view must be of type C<rrprint>. Returned is the text
+output produced by this view.
+
+=item * C<scale(text)>
+
+Interprets the given text as a floating-point number and returns
+its representation in the "metric" scale: 1000 is translated into "k",
+million into "M" etc. It may be used together with C<rrprint>
+for better formatting.
+
+=item * C<tsetMembers(tset)>
+
+Returns the array of the tokenset member tokens.
+
+=item * C<tsetList>
+
+Returns the array of the tokenset names.
+
+=item * C<stylesheet>
+
+Returns the relative URI to the default CSS stylesheet,
+as defined in C<$Torrus::Renderer::stylesheet>.
+
+=item * C<version>
+
+Returns current Torrus package version.
+
+=back
+
+=item * C<rrgraph>
+
+Generates the RRD Graph representation of the given I<leaf> (remember,
+subtrees are only logical grouping of the real data).
+
+The following parameters are mandatory for this kind of view:
+
+=over 8
+
+=item * C<width>, C<height>, C<start>
+
+Correspond to same parameters in RRD Graph command.
+C<end> can also be given, it defaults to I<C<now>>.
+
+=item * C<line-style>
+
+Line specification in RRD graph. May be I<C<LINE1>>, I<C<LINE2>> etc.
+Two hashes in the beginning and a name refer to the line style from
+the styling profile, e.g. C<##SingleGraph>.
+
+=item * C<line-color>
+
+Line color. Must have the hash symbol in the beginning, like I<C<#0000FF>>.
+Two hashes in the beginning and a name refer to the color from
+the styling profile, e.g. C<##SingleGraph>.
+
+=item * C<rrd-hwpredict>
+
+If equals to C<disabled>, HWPREDICT display is disabled for this view.
+Note that if the datasource has C<rrd-hwpredict> parameter set to C<enabled>,
+this emplies that the view would contain Holt-Winters boundaries and failures
+graph.
+
+=item * C<hw-bndr-style>
+
+Optional parameter, defaults to C<LINE1>. Specifies the line style for
+Holt-Winters boundaries.
+
+=item * C<hw-bndr-color>
+
+Optional parameter, defaults to C<#FF0000>. Specifies the color for
+Holt-Winters boundaries.
+
+=item * C<hw-fail-color>
+
+Optional parameter, defaults to C<#FFFFA0>. Specifies the color for
+Holt-Winters failure ticks.
+
+=item * C<hrules>, C<hrule-value-I<name>>, C<hrule-color-I<name>>
+
+Optional parameter C<hrules> contains a comma-separated list of
+horizontal rule names. For each name, mandatory parameter
+C<hrule-value-I<name>> defines a name of the leaf parameter that will be
+used as the horizontal rule value. The rule is not drawn if such parameter
+is not defined for the leaf. Mandatory parameter C<hrule-color-I<name>>
+defines the color for the rule, of the form C<#DDDDDD>, where C<D> corresponds
+to a hexademical digit. Two hashes in the beginning and a name refer to
+the color from the styling profile, e.g. C<##HruleMin>.
+Optional parameter C<hrule-legend-I<name>>
+defines the legend text to be displayed on the graph. The following horizontal
+rules are defined in F<defaults.xml> for all rrgraph views:
+
+ <param name="hrules" value="min,norm,max"/>
+ <param name="hrule-color-min" value="##HruleMin"/>
+ <param name="hrule-value-min" value="lower-limit"/>
+ <param name="hrule-color-norm" value="##HruleNormal"/>
+ <param name="hrule-value-norm" value="normal-level"/>
+ <param name="hrule-color-max" value="##HruleMax"/>
+ <param name="hrule-value-max" value="upper-limit"/>
+
+
+=item * C<decorations>
+
+Optional. Comma-separated list of decoration names. Decoration is an RRD
+pseudo-line that does not depend on any datasource. For each decoration
+name, the following parameters must be supplied: C<dec-order-E<lt>nameE<gt>>
+determines the order of drawing. Negative order numbers correspond to
+the lines or areas behind the data line. C<dec-expr-E<lt>nameE<gt>>
+gives the RPN expression that defines the line or area.
+C<dec-style-E<lt>nameE<gt>> and C<dec-color-E<lt>nameE<gt>> define
+the style (AREA or LINE1..3) and the color of the drawing.
+Node parameter C<graph-ignore-decorations> disables the decorations.
+
+=item * C<gprint-values>, C<gprint-header>, C<gprint-format-*>
+
+Optional. These parameters define the printing of values together with legends
+below the graph. C<gprint-values> is a comma-separated list of format names,
+and for each format name, there should be a corresponding C<gprint-format-*>
+parameter. C<gprint-header> defines a string that will be printed on top of
+all orther lines. Example:
+
+ <param name="gprint-values" value="current,average,max,min"/>
+ <param name="gprint-header"
+ value="Current Average Maximum Minimum"/>
+ <param name="gprint-format-current" value="LAST:%8.2lf%s"/>
+ <param name="gprint-format-average" value="AVERAGE:%8.2lf%s"/>
+ <param name="gprint-format-max" value="MAX:%8.2lf%s"/>
+ <param name="gprint-format-min" value="MIN:%8.2lf%s"/>
+
+=item * C<description>
+
+Optional. Defines the text description of the graph. This description is
+usually placed as ALT HTML attribute in the generated HTML pages.
+
+=item * C<rrd-params>
+
+Optional. Supplies additional RRDtool graph comand-line options, as one
+string separated by spaces.
+
+=back
+
+=item * C<rrprint>
+
+This view produces the text output from PRINT statement in
+RRD graph command. The required parameters are C<start> and C<print-cf>.
+The first one defines the starting time. C<end> may be also optionally
+specified.
+
+C<print-cf> specifies oe or more consolidation functions, separated by comma.
+The result of the rendering is the text line with the output values
+separated by colon (:).
+
+=back
+
+=item * C<disable-legend>, C<disable-title>, C<disable-vertical-label>
+
+When set to C<yes>, the corresponding elements of the graph are not displayed.
+
+
+
+=head3 Styling Profiles
+
+Styling profiles allow symbolic names to be used for line type
+and color.
+
+Two hashes in the beginning and a name refer to the line style from
+the styling profile, e.g. C<##BpsIn>, C<##green>, C<##one>, C<##two>.
+
+ <leaf name="InOutBytes">
+ <param name="comment" value="Input and Output bits per second graphs"/>
+ <param name="ds-type" value="rrd-multigraph"/>
+ <param name="ds-names" value="in,out"/>
+ <!-- IN -->
+ <param name="ds-expr-in" value="{ifInOctets}"/>
+ <param name="graph-legend-in" value="Bytes per second in"/>
+ <param name="line-style-in" value="##BpsIn"/>
+ <param name="line-color-in" value="##BpsIn"/>
+ <param name="line-order-in" value="1"/>
+ <!-- OUT -->
+ <param name="ds-expr-out" value="{ifOutOctets}"/>
+ <param name="graph-legend-out" value="Bytes per second out"/>
+ <param name="line-style-out" value="##BpsOut"/>
+ <param name="line-color-out" value="##BpsOut"/>
+ <param name="line-order-out" value="2"/>
+ </leaf>
+
+When processed the example above effectivly becomes:
+
+ <leaf name="InOutBytes">
+ <param name="comment" value="Input and Output bits per second graphs"/>
+ <param name="ds-type" value="rrd-multigraph"/>
+ <param name="ds-names" value="in,out"/>
+ <!-- IN -->
+ <param name="ds-expr-in" value="{ifInOctets}"/>
+ <param name="graph-legend-in" value="Bytes per second in"/>
+ <param name="line-style-in" value="AREA"/>
+ <param name="line-color-in" value="#00FF00"/>
+ <param name="line-order-in" value="1"/>
+ <!-- OUT -->
+ <param name="ds-expr-out" value="{ifOutOctets}"/>
+ <param name="graph-legend-out" value="Bytes per second out"/>
+ <param name="line-style-out" value="LINE2"/>
+ <param name="line-color-out" value="#0000FF"/>
+ <param name="line-order-out" value="2"/>
+ </leaf>
+
+Schema definitions can be modified in two ways
+(see the I<Torrus Styling Profile Guide> manual for available styles
+and override details)
+
+=over 4
+
+=item * Create an overlay schema:
+
+Specify the overlay schema in torrus-siteconfig.pl using the
+$Torrus::Renderer::stylingProfileOverlay variable.
+
+=item * Create a replacement schema:
+
+Specify the replacement schema in torrus-siteconfig using the
+$Torrus::Renderer::stylingProfile variable.
+
+=back
+
+
+=head2 Token sets definitions
+
+I<Token> is a symbolic identifier for each subtree or a leaf.
+
+A I<tokenset> is a named list of tokens. Its contents can be
+rendered, and its members can be added or removed at any time.
+
+Each tokenset can have a number of parameters defined. It also
+inherits the parameter defined in the top C<E<lt>token-setsE<gt>>
+XML element:
+
+ <token-sets>
+
+ <param name="default-tset-view" value="default-tset-html" />
+ <param name="default-tsetlist-view" value="tset-list-html" />
+
+ <token-set name="jumps">
+ <param name="comment" value="Traffic rate jumps" />
+ </token-set>
+
+ <token-set name="hw-failures">
+ <param name="comment" value="Holt-Winters prediction failures" />
+ </token-set>
+
+ </token-sets>
+
+Parameter C<default-tsetlist-view> is mandatory for tokenset list.
+It defines the default view when displaying the list of tokensets.
+
+The following parameters are mandatory for tokensets:
+
+=over 4
+
+=item * C<default-tset-view>
+
+Determines the view for displaying the tokenset contents.
+
+=item * C<comment>
+
+The text that describes this tokenset.
+
+=back
+
+=head2 Monitor definitions
+
+I<Monitor> is a named set of parameters that defines the behaviour
+of monitor module. Each leaf can be given a number of monitors
+via C<monitor> parameter.
+
+Upon monitor module run, an I<action> is launched if the alarm conditions
+of a given monitor are satisfied.
+
+ <monitors>
+ <!-- First define the actions -->
+
+ <!-- This action will put the graphs of alarmed datasources in
+ a single alarm report page -->
+ <action name="graph-hw-failures">
+ <param name="action-type" value="tset" />
+ <param name="set-name" value="hw-failures" />
+ </action>
+
+ <action name="graph-jumps">
+ <param name="action-type" value="tset" />
+ <param name="set-name" value="jumps" />
+ </action>
+
+ <monitor name="hw-failures">
+ <param name="monitor-type" value="failures" />
+ <param name="action" value="graph-hw-failures" />
+ <param name="expires" value="3600" />
+ </monitor>
+
+ <!-- alarm if 5 minutes away it was 10 times lower -->
+ <monitor name="high-jumps">
+ <param name="monitor-type" value="expression" />
+ <param name="rpn-expr" value="{(-300)},10,*,GT,{},{(-300)},10,/,LT,OR" />
+ <param name="action" value="graph-jumps" />
+ <param name="expires" value="3600" />
+ <param name="comment"
+ value="Value jumped more than 10-fold in 5 minutes" />
+ </monitor>
+
+ <monitor name="hundred-megs">
+ <param name="monitor-type" value="expression" />
+ <param name="rpn-expr" value="100,1024,1024,*,*,GT" />
+ <param name="action" value="graph-jumps" />
+ <param name="expires" value="3600" />
+ <param name="comment"
+ value="Traffic is higher than 10 mbps" />
+ </monitor>
+ </monitors>
+
+=head3 Event types
+
+Should the alarm condition occur, a series of events is happening
+in sequentional order:
+
+=over 4
+
+=item * C<set>
+
+This event type occurs the first time the alarm condition is met.
+
+=item * C<repeat>
+
+This event type means that the alarm condition still persists
+after the previous run of Monitor.
+
+=item * C<clear>
+
+Event of this type happens when the alarm condition stops.
+
+=item * C<forget>
+
+Once the alarm is cleared, this event happens after the expiration
+time of the monitor.
+
+=back
+
+=head3 Monitor parameters
+
+=over 4
+
+=item * C<monitor-type>
+
+Mandatory parameter. Specifies the monitor type. The following monitor
+types are recognized:
+
+=over 8
+
+=item * C<failures>
+
+Triggers the action when Holt-Winters FAILURES function gives value of 1.
+This requires RRDtool verion 1.1.x and aberrant behaviour parameters
+defined for te given RRD file.
+
+=item * C<expression>
+
+Triggers the action when given RPN expression returns nonzero.
+See I<RPN expressions in Torrus> manual for more details.
+This monitor type implies that the RPN expression is specified in
+C<rpn-expr> parameter. The current leaf value is prepended to the given RPN.
+
+=back
+
+=item * C<rpn-expr>
+
+Mandatory for monitor type C<expression>. Defines the RPN expression to
+evaluate. The current leaf value is prepended to the given RPN.
+The expresion may reference leaf-dependent variables: the
+constructs of the form C<#varname> are replaced with the variable
+value specified in the leaf's C<monitor-vars> parameter.
+
+=item * C<action>
+
+Mandatory parameter, comma-separated list of action names (spaces
+are allowed). Each action is triggered when the alarm condition is met.
+
+=item * C<expires>
+
+Mandatory parameter, the number of seconds of expiration period.
+After the alarm condition becomes false, this parameter determines
+the time of memorizing the event in monitor status reports.
+
+=item * C<comment>
+
+Optional but recommended parameter, specifies the string identifying
+the event that this monitor watches.
+
+=item * C<severity>
+
+Optional severity level. Used for the action type C<exec>.
+
+=item * C<display-rpn-expr>
+
+Optional RPN expression for transforming the datasource value.
+If defined, it will be applied to the value before setting
+C<TORRUS_VALUE> and C<TORRUS_DISPLAY_VALUE> environment variables.
+
+=item * C<display-format>
+
+Optional I<sprintf> format for displaying the value in
+C<TORRUS_DISPLAY_VALUE> environment variable. Default is C<%.2f>.
+
+=back
+
+
+=head3 Action parameters
+
+=over 4
+
+=item * C<action-type>
+
+Mandatory parameter, defines the type of action. Recognized
+values are:
+
+=over 8
+
+=item * C<tset>
+
+When this type of action is triggered, the leaf is added to the specified
+tokenset (see I<Token sets definitions> section in this manual).
+The leaf persists in the tokenset until the event of type C<forget>.
+This action type implies the parameter C<tset-name>.
+
+=item * C<exec>
+
+This action type defines an external program to launch. Two other parameters
+determinate its behaviour: mandatory C<command> and optional C<launch-when>.
+
+=back
+
+=item * C<tset-name>
+
+Mandatory for action type C<tset>. Defines the tokenset name
+where the leaf is added when the monitor condition is met.
+
+=item * C<command>
+
+Mandatory for action type C<exec>. Defines the external program to launch.
+The following strings are substituted in the parameter value:
+
+=over 8
+
+=item * C<E<amp>gt;>
+
+Relaced with C<E<gt>>.
+
+=item * C<E<amp>lt;>
+
+Relaced with C<E<lt>>.
+
+=back
+
+The following environment variables are passed to the child process:
+
+=over 8
+
+=item * C<$TORRUS_HOME>
+
+C<prefix> where Torrus was installed.
+
+=item * C<$TORRUS_BIN>
+
+Directory containing Torrus executables.
+
+=item * C<$TORRUS_UPTIME>
+
+Number of seconds since Monitor has started.
+
+=item * C<$TORRUS_TREE>, C<$TORRUS_TOKEN>, C<$TORRUS_NODEPATH>
+
+Tree name, token and pathname of the leaf causing the alarm.
+
+=item * C<$TORRUS_NCOMMENT>, C<$TORRUS_NPCOMMENT>
+
+C<comment> parameter of the node and its parent.
+Empty if the parameter is not defined for the given leaf.
+
+=item * C<$TORRUS_EVENT>
+
+Event type.
+
+=item * C<$TORRUS_MONITOR>
+
+Monitor name
+
+=item * C<$TORRUS_MCOMMENT>
+
+Monitor's C<comment> parameter value.
+
+=item * C<$TORRUS_TSTAMP>
+
+Timestamp (in seconds since Epoch) of the event.
+
+=item * C<$TORRUS_VALUE>
+
+For expression monitor type, this returns the last read value of the
+datasource, possibly transformed by C<display-rpn-expr> expression.
+
+=item * C<$TORRUS_DISPLAY_VALUE>
+
+For expression monitor type, it contains a human-readable form
+of the value, possibly transformed by C<display-rpn-expr> expression.
+
+=item * C<$TORRUS_SEVERITY>
+
+If the C<severity> parameter is defined in the monitor, its value
+is passed with this variable.
+
+=back
+
+=item * C<launch-when>
+
+Optional for action type C<exec>. The comma-separated list of event
+types when the given action should be launched. If not defined,
+the event type C<set> is used by default.
+
+=item * C<setenv-params>
+
+Optional for action type C<exec>. The comma-separated list of leaf parameters
+which would be passed as environment variables to the child process.
+The environment variables are of the form C<$TORRUS_P_paramname>. Hyphens ('-')
+are replaced with underscores ('_') in the parameter names.
+
+=item * C<setenv-dataexpr>
+
+Optional for action type C<exec>. Comma-separated list of C<ENV=paramname>
+pairs. C<ENV> defines the environment variable name: it is prefixed with
+C<Torrus_>. C<paramname> defines the action parameter name. This parameter
+is interpreted as RPN expression applied to the current leaf being monitored.
+The result of this RPN expression is passed to the action script
+in the environment variable.
+
+Example:
+
+ <action name="report-temperature">
+ <param name="action-type" value="exec" />
+
+ <!-- This is our proprietary reporting script -->
+ <param name="command">
+ /usr/local/bin/report_temperature
+ </param>
+ <param name="launch-when" value="set" />
+
+ <!-- We want to tell the action script the actual values
+ of the "temperature" and "humidity" leaves in the current
+ datasource tree -->
+ <param name="setenv-dataexpr" value="TEMP=expr-temp, HMD=expr-hmd" />
+ <param name="expr-temp" value="{temperature(LAST)}" />
+ <param name="expr-hmd" value="{humidity(LAST)}" />
+
+ <!-- We also want to tell the action script the parameter "monitor-vars"
+ which was configured for the current leaf. -->
+ <param name="setenv-params" value="monitor-vars" />
+ </action>
+
+
+=back
+
+
+=head1 Author
+
+Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>
projects / freeside.git / blobdiff