diff options
Diffstat (limited to 'torrus/doc/xmlconfig.pod.in')
-rw-r--r-- | torrus/doc/xmlconfig.pod.in | 1725 |
1 files changed, 1725 insertions, 0 deletions
diff --git a/torrus/doc/xmlconfig.pod.in b/torrus/doc/xmlconfig.pod.in new file mode 100644 index 000000000..f1ae4350c --- /dev/null +++ b/torrus/doc/xmlconfig.pod.in @@ -0,0 +1,1725 @@ +# 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> |