X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=torrus%2Fdoc%2Fxmlconfig.pod.in;fp=torrus%2Fdoc%2Fxmlconfig.pod.in;h=f1ae4350cb518a2d663793e4d0e98cb6538ab2db;hp=0000000000000000000000000000000000000000;hb=74e058c8a010ef6feb539248a550d0bb169c1e94;hpb=35359a73152b3d7a9ad5e3d37faf81f6fedb76e8 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 +# +# + +=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. +In addition, when I, I and I processes +notice the configuration changes, they refresh their information automatically. + +The top-level XML element is always CconfigurationE>, with +sub-elements defining various sections, like datasources or views: + + + + + + + + + ... + + + + ... + + + + + + + + + + + + + + + + ... + +These definitions are global across all XML configuration files, +and are referenced with dollar sign and the definition name, e.g.: + + + + ... + + +=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". + + + + + + + + ... + + + + +=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 and I. 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: + + + + + + + + + + + ... + + + ... + + + + + + + + + + + + + + + + + + + + + + + + +Each subtree or a leaf is identified by a I, 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 and +I. + +=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 CtemplateE> +element is memorized under the template name, and reproduced +in every occurrence of Capply-templateE> with the corresponding +template name. The template definition must be the direct child +element of CconfigurationE> XML element: + + + + + + + + + ... + + + + + + + + + + + + + + + + + +=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: + + + /Netflow/ExportersByName/rtrTelehouse1/ + ... + +=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 XML element, with mandatory attributes +C and C. + +Variable values are used in C and C XML elements. +Mandatory parameter C specifies the variable name. The child XML elements +are compiled if the variable value is true or false, correspondingly. +A true value is C or a nonzero number. Undefined variable is identified +as false. + +Example: + + + + + + .... + + + +=head3 Parameter value substitution + +For any given leaf, some parameters may reference the other parameter values, +by embracing the parameter name with percent signs: + + + +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 + +Mandatory parameter for every datasource leaf. Currently, the following values +are recongized: + +=over 8 + +=item * C + +The datasource is an RRD file generated by some external collector. +Implies mandatory parameters: C, C, C. + +=item * C + +The datasource is generated by Torrus Collector. +Implies mandatory parameters: C, C, +C, C. + +=item * C + +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 + +Optional. If defined, it should contain a unique string identifying +this particular leaf or subtree. + + +=item * C + +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 + +Optional. This is a string of text which is displayed when browsing through +the tree. + +=item * C + +Optional. This parameter is not inherited by child nodes. If defined, +the user is offered a I 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 + +Optional. Comma-separated list of monitor names (spaces are allowed) that +must be run upon periodic runs of monitor module (see I +section of this manual). Monitor schedule parameters must be defined +for the monitor to run properly: C and C. + +=item * C, C + +Mandatory parameters for leaves that have C 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 + +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 parameter. +The syntax of this parameter is semicolon-delimited C pairs: + + + +=item * C + +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 + +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 + +Optional. If given, produces a short listing at the top of the HTML output, +with tabulated values. Format: C. +Spaces around the delimiters are ignored. + +Example: + + + + Location:Zurich; + Contact: John Smith; + Telephone: 01 9911299 + + +=item * C + +A horizontal string at the top of the graph. + +=item * C + +Optional. This legend text is printed inside the graph explaining +the line color. + +=item * C + +Optional. Text to print along Y axsis on the graph. + +=item * C, C + +Optional. Fix the upper and lower boundaries of the graph. + +=item * C + +Optional. When set to "yes", the graph will not expand if the value is outside +the lower or upper limit. + +=item * C + +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 + +Optional. When set to "yes", the graph is drawn in logarithmic y-axis scale. + +=item * C, C + +These optional parameters override the corresponding ones from the view +definition. + +=item * C, C + +Mandatory. Determine the default view for a leaf or subtree, correspondingly. +See I section of this manual. + +=item * C + +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 + +Optional. Adds this leaf or this subtree child leaves to the specified +token sets. Tokenset names are comma-separated, and must be defined in +Ctoken-setsE> part of configuration. + +=item * C + +Optional. If defined, it is used in tokenset members listing as a member +identifier, instead of the leaf path. + +=item * C + +Optional. Valid values: C, C. +When set to C, the leaf or subtree is not +displayed in the subtree listing, +unless C option is true. When C is enabled, +the node name and comment are shown in italics. + +=item * C, C, +C, C, +C, C, +C, C + +When C is set to C on a subtree level, +default HTML templates expect the five parameters to be set. +C is a comma-separated list of shortcut names, +and for each name "X", C defines the +current subtree's grandchild leaves name which would compose the overview page. +When C is set to C, the URL under the +graph will point to the direct child subtree, and +C will define the view for that subtree. +Usually this view would be C. + +=item * C, C, C + +Optional. When set to C, they make the renderer ignore +C, C, or both, accordingly. +In addition, C disables the C +parameter. + +=item * C + +Optional. When set to C, the view C are ignored. + +=item * C + +Optional. When set to C, the view parameter C and other +GPRINT-related parameters are ignored. + +=item * C> + +Optional. If a horizontal rule with the given name is defined, this parameter +specifies the legend to be printed. + +=item * C + +Optional. If set to C, the corresponding subtree or leaf is included +in the search database. + +=back + + +=head3 RRD-related parameters + +=over 4 + +=item * C + +Mandatory. Specifies the filesystem directory +path where the data files are resided. + +=item * C + +Mandatory. Name of the data file. + +=item * C + +Mandatory. Determines the type of RRD access. Recognized values are: + +=over 8 + +=item * C + +Corresponds to DEF specification in RRDgraph query. Implies two mandatory +parameters: C and C, giving the DS name and consolidation +function, correspondingly. + +=item * C + +Mandatory when a leaf refers to an RRD file (C in +C leaves or C in C leaves). The +parameter Specifies the RRD datasource name within a file. + +=item * C + +Mandatory when a leaf refers to an RRD file (C in +C leaves or C in C leaves). The +parameter Specifies the RRD datasource name within a file. + +=item * C + +Mandatory under the same conditios as C. Defines the default +consolidation function which is used when retrieving the RRD data. + +=item * C + +Supported for C only. +Corresponds to CDEF specification in RRDgraph query. Implies one +mandatory parameter: C, 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 manual for more details. + +=back + +=item * C + +Optional. If equals to C, then this RRD datasource +is expected to have HWPREDICT and all the suite of +Holt-Winters consolidation functions. +In case of C, C indicates +that the RRD file must be created with use of Holt-Winters RRAs. + +=item * C + +Mandatory when C and C. +Specifies the datasource type for RRD creation. Valid values are: +C, C, C, C. + +=item * C + +Mandatory when C and C. +Space-separated list of RRA definitions for RRD creation, as they +are passed to RRD Create command. +Example: + + + + 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 + + +=item * C + +Mandatory when C and C. +Heartbeat parameter as defined in RRD Create manual page. + +=item * C, C + +Optional minimum and maximum parameters for RRD datasource. + +=item * C + +Mandatory when C and C +and C. Specifies the RRA length for +Holt-Winters archives. Recommended same length as main 5-minutes RRA. + +=item * C, C, + C, C, + C, C + +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 + +Mandatory parameter for datasource type C. Currently supported +values are: C and C. Other valid values may be added with plugins. + +=item * C + +Mandatory parameter for datasource type C. Comma-separated list +of storage types. The collected value is duplicated on every storage listed. +Supported values are: C, C. For C (external storage), +see the I. + +=item * C, C + +Mandatory parameters for datasource type C. +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 + +Optional. When set to C, C spreads the collector offsets +among values determined from C, +C, C, +and C. + +=item * C, +C, C + +Mandatory when C is set to C. +They define the limits and the step for collector timeoffset dispersion. + +=item * C + +Mandatory when C is set to C. +Defines the string that is used as a hash for timeoffset dispersion. + +=item * C + +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 + +Mandatiry. The parameter defines the collector instance number. +This parameter is automatically calculated by the configuration compiler. + +=item * C + +Optional. Defines a piece of Perl code that will be used for value +transformation. The keyword C is replaced with the dollar sign ($), +and C is replaced with the percent sign (%). +The initial value is supplied in C<$_>, which should be referenced as +C in your Perl code. +The code should return a numeric value or C 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 + +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 pairs. + + +=item * C + +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 the translation works I +the RRDtool processes the data, so it makes sence to scale only non-COUNTER +values. + +=item * C + +Mandatory for C. Valid values are C<4> and C<6>. The +parameter defines the IP protocol version. If C contains a DNS +name, the IP address is determined by looking up A or AAAA DNS records, +according to IP version. + +=item * C + +Mandatory for C. Valid values are C and C. + + +=item * C + +Mandatory when C. Specifies the hostname or IP address +of the SNMP agent. + +=item * C + +Mandatory when C. Specifies the UDP port of the +SNMP agent. + +=item * C + +Optional DNS domain name. If given, and if C does not contain +dot symbol (.), this domain name is appended to C. + +=item * C and C + +Optional parameters specifying the local socket binding address and port. + +=item * C + +Mandatory when C. Specifies the SNMP version for the +given device. Valid values are: C<1>, C<2c>, C<3>. + +=item * C + +Mandatory when C and SNMP version is +C<1> or C<2c>. Specifies the SNMP community for the given device. + +=item * C + +Mandatory when C and SNMP version is C<3>. + +=item * C + +Optional authentication key for SNMPv3. If not defined, the authentication +level is set to C. If only C or +C are specified, the security level is set to +C. The security level is set to C if either +of C or C is defined. + +=item * C + +Optional authentication password for SNMPv3. See notes for C +parameter. + +=item * C + +Optional authentication protocol for SNMPv3. Valid values: C or C. +Default is C. + +=item * C + +Optional privacy key for SNMPv3. If defined, C or +C must be defined too. + +=item * C + +Optional privacy password for SNMPv3. If defined, C or +C must be defined too. + +=item * C + +Optional privacy protocol for SNMPv3. Valid values: C, C, +or C<3desede>. Default is C. + +=item * C + +Mandatory when C. Specifies the SNMP session timeout +in seconds. + +=item * C + +Mandatory when C. Specifies the SNMP session retry count. + +=item * C + +Mandatory when C. Specifies the number of SNMP OIDs per +one UDP packet. + +=item * C + +Mandatory when C. 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 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 + +Optional. Supported values: C, C. When set to C, +the SNMP variable value is treated as 64-bit integer. Not using this +parameter may lead to loss of precision. + +=item * C + +Optional. Default value: C. When set to C, the collector does not +query C (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 + +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 + +Optional. If set to C, the SNMP errors C, C, +C are ignored, and no action is performed when such errors +occur. + +=item * C + +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, C and C. + +=item * C + +Mandatory when C. 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 + +Mandatory when C. 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 sets +the default value to 0. + +=item * C + +Mandatory when C. Delay time in collector periods that +the collector accepts when no recent data is available. +F sets the default value to 2. + +=back + + +=head3 RRD-Multigraph leaves + +The leaves with C 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: + + + + + + + + + + + + + + + + + + + + + + + + +Parameters: + +=over 4 + +=item * C + +Comma-separated list of symbolic DS names. These names are +used for other DS-specific parameter names formation. +In the parameter descriptions below, C stands for the DS name. + +=item * C + +Datasource leaf RPN expression. +Any other parameter values may be substituted as C<%parameter_name%>. + +=item * C + +Short description text used as the graph legend. + +=item * C + +Line specification in RRD graph. May be I>, I> 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. Must have the hash symbol in the beginning, like I>. +Two hashes in the beginning and a name refer to the color from +the styling profile, e.g. C<##BpsIn>. + +=item * C + +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 + +Optional. When set to C, the line is stacked on top of a previous line. +Both areas and lines are stackable. + +=item * C + +Optional. If specified, must be two hexademical, uppercase digits. This +parameter defines the line (or area) transparency. Value C is +equivalent to solid colour. Value C<7F> gives 50% transparency which should +be suitable for most applications. + +=item * C + +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 + +Optional. When set to C, this datasource is not included in GPRINT output. + +=back + +=head2 View definitions + +In our context, I 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 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 and C. + +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: + + + + + + + + + + + + + + + + + + + + + + + +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 + +Determines the processing procedure which interprets the other parameters. + +=item * C + +Gives the expiration time in seconds for the I cache. + +=back + +The following values of C are recognized: + +=over 4 + +=item * C + +Defines the HTML representation of subtree or a leaf. +One additional parameter is required: C must contain a file +name of the HTML template. Those templates are copied from F +subdirectory of the installation package. We use Template-Toolkit +Ehttp://www.template-toolkit.orgE for HTML processing. +The template file name is defined with the parameter C. + +The following +variables and functions are defined when the template is processed: + +=over 8 + +=item * C + +Returns the current node token. + +=item * C + +Returns the name of the current view. + +=item * C + +Returns the full path name of the given node token. + +=item * C + +Returns the token for the specified path. + +=item * C + +Returns true if the specified path points to a node. + +=item * C + +Returns the list of children for the given path. + +=item * C + +Returns true if the token is pointing to a leaf node. + +=item * C + +Returns the array of tokens, sorted according to C parameter. + +=item * C + +Returns the node name part of the node path. + +=item * C + +Returns the parent's token for the specified node. + +=item * C + +Returns the value of the parameter for the given node. + +=item * C + +Returns the value of the parameter for the given view, monitor, or action. + +=item * C + +Returns the URL which displays the given node using the given view. +If the view is omitted, use the default view. + +=item * C + +Same as above, but the URL is built from persistent information: nodeid +(if available) or full path in the tree. + +=item * C + +Returns a piece of HTML code representing the path with clickable +node names, each referencing the corresponding view. + +=item * C + +The specified view must be of type C. Returned is the text +output produced by this view. + +=item * C + +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 +for better formatting. + +=item * C + +Returns the array of the tokenset member tokens. + +=item * C + +Returns the array of the tokenset names. + +=item * C + +Returns the relative URI to the default CSS stylesheet, +as defined in C<$Torrus::Renderer::stylesheet>. + +=item * C + +Returns current Torrus package version. + +=back + +=item * C + +Generates the RRD Graph representation of the given I (remember, +subtrees are only logical grouping of the real data). + +The following parameters are mandatory for this kind of view: + +=over 8 + +=item * C, C, C + +Correspond to same parameters in RRD Graph command. +C can also be given, it defaults to I>. + +=item * C + +Line specification in RRD graph. May be I>, I> 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. Must have the hash symbol in the beginning, like I>. +Two hashes in the beginning and a name refer to the color from +the styling profile, e.g. C<##SingleGraph>. + +=item * C + +If equals to C, HWPREDICT display is disabled for this view. +Note that if the datasource has C parameter set to C, +this emplies that the view would contain Holt-Winters boundaries and failures +graph. + +=item * C + +Optional parameter, defaults to C. Specifies the line style for +Holt-Winters boundaries. + +=item * C + +Optional parameter, defaults to C<#FF0000>. Specifies the color for +Holt-Winters boundaries. + +=item * C + +Optional parameter, defaults to C<#FFFFA0>. Specifies the color for +Holt-Winters failure ticks. + +=item * C, C>, C> + +Optional parameter C contains a comma-separated list of +horizontal rule names. For each name, mandatory parameter +C> 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> +defines the color for the rule, of the form C<#DDDDDD>, where C 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> +defines the legend text to be displayed on the graph. The following horizontal +rules are defined in F for all rrgraph views: + + + + + + + + + + +=item * C + +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: CnameE> +determines the order of drawing. Negative order numbers correspond to +the lines or areas behind the data line. CnameE> +gives the RPN expression that defines the line or area. +CnameE> and CnameE> define +the style (AREA or LINE1..3) and the color of the drawing. +Node parameter C disables the decorations. + +=item * C, C, C + +Optional. These parameters define the printing of values together with legends +below the graph. C is a comma-separated list of format names, +and for each format name, there should be a corresponding C +parameter. C defines a string that will be printed on top of +all orther lines. Example: + + + + + + + + +=item * C + +Optional. Defines the text description of the graph. This description is +usually placed as ALT HTML attribute in the generated HTML pages. + +=item * C + +Optional. Supplies additional RRDtool graph comand-line options, as one +string separated by spaces. + +=back + +=item * C + +This view produces the text output from PRINT statement in +RRD graph command. The required parameters are C and C. +The first one defines the starting time. C may be also optionally +specified. + +C 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, C, C + +When set to C, 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>. + + + + + + + + + + + + + + + + + + + +When processed the example above effectivly becomes: + + + + + + + + + + + + + + + + + + + +Schema definitions can be modified in two ways +(see the I 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 is a symbolic identifier for each subtree or a leaf. + +A I 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 Ctoken-setsE> +XML element: + + + + + + + + + + + + + + + + +Parameter C 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 + +Determines the view for displaying the tokenset contents. + +=item * C + +The text that describes this tokenset. + +=back + +=head2 Monitor definitions + +I is a named set of parameters that defines the behaviour +of monitor module. Each leaf can be given a number of monitors +via C parameter. + +Upon monitor module run, an I is launched if the alarm conditions +of a given monitor are satisfied. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +=head3 Event types + +Should the alarm condition occur, a series of events is happening +in sequentional order: + +=over 4 + +=item * C + +This event type occurs the first time the alarm condition is met. + +=item * C + +This event type means that the alarm condition still persists +after the previous run of Monitor. + +=item * C + +Event of this type happens when the alarm condition stops. + +=item * C + +Once the alarm is cleared, this event happens after the expiration +time of the monitor. + +=back + +=head3 Monitor parameters + +=over 4 + +=item * C + +Mandatory parameter. Specifies the monitor type. The following monitor +types are recognized: + +=over 8 + +=item * C + +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 + +Triggers the action when given RPN expression returns nonzero. +See I manual for more details. +This monitor type implies that the RPN expression is specified in +C parameter. The current leaf value is prepended to the given RPN. + +=back + +=item * C + +Mandatory for monitor type C. 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 parameter. + +=item * C + +Mandatory parameter, comma-separated list of action names (spaces +are allowed). Each action is triggered when the alarm condition is met. + +=item * C + +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 + +Optional but recommended parameter, specifies the string identifying +the event that this monitor watches. + +=item * C + +Optional severity level. Used for the action type C. + +=item * C + +Optional RPN expression for transforming the datasource value. +If defined, it will be applied to the value before setting +C and C environment variables. + +=item * C + +Optional I format for displaying the value in +C environment variable. Default is C<%.2f>. + +=back + + +=head3 Action parameters + +=over 4 + +=item * C + +Mandatory parameter, defines the type of action. Recognized +values are: + +=over 8 + +=item * C + +When this type of action is triggered, the leaf is added to the specified +tokenset (see I section in this manual). +The leaf persists in the tokenset until the event of type C. +This action type implies the parameter C. + +=item * C + +This action type defines an external program to launch. Two other parameters +determinate its behaviour: mandatory C and optional C. + +=back + +=item * C + +Mandatory for action type C. Defines the tokenset name +where the leaf is added when the monitor condition is met. + +=item * C + +Mandatory for action type C. Defines the external program to launch. +The following strings are substituted in the parameter value: + +=over 8 + +=item * Cgt;> + +Relaced with C>. + +=item * Clt;> + +Relaced with C>. + +=back + +The following environment variables are passed to the child process: + +=over 8 + +=item * C<$TORRUS_HOME> + +C 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 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 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 expression. + +=item * C<$TORRUS_DISPLAY_VALUE> + +For expression monitor type, it contains a human-readable form +of the value, possibly transformed by C expression. + +=item * C<$TORRUS_SEVERITY> + +If the C parameter is defined in the monitor, its value +is passed with this variable. + +=back + +=item * C + +Optional for action type C. The comma-separated list of event +types when the given action should be launched. If not defined, +the event type C is used by default. + +=item * C + +Optional for action type C. 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 + +Optional for action type C. Comma-separated list of C +pairs. C defines the environment variable name: it is prefixed with +C. C 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: + + + + + + + /usr/local/bin/report_temperature + + + + + + + + + + + + + +=back + + +=head1 Author + +Copyright (c) 2002-2005 Stanislav Sinyagin Essinyagin@yahoo.comE