torrus/doc/xmlconfig.pod.in

   1 #  xmlconfig.pod - Torrus configuration guide
   2 #  Copyright (C) 2002  Stanislav Sinyagin
   3 #
   4 #  This program is free software; you can redistribute it and/or modify
   5 #  it under the terms of the GNU General Public License as published by
   6 #  the Free Software Foundation; either version 2 of the License, or
   7 #  (at your option) any later version.
   8 #
   9 #  This program is distributed in the hope that it will be useful,
  10 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 #  GNU General Public License for more details.
  13 #
  14 #  You should have received a copy of the GNU General Public License
  15 #  along with this program; if not, write to the Free Software
  16 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  17
  18 # $Id: xmlconfig.pod.in,v 1.1 2010-12-27 00:04:34 ivan Exp $
  19 # Stanislav Sinyagin <ssinyagin@yahoo.com>
  20 #
  21 #
  22
  23 =head1 Torrus XML Configuration Guide
  24
  25 =head2 Common rules
  26
  27 The Torrus configuration consists of several XML files.
  28 Once the XML configuration is changed, it must
  29 be compiled into the database by executing C<torrus compilexml>.
  30 In addition, when I<Renderer>, I<Collector> and I<Monitor> processes
  31 notice the configuration changes, they refresh their information automatically.
  32
  33 The top-level XML element is always C<E<lt>configurationE<gt>>, with
  34 sub-elements defining various sections, like datasources or views:
  35
  36   <configuration>
  37
  38     <!-- Optional inclusion of other XML files -->
  39     <include filename="myconfig.xml"/>
  40
  41     <datasources>
  42       <!-- Data sources tree definition -->
  43       ...
  44     </datasources>
  45     <views>
  46       <!-- View definitions -->
  47       ...
  48     </views>
  49     <token-sets>
  50       <!-- Token sets definitions ->
  51       ...
  52     </token-sets>
  53     <monitors>
  54       <!-- Monitor definitions ->
  55       ...
  56     </monitors>
  57   </configuration>
  58
  59 Multiple XML files are interpreted in additive matter, i.e.
  60 C<E<lt>datasourcesE<gt>> section from one file is concatenated with
  61 the corresponding sections of previous files. If the same
  62 parameter is defined for the same subtree in several input files,
  63 the last processed value gets into the configuration.
  64
  65 Additional XML files may be added to the compilation list by means of
  66 C<E<lt>includeE<gt>> statement. They will be processed recursively
  67 before the content of the XML file they are referenced from.
  68 The argument C<filename> determines the
  69 name of the file in standard XML files directory.
  70 It is safe to include the same file several times,
  71 Torrus compiler guarantees that files are only processed once.
  72
  73 Some kinds of sections, like C<E<lt>datasourcesE<gt>>, allow to
  74 define the same elements two or more times. In this case,
  75 the previous parameter values are overridden by the new values.
  76
  77 Each component of the configuration is defined by the set of I<parameters>.
  78 They are specified in a common manner, differentiating in parameter names only:
  79
  80   <view name="default-rrd-html">
  81     <param name="view-type"     value="html" />
  82     <param name="expires"       value="300" />
  83     <param name="html-template" value="default-rrd.html" />
  84   </view>
  85
  86 The parameter value can be specified either by C<value> XML attribute,
  87 or by the text contents of the C<E<lt>paramE<gt>> element.
  88
  89 Some parameter values require other parameters to be defined, like in the
  90 above example: a view of type C<html> cannot exist without a template.
  91
  92 After I<all> XML files are compiled, the parameters are checked for validity
  93 by the compiler.
  94
  95 =head2 Character sets
  96
  97 By default, all XML input is treated as UTF-8 (unicode). This is important
  98 because all the HTML output generated by Torrus is encoded UTF-8.
  99
 100 However, you may use Latin1 (ISO-8859-1) encoding in your XML files.
 101 In order to ensure correct displaying of non-ASCII characters,
 102 the encoding must be specified in your XML files:
 103
 104   <?xml version="1.0" encoding="ISO-8859-1"?>
 105
 106 You need this only in those files containing non-ASCII characters
 107 in Latin1 encoding.
 108
 109 In addition, version C<1.54_3> or higher of C<XML::LibXML> is required, and
 110 Torrus version 0.0.16 or above.
 111
 112
 113 =head2 Macros
 114
 115 In the top level of the configuration tree, a number of macros may be defined.
 116 Currently they are used in C<snmp-object> parameter only.
 117 Macros are specified with C<E<lt>defE<gt>> elements, being the direct
 118 children of C<E<lt>definitionsE<gt>> element:
 119
 120   <configuration>
 121     <definitions>
 122       <!-- IF-MIB:ifTable  -->
 123       <def name="ifDescr"           value="1.3.6.1.2.1.2.2.1.2" />
 124       <def name="ifPhysAddress"     value="1.3.6.1.2.1.2.2.1.6" />
 125       <def name="ifInOctets"        value="1.3.6.1.2.1.2.2.1.10" />
 126       <def name="ifInUcastPkts"     value="1.3.6.1.2.1.2.2.1.11" />
 127       <def name="ifInErrors"        value="1.3.6.1.2.1.2.2.1.14" />
 128       <def name="ifOutOctets"       value="1.3.6.1.2.1.2.2.1.16" />
 129       <def name="ifOutUcastPkts"    value="1.3.6.1.2.1.2.2.1.17" />
 130       <def name="ifOutErrors"       value="1.3.6.1.2.1.2.2.1.20" />
 131
 132       <!-- Default Interface index lookup -->
 133       <def name="IFIDX"         value="M($ifDescr, %interface-name%)" />
 134     </definitions>
 135     ...
 136
 137 These definitions are global across all XML configuration files,
 138 and are referenced with dollar sign and the definition name, e.g.:
 139
 140     <leaf name="ifInErrors">
 141       <param name="snmp-object" value="$ifInErrors.$IFIDX" />
 142       ...
 143
 144
 145 =head2 Parameter properties
 146
 147 Some parameters require special handling during the compilation or
 148 at the runtime. The parameter properties define such behaviour in the
 149 XML configuration.
 150
 151 Currently two properties are recognized: "remspace" and "expand".
 152
 153   <configuration>
 154     <param-properties>
 155       <!-- Parameters where space is removed from values -->
 156       <prop param="action"             prop="remspace" value="1"/>
 157       <prop param="display-rpn-expr"   prop="remspace" value="1"/>
 158       <prop param="ds-names"           prop="remspace" value="1"/>
 159       ...
 160     </param-properties>
 161
 162
 163
 164 =head2 Datasource definitions
 165
 166 Datasources are organized into a tree hierarchy. All parameters are inherited
 167 by the subtrees and leafs from their parents, and can be overridden on
 168 lower levels.
 169
 170 The datasources tree consists of two key types of components:
 171 I<subtree> and I<leaf>. A subtree can have child subtrees or leaves.
 172 A leaf can never have children. A subtree represents logical aggregation,
 173 while the leaf always represends the actual datasource.
 174
 175 In XML configuration, a child subtree or leaf belongs to the parent
 176 element, like the following:
 177
 178   <datasources>
 179     <!-- This is the first child of the tree root -->
 180     <subtree name="Netflow">
 181       <param name="ds-type" value="rrd-file" />
 182       <param name="comment"
 183              value="Netfow data collected by FlowScan with CarrierIn.pm" />
 184       <!-- All Flowscan-generated files reside here -->
 185       <param name="data-dir" value="/var/local/flowscan/graphs" />
 186       <subtree name="Exporters">
 187         <param name="comment" value="Netflow exporting devices" />
 188         ...
 189         <!-- all exporters defined here -->
 190       </subtree>
 191        ...
 192       <subtree name="Total">
 193         <param name="data-file" value="total.rrd" />
 194         <leaf name="bps">
 195           <param name="comment" value="Bits per second" />
 196           <param name="leaf-type" value="rrd-def" />
 197           <param name="rrd-ds" value="bits" />
 198           <param name="rrd-cf" value="AVERAGE" />
 199         </leaf>
 200         <leaf name="pps">
 201           <param name="comment" value="Packets per second" />
 202           <param name="leaf-type" value="rrd-def" />
 203           <param name="rrd-ds" value="pkts" />
 204           <param name="rrd-cf" value="AVERAGE" />
 205         </leaf>
 206         <leaf name="packlen">
 207           <param name="comment" value="Average packet length in bytes" />
 208           <param name="leaf-type" value="rrd-cdef" />
 209           <param name="rpn-expr" value="{bps},8,/,{pps},/" />
 210         </leaf>
 211       </subtree>
 212     </subtree>
 213   </datasources>
 214
 215
 216 Each subtree or a leaf is identified by a I<path>, the symbolic
 217 notation similar to filesystem paths. In any path notation,
 218 subtree names always end with slash (/), and this trailing slash is
 219 the part of the name. In this case, any subtree is identified by a path
 220 ending with slash, while leaf paths always end with a word symbol.
 221 The top-level subtree is identified by a single slash.
 222
 223 The other components of the datasouce definition are I<templates> and
 224 I<aliases>.
 225
 226 =head3 Templates
 227
 228 A template is used when it's needed to define multiple different pieces of
 229 the configuration in the same way. For instance, the definition for
 230 input/output octets and bits can be specified once in a template,
 231 and then applied where appropriate.
 232
 233 The piece of XML configuration inside the C<E<lt>templateE<gt>>
 234 element is memorized under the template name, and reproduced
 235 in every occurrence of C<E<lt>apply-templateE<gt>> with the corresponding
 236 template name. The template definition must be the direct child
 237 element of C<E<lt>configurationE<gt>> XML element:
 238
 239   <datasources>
 240     <!-- Default views must be defined -->
 241     <param name="default-subtree-view" value="default-dir-html" />
 242     <param name="default-leaf-view" value="default-rrd-html" />
 243
 244     <!-- Many of our RRDs have the field "bits" - let's define it here -->
 245     <template name="bps">
 246       <leaf name="bps">
 247         <param name="comment" value="Bits per second" />
 248         <param name="leaf-type" value="rrd-def" />
 249         <param name="rrd-ds" value="bits" />
 250         <param name="rrd-cf" value="AVERAGE" />
 251       </leaf>
 252     </template>
 253     ...
 254       <subtree name="Total">
 255         <param name="data-file" value="total.rrd" />
 256         <apply-template name="bps" />
 257         <leaf name="pps">
 258           <param name="comment" value="Packets per second" />
 259           <param name="leaf-type" value="rrd-def" />
 260           <param name="rrd-ds" value="pkts" />
 261           <param name="rrd-cf" value="AVERAGE" />
 262         </leaf>
 263         <leaf name="packlen">
 264           <param name="comment" value="Average packet length in bytes" />
 265           <param name="leaf-type" value="rrd-cdef" />
 266           <param name="rpn-expr" value="bps,8,/,pps,/" />
 267         </leaf>
 268       </subtree>
 269
 270
 271 =head3 Aliases
 272
 273 Alias is the alternative symbolic name for a subtree or a leaf.
 274 It can be even a name from a different subtree hierarchy.
 275 If that alternative hierarchy does not exist, the corresponding
 276 subtrees are created:
 277
 278   <subtree name="62.3.44.55">
 279     <alias>/Netflow/ExportersByName/rtrTelehouse1/</alias>
 280     ...
 281
 282 =head3 Compile-time variables
 283
 284 Compile-time variables are those defined somewhere in datasource hierarchy,
 285 and valid within a given subtree and its children. It is possible to define
 286 pieces of XML configuration which are or are not compiled, depending on the
 287 value of corresponding variable.
 288
 289 Variables are set by C<setvar> XML element, with mandatory attributes
 290 C<name> and C<value>.
 291
 292 Variable values are used in C<iftrue> and C<iffalse> XML elements.
 293 Mandatory parameter C<var> specifies the variable name. The child XML elements
 294 are compiled if the variable value is true or false, correspondingly.
 295 A true value is C<true> or a nonzero number. Undefined variable is identified
 296 as false.
 297
 298 Example:
 299
 300   <template name="cisco-cbqos-classmap-meters">
 301   ...
 302     <iftrue var="CiscoIOS_cbQoS::CMNoBufDrop">
 303       <leaf name="Dropped_No_Buffer">
 304       ...
 305       </leaf>
 306     </iftrue>
 307   </template>
 308
 309   <subtree name="QoS_Stats">
 310     <setvar name="CiscoIOS_cbQoS::CMNoBufDrop" value="true"/>
 311     ....
 312   </subtree>
 313
 314
 315 =head3 Parameter value substitution
 316
 317 For any given leaf, some parameters may reference the other parameter values,
 318 by embracing the parameter name with percent signs:
 319
 320    <param name="data-file" value="%snmp-host%_hostaverages.rrd" />
 321
 322 The parameter substitution is performed at runtime. The substitution formula
 323 may be defined at a higher subtree level, and the substitution itself will
 324 occur at leaf level.
 325
 326 The parameter substitution is performed only to those paraneters
 327 which are defined with the property "expand".
 328
 329 =head3 Common parameters
 330
 331 =over 4
 332
 333 =item * C<ds-type>
 334
 335 Mandatory parameter for every datasource leaf. Currently, the following values
 336 are recongized:
 337
 338 =over 8
 339
 340 =item * C<rrd-file>
 341
 342 The datasource is an RRD file generated by some external collector.
 343 Implies mandatory parameters: C<data-dir>, C<data-file>, C<leaf-type>.
 344
 345 =item * C<collector>
 346
 347 The datasource is generated by Torrus Collector.
 348 Implies mandatory parameters: C<collector-type>, C<storage-type>,
 349 C<collector-period>, C<collector-timeoffset>.
 350
 351 =item * C<rrd-multigraph>
 352
 353 This leaf is dedicated to displaying of multiple
 354 other datasources in one graph. It cannot be referenced for any
 355 other purpose, because there's no numeric value associated with it.
 356
 357 =back
 358
 359 =item * C<nodeid>
 360
 361 Optional. If defined, it should contain a unique string identifying
 362 this particular leaf or subtree.
 363
 364
 365 =item * C<node-display-name>
 366
 367 Optional. If defined, it overrides the subtree or leaf name for displaying.
 368 The subtree and leaf names are not allowed to have spaces and special
 369 characters, and this parameter helps to display strings as they are, such as
 370 router interface names.
 371
 372
 373 =item * C<comment>
 374
 375 Optional. This is a string of text which is displayed when browsing through
 376 the tree.
 377
 378 =item * C<help-text>
 379
 380 Optional. This parameter is not inherited by child nodes. If defined,
 381 the user is offered a I<Help> shortcut in the given subtree or view.
 382 It allows to open a new window with the help text displayed, together with
 383 the current path. Some simple markup is allowed in the text, in a format
 384 of Template-Toolkit tool:
 385 C<[%em('some text')%]> would be displayed in italics, and
 386 C<[%strong('some text')%]> would be bold.
 387
 388 =item * C<monitor>
 389
 390 Optional. Comma-separated list of monitor names (spaces are allowed) that
 391 must be run upon periodic runs of monitor module (see I<Monitor definitions>
 392 section of this manual). Monitor schedule parameters must be defined
 393 for the monitor to run properly: C<monitor-period> and C<monitor-timeoffset>.
 394
 395 =item * C<monitor-period>, C<monitor-timeoffset>
 396
 397 Mandatory parameters for leaves that have C<monitor> defined.
 398 They define the monitor schedule for each individual datasource.
 399 The time for execution is determined by formula:
 400
 401    time + period - (time mod period) + timeoffset
 402
 403 =item * C<monitor-vars>
 404
 405 Required if one or more monitors requires the variables. In monitor's
 406 RPN expressions, the variables are referenced as C<#varname>. These
 407 variables are looked up in the leaf's C<monitor-vars> parameter.
 408 The syntax of this parameter is semicolon-delimited C<name=value> pairs:
 409
 410   <param name="monitor-vars" value="min=300000;max=1000000"/>
 411
 412 =item * C<monitor-action-target>
 413
 414 Optional. Specifies a reference to an alternative leaf which will be used
 415 for the monitor action. For example, you might need to see a multigraph
 416 leaf in the tokenset instead of one single datasource.
 417
 418 =item * C<precedence>
 419
 420 Optional. Default value: C<0>. When rendering, the subtree listing is
 421 sorted according to precedence and alphabetic order of names.
 422 The higher the precedence, the closer to the top of the list
 423 the child node is displayed.
 424
 425 =item * C<legend>
 426
 427 Optional. If given, produces a short listing at the top of the HTML output,
 428 with tabulated values. Format: C<Category1:Value1; Category2:Value2...>.
 429 Spaces around the delimiters are ignored.
 430
 431 Example:
 432
 433   <subtree name="rtrZurich1">
 434     <param name="legend">
 435       Location:Zurich;
 436       Contact: John Smith;
 437       Telephone: 01 9911299
 438     </param>
 439
 440 =item * C<graph-title>
 441
 442 A horizontal string at the top of the graph.
 443
 444 =item * C<graph-legend>
 445
 446 Optional. This legend text is printed inside the graph explaining
 447 the line color.
 448
 449 =item * C<vertical-label>
 450
 451 Optional. Text to print along Y axsis on the graph.
 452
 453 =item * C<graph-lower-limit>, C<graph-upper-limit>
 454
 455 Optional. Fix the upper and lower boundaries of the graph.
 456
 457 =item * C<graph-rigid-boundaries>
 458
 459 Optional. When set to "yes", the graph will not expand if the value is outside
 460 the lower or upper limit.
 461
 462 =item * C<rrd-scaling-base>
 463
 464 Optional. Valid values are: "1000" and "1024". Default: "1000".
 465 Determines the base for kilo-, mega-, and giga- scaling factor.
 466 Normally it should be 1000 for traffic counters, and 1024 for memory
 467 or storage sizes.
 468
 469 =item * C<graph-logarithmic>
 470
 471 Optional. When set to "yes", the graph is drawn in logarithmic y-axis scale.
 472
 473 =item * C<line-style>, C<line-color>
 474
 475 These optional parameters override the corresponding ones from the view
 476 definition.
 477
 478 =item * C<default-subtree-view>, C<default-leaf-view>
 479
 480 Mandatory. Determine the default view for a leaf or subtree, correspondingly.
 481 See I<View definitions> section of this manual.
 482
 483 =item * C<rrgraph-views>
 484
 485 Mandatory. Defines 5 views to display the graphs. Must contain 5
 486 comma-delimited view names for short-period, daily, weekly, monthly,
 487 and yearly view.
 488
 489 =item * C<tokenset-member>
 490
 491 Optional. Adds this leaf or this subtree child leaves to the specified
 492 token sets. Tokenset names are comma-separated, and must be defined in
 493 C<E<lt>token-setsE<gt>> part of configuration.
 494
 495 =item * C<descriptive-nickname>
 496
 497 Optional. If defined, it is used in tokenset members listing as a member
 498 identifier, instead of the leaf path.
 499
 500 =item * C<hidden>
 501
 502 Optional. Valid values: C<yes>, C<no>.
 503 When set to C<yes>, the leaf or subtree is not
 504 displayed in the subtree listing,
 505 unless C<SHOWHIDDEN> option is true. When C<SHOWHIDDEN> is enabled,
 506 the node name and comment are shown in italics.
 507
 508 =item * C<has-overview-shortcuts>, C<overview-shortcuts>,
 509 C<overview-subleave-name-X>, C<overview-shortcut-text-X>,
 510 C<overview-shortcut-title-X>, C<overview-page-title-X>,
 511 C<overview-direct-link-X>, C<overview-direct-link-view-X>
 512
 513 When C<has-overview-shortcuts> is set to C<yes> on a subtree level,
 514 default HTML templates expect the five parameters to be set.
 515 C<overview-shortcuts> is a comma-separated list of shortcut names,
 516 and for each name "X", C<overview-subleave-name-X> defines the
 517 current subtree's grandchild leaves name which would compose the overview page.
 518 When C<overview-direct-link-X> is set to C<yes>, the URL under the
 519 graph will point to the direct child subtree, and
 520 C<overview-direct-link-view-X> will define the view for that subtree.
 521 Usually this view would be C<expanded-dir-html>.
 522
 523 =item * C<ignore-lower-limit>, C<ignore-upper-limit>, C<ignore-limits>
 524
 525 Optional. When set to C<yes>, they make the renderer ignore
 526 C<graph-lower-limit>, C<graph-upper-limit>, or both, accordingly.
 527 In addition, C<ignore-limits> disables the C<graph-rigid-boundaries>
 528 parameter.
 529
 530 =item * C<graph-ignore-decorations>
 531
 532 Optional. When set to C<yes>, the view C<decorations> are ignored.
 533
 534 =item * C<graph-disable-gprint>
 535
 536 Optional. When set to C<yes>, the view parameter C<gprint-values> and other
 537 GPRINT-related parameters are ignored.
 538
 539 =item * C<hrule-legend-I<name>>
 540
 541 Optional. If a horizontal rule with the given name is defined, this parameter
 542 specifies the legend to be printed.
 543
 544 =item * C<searchable>
 545
 546 Optional. If set to C<yes>, the corresponding subtree or leaf is included
 547 in the search database.
 548
 549 =back
 550
 551
 552 =head3 RRD-related parameters
 553
 554 =over 4
 555
 556 =item * C<data-dir>
 557
 558 Mandatory. Specifies the filesystem directory
 559 path where the data files are resided.
 560
 561 =item * C<data-file>
 562
 563 Mandatory. Name of the data file.
 564
 565 =item * C<leaf-type>
 566
 567 Mandatory. Determines the type of RRD access. Recognized values are:
 568
 569 =over 8
 570
 571 =item * C<rrd-def>
 572
 573 Corresponds to DEF specification in RRDgraph query. Implies two mandatory
 574 parameters: C<rrd-ds> and C<rrd-cf>, giving the DS name and consolidation
 575 function, correspondingly.
 576
 577 =item * C<rrd-ds>
 578
 579 Mandatory when a leaf refers to an RRD file (C<storage-type=rrd> in
 580 C<collector> leaves or C<leaf-type=rrd-def> in C<rrd-file> leaves). The
 581 parameter Specifies the RRD datasource name within a file.
 582
 583 =item * C<rrd-ds>
 584
 585 Mandatory when a leaf refers to an RRD file (C<storage-type=rrd> in
 586 C<collector> leaves or C<leaf-type=rrd-def> in C<rrd-file> leaves). The
 587 parameter Specifies the RRD datasource name within a file.
 588
 589 =item * C<rrd-cf>
 590
 591 Mandatory under the same conditios as C<rrd-ds>. Defines the default
 592 consolidation function which is used when retrieving the RRD data.
 593
 594 =item * C<rrd-cdef>
 595
 596 Supported for C<ds-type=rrd-file> only.
 597 Corresponds to CDEF specification in RRDgraph query. Implies one
 598 mandatory parameter: C<rpn-expr>, which gives the RPN expression.
 599 Other leaves' value references are specified in curly braces. These leaves
 600 can be specified as relative or absolute paths in the configuration tree.
 601 See I<RPN expressions in Torrus> manual for more details.
 602
 603 =back
 604
 605 =item * C<rrd-hwpredict>
 606
 607 Optional. If equals to C<enabled>, then this RRD datasource
 608 is expected to have HWPREDICT and all the suite of
 609 Holt-Winters consolidation functions.
 610 In case of C<ds-type=collector>, C<rrd-hwpredict=enabled> indicates
 611 that the RRD file must be created with use of Holt-Winters RRAs.
 612
 613 =item * C<rrd-create-dstype>
 614
 615 Mandatory when C<ds-type=collector> and C<storage-type=rrd>.
 616 Specifies the datasource type for RRD creation. Valid values are:
 617 C<GAUGE>, C<COUNTER>, C<DERIVE>, C<ABSOLUTE>.
 618
 619 =item * C<rrd-create-rra>
 620
 621 Mandatory when C<ds-type=collector> and C<storage-type=rrd>.
 622 Space-separated list of RRA definitions for RRD creation, as they
 623 are passed to RRD Create command.
 624 Example:
 625
 626     <!-- Round-robin arrays to be created, separated by space.
 627      In this example, we keep 5-minute details for 2 weeks,
 628      30-minute average and maximum details for 6 weeks,
 629      and 1-day aggregated stats for 2 years -->
 630     <param name="rrd-create-rra">
 631       RRA:AVERAGE:0.5:1:4032
 632       RRA:AVERAGE:0.5:6:2016     RRA:MAX:0.5:6:2016
 633       RRA:AVERAGE:0.5:288:732    RRA:MAX:0.5:288:732
 634     </param>
 635
 636 =item * C<rrd-create-heartbeat>
 637
 638 Mandatory when C<ds-type=collector> and C<storage-type=rrd>.
 639 Heartbeat parameter as defined in RRD Create manual page.
 640
 641 =item * C<rrd-create-min>, C<rrd-create-max>
 642
 643 Optional minimum and maximum parameters for RRD datasource.
 644
 645 =item * C<rrd-create-hw-rralen>
 646
 647 Mandatory when C<ds-type=collector> and C<storage-type=rrd>
 648 and C<rrd-hwpredict=enabled>. Specifies the RRA length for
 649 Holt-Winters archives. Recommended same length as main 5-minutes RRA.
 650
 651 =item * C<rrd-create-hw-season>, C<rrd-create-hw-alpha>,
 652   C<rrd-create-hw-beta>, C<rrd-create-hw-gamma>,
 653   C<rrd-create-hw-winlen>, C<rrd-create-hw-failth>
 654
 655 Optional Holt-Winters parameters. Default values are:
 656
 657         season=288
 658         alpha=0.1, beta=0.0035, gamma=0.1,
 659         window_length=9, failure_threshold=6
 660
 661 =back
 662
 663 =head3 Collector-related parameters
 664
 665 =over 4
 666
 667 =item * C<collector-type>
 668
 669 Mandatory parameter for datasource type C<collector>. Currently supported
 670 values are: C<snmp> and C<cdef>. Other valid values may be added with plugins.
 671
 672 =item * C<storage-type>
 673
 674 Mandatory parameter for datasource type C<collector>. Comma-separated list
 675 of storage types. The collected value is duplicated on every storage listed.
 676 Supported values are: C<rrd>, C<ext>. For C<ext> (external storage),
 677 see the I<Reporting Setup Guide>.
 678
 679 =item * C<collector-period>, C<collector-timeoffset>
 680
 681 Mandatory parameters for datasource type C<collector>.
 682 They define the collector schedule for each individual datasource.
 683 The time for execution is determined by formula:
 684
 685    time + period - (time mod period) + timeoffset
 686
 687 =item * C<collector-dispersed-timeoffset>
 688
 689 Optional. When set to C<yes>, C<compilexml> spreads the collector offsets
 690 among values determined from C<collector-timeoffset-min>,
 691 C<collector-timeoffset-max>, C<collector-timeoffset-step>,
 692 and C<collector-timeoffset-hashstring>.
 693
 694 =item * C<collector-timeoffset-min>,
 695 C<collector-timeoffset-max>, C<collector-timeoffset-step>
 696
 697 Mandatory when C<collector-dispersed-timeoffset> is set to C<yes>.
 698 They define the limits and the step for collector timeoffset dispersion.
 699
 700 =item * C<collector-timeoffset-hashstring>
 701
 702 Mandatory when C<collector-dispersed-timeoffset> is set to C<yes>.
 703 Defines the string that is used as a hash for timeoffset dispersion.
 704
 705 =item * C<collector-instance-hashstring>
 706
 707 Mandatory.
 708 Defines the string that is used as a hash to calculate the collector
 709 instance number for a particular leaf.
 710 By default it is defined as C<%system-id%>, so that
 711 the same collector instance deals with every remote system.
 712
 713 =item * C<collector-instance>
 714
 715 Mandatiry. The parameter defines the collector instance number.
 716 This parameter is automatically calculated by the configuration compiler.
 717
 718 =item * C<transform-value>
 719
 720 Optional. Defines a piece of Perl code that will be used for value
 721 transformation. The keyword C<DOLLAR> is replaced with the dollar sign ($),
 722 and C<MOD> is replaced with the percent sign (%).
 723 The initial value is supplied in C<$_>, which should be referenced as
 724 C<DOLLAR_> in your Perl code.
 725 The code should return a numeric value or C<U> for an undefined
 726 value. The returned value is then passed to the storage.
 727 The parameter substititions are performed on the value of the
 728 parameter, therefore it should not contain the percent(%) and dollar ($) signs.
 729
 730 =item * C<value-map>
 731
 732 Optional. Collector may return values which need translation into
 733 numbers. This parameter defines the mapping for such values. The
 734 parameter value is a comma-separated list of C<value:number> pairs.
 735
 736
 737 =item * C<collector-scale>
 738
 739 Optional. Specifies the translation RPN formula for the data before
 740 being passed to RRD database. Implicitly the datasource value is appended
 741 to the left of the given RPN. I<Warning:> the translation works I<before>
 742 the RRDtool processes the data, so it makes sence to scale only non-COUNTER
 743 values.
 744
 745 =item * C<snmp-ipversion>
 746
 747 Mandatory for C<collector-type=snmp>. Valid values are C<4> and C<6>. The
 748 parameter defines the IP protocol version. If C<snmp-host> contains a DNS
 749 name, the IP address is determined by looking up A or AAAA DNS records,
 750 according to IP version.
 751
 752 =item * C<snmp-transport>
 753
 754 Mandatory for C<collector-type=snmp>. Valid values are C<tcp> and C<udp>.
 755
 756
 757 =item * C<snmp-host>
 758
 759 Mandatory when C<collector-type=snmp>. Specifies the hostname or IP address
 760 of the SNMP agent.
 761
 762 =item * C<snmp-port>
 763
 764 Mandatory when C<collector-type=snmp>. Specifies the UDP port of the
 765 SNMP agent.
 766
 767 =item * C<domain-name>
 768
 769 Optional DNS domain name. If given, and if C<snmp-host> does not contain
 770 dot symbol (.), this domain name is appended to C<snmp-host>.
 771
 772 =item * C<snmp-localaddr> and C<snmp-localport>
 773
 774 Optional parameters specifying the local socket binding address and port.
 775
 776 =item * C<snmp-version>
 777
 778 Mandatory when C<collector-type=snmp>. Specifies the SNMP version for the
 779 given device. Valid values are: C<1>, C<2c>, C<3>.
 780
 781 =item * C<snmp-community>
 782
 783 Mandatory when C<collector-type=snmp> and SNMP version is
 784 C<1> or C<2c>. Specifies the SNMP community for the given device.
 785
 786 =item * C<snmp-username>
 787
 788 Mandatory when C<collector-type=snmp> and SNMP version is C<3>.
 789
 790 =item * C<snmp-authkey>
 791
 792 Optional authentication key for SNMPv3. If not defined, the authentication
 793 level is set to C<noAuthNoPriv>. If only C<snmp-authkey> or
 794 C<snmp-authpassword> are specified, the security level is set to
 795 C<authNoPriv>. The security level is set to C<authPriv> if either
 796 of C<snmp-privkey> or C<snmp-privpassword> is defined.
 797
 798 =item * C<snmp-authpassword>
 799
 800 Optional authentication password for SNMPv3. See notes for C<snmp-authkey>
 801 parameter.
 802
 803 =item * C<snmp-authprotocol>
 804
 805 Optional authentication protocol for SNMPv3. Valid values: C<md5> or C<sha>.
 806 Default is C<md5>.
 807
 808 =item * C<snmp-privkey>
 809
 810 Optional privacy key for SNMPv3. If defined, C<snmp-authkey> or
 811 C<snmp-authpassword> must be defined too.
 812
 813 =item * C<snmp-privpassword>
 814
 815 Optional privacy password for SNMPv3. If defined, C<snmp-authkey> or
 816 C<snmp-authpassword> must be defined too.
 817
 818 =item * C<snmp-privprotocol>
 819
 820 Optional privacy protocol for SNMPv3. Valid values: C<des>, C<aes128cfb>,
 821 or C<3desede>. Default is C<des>.
 822
 823 =item * C<snmp-timeout>
 824
 825 Mandatory when C<collector-type=snmp>. Specifies the SNMP session timeout
 826 in seconds.
 827
 828 =item * C<snmp-retries>
 829
 830 Mandatory when C<collector-type=snmp>. Specifies the SNMP session retry count.
 831
 832 =item * C<snmp-oids-per-pdu>
 833
 834 Mandatory when C<collector-type=snmp>. Specifies the number of SNMP OIDs per
 835 one UDP packet.
 836
 837 =item * C<snmp-object>
 838
 839 Mandatory when C<collector-type=snmp>. Specifies the SNMP OID to be polled
 840 from the agent. The object must return a single numeric value.
 841
 842 In order to reference the dynamic instances, i.e. interface counters,
 843 two mapping types are supported: reverse mapping and variable value
 844 substitution.
 845
 846 Reverse mapping has syntax as follows:
 847
 848   M(baseoid, string)
 849
 850 The result of reverse mapping is the tail of the OID which has the head
 851 C<baseoid> and whose value equals the string.
 852
 853 Variable value substitution is defined by syntax:
 854
 855   V(oid)
 856
 857 The returned value must be a numeric value which is substituted in place
 858 of this expression.
 859
 860 =item * C<snmp-object-type>
 861
 862 Optional. Supported values: C<COUNTER64>, C<OTHER>. When set to C<COUNTER64>,
 863 the SNMP variable value is treated as 64-bit integer. Not using this
 864 parameter may lead to loss of precision.
 865
 866 =item * C<snmp-check-sysuptime>
 867
 868 Optional. Default value: C<yes>. When set to C<no>, the collector does not
 869 query C<SNMPv2-MIB::sysUpTime> (C<1.3.6.1.2.1.1.3.0>). By default,
 870 the uptime counter is used to detect if the agent was rebooted between
 871 the collector cycles. In this case the dynamic maps for the given host
 872 are automatically rebuilt. This parameter is needed for compatibility
 873 with some non-standard agents which don't implement this OID.
 874
 875 =item * C<snmp-max-msg-size>
 876
 877 Optional. If defined, it sets the SNMP maximum message size different from
 878 default 1472 octets (true for UDP/IPv4, see Net::SNMP documentation for more
 879 information).
 880
 881 =item * C<snmp-ignore-mib-errors>
 882
 883 Optional. If set to C<yes>, the SNMP errors C<noSuchObject>, C<noSuchInstance>,
 884 C<endOfMibView> are ignored, and no action is performed when such errors
 885 occur.
 886
 887 =item * C<system-id>
 888
 889 Mandatory for every collector type.
 890 Default value for SNMP collector: C<%snmp-host%>.
 891 Unique identifier of the host.
 892 This parameter is used in various template definitions for
 893 C<data-file>, C<descriptive-nickname> and C<collector-timeoffset-hashstring>.
 894
 895 =item * C<rpn-expr>
 896
 897 Mandatory when C<collector-type=cdef>. The RPN defines an arithmetic expression
 898 that is used to create a new datasource from several other ones. For example,
 899 it may define the sum of traffic on several different interfaces.
 900
 901 =item * C<cdef-collector-delay>
 902
 903 Mandatory when C<collector-type=cdef>. Defines the delay time in collector
 904 periods. The collector will read the data from the RPN datasources with the
 905 specified delay from the current time. F<cdef-collector-defs.xml> sets
 906 the default value to 0.
 907
 908 =item * C<cdef-collector-tolerance>
 909
 910 Mandatory when C<collector-type=cdef>. Delay time in collector periods that
 911 the collector accepts when no recent data is available.
 912 F<cdef-collector-defs.xml> sets the default value to 2.
 913
 914 =back
 915
 916
 917 =head3 RRD-Multigraph leaves
 918
 919 The leaves with C<ds-type=rrd-multigraph> are dedicated for
 920 displaying of several datasource values in one graph.
 921 Such leaves cannot be referenced for a numerical value, hence
 922 cannot be monitored.
 923
 924 Example:
 925
 926   <subtree name="SampleMulti">
 927     <leaf name="sample1">
 928       <param name="ds-type" value="rrd-multigraph" />
 929       <param name="ds-names" value="in,out" />
 930       <param name="foobarpath"
 931              value="/SNMP/Routers/213.230.38.4/FastEthernet0_0" />
 932
 933       <!-- parameter name tail is formed by the DS name -->
 934
 935       <param name="ds-expr-in"       value="{%foobarpath%/locIfInBitsSec}" />
 936       <param name="graph-legend-in"  value="Bits per second in" />
 937       <param name="line-style-in"   value="AREA" />
 938       <param name="line-color-in"   value="#00FF00" />
 939       <param name="line-order-in"    value="1" />
 940
 941       <param name="ds-expr-out"      value="{%foobarpath%/locIfOutBitsSec}" />
 942       <param name="graph-legend-out" value="Bits per second out" />
 943       <param name="line-style-out"   value="LINE2" />
 944       <param name="line-color-out"   value="#0000FF" />
 945       <param name="line-order-out"   value="2" />
 946
 947     </leaf>
 948   </subtree>
 949
 950 Parameters:
 951
 952 =over 4
 953
 954 =item * C<ds-names>
 955
 956 Comma-separated list of symbolic DS names. These names are
 957 used for other DS-specific parameter names formation.
 958 In the parameter descriptions below, C<X> stands for the DS name.
 959
 960 =item * C<ds-expr-X>
 961
 962 Datasource leaf RPN expression.
 963 Any other parameter values may be substituted as C<%parameter_name%>.
 964
 965 =item * C<graph-legend-X>
 966
 967 Short description text used as the graph legend.
 968
 969 =item * C<line-style-X>
 970
 971 Line specification in RRD graph. May be I<C<LINE1>>, I<C<LINE2>> etc.
 972 Two hashes in the beginning and a name refer to the line style from
 973 the styling profile, e.g. C<##BpsIn>.
 974
 975 =item * C<line-color-X>
 976
 977 Line color. Must have the hash symbol in the beginning, like I<C<#0000FF>>.
 978 Two hashes in the beginning and a name refer to the color from
 979 the styling profile, e.g. C<##BpsIn>.
 980
 981 =item * C<line-order-X>
 982
 983 Numerical order of line drawing. The lines are drawn in accending order.
 984 If omitted, the XML compiler issues warning, and Renderer conciders
 985 the order of 100.
 986
 987 =item * C<line-stack-X>
 988
 989 Optional. When set to C<yes>, the line is stacked on top of a previous line.
 990 Both areas and lines are stackable.
 991
 992 =item * C<line-alpha-X>
 993
 994 Optional. If specified, must be two hexademical, uppercase digits. This
 995 parameter defines the line (or area) transparency. Value C<FF> is
 996 equivalent to solid colour. Value C<7F> gives 50% transparency which should
 997 be suitable for most applications.
 998
 999 =item * C<ignore-views-X>
1000
1001 Optional comma-separated list of view names. The graph for this DS name
1002 will not be drawn in the views specified. The validator does not check
1003 it, so it's up to you to guarantee that at least one DS is always displayed
1004 in a multigraph.
1005
1006 =item * C<disable-gprint-X>
1007
1008 Optional. When set to C<yes>, this datasource is not included in GPRINT output.
1009
1010 =back
1011
1012 =head2 View definitions
1013
1014 In our context, I<view> means any kind of object representation.
1015 The same subtree or view can be displayed in different ways and in
1016 different formats: HTML, graph image, plain text, etc.
1017
1018 I<Renderer> module handles these view definitions. For any subtree
1019 or leaf, it renders the specified view, and keeps the cache of rendered
1020 files.
1021
1022 Each subtree or leaf must have a default view. This is controlled by
1023 two parameters that may be defined in the root subtree:
1024 C<default-subtree-view> and C<default-leaf-view>.
1025
1026 The set of views is flat, though they can inherit the parameters
1027 one from another. Each view is referenced by its name, and is
1028 defined by the set of parameters. Same way as with datasources,
1029 certain parameter values imply the neccessaty to define certain other
1030 parameters:
1031
1032   <views>
1033     <view name="default-rrgraph">
1034       <param name="view-type"     value="rrgraph" />
1035       <param name="expires"       value="300" />
1036       <param name="width"         value="500" />
1037       <param name="height"        value="250" />
1038       <param name="width-hint"    value="580" />
1039       <param name="line-style"    value="##SingleGraph" />
1040       <param name="line-color"    value="##SingleGraph" />
1041
1042       <!-- Daily graph, inherits parameters from the above -->
1043       <view name="last24h">
1044         <param name="start"         value="-24h" />
1045       </view>
1046
1047       <!-- Weekly graph -->
1048       <view name="lastweek">
1049         <param name="start"         value="-7d" />
1050       </view>
1051     </view>
1052   </views>
1053
1054 Currently the view is defined by the configuration only.
1055 Probably, in the future additional parameters will be supplied dynamically.
1056
1057
1058 =head3 View parameters
1059
1060 For every view, the mandatory parameters are:
1061
1062 =over 4
1063
1064 =item * C<view-type>
1065
1066 Determines the processing procedure which interprets the other parameters.
1067
1068 =item * C<expires>
1069
1070 Gives the expiration time in seconds for the I<Renderer> cache.
1071
1072 =back
1073
1074 The following values of C<view-type> are recognized:
1075
1076 =over 4
1077
1078 =item * C<html>
1079
1080 Defines the HTML representation of subtree or a leaf.
1081 One additional parameter is required: C<html-template> must contain a file
1082 name of the HTML template. Those templates are copied from F<templates>
1083 subdirectory of the installation package. We use Template-Toolkit
1084 E<lt>http://www.template-toolkit.orgE<gt> for HTML processing.
1085 The template file name is defined with the parameter C<html-template>.
1086
1087 The following
1088 variables and functions are defined when the template is processed:
1089
1090 =over 8
1091
1092 =item * C<token>
1093
1094 Returns the current node token.
1095
1096 =item * C<view>
1097
1098 Returns the name of the current view.
1099
1100 =item * C<path(token)>
1101
1102 Returns the full path name of the given node token.
1103
1104 =item * C<pathToken(path)>
1105
1106 Returns the token for the specified path.
1107
1108 =item * C<nodeExists(path)>
1109
1110 Returns true if the specified path points to a node.
1111
1112 =item * C<children(path)>
1113
1114 Returns the list of children for the given path.
1115
1116 =item * C<isLeaf(token)>
1117
1118 Returns true if the token is pointing to a leaf node.
1119
1120 =item * C<sortTokens(array)>
1121
1122 Returns the array of tokens, sorted according to C<precedence> parameter.
1123
1124 =item * C<nodeName(token)>
1125
1126 Returns the node name part of the node path.
1127
1128 =item * C<parent(token)>
1129
1130 Returns the parent's token for the specified node.
1131
1132 =item * C<nodeParam(token, param_name)>
1133
1134 Returns the value of the parameter for the given node.
1135
1136 =item * C<param(entity_name, param_name)>
1137
1138 Returns the value of the parameter for the given view, monitor, or action.
1139
1140 =item * C<url(token, [view])>
1141
1142 Returns the URL which displays the given node using the given view.
1143 If the view is omitted, use the default view.
1144
1145 =item * C<persistentUrl(token, [view])>
1146
1147 Same as above, but the URL is built from persistent information: nodeid
1148 (if available) or full path in the tree.
1149
1150 =item * C<splitUrls(token, [view])>
1151
1152 Returns a piece of HTML code representing the path with clickable
1153 node names, each referencing the corresponding view.
1154
1155 =item * C<rrprint(token, view)>
1156
1157 The specified view must be of type C<rrprint>. Returned is the text
1158 output produced by this view.
1159
1160 =item * C<scale(text)>
1161
1162 Interprets the given text as a floating-point number and returns
1163 its representation in the "metric" scale: 1000 is translated into "k",
1164 million into "M" etc. It may be used together with C<rrprint>
1165 for better formatting.
1166
1167 =item * C<tsetMembers(tset)>
1168
1169 Returns the array of the tokenset member tokens.
1170
1171 =item * C<tsetList>
1172
1173 Returns the array of the tokenset names.
1174
1175 =item * C<stylesheet>
1176
1177 Returns the relative URI to the default CSS stylesheet,
1178 as defined in C<$Torrus::Renderer::stylesheet>.
1179
1180 =item * C<version>
1181
1182 Returns current Torrus package version.
1183
1184 =back
1185
1186 =item * C<rrgraph>
1187
1188 Generates the RRD Graph representation of the given I<leaf> (remember,
1189 subtrees are only logical grouping of the real data).
1190
1191 The following parameters are mandatory for this kind of view:
1192
1193 =over 8
1194
1195 =item * C<width>, C<height>, C<start>
1196
1197 Correspond to same parameters in RRD Graph command.
1198 C<end> can also be given, it defaults to I<C<now>>.
1199
1200 =item * C<line-style>
1201
1202 Line specification in RRD graph. May be I<C<LINE1>>, I<C<LINE2>> etc.
1203 Two hashes in the beginning and a name refer to the line style from
1204 the styling profile, e.g. C<##SingleGraph>.
1205
1206 =item * C<line-color>
1207
1208 Line color. Must have the hash symbol in the beginning, like I<C<#0000FF>>.
1209 Two hashes in the beginning and a name refer to the color from
1210 the styling profile, e.g. C<##SingleGraph>.
1211
1212 =item * C<rrd-hwpredict>
1213
1214 If equals to C<disabled>, HWPREDICT display is disabled for this view.
1215 Note that if the datasource has C<rrd-hwpredict> parameter set to C<enabled>,
1216 this emplies that the view would contain Holt-Winters boundaries and failures
1217 graph.
1218
1219 =item * C<hw-bndr-style>
1220
1221 Optional parameter, defaults to C<LINE1>. Specifies the line style for
1222 Holt-Winters boundaries.
1223
1224 =item * C<hw-bndr-color>
1225
1226 Optional parameter, defaults to C<#FF0000>. Specifies the color for
1227 Holt-Winters boundaries.
1228
1229 =item * C<hw-fail-color>
1230
1231 Optional parameter, defaults to C<#FFFFA0>. Specifies the color for
1232 Holt-Winters failure ticks.
1233
1234 =item * C<hrules>, C<hrule-value-I<name>>, C<hrule-color-I<name>>
1235
1236 Optional parameter C<hrules> contains a comma-separated list of
1237 horizontal rule names. For each name, mandatory parameter
1238 C<hrule-value-I<name>> defines a name of the leaf parameter that will be
1239 used as the horizontal rule value. The rule is not drawn if such parameter
1240 is not defined for the leaf. Mandatory parameter C<hrule-color-I<name>>
1241 defines the color for the rule, of the form C<#DDDDDD>, where C<D> corresponds
1242 to a hexademical digit. Two hashes in the beginning and a name refer to
1243 the color from the styling profile, e.g. C<##HruleMin>.
1244 Optional parameter C<hrule-legend-I<name>>
1245 defines the legend text to be displayed on the graph. The following horizontal
1246 rules are defined in F<defaults.xml> for all rrgraph views:
1247
1248     <param name="hrules"            value="min,norm,max"/>
1249     <param name="hrule-color-min"   value="##HruleMin"/>
1250     <param name="hrule-value-min"   value="lower-limit"/>
1251     <param name="hrule-color-norm"  value="##HruleNormal"/>
1252     <param name="hrule-value-norm"  value="normal-level"/>
1253     <param name="hrule-color-max"   value="##HruleMax"/>
1254     <param name="hrule-value-max"   value="upper-limit"/>
1255
1256
1257 =item * C<decorations>
1258
1259 Optional. Comma-separated list of decoration names. Decoration is an RRD
1260 pseudo-line that does not depend on any datasource. For each decoration
1261 name, the following parameters must be supplied: C<dec-order-E<lt>nameE<gt>>
1262 determines the order of drawing. Negative order numbers correspond to
1263 the lines or areas behind the data line. C<dec-expr-E<lt>nameE<gt>>
1264 gives the RPN expression that defines the line or area.
1265 C<dec-style-E<lt>nameE<gt>> and C<dec-color-E<lt>nameE<gt>> define
1266 the style (AREA or LINE1..3) and the color of the drawing.
1267 Node parameter C<graph-ignore-decorations> disables the decorations.
1268
1269 =item * C<gprint-values>, C<gprint-header>, C<gprint-format-*>
1270
1271 Optional. These parameters define the printing of values together with legends
1272 below the graph. C<gprint-values> is a comma-separated list of format names,
1273 and for each format name, there should be a corresponding C<gprint-format-*>
1274 parameter. C<gprint-header> defines a string that will be printed on top of
1275 all orther lines. Example:
1276
1277     <param name="gprint-values"         value="current,average,max,min"/>
1278     <param name="gprint-header"
1279            value="Current    Average    Maximum    Minimum"/>
1280     <param name="gprint-format-current" value="LAST:%8.2lf%s"/>
1281     <param name="gprint-format-average" value="AVERAGE:%8.2lf%s"/>
1282     <param name="gprint-format-max"     value="MAX:%8.2lf%s"/>
1283     <param name="gprint-format-min"     value="MIN:%8.2lf%s"/>
1284
1285 =item * C<description>
1286
1287 Optional. Defines the text description of the graph. This description is
1288 usually placed as ALT HTML attribute in the generated HTML pages.
1289
1290 =item * C<rrd-params>
1291
1292 Optional. Supplies additional RRDtool graph comand-line options, as one
1293 string separated by spaces.
1294
1295 =back
1296
1297 =item * C<rrprint>
1298
1299 This view produces the text output from PRINT statement in
1300 RRD graph command. The required parameters are C<start> and C<print-cf>.
1301 The first one defines the starting time. C<end> may be also optionally
1302 specified.
1303
1304 C<print-cf> specifies oe or more consolidation functions, separated by comma.
1305 The result of the rendering is the text line with the output values
1306 separated by colon (:).
1307
1308 =back
1309
1310 =item * C<disable-legend>, C<disable-title>, C<disable-vertical-label>
1311
1312 When set to C<yes>, the corresponding elements of the graph are not displayed.
1313
1314
1315
1316 =head3 Styling Profiles
1317
1318 Styling profiles allow symbolic names to be used for line type
1319 and color.
1320
1321 Two hashes in the beginning and a name refer to the line style from
1322 the styling profile, e.g. C<##BpsIn>, C<##green>, C<##one>, C<##two>.
1323
1324       <leaf name="InOutBytes">
1325         <param name="comment" value="Input and Output bits per second graphs"/>
1326         <param name="ds-type" value="rrd-multigraph"/>
1327         <param name="ds-names" value="in,out"/>
1328         <!-- IN -->
1329         <param name="ds-expr-in" value="{ifInOctets}"/>
1330         <param name="graph-legend-in" value="Bytes per second in"/>
1331         <param name="line-style-in" value="##BpsIn"/>
1332         <param name="line-color-in" value="##BpsIn"/>
1333         <param name="line-order-in" value="1"/>
1334         <!-- OUT -->
1335         <param name="ds-expr-out" value="{ifOutOctets}"/>
1336         <param name="graph-legend-out" value="Bytes per second out"/>
1337         <param name="line-style-out" value="##BpsOut"/>
1338         <param name="line-color-out" value="##BpsOut"/>
1339         <param name="line-order-out" value="2"/>
1340       </leaf>
1341
1342 When processed the example above effectivly becomes:
1343
1344       <leaf name="InOutBytes">
1345         <param name="comment" value="Input and Output bits per second graphs"/>
1346         <param name="ds-type" value="rrd-multigraph"/>
1347         <param name="ds-names" value="in,out"/>
1348         <!-- IN -->
1349         <param name="ds-expr-in" value="{ifInOctets}"/>
1350         <param name="graph-legend-in" value="Bytes per second in"/>
1351         <param name="line-style-in" value="AREA"/>
1352         <param name="line-color-in" value="#00FF00"/>
1353         <param name="line-order-in" value="1"/>
1354         <!-- OUT -->
1355         <param name="ds-expr-out" value="{ifOutOctets}"/>
1356         <param name="graph-legend-out" value="Bytes per second out"/>
1357         <param name="line-style-out" value="LINE2"/>
1358         <param name="line-color-out" value="#0000FF"/>
1359         <param name="line-order-out" value="2"/>
1360       </leaf>
1361
1362 Schema definitions can be modified in two ways
1363 (see the I<Torrus Styling Profile Guide> manual for available styles
1364 and override details)
1365
1366 =over 4
1367
1368 =item * Create an overlay schema:
1369
1370 Specify the overlay schema in torrus-siteconfig.pl using the
1371 $Torrus::Renderer::stylingProfileOverlay variable.
1372
1373 =item * Create a replacement schema:
1374
1375 Specify the replacement schema in torrus-siteconfig using the
1376 $Torrus::Renderer::stylingProfile variable.
1377
1378 =back
1379
1380
1381 =head2 Token sets definitions
1382
1383 I<Token> is a symbolic identifier for each subtree or a leaf.
1384
1385 A I<tokenset> is a named list of tokens. Its contents can be
1386 rendered, and its members can be added or removed at any time.
1387
1388 Each tokenset can have a number of parameters defined. It also
1389 inherits the parameter defined in the top C<E<lt>token-setsE<gt>>
1390 XML element:
1391
1392   <token-sets>
1393
1394     <param name="default-tset-view" value="default-tset-html" />
1395     <param name="default-tsetlist-view" value="tset-list-html" />
1396
1397     <token-set name="jumps">
1398       <param name="comment" value="Traffic rate jumps" />
1399     </token-set>
1400
1401     <token-set name="hw-failures">
1402       <param name="comment" value="Holt-Winters prediction failures" />
1403     </token-set>
1404
1405   </token-sets>
1406
1407 Parameter C<default-tsetlist-view> is mandatory for tokenset list.
1408 It defines the default view when displaying the list of tokensets.
1409
1410 The following parameters are mandatory for tokensets:
1411
1412 =over 4
1413
1414 =item * C<default-tset-view>
1415
1416 Determines the view for displaying the tokenset contents.
1417
1418 =item * C<comment>
1419
1420 The text that describes this tokenset.
1421
1422 =back
1423
1424 =head2 Monitor definitions
1425
1426 I<Monitor> is a named set of parameters that defines the behaviour
1427 of monitor module. Each leaf can be given a number of monitors
1428 via C<monitor> parameter.
1429
1430 Upon monitor module run, an I<action> is launched if the alarm conditions
1431 of a given monitor are satisfied.
1432
1433   <monitors>
1434     <!-- First define the actions -->
1435
1436     <!-- This action will put the graphs of alarmed datasources in
1437          a single alarm report page -->
1438     <action name="graph-hw-failures">
1439       <param name="action-type" value="tset" />
1440       <param name="set-name" value="hw-failures" />
1441     </action>
1442
1443     <action name="graph-jumps">
1444       <param name="action-type" value="tset" />
1445       <param name="set-name" value="jumps" />
1446     </action>
1447
1448     <monitor name="hw-failures">
1449       <param name="monitor-type" value="failures" />
1450       <param name="action" value="graph-hw-failures" />
1451       <param name="expires" value="3600" />
1452     </monitor>
1453
1454     <!-- alarm if 5 minutes away it was 10 times lower -->
1455     <monitor name="high-jumps">
1456       <param name="monitor-type" value="expression" />
1457       <param name="rpn-expr" value="{(-300)},10,*,GT,{},{(-300)},10,/,LT,OR" />
1458       <param name="action" value="graph-jumps" />
1459       <param name="expires" value="3600" />
1460       <param name="comment"
1461              value="Value jumped more than 10-fold in 5 minutes" />
1462     </monitor>
1463
1464     <monitor name="hundred-megs">
1465       <param name="monitor-type" value="expression" />
1466       <param name="rpn-expr" value="100,1024,1024,*,*,GT" />
1467       <param name="action" value="graph-jumps" />
1468       <param name="expires" value="3600" />
1469       <param name="comment"
1470              value="Traffic is higher than 10 mbps" />
1471     </monitor>
1472   </monitors>
1473
1474 =head3 Event types
1475
1476 Should the alarm condition occur, a series of events is happening
1477 in sequentional order:
1478
1479 =over 4
1480
1481 =item * C<set>
1482
1483 This event type occurs the first time the alarm condition is met.
1484
1485 =item * C<repeat>
1486
1487 This event type means that the alarm condition still persists
1488 after the previous run of Monitor.
1489
1490 =item * C<clear>
1491
1492 Event of this type happens when the alarm condition stops.
1493
1494 =item * C<forget>
1495
1496 Once the alarm is cleared, this event happens after the expiration
1497 time of the monitor.
1498
1499 =back
1500
1501 =head3 Monitor parameters
1502
1503 =over 4
1504
1505 =item * C<monitor-type>
1506
1507 Mandatory parameter. Specifies the monitor type. The following monitor
1508 types are recognized:
1509
1510 =over 8
1511
1512 =item * C<failures>
1513
1514 Triggers the action when Holt-Winters FAILURES function gives value of 1.
1515 This requires RRDtool verion 1.1.x and aberrant behaviour parameters
1516 defined for te given RRD file.
1517
1518 =item * C<expression>
1519
1520 Triggers the action when given RPN expression returns nonzero.
1521 See I<RPN expressions in Torrus> manual for more details.
1522 This monitor type implies that the RPN expression is specified in
1523 C<rpn-expr> parameter. The current leaf value is prepended to the given RPN.
1524
1525 =back
1526
1527 =item * C<rpn-expr>
1528
1529 Mandatory for monitor type C<expression>. Defines the RPN expression to
1530 evaluate. The current leaf value is prepended to the given RPN.
1531 The expresion may reference leaf-dependent variables: the
1532 constructs of the form C<#varname> are replaced with the variable
1533 value specified in the leaf's C<monitor-vars> parameter.
1534
1535 =item * C<action>
1536
1537 Mandatory parameter, comma-separated list of action names (spaces
1538 are allowed). Each action is triggered when the alarm condition is met.
1539
1540 =item * C<expires>
1541
1542 Mandatory parameter, the number of seconds of expiration period.
1543 After the alarm condition becomes false, this parameter determines
1544 the time of memorizing the event in monitor status reports.
1545
1546 =item * C<comment>
1547
1548 Optional but recommended parameter, specifies the string identifying
1549 the event that this monitor watches.
1550
1551 =item * C<severity>
1552
1553 Optional severity level. Used for the action type C<exec>.
1554
1555 =item * C<display-rpn-expr>
1556
1557 Optional RPN expression for transforming the datasource value.
1558 If defined, it will be applied to the value before setting
1559 C<TORRUS_VALUE> and C<TORRUS_DISPLAY_VALUE> environment variables.
1560
1561 =item * C<display-format>
1562
1563 Optional I<sprintf> format for displaying the value in
1564 C<TORRUS_DISPLAY_VALUE> environment variable. Default is C<%.2f>.
1565
1566 =back
1567
1568
1569 =head3 Action parameters
1570
1571 =over 4
1572
1573 =item * C<action-type>
1574
1575 Mandatory parameter, defines the type of action. Recognized
1576 values are:
1577
1578 =over 8
1579
1580 =item * C<tset>
1581
1582 When this type of action is triggered, the leaf is added to the specified
1583 tokenset (see I<Token sets definitions> section in this manual).
1584 The leaf persists in the tokenset until the event of type C<forget>.
1585 This action type implies the parameter C<tset-name>.
1586
1587 =item * C<exec>
1588
1589 This action type defines an external program to launch. Two other parameters
1590 determinate its behaviour: mandatory C<command> and optional C<launch-when>.
1591
1592 =back
1593
1594 =item * C<tset-name>
1595
1596 Mandatory for action type C<tset>. Defines the tokenset name
1597 where the leaf is added when the monitor condition is met.
1598
1599 =item * C<command>
1600
1601 Mandatory for action type C<exec>. Defines the external program to launch.
1602 The following strings are substituted in the parameter value:
1603
1604 =over 8
1605
1606 =item * C<E<amp>gt;>
1607
1608 Relaced with C<E<gt>>.
1609
1610 =item * C<E<amp>lt;>
1611
1612 Relaced with C<E<lt>>.
1613
1614 =back
1615
1616 The following environment variables are passed to the child process:
1617
1618 =over 8
1619
1620 =item * C<$TORRUS_HOME>
1621
1622 C<prefix> where Torrus was installed.
1623
1624 =item * C<$TORRUS_BIN>
1625
1626 Directory containing Torrus executables.
1627
1628 =item * C<$TORRUS_UPTIME>
1629
1630 Number of seconds since Monitor has started.
1631
1632 =item * C<$TORRUS_TREE>, C<$TORRUS_TOKEN>, C<$TORRUS_NODEPATH>
1633
1634 Tree name, token and pathname of the leaf causing the alarm.
1635
1636 =item * C<$TORRUS_NCOMMENT>, C<$TORRUS_NPCOMMENT>
1637
1638 C<comment> parameter of the node and its parent.
1639 Empty if the parameter is not defined for the given leaf.
1640
1641 =item * C<$TORRUS_EVENT>
1642
1643 Event type.
1644
1645 =item * C<$TORRUS_MONITOR>
1646
1647 Monitor name
1648
1649 =item * C<$TORRUS_MCOMMENT>
1650
1651 Monitor's C<comment> parameter value.
1652
1653 =item * C<$TORRUS_TSTAMP>
1654
1655 Timestamp (in seconds since Epoch) of the event.
1656
1657 =item * C<$TORRUS_VALUE>
1658
1659 For expression monitor type, this returns the last read value of the
1660 datasource, possibly transformed by C<display-rpn-expr> expression.
1661
1662 =item * C<$TORRUS_DISPLAY_VALUE>
1663
1664 For expression monitor type, it contains a human-readable form
1665 of the value, possibly transformed by C<display-rpn-expr> expression.
1666
1667 =item * C<$TORRUS_SEVERITY>
1668
1669 If the C<severity> parameter is defined in the monitor, its value
1670 is passed with this variable.
1671
1672 =back
1673
1674 =item * C<launch-when>
1675
1676 Optional for action type C<exec>. The comma-separated list of event
1677 types when the given action should be launched. If not defined,
1678 the event type C<set> is used by default.
1679
1680 =item * C<setenv-params>
1681
1682 Optional for action type C<exec>. The comma-separated list of leaf parameters
1683 which would be passed as environment variables to the child process.
1684 The environment variables are of the form C<$TORRUS_P_paramname>. Hyphens ('-')
1685 are replaced with underscores ('_') in the parameter names.
1686
1687 =item * C<setenv-dataexpr>
1688
1689 Optional for action type C<exec>. Comma-separated list of C<ENV=paramname>
1690 pairs. C<ENV> defines the environment variable name: it is prefixed with
1691 C<Torrus_>. C<paramname> defines the action parameter name. This parameter
1692 is interpreted as RPN expression applied to the current leaf being monitored.
1693 The result of this RPN expression is passed to the action script
1694 in the environment variable.
1695
1696 Example:
1697
1698   <action name="report-temperature">
1699       <param name="action-type" value="exec" />
1700
1701       <!-- This is our proprietary reporting script -->
1702       <param name="command">
1703         /usr/local/bin/report_temperature
1704       </param>
1705       <param name="launch-when" value="set" />
1706
1707       <!-- We want to tell the action script the actual values
1708            of the "temperature" and "humidity" leaves in the current
1709            datasource tree -->
1710       <param name="setenv-dataexpr" value="TEMP=expr-temp, HMD=expr-hmd" />
1711       <param name="expr-temp" value="{temperature(LAST)}" />
1712       <param name="expr-hmd" value="{humidity(LAST)}" />
1713
1714       <!-- We also want to tell the action script the parameter "monitor-vars"
1715            which was configured for the current leaf. -->
1716       <param name="setenv-params" value="monitor-vars" />
1717   </action>
1718
1719
1720 =back
1721
1722
1723 =head1 Author
1724
1725 Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>