path: root/torrus/doc/snmpdiscovery.pod.in

#  Copyright (C) 2002-2009  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: snmpdiscovery.pod.in,v 1.1 2010-12-27 00:04:35 ivan Exp $
# Stanislav Sinyagin <ssinyagin@yahoo.com>
#
#

=head1 Torrus SNMP Discovery User Guide

=head2 Introduction

In many (but not only) cases Torrus is used for SNMP monitoring.
It provides powerful tools which automate the process of devices' MIB
discovery.

The discovery tools consist of two programs: C<torrus devdiscover> performs
the SNMP discovery, based on the discovery instructions XML file.
The result of its work is a new Torrus datasource configuration file.
Another utility, C<torrus genddx>, is a program that generates the
basic discovery instructions file based on a set of commandline options.

The device discovery XML, or as we call them DDX files, are usually
resided in F<@siteconfdir@/discovery/> directory. This is the default
path to search for them when the absolute path is not given.

=head2 C<torrus genddx>: Discovery instructions generator

  Usage: torrus genddx options...
  Options:
     --host=hostname         router hostname
     --hostfile=filename     space-separated router hostnames file
     --out=outfile           output file.         [routers.ddx]
     --discout=filename      discovery output file [routers.xml]
     --domain=domain         optional DNS domain name
     --version=v             SNMP version         [2c]
     --community=string      SNMP read community  [public]
     --port=number           SNMP port            [161]
     --retries=number        SNMP retries         [2]
     --timeout=number        SNMP timeout         [10]
     --subtree=string        Subtree name         [/Routers]
     --datadir=path          data-dir parameter [@defrrddir@]
     --holtwinters           Enable Holt-Winters analysis

This utility generates C<devdiscover> instructions XML file (DDX) based on
commandline options and a plain list of SNMP agents' hostnames.
Hostnames are specified with one or many C<--host=hostname> options,
or a plain text file with space-separated hostnames.

Each host may have a symbolic name. This symbolic name is used as
the host-level subtree name. The symbolic name follows the hostname with
a semicolon.

By default, the devices are placed into C</Routers/> subtree hierarchy.
You may change the subtree name with the I<--subtree> option.
Single slash as subtree name would cause host-level subtrees placed at the top
of the datasources tree.

By default, C<genddx> specifies the discovery output file as <routers.xml>,
and it would be placed in site XML configuration directory.
You most probably will change this by using the C<--discout> option.

Examples:

  torrus genddx --out=ch-langenthal.ddx \
    --discout=ch-langenthal.xml \
    --host=192.168.34.35:Langenthal_PE1 \
    --host=192.168.34.36:Langenthal_PE2 \
    --host=192.168.34.37:Langenthal_CE_Stadtverwaltung \
    --community=blahBlah \
    --subtree=/MPLS/CH/Bern/Langenthal

  torrus devdiscover --in=ch-langenthal.ddx

B<Note:> C<genddx> is designed as a one-time utility. You may run it to create
a typical discovery file with basic set of options. Then the discovery
configuration XML would be the primary source of information, and it should
be maintained by manual editing, or by some other automated means.
Alternatively you may use C<ttproclist> utility and generate highly customized
discovery instruction files based on static templates and lists of SNMP nodes.
See L<torrus_ttproclist(@mansec_usercmd@)> manpage for more details and
examples.



=head2 C<torrus devdiscover>: SNMP discovery tool

  Usage: torrus devdiscover --in=filename.ddx options... [ddx files]
  Options:
   --in=filename.ddx       discovery instructions XML file(s)
   --mkdir                 create data-dir directories
   --limit=regexp          limit the discovery by output files
   --forcebundle           always write the bundle file
   --fallback=integer      maximum age of XML file to fall back to
   --threads=integer       number of parallel discovery threads
   --verbose               print extra information
   --debug                 print debugging information
   --snmpdebug             print SNMP protocol details

This utility performs the SNMP discovery of devices listed in the input
DDX file. The output XML file is the Torrus datasources configuration.
Output file name is taken from C<output-file> parameter in the DDX.
If the output file is not an absolute path, the file is placed
in the site XML configuration directory (F<@sitexmldir@>).

C<devdiscover> is accompanied by a number of MIB- or vendor-specific
modules, each responsible for finding specific SNMP variables in
the SNMP device, and for generating a piece of Torrus configuration XML
file responsible for that specific MIB. The list of supported generic MIBs and
vendors is constantly growing. It is quite easy to create new discovery
modules, and the internals are documented in
I<Torrus SNMP Device Discovery Developer's Guide>.

The output file automatically includes all required prerequisite
generic and vendor template definition files.

Behaviour of C<devdiscover> is controlled by variables in
F<@siteconfdir@/devdiscover-siteconfig.pl> file. Default values for
those variables reside in F<@cfgdefdir@/devdiscover-config.pl>.

For large installations, it is recommended to place RRD files into
a hashed directory structure. You can enable this feature by setting

  $Torrus::DevDiscover::hashDataDirEnabled = 1;

in your F<devdiscover-siteconfig.pl> file.
Then launching C<devdiscover> with C<--mkdir> option would automatically
create the subdirectories inside C<data-dir>.

The XML files produced by C<devdiscover> may be automatically changed
with some local site-specific scripts. See XUpdate usage example in
I<Torrus User Guide>.


=head2 DDX, the discovery instructions file

The input file for C<devdiscover> is an XML file. Its DTD is available
in Torrus distribution in F<snmp-discovery.dtd>.

A typical place to store the discovery XML is F<@siteconfdir@/discovery/>.

Example:

    <?xml version="1.0" encoding="UTF-8"?>
    <snmp-discovery>
      <file-info>
        <format-version>
    1.0
        </format-version>
      </file-info>
      <creator-info>
    Torrus version 0.1.4d
    This file was generated by command:
    /usr/local/torrus-0.1/bin/genddx \
     --discout=share/torrus/xmlconfig/myrouters.xml \
     --community=blahblah  --host=10.0.0.1  --host=10.0.1.1
    On Tue Dec  2 17:43:30 2003
      </creator-info>
      <param name="data-dir" value="@defrrddir@"/>
      <param name="domain-name" value=""/>
      <param name="host-subtree" value="/Routers"/>
      <param name="output-file" value="myrouters.xml"/>
      <param name="rrd-hwpredict" value="no"/>
      <param name="snmp-community" value="blahblah"/>
      <param name="snmp-port" value="161"/>
      <param name="snmp-retries" value="2"/>
      <param name="snmp-timeout" value="10"/>
      <param name="snmp-version" value="2c"/>
      <host>
        <param name="snmp-host" value="10.0.0.1"/>
        <param name="symbolic-name" value="10.0.0.1"/>
      </host>
      <host>
        <param name="snmp-host" value="10.0.1.1"/>
        <param name="symbolic-name" value="10.0.1.1"/>
      </host>
    </snmp-discovery>

=head3 XML elements

=over 4

=item * C<snmp-discovery>

Mandatory. The top-level element.

=item * C<file-info>

Mandatory. It must contain the element C<format-version>.

=item * C<format-version>

Mandatory. It must contain a format version currently
supported by devdiscover. Currently supported version is C<1.0>.

=item * C<creator-info>

Optional. May contain the information about the file creator: a human author
name, or a program.

=item * C<param>

Some parameters are mandatory. This element defines a global or host-specific
parameter. Mandatory attribute C<name> identifies the parameter,
and the value is taken eother from C<value> attribute, or from the
textual content of the element.

C<param> element should be the child element of C<snmp-discovery> for global
parameters or C<host> for host-level parameters. Host-level parameters
override the values of global parameters.

These parameters are for C<devdiscover> only. They are not Torrus configuration
parameters, although some of them are directly copied into the generated
configuration file.

=item * C<host>

Mandatory. Defines a host to run SNMP discovery.

=back


=head3 Common parameters

=over 4

=item * C<collector-period>, C<collector-timeoffset>,
C<collector-dispersed-timeoffset>, C<collector-timeoffset-min>,
C<collector-timeoffset-max>, C<collector-timeoffset-step>,
C<monitor-period>, C<monitor-timeoffset>

Optional. When defined, these parameters override those from C<snmp-defaults>
template in F<snmp-defs.xml>.

=item * C<output-file>

Mandatory. Specifies the output filename for generated Torrus configuration.
If it's a relative path, the file is placed in F<@sitexmldir@> directory.

=item * C<output-bundle>

Optional. Specifies a comma-separated list of XML file names for bundle
output. Each bundle file will contain E<lt>includeE<gt> statement for each
corresponding C<output-file>.

=item * C<snmp-ipversion>, C<snmp-transport>, C<snmp-port>,
        C<snmp-community>,  C<snmp-version>, C<snmp-timeout>,
        C<snmp-retries>, C<snmp-host>, C<snmp-username>, C<snmp-authkey>,
        C<snmp-authpassword>, C<snmp-authprotocol>, C<snmp-privkey>,
        C<snmp-privpassword>, C<snmp-privprotocol>

Mandatory SNMP session parameters. Authentication parameters depend on the
SNMP version used. See the I<XML Configuration Guide> for details.
These parameters define the SNMP agent properties and are
copied one-to-one to the output configuration.

=item * C<domain-name>

Optional. Defines a DNS domain name to be appended to C<snmp-host>.

=item * C<snmp-localaddr> and C<snmp-localport>

Optional parameters specifying the local socket binding address and port.

=item * C<data-dir>

Mandatory. Defines the directory path where RRD files for this host
are stored. In case if hashed directories are enabled, C<data-dir> specifies
the base path under which the hashed subdirectories are created.

=item * C<symbolic-name>

Optional. Determines the host-specific subtree name. If not specified,
the subtree is named by C<system-id>, or by C<snmp-host> if system ID is
not defined.

=item * C<system-id>

Optional. If defined, it overrides the default value of system ID, which
is equal to the value of C<snmp-host>.

=item * C<nodeid-device>

Optional. Defines the host-specific reference for I<nodeid>. Default value
is equal to C<system-id>.

=item * C<snmp-oids-per-pdu>

Optional. When defined, these parameters overwrites the value from the
template and vendor-specific discovery modules.

=item * C<snmp-check-sysuptime>

Optional. Default: C<yes>. Devdiscover sets this parameter to C<no> when it
finds SNMPv2-MIB::sysUpTime variable unavailable in the device.

=item * C<snmp-max-msg-size>

Optional. If defined, it sets the SNMP maximum message size different from
default. The default value is 1470 (defined in Net::SNMP).

=item * C<host-subtree>

Optional. Defines the datasourse tree path under which the host-specific
subtree is created.

=item * C<rrd-hwpredict>

Optional. Valid values: C<yes>, C<no>. Determines if Holt-Winters forecasting
should be enabled for the given host.

=item * C<disable-devtypes>

Optional. Comma-separated list of discovery device types that need to be
excluded from discovery process. For example, ATMEL appliances conflict with
Empire SystemEdge MIBs, and you need to disable C<EmpireSystemedge> module
in order to run the discovery on those appliances.

=item * C<only-devtypes>

Optional comma-separated list of device types. If defined, only the specified
types will be used for device probing.

=item * C<host-aliases>

Optional comma-separated list of alias paths for a given host. Aliases
must be unique for each host.

=item * C<custom-host-templates>

Optional comma-separated list of template names that will be applied
to the resulting XML configuration at the host level.

=item * C<include-files>

Optional comma-separated list of XML files that will be listed in C<include>
statements in the resulting XML output.


=item * C<host-copy-params>

Optional comma-separated list of parameter names that should be copied
from the discovery configuration file to the generated Torrus configuration
at the host level.

=item * C<selectors>

Optional comma-separated list of object selectors. They are explained in more
detail below.

=item * C<disable-snmpcollector>

When set to C<yes>, this parameter disables SNMP collection for this
host. It is useful for creating custom views, in conjunction with
C<RFC2863_IF_MIB::only-interfaces> parameter.

=item * C<define-tokensets>

Semicolon-separated (;) list of pairs of tokenset names and descriptions.
Each tokenset name is followed by colon (:) and the description text:

  <param name="define-tokensets">
    important-graphs: Important Graphs;
    unimportant-graphs: Unimportant Graphs
  </param>

=item * C<suppress-legend>

if set to C<yes>, the legend is not shown. It usually has uptime,
software version, and contact information for the SNMP device.

=item * C<comment>

Sets the comment string for the host.

=item * C<show-recursive>

Default: C<yes>. When set to C<no>, the link to the recursive view at the
host level is omitted.

=item * C<template-registry-overlays>

If defined, this should be a comma-separated list of template registry
entries that override the default template references. The overlaying
templates should be referred in
C<%Torrus::DevDiscover::templateOverlays>.
For example, we want to redefine the interface counter template. Then
in the DDX file, we set

  <param name="template-registry-overlays" value="my_ifcounters"/>

Then in F<devdiscover-siteconfig.pl> we set 

  %Torrus::DevDiscover::templateOverlays = {
      'my_ifcounters' => {
          'RFC2863_IF_MIB::iftable-octets' => {
             'name'   => 'my-iftable-octets',
             'source' => 'mycustom-rfc2863.if-mib.xml'
             },
         'RFC2863_IF_MIB::ifxtable-hcoctets' => {
             'name'   => 'my-ifxtable-hcoctets',
             'source' => 'mycustom-rfc2863.if-mib.xml'
             },
         }};


=back


=head3 Parameters for C<RFC2863_IF_MIB>

This discovery module is responsible for agent's interfaces table and
interface counters. Recognized optional parameters are:

=over 4

=item * C<RFC2863_IF_MIB::suppress-hc-counters>

Some agents do not implement 64-bit counters correctly. When this parameter
is set to C<yes>, 64-bit interface counters are not used for the host.
For Cisco IOS devices, the C<CiscoIOS> discovery module tries to detect
such situation automatically.

=item * C<RFC2863_IF_MIB::subtree-name>

Defines the child subtree name within host-level subtree where interface
counters are located. Default: C<Interface_Counters>.

=item * C<RFC2863_IF_MIB::subtree-comment>

Defines the comment string for interface counters subtree.
Default: I<Interface traffic and error counters>.

=item * C<RFC2863_IF_MIB::list-admindown-interfaces>

If set to C<yes>, interfaces with ifAdminStatus set to other than up(1)
are included in the discovery results.
By default, such interfaces are not listed.

=item * C<RFC2863_IF_MIB::list-notpresent-interfaces>

If set to C<yes>, the interfaces with ifOperStatus status set to notPresent(6)
are included in the discovery results. By default, such interfaces are
not listed.

=item * C<RFC2863_IF_MIB::exclude-down-interfaces>

If set to C<yes>, the interfaces with ifOperStatus equal to down(2)
are excluded from the discovery results.

=item * C<RFC2863_IF_MIB::exclude-interfaces>

Comma-separated list of interface names which should be excluded from
configuration. Spaces are allowed between the names and commas.
The names should be the ones that are used for interface subtrees.

=item * C<RFC2863_IF_MIB::only-interfaces>

If defined, this parameter specifies the list of interfaces that will be
included in the discovery results. The names should match the interface
subtree names. Caution: if specified incorrectly, this parameter may
disable discovery for all interfaces on a device.

=item * C<RFC2863_IF_MIB::tokenset-members>

This parameter defines which interfaces' C<InOut_bps> leaves to add to
which tokensets. The value is a semicolon-separated (;) list of
entries of form I<tset:interface,interface>, where I<tset> is a name of the
tokenset, and the I<interface> is the subtree name of the corresponding
interface. The token sets must be defined elsewhere in Torrus configuration.
Example:

  <host>
    <param name="snmp-host" value="192.168.49.131"/>
    <param name="RFC2863_IF_MIB::tokenset-members">
     clusters: 10_1, 10_2;
     uplinks: 1_1, 1_2
    </param>
  </host>

Alternatively, this parameter can be defined at the global level,
and then each interface should be pretended by the SNMP host name (the same as
in C<snmp-host> parameter) and slash sign (/):

    <param name="RFC2863_IF_MIB::tokenset-members">
     clusters: RTR01/Ethernet0_0, RTR01/FastEthernet2_1;
    </param>


=item * C<RFC2863_IF_MIB::copy-params>

Optional comma-separated list of parameter names that would be copied
to the output Torrus configuration at interface level.
For each parameter I<param>, the value for a particular interface I<intf>
will be taken from parameter C<RFC2863_IF_MIB::I<param>::I<intf>> in
the discovery configuration file. Example:

  <host>
    <param name="snmp-host" value="192.168.49.131"/>
    <param name="RFC2863_IF_MIB::copy-params" value="intf-error-threshold"/>
    <param name="RFC2863_IF_MIB::intf-error-threshold::10_1" value="300"/>
    <param name="RFC2863_IF_MIB::intf-error-threshold::2_1" value="900"/>
  </host>

=item * C<RFC2863_IF_MIB::ifindex-map-hint>

Optional. For a device that doesn't have a corresponding vendor-specific
discovery module, this parameter would advice C<devdiscover> how to build
C<ifTable> index mapping. By default, the interfaces are mapped by
C<ifDescr> variables. For many vendors, this would not give reliable
mapping. Valid values are: C<ifName>, C<ifPhysAddress>, and C<ifIndex>.
The first two suggest the mapping by corresponding SNMP variables, and
the third one should be used for devices with fixed C<ifIndex> layout: in
this case, the C<ifIndex> values are recorded as they are at the moment of
discovery. This option is ignored if the device is supported by a vendor
specific discovery module.

=item * C<RFC2863_IF_MIB::subtree-name-hint>

Optional. By default, per-interface subtrees are named after the values of
C<ifDescr> SNMP variables. If this option is set to C<ifName>, this
SNMP variable would be used for subtree naming. This option is ignored if
the device is supported by a vendor specific discovery module.

=item * C<RFC2863_IF_MIB::nodeid-hint>

Optional. By default, per-interface I<nodeid> is derived from
C<RFC2863_IF_MIB::ifindex-map-hint>. This parameter can change the
reference table for nodeid. Valid values are:
C<ifDescr>, C<ifName>, C<ifAlias>, C<ifIndex>.


=item * C<RFC2863_IF_MIB::noout>

If set to C<yes>, all the interface statistics are skipped from
the XML configuration output. Still the interface table is examined and
the results may be used by other discovery modules.

=item * C<RFC2863_IF_MIB::bandwidth-usage>

If set to C<yes>, the bandwidth usage percentage will be shown for those
interfaces where two parameters are defined (in megabits per second):
C<bandwidth-limit-in> and C<bandwidth-limit-out>. These interface
parameters may be set by C<RFC2863_IF_MIB::bandwidth-limits> discovery
parameter, or by selectors with the action C<Parameters>, or by
setting C<RFC2863_IF_MIB::copy-params>.

=item * C<RFC2863_IF_MIB::bandwidth-limits>

Defines the values (in megabits per second) for C<bandwidth-limit-in> and
C<bandwidth-limit-out> interface parameters. Semicolon-separated list
of (I<Inteface name>:I<Input limit>:I<Output limit>) values, for example:

  <host>
    <param name="snmp-host" value="10.1.1.5"/>
    <param name="symbolic-name" value="bsr2k.example.net"/>
    <param name="output-file" value="bsr2k.example.net.xml"/>
    <param name="RFC2863_IF_MIB::bandwidth-usage" value="yes" />
    <param name="RFC2863_IF_MIB::bandwidth-limits">
      ethernet0_0:10:10; ethernet0_1:20:20;
    </param>
  </host>


=item * C<RFC2863_IF_MIB::traffic-summaries>,
C<RFC2863_IF_MIB::traffic-XXX-path>, C<RFC2863_IF_MIB::traffic-XXX-comment>,
C<RFC2863_IF_MIB::traffic-XXX-interfaces>

Defines traffic summary graphs. A summary graph presents a sum of
traffic from several interfaces. The interfaces can belong to different
hosts, but then these hosts should have the same C<output-file> parameter
value. C<RFC2863_IF_MIB::traffic-summaries> defines a list of summary names,
C<RFC2863_IF_MIB::traffic-XXX-path> specifies the full path in the
datasource tree to display the graph, optional
C<RFC2863_IF_MIB::traffic-XXX-comment> defines a descriptive comment
for the graph, and C<RFC2863_IF_MIB::traffic-XXX-interfaces> lists the
interfaces that comprise this sum. The interfaces can be defined at the host
level in the form C<name, name, ...> or at the global level in the form
C<host/intf, host/intf, ...>. Example:

  <param name="RFC2863_IF_MIB::traffic-summaries" value="sum1" />
  <param name="RFC2863_IF_MIB::traffic-sum1-path" value="/Summary/Sum1" />
  <param name="RFC2863_IF_MIB::traffic-sum1-comment" value="Test summary" />

  <host>
    <param name="snmp-host" value="router1.network.net"/>
    <param name="RFC2863_IF_MIB::traffic-sum1-interfaces" 
             value="GigabitEthernet0_2" />
    <param name="output-file" value="TEST/core.xml"/>
  </host>

  <host>
    <param name="snmp-host" value="router2.network.net"/>
    <param name="RFC2863_IF_MIB::traffic-sum1-interfaces" 
             value="GigabitEthernet1_0" />
    <param name="output-file" value="TEST/core.xml"/>
  </host>


=back

=head3 Other generic MIB parameters

=over 4

=item * C<RFC2790_HOST_RESOURCES::sysperf-subtree-name>

Defines the child subtree name within host-level subtree where system CPU
and memory statistics are located. Default: C<System_Performance>.

=item * C<RFC2670_DOCS_IF::upstreams-only>

If set to C<yes>, only the DOCSIS upstream statistics are enabled, and
downstream and MAC layer stats are skipped.

=back

=head3 Vendor parameters

=over 4

=item * C<Arbor_E::disable-bundle-offer>,
    C<Arbor_E::disable-bundle-offer-deny>,
    C<Arbor_E::disable-bundle-offer-pktsize>,
    C<Arbor_E::disable-bundle-offer-rate>,
    C<Arbor_E::disable-bundle-offer-subcount>, C<Arbor_E::disable-flowdev>,
    C<Arbor_E::enable-bundle-name-rrd>,
    C<Arbor_E::disable-e30-buffers>, C<Arbor_E::disable-e30-bundle>,
    C<Arbor_E::disable-e30-cpu>,
    C<Arbor_E::disable-e30-fwdTable>,
    C<Arbor_E::disable-e30-fwdTable-login>,
    C<Arbor_E::disable-e30-hdd>, C<Arbor_E::enable-e30-hdd-errors>,
    C<Arbor_E::disable-e30-hdd-logs>, C<Arbor_E::disable-e30-l2tp>,
    C<Arbor_E::disable-e30-mem>, C<Arbor_E::enable-e30-mempool>,
    C<Arbor_E::disable-e30-bundle>, C<Arbor_E::disable-e30-bundle-deny>, 
    C<Arbor_E::disable-e30-bundle-rate>, C<Arbor_E::disable-e30-slowpath>

When set to C<yes>, the corresponding statistics are included or excluded from
the graphs.

=item * C<Arbor_E::enable-e30-bundle-name-rrd>

When set to C<yes>, the data will be written to filenames based on the name
bundle instead of by the ID of the bundle.

=item * C<Apple_AE::disable-clients-stats>

When set to C<yes>, wireless client machines are not tracked.

=item * C<CiscoGeneric::disable-cpu-stats>

When set to C<yes>, Cisco CPU usage statistics are excluded from discovery.

=item * C<CiscoGeneric::disable-memory-pools>

When set to C<yes>, Cisco memory pool usage statistics are excluded from
discovery. For Cisco series 7500, see the note in the
I<Torrus Vendor Support List>.

=item * C<CiscoGeneric::disable-sensors>

When set to C<yes>, Cisco temperature sensors are excluded from discovery.

=item * C<CiscoGeneric::use-fahrenheit>

When set to C<yes>, Cisco temperature sensors are recorded and displayed
in degrees Fahrenheit.

=item * C<CiscoGeneric::file-per-sensor>

When set to C<yes>, Cisco temperature sensor values are stored in
a separate RRD file per sensor ID. This is useful for modular big routers
like Cisco GSR.

=item * C<CiscoGeneric::disable-psupplies>

if set to C<yes>, Cisco power supply statistics are not collected.

=item * C<CiscoGeneric::power-monitor>

Name of the power supply monitor for Cisco devices.

=item * C<CiscoIOS::enable-membuf-stats>

When set to C<yes>, Cisco memory buffer statistics are included to the 
discovery. Many IOS releases report faulty information, thus these
stats are disabled by default.

=item * C<CiscoIOS::disable-ipsec-stats>

When set to C<yes>, IPSec statistics are excluded from discovery.

=item * C<CiscoIOS::disable-bgp-stats>

If set to C<yes>, BGP statistics are not included.

=item * C<CiscoIOS::enable-vlan-interfaces>

When set to C<yes>, the interfaces VlanXXX are added to statistics.
By default they are not included, because some hardware platforms give
irrelevant counter statistics.

=item * C<CiscoIOS::enable-unrouted-vlan-interfaces>

When set to C<yes>, the interfaces "unrouted Vlan XXX" are added to statistics.
By default they are not included, because some hardware platforms provide
no statistics for such interfaces.


=item * C<CiscoCatOS::suppress-noname-ports>

When set to C<yes>, only those Catalyst ports are included in configuration
which have a port name (set up by C<set port name> command).

=item * C<CiscoIOS_MacAccounting::bgponly>

When set to C<yes>, Cisco MAC accounting statistics will be enabled for
those MACs which correspond to BGP peers only.

=item * C<bgp-as-description-NNNN>

Specifies a description for an autonomous system number. Currently it's used
with Cisco MAC accounting and Cisco BGP statistics only.

=item * C<peer-ipaddr-description-AAA_AAA_AAA_AAA>

Specifies a description for a peer by its IP address. Dots in IP address should
be replaced with underscores. Currently it's used with Cisco
MAC accounting and Cisco BGP statistics only.

=item * C<CiscoIOS_MacAccounting::tokenset-members>

Works the same way as C<RFC2863_IF_MIB::tokenset-members> and assigns MAC
accounting peers to tokensets.

=item * C<CiscoIOS::disable-car-stats>

When set to C<yes>, the Committed Access Rate statistics are disabled
from discovery.

=item * C<CiscoIOS::disable-vpdn-stats>

When set to C<yes>, the VPDN (Virtual Private Dial-up Network) statistics
are disabled from discovery.

=item * C<CiscoIOS::short-device-comment>

If set to C<yes>, the Hw Serial and Revision strings are not shown in
device comment.

=item * C<CiscoSCE::disable-disk>, C<CiscoSCE::disable-gc>,
    C<CiscoSCE::disable-qos>, C<CiscoSCE::disable-rdr>,
    C<CiscoSCE::disable-subs>, C<CiscoSCE::disable-tp>

If set to C<yes>, the corresponding statistics are excluded from Cisco SCE
graphs.

=item * C<FTOS::disable-cpu>, C<FTOS::disable-power>,
    C<FTOS::disable-temperature>

When set to C<yes>, disables the corresponding statistics category.

=item * C<FTOS::use-fahrenheit>, C<FTOS::file-per-sensor>

When set to C<yes>, enables the user of fahrenheit temperature, or writes
multiple rrd files.

=item * C<JunOS::disable-cos>, C<JunOS::disable-cos-red>,
    C<JunOS::disable-cos-tail>, C<JunOS::disable-firewall>,
    C<JunOS::disable-operating>, C<JunOS::disable-rpf>

When set to C<yes>, disables the corresponding statistics category for JunOS
devices.

=item * C<Liebert::disable-temperature>, C<Liebert::disable-humidity>,
    C<Liebert::disable-state>, C<Liebert::disable-stats>

When set to C<yes>, disable the corresponding statistics category for Liebert
devices.

=item * C<Liebert::use-fahrenheit>

When set to C<yes>, the temperature readings will be in fahrenheit.


=item * C<NetBotz::temp-max>, C<NetBotz::humi-max>, C<NetBotz::dew-max>

Set a numeric value for the maximum temperature, humidity, or dew point
on NetBotz sensor graphs. The maximum is displayed with a dark red line.

=item * C<Paradyne::slot-name>

Mandatory for Paradyne DSLAM devices. It should uniquely identify
the slot within the device. Any sequence of word characters is allowed.

=back

See also: I<Torrus Vendor Support List> for the list of supported MIBs and
vendors.

=head2 Object selectors

Selectors are a common mechanism for applying customizations to
some discovery objects. For example, you may want to apply a monitor
to byte counters of interfaces that have a special word in the description.
Or apply Holt-Winters prediction to a certain subset of interfaces.

Selectors are defined in a DDX file as regular parameters.
The parameter C<selectors> defines a list of selector names.
Each selector is identifed by its name and type. The type of selector
defines which objects will be searched: IF-MIB interfaces, or Cisco
temperature sensors, or something else. The parameters are described
below.

=over 4

=item * C<selectors>

Comma-separated list of selector names. Further below we use C<S> as
selector name, C<A> as attribute name, and C<T> as action name.

=item * C<S-selector-type>

Type of objects to be selected. Supported values are: C<RFC2863_IF_MIB>,
C<CiscoCPU>, C<CiscoSensor>.

=item * C<S-selector-expr>

An RPN (reverse Polish notation) expression that defines the
object attributes to be checked and relation between them. Attribute names
should be specified in curly braces ({}). The rest of the syntax is described
in I<RPN expressions in Torrus> guide. The attribute names are specific to the
selector type and are described below.

=item * C<S-A>

For a given selector name C<S> and attribute name C<A>,
this parameter defines the attribute value that should be compared
to the object's properties. In most cases it defines a regular
expression that should match the value of a corresponding object's
property.

=item * C<S-selector-actions>

For a given selector name C<S>, this parameter defines a comma-separated
list of actions to be applied for objects where C<S-selector-expr> returns
true. The action names are specific to the selector type and are
described below.

=item * C<S-T-arg>

For a given selector C<S> and action C<T>, this parameter defines
an argument that should be passed to the action. Each action
defines its own meaning of the argument.

=back



=head3 RFC2863_IF_MIB selector

This type of selector selects the network interfaces on a SNMP device.
The following attribute names are supported:

=over 4

=item * C<ifSubtreeName>, C<ifSubtreeName1>, ...

Interface-level subtree name as you see it in the discovery results.
You can compose a complex expression of subtree matches, by
createing attributes with different numbers at the end.

=item * C<ifComment>

Comment string that is defined in C<comment> parameter. It is
usually derived from an interface description.

=item * C<ifType>

Numeric IANA interface type, as returned by C<ifType> SNMP variable.

=back

C<ifType> is compared numerically.
C<ifSubtreeName> and C<ifComment> are regular expressions.
C<ifSubtreeName> accepts multiple expressions separated by space,
and the selector matches if any of these expressions matches the subtree name.



The following actions are supported:

=over 4

=item * C<InBytesMonitor>, C<OutBytesMonitor>

The argument defines the monitor name to be applied to the input
or output bytes counter.

=item * C<InDiscardsMonitor>, C<OutDiscardsMonitor>,
C<InErrorsMonitor>, C<OutErrorsMonitor>

The argument defines the monitor name to be applied to discard and error 
counters that are discovered for a given interface.

=item * C<NotifyPolicy>

The argument defines the value for C<notify-policy> parameter. See the manual
for F<action_notify> for more details.

=item * C<HoltWinters>

No argument needed. This action enables Holt-Winters prediction
for given interface's counters.

=item * C<NoPacketCounters>, C<NoDiscardCounters>, C<NoErrorCounters>

No argument needed. The action disables the packet, discard or error counters
for a given interface to be collected.

=item * C<TokensetMember>

The argument is a comma-separated list of tokenset names where C<InOutBbs>
graphs would be added. This action complements
C<RFC2863_IF_MIB::tokenset-members>.

=item * C<Parameters>

The argument defines additional configuration parameters to be
placed at the interface level. The value should be one
or several C<param=value> pairs separated by semicolon (;).
Parameters defined in C<RFC2863_IF_MIB::copy-params> may override
the ones defined in this action.

=item * C<InBytesParameters>, C<OutBytesParameters>

Analagous to C<Parameters>, but the parameters are applied to InBytes and
OutBytes leaves of the selected interface.

=item * C<DocsisUpSNRMonitor>

For a DOCSIS CMTS, this action assigns a new  monitor to the upstream
Signal/Noise ratio gauge, instead of the default monitor.

=item * C<DocsisUpSNRTokenset>

For a DOCSIS CMTS, this action adds the Signal/Noise ratio graph to a
specified tokenset.

=item * C<DocsisUpFECCorMonitor>

For a DOCSIS CMTS, this action assigns a monitor to the C<Correctable>
counter of the upstream FEC statistics.

=item * C<DocsisUpFECUncorMonitor>

For a DOCSIS CMTS, this action assigns a monitor to the C<Uncorrectable>
counter of the upstream FEC statistics.

=item * C<DocsisDownUtilMonitor>

For a DOCSIS CMTS, this action assigns a monitor to the downstream
C<UsedBytes> counter.

=item * C<DocsisMacModemsMonitor>

For Cisco uBR, this action assigns a monitor to the C<Modems_Registered> gauge
in the MAC layer stats.

=item * C<DocsisUpUtilMonitor>, C<DocsisUpSlotsMonitor>

For Cisco uBR, this action assigns a monitor to upstream utilization and
free contention timeslots gauges correspondingly.

=back


=head3 CiscoCPU selector

A selector of this type selects CPU statistics Cisco router or
switch.

The attributes supported are: C<CPUName> and C<CPUDescr>, and their
values are regular expressions that should match the CPU name or description,
as discovered by C<devdiscover>.

The action supported is C<TokensetMember>, and its argument specifies
the tokenset where to place the CPU statistics graph.


=head3 CiscoSensor selector

A selector of this type selects temperature sensors on a Cisco router or
switch.

The only attribute supported is C<SensorDescr>, and its value is a regular
expression that should match the sensor description, as discovered
by C<devdiscover>.

Actions supported: C<Monitor>, C<TokensetMember>.


=head3 ALU_SAP selector

This selector type is designed for SAP entries in Alcatel-Lucent ESS and SR
routers.

Attributes supported: C<sapDescr> (regexp), C<custDescr> (regexp),
C<sapName> (exact match), C<sapPort> (exact match).

Actions supported: C<RemoveSAP> (excludes a selected SAP from the datasources).



=head3 Examples

The following example applies a monitor called C<temp60degrees> to all
inlet sensors on a Cisco device:

  <host>
    <param name="snmp-host" value="router1"/>
    <param name="output-file" value="router1.xml"/>
    <param name="selectors" value="inlet"/>
    <param name="inlet-selector-type" value="CiscoSensor"/>
    <param name="inlet-selector-expr"  value="{SensorDescr}"/>
    <param name="inlet-SensorDescr" value="Inlet"/>
    <param name="inlet-selector-actions"  value="Monitor"/>
    <param name="inlet-Monitor-arg" value="temp60degrees"/>
  </host>

The following example enables Holt-Winters prediction and specifies some
parameters to all FastEthernet interfaces which have the string "SRV-ID"
in their descriptions:

  <host>
    <param name="snmp-host" value="router2"/>

    <param name="selectors"  value="FastEthHW"/>
    <param name="FastEthHW-selector-type"     value="RFC2863_IF_MIB"/>

    <param name="FastEthHW-selector-expr"    
           value="{ifSubtreeName},{ifComment},AND"/>
    <param name="FastEthHW-ifSubtreeName"     value="^FastEthernet"/>
    <param name="FastEthHW-ifComment"         value="SRV-ID"/>

    <param name="FastEthHW-selector-actions"
           value="HoltWinters,Parameters"/>

    <param name="FastEthHW-Parameters-arg"
       value="rrd-create-hw-alpha=0.2; rrd-create-hw-beta=0.01"/>
  </host>

The following example sets up the monitors defined in
F<examples/docsis-monitors.xml>:

    <param name="selectors" value="docs"/>
    <param name="docs-selector-type" value="RFC2863_IF_MIB"/>
    <param name="docs-selector-expr"  value="{ifSubtreeName}"/>
    <param name="docs-ifSubtreeName"  value="^Cable"/>
    <param name="docs-selector-actions"> 
          DocsisUpSNRMonitor,
          DocsisUpFECCorMonitor,
          DocsisUpFECUncorMonitor,
          DocsisDownUtilMonitor,
          DocsisMacModemsMonitor,
          DocsisUpUtilMonitor,
          DocsisUpSlotsMonitor,
          InErrorsMonitor,
          OutErrorsMonitor
    </param>
    <param name="docs-DocsisUpSNRMonitor-arg" 
           value="docsis-snr-1,docsis-snr-2,docsis-snr-3"/>

    <param name="docs-DocsisUpFECCorMonitor-arg" 
           value="docsis-feccor-1,docsis-feccor-2"/>

    <param name="docs-DocsisUpFECUncorMonitor-arg" 
           value="docsis-fecuncor-1,docsis-fecuncor-2,docsis-fecuncor-3"/>

    <param name="docs-DocsisDownUtilMonitor-arg" 
           value="docsis-downutl-1,docsis-downutl-2,docsis-downutl-3"/>

    <param name="docs-DocsisMacModemsMonitor-arg" 
           value="docsis-modems-1,docsis-modems-2"/>

    <param name="docs-DocsisUpUtilMonitor-arg" 
           value="docsis-uputil-1,docsis-uputil-2,docsis-uputil-3"/>
    
    <param name="docs-DocsisUpSlotsMonitor-arg" 
           value="docsis-upslots-1,docsis-upslots-2,docsis-upslots-3"/>
    
    <param name="docs-InErrorsMonitor-arg" 
           value="docs-inerrors-1,docs-inerrors-2"/>

    <param name="docs-OutErrorsMonitor-arg" 
           value="docs-outerrors-1,docs-outerrors-2"/>



=head1 Author

Copyright (c) 2002-2005 Stanislav Sinyagin E<lt>ssinyagin@yahoo.comE<gt>