Torrus SNMP Discovery User Guide
  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: "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, "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 /usr/local/etc/torrus/conf/discovery/ directory. This is the
    default path to search for them when the absolute path is not given.

  "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 [/var/torrus/collector_rrd]
         --holtwinters           Enable Holt-Winters analysis

    This utility generates "devdiscover" instructions XML file (DDX) based
    on commandline options and a plain list of SNMP agents' hostnames.
    Hostnames are specified with one or many "--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 "/Routers/" subtree hierarchy.
    You may change the subtree name with the *--subtree* option. Single
    slash as subtree name would cause host-level subtrees placed at the top
    of the datasources tree.

    By default, "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 "--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

    Note: "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 "ttproclist" utility and
    generate highly customized discovery instruction files based on static
    templates and lists of SNMP nodes. See torrus_ttproclist(1) manpage for
    more details and examples.

  "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 "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 (/usr/local/etc/torrus/xmlconfig).

    "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 *Torrus SNMP
    Device Discovery Developer's Guide*.

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

    Behaviour of "devdiscover" is controlled by variables in
    /usr/local/etc/torrus/conf/devdiscover-siteconfig.pl file. Default
    values for those variables reside in
    /usr/local/share/torrus/conf_defaults/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 devdiscover-siteconfig.pl file. Then launching "devdiscover"
    with "--mkdir" option would automatically create the subdirectories
    inside "data-dir".

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

  DDX, the discovery instructions file
    The input file for "devdiscover" is an XML file. Its DTD is available in
    Torrus distribution in snmp-discovery.dtd.

    A typical place to store the discovery XML is
    /usr/local/etc/torrus/conf/discovery/.

    Example:

        <?xml version="1.0" encoding="UTF-8"?>
        <snmp-discovery>
          <file-info>
            <format-version>
        1.0
            </format-version>
          </file-info>
          <creator-info>
           Manually edited by Vassisuali Poupkine
          </creator-info>
          <param name="data-dir" value="/var/torrus/collector_rrd"/>
          <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"/>

            <!-- Example of 15-second polling interval.
                 15-second stats are stored for 10 days, and 5-minute
                 aggregates are stored for 30 days.-->

            <param name="collector-period" value="15"/>
            <param name="collector-timeoffset" value="0"/>
            <param name="rrd-create-rra">
               RRA:AVERAGE:0:1:57600
               RRA:AVERAGE:0.25:20:8640      RRA:MAX:0.25:20:8640
            </param>
          </host>

          <host>
            <param name="snmp-host" value="10.0.1.1"/>
            <param name="symbolic-name" value="10.0.1.1"/>

            <!--
             Example of extended RRA definition.
             The RRD files are approximately 8 times bigger than standard.
             5-minute stats: 366 days
             60-minute max and average: 190 days
             daily max and average: 732 days
             In hourly aggregates, 20 minutes missing is allowed.
             In daily aggregates, 6 hours missing is allowed.
            -->
           <param name="rrd-create-rra">
             RRA:AVERAGE:0:1:105408
             RRA:AVERAGE:0.34:12:4560     RRA:MAX:0.34:12:4560
             RRA:AVERAGE:0.25:288:732    RRA:MAX:0.25:288:732
           </param>
          </host>
        </snmp-discovery>

   XML elements
    *   "snmp-discovery"

        Mandatory. The top-level element.

    *   "file-info"

        Mandatory. It must contain the element "format-version".

    *   "format-version"

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

    *   "creator-info"

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

    *   "param"

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

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

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

    *   "host"

        Mandatory. Defines a host to run SNMP discovery.

   Common parameters
    *   "collector-period", "collector-timeoffset",
        "collector-dispersed-timeoffset", "collector-timeoffset-min",
        "collector-timeoffset-max", "collector-timeoffset-step",
        "monitor-period", "monitor-timeoffset"

        Optional. When defined, these parameters override those from
        "snmp-defaults" template in snmp-defs.xml.

    *   "output-file"

        Mandatory. Specifies the output filename for generated Torrus
        configuration. If it's a relative path, the file is placed in
        /usr/local/etc/torrus/xmlconfig directory.

    *   "output-bundle"

        Optional. Specifies a comma-separated list of XML file names for
        bundle output. Each bundle file will contain <include> statement for
        each corresponding "output-file".

    *   "snmp-ipversion", "snmp-transport", "snmp-port", "snmp-community",
        "snmp-version", "snmp-timeout", "snmp-retries", "snmp-host",
        "snmp-username", "snmp-contextname", "snmp-authkey",
        "snmp-authpassword", "snmp-authprotocol", "snmp-privkey",
        "snmp-privpassword", "snmp-privprotocol"

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

    *   "domain-name"

        Optional. Defines a DNS domain name to be appended to "snmp-host".

    *   "snmp-localaddr" and "snmp-localport"

        Optional parameters specifying the local socket binding address and
        port.

    *   "data-dir"

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

    *   "symbolic-name"

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

    *   "system-id"

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

    *   "nodeid-device"

        Optional. Defines the host-specific reference for *nodeid*. Default
        value is equal to "system-id".

    *   "snmp-oids-per-pdu"

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

    *   "snmp-check-sysuptime"

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

    *   "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).

    *   "snmp-maxrepetitions"

        Optional. If defined, it sets the maximum number of objects to
        return in SNMP getBulkRequest. The default value is 10.

    *   "host-subtree"

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

    *   "rrd-hwpredict"

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

    *   "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
        "EmpireSystemedge" module in order to run the discovery on those
        appliances.

    *   "only-devtypes"

        Optional comma-separated list of device types. If defined, only the
        specified types will be used for device probing. Also it
        automatically disables the SNMP reachability statistics unless
        "enable-reachability-stats" is set to "yes".

    *   "host-aliases"

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

    *   "custom-host-templates"

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

    *   "include-files"

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

    *   "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.

    *   "selectors"

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

    *   "disable-snmpcollector"

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

    *   "disable-reachability-stats"

        If set to "yes", the device reachability statistics are not enabled
        for this host.

    *   "enable-reachability-stats"

        If "only-devtypes" parameter is specified, the SNMP reachability
        statistics are disabled by default. If "enable-reachability-stats"
        is set to "yes", the reachability statistics are actvated in any
        case.

    *   "reachability-monitor"

        This parameter defines the monitor name which will be applied to
        device reachability statistics.

    *   "rrd-create-rra"

        This parameter overrides the default round-robin array definition
        for collector statistics. By default, we keep 5-minute details for 2
        weeks, 30-minute average and maximum details for 6 weeks, and 1-day
        aggregated stats for 2 years.

    *   "snmp-reachability-rra"

        This parameter overrides the round-robin array definitions for SNMP
        reachability statistics. By default, 5-minute data is stored for 3
        months, and daily averages are stored for 3 years.

    *   "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>

    *   "XXX-tokenset-rrgraph-view"

        For a tokenset XXX, specifies the value of "rrgraph-view" parameter.
        It defines the view name that is used to display graphs inside the
        tokenset.

    *   "suppress-legend"

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

    *   "comment"

        Sets the comment string for the host.

    *   "show-recursive"

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

    *   "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
        %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 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'
                     },
                 }};

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

    *   "RFC2863_IF_MIB::suppress-hc-counters"

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

    *   "RFC2863_IF_MIB::subtree-name"

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

    *   "RFC2863_IF_MIB::subtree-comment"

        Defines the comment string for interface counters subtree. Default:
        *Interface traffic and error counters*.

    *   "RFC2863_IF_MIB::list-admindown-interfaces"

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

    *   "RFC2863_IF_MIB::list-notpresent-interfaces"

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

    *   "RFC2863_IF_MIB::exclude-down-interfaces"

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

    *   "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.

    *   "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.

    *   "RFC2863_IF_MIB::tokenset-members"

        This parameter defines which interfaces' "InOut_bps" leaves to add
        to which tokensets. The value is a semicolon-separated (;) list of
        entries of form *tset:interface,interface*, where *tset* is a name
        of the tokenset, and the *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 "snmp-host" parameter) and slash sign (/):

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

    *   "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 *param*, the value for a particular interface *intf*
        will be taken from parameter "RFC2863_IF_MIB::*param*::*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>

    *   "RFC2863_IF_MIB::ifindex-map-hint"

        Optional. For a device that doesn't have a corresponding
        vendor-specific discovery module, this parameter would advice
        "devdiscover" how to build "ifTable" index mapping. By default, the
        interfaces are mapped by "ifDescr" values if they are unique, or
        "ifName" otherwise. If "ifName" is non-unique, "ifIndex" is taken as
        interface reference. For many vendors, this would not give reliable
        or convenient mapping. Valid values for the hint are: "ifName",
        "ifPhysAddress", and "ifIndex". The first two suggest the mapping by
        corresponding SNMP variables, and the third one should be used for
        devices with fixed "ifIndex" layout: in this case, the "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.

    *   "RFC2863_IF_MIB::ifnick-from-ifname"

        Optional. Before Torrus version 1.0.10, "interface-nick" parameter
        was derived from "ifName" values, even if they were non-unique. Now
        this interface nick is based on "ifName" only if it contains unique
        values. This discovery parameter, if set to "yes", restores the old
        behavior.

    *   "RFC2863_IF_MIB::subtree-name-hint"

        Optional. By default, per-interface subtrees are named after the
        values of "ifDescr" SNMP variables. If this option is set to
        "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. If "ifDescr" entries are non-unique on the device,
        but you still want to use them for subtree names, you need to
        specify this parameter explicitly with "ifDescr" as a value.

    *   "RFC2863_IF_MIB::name-hint"

        Optional. By default, human-readable interface names are taken from
        "ifDescr" SNMP values. It can be changed with this parameter.

    *   "RFC2863_IF_MIB::comment-hint"

        Optional. By default, interface descriptions are taken from
        "ifAlias" SNMP values. It can be changed with this parameter.

    *   "RFC2863_IF_MIB::nodeid-hint"

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

    *   "RFC2863_IF_MIB::sort-by-name"

        Optional. By default, interfaces are ordered by their ifindex, which
        can lead to not being ordered at all on devices where interfaces can
        come and go. Setting this parameter to "yes" drops the
        auto-generated *precedence* values and makes Torrus sort the
        interfaces alphabetically.

    *   "RFC2863_IF_MIB::noout"

        If set to "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.

    *   "RFC2863_IF_MIB::bandwidth-usage"

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

    *   "RFC2863_IF_MIB::bandwidth-limits"

        Defines the values (in megabits per second) for "bandwidth-limit-in"
        and "bandwidth-limit-out" interface parameters. Semicolon-separated
        list of (*Inteface name*:*Input limit*:*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>

    *   "RFC2863_IF_MIB::traffic-summaries",
        "RFC2863_IF_MIB::traffic-XXX-path",
        "RFC2863_IF_MIB::traffic-XXX-comment",
        "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
        "output-file" parameter value. "RFC2863_IF_MIB::traffic-summaries"
        defines a list of summary names, "RFC2863_IF_MIB::traffic-XXX-path"
        specifies the full path in the datasource tree to display the graph,
        optional "RFC2863_IF_MIB::traffic-XXX-comment" defines a descriptive
        comment for the graph, and "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 "name, name, ..." or at the
        global level in the form "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>

    *   "RFC2863_IF_MIB::disable-all"

        if set to "yes", disables processing of IF-MIB completely.

   Other generic MIB parameters
    *   "RFC2790_HOST_RESOURCES::sysperf-subtree-name"

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

    *   "RFC2670_DOCS_IF::upstreams-only"

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

    *   "RFC2670_DOCS_IF::disable-downstreams"

        If set to "yes", the DOCSIS downstream statistics are disabled.

    *   "RFC2670_DOCS_IF::suppress-all-cable-stats"

        If set to "yes", all DOCSIS interfaces are excluded from any cable
        or interface statistics.

    *   "RFC4293_IP_MIB::ipv4-stats", "RFC4293_IP_MIB::ipv6-stats"

        If set to "yes", IP-MIB statistics for the corresponding IP protocol
        version are included in discovery.

    *   "RFC4293_IP_MIB::tokenset-members",
        "RFC4293_IP_MIB::ipv4-external-serviceid",
        "RFC4293_IP_MIB::ipv6-external-serviceid"

        These parameters work for IP-MIB statistics the same way as
        corresponding parameters in RFC2863_IF_MIB.

   Vendor parameters
    *   "Albis_ULAF::mp-name-filter"

        If defined, the parameter shoudl specify a regular expression for
        SOAM MP names which should be excluded from discovery results.

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

        When set to "yes", the corresponding statistics are included or
        excluded from the graphs.

    *   "Arbor_E::enable-e30-bundle-name-rrd"

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

    *   "Apple_AE::disable-clients-stats"

        When set to "yes", wireless client machines are not tracked.

    *   "CiscoIOS::ifindex-persist"

        Set this to "yes" if the router is configured with "snmp-server
        ifindex persist" command. There is no way to verify via SNMP if this
        option is configured on the router, so it should be used with care.
        When enabled, this option enables ifIndex-based indexing of router
        interfaces, and the collector does not have to retrieve interface
        names from the device.

    *   "CiscoGeneric::disable-cpu-stats"

        When set to "yes", Cisco CPU usage statistics are excluded from
        discovery.

    *   "CiscoGeneric::disable-memory-pools"

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

    *   "CiscoGeneric::disable-sensors"

        When set to "yes", Cisco temperature sensors are excluded from
        discovery.

    *   "CiscoGeneric::use-fahrenheit"

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

    *   "CiscoGeneric::file-per-sensor"

        When set to "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.

    *   "CiscoGeneric::disable-psupplies"

        if set to "yes", Cisco power supply statistics are not collected.

    *   "CiscoGeneric::disable-system-ext-mib"

        if set to "yes", CPU and memory statistics from CISCO-SYSTEM-EXT-MIB
        are not used.

    *   "CiscoGeneric::power-monitor"

        Name of the power supply monitor for Cisco devices.

    *   "CiscoIOS::enable-membuf-stats"

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

    *   "CiscoIOS::disable-ipsec-stats"

        When set to "yes", IPSec statistics are excluded from discovery.

    *   "CiscoIOS::disable-bgp-stats"

        If set to "yes", BGP statistics are not included.

    *   "CiscoIOS::enable-vlan-interfaces"

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

    *   "CiscoIOS::enable-unrouted-vlan-interfaces"

        When set to "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.

    *   "CiscoIOS::enable-dialer-interfaces"

        If set to "yes", DialerX interfaces are included in discovery
        results.

    *   "CiscoCatOS::suppress-noname-ports"

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

    *   "CiscoIOS_MacAccounting::bgponly"

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

    *   "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.

    *   "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.

    *   "CiscoIOS_MacAccounting::tokenset-members"

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

    *   "CiscoIOS::disable-car-stats"

        When set to "yes", the Committed Access Rate statistics are disabled
        from discovery.

    *   "CiscoIOS::disable-vpdn-stats"

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

    *   "CiscoIOS::disable-port-qos-stats"

        If set to "yes", ME3400 Port QoS statistics are disabled.

    *   "CiscoIOS::short-device-comment"

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

    *   "CiscoSCE::disable-disk", "CiscoSCE::disable-gc",
        "CiscoSCE::disable-qos", "CiscoSCE::disable-rdr",
        "CiscoSCE::disable-subs", "CiscoSCE::disable-tp"

        If set to "yes", the corresponding statistics are excluded from
        Cisco SCE graphs.

    *   "CiscoWLC::only-ssid"

        Comma-separated list of SSID which are only allowed for discovery.
        By default, all SSID are allowed.

    *   "FTOS::disable-cpu", "FTOS::disable-power",
        "FTOS::disable-temperature"

        When set to "yes", disables the corresponding statistics category.

    *   "FTOS::use-fahrenheit", "FTOS::file-per-sensor"

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

    *   "JunOS::disable-cos", "JunOS::disable-cos-red",
        "JunOS::disable-cos-tail", "JunOS::disable-firewall",
        "JunOS::disable-operating", "JunOS::disable-rpf"

        When set to "yes", disables the corresponding statistics category
        for JunOS devices.

    *   "Liebert::disable-temperature", "Liebert::disable-humidity",
        "Liebert::disable-state", "Liebert::disable-stats"

        When set to "yes", disable the corresponding statistics category for
        Liebert devices.

    *   "Liebert::use-fahrenheit"

        When set to "yes", the temperature readings will be in fahrenheit.

    *   "NetBotz::temp-max", "NetBotz::humi-max", "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.

    *   "Paradyne::slot-name"

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

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

  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
    "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.

    *   "selectors"

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

    *   "S-selector-type"

        Type of objects to be selected. Supported values are:
        "RFC2863_IF_MIB", "CiscoCPU", "CiscoSensor", "ALU_SAP",
        "NetBotzSensor", "RFC2662_ADSL_LINE"

    *   "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 *RPN expressions in Torrus* guide. The attribute names
        are specific to the selector type and are described below.

    *   "S-A"

        For a given selector name "S" and attribute name "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.

    *   "S-selector-actions"

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

    *   "S-T-arg"

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

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

    *   "ifSubtreeName", "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.

    *   "ifComment"

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

    *   "ifType"

        Numeric IANA interface type, as returned by "ifType" SNMP variable.

    "ifType" is compared numerically. "ifSubtreeName" and "ifComment" are
    regular expressions. "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:

    *   "InBytesMonitor", "OutBytesMonitor"

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

    *   "InDiscardsMonitor", "OutDiscardsMonitor", "InErrorsMonitor",
        "OutErrorsMonitor"

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

    *   "NotifyPolicy"

        The argument defines the value for "notify-policy" parameter. See
        the manual for action_notify for more details.

    *   "HoltWinters"

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

    *   "NoPacketCounters", "NoDiscardCounters", "NoErrorCounters"

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

    *   "TokensetMember"

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

    *   "Parameters"

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

    *   "InBytesParameters", "OutBytesParameters"

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

    *   "AddTemplates"

        The argument is a comma-separated list of template names to add at
        the interface level. If a template is not seen in the DevDiscover's
        template registry, it produces a warning. See
        "template-registry-overlays" for more details about a proper way of
        adding custom templates.

    *   "RemoveInterface"

        This action excludes the matched interface from discovery results.
        No arguments needed.

    *   "DocsisUpSNRMonitor"

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

    *   "DocsisUpSNRTokenset"

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

    *   "DocsisUpFECCorMonitor"

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

    *   "DocsisUpFECUncorMonitor"

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

    *   "DocsisDownUtilMonitor"

        For a DOCSIS CMTS, this action assigns a monitor to the downstream
        "UsedBytes" counter.

    *   "DocsisMacModemsMonitor"

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

    *   "DocsisUpUtilMonitor", "DocsisUpSlotsMonitor"

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

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

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

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

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

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

    Actions supported: "Monitor", "TokensetMember".

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

    Attributes supported: "sapDescr" (regexp), "custDescr" (regexp),
    "sapName" (exact match), "sapPort" (exact match).

    Actions supported: "RemoveSAP" (excludes a selected SAP from the
    datasources).

   NetBotzSensor selector
    A selector of this type selects sensors on a NetBotz environment
    monitoring appliances.

    Attributes supported: "SensorLabel", "EnclosureLabel", "EnclosureID".
    Arguments are matched as regular expressions.

    Actions supported: "Monitor", "TokensetMember".

   RFC2662_ADSL_LINE selector
    This type of selector applies to ADSL line statistics.

    Attributes supported: "ifSubtreeName".

    Actions supported: "AtucSnrMonitor", "AturSnrMonitor", "AtucAtnMonitor",
    "AturAtnMonitor", "AtucAttRateMonitor", "AturAttRateMonitor",
    "AtucTxRateMonitor", "AturTxRateMonitor", "AtucLofsMonitor",
    "AturLofsMonitor", "AtucLossMonitor", "AturLossMonitor",
    "AtucLprsMonitor", "AturLprsMonitor", "AtucESsMonitor",
    "AturESsMonitor", "AtucInitsMonitor".

   RFC4293_IP_MIB_v4 and RFC4293_IP_MIB_v6 selectors
    These selectors apply to the IP-MIB statistics if they are present on
    the device and their discovery is activated by
    "RFC4293_IP_MIB::ipv4-stats" or "RFC4293_IP_MIB::ipv6-stats" parameters.

    Attributes supported: "ifSubtreeName".

    Actions supported: "InBytesMonitor", "OutBytesMonitor",
    "InBytesParameters", "OutBytesParameters", "TokensetMember"

   Examples
    The following example applies a monitor called "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
    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"/>

    This example excludes all non-Gigabit ports from discovery results:

      <host>
        <param name="snmp-host"                 value="router001"/>
        <param  name="output-file"              value="routers/router001.xml"/>
        <param name="selectors"                 value="NotGigE" />
        <param  name="NotGigE-selector-type"    value="RFC2863_IF_MIB"  />
        <param name="NotGigE-selector-expr"     value="{ifSubtreeName},NOT"  />
        <param  name="NotGigE-ifSubtreeName"    value="^Gigabit" />
        <param  name="NotGigE-selector-actions" value="RemoveInterface" />
      </host>

    The following example sets the SNR monitoring on ADSL line statistics:

      <param name="selectors" value="AdslMon" />
      <param  name="AdslMon-selector-type"    value="RFC2662_ADSL_LINE"/>
      <param  name="AdslMon-selector-actions">
         AtucSnrMonitor,
         AturSnrMonitor
      </param>
      <param name="AdslMon-AtucSnrMonitor-arg" value="adsl-snr-6db"/>
      <param name="AdslMon-AturSnrMonitor-arg" value="adsl-snr-6db"/>

Author
    Copyright (c) 2002-2011 Stanislav Sinyagin <ssinyagin@k-open.com>

