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