This is a generic SNMP (Simple Network Management Protocol) module.

Note: this module internally uses 64 bit row numbers and therefore requires Tcl/Tk 8.4 or above (which is already the case if you are reading this from a running moodss application).

It requires the Tnm Tcl extension package (from the Scotty Tcl extension software) to be installed on the computer (on Windows, use the latest release from http://spog.gaertner.de/~schoenfr/scotty/).

Data is initially displayed in one or several tables, with one column per object identifier (see the -i (--identifiers) option).

This module can either display a SNMP table or a set of discrete objects.

If the -t (--table) option is used, then the corresponding SNMP table data is displayed in a table. The -i (--identifiers) option can be used to constrain the display to a subset of the table columns, and eventually split the data into several views.
If the SNMP table index consists of a single object, then the corresponding column will be used as the index of the displayed table(s), else a specific column containing a row creation unique number is generated. In either case, the index column is inserted, or placed if already specified in the identifiers list (see -i (--identifiers) option), at the leftmost position in each of the displayed tables.

If the -t (--table) option is not used, then the -i (--identifiers) option specifies a list of identifiers which can contain groups but no table. When a group is part of the list of objects, it is expanded into a list of its immediate successor identifiers. In this case, only the accessible identifiers are displayed. Data can be split in different views. All displayed data tables use a swapped layout, with 2 columns: identifiers on the left side and their values on the right side.

Data is displayed as returned by the SNMP peer after formatting by the Scotty SNMP engine, except for the objects of the counter type, which are displayed as per second values, calculated by dividing the difference between 2 poll values by the actual time difference between the two last polls. The SNMP agent system uptime value is used for most precise calculations.

Of course, you can, as with any other moodss module, specify several instances of this module in the command line to monitor as many SNMP peers as desired, and even combine with trap views using the related snmptrap module.

This document includes extracts from the Scotty documentation. The Scotty software is copyrighted by Juergen Schoenwaelder, the Technical University of Braunschweig, the University of Twente and other parties (please refer to the Scotty license for further information).

Error handling:

When there is a communication error with the remote host, all rows disappear and the displayed table becomes empty. A descriptive error message is also generated in such a case.

Module options:

• -a (--address)
  Defines the network address of the SNMP peer. The value of address may be an IP address in dotted notation (e.g. 134.169.34.1) or a hostname that can be resolved to an IP address. The default address is 127.0.0.1.
• --community
  Specific for SNMPv1 and SNMPv2C sessions. It defines the community string which is used to identify the sender of SNMP messages. The default community string is "public".
• --context
  Specific to SNMPv2U sessions. It allows to select between multiple contexts. The default context is "".
• --delay
  Can be used to define a delay in milliseconds between two messages send by the SNMP protocol engine. This can be used to avoid network congestion problems. The default delay is 0 milliseconds.
• --directory
  Optional. Directory where MIB files can be found.
  If there are no files specified using the --mibs switch, all files with the mib extension in the specified directory are loaded.
  If there are files specified using the --mibs switch, the specified directory is used as base directory for those files without directory.
• -i (--identifiers)
  A comma separated list of SNMP object identifiers (no blank characters allowed).
  If the -t (--table) is used, all identifiers must belong to the same MIB table, meaning that they must all be listed in the table entry or be part of the table index.
  If the -t (--table) is not used, identifiers may contain instanced identifiers or groups which are then expanded into their immediate accessible children, but no table.
  The option value may be a list of identifiers separated by single commas with double commas separating table views (see examples).
• --mibs
  A comma separated list of files containing valid MIB definitions. The mib extension is automatically used for specified files without extension.
  Parsing errors are written to stderr. The MIB files are usually located at the file system position defined by the file argument. However, if file is a simple file name and it does not exist in the current directory, than it will be searched in $tnm(library)/site and $tnm(library)/mibs in this order.
  If there is a directory specified using the --directory switch, it is used as base directory for specified MIB files without directory.
• --port
  Defines the UDP port which is used by the SNMP peer to receive SNMP messages. The value of port may be a port number or a service name which can be resolved to a port number. The default port number is 161.
• --password
  Specific to SNMPv2U sessions. It is used to specify the password of the user. The password is automatically converted into a key by applying the password2key algorithm of RFC 1910. The key is also automatically localized once the agentID of the SNMP agent is known. Note that the application should take care to keep the passwords safe from unauthorized access. An empty password turns SNMPv2U authentication off. The default password is "".
• --retries
  Defines how many times a request is retransmitted during the timeout interval. The default number of retries is 3.
• -t (--table)
  A MIB table identifier.
  If no identifiers are specified with the -i (--identifiers) option, then a single data table is displayed, with as many columns as there are objects in the MIB table entry, plus eventually a specific row number column if necessary.
• --timeout
  Defines the time the session will wait for a response. The time is defined in seconds with a default of 5 seconds.
• --title
  Sets the initial data table(s) window(s) title(s). Without this option, the title is simply snmp. The valid values for this option are: a, t or any combination of those 2 letters. When a is specified, the agent address is displayed, whereas with t, the SNMP table identifier is displayed.
  For example, when at is used, the title is set to snmp(address,table).
• --trace
  On standard output, display SNMP requests and responses in the form of object identifiers and their values.
• --trim
  Remove when possible, leading text from displayed identifier names used as table(s) column titles (see examples).
• --user
  Specific to SNMPv2U sessions. It is used to define the SNMP user name. The default user name is "public".
• --version
  Selects the SNMP version used by a SNMP session. The currently supported version numbers are 1 (SNMPv1, RFC 1157 style SNMP), 2C (SNMPv2C, RFC 1901 style SNMP) and 2U (SNMPv2U, RFC 1910 style SNMP). The default SNMP version is 1.
• --window
  Allows to define a window which limits the number of active asynchronous requests. This can be used to prevent fast scripts to flood an agent with asynchronous messages. The Tnm extension queues requests internally so that no more than size asynchronous requests are on the wire. Setting the size to 0 turns the windowing mechanism off. The default window size is 10 messages.

Examples:

$ moodss snmp -t ipAddrTable
$ moodss snmp -a 134.169.34.1 --mibs rfc1213.mib -t ifTable

$ moodss snmp --trim if -a 134.169.34.1 -t ifTable -i ifDescr,ifType,ifMtu,ifSpeed,ifOperStatus,,ifInOctets,ifInErrors,ifOutOctets,ifOutErrors

$ moodss snmp --trim frCircuit -a router.mycompany.com --mibs rfc1212.mib,/home/jdoe/mibs/rfc1315.mib -t frCircuitTable -i frCircuitDlci,frCircuitThroughput,frCircuitState,frCircuitReceivedOctets,frCircuitSentOctets
$ moodss snmp --trim sys -a router.mycompany.com -i system
$ moodss snmp -i system,,interfaces,,tcp
$ moodss snmp --trim if -i ifDescr.1,ifType.1,ifSpeed.1,ifOperStatus.1,,ifInOctets.1,ifInErrors.1,ifOutOctets.1,ifOutErrors.1
$ moodss snmp -a 134.169.34.1 --identifiers sysUpTime.0,sysDescr.0,sysName.0
$ moodss snmp -i system --directory /usr/lib/tnm2.1.11/mibs
$ moodss snmp -i sysDescr,hrSystemProcesses --mibs rfc1213,rfc1514
$ moodss snmp -i someOid --directory /some/dir --mibs custom,test.my