This is a 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 MIB Smithy SDK library from Muonics (commercial software) to be installed on the computer. A usable demonstration library can be downloaded for testing this module from http://www.muonics.com/Products/MIBSmithySDK/.
The MIB Smithy SDK is a dynamic Tcl/Tk extension for developing SNMP management scripts and custom MIB compiler/conversion tools. It directly supports all features of both the SMIv1 and SMIv2 MIB modules language, as well as XML modules generated by MIB Smithy Pro/Standard editions, and provides APIs for complete read-write access to all aspects of MIB module definitions. The SDK also provides SNMP management APIs supporting SNMPv1, SNMPv2c and SNMPv3 with both HMAC-SHA-96 and HMAC-MD5-96 authentication and CBC-DES privacy.
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 MIB Smithy SDK library, 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.
This document includes extracts from the MIB Smithy SDK documentation with the permission from Muonics (MIB Smithy SDK is a trademark of Muonics ; Copyright © 2003 Muonics ; All Rights Reserved).
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.
- -a (--address)
Specify the remote IP address or host name to send requests to. If a host name is specified, the SDK will attempt to resolve the name to an IP address via DNS. An error will result if the hostname does not resolve. Default: 127.0.0.1.
Specifies the password to be used when sending authenticated SNMPv3 messages. The SDK will automatically convert the password to a localized key internally, according to the configured Authentication Protocol, when it discovers the agent's Engine ID. If the Authentication Protocol or Engine ID change, the password will be automatically reconvered and re-localized. The value can either be an ASCII string or a colon-delimited hex string (e.g. "0x01:02:ab:cd"). Default: not set - authentication disabled.
Specifies the Authentication Protocol to use when sending SNMPv3 authNoPriv and authPriv messages if an Authentication Password has been set. If no password is set, the state of this parameter is ignored and all SNMPv3 messages are sent noAuthNoPriv. Accepted values are HMAC-SHA-96 and HMAC-MD5-96, or short forms MD5 or SHA (long form recommended). Default: HMAC-MD5-96.
Specifies the community string to be used when sending SNMPv1 and SNMPv2c GET, GET-NEXT and GET-BULK requests. The value can either be an ASCII string or a colon-delimited hex string (e.g. "0x01:02:ab:cd"). Default: public.
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).
A license key file is required for the MIB Smithy SDK library. The library will attempt to locate the file automatically, but its location may be specified explicitly by using this option or alternately setting the SMITHY_LICENSE_FILE environment variable to the full path name of the file.
A comma separated list of files containing valid MIB definitions. The mib extension is automatically used for specified files without extension.
If there is a directory specified using the --directory switch, it is used as base directory for specified MIB files without directory.
Specify the remote port send requests to. By default, most SNMP agents accept requests on port 161, although many allow the agent to be configured to listen on a different port. Default: 161.
Specifies the password to be used when sending private (encrypted) SNMPv3 messages. The SDK will automatically convert the password to a localized key internally, according to the configured Privacy Protocol, when it discovers the agent's Engine ID. If the Privacy Protocol or Engine ID change, the password will be automatically reconvered and re-localized. The value can either be an ASCII string or a colon-delimited hex string (e.g. "0x01:02:ab:cd"). Default: not set - privacy disabled.
Specifies the Privacy Protocol to use when sending SNMPv3 authPriv messages if a Privacy Password has been set. If no password is set, the state of this parameter is ignored and all SNMPv3 messages are sent using authNoPriv or noAuthNoPriv depending on whether or not an authentication password has been configured. Accepted values are CBC-DES or short form DES (long form recommended). Default: CBC-DES.
Specifies the number of attempts that should be made to retransmit requests that have not been received after the first try. If non-zero, then a total of (retries + 1) attempts will be made before signalling a timeout to the script. The SDK can be configured to retry the request up to 30 times. Default: 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.
Specifies the timeout (in seconds) to wait after sending a request before considering the message to have been dropped. The total time that the SDK will wait for a response before signalling a timeout to the script is ((retries + 1) * timeout). The maximum time to wait for a response to an individual attempt is 300 s (5 minutes). Default: 5 seconds.
Sets the initial data table(s) window(s) title(s). Without this option, the title is simply smithy. 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 smithy(address,table).
On standard output, display SNMP requests and responses in the form of object identifiers and their values.
Remove when possible, leading text from displayed identifier names used as table(s) column titles (see examples).
Specifies the SNMPv3 User Name to use when sending messages using the User-Based Security Model, regardless of security level. The value can either be an ASCII string or a colon-delimited hex string (e.g. "0x01:02:ab:cd"). Default: not set/zero-length.
Selects the SNMP version used by a SNMP session. The currently supported version numbers are 1 (SNMPv1), 2C (SNMPv2C) and 3 (SNMPv3). Default: SNMPv1.
$ moodss smithy -t ipAddrTable
$ moodss smithy -a 126.96.36.199 --mibs rfc1213.mib -t ifTable
$ moodss smithy --trim if -a 188.8.131.52 -t ifTable -i ifDescr,ifType,ifMtu,ifSpeed,ifOperStatus,,ifInOctets,ifInErrors,ifOutOctets,ifOutErrors
creates the following 2 tables:
$ moodss smithy --directory /usr/lib/smithysdk/samples --trim frCircuit -a router.mycompany.com --mibs rfc1212.mib,/home/jdoe/mibs/rfc1315.mib -t frCircuitTable -i frCircuitDlci,frCircuitThroughput,frCircuitState,frCircuitReceivedOctets,frCircuitSentOctets
$ moodss smithy --directory /usr/lib/smithysdk/samples --trim sys -a router.mycompany.com -i system
$ moodss smithy --directory /usr/lib/smithysdk/samples -i system,,interfaces,,tcp
$ moodss smithy --directory /usr/lib/smithysdk/samples --trim if -i ifDescr.1,ifType.1,ifSpeed.1,ifOperStatus.1,,ifInOctets.1,ifInErrors.1,ifOutOctets.1,ifOutErrors.1
$ moodss smithy --directory /usr/lib/smithysdk/samples -a 184.108.40.206 --identifiers sysUpTime.0,sysDescr.0,sysName.0
$ moodss smithy --directory /usr/lib/smithysdk/samples --mibs rfc1213,rfc1514 -i sysDescr,hrSystemProcesses
$ moodss smithy --directory /usr/lib/smithysdk/samples --mibs custom,test.my -i someOid
$ moodss smithy --keyfile /usr/license.key --directory /usr/lib/smithysdk/samples -t ifTable