SNMP Plugin Reference/en
SNMP Plugin
The SNMP plugin lets a test suite talk to SNMP capable equipment - routers, switches, printers, servers, UPS units, sensors - and receive the notifications such a device sends. It delivers the SNMP Library, whose blocks cover the manager side of SNMP v1, v2c and v3: reading and writing objects, walking subtrees, reading whole tables, resolving MIB names, and receiving as well as sending traps.
Everything is implemented in expecco itself. No net-snmp installation and no other external library is needed, and the blocks behave the same on every supported platform.
The SNMP Library
The blocks are found in the library "SNMP Library", grouped into six categories. Every block carries its own documentation, every pin explains what it expects, and every block has a Test/Demo network which shows it in use.
SNMP Connection
- Open SNMP Session - open a session to a device with SNMP v1 or v2c, using a community string.
- Open SNMPV3 Session - open an SNMPv3 session with a user name, an authentication and an encryption protocol, and the two passphrases. The context name and context engine id can be given for agents which partition their MIB into contexts.
- Close SNMP Session - release the session and its socket.
- SNMP Timeout/Retries - how long to wait for an answer and how often to repeat a request.
- SNMP Session Info - which host, port, version, community and context a session handle refers to.
- SNMP Last Error - why the last request did not deliver a value, as a symbolic reason (noResponse, timedOut, noSuchName, wrongDigest, notWritable, ...).
- SNMP Max Repetitions - how many objects one GetBulk request asks for; this is what a walk uses.
SNMP Requests
- SNMP Get / SNMP Get Next / SNMP Get Bulk - read one object, the object following it, or a batch of following objects.
- SNMP Get Subtree - walk everything below an object (for instance the whole system group or an entire table) and answer it as an oid to value dictionary.
- SNMP Set - write one object. Without an explicit type the type is taken from the MIB definition, and the object is read back afterwards, so the outputs show what the agent really stored.
- SNMP Multi Get / Multi Get Next / Multi Get Bulk / Multi Set - the same for several objects in ONE request, which is much faster than asking one by one.
- SNMP Get with Default - read an object which only some devices implement, answering a default instead of failing.
- Read SNMP Table - read a whole conceptual table (ifTable, ipAddrTable, tcpConnTable, ...) and answer its rows in index order. The rows are also delivered one by one, so a following step can run once per row.
- Table Row Value / Table Row Index / Table Row as Dictionary - read a column of a row by name or number, the decoded INDEX of a row, or the whole row as a columnName to value dictionary.
- SNMP Get on Hosts / SNMP Multi Get on Hosts - ask many devices the same question at once. The hosts are queried in parallel, so the block takes about as long as the slowest device rather than the sum of all of them; a host which does not answer is reported, not an error.
MIB Access
- Name to OID / OID to Name - translate between a MIB name (sysDescr.0, SNMPv2-MIB::sysDescr.0) and the numeric object identifier.
- Resolve OIDs in Dictionary Keys / ... Values - replace the OIDs in the result of a walk or a multi get by their MIB names, which is what makes such a result readable in the report.
- Describe MIB Object - what the MIB knows about an object: full name, syntax, access, status, unit, the labels of an enumerated INTEGER, and whether it is a table or a table row with its INDEX.
MIB Management
- Add MIB Directory - parse the MIB files of a directory and add them, so vendor specific names can be used in the other blocks.
- Shutdown MIB - forget everything read from MIB files; the next name to resolve reads them again.
SNMP Traps
- Start Trap Listener - listen for notifications on a UDP port. The standard port 162 needs root privileges on unix, so an unprivileged port such as 11162 is often used.
- Wait for Trap - wait for the next notification and answer its sender, version, identifier (resolved through the MIB) and all its variables. Notifications which arrived before the block ran are not lost, and an inform request is acknowledged automatically.
- Stop Trap Listener - stop listening and release the port.
- Send Trap - send a notification to a trap receiver, as a plain trap or as an inform request which the receiver has to acknowledge.
Protocol versions and security
SNMP v1 and v2c identify the caller with a community string, which travels in clear text.
SNMP v3 authenticates and encrypts with the User-based Security Model. Supported protocols:
- authentication: md5 and sha1 (RFC 3414), and the SHA-2 protocols sha224, sha256, sha384 and sha512 (RFC 7860). Current net-snmp builds refuse MD5, so prefer SHA-256.
- encryption: des and aes128 (RFC 3826). Encryption is only possible together with authentication.
Engine discovery and the clock synchronisation an authenticated session needs happen automatically.
MIBs
A current set of MIB modules is delivered with the library, so the usual names - those of SNMPv2-MIB, IF-MIB, IP-MIB, TCP-MIB, UDP-MIB, HOST-RESOURCES-MIB and many more - resolve without any setup. Vendor MIBs are added with "Add MIB Directory", either from a directory of your own or from ~/.snmp/mibs, which is read automatically.
The deprecated RFC1213-MIB groups at, egp and ipRouteTable are not part of the delivered set; objects below them are shown numerically. Their replacements are ipNetToMediaTable, ipCidrRouteTable and inetCidrRouteTable. If a device really needs the old names, drop RFC1213-MIB.txt into a MIB directory.
Reading a table
"Read SNMP Table" answers the rows of a conceptual table. A row knows its columns by name and the INDEX which identifies it, and "Table Row Index" decodes that INDEX as the MIB defines it - the interface number for ifTable, the IP address for ipAddrTable, the four parts of a connection for tcpConnTable. Values arrive as Smalltalk objects: a counter as a number, an ifOperStatus as its label (up, down), an IP address as an address, sysUpTime as a time duration.
Traps and informs
A test can wait for a notification instead of polling: start a listener, let the device do whatever should trigger the trap, and read it with "Wait for Trap". Traps of all three versions are accepted; for SNMPv3 the sender is the authoritative engine, so the listener localizes the keys per sending device by itself. Notifications which do not authenticate, or whose community is not accepted, are dropped silently.
An inform request is acknowledged automatically, and "Send Trap" can send one, so a suite can also play the role of the device.
Test/Demo networks
Every block has a Test/Demo network. The ones which need a device use these environment variables of the library, so that one place decides which equipment the demos talk to:
| Variable | Meaning |
|---|---|
| DemoSNMPHost | the device the demos read from |
| DemoSNMPCommunity | the community string used for v1 / v2c |
| DemoSNMPV3User | the SNMPv3 user name |
| DemoSNMPV3AuthPassphrase | its authentication passphrase (the demo agent uses SHA-256) |
| DemoSNMPV3PrivPassphrase | its encryption passphrase (the demo agent uses AES-128) |
Change them to a device of your own before running the demos. The trap demos need nothing on the network - they start a listener, send themselves a trap and read it back.