Net-SNMP Command-Line Tools (Essential SNMP)

C.3.1. snmpwalk

snmpwalk performs the get-next operation. We've used it throughout the book, so it should be familiar; in this section, we'll use it to demonstrate some of the options introduced in Table C-1.

Let's say you want to perform an snmpwalk against a Cisco router. If you don't have any Cisco MIBs installed, here's what you will see:

$ snmpwalk cisco.ora.com public .1.3.6.1.4.1.9
enterprises.9.2.1.1.0 = "..System Bootstrap, Version 11.2(17)GS2, [htseng 180] 
EARLY DEPLOYMENT RELEASE SOFTWARE (fc1)..Copyright (c) 1999 by Cisco Systems, 
Inc..."
enterprises.9.2.1.2.0 = "reload"
enterprises.9.2.1.3.0 = "cisco"
enterprises.9.2.1.4.0 = "ora.com"
enterprises.9.2.1.5.0 = IpAddress: 127.45.23.1
enterprises.9.2.1.6.0 = IpAddress: 0.0.0.0
enterprises.9.2.1.8.0 = 131890952
enterprises.9.2.1.9.0 = 456
enterprises.9.2.1.10.0 = 500
enterprises.9.2.1.11.0 = 17767568
enterprises.9.2.1.12.0 = 0
enterprises.9.2.1.13.0 = 0
enterprises.9.2.1.14.0 = 104
enterprises.9.2.1.15.0 = 600
...

Recall that .1.3.6.1.4.1 is .iso.org.dod.internet.private.enterprises, and 9 is Cisco's private enterprise number. Therefore, the previous command is walking the entire Cisco subtree, which is very large; we've deleted most of its output. The output you see isn't very readable because we haven't yet installed the Cisco MIBs, so the snmpwalk command has no way of providing human-readable object names. We just have to guess what these objects are.

This problem is easy to solve. Copy the Cisco MIBs [79] to the main Net-SNMP repository (/usr/local/share/snmp/mibs) and use the -m ALL command-line option. With this option, snmpwalk parses all the files in the MIB repository. As a result we get the object IDs in string (human-readable) form, and we can walk the cisco subtree by name rather than specifying its complete numeric object ID (.1.3.6.1.4.1.9):

[79] You can find many Cisco MIBs at ftp://ftp.cisco.com/pub/mibs/.

$ snmpwalk -m ALL cisco.ora.com public cisco
enterprises.cisco.local.lcpu.1.0 = "..System Bootstrap, Version 11.2(17)GS2, 
[htseng 180] EARLY DEPLOYMENT RELEASE SOFTWARE (fc1)..Copyright (c) 1999 by Cisco 
Systems, Inc..."
enterprises.cisco.local.lcpu.2.0 = "reload"
enterprises.cisco.local.lcpu.3.0 = "cisco"
enterprises.cisco.local.lcpu.4.0 = "ora.com"
enterprises.cisco.local.lcpu.5.0 = IpAddress: 127.45.23.1
enterprises.cisco.local.lcpu.6.0 = IpAddress: 0.0.0.0
enterprises.cisco.local.lcpu.8.0 = 131888844
enterprises.cisco.local.lcpu.9.0 = 456
enterprises.cisco.local.lcpu.10.0 = 500
enterprises.cisco.local.lcpu.11.0 = 17767568
enterprises.cisco.local.lcpu.12.0 = 0
enterprises.cisco.local.lcpu.13.0 = 0
enterprises.cisco.local.lcpu.14.0 = 104
enterprises.cisco.local.lcpu.15.0 = 600
...

Now let's trim the output by adding the -Os option, which omits the initial part of each OID:

$ snmpwalk -m ALL -Os cisco.ora.com public cisco
lcpu.1.0 = "..System Bootstrap, Version 11.2(17)GS2, [htseng 180] EARLY 
DEPLOYMENT RELEASE SOFTWARE (fc1)..Copyright (c) 1999 by Cisco Systems, Inc..."
lcpu.2.0 = "reload"
lcpu.3.0 = "cisco"
lcpu.4.0 = "ora.com"
lcpu.5.0 = IpAddress: 127.45.23.1
lcpu.6.0 = IpAddress: 0.0.0.0
lcpu.8.0 = 131888844
lcpu.9.0 = 456
lcpu.10.0 = 500
lcpu.11.0 = 17767568
lcpu.12.0 = 0
lcpu.13.0 = 0
lcpu.14.0 = 104
lcpu.15.0 = 600
...

This output is a little easier to read, since it cuts off the redundant part of each OID. Let's take this command one step further:

$ snmpwalk -OsS cisco.ora.com public system
RFC1213-MIB::sysDescr.0 = "Cisco Internetwork Operating System Software ..IOS (tm)
GS Software (GSR-K4P-M), Version 12.0(15)S, EARLY DEPLOYMENT RELEASE SOFTWARE 
(fc1)..TAC Support: http://www.cisco.com/cgi-bin/ibld/view.pl?i=support..
Copyright (c) 1986-2001 by Cisco Systems, Inc..."
RFC1213-MIB::sysObjectID.0 = OID: DTRConcentratorMIB::catProd.182
EXPRESSION-MIB::sysUpTimeInstance = Timeticks: (344626986) 39 days, 21:17:49.86
RFC1213-MIB::sysContact.0 = "O'Reilly Data Center"
RFC1213-MIB::sysName.0 = "cisco.ora.com"
RFC1213-MIB::sysLocation.0 = "Atlanta, GA"
RFC1213-MIB::sysServices.0 = 6
RFC1213-MIB::system.8.0 = Timeticks: (0) 0:00:00.00

This command walks the system subtree. Since the system group falls under mib-2, there is no need to use -m ALL; mib-2 is one of the MIBs the Net-SNMP tools load automatically. Adding S to the -O option instructs the command to prefix each line of output with the name of the MIB file; we see that each line begins with RFC1213-MIB, which is the name of the file that defines mib-2.

C.3.2. snmpget

The snmpget command issues a single get operation. Its syntax is:

snmpget options hostname community objectID...

C.3.3. snmpbulkget

SNMPv2 provides an operation called get-bulk, which is implemented by the snmpbulkget command. get-bulk allows you to retrieve a chunk of information in one operation, as opposed to a single get or sequence of get-next operations. The syntax of snmpbulkget is:

snmpbulkget -v 2c options hostname community objectID

-v 2c is required because get-bulk is defined by SNMP Version 2.

There is one command-specific option, -B nonrep rep. nonrep is the number of scalar objects that this command will return; rep is the number of instances of each nonscalar object that the command will return. If you omit this option the default values of nonrep and rep, 1 and 100, respectively, will be used.

C.3.4. snmpbulkwalk

The snmpbulkwalk command uses the get-bulk command sequence to retrieve parts of a MIB. This command differs from snmpbulkget in that it does not need the -B option set; it walks the entire tree until it reaches the end or retrieves all the requested objects. Its syntax is:

snmpbulkwalk -v 2c options hostname community objectID

C.3.5. snmpset

The snmpset command is used to change, or set, the value of a MIB object. The command looks like this:

snmpset options hostname community objectID type value...

You can provide any number of objectID/type/value triples; the command will execute set operations for all the objects you give it. type is a single-character abbreviation that indicates the datatype of the object you're setting. Table C-2 lists the valid types.

Table C-2. snmpset Object Types

Abbreviation	Type
`a`	IP address
`b`[80]	Bits
`d`	Decimal string
`D`	Double
`F`	Float
`i`	Integer
`I`	Signed int64
`n`	Null
`o`	Object ID
`s`	String
`t`	Time ticks
`u`	Unsigned integer
`U`	Unsigned int64
`x`	Hexadecimal string

[80]While the manpages show this as a valid datatype, the help output from the command does not.

C.3.6. snmptrap

To send a trap, use the snmptrap command. The syntax for this command is:

snmptrap options hostname community trap parameters...

For Version 1, the following trap parameters are required:

enterprise-oid agent trap-type specific-type uptime objectID type value...

This command is discussed in detail in Chapter 10, "Traps". Each object ID/type/value triplet specifies a variable binding to be included with the trap; you may include any number of variable bindings. Note that the agent and the uptime are not optional; however, if you provide an empty string ("") as a placeholder they default to the IP address of the system sending the trap and the system's current uptime.

The parameters are simpler for Version 2 traps, largely because traps (now called notifications) are full-fledged MIB objects in their own right. The following parameters are required:

snmptrap -v 2c options hostname community uptime trapoid objectID type value...

C.3.7. snmpdelta

The snmpdelta command monitors OIDs and tracks changes in OID values over time. Its syntax is:

snmpdelta options hostname community objectID...

snmpdelta requires you to specify the OID of an integer-valued scalar object -- it can't monitor tables. For example, if you want to want to watch the octets arriving on an interface, you can't just specify ifInOctets; you must specify the interface number in addition to the object name (e.g., ifInOctets.3). By default, snmpdelta polls the given object every second.

Table C-3 lists some of the snmpdelta-specific options. There are many problems with the documentation for this command, but if you stick to the options listed below you should be on firm ground.

Table C-3. snmpdelta Options

Option	Description
-t	The documentation says "Determine time interval from the monitored entity." It's not clear what this means, but you seem to need this entry to get nonzero readings.
-s	Display a timestamp with every set of results.
-m	Print the maximum value obtained.
-l	Write the output to a file. The filename is in the form hostname-OID. For example, if you want to monitor the variables ifInOctets.3 and ifOutOctets.3 on the host router, the -l option will create two files, hostname-ifInOctets.3 and hostname-ifOutOctets.3, where the output of snmpdelta will be written. (Note that this output has no apparent connection to the configuration, as the documentation claims.)
-p	Specify the polling interval (the default is 1 second).
-T	Print output in tabular format.

C.3.8. snmpdf

snmpdf works exactly like the Unix df command, except it uses SNMP to query hosts on a network. Its syntax is:

snmpdf -Cu options... hostname community

The -Cu option tells the command to consult the Net-SNMP private MIB. The Host Resources MIB is used by default.

C.3.9. snmpgetnext

The snmpgetnext command uses the get-next operation to retrieve the next object from a host. For example, if you ask it to perform a get-next for ifOutOctets.4 it will retrieve the next object in the MIB tree, which will probably be ifOutOctets.5. (If the machine you're polling has only four interfaces, you'll get the next object in the MIB, whatever that happens to be. You should also be aware that there are some obscure situations that create a "hole" in the interface table, so the interface following .4 might be .6 or .7.) You can use this command to implement your own version of snmpwalk. The syntax is:

snmpgetnext options... hostname community objectID...

There are no options specific to snmpgetnext.

C.3.10. snmpstatus

The snmpstatus command retrieves status information from a host. It prints the following information:

The IP address of the entity
A textual description of the entity (sysDescr.0)
The uptime of the entity (sysUpTime.0)
The sum of received packets on all interfaces (ifInUcastPkts.* + ifInNUcastPkts.* )
The sum of transmitted packets on all interfaces (ifOutUcastPkts.* + ifOutNUcastPkts.* )
The number of IP input packets (ipInReceives.0)
The number of IP output packets (ipOutRequests.0)

The syntax of snmpstatus is straightforward, and there are no command-specific options:

snmpstatus options... hostname community

C.3.11. snmptable

The snmptable command uses get-next commands to print the contents of a table in tabular form. Its syntax is:

snmptable options... hostname community objectID

The objectID must be the ID of a table (e.g., ifTable), not of an object within a table. Table C-4 lists some of the snmptable-specific options.

Table C-4. snmptable Options

Option	Description
-Cf F	Separate table columns with the string F. For example, -Cf : separates columns with a colon, which might make it easier to import the output from snmptable into another program.
-Cw W	Set the maximum width of the table to W. If the lines are longer than W, the table is split into sections. Since tables can have many columns, you almost certainly want to use this option.
-Ci	Prepend the index of the entry to all printed lines.
-Cb	Display a brief heading.
-Ch	Print only column headers.
-CH	Suppress column headers.

C.3.12. snmpusm

The snmpusm command provides simple access to the agent's User-based Security Model (USM) table. This is primarily used for configuring the agent's SNMPv3 features (managing users, setting and changing passphrases, etc.). This command is discussed in Appendix F, "SNMPv3".

C.3.13. snmpconf

This command is an interactive Perl script used to create and maintain the Net-SNMP configuration files, snmp.conf and snmpd.conf. Its syntax is:

snmpconf filename

filename must be either snmp.conf or snmpd.conf.

C.3.14. snmpinform

This command can be used to send an SNMPv2 trap. If you send a trap with snmpinform, it will wait for a response from the recipient. Note that you can send an inform using the snmptrap command if you specify -Ci. The options to snmpinform are identical to those for snmptrap.

C.3.15. snmptranslate

The Net-SNMP package comes with a handy tool called snmptranslate that translates between numerical and human-readable object names. More generally, it can be used to look up information from MIB files. Its syntax is:

snmptranslate options objectID

snmptranslate does not perform queries against any device, so it doesn't need the hostname or community parameters. Its sole purpose is to read MIB files and produce output about specific objects. Before looking at examples, it's worth noting that snmptranslate's interpretations of the -O options are, to be kind, interesting. To speak more plainly, they're just plain wrong. The following examples show what actually happens when you use these options -- we'll leave the rationalization to you. We expect these problems to be fixed in some later version of Net-SNMP.

Let's say you want to know the enterprise OID for Cisco Systems. The following command does the trick:

$ snmptranslate -m ALL -IR -Of cisco
.1.3.6.1.4.1.9

This tells us that Cisco's enterprise OID is .1.3.6.1.4.9. Note the use of the -IR option, which tells snmptranslate to do a random-access search for an object named cisco. If you leave this option out, snmptranslate will fail because it will try to locate cisco under the mib-2 tree.

Let's say you want to take .1.3.6.1.4.1.9 and convert it to its full symbolic name. That's easy:

$ snmptranslate -m ALL -Ofn .1.3.6.1.4.1.9
.iso.org.dod.internet.private.enterprises.cisco

In this case, -IR isn't needed because we're not performing a random-access search. -Ofn ensures that we print the full object ID, in symbolic (text) form. Here's what happens if we use -Of by itself:

$ snmptranslate -m ALL -Of .1.3.6.1.4.1.9
enterprises.cisco

As we said earlier, this is not how you'd expect -Ofn and -Of to behave. If you're writing scripts, you shouldn't count on this behavior staying the same in future versions.

Now, let's say you want to know a little bit more information about a particular object. The-Td option displays the object's definition as it appears in the MIB file:

$ snmptranslate -Td system.sysLocation
.1.3.6.1.2.1.1.6
sysLocation OBJECT-TYPE
  -- FROM               SNMPv2-MIB, RFC1213-MIB
  -- TEXTUAL CONVENTION DisplayString
  SYNTAX                OCTET STRING (0..255) 
  DISPLAY-HINT          "255a"
  MAX-ACCESS            read-write
  STATUS                current
  DESCRIPTION           "The physical location of this node (e.g., 'telephone
                         closet, 3rd floor'). If the location is unknown, the
                         value is the zero-length string."
::= { iso(1) org(3) dod(6) internet(1) mgmt(2) mib-2(1) system(1) 6 }

-Td can save you a lot of work poking through MIB files to find an appropriate definition, particularly when combined with -IR. Furthermore, the last line shows you the entire object ID in both numeric and string forms, not just the object's parent. Note that the other Net-SNMP commands have an unrelated -T option; don't get confused. -T is meaningless for this command, because snmptranslate only looks up a local file and doesn't need to access the network.

The -Tp option prints an entire OID tree. The best way to understand this is to see it:

$ snmptranslate -Tp system
+--system(1)
   |
   +-- -R-- String    sysDescr(1)
   |        Textual Convention: DisplayString
   |        Size: 0..255
   +-- -R-- ObjID     sysObjectID(2)
   +-- -R-- TimeTicks sysUpTime(3)
   +-- -RW- String    sysContact(4)
   |        Textual Convention: DisplayString
   |        Size: 0..255
   +-- -RW- String    sysName(5)
   |        Textual Convention: DisplayString
   |        Size: 0..255
   +-- -RW- String    sysLocation(6)
   |        Textual Convention: DisplayString
   |        Size: 0..255
   +-- -R-- Integer   sysServices(7)
   +-- -R-- TimeTicks sysORLastChange(8)
   |        Textual Convention: TimeStamp
   |
   +--sysORTable(9)
      |
      +--sysOREntry(1)
         |
         +-- ---- Integer   sysORIndex(1)
         +-- -R-- ObjID     sysORID(2)
         +-- -R-- String    sysORDescr(3)
         |        Textual Convention: DisplayString
         |        Size: 0..255
         +-- -R-- TimeTicks sysORUpTime(4)
                  Textual Convention: TimeStamp

We displayed the system subtree because it's fairly short. From this output it's relatively easy to see all the objects underneath system, together with their types and textual conventions. This is a great way to see what objects are defined in a MIB, as well as their relationships to other objects. The output can be voluminous, but it's still a convenient way to get a map and figure out what objects are likely to be useful.