C.3. Net-SNMP Command-Line Tools

This section briefly
describes each of the Net-SNMP tools. By default, installing Net-SNMP
places all these commands in /usr/local/bin. All
the examples in this section assume that
/usr/local/bin is in your path.

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:

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):

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.

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:

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:

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:

-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:

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.