C.3. Net-SNMP Command-Line ToolsThis 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. snmpwalksnmpwalk performs the getnext 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 -v2c -c public cisco.oreilly.com .1.3.6.1.4.1.9 SNMPv2-SMI::enterprises.9.2.1.1.0 = " System Bootstrap, Version 12.2(6r), RELEASE SOFTWARE (fc1) TAC Support: http://www.cisco.com/tac Copyright (c) 2001 by cisco Systems, Inc." SNMPv2-SMI::enterprises.9.2.1.2.0 = "reload" SNMPv2-SMI::enterprises.9.2.1.3.0 = "cisco" SNMPv2-SMI::enterprises.9.2.1.4.0 = "oreilly.com" SNMPv2-SMI::enterprises.9.2.1.5.0 = IpAddress: 127.45.23.1 SNMPv2-SMI::enterprises.9.2.1.6.0 = IpAddress: 0.0.0.0 SNMPv2-SMI::enterprises.9.2.1.8.0 = 131890952 SNMPv2-SMI::enterprises.9.2.1.9.0 = 456 SNMPv2-SMI::enterprises.9.2.1.10.0 = 500 SNMPv2-SMI::enterprises.9.2.1.11.0 = 17767568 SNMPv2-SMI::enterprises.9.2.1.12.0 = 0 SNMPv2-SMI::enterprises.9.2.1.13.0 = 0 SNMPv2-SMI::enterprises.9.2.1.14.0 = 104 SNMPv2-SMI::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[*] 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 instead of specifying its complete numeric object ID (.1.3.6.1.4.1.9):
$ snmpwalk -m ALL -v2c -c public cisco.oreilly.com cisco CISCO-SMI::enterprises.cisco.local.lcpu.1.0 = " System Bootstrap, Version 12.2(6r), RELEASE SOFTWARE (fc1) TAC Support: http://www.cisco.com/tac Copyright (c) 2001 by cisco Systems, Inc." CISCO-SMI::local.lcpu.2.0 = "reload" CISCO-SMI::local.lcpu.3.0 = "cisco" CISCO-SMI::local.lcpu.4.0 = "oreilly.com" CISCO-SMI::local.lcpu.5.0 = IpAddress: 127.45.23.1 CISCO-SMI::local.lcpu.6.0 = IpAddress: 0.0.0.0 CISCO-SMI::local.lcpu.8.0 = 131888844 CISCO-SMI::local.lcpu.9.0 = 456 CISCO-SMI::local.lcpu.10.0 = 500 CISCO-SMI::local.lcpu.11.0 = 17767568 CISCO-SMI::local.lcpu.12.0 = 0 CISCO-SMI::local.lcpu.13.0 = 0 CISCO-SMI::local.lcpu.14.0 = 104 CISCO-SMI::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 -v2c -m ALL -Os -c public cisco.oreilly.com cisco lcpu.1.0 = " System Bootstrap, Version 12.2(6r), RELEASE SOFTWARE (fc1) TAC Support: http://www.cisco.com/tac Copyright (c) 2001 by cisco Systems, Inc." lcpu.2.0 = "reload" lcpu.3.0 = "cisco" lcpu.4.0 = "oreilly.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 -v2c -c public cisco.oreilly.com system SNMPv2-MIB::sysDescr.0 = " Cisco IOS Software, C2600 Software (C2600-IPBASE-M), Version 12.3(8)T3, RELEASE SOFTWARE (fc1) Technical Support: http://www.cisco.com/techsupport Copyright (c) 1986-2004 by Cisco Systems, Inc. Compiled Tue 20-Jul-04 17:03 by eaarmas" SNMPv2-MIB::sysObjectID.0 = OID: DTRConcentratorMIB::catProd.182 EXPRESSION-MIB::sysUpTimeInstance = Timeticks: (344626986) 39 days, 21:17:49.86 SNMPv2-MIB::sysContact.0 = "O'Reilly Data Center" SNMPv2-MIB::sysName.0 = "cisco.oreilly.com" SNMPv2-MIB::sysLocation.0 = "Atlanta, GA" SNMPv2-MIB::sysServices.0 = 6 SNMPv2-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. We see that each line begins with SNMPv2-MIB, which is the name of the MIB which describes the system tree in SNMPv2. This is the default output for Net-SNMP commands. C.3.2. snmpgetThe snmpget command issues a single get operation. Its syntax is: snmpget options hostname objectID... C.3.3. snmpbulkgetSNMPv2 provides an operation called getbulk, which is implemented by the snmpbulkget command. getbulk allows you to retrieve a chunk of information in one operation, as opposed to a single get or sequence of getnext operations. The syntax of snmpbulkget is: snmpbulkget -v2c options hostname objectID -v2c is required because getbulk is defined by SNMP Version 2. There are two command-specific options, -Cnnonrep and -Crrep. nonrep is the number of scalar objects that this command returns; rep is the number of instances of each nonscalar object that the command returns. If you omit this option, the default values of nonrep and rep, 0 and 10, respectively, are used. C.3.4. snmpbulkwalkThe snmpbulkwalk command uses the getbulk command sequence to retrieve parts of a MIB. This command differs from snmpbulkget in that you can tell it to ignore OIDs that are not increasing. This can be useful because some SNMP agents return OIDs out of order. Use -Cc to specify this behavior. Its syntax is: snmpbulkwalk -v2c options hostname objectID C.3.5. snmpsetThe snmpset command is used to change, or set, the value of a MIB object. The command looks like this: snmpset options hostname objectID type value... You can provide any number of objectID/type/value triples; the command executes 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.
C.3.6. snmptrapTo send a trap, use the snmptrap command. The syntax for this command is: snmptrap options hostname 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 9. 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 agent and 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 -v2c options hostname uptime trapoid objectID type value... C.3.7. snmpdeltaThe snmpdelta command monitors OIDs and tracks changes in OID values over time. Its syntax is: snmpdelta options hostname objectID... snmpdelta requires you to specify the OID of an integer-valued scalar objectit can't monitor tables. For example, if you 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. The documentation for this command has many problems, but if you stick to the options listed here you should be on firm ground.
C.3.8. snmpdfsnmpdf works exactly like the Unix df command, except it uses SNMP to query hosts on a network. Its syntax is: snmpdf [-Cu] options... hostname The -Cu option tells the command to consult the old UCD-SNMP private MIB. The Host Resources MIB is used by default. C.3.9. snmpgetnextThe snmpgetnext command uses the getnext operation to retrieve the next object from a host. For example, if you ask it to perform a getnext 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 objectID... There are no options specific to snmpgetnext. C.3.10. snmpstatusThe snmpstatus command retrieves status information from a host. It prints the following information:
The syntax of snmpstatus is straightforward, and there are no command-specific options: snmpstatus options... hostname C.3.11. snmptableThe snmptable command uses getnext commands to print the contents of a table in tabular form. Its syntax is: snmptable options... hostname 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.
C.3.12. snmpusmThe snmpusm command provides simple access to the agent's 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 Chapter 6. C.3.13. snmpconfThis 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. snmpinformThis 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 for snmpinform are identical to those for snmptrap. C.3.15. snmptranslateThe 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 optionswe'll leave the rationalization to you. Let's say you want to know the enterprise OID for Cisco Systems. The following command does the trick: $ snmptranslate -m ALL -IR -On cisco .1.3.6.1.4.1.9 This tells us that Cisco's enterprise OID is .1.3.6.1.4.1.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 -Of .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. -Of ensures that we print the full object ID, in symbolic (text) form. Now, let's say you want to know a little more information about a particular object. The -Td option displays the object's definition as it appears in the MIB file: $ snmptranslate -IR -Td system.sysLocation SNMPv2-MIB::sysLocation 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. The -Tp option prints an entire OID tree. The best way to understand this is to see it: $ snmptranslate -IR -Tp system +--system(1) | +-- -R-- String sysDescr(1) | Textual Convention: DisplayString | Size: 0..255 +-- -R-- ObjID sysObjectID(2) +-- -R-- TimeTicks sysUpTime(3) | | | +--sysUpTimeInstance(0) | +-- -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) | Range: 0..127 +-- -R-- TimeTicks sysORLastChange(8) | Textual Convention: TimeStamp | +--sysORTable(9) | +--sysOREntry(1) | Index: sysORIndex | +-- ---- INTEGER sysORIndex(1) | Range: 1..2147483647 +-- -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. |