snmp-walk reads every variable in a part of the device’s MIB tree, or in all of it, and prints one line per variable. It is part of SNMPSoft Tools 2.0 and replaces SnmpWalk 1.x: the 1.x options still work, so most scripts only need the new program name. See Upgrading from 1.x.
snmp-walk -r:10.0.0.1 -v:2c -os:.1.3.6.1.2.1.1
.1.3.6.1.2.1.1.1.0 = STRING: "ER-2400 Router, Version 4.2.1"
.1.3.6.1.2.1.1.2.0 = OID: .1.3.6.1.4.1.32473.1.1
.1.3.6.1.2.1.1.3.0 = Timeticks: (12345678) 1d 10:17:36.78
.1.3.6.1.2.1.1.4.0 = STRING: "Network Team"
.1.3.6.1.2.1.1.5.0 = STRING: "MainRouter"
.1.3.6.1.2.1.1.6.0 = STRING: "Server room 2"
.1.3.6.1.2.1.1.7.0 = INTEGER: 78
Synopsis
snmp-walk [-q] -r:host [-p:port] [-t:timeout] [-v:version] [-c:community]
[-ei:engine_id] [-sn:sec_name] [-ap:auth_proto]
[-aw:auth_passwd] [-pp:priv_proto] [-pw:priv_passwd]
[-cn:cont_name] [-ce:cont_engine] [-m[:dir]] [-n]
[-os:start_oid] [-op:stop_oid] [-csv]
Use it to find out which variables a device has, and to read whole tables such as the interface table.
Every option has two forms: the colon form used by SnmpWalk 1.x, such as -r:10.0.0.1, and a GNU form, such as --host 10.0.0.1 or --host=10.0.0.1. The two can be mixed. A one-letter option also accepts -r 10.0.0.1 and -r=10.0.0.1. Option names are case-sensitive.
In PowerShell, quote colon options so the shell passes them unchanged:
snmp-walk '-r:10.0.0.1' '-os:.1.3.6.1.2.1.1'
Options
| Colon form | GNU form | Meaning |
|---|---|---|
-r:host |
--host HOST |
Name or address (IPv4 or IPv6) of the device. Required. |
-os:start_oid |
--start-oid OID |
Where the walk starts. The leading dot is optional. With -m also a name, such as IF-MIB::ifTable (see MIB catalog). Default: .1, everything an agent serves. |
-op:stop_oid |
--stop-oid OID |
Last OID to walk, inclusive. It cannot come before the start OID. See What is walked. Default: the end of the start subtree. |
-csv |
--csv |
Write comma-separated values. See Output. |
-p:port |
--port PORT |
UDP port of the SNMP agent. Default: 161 |
-t:timeout |
--timeout SECONDS |
How long to wait for each answer, 1-600 seconds. Default: 5 |
-v:version |
--snmp-version VERSION |
SNMP version: 1, 2c or 3. Default: 1 |
-c:community |
--community COMMUNITY |
Community string for SNMP v1 and v2c. Default: public |
-q |
--quiet |
Print values only. With -csv, leave out the header row. |
-m[:dir] |
--mib[=DIR] |
Show names and decoded values from the MIB catalog. See MIB catalog. |
-n |
--numeric |
With -m, print the numeric OID of each row instead of its name. See MIB catalog. |
SNMPv3 options
See SNMPv3.
| Colon form | GNU form | Meaning |
|---|---|---|
-sn:sec_name |
--security-name NAME |
USM user name. Required for v3. |
-ap:auth_proto |
--auth-protocol PROTO |
MD5, SHA (SHA-1), SHA224, SHA256, SHA384 or SHA512. |
-aw:auth_passwd |
--auth-password PASS |
Authentication password, at least 8 octets. |
-pp:priv_proto |
--priv-protocol PROTO |
DES, 3DES, AES128, AES192, AES256, AES192-REEDER or AES256-REEDER. |
-pw:priv_passwd |
--priv-password PASS |
Privacy password, at least 8 octets. |
-ei:engine_id |
--engine-id HEX |
Authoritative engine ID of the agent, in hex. Normally discovered automatically. |
-cn:cont_name |
--context-name NAME |
Context name. |
-ce:cont_engine |
--context-engine HEX |
Context engine ID, in hex. Must be the same as -ei (see SNMPv3). |
Protocol names are not case-sensitive.
Other options
| Option | Meaning |
|---|---|
-h, --help |
Print a summary of the options. |
-V, --version |
Print the program version, the copyright and the license terms, or the commercial license in a .lic file next to the program. |
What is walked
Without -op, the walk covers the subtree under -os: every variable whose OID starts with the start OID. -os:.1.3.6.1.2.1.2.2 lists the interface table and stops at its end.
With -op, the walk runs in OID order from -os through -op, including both if they exist. This range can go past the start subtree, for example from the middle of one table to the middle of another.
If the start OID is a single variable with nothing under it, such as -os:.1.3.6.1.2.1.1.5.0, its value is printed, as snmp-get would.
SNMPv1 reads one variable per request (GETNEXT). SNMP v2c and v3 read many per request (GETBULK), which is much faster on large tables; use -v:2c when the device supports it. -t applies to each request, not to the whole walk.
A walk that finds nothing prints nothing and exits with 0. If the agent returns an OID that does not increase, the walk stops with an error instead of looping.
Some devices cannot read one of their own variables and answer with a general error (genErr). The device does not say which variable failed, so snmp-walk finds it with a few extra requests, skips it and goes on. Each skip is a warning on standard error, such as
snmp-walk: warning: the agent could not read the variables after
.1.3.6.1.2.1.2.2.1.2.5 through .1.3.6.1.2.1.2.2.1.2.6 (genErr);
skipped them
(on one line). Usually this is a single variable, the second OID; when several in a row cannot be read, they are skipped together. The walk then ends with exit code 1, because its output is incomplete. A variable that cannot be read just after the end of the walk is not part of it, so it is neither a warning nor an error.
When the program that reads the output stops reading, as in snmp-walk ... | head -5 on Linux, or snmp-walk ... | more closed with Q in the Windows command prompt, the walk stops without a message and exits with 0. In PowerShell, snmp-walk ... | Select-Object -First 5 stops the walk too, but PowerShell ends the program itself, so $LASTEXITCODE is -1, not 0.
The default start .1, as in SnmpWalk 1.x, covers everything an agent serves, including the IEEE MIBs outside .1.3, such as LLDP-MIB under .1.0.8802. -os:.1.3 leaves them out.
SNMPv3
With -v:3, -sn is required. The security level follows from the options:
| Options given | Security level |
|---|---|
-sn only |
noAuthNoPriv |
-sn, -ap, -aw |
authNoPriv |
-sn, -ap, -aw, -pp, -pw |
authPriv |
Privacy needs authentication. Both passwords must be at least 8 octets long, as SNMPv3 requires.
SHA means SHA-1. AES192 and AES256 need a longer key than the password gives, and there are two incompatible ways to extend it. AES192 and AES256 use the Blumenthal method. AES192-REEDER and AES256-REEDER use the Reeder method, which Cisco devices use. If one fails with a decryption error, try the other. AES means AES128. IDEA, which SnmpWalk 1.x listed, is not supported.
The agent’s engine ID is discovered with a first request, so -ei is only needed to skip that step. Engine IDs may be written as 8000000903..., 0x8000000903..., or with colons or spaces between the bytes. -ce is accepted only when it is the same as -ei, because the requests always use the agent’s own engine as context engine.
The SNMPv3 options are rejected with -v:1 and -v:2c. -c is not used with -v:3.
Output
One line per variable, the same as snmp-get:
.1.3.6.1.2.1.1.1.0 = STRING: "ER-2400 Router, Version 4.2.1"
.1.3.6.1.2.1.1.2.0 = OID: .1.3.6.1.4.1.32473.1.1
.1.3.6.1.2.1.1.3.0 = Timeticks: (12345678) 1d 10:17:36.78
With -q, values only:
ER-2400 Router, Version 4.2.1
.1.3.6.1.4.1.32473.1.1
(12345678) 1d 10:17:36.78
With -csv, a header row and one row per variable, for spreadsheets and scripts:
OID,Type,Value
.1.3.6.1.2.1.1.1.0,STRING,"ER-2400 Router, Version 4.2.1"
.1.3.6.1.2.1.1.2.0,OID,.1.3.6.1.4.1.32473.1.1
.1.3.6.1.2.1.1.3.0,Timeticks,(12345678) 1d 10:17:36.78
A field that holds a comma, a double quote or a line break is put in double quotes, with quotes doubled (RFC 4180), so Excel and other CSV readers read it correctly. -csv -q leaves out the header row and keeps all three columns.
Values are written exactly as the device sends them. A text value that starts with =, +, - or @ is a formula to Excel, so import a file from a device you do not trust with Data > From Text/CSV instead of opening it directly.
Lines are written as they arrive, so a walk that fails partway keeps the lines already written. Errors and warnings go to standard error, starting with snmp-walk:, so they never mix with the rows on standard output.
MIB catalog (-m)
With -m, snmp-walk shows each row by name and decodes its value: enumeration labels such as up(1), BITS labels, display hints such as MAC addresses, and units. The walk ends with a list of the MIB modules found and how many rows each had:
SNMPv2-MIB::sysDescr.0 = STRING: "ER-2400 Router, Version 4.2.1"
...
IF-MIB::ifOperStatus.1 = INTEGER: up(1)
...
.1.3.6.1.4.1.32473.1.9.0 = IpAddress: 10.0.0.5 [unknown]
MIBs:
IF-MIB (44)
SNMPv2-MIB (7)
unknown (12)
The names and types come from parsed MIB files on the local disk. The index and the MIB files can be downloaded from the EZ5 MIB Catalog.
A row the catalog cannot name keeps its numeric OID and ends with its MIB module in brackets, or [unknown].
With -n as well, every row keeps its numeric OID. The values are still decoded, and the walk still ends with the list of MIB modules, so -m -n shows which MIBs a device uses without changing the OIDs:
.1.3.6.1.2.1.1.1.0 = STRING: "ER-2400 Router, Version 4.2.1"
...
.1.3.6.1.2.1.2.2.1.8.1 = INTEGER: up(1)
...
.1.3.6.1.4.1.32473.1.9.0 = IpAddress: 10.0.0.5
MIBs:
IF-MIB (44)
SNMPv2-MIB (7)
unknown (12)
With -n, no row ends with a module in brackets. -n changes nothing with -csv, which always has both the OID and the name, or with -q. -n without -m is a usage error (exit code 2).
With -m, -os and -op may also be names, the way -m prints them: a table, as in snmp-walk -m -os:IF-MIB::ifTable, or a row whose index has several parts, such as IP-MIB::ipAddressIfIndex.ipv4."10.0.0.1". The module is always given. The part after the name may also be the index as numbers: IP-MIB::ipAddressIfIndex.1.4.10.0.0.1 is the same variable. A name without -m, or one the catalog cannot find, is a usage error (exit code 2), and nothing is sent. In Windows PowerShell 5.1, write each " inside an argument as \", or give the index as numbers.
With -csv, the columns are OID,Name,Type,Value,Raw,MIB: the numeric OID and the raw value stay, and the name, the decoded value and the module are added:
OID,Name,Type,Value,Raw,MIB
.1.3.6.1.2.1.2.2.1.8.1,IF-MIB::ifOperStatus.1,INTEGER,up(1),1,IF-MIB
-q without -csv prints the decoded values only.
The catalog is a folder with the newest mib-index-YYYYMMDD-HHMM.bin (or .bin.gz) file and the module files <MODULE>.json (or .json.gz). snmp-walk looks for it in the folder that holds snmp-walk, or in the folder given as -m:DIR. The downloads page explains how to set it up. If the index or a module file is missing or damaged, a warning goes to standard error once, and the walk runs as usual.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The walk completed. This includes a walk that found nothing. |
| 1 | The walk failed: timeout, unknown host, or an SNMP error. The rows read before the failure have been written. After a general error (genErr) the walk goes on and writes the rows it can still read; see What is walked. |
| 2 | Usage error: a missing or invalid option. Nothing was sent. |
Examples
Commands shown on two lines are typed on one line.
Walk the whole device with SNMPv1 and the community “public”:
snmp-walk -r:MainRouter
The system group with SNMP v2c, a 10 second timeout and the community “admin_rw”:
snmp-walk -r:10.0.0.1 -v:2c -t:10 -c:admin_rw -os:.1.3.6.1.2.1.1
The interface table by name, saved as CSV for a spreadsheet:
snmp-walk -r:10.0.0.1 -v:2c -os:.1.3.6.1.2.1.2.2 -m -csv > ifTable.csv
The same with GNU options and the catalog in another folder:
snmp-walk --host 10.0.0.1 --snmp-version 2c --start-oid .1.3.6.1.2.1.2.2 --mib=/opt/mibs
Numeric OIDs with decoded values, and the list of the device’s MIBs:
snmp-walk -r:10.0.0.1 -v:2c -m -n
The interfaces group through the IP group, a range across subtrees, with SNMPv3 (MD5 and DES), values only:
snmp-walk -r:::1 -v:3 -sn:SomeName -ap:MD5 -aw:SomeAuthPass -pp:DES
-pw:SomePrivPass -os:.1.3.6.1.2.1.2 -op:.1.3.6.1.2.1.5 -q