==============================================================================
snmp-walk - list the SNMP variables of a network device
==============================================================================

SNMPSoft Tools 2.0. Copyright (C) 2026 EZ5 Systems Ltd.

Contents
--------
  1. Synopsis
  2. Options
  3. What is walked
  4. SNMPv3
  5. Output
  6. MIB catalog (-m)
  7. Exit codes
  8. Examples


1. 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]

  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 the way 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'


2. 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
                                           (section 6). Default: .1,
                                           everything an agent serves.
  -op:stop_oid     --stop-oid OID          Last OID to walk, inclusive. See
                                           section 3. Default: the end of the
                                           start subtree.
  -csv             --csv                   Write comma-separated values. See
                                           section 5.
  -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 section 6.
  -n               --numeric               With -m, print the numeric OID of
                                           each row instead of its name. See
                                           section 6.

  SNMPv3 options (see section 4):

  -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 section 4).

  Other options:

                   -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
                                           (see README.txt, section 4).

  Protocol names are not case-sensitive. A value that does not fit its
  option, such as -t:0, -v:4, or a stop OID before the start OID, is
  reported before anything is sent.


3. 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.


4. SNMPv3
----------
  With -v:3, -sn is required. The security level follows from the options:

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


5. 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.


6. 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
  (https://mibs.ezfive.com/).

  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 \" (see README.txt, section 5), 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. See README.txt, section 6, for 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.


7. Exit codes
--------------
  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
      section 3.
  2   Usage error: a missing or invalid option. Nothing was sent.


8. Examples
------------
  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

  (In the multi-line examples above, type the command on one line.)
