==============================================================================
snmp-table - print an SNMP table of a network device
==============================================================================

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

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


1. Synopsis
------------
  snmp-table [-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]]
             -o:table_oid [-csv]

  snmp-table reads every column of one table, such as the interface table,
  and prints it as a grid: one line per row and one column per table
  column. It only reads; to add or delete a row, use snmp-row.

  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-table '-r:10.0.0.1' '-o:.1.3.6.1.2.1.2.2'


2. Options
-----------
  Colon form       GNU form                Meaning
  ---------------  ----------------------  -----------------------------------
  -r:host          --host HOST             Name or address (IPv4 or IPv6) of
                                           the device. Required.
  -o:table_oid     --oid OID               OID of the table, such as
                                           .1.3.6.1.2.1.2.2, or of its entry,
                                           .1.3.6.1.2.1.2.2.1. With -m also
                                           the table's name, such as
                                           IF-MIB::ifTable. The leading dot is
                                           optional. Required.
  -csv             --csv                   Print comma-separated values
                                           instead of a grid. 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                 Leave out the heading, or with
                                           -csv the header row.
  -m[:dir]         --mib[=DIR]             Name the columns, split the index
                                           and decode the values from the MIB
                                           catalog. 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 or -v:4, is reported before anything is sent.


3. What is read
----------------
  snmp-table reads every variable under the table, the same way snmp-walk
  does, and sorts them into rows and columns. A table's variables are
  .table.1.column.index: the table's OID, the entry (always 1), the column
  number, and the row's index. -o may be the table's OID or the entry's.

  Without -m, snmp-table cannot look the table up, so it decides from the
  answer: if every variable under -o is also under -o followed by .1, -o is
  the table; otherwise it is the entry.

  All rows are read before anything is printed, because the column widths
  depend on every value. Rows are printed in index order. A cell the agent
  has no value for is empty: tables are often sparse, with some columns
  only on some rows.

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

  If the device cannot read one of its own variables and answers with a
  general error (genErr), snmp-table skips it with a warning on standard
  error, as snmp-walk does (see snmp-walk.txt, section 3), and exits with 1
  at the end, because the table is incomplete. If a request fails partway,
  such as with a timeout, the rows read so far are printed, then the error,
  and the exit code is 1.

  When the program that reads the output stops reading, as in "snmp-table ...
  | head -5" on Linux, or "snmp-table ... | more" closed with Q in the Windows
  command prompt, snmp-table stops without a message and exits with 0. In
  PowerShell, "snmp-table ... | Select-Object -First 5" stops it too, but
  PowerShell ends the program itself, so $LASTEXITCODE is -1, not 0.


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 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
----------
  A heading, a line of dashes, then one line per row. Each column is as
  wide as its widest value, with two spaces between columns:

    Index      1          2  3              4  5
    ---------  ---------  -  -------------  -  -----
    10.0.0.1   10.0.0.1   2  255.255.255.0  1  65535
    127.0.0.1  127.0.0.1  1  255.0.0.0      1  65535

  Without -m, the first column is the row's index as numbers, and the other
  columns are headed by their column number. The example is the IP address
  table, whose index is the address. Every column is printed, so a wide table
  makes long lines that wrap in the console; -csv is the way to read it in a
  spreadsheet. A line break or tab in a value is shown as \n, \r or \t, so
  each row stays on one line.

  With -q, the heading and the dashes are left out.

  With -csv, the same heading and rows as comma-separated values, for
  spreadsheets and scripts:

    Index,1,2,3,4,5
    10.0.0.1,10.0.0.1,2,255.255.255.0,1,65535
    127.0.0.1,127.0.0.1,1,255.0.0.0,1,65535

  A field that holds a comma, a double quote or a line break is put in double
  quotes, with quotes doubled (RFC 4180), such as "eth0, uplink". -csv -q
  leaves out the header row. Values are written exactly as the device sends
  them; see snmp-walk.txt, section 5, about opening CSV from a device you do
  not trust in Excel.

  A table with no rows prints nothing without -m, and only the heading with
  -m. Errors and warnings go to standard error, starting with "snmp-table:",
  so they never mix with the rows on standard output.


6. MIB catalog (-m)
--------------------
  With -m, snmp-table uses the MIB catalog, a set of parsed MIB files on the
  local disk:

  + -o may be the table's name, such as IF-MIB::ifTable. The catalog has no
    names for table entries, so the name is always the table's.
  + The columns are headed by name, and every readable column the MIB lists is
    shown, empty where the device has no value, so the layout is the same on
    every device. A column that the device returns but the MIB does not list
    is also shown, headed by its number.
  + The index is split into one column per INDEX part, decoded by its type,
    so a spreadsheet can sort and filter by each part. A column that is also
    an INDEX part, such as ifIndex in the interface table, is shown once, as
    the index.
  + The values are decoded as snmp-walk -m decodes them: enumeration labels
    such as up(1), display hints such as MAC addresses, and units.

    ipAddressAddrType  ipAddressAddr  ipAddressIfIndex  ...
    -----------------  -------------  ----------------
    ipv4               10.0.0.1       2
    ipv6               fe80::1        3

  A row whose index does not fit the table's INDEX keeps its index as
  numbers in the first index column, with a warning. If the catalog has no
  table at -o, snmp-table warns and shows the columns by number, with the
  values decoded where the catalog knows them.

  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-table
  looks for it in the folder that holds snmp-table, or in the folder given as
  -m:DIR. The index and the MIB files can be downloaded from the EZ5 MIB
  Catalog (https://mibs.ezfive.com/). 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, and the table is printed without names, unless -o is
  a name, which then cannot be found (exit code 2).


7. Exit codes
--------------
  0   The table was read. This includes a table with no rows.
  1   Reading failed: timeout, unknown host, or an SNMP error. The rows read
      before the failure have been printed. After a general error (genErr)
      snmp-table goes on and prints the rows it can still read; see
      section 3.
  2   Usage error: a missing or invalid option, or a name that cannot be
      found. Nothing was sent.


8. Examples
------------
  The interface table with SNMP v2c:
    snmp-table -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.2.2

  The same by name, with decoded values:
    snmp-table -r:10.0.0.1 -v:2c -m -o:IF-MIB::ifTable

  The ARP table as CSV, one column per index part, for a spreadsheet:
    snmp-table -r:10.0.0.1 -v:2c -m -o:IP-MIB::ipNetToPhysicalTable -csv
               > arp.csv

  With GNU options and the catalog in another folder:
    snmp-table --host 10.0.0.1 --snmp-version 2c --oid IF-MIB::ifTable
               --mib=/opt/mibs

  With SNMPv3 (SHA-256, no privacy), rows only:
    snmp-table -r:::1 -v:3 -sn:SomeName -ap:SHA256 -aw:SomeAuthPass
               -o:.1.3.6.1.2.1.2.2 -q

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