==============================================================================
snmp-row - add or delete a row of an SNMP table on a network device
==============================================================================

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

Contents
--------
  1. Synopsis
  2. Options
  3. The table and the row
  4. Adding a row
  5. Deleting a row
  6. MIB catalog (-m, -d, -strict)
  7. SNMPv3
  8. Output
  9. Exit codes
 10. Examples


1. Synopsis
------------
  snmp-row [-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]] [-d] [-strict]
           (-add | -rm) -o:table_oid -i:index [-i:index ...] [-rs:column]
           [-vb:column[:type]=value ...] [-vbf:file] [-wait] [-keep]

  snmp-row creates (-add) or deletes (-rm) one row of a table through the
  table's RowStatus column (RFC 2579), such as a VLAN, a static ARP entry,
  or a trap target. To read a table, use snmp-table; to change a column of
  an existing row, use snmp-set.

  snmp-row changes the configuration of the device. -d shows what would be
  sent without sending it.

  Every option has two forms: the colon form, 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-row '-r:10.0.0.1' -m -rm '-o:Q-BRIDGE-MIB::dot1qVlanStaticTable'
               '-i:100'


2. Options
-----------
  Colon form       GNU form                Meaning
  ---------------  ----------------------  -----------------------------------
  -r:host          --host HOST             Name or address (IPv4 or IPv6) of
                                           the device. Required.
  -add             --add                   Create the row. One of -add and
                                           -rm is required.
  -rm              --remove                Delete the row.
  -o:table_oid     --oid OID               The table: its OID, or with -m
                                           its name, such as
                                           Q-BRIDGE-MIB::dot1qVlanStaticTable.
                                           Required. See section 3.
  -i:index         --index INDEX           The row's index. With -m, once per
                                           INDEX part; without it, once, as
                                           numbers. Required. See section 3.
  -rs:column       --row-status COLUMN     The number of the RowStatus
                                           column. Required without -m; with
                                           -m it overrides the MIB's.
  -vb:col=value    --varbind VARBIND       With -add, a column of the new
                                           row, as COLUMN=VALUE or
                                           COLUMN:TYPE=VALUE. May be repeated.
                                           See section 4.
  -vbf:file        --varbind-file FILE     With -add, a file with one column
                                           per line, as for -vb; -vbf:- reads
                                           standard input.
  -wait            --wait                  With -add, create the row with
                                           createAndWait, then make it
                                           active. See section 4.
  -keep            --keep                  With -wait, leave a row whose
                                           second SET failed instead of
                                           removing it.
  -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: private
  -q               --quiet                 Print nothing on success.
  -m[:dir]         --mib[=DIR]             Find the table, its RowStatus
                                           column, its index and the column
                                           types in the MIB catalog, and show
                                           the answer by name. See section 6.
  -d               --describe              Print the SETs that would be sent,
                                           and send nothing. Cannot be
                                           combined with -q.
  -strict          --strict                With -m, send nothing if a value
                                           does not fit its column or cannot
                                           be checked, or a read-create
                                           column with no DEFVAL is left out.

  SNMPv3 options (see section 7):

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

  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 and type names are not case-sensitive. Everything that needs no
  network is checked before anything is sent, including every value.


3. The table and the row
-------------------------
  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. snmp-row builds each
  OID from -o, the column and -i.

  With -m (section 6), -o may be the table's name or its OID, or the OID of
  its entry. -i is given once per part of the table's INDEX, in INDEX order,
  each as text:

    an integer          a number, or an enumeration label such as ipv4
    an IpAddress        10.0.0.1
    an InetAddress      an address for the InetAddressType just before it:
                        10.0.0.1, fe80::1, fe80::1%3, or a host name for dns
    a string            its text
    an OID              1.3.6.1.4.1.9

    -i:100                          dot1qVlanStaticTable (dot1qVlanIndex)
    -i:2 -i:ipv4 -i:10.0.0.5        ipNetToPhysicalTable

  Separate -i options need no quotes inside the shell's quotes, which
  Windows PowerShell 5.1 passes badly to programs.

  Without -m, -o is the table's OID, -rs the number of its RowStatus
  column, and -i the index as numbers, as they appear in the OID:

    -o:.1.3.6.1.2.1.4.35 -rs:8 -i:2.1.4.10.0.0.5

  snmp-row only works with tables that have a RowStatus column. RMON
  tables, which use EntryStatus, and old MIB-II tables, which delete a row
  by setting a column to invalid(2), are changed with snmp-set.


4. Adding a row
----------------
  -vb gives the value of one column of the new row, and may be repeated:

    -vb:COLUMN=VALUE
    -vb:COLUMN:TYPE=VALUE

  With -m the column is its name; without it, its number. TYPE is one of
  snmp-set's -tp names: int, uint, str, hex, oid, ip, ticks, cnt32, cnt64 or
  bits. Without it, the value has the column's MIB type with -m, as in
  snmp-set -m, and is a string without -m. -vbf reads the same columns from a
  file, one per line, as snmp-set's -vbf does (see snmp-set.txt, section 7):
  blank lines and lines that start with # are skipped, and a value in double
  quotes may use \", \\, \n and \t. A file works for any row of the table,
  since snmp-row adds the index:

    # vlan.txt
    dot1qVlanStaticName=Lab
    dot1qVlanStaticEgressPorts:hex=F0

  A column given twice is sent once, with the later value, and a warning.
  The RowStatus column cannot be given; snmp-row sets it itself.

  By default, one SET writes every value together with RowStatus
  createAndGo(4). The agent applies all of them or none, so the row is
  created with its values or not at all.

  Some agents refuse createAndGo. With -wait, snmp-row sends two SETs:

    1. RowStatus createAndWait(5), which makes the row.
    2. The values, with RowStatus active(1).

  If the second SET fails, the agent keeps a row that is not active. snmp-row
  then removes it with RowStatus destroy(6) and reports the error, and whether
  the row was removed. With -keep the row is left, to be fixed with snmp-set
  and made active by hand.

  A SET that times out may still have been applied, with only the answer
  lost. The error then says so, and names the RowStatus variable to check
  with snmp-get.


5. Deleting a row
------------------
  -rm sends one SET of RowStatus destroy(6). Like snmp-set, it does not ask
  for confirmation; -d shows what would be sent. -vb and -vbf cannot be used
  with -rm.


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

  + -o may be the table's name, and the RowStatus column is the column
    whose SYNTAX is RowStatus. -rs overrides it, for a MIB that is wrong or
    a table with two RowStatus columns.
  + -i is given once per INDEX part (section 3).
  + A column is given by name, and each value gets the column's MIB type
    and is checked as snmp-set -m checks it: enumeration labels such as
    active, display hints such as MAC addresses, ranges and sizes. A failed
    check is a warning, and the value is sent anyway.
  + A writable (read-create) column that is not given and has no DEFVAL is
    a warning, because many agents fill in their own default:

      snmp-row: warning: Q-BRIDGE-MIB::dot1qVlanForbiddenEgressPorts is not
      given and has no DEFVAL; the agent may refuse the row

  + The answer is shown by name, with decoded values.

  -strict turns every such warning into an error, and nothing is sent
  (exit code 2).

  -d is a dry run, with or without -m. It prints each SET that would be sent.
  With -m it also lists the writable columns that were not given, each with
  its DEFVAL or the note that it has none:

    Would send 1 SET to 10.0.0.1:
      Q-BRIDGE-MIB::dot1qVlanStaticName.100 = STRING: "Lab"
      Q-BRIDGE-MIB::dot1qVlanStaticEgressPorts.100 = Hex-STRING: F0
      Q-BRIDGE-MIB::dot1qVlanStaticRowStatus.100 = INTEGER: createAndGo(4)
    Not given, so the agent or the DEFVAL decides:
      dot1qVlanForbiddenEgressPorts (no DEFVAL)
      dot1qVlanStaticUntaggedPorts (no DEFVAL)
    Nothing was sent (-d).

  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-row
  looks for it in the folder that holds snmp-row, 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 catalog cannot be used, a warning goes to standard error.
  A table or column given by name, or a table without -rs, is then a usage
  error, because both need the catalog.


7. 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. SHA means SHA-1. AES192 and AES256 use the Blumenthal key extension,
  and AES192-REEDER and AES256-REEDER the Reeder one, which Cisco devices
  use; see snmp-set.txt, section 4. IDEA is not supported. -ce is accepted
  only when it is the same as -ei. The SNMPv3 options are rejected with -v:1
  and -v:2c.


8. Output
----------
  On success, snmp-row prints the agent's answer, one line per variable, as
  snmp-set does, and with -wait the answers of both SETs:

    Q-BRIDGE-MIB::dot1qVlanStaticName.100 = STRING: "Lab"
    Q-BRIDGE-MIB::dot1qVlanStaticRowStatus.100 = INTEGER: createAndGo(4)

  With -q it prints nothing, and the exit code says whether it worked.

  When the agent refuses a SET, the error names the variable it refused:

    snmp-row: SNMP SET failed: inconsistentValue for
    Q-BRIDGE-MIB::dot1qVlanStaticRowStatus.100

  inconsistentValue on the RowStatus usually means that the row already
  exists (-add) or that a required column is missing. wrongValue on
  createAndGo usually means the agent needs -wait. Errors and warnings go to
  standard error, starting with "snmp-row:".


9. Exit codes
--------------
  0   The agent accepted the request. With -d: the dry run completed.
  1   A request failed: timeout, unknown host, or an SNMP error from the
      agent, such as inconsistentValue. After a failed second SET of
      -wait, the row has been removed, unless -keep.
  2   Usage error: a missing or invalid option, a name or column that
      cannot be found, a value that does not fit its type, or a check
      refused by -strict. Nothing was sent.


10. Examples
-------------
  Create VLAN 100 named Lab:
    snmp-row -r:10.0.0.1 -v:2c -m -add
             -o:Q-BRIDGE-MIB::dot1qVlanStaticTable -i:100
             -vb:dot1qVlanStaticName=Lab -vb:dot1qVlanStaticEgressPorts:hex=F0

  The same without the catalog:
    snmp-row -r:10.0.0.1 -v:2c -add -o:.1.3.6.1.2.1.17.7.1.4.3 -rs:5 -i:100
             -vb:1=Lab -vb:2:hex=F0

  On an agent that refuses createAndGo, with the columns from a file:
    snmp-row -r:10.0.0.1 -v:2c -m -add -wait
             -o:Q-BRIDGE-MIB::dot1qVlanStaticTable -i:100 -vbf:vlan.txt

  Check first what that would send:
    snmp-row -r:10.0.0.1 -v:2c -m -add -wait
             -o:Q-BRIDGE-MIB::dot1qVlanStaticTable -i:100 -vbf:vlan.txt -d

  A static ARP entry for 10.0.0.5 on interface 2, then its deletion:
    snmp-row -r:10.0.0.1 -v:2c -m -add -o:IP-MIB::ipNetToPhysicalTable
             -i:2 -i:ipv4 -i:10.0.0.5
             -vb:ipNetToPhysicalPhysAddress:hex=001A2B3C4D5E
             -vb:ipNetToPhysicalType=static
    snmp-row -r:10.0.0.1 -v:2c -m -rm -o:IP-MIB::ipNetToPhysicalTable
             -i:2 -i:ipv4 -i:10.0.0.5

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