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. It is part of SNMPSoft Tools 2.0 and is new in version 2.0.
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
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]
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'
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 The table and the row. |
-i:index |
--index INDEX |
The row’s index. With -m, once per INDEX part; without it, once, as numbers. Required. See The table and the row. |
-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 Adding a row. |
-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 Adding a row. |
-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 MIB catalog. |
-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
| 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. |
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. |
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 (MIB catalog), -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:
| Index part | Written as |
|---|---|
| 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.
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; the names are not case-sensitive. 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): 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:
- RowStatus createAndWait(5), which makes the row.
- 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.
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.
MIB catalog (-m, -d, -strict)
With -m, snmp-row uses the MIB catalog, a set of parsed MIB files on the local disk:
-
-omay be the table’s name, and the RowStatus column is the column whose SYNTAX is RowStatus.-rsoverrides it, for a MIB that is wrong or a table with two RowStatus columns. -
-iis given once per INDEX part (The table and the row). -
A column is given by name, and each value gets the column’s MIB type and is checked as
snmp-set -mchecks 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. The downloads page explains 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.
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. 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. 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.
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:”.
Exit codes
| Code | Meaning |
|---|---|
| 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. |
Examples
Commands shown on two lines are typed on one line.
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