==============================================================================
snmp-set - change SNMP variables on a network device
==============================================================================

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

Contents
--------
  1. Synopsis
  2. Options
  3. Value types (-tp)
  4. SNMPv3
  5. Output
  6. MIB catalog (-m, -d, -strict)
  7. Several variables in one request (-vb, -vbf)
  8. Exit codes
  9. Examples


1. Synopsis
------------
  snmp-set [-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]
           -o:var_oid -val:value [-tp:type]

  snmp-set [options as above] [-vb:oid[:type]=value ...] [-vbf:file]

  snmp-set sends one SNMP SET request that writes one variable, or with -vb
  and -vbf several variables together (section 7), and prints the agent's
  answer.

  snmp-set changes the configuration of the device. Check the OID and the
  value before you run it; -m with -d shows what would be sent without
  sending it.

  Every option has two forms: the colon form used by SnmpSet 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-set '-r:10.0.0.1' '-o:.1.3.6.1.2.1.1.5.0' '-val:MainRouter'


2. Options
-----------
  Colon form       GNU form                Meaning
  ---------------  ----------------------  -----------------------------------
  -r:host          --host HOST             Name or address (IPv4 or IPv6) of
                                           the device. Required.
  -o:var_oid       --oid OID               OID of the variable to change,
                                           such as .1.3.6.1.2.1.1.5.0. The
                                           leading dot is optional. With -m
                                           also a name, such as
                                           IF-MIB::ifAdminStatus.3 (section
                                           6). Required, unless -vb or -vbf
                                           is given.
  -val:value       --value VALUE           The new value. Required with -o.
                                           -val:
                                           with nothing after the colon sets
                                           an empty string. Text that starts
                                           with "-", other than a number,
                                           must be attached: -val:-text or
                                           --value=-text.
  -tp:type         --type TYPE             Type of the value: int, uint, str,
                                           hex, oid, ip, ticks, cnt32, cnt64
                                           or bits. Default: str, or the
                                           object's type with -m. See
                                           section 3.
  -vb:oid=value    --varbind VARBIND       One variable of a request that
                                           sets several, as OID=VALUE or
                                           OID:TYPE=VALUE. May be repeated.
                                           See section 7.
  -vbf:file        --varbind-file FILE     A file with one variable per
                                           line, as for -vb; -vbf:- reads
                                           standard input. See section 7.
  -p:port          --port PORT             UDP port of the SNMP agent.
                                           Default: 161
  -t:timeout       --timeout SECONDS       How long to wait for the 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 the value only. With -vb or
                                           -vbf, print nothing (section 7).
  -m[:dir]         --mib[=DIR]             Type and check each value, and
                                           show the answer by name, from the
                                           MIB catalog. See section 6.
  -d               --describe              With -m, print each value that
                                           would be sent and its object's
                                           definition, and send nothing.
                                           Cannot be combined with -q.
  -strict          --strict                With -m, send nothing if a value
                                           does not fit its object, or the
                                           catalog cannot check it.

  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 and type 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. Value types (-tp)
---------------------
  Type   SNMP type           Printed as  Accepted values
  -----  ------------------  ----------  -------------------------------------
  int    INTEGER             INTEGER     -2147483648 to 2147483647
  uint   Gauge32             Gauge32     0 to 4294967295. Gauge32 is the same
                                         wire type as Unsigned32.
  str    OCTET STRING        STRING      The text exactly as given, including
                                         spaces at the start or end. This is
                                         the default.
  hex    OCTET STRING        Hex-STRING  Hex digits, such as 0A1B, 0a:1b,
                                         0a 1b or 0x0a1b.
  oid    OBJECT IDENTIFIER   OID         An OID, such as .1.3.6.1.4.1.
  ip     IpAddress           IpAddress   An IPv4 address, such as 10.0.0.1.
  ticks  TimeTicks           Timeticks   Hundredths of a second, 0 to
                                         4294967295, or a time as it is
                                         printed, such as 1d 10:17:36.78.
  cnt32  Counter32           Counter32   0 to 4294967295
  cnt64  Counter64           Counter64   0 to 18446744073709551615. Needs SNMP
                                         v2c or v3.
  bits   OCTET STRING        Hex-STRING  The numbers of the bits to set, such
                                         as 0,3. Bit 0 is the first bit of the
                                         first octet.

  "Printed as" is the type name in the output of the tools, for a script that
  reads a value and sets it again. An OCTET STRING is printed as STRING when
  its bytes are readable text, and as Hex-STRING otherwise, whichever type it
  was set with.

  A value that does not fit its type is a usage error (exit code 2), and
  nothing is sent:

    snmp-set: value 'abc' is not an int (-2147483648 to 2147483647)

  int, uint, str, hex, oid and ip are the SnmpSet 1.x types. ticks, cnt32,
  cnt64 and bits are new in 2.0.

  A ticks value may be a time alone, 1d 10:17:36.78 or 00:00:43.21, or the
  whole value as it is printed, (12345678) 1d 10:17:36.78, so a printed value
  can be given back. The number and the time must then agree. A value with a
  space needs quotes: "-val:1d 10:17:36.78".

  bits takes bit numbers separated by commas, spaces or |, and an empty value
  sets no bits. Labels such as up need -m, without -tp (section 6).

  The agent decides whether it accepts the type and the value. If it does not,
  it answers with an SNMP error such as wrongType or badValue (exit code 1).
  Counter64 needs SNMP v2c or v3; with v1 it is a usage error, and nothing is
  sent.


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 SnmpSet 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
----------
  An agent that accepts a SET answers with the variable and value it was
  sent. snmp-set prints that answer in the same form as snmp-get; to read
  the value the device now holds, use snmp-get afterwards:

    .1.3.6.1.2.1.1.5.0 = STRING: "MainRouter"
    .1.3.6.1.4.1.32473.1.9.0 = Hex-STRING: 0A 1B
    .1.3.6.1.4.1.32473.1.9.0 = IpAddress: 10.0.0.5

  With -q, only the value is printed:

    MainRouter

  An agent that refuses the SET answers with an SNMP error, which goes to
  standard error with exit code 1:

    snmp-set: SNMP SET failed: SNMP error from 10.0.0.1:161: badValue at
    index 1

  The usual errors are noSuchName or notWritable (the OID cannot be
  written), wrongType, badValue or wrongValue (the value is not accepted),
  and noAccess or authorizationError (the community or user may not write).
  A wrong community is often not answered at all, which shows as a timeout.

  Errors and warnings go to standard error, starting with "snmp-set:", so
  they never mix with the value on standard output.


6. MIB catalog (-m, -d, -strict)
---------------------------------
  With -m, snmp-set gives each value its type from the MIB, checks it, and
  shows the answer by name. 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/).

  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-set
  looks for it in the folder that holds snmp-set, or in the folder given as
  -m:DIR. See README.txt, section 6, for how to set it up.

  Without -tp, the value is sent with the object's type from the MIB, and
  -val may be written the way -m prints values:

    Object type               -val examples
    ------------------------  ---------------------------------------------
    enumeration               down, down(2) or 2
    BITS                      up,loopback, or bit numbers such as 0,3, or
                              up(0) loopback(3)
    MAC address and other     00:1a:2b:3c:4d:5e
    display hints
    DateAndTime               2026-10-26,13:30:15.0 or
                              2026-10-26,13:30:15.0,+2:0
    fixed point (d-2)         12.50  (a plain integer such as 1250 is sent
                              as it is)
    hex integer (x)           0x10 or ff  (a plain number such as 10 is
                              always decimal, even where -m prints hex)
    IpAddress                 10.0.0.1
    OBJECT IDENTIFIER         .1.3.6.1.2.1.2.2 or the MODULE::name of a
                              scalar or column in the catalog, such as
                              IF-MIB::ifDescr or SNMPv2-MIB::sysUpTime.
                              Tables and notifications must be given as
                              numbers.
    TimeTicks                 a number, or a time as it is printed, such as
                              1d 10:17:36.78
    Counter32, Counter64,     a number
    Gauge32, Unsigned32

  With -m, -o and the OIDs of -vb and -vbf may also be names, as -m prints
  them: IF-MIB::ifAdminStatus.3, SNMPv2-MIB::sysName.0, 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.

  -tp still sets the type when given. Before sending, the value is checked
  against the object: whether it is writable, whether a -tp type fits it,
  and its listed enumeration values, ranges, size and display hint. A failed
  check is a warning, and the value is sent anyway:

    snmp-set: warning: 300 is outside 1..255 for IP-MIB::ipDefaultTTL

  With -strict a failed check is an error, and nothing is sent (exit code
  2):

    snmp-set: 300 is outside 1..255 for IP-MIB::ipDefaultTTL; nothing sent
    (--strict)

  Two more things are reported the same way, as a warning, or as an error
  with -strict:

  + A BITS flag written as name(number) whose number is not the bit of
    that name, such as up(5) when up is bit 0. The name decides the bit.
  + An object whose type snmp-set cannot build from text, such as Opaque.
    The value is sent as str, which the device will most likely refuse.
    No -tp type sends an Opaque value either.

  The answer is shown by name, with the value decoded:

    IF-MIB::ifAdminStatus.3 = INTEGER: down(2)

  -d is a dry run: it prints the value that would be sent and the object's
  definition, and sends nothing. For example:

    Would set IF-MIB::ifAdminStatus.3 = INTEGER: down(2)
    Nothing was sent (-d).

    IF-MIB::ifAdminStatus
      OID:        .1.3.6.1.2.1.2.2.1.7
      ...
      Values:     up(1), down(2), testing(3)
      Access:     read-write
      ...

  A value for an OID that the catalog does not know is sent as it would be
  without -m: with the -tp type, or as a string with a note on standard error.
  The same happens, after a warning, when the index or a module file is
  missing or damaged. With -strict, a value that cannot be checked is refused,
  and nothing is sent (exit code 2):

    snmp-set: no MIB definition for .1.3.6.1.4.1.32473.1.5.0, so the
    value cannot be checked; nothing sent (--strict)


7. Several variables in one request (-vb, -vbf)
-------------------------------------------------
  The agent applies all the variables of one SET together: it changes all of
  them or none. Some changes need that, such as creating a table row with
  RowStatus createAndGo(4), or an address and its address type; it also
  means a failure changes nothing. snmp-row (snmp-row.txt) is the easier way
  to create and delete table rows.

  -vb gives one variable and may be repeated:

    -vb:OID=VALUE
    -vb:OID:TYPE=VALUE

  The variable is split at the first = that is not inside double quotes, so
  the value may contain = and :. TYPE is one of the -tp names (section 3);
  without it the value is a string, or with -m it has the object's type, as
  for -val. Only a -tp name after the last : counts as a type, so
  -vb:IF-MIB::ifAlias.3=Uplink has none.

  A value that starts with " is a quoted string, which ends at the next "
  that is not escaped; inside it, \" is a double quote, \\ a backslash, \n
  a line feed and \t a tab. Any other value is taken exactly as written,
  including spaces at the end. = with nothing after it sets an empty string.

    -vb:.1.3.6.1.2.1.2.2.1.7.3:int=2         INTEGER 2
    -vb:.1.3.6.1.2.1.1.6.0=Server room 2     the text Server room 2
    -vb:.1.3.6.1.2.1.1.6.0="Room 2  "        with two spaces at the end
    -vb:.1.3.6.1.2.1.1.6.0="Line 1\nLine 2"  two lines
    -vb:IF-MIB::ifAdminStatus.3=down         with -m

  -vbf reads the same variables from a file, one per line, each in the form
  that follows -vb:. -vbf:- reads them from standard input. Lines that start
  with # and blank lines are skipped, and spaces and tabs at the start of a
  line are ignored. The file may be UTF-8, or UTF-16 with a byte order mark,
  as Notepad saves it, with CRLF or LF line ends:

    # VLAN 100 for the lab
    .1.3.6.1.2.1.17.7.1.4.3.1.1.100:str=Lab
    .1.3.6.1.2.1.17.7.1.4.3.1.5.100:int=4

  A mistake in the file names the file and the line, and nothing is sent:

    snmp-set: vlan.txt line 3: value 'x' is not an int (-2147483648 to
    2147483647)

  -vb and -vbf can be combined: the file's variables come first, then the
  -vb ones. An OID given twice is sent once, with the later value, and a
  warning. -o, -val and -tp cannot be combined with -vb or -vbf; alone, they
  work exactly as in SnmpSet 1.x.

  All the variables go into one request, however many there are. An agent
  that finds the request too big answers tooBig; snmp-set then says how many
  variables were sent. Splitting them into several runs works, but the runs
  are then not all-or-nothing.

  With -m, every value is typed and checked as for -val (section 6); -strict
  refuses the whole request if any value fails a check, and -d prints every
  value that would be sent and each object's definition.

  On success, snmp-set prints one line per variable of the agent's answer,
  in the order sent. With -vb or -vbf, -q prints nothing, and the exit code
  says whether the request succeeded. When the agent refuses the request, the
  error names the variable it refused:

    snmp-set: SNMP SET failed: notWritable for .1.3.6.1.2.1.1.1.0

  In Windows PowerShell 5.1, a value with " inside a quoted argument needs
  \" for each quote; a -vbf file avoids that.


8. Exit codes
--------------
  0   The agent accepted the request. With -d: the dry run completed.
  1   The request failed: timeout, unknown host, or an SNMP error from the
      agent, such as notWritable or badValue.
  2   Usage error: a missing or invalid option, a value that does not fit
      -tp, or a value refused by -strict. Nothing was sent.


9. Examples
------------
  Set sysName with SNMPv1 and the community "admin_rw":
    snmp-set -r:10.0.0.1 -t:10 -c:admin_rw -o:.1.3.6.1.2.1.1.5.0
             -val:MainRouter

  Set sysContact with SNMP v2c, GNU options, printing only the new value:
    snmp-set --host MainRouter --snmp-version 2c --quiet
             --oid .1.3.6.1.2.1.1.4.0 --value "Network Team"

  Write an integer with SNMPv3 (MD5 and DES):
    snmp-set -r:::1 -v:3 -sn:SomeName -ap:MD5 -aw:SomeAuthPass -pp:DES
             -pw:SomePrivPass -o:.1.3.6.1.2.1.11.30.0 -val:1 -tp:int

  Write raw bytes and an IP address:
    snmp-set -r:10.0.0.1 -o:.1.3.6.1.4.1.32473.1.1.0 -val:0A1B -tp:hex
    snmp-set -r:10.0.0.1 -o:.1.3.6.1.4.1.32473.1.2.0 -val:10.0.0.5 -tp:ip

  Write a TimeTicks value of one hour, and a Counter64 value:
    snmp-set -r:10.0.0.1 -o:.1.3.6.1.4.1.32473.1.3.0 -val:360000 -tp:ticks
    snmp-set -r:10.0.0.1 -v:2c -o:.1.3.6.1.4.1.32473.1.4.0 -val:5000000000
             -tp:cnt64

  Shut down interface 3 by label, refusing values that break the MIB:
    snmp-set -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.2.2.1.7.3 -val:down -m -strict

  Check first what that would send, without sending it:
    snmp-set -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.2.2.1.7.3 -val:down -m -d

  The same by name:
    snmp-set -r:10.0.0.1 -v:2c -m -o:IF-MIB::ifAdminStatus.3 -val:down

  Set the contact and the location together:
    snmp-set -r:10.0.0.1 -v:2c -vb:.1.3.6.1.2.1.1.4.0=Admin
             "-vb:.1.3.6.1.2.1.1.6.0=Server room 2"

  Create VLAN 100 from a file, with the MIB checking each value:
    snmp-set -r:10.0.0.1 -v:2c -m -strict -vbf:vlan100.txt

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