==============================================================================
snmp-get - read one SNMP variable from a network device
==============================================================================

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

Contents
--------
  1. Synopsis
  2. Options
  3. SNMPv3
  4. Output
  5. MIB catalog (-m, -d)
  6. Exit codes
  7. Examples


1. Synopsis
------------
  snmp-get [-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] -o:var_oid

  snmp-get sends one SNMP GET request and prints the value of one variable.

  Every option has two forms: the colon form used by SnmpGet 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-get '-r:10.0.0.1' '-o:.1.3.6.1.2.1.1.1.0'


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 read, such
                                           as .1.3.6.1.2.1.1.5.0. The leading
                                           dot is optional. With -m also a
                                           name, such as SNMPv2-MIB::sysName.0
                                           (section 5). Required.
  -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: public
  -q               --quiet                 Print the value only.
  -m[:dir]         --mib[=DIR]             Show names and decoded values from
                                           the MIB catalog. See section 5.
  -d               --describe              With -m, also print the object's
                                           definition. Cannot be combined
                                           with -q.

  SNMPv3 options (see section 3):

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

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


4. Output
----------
  One line: the OID, the type and the value.

    .1.3.6.1.2.1.1.5.0 = STRING: "MainRouter"
    .1.3.6.1.2.1.1.3.0 = Timeticks: (12345678) 1d 10:17:36.78
    .1.3.6.1.2.1.2.2.1.6.1 = Hex-STRING: 00 1A 2B 3C 4D 5E

  With -q, only the value is printed, without quotes, which suits scripts:

    MainRouter

  Text is shown as STRING when it is readable text (UTF-8, line breaks and
  tabs allowed), and as Hex-STRING otherwise. Other types are INTEGER,
  Counter32, Counter64, Gauge32, UInteger32, Timeticks, IpAddress, OID,
  Opaque and NULL.

  An SNMP v2c or v3 agent answers a missing variable with a value, which is
  printed, and snmp-get exits with 1:

    .1.3.6.1.2.1.1.99.0 = No Such Object available on this agent at this OID

  With -q, nothing is printed on standard output, and the message goes to
  standard error, so a script never takes it for the value:

    snmp-get: No Such Object available on this agent at this OID:
    .1.3.6.1.2.1.1.99.0

  An SNMPv1 agent reports the same case as an error (also exit code 1):

    snmp-get: SNMP GET failed: SNMP error from 10.0.0.1:161: noSuchName at
    index 1

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


5. MIB catalog (-m, -d)
------------------------
  With -m, snmp-get shows the OID by name and decodes the value: enumeration
  labels such as up(1), display hints such as MAC addresses, and units.

    IF-MIB::ifOperStatus.3 = INTEGER: up(1)

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

  With -m, -o may also be a name, the way -m prints it, as in
  snmp-get -m -o:IF-MIB::ifOperStatus.3, 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.

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

  An OID that the catalog cannot name keeps its numeric form, and a second
  line names the MIB module it belongs to, or "unknown":

    .1.3.6.1.4.1.32473.1.9.0 = IpAddress: 10.0.0.5
    MIB: unknown

  With -q, only the decoded value is printed. If the index or a module file
  is missing or damaged, a warning goes to standard error and the GET runs
  as it does without -m.

  -d prints the object's definition after the value: its syntax, enumeration
  values, ranges, display hint, units, access, default value, description,
  and a warning if the value does not fit the type. For example:

    IF-MIB::ifIndex.2 = INTEGER: 2

    IF-MIB::ifIndex
      OID:        .1.3.6.1.2.1.2.2.1.1
      Table:      ifTable
      Index:      ifIndex
      Instance:   2
      Syntax:     InterfaceIndex (Integer32)
      Range:      1..2147483647
      Hint:       d
      Access:     read-only
      Module:     IF-MIB, last updated 2000-06-14

      A unique value, greater than zero, for each interface. It is recommended
      that values are assigned contiguously starting from 1. The value for
      each interface sub-layer must remain constant at least from one
      re-initialization of the entity's network management system to the next
      re- initialization.


6. Exit codes
--------------
  0   The agent answered with the variable's value.
  1   The request failed: timeout, unknown host, or an SNMP error; or the
      agent has no such variable ("No Such Object" or "No Such Instance").
  2   Usage error: a missing or invalid option. Nothing was sent.


7. Examples
------------
  Read sysDescr with SNMPv1 and the community "public":
    snmp-get -r:10.0.0.1 -o:.1.3.6.1.2.1.1.1.0

  The same with GNU options and SNMP v2c:
    snmp-get --host 10.0.0.1 --snmp-version 2c --oid .1.3.6.1.2.1.1.1.0

  Print only the value, from a non-standard port, with a 10 second timeout:
    snmp-get -q -r:MainRouter -v:2c -p:10161 -t:10 -o:.1.3.6.1.2.1.1.5.0

  SNMPv3 with SHA-256 and AES-128 over IPv6:
    snmp-get -r:::1 -v:3 -sn:SomeName -ap:SHA256 -aw:SomeAuthPass
             -pp:AES128 -pw:SomePrivPass -o:.1.3.6.1.2.1.1.1.0

  Interface status by name, with the catalog in another folder:
    snmp-get -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.2.2.1.8.3 -m:C:\mibs

  The same with the object's definition:
    snmp-get -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.2.2.1.8.3 -m -d

  Use the value in PowerShell (the first line keeps non-ASCII characters
  intact in Windows PowerShell 5.1; see README.txt section 5):
    [Console]::OutputEncoding = [Text.Encoding]::UTF8
    $name = snmp-get -q '-r:10.0.0.1' '-o:.1.3.6.1.2.1.1.5.0'
    if ($LASTEXITCODE -ne 0) { exit 1 }

  Use the value in a Linux shell script:
    name=$(snmp-get -q -r:10.0.0.1 -o:.1.3.6.1.2.1.1.5.0) || exit 1
