==============================================================================
SNMPSoft Tools 2.0 - command-line SNMP tools for network administrators
==============================================================================

snmp-get, snmp-set, snmp-walk, snmp-table, snmp-row and snmp-trap-gen,
version 2.0.0
Copyright (C) 2026 EZ5 Systems Ltd. https://ezfive.com/snmpsoft-tools/

Contents
--------
  1. Overview
  2. Features
  3. System requirements
  4. Installation
  5. Quick start
  6. MIB catalog
  7. Exit codes
  8. Privacy
  9. Upgrading from SnmpGet, SnmpSet, SnmpWalk and SnmpTrapGen 1.x
 10. License
 11. Support and contact
 12. Version history


1. Overview
------------
  SNMPSoft Tools are command-line programs for SNMP, the standard protocol
  for monitoring and managing network devices such as routers, switches,
  firewalls, printers and UPSs:

    snmp-get       reads the value of one SNMP variable.
    snmp-set       changes the value of one SNMP variable, or of several
                   together.
    snmp-walk      lists the variables of a device, or of a part of its
                   MIB tree, such as one table.
    snmp-table     prints one table, such as the interface table, as a
                   grid or as CSV.
    snmp-row       adds or deletes a row of a table, such as a VLAN.
    snmp-trap-gen  sends a trap or an inform to a management system.

  They are made for scripts: the value goes to standard output, errors go
  to standard error, and the exit code is 0 only on success.

  Version 2.0 is a new implementation of SnmpGet, SnmpSet, SnmpWalk and
  SnmpTrapGen 1.x. The 1.x options still work, so most scripts only need
  the new program names (see section 9). New in 2.0: SNMPv3 with SHA-2,
  GNU-style options, Linux builds, names and decoded values from the EZ5
  MIB Catalog, and the tools snmp-table and snmp-row.

  Each tool has a full reference in the docs folder: docs/snmp-get.txt,
  docs/snmp-set.txt, docs/snmp-walk.txt, docs/snmp-table.txt,
  docs/snmp-row.txt and docs/snmp-trap-gen.txt. "snmp-get --help" prints a
  summary of the options.


2. Features
------------
  + SNMP v1, v2c and v3
  + SNMPv3 authentication: MD5, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512
  + SNMPv3 privacy: DES, 3DES, AES-128, AES-192, AES-256
  + IPv4 and IPv6, host names or addresses
  + All SNMP value types
  + The 1.x colon options (-r:host) and GNU options (--host host)
  + Walk output as text or CSV, for whole devices, subtrees or OID ranges
  + Fast walks with GETBULK on SNMP v2c and v3
  + Tables as a grid or as CSV, with one column per index part
  + Table rows created and deleted through their RowStatus column
  + Several variables in one all-or-nothing SET (-vb, -vbf)
  + Traps in SNMP v1, v2c and v3, and acknowledged informs
  + OIDs by name and decoded values with the MIB catalog (-m), such as
    IF-MIB::ifOperStatus.3 = INTEGER: up(1), and names as input, such as
    -o:IF-MIB::ifAdminStatus.3
  + Object definitions (-d), and SET and trap values checked against the
    MIB
  + Single executables with no installer, no runtime and no dependencies


3. System requirements
-----------------------
  Windows:  Windows 10 or 11, or Windows Server 2016 or later, x64.
  Linux:    Any distribution on x64 or ARM64 (aarch64), such as a Raspberry
            Pi with a 64-bit system. The programs are statically linked, so
            they need no particular library versions.

  The device you query must have SNMP enabled, and must accept requests
  from your computer, usually on UDP port 161.


4. Installation
----------------
  Windows:
    1. Unzip the archive into a folder, for example C:\Tools\snmp-tools.
    2. Optional: add that folder to the PATH, so the tools can be run from
       any folder. In Settings, search for "environment variables", edit
       Path, and add the folder.
    3. Open Command Prompt or PowerShell and run:
         snmp-get --version

  Linux:
    1. Unpack the archive and copy the programs to a folder in the PATH:
         tar -xzf snmp-tools-2.0.0-linux-x64.tar.gz
         sudo cp snmp-tools-2.0.0-linux-x64/snmp-* /usr/local/bin/
       (use the linux-arm64 archive on ARM64).
    2. Check that they run:
         snmp-get --version

  Commercial license: put the license file (.lic) that EZ5 Systems sent
  you in the same folder as the programs; on Linux, copy it to
  /usr/local/bin with them. snmp-get --version then shows the license.

  To uninstall, delete the files. The tools write no settings anywhere.


5. Quick start
---------------
  Options can be given in the 1.x colon form, -r:10.0.0.1, or in the GNU
  form, --host 10.0.0.1. Run a tool with --help for the full list. The
  defaults are SNMP version 1, port 161 (162 for snmp-trap-gen), a 5 second
  timeout and the community "public" ("private" for snmp-set and
  snmp-row).

  In PowerShell, quote the colon options: '-r:10.0.0.1'. Windows
  PowerShell 5.1 drops a double quote inside an argument it passes to a
  program, so write each one as \" there, as in
  '-o:IP-MIB::ipAddressIfIndex.ipv4.\"10.0.0.1\"'.

  The tools write text as UTF-8. Windows PowerShell 5.1, the version built
  into Windows, garbles non-ASCII characters (such as accented letters) in
  output it captures, as in $name = snmp-get ..., unless you first run:

    [Console]::OutputEncoding = [Text.Encoding]::UTF8

  The console display, Command Prompt and PowerShell 7 need no change.

  snmp-get - read one variable (details: docs/snmp-get.txt)

    snmp-get -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.1.5.0
    .1.3.6.1.2.1.1.5.0 = STRING: "MainRouter"

    snmp-get -q -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.1.5.0
    MainRouter

    snmp-get -r:10.0.0.1 -v:3 -sn:admin -ap:SHA256 -aw:AuthPassword
             -pp:AES128 -pw:PrivPassword -o:.1.3.6.1.2.1.1.3.0

  snmp-set - change variables (details: docs/snmp-set.txt)

    snmp-set -r:10.0.0.1 -v:2c -c:admin_rw -o:.1.3.6.1.2.1.1.5.0
             -val:MainRouter
    .1.3.6.1.2.1.1.5.0 = STRING: "MainRouter"

    snmp-set -r:10.0.0.1 -v:2c -c:admin_rw -o:.1.3.6.1.2.1.2.2.1.7.3
             -val:2 -tp:int

    snmp-set -r:10.0.0.1 -v:2c -c:admin_rw -vb:.1.3.6.1.2.1.1.4.0=Admin
             "-vb:.1.3.6.1.2.1.1.6.0=Server room 2"

  snmp-walk - list variables (details: docs/snmp-walk.txt)

    snmp-walk -r:10.0.0.1 -v:2c -os:.1.3.6.1.2.1.1
    .1.3.6.1.2.1.1.1.0 = STRING: "ER-2400 Router, Version 4.2.1"
    .1.3.6.1.2.1.1.2.0 = OID: .1.3.6.1.4.1.32473.1.1
    ...

    snmp-walk -r:10.0.0.1 -v:2c -os:.1.3.6.1.2.1.2.2 -csv > interfaces.csv

  snmp-table - print a table (details: docs/snmp-table.txt)

    snmp-table -r:10.0.0.1 -v:2c -o:.1.3.6.1.2.1.2.2
    Index  1  2     3   ...
    -----  -  ----  --
    1      1  lo    24
    2      2  eth0  6

    snmp-table -r:10.0.0.1 -v:2c -m -o:IF-MIB::ifTable -csv > interfaces.csv

  snmp-row - add or delete a table row (details: docs/snmp-row.txt)

    snmp-row -r:10.0.0.1 -v:2c -c:admin_rw -m -add
             -o:Q-BRIDGE-MIB::dot1qVlanStaticTable -i:100
             -vb:dot1qVlanStaticName=Lab

    snmp-row -r:10.0.0.1 -v:2c -c:admin_rw -m -rm
             -o:Q-BRIDGE-MIB::dot1qVlanStaticTable -i:100

  snmp-trap-gen - send a trap (details: docs/snmp-trap-gen.txt)

    snmp-trap-gen -r:10.0.0.5 -v:2c -to:.1.3.6.1.4.1.32473.0.7
                  -vb:.1.3.6.1.2.1.1.5.0=MainRouter
    OK

    snmp-trap-gen -r:10.0.0.5 -v:2c -m -inform -to:IF-MIB::linkDown
                  -vb:IF-MIB::ifIndex.3=3 -vb:IF-MIB::ifAdminStatus.3=up
                  -vb:IF-MIB::ifOperStatus.3=down

  (Commands shown on two lines are typed on one line.)


6. MIB catalog
---------------
  Without a catalog, the tools show OIDs and values in numeric form. With
  the option -m and the EZ5 MIB Catalog, they show names and decoded
  values:

    snmp-walk -r:10.0.0.1 -v:2c -os:.1.3.6.1.2.1.2.2.1.8 -m
    IF-MIB::ifOperStatus.1 = INTEGER: up(1)
    IF-MIB::ifOperStatus.2 = INTEGER: down(2)

    MIBs:
      IF-MIB (2)

  The catalog is not included in this archive, because it is updated more
  often than the tools. To set it up:

    1. Download the newest index, mib-index-YYYYMMDD-HHMM.bin.gz, from the
       home page of https://mibs.ezfive.com/. The tools read it as .bin.gz;
       there is no need to unpack it.
    2. For each MIB module you use, open its page on mibs.ezfive.com and
       download its parsed-MIB file, <MODULE>.json.gz, such as
       IF-MIB.json.gz.
    3. Put the files in the folder that holds the tools, or in any folder
       you then give as -m:DIR, for example -m:C:\mibs or -m:/opt/mibs.

  The index alone is enough to tell which MIB module an OID belongs to;
  the module files add the names and decoding. When several index files
  are in the folder, the newest is used; if it is damaged, the next newest
  is used, with a warning. A missing or damaged file is only a warning,
  and the tool then works as without -m, except that a name cannot be
  found.

  With -m, snmp-get -d and snmp-set -d also print the object's definition
  from the MIB, and snmp-set, snmp-row and snmp-trap-gen check values
  against it before sending (-strict refuses a value that does not fit).
  snmp-trap-gen also checks a trap's variables against its OBJECTS. OIDs
  may then be given by name, such as -o:IF-MIB::ifAdminStatus.3; a name
  without -m is a usage error. snmp-table names its columns and splits each
  row's index into its parts, and snmp-row finds a table's RowStatus column
  and the types of its columns. snmp-walk -m -n keeps the numeric OIDs and
  still decodes the values and lists the MIB modules it found.


7. Exit codes
--------------
  All the tools exit with:

    0   Success.
    1   The request failed: timeout, unknown host, or an SNMP error from
        the device. For snmp-get, also a variable the device does not have;
        for snmp-trap-gen, an inform that gets no answer.
    2   Usage error: a missing or invalid option or value. Nothing was sent.

  Error messages are written to standard error and start with the name of
  the tool, such as "snmp-get: SNMP GET failed: timeout ...".


8. Privacy
-----------
  The tools do not collect personal data and send nothing to EZ5 Systems.
  They contact only the hosts you name on the command line; a host name is
  first looked up through your system's name service (DNS). They read only
  two kinds of files: the MIB catalog, in the folder you give with -m or,
  when -m has no folder, in the folder that holds the tools; and, for
  --version and --help only, license files (.lic) in the folder that holds
  the tools. Passwords and community strings are used only for the SNMP
  requests you ask for, and are not stored.


9. Upgrading from SnmpGet, SnmpSet, SnmpWalk and SnmpTrapGen 1.x
------------------------------------------------------------------
  The 1.x options, their meaning and their defaults are kept, so most
  scripts only need the new program names. Check these differences:

  + Version 2.0 has a new license. It is free for non-commercial use; other
    use, such as for a business or a government body, needs a commercial
    license after a 30-day evaluation (see section 10). Version 1.x stays
    under its own license.
  + The programs are named snmp-get, snmp-set, snmp-walk and
    snmp-trap-gen (snmp-get.exe and so on, on Windows), instead of
    SnmpGet.exe, SnmpSet.exe, SnmpWalk.exe and SnmpTrapGen.exe. To keep old
    scripts unchanged, you can copy or rename snmp-get.exe to SnmpGet.exe;
    the tool works under any name.
  + Each variable is printed on one line, as the OID, the type and the
    value, such as .1.3.6.1.2.1.1.5.0 = STRING: "MainRouter". The 1.x
    header lines are gone, so check scripts that parse the full output.
    -q still prints the value only. snmp-walk -csv writes the columns
    OID,Type,Value. Timeticks are written as (12345678) 1d 10:17:36.78:
    the number of hundredths of a second in parentheses, then days and
    time. There is no comma, so the value needs no quoting in CSV.
  + The IDEA privacy protocol is no longer supported.
  + -ce (context engine) is accepted only when it is the same as -ei.
  + Invalid options are reported before anything is sent, with exit code
    2. SNMPv3 passwords must be at least 8 octets long, as SNMPv3
    requires.
  + snmp-trap-gen sends SNMPv3 traps from the sending computer's own engine
    ID, where SnmpTrapGen 1.x always sent SnmpTrapGen. For a receiver set
    up for 1.x, add -ei:536E6D705472617047656E. It prints OK on success, as
    1.x did, without the header lines. docs/snmp-trap-gen.txt, section 10,
    lists its other changes.
  + New: SHA-224/256/384/512, AES192-REEDER and AES256-REEDER (for Cisco
    devices), GNU options, Linux builds, -m, -d and -strict, and the value
    types ticks, cnt32, cnt64 and bits.


10. License
------------
  SNMPSoft Tools are free for non-commercial use: personal use, teaching
  and research, and registered charities and non-profit organizations. Any
  other use, such as use for a business or a government body, or running
  the production network of a school or university, needs a commercial
  license after a 30-day evaluation; contact sales@ezfive.com.

  With a commercial license you receive a license file, which states your
  license; snmp-get --version shows it (see section 4).

  The full terms are in LICENSE.txt, which you accept by using the tools.
  Please read it, in particular the parts on commercial use, redistribution
  and the absence of warranty.

  The tools include open-source components. Their licenses are listed in
  ACKNOWLEDGEMENTS.txt.

  To include SNMPSoft Tools in a product you sell or supply, or to use the
  SNMP code as a library in your own software, contact sales@ezfive.com.


11. Support and contact
------------------------
  Web:      https://ezfive.com/snmpsoft-tools/
  MIBs:     https://mibs.ezfive.com/
  E-mail:   sales@ezfive.com

  When reporting a problem, please include the command line (without
  passwords), the full output, and the type of device.


12. Version history
--------------------
  2.0.0  - New implementation of SnmpGet, SnmpSet, SnmpWalk and
           SnmpTrapGen, now named snmp-get, snmp-set, snmp-walk and
           snmp-trap-gen, for Windows and Linux.
         - NEW: SNMPv3 authentication with SHA-224, SHA-256, SHA-384 and
           SHA-512, and AES-192/256 with the Reeder key extension.
         - NEW: GNU-style options alongside the 1.x colon options.
         - NEW: Names and decoded values from the EZ5 MIB Catalog (-m),
           object definitions (-d), and SET values checked against the
           MIB (-strict).
         - NEW: snmp-walk uses GETBULK with SNMP v2c and v3.
         - NEW: snmp-table prints a table as a grid or as CSV.
         - NEW: snmp-row adds and deletes table rows through their
           RowStatus column.
         - NEW: snmp-set sets several variables in one request (-vb,
           -vbf).
         - NEW: The value types ticks, cnt32, cnt64 and bits, for
           TimeTicks, Counter32, Counter64 and BITS values without the
           MIB catalog.
         - NEW: snmp-trap-gen sends acknowledged informs (-inform), and
           SNMPv3 traps with the sending computer's own engine ID.
         - NEW: OIDs by name as input with -m, such as
           IF-MIB::ifAdminStatus.3.
         - NEW: Linux builds for x64 and ARM64.
         - CHANGED: output format: one line per variable with the OID,
           the type and the value, and no header lines.
         - REMOVED: the IDEA privacy protocol.

  SnmpTrapGen 1.1         - NEW: Several variables in one trap
  SnmpWalk 1.02           - FIXED: CSV format output
  SnmpGet, SnmpSet,       - FIXED: Redirecting the output to a file
  SnmpWalk 1.01
  1.0                     - Initial release


==============================================================================
