==============================================================================
snmp-trap-gen - send an SNMP trap or inform to a receiver
==============================================================================

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

Contents
--------
  1. Synopsis
  2. Options
  3. The trap
  4. Variables
  5. SNMPv3
  6. Informs (-inform)
  7. MIB catalog (-m, -strict)
  8. Output
  9. Exit codes
 10. Changes from SnmpTrapGen 1.x
 11. Examples


1. Synopsis
------------
  snmp-trap-gen [-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]] [-strict] [-inform] -to:trap_oid [-eo:ent_oid]
                [ -vid:var_oids [-vtp:var_types] -val:var_values [-del:text]
                | [-vb:oid[:type]=value ...] [-vbf:file] ]

  snmp-trap-gen sends one SNMP trap to a trap receiver, such as a network
  management system, and exits. With -inform it sends an inform instead,
  which the receiver acknowledges. It is the 2.0 version of SnmpTrapGen
  1.x, whose command lines keep working; section 10 lists the differences.

  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,
  and quote every list that contains a ; so it does not end the command:
      snmp-trap-gen '-r:10.0.0.1' '-to:.1.3.6.1.4.1.32473.0.7' '-del:;'
                    '-vid:.1.3.6.1.2.1.1.5.0;.1.3.6.1.2.1.1.6.0'
                    '-vtp:str;str' '-val:router;lab'


2. Options
-----------
  Colon form       GNU form                Meaning
  ---------------  ----------------------  -----------------------------------
  -r:host          --host HOST             Name or address (IPv4 or IPv6) of
                                           the receiver. Required.
  -to:trap_oid     --trap-oid OID          The trap's OID, sent as
                                           snmpTrapOID.0, or with -m its
                                           name, such as IF-MIB::linkDown.
                                           Required. See section 3.
  -eo:ent_oid      --enterprise-oid OID    The enterprise of a standard trap
                                           such as coldStart. Default:
                                           snmpTraps. See section 3.
  -vid:var_oids    --var-oids OIDS         The variables' OIDs, split at
                                           -del. See section 4.
  -vtp:var_types   --var-types TYPES       The variables' types, split at
                                           -del: int, uint, str, hex, oid,
                                           ip, ticks, cnt32, cnt64 or bits.
                                           Default: str, or the object's
                                           type with -m.
  -val:var_values  --var-values VALUES     The variables' values, split at
                                           -del.
  -del:text        --delimiter TEXT        What separates the items of -vid,
                                           -vtp and -val. Default: none, so
                                           each list is one item.
  -vb:oid=value    --varbind VARBIND       One variable, as OID=VALUE or
                                           OID:TYPE=VALUE. May be repeated.
                                           See section 4.
  -vbf:file        --varbind-file FILE     A file with one variable per
                                           line, as for -vb; -vbf:- reads
                                           standard input.
  -inform          --inform                Send an inform, which the
                                           receiver acknowledges, instead of
                                           a trap (v2c and v3). See section 6.
  -p:port          --port PORT             UDP port of the receiver.
                                           Default: 162
  -t:timeout       --timeout SECONDS       How long to wait for an inform's
                                           answer, and for the host's name,
                                           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 nothing on success.
  -m[:dir]         --mib[=DIR]             Name the OIDs, and type and check
                                           the values, from the MIB catalog.
                                           See section 7.
  -strict          --strict                With -m, send nothing if a check
                                           fails. See section 7.

  SNMPv3 options (see section 5):

  -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         For a trap, the sending computer's
                                           engine ID, in hex. Default:
                                           80 00 D8 F8 04 and the host name.
                                           For an inform, the receiver's,
                                           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 the engine ID.

  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 trap
------------
  SNMP v2c and v3 send an SNMPv2-Trap with these variables:

    sysUpTime.0              The sending computer's uptime, in hundredths
                             of a second.
    snmpTrapOID.0            -to.
    the variables            In the order given (section 4).
    snmpTrapEnterprise.0     -eo, for a standard trap only.

  SNMP v1 has a different trap, without snmpTrapOID.0. snmp-trap-gen builds
  it from -to, as RFC 3584 translates between the two:

  + The six standard traps, .1.3.6.1.6.3.1.1.5.1 (coldStart) to .6
    (egpNeighborLoss), are generic-trap 0 to 5, with specific-trap 0 and
    the enterprise -eo, or snmpTraps (.1.3.6.1.6.3.1.1.5) without it.
  + Any other -to is enterprise-specific (generic-trap 6): its last number
    is the specific-trap, and the rest is the enterprise, without the 0
    that usually comes before the last number. So -to:.1.3.6.1.4.1.32473.0.7
    is enterprise .1.3.6.1.4.1.32473, specific-trap 7. This is also the OID
    a receiver shows for such a v1 trap.
  + The agent address is the sending computer's IPv4 address on the way to
    the receiver, and 0.0.0.0 toward an IPv6 receiver. The time-stamp is
    its uptime.

  With an enterprise-specific -to, the enterprise is the one in -to, so a
  different -eo is ignored, with a warning.


4. Variables
-------------
  A trap may carry variables, given in one of two ways that cannot be
  combined.

  The first way, as in SnmpTrapGen 1.x, is three lists: -vid for the OIDs,
  -vtp for the types and -val for the values. Each list is split at the text
  given with -del. Without -del, each list is one item:

    -vid:.1.3.6.1.2.1.1.5.0 -val:router

  With -del, the lists hold one item per variable, in the same order:

    -del:; -vid:.1.3.6.1.2.1.1.5.0;.1.3.6.1.2.1.2.2.1.1.1 -vtp:str;int
    -val:router;1

  -vid and -val must have the same number of items, and so must -vtp when
  it is given. Without -vtp every value is a string, or with -m it has its
  object's type. An empty item is an empty value: -val:;b gives an empty
  string and b. -val: with nothing after the colon is one empty string.

  The types are those of snmp-set:

    int    INTEGER, -2147483648 to 2147483647
    uint   Gauge32 (the same wire type as Unsigned32), 0 to 4294967295
    str    OCTET STRING from the text as given
    hex    OCTET STRING from hex digits, such as 0A1B, 0a:1b or 0x0a1b
    oid    OBJECT IDENTIFIER, such as .1.3.6.1.4.1
    ip     IpAddress, such as 10.0.0.1
    ticks  TimeTicks, hundredths of a second or a time, such as 1d 10:17:36.78
    cnt32  Counter32, 0 to 4294967295
    cnt64  Counter64, 0 to 18446744073709551615; needs SNMP v2c or v3
    bits   BITS, as the numbers of the bits to set, such as 0,3

  The second way, as in snmp-set, is -vb and -vbf: -vb:OID=VALUE or
  -vb:OID:TYPE=VALUE gives one variable and may be repeated, and -vbf:FILE
  reads one such variable per line. Blank lines and lines that start with #
  are skipped. The value is everything after the first =, and a value in
  double quotes may use \" \\ \n \t. The file's variables come first, then the
  -vb ones. snmp-set.txt, section 7, describes the file.

  A value that does not fit its type is a usage error (exit code 2), and
  nothing is sent; the error message names the list item or the file line. An
  OID given twice is sent once, with the later value, and a warning. A
  Counter64 value needs v2c or v3.


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

  A trap comes from the sending computer's own SNMP engine, and the
  receiver checks it against that engine's ID: it must know the user under
  that engine ID.

  Without -ei the engine ID is 80 00 D8 F8 04 followed by the host name, at
  most 27 characters of it: the RFC 3411 text format, with EZ5 Systems'
  enterprise number 55544. The host name is the one Windows keeps in
  COMPUTERNAME, or Linux in /proc/sys/kernel/hostname. The engine ID is the
  same on every run, and differs from one computer to the next. -ei sets
  another.

  SnmpTrapGen 1.x always sent the engine ID SnmpTrapGen, so a receiver set
  up for it knows the user under that ID. To keep it working, give

    -ei:536E6D705472617047656E

  Nothing is stored between runs, so each run is a new start of the engine,
  numbered by the clock: snmpEngineBoots is the number of seconds since
  2020-01-01 UTC, and the engine time starts at 0. The number grows from
  run to run, as receivers require, so a receiver drops an old trap that
  is sent again later. A clock that is set back makes the receiver drop
  traps until it reaches the time it was set back from.

  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 the engine ID. The SNMPv3
  options are rejected with -v:1 and -v:2c.


6. Informs (-inform)
---------------------
  A trap has no answer, so its sender cannot tell whether it arrived. An
  inform carries the same variables, and the receiver answers it.
  snmp-trap-gen -inform waits up to -t seconds for that answer, once, and
  exits with 1 without it:

    snmp-trap-gen: the inform got no answer within 5 s (-t)

  Informs need v2c or v3. With v3 the receiver's engine is the one that
  counts, so snmp-trap-gen finds its engine ID first, as snmp-get finds an
  agent's, unless -ei gives it. The receiver must know the user under its
  own engine ID.


7. MIB catalog (-m, -strict)
-----------------------------
  -m uses the MIB catalog, a set of parsed MIB files on the local disk, as in
  the other tools:

  + -to, -eo and the variables' OIDs may be names, such as
    IF-MIB::linkDown and IF-MIB::ifOperStatus.3. A name without -m, or one
    the catalog cannot find, is a usage error.
  + Each value is built from its object's type, unless a type is given, and
    may be written the way -m prints values, such as down for
    ifOperStatus. It is checked as snmp-set checks a value (snmp-set.txt,
    section 6), except that the object need not be writable: a trap only
    reports it. A failed check is a warning.
  + A variable that is not one of the trap's OBJECTS is a warning:

      snmp-trap-gen: warning: IF-MIB::ifSpeed.3 is not one of the OBJECTS
      of IF-MIB::linkDown (ifIndex, ifAdminStatus, ifOperStatus)

  + A -to OID that the catalog does not list as a notification is a warning
    too.

  -strict makes every warning a usage error, and nothing is sent (exit
  code 2). It also refuses a value that the catalog cannot check.

  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-trap-gen looks for it in the folder that holds snmp-trap-gen, 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 and the trap is sent as it would be without -m. If an OID was
  given as a name, or -strict is set, it is a usage error instead.


8. Output
----------
  When the trap is sent, or the inform acknowledged, snmp-trap-gen prints

    OK

  as SnmpTrapGen 1.x does, without 1.x's header lines. With -q it prints
  nothing, and the exit code says whether it worked. A trap has no answer,
  so OK means only that it was sent; -inform makes sure it arrived.

  Errors and warnings go to standard error, starting with "snmp-trap-gen:".


9. Exit codes
--------------
  0   The trap was sent, or the inform was acknowledged.
  1   Sending failed: an unknown host, a network error, or an inform that
      got no answer within -t.
  2   Usage error: a missing or invalid option, lists that do not match, a
      name that cannot be found, a value that does not fit its type, or a
      check refused by -strict. Nothing was sent.


10. Changes from SnmpTrapGen 1.x
---------------------------------
  The 1.x command lines keep working. These things behave differently:

  + SNMPv3 traps carry the sending computer's own engine ID (section 5),
    and -ei sets it. 1.x always sent SnmpTrapGen and ignored -ei: give
    -ei:536E6D705472617047656E for receivers set up for 1.x.
  + -vtp may be left out, as the 1.x help says; 1.x required it.
  + -eo is used for the standard traps (section 3). 1.x ignored it, and
    sent the enterprise .0.0 for a standard v1 trap.
  + An empty list item is an empty value, where 1.x refused the lists.
  + A value that does not fit its type is an error: 1.x sent abc as the
    integer 0, and the hex 0a:1b as 00 a0 1b.
  + Errors go to standard error with exit code 2 for a usage error, and an
    unknown option is an error. 1.x printed errors on standard output, and
    exited with 0 after some of them, such as lists that do not match.
  + The output is the word OK, without the 1.x header lines.
  + New: -vb and -vbf, -inform, -m and -strict, SHA-224 to SHA-512,
    AES192-REEDER and AES256-REEDER, and GNU options.


11. Examples
-------------
  An enterprise-specific v1 trap, as in 1.x:
    snmp-trap-gen -r:10.0.0.1 -to:.1.3.6.1.4.1.32473.0.7

  A v2c coldStart trap with its enterprise, to port 10162, printing
  nothing:
    snmp-trap-gen -r:SnmpCollector -q -v:2c -p:10162
                  -to:.1.3.6.1.6.3.1.1.5.1 -eo:.1.3.6.1.4.1.32473

  Two variables in the 1.x lists:
    snmp-trap-gen -r:10.0.0.1 -v:2c -to:.1.3.6.1.4.1.32473.0.7 -del:;
                  -vid:.1.3.6.1.2.1.1.5.0;.1.3.6.1.2.1.2.2.1.1.1
                  -vtp:str;int -val:router;1

  A linkDown trap by name, its values typed by the MIB:
    snmp-trap-gen -r:10.0.0.1 -v:2c -m -to:IF-MIB::linkDown
                  -vb:IF-MIB::ifIndex.3=3 -vb:IF-MIB::ifAdminStatus.3=up
                  -vb:IF-MIB::ifOperStatus.3=down

  An SNMPv3 inform with authentication and privacy:
    snmp-trap-gen -r:10.0.0.1 -v:3 -sn:SomeName -ap:SHA256
                  -aw:SomeAuthPass -pp:AES128 -pw:SomePrivPass -inform
                  -to:.1.3.6.1.4.1.32473.0.7

  An SNMPv3 trap to a receiver set up for SnmpTrapGen 1.x:
    snmp-trap-gen -r:10.0.0.1 -v:3 -sn:SomeName -ap:SHA -aw:SomeAuthPass
                  -ei:536E6D705472617047656E -to:.1.3.6.1.4.1.32473.0.7

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