SNMP TRAP/INFORM#

SNMP notifications provide a way for an SNMP agent to send an asynchronous notification about conditions that the SNMP manager(s) might care about. The notifications that particular SNMP agent can generate are typically defined by the MIB(s) that agent supports.

The snmptrap.py tool implements SNMP TRAP and INFORM notification originator. TRAPs are typically produced by the SNMP agent.

The snmptrap.py behavior is tightly aligned with its Net-SNMP prototypes e.g. snmptrap and snmpinform.

Command line syntax is as follows:

snmptrap.py [options] <peer-address> <trap-parameters

Options always start with dash (-), other parameters are positional.

Options can be categorized by the part they are tackling e.g.

Past these named options, mandatory positional parameters follow:

Protocol options#

The following options have direct influence on SNMP engine operation.

SNMP version#

The -v option specifies SNMP version to be used:

  • 1 - SNMP version 1

  • 2c - SNMP version 2c

  • 3 - SNMP version 3

SNMP community#

The -c option sets SNMP v1/v2c community name. It serves like a shared secret and identification token between SNMP parties.

Note

The community name is never encrypted on the wire so it’s highly insecure. This is the sole reason why SNMP is sometimes jokingly referred to as Security – Not My Problem.

SNMPv3 USM security name#

The -u option sets SNMP user name to the User Security Module subsystem. This is a string from 1 to 32 octets of length. Should be configured in the same way at both SNMP entities trying to communicate.

SNMPv3 USM security level#

The -l option configures authentication and encryption features to be used. In SNMP parlance this is known as Security Level. Valid values are:

  • noAuthNoPriv - no authentication and no encryption

  • authNoPriv - use authentication but no encryption

  • authPriv - use both authentication and encryption

SNMPv3 authentication protocol#

SNMPv3 messages can be authenticated. The following authentication protocols can be chosen via the -a option:

SNMPv3 authentication key#

SNMPv3 message authentication involves a shared secret key known to both SNMP parties engaged in message exchange. This secret authentication key (AKA as passphrase) can be conveyed via the -A option.

Note

SNMP authentication key must be at least eight octets long.

SNMPv3 encryption protocol#

SNMPv3 messages can be encrypted (AKA as privacy). The following encryption protocols can be chosen via the -x option:

SNMPv3 encryption key#

SNMPv3 message encryption involves a shared secret key known to both SNMP parties engaged in message exchange. This secret encryption key (AKA as passphrase) can be conveyed via the -A option.

Note

SNMP encryption (e.g. privacy) key must be at least eight octets long.

SNMPv3 context engine ID#

The -E option sets the context engineID used for SNMPv3 REQUEST messages scopedPdu, given as a hexadecimal string. If not specified, this will default to the authoritative engineID.

SNMPv3 security engine ID#

The -e option sets the authoritative (security) engineID used for SNMPv3 REQUEST messages, given as a hexadecimal string. It is typically not necessary to specify engine ID, as it will usually be discovered automatically, unless master or localized USM keys are used.

SNMPv3 context name#

The -n option sets the SNMPv3 context name to SNMPv3 REQUEST messages. The default is the empty string. SNMP context name is used to address a specific instance of SNMP managed objects behind a single SNMP agent.

SNMPv3 engine boots and time#

The -Z option sets SNMP engine boot counter and its timeline values to SNMPv3 REQUEST message. These values are used for message authentication. It is typically not necessary to specify this option, as these values will usually be discovered automatically.

SNMPv3 USM master and localized keys#

The -3[MmKk] set of options allow for specifying master or localized keys for given USM user instead of pass phrase (via -A and -X options respectively).

  • -3m key - adds master authentication key (hashed passphrase or password) for USM security name

  • -3M key - adds master privacy key (hashed passphrase) for USM security name

  • -3k key - adds localized authentication key (passphrase hashed with security SNMP engine ID) for USM security name and SNMP security engine ID

  • -3K key - adds localized privacy key (passphrase hashed with security SNMP engine ID) for USM security name and SNMP security engine ID

The key argument could be an ASCII string or a hexadecimal string (if it starts with 0x prefix).

Regular pass-phrase, master and localized keys can be used together in any combination.

See RFC 3414#section-2.6 for more information on key localization algorithm.

Note

Using any of -3[kKMm] options effectively inactivate USM key localization mechanism. As a consequence, local SNMP engine configuration won’t get automatically populated with remote SNMP engine’s securityEngineId.

Therefore authoritative security SNMP engine ID should be specified along with -3[kKMm] options (via -e option).

Otherwise, the magic securityEngineId value of five zeros (0x0000000000) will be added to local configuration automatically to refer to the localized keys that should be used with any unknown authoritative SNMP engine.

Note

When SNMP TRAP is sent over authenticated/encrypted SNMP v3, SNMP engine discovery can not be performed. That implies that receiving SNMPv3 entity must have USM configuration tied to the SNMPv3 engine ID used by the snmptrap.py.

MIB options#

Pre-load MIBs#

You may want to pre-load some of the MIB modules to let the snmptrap.py tool rendering SNMP responses in a more meaningful way.

The -m option specifies a colon separated list of MIB modules (not files) to load. The snmptrap.py tool will first try to find pre-compiled pysnmp MIB files (by default in ~/.pysnmp/mibs in UNIX), then try to find required ASN.1 MIB file on local filesystem or on Web (by default it will look it up at https://mibs.pysnmp.com/asn1/). If ASN.1 MIB file is found, it will be compiled into pysnmp form and cached for future use.

The special keyword ALL is used to load all pre-compiled pysnmp MIB modules in the MIB directory search list.

MIB files search path#

The -M option specifies a colon separated list of local directories and/or URLs pointing to remote HTTP/FTP servers where to search for MIBs.

Note

Default MIB search path is https://mibs.pysnmp.com/asn1/

Input options#

The following one-letter options following the -I option modify the way how snmptrap.py tool processes its input.

Interpret DISPLAY-HINT#

The -Ih option disables snmptrap.py’s attempt to parse input value or index as a DISPLAY-HINT-rendered value.

Output options#

The following one-letter options following the -O option modify snmptrap.py tool’s output.

Equal sign and type information#

The -Oq option removes the equal sign (=) and SNMP value type information from the variable-binding being reported on stdout.

$ snmpget -v2c -c public -Oq demo.pysnmp.com sysDescr.0
SNMPv2-MIB::sysDescr.0 Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686
$
$ snmpget -v2c -c public demo.pysnmp.com sysDescr.0
SNMPv2-MIB::sysDescr.0 = DisplayString: Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686

Type information#

The -OQ option removes the SNMP value type information from the variable-binding being reported on stdout.

$ snmpget -v2c -c public -OQ demo.pysnmp.com sysDescr.0
SNMPv2-MIB::sysDescr.0 = Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686
$
$ snmpget -v2c -c public demo.pysnmp.com sysDescr.0
SNMPv2-MIB::sysDescr.0 = DisplayString: Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686

Managed object path#

The -Of option prints out the full path of the managed object in the MIB tree rather than MIB name and MIB object name (the default).

$ snmpget -v2c -c public -Of demo.pysnmp.com sysDescr.0
iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0 = DisplayString: Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686

Managed object name#

The -Os option prints out just managed object name (excluding MIB name) rather than MIB name and MIB object name (the default).

$ snmpget -v2c -c public -Os demo.pysnmp.com sysDescr.0
sysDescr.0 = DisplayString: Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686

Raw OID#

The -On option prints out the raw object identifier (OID) rather than human friendly MIB object name:

$ snmpget -v2c -c public -On demo.pysnmp.com sysDescr.0
1.3.6.1.2.1.1.1.0 = DisplayString: Linux zeus 4.8.6.5-smp #2 SMP Sun Nov 13 14:58:11 CDT 2016 i686

Numeric enumerations#

The -Oe option disables symbolic labels rendering for the enumeration values:

$ snmpget -v2c -c public -On demo.pysnmp.com IF-MIB::ifAdminStatus.1
1.3.6.1.2.1.2.2.1.7.1 = Integer32: 'up'
$
$ snmpget -v2c -c public -Oe demo.pysnmp.com IF-MIB::ifAdminStatus.1
IF-MIB::ifAdminStatus."1" = Integer32: 1

Break down table index#

The -Ob option disables interpreting SNMP table indices and renders just raw OID instead:

$ snmpget  -v2c -c public -Ob demo.pysnmp.com TCP-MIB::tcpConnState."195.218.254.105"."45632"."10.105.41.179"."3389"
TCP-MIB::tcpConnState.195.218.254.105.45632.10.105.41.179.3389 = Integer32: 'established'
$
$ snmpget  -v2c -c public demo.pysnmp.com TCP-MIB::tcpConnState."195.218.254.105"."45632"."10.105.41.179"."3389"
TCP-MIB::tcpConnState."195.218.254.105"."45632"."10.105.41.179"."3389" = Integer32: 'established'

Escape table index quotes#

The -OE includes extra escaped quotes surrounding SNMP table index parts. This can be useful when UNIX shell is in the processing pipeline.

$ snmpget  -v2c -c public -OE  demo.pysnmp.com TCP-MIB::tcpConnState."195.218.254.105"."45632"."10.105.41.179"."3389"
TCP-MIB::tcpConnState.\"195.218.254.105\".\"45632\".\"10.105.41.179\".\"3389\" = Integer32: 'established'

Brackets around table indices#

The -OX option surrounds SNMP table index parts with square brackets instead of quotes (default):

$ snmpget  -v2c -c public -OX  demo.pysnmp.com TCP-MIB::tcpConnState."195.218.254.105"."45632"."10.105.41.179"."3389"
TCP-MIB::tcpConnState.[195.218.254.105].[45632].[10.105.41.179].[3389] = Integer32: 'established'

Hexified values#

The -OT option ensures that rendered values are always in hex:

$ snmpget -v2c -c public -OT demo.pysnmp.com sysName.0
SNMPv2-MIB::sysName.0 = DisplayString: 6e 65 77 20 73 79 73 74 65 6d 20 6e 61 6d 65
$
$ snmpget -v2c -c public demo.pysnmp.com sysName.0
SNMPv2-MIB::sysName.0 = DisplayString: new system name

Rendering just values#

The -Ov option removes managed object name from the rendered output:

$ snmpget -v2c -c public -Ov demo.pysnmp.com sysName.0
DisplayString: new system name

Units rendering#

The -OU option disables units rendering:

$ snmpget -v2c -c public demo.pysnmp.com TCP-MIB::tcpRtoMin.0
TCP-MIB::tcpRtoMin.0 = Integer32: 200 milliseconds
$
$ snmpget -v2c -c public -OU  demo.pysnmp.com TCP-MIB::tcpRtoMin.0
TCP-MIB::tcpRtoMin.0 = Integer32: 200

Raw timeticks#

The -Ot option disables TimeTicks values interpretation so that raw values get rendered:

$ snmpget -v2c -c public -Ot demo.pysnmp.com SNMPv2-MIB::sysORLastChange.0
SNMPv2-MIB::sysORLastChange.0 = TimeStamp: 143145968
$
$ snmpget -v2c -c public demo.pysnmp.com SNMPv2-MIB::sysORLastChange.0
SNMPv2-MIB::sysORLastChange.0 = TimeStamp: 16 days 13:37:44.82

Network options#

Maximum retries#

The -r option specifies how many times the snmptrap.py tool should retry sending the same request packet till it gives up and reports failure. The value of zero means that just a single (initial) request will be send. The default value is 5.

Response timeout#

The -t option specifies how many seconds the snmptrap.py tool should wait for the initial request and for each retry to produce any response. Once the timeout is reached, the snmptrap.py tool will either send a retry or fail. Default is one second.

Debugging options#

Release information#

The -V flag reports version information for the snmptrap.py tool and its underlying libraries.

Debug mode#

The -d option prints out raw SNMP packets in hex.

The -D option lets you debug one or more specific SNMP sub-systems. The required argument can be one or more (comma-separated) tokens:

  • io - report input/output activity and raw data being exchanged

  • dsp - report high-level SNMP engine operation

  • msgproc - report SNMP message processing subsystem operation

  • secmod - report SNMP security subsystem operation

  • mibbuild - report MIB files loading and processing

  • mibview - report MIB browser initialization and operation (manager role MIB use)

  • mibinstrum - report MIB instrumentation operation (agent role MIB use)

  • acl - report MIB access control subsystem operation

  • proxy - report built-in SNMP proxy operation

  • app - report SNMP standard application operation

  • all - all of the above (verbose!)

You can also negate the token by prepending it with the ! sign.

TRAP/INFORM options#

The following one-letter options following the -C option modify the way how snmptrap.py tool behaves. These options are mostly specific to snmptrap.py’s operation logic.

Use INFORM notification#

The -Ci option forces snmptrap.py to use SNMP INFORM notification flavor instead of SNMP TRAP one. The difference is that INFORM implies receiver acknowledgement, while TRAP is always a one-way communication.

Note

Historically, INFORM was not meant to be used for the same purpose as SNMP TRAP - its original purpose was to let SNMP entities exchanging some management informaiton they gathered on an ad-hoc, peer-to-peer basis.

SNMP peer address#

The first positional parameter specifies SNMP peer address on the network and, optionally, network protocol to use.

The network protocol can be either udp for UDP-over-IPv4 or udp6 for UDP-over-IPv6.

The network address is either IPv4 or IPv6 address or a fully qualified domain name optionally followed by a colon-separated port number. The default for port is 162.

Note

Numeric IPv6 addresses should be surrounded by square brackets to be parsed correctly. The entire token (address in brackets) might need to be quored to avoid shell expansion. Example: ‘udpv6:[::1]:161’

SNMPv1 TRAP parameters#

When SNMPv1 is used for sending TRAP, the following parameters should be given to populate TRAP PDU:

snmptrap.py enterprise-oid agent generic-trap specific-trap uptime [mib-object […]]

Note

SNMP v1 TRAP PDU is very different that SNMP v2c/v3 TRAP PDU. The former has a number of fields designed specifically to hold TRAP data while the latter is unified with the rest of PDU types.

Enterprise OID#

SNMP TRAPs fall into two categories, ref:generic <snmptrap-v1-generic-trap> and ref:enterprise-specific <snmptrap-v1-specific-trap>. When enterprise-specific TRAPs are used, the enterprise object identifier is put into the packet for receiver to triage and understand the agent-specific meaning of the event.

For example, for IANA-assigned enterprise number is 1248, the enterprise OID is 1.3.6.1.4.1.1248.

SNNP agent IP#

The TRAP PDU also carries the IPv4 address of the SNMP agent that produces this notification. Depending on the network configuration, it may or may not be the same as the source IPv4 address of the TRAP packet.

Generic TRAP ID#

There are seven generic TRAP numbers (0-6) for various typical conditions that may occur to pretty much any SNMP-managed system.

  • coldStart

  • warmStart

  • linkDown

  • linkUp

  • authenticationFailure

  • egpNeighborLoss

  • enterpriseSpecific

The last, enterpriseSpecific is used when specific TRAP is in effect.

Specific TRAP ID#

Enterprise-specific TRAP is the way to extend the built-in generic events in a vendor-specific manner. An enterprise-specific TRAP is identified by two things: the Enterprise OID of the company that defined the TRAP and a company-specific TRAP number (just an integer).

SNMP agent uptime#

SNMP TRAP requires an uptime value. Uptime is how long the system has been running since boot. With snmptrap.py, this value is set to either SNMP engine uptime which is likely zero.

When sending SNMP TRAP with snmptrap.py you can choose whatever uptime value best models the situation you are trying to produce.

The value is measured in hundreds of a second.

SNMPv2/SNMPv3 parameters#

When SNMPv2c or SNMPv3 is used for sending TRAP, the following parameters should be given to populate TRAP2 PDU:

snmptrap.py uptime trap-oid [mib-object […]]

Note

SNMP v2c/v3 TRAP PDU is very different that SNMP v1 TRAP PDU. The latter has a number of fields designed specifically to hold TRAP data, while the latter is unified with the rest of PDU types.

The way how that unification is implemented is that all the TRAP-specific items are put into the variable-bindings. You still need to supply the mandatory items at the snmptrap.py’s command line, the missing parameters get reasonable defaults.

SNMP agent uptime#

SNMPv2c/v3 TRAP PDU carries the uptime value in the first variable-binding (e.g. SNMPv2-MIB::sysUpTime.0). With snmptrap.py, this value is set to either SNMP engine uptime which is likely zero.

When sending SNMP TRAP with snmptrap.py you can choose whatever uptime value best models the situation you are trying to produce.

The value is measured in hundreds of a second.

TRAP OID#

TRAP object identifier is always present in TRAP v2c PDU at the second place of the variable-bindings (e.g. SNMPv2-MIB::snmpTrapOID.0). The value part is either one of the Generic TRAPs:

  • SNMPv2-MIB::coldStart

  • SNMPv2-MIB::warmStart

  • IF-MIB::linkDown

  • IF-MIB::linkUp

  • SNMPv2-MIB::authenticationFailure*

In case of a Specific TRAP, the Enterprise OID should be passed as a value.

The snmptrap.py requires the Enterprise TRAP value to be specified at the command line.

SNNP agent IP#

The TRAP v2c/v3 PDU can optionally carry the IPv4 address of the SNMP agent that produces this notification. Depending on the network configuration, it may or may not be the same as the source IPv4 address of the TRAP packet.

To pass SNMP agent IP to snmptrap.py, you need to give it a variable-binding with the OID of SNMP-COMMUNITY-MIB::snmpTrapAddress.0 and value of your choice.

MIB objects specification#

The rest of positional parameters specify SNMP managed objects to modify and their new values. The syntax for setting a new value to a MIB object is either of:

  • mib-object = value

  • mib-object <snmp-type> value

The = modifier can only be used if mib-object refers to a MIB which would be looked up and the type of the value to set would be figured out.

Alternatively, snmp-type modifier can be passed to directly specify SNMP type of the value being set without using the MIB.

The following snmp-type’s are recognized:

ID

SNMP type

i

INTEGER

u

Unsigned32

s

OctetString

n

NULL

o

ObjectIdentifier

t

TimeTicks

a

IP address

The mib-object can be specified in either of these ways:

  • [MIB-name::]object-name[.index[.index]…]

  • object-identifier

When MIB name or object-name is referenced, the snmptrap.py tool will try to locate and load the corresponding MIB module. The OID specification does not require MIB access, however if you are not using a MIB, be prepared to specify SNMP value type by hand.

SNMP TRAP examples#

SNMPv1 TRAP example#

The following command will send SNMP v1 TRAP message:

  • with community name ‘public’

  • with Generic Trap #1 (warmStart) and Specific Trap 0

  • with default Uptime

  • with default Agent Address

  • with Enterprise OID 1.3.6.1.4.1.20408.4.1.1.2

  • include managed object information ‘1.3.6.1.2.1.1.1.0’ = ‘my system’

snmptrap -v1 -c public demo.pysnmp.com 1.3.6.1.4.1.20408.4.1.1.2 \
    0.0.0.0 1 0 0 1.3.6.1.2.1.1.1.0 s "my system"

SNMPv2c TRAP example#

The following command will send SNMP v2c TRAP message:

  • with community name ‘public’

  • with Agent uptime value 123

  • with TRAP ID ‘coldStart’

  • include managed object information specified as var-bind objects pair

snmptrap -v2c -c public demo.pysnmp.com 123 1.3.6.1.6.3.1.1.5.1 \
 SNMPv2-MIB::sysName.0 = "my system"

SNMPv3 TRAP example#

The following command will send SNMP v3 TRAP message:

  • with authoritative snmpEngineId = 0x8000000001020304 (USM at the receiving manager part must be configured accordingly)

  • with user ‘usr-sha-aes128’, auth: SHA, priv: AES128

  • with TRAP ID ‘authenticationFailure’

  • include managed object information specified as var-bind objects pair

snmptrap -v3 -e 8000000001020304 -l authPriv -u usr-sha-aes \
-A authkey1 -X privkey1 -a SHA -x AES demo.pysnmp.com 12345 \
    1.3.6.1.4.1.20408.4.1.1.2 SNMPv2-MIB::sysName.0 = "my system"

Note

SNMPv3 TRAPs requires pre-sharing the Notification Originator’s value of SnmpEngineId with Notification Receiver. To facilitate that we will use static (e.g. not autogenerated) version of snmpEngineId.