View source for TUT:snmptrap

Most SNMP traffic is sent from a management station to a network entity,
in order to find out about that system or adjust its configuration in
some way.  Notifications (Traps and Informs) can be used by a network
entity to signal abnormal conditions to a management station.

Typically, such a notification would normally be generated by an SNMP
agent, but this tutorial will concentrate on the <code>snmptrap</code>
command, which can also be used to generate such traps.

== Trap Definitions ==

There are two ways of defining a notification - one used in SMIv1 MIBs
and one used in SMIv2 MIBs.  The two styles are basically equivalent,
and it is possible to convert between the two.  In particular, it is
perfectly valid to send an SMIv2-defined notification as an SNMPv1 trap,
or an SMIv1-defined trap as an SNMPv2c (or SNMPv3) notification.

=== SMIv1 Traps ===

A trap is defined in an SMIv1 MIB file using the TRAP-TYPE macro,
as in the following example:

  UCD-TRAP-TEST-MIB DEFINITIONS ::= BEGIN
        IMPORTS ucdExperimental FROM UCD-SNMP-MIB;
  
  demotraps OBJECT IDENTIFIER ::= { ucdExperimental 990 }
  
  '''demoTrap''' TRAP-TYPE
        '''ENTERPRISE demotraps'''
        VARIABLES { sysLocation }
        DESCRIPTION "An example of an SMIv1 trap"
        '''::= 17'''
  
  END

Note that the trap is identified by two values - the ENTERPRISE oid
and the value of the TRAP-TYPE macro.

=== SMIv2 Notifications ===

A notification is defined in an SMIv2 MIB file using the NOTIFICATION-TYPE macro,
as in the following example:

  UCD-NOTIFICATION-TEST-MIB DEFINITIONS ::= BEGIN
        IMPORTS ucdExperimental FROM UCD-SNMP-MIB;
  
  ucdNotificationTestMib MODULE-IDENTITY
    ''-- omitted''
  
  demotraps  OBJECT IDENTIFIER ::= { ucdExperimental 990 }
  demonotifs OBJECT IDENTIFIER ::= { demotraps 0 }
  
  '''demoNotif''' NOTIFICATION-TYPE
        OBJECTS { sysLocation }
        STATUS current
        DESCRIPTION "An example of an SMIv2 notification"
        '''::= { demonotifs 18 }'''
  
  ucdNotificationGroup NOTIFICATION-GROUP
    ''-- omitted''
  END

Note that this defines a single OID which will uniquely identify
the notification.

=== Variables ===

Both SMIv1 and SMIv2 definitions can specify additional information
that should be included within the trap.
The name of the clause is different between the two definitions
(VARIABLES vs OBJECTS), but the meaning is the same - the
notification should include a varbind (OID and value) for each
object listed, in the order that they appear.

''<tasks>[ ] Object vs Instance</tasks>''


=== Traps vs Notifications ===

Strictly speaking, we should probably refer to all such MIB definitions
as "notifications" - with the term "trap" being reserved for the
(unacknowledged) SNMP request used to transport the relevant information.
But people do tend to use the two terms interchangeably (as has been
the case in this tutorial as well!)

''<tasks>[ ] describe {enterprises}.0.{value} &lt;-&gt; {oid} conversion</tasks>''

== SNMP Traps ==

OK - so that describes how notifications are defined in a MIB file.
How are they represented as SNMP requests?

=== SNMPv1 Traps ===

Unsurprisingly, the format of a trap request follows the format of the
corresponding SMI definition fairly closely.  So an SNMPv1 trap should
contain two values - the enterprise OID and the value of the trap itself, right?

Wrong!  It actually contains ''three'' elements - an enterprise OID and
''two'' trap values - a "generic-trap" field and a "specific-trap" field.
For traps defined in a MIB file, the generic-trap field will always have
the value 6, and the specific-trap field will have the value of the
TRAP-TYPE macro.

In fact, the SNMPv1 trap request actually contains five values - these
three plus the IP address of the system generating the trap, and the
<code>sysUpTime</code> of the generating application.

The <code>snmptrap</code> command will use sensible defaults for
these last two fields, so it's really just necessary to provide the
enterprise OID and the two trap values:

   $ snmptrap -v 1 -c public host '''UCD-TRAP-TEST-MIB::demotraps''' "" '''6 17''' "" \
        SNMPv2-MIB::sysLocation.0 s "Just here"

Note that this command also includes an (OID,type,value) triple for the
varbinds listed in the VARIABLES clause (in the same way as with the
[[TUT:snmpset|snmpset]] command).

=== SNMPv2 Traps ===

SNMPv2 simplified the format of a notification request, consolidating
everything within the varbind list, rather than having separate header
fields just for Trap requests.  So the first two varbinds of an SNMPv2
notification will be <code>sysUpTime.0</code> following by <code>snmpTrapOID.0</code>.
The value of this second varbind is the OID identifying the trap being sent.

The <code>snmptrap</code> command will insert a sensible value for
the sysUpTime varbind, so it's really just necessary to provide the
trap OID (plus any additional varbinds from the OBJECTS clause):

   $ snmptrap -v '''2c''' -c public host "" '''UCD-NOTIFICATION-TEST-MIB::demoNotif''' \
        SNMPv2-MIB::sysLocation.0 s "Just here"

=== SNMPv2 Informs ===

''<tasks>[ ] Similar to Traps, but acknowledged - i.e. resend if no response</tasks>''

=== SNMPv3 Notifications ===

''<tasks>[ ] Same as SNMPv2, but v3 admin</tasks>''

== Agent Traps ==

The agent is able to generate a few traps by itself. When starting up, it will generate a SNMPv2-MIB::coldStart trap, and when shutting down a UCD-SNMP-MIB::ucdShutDown. 

These traps are sent to managers specified in the snmpd.conf file, using the trapsink or trap2sink directive (SNMPv1 and SNMPv2 trap respectively) 

  # send v1 traps
  trapsink        nms.system.com  public
  # also send v2 traps
  trap2sink       nms.system.com  secret
  # send traps on authentication failures
  authtrapenable  1

In addition, the agent is able to send authentication failure traps
to the same hosts as above, controlled by the authtrapenable directive
in snmpd.conf, or by setting the SNMPv2-MIB::snmpEnableAuthenTraps
variable

  $ '''snmpset -c public agent SNMPv2-MIB::snmpEnableAuthenTraps s enable'''


To perform various tasks when notifications arrive at the Net-SNMP [[snmptrapd]] notification receiver, please see the page on [[TUT:Configuring snmptrapd]]

<hr>

{{TUT:LIST}}