TUT:snmptrap

From Net-SNMP Wiki
Revision as of 23:37, 30 June 2011 by Wes (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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 snmptrap 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 (.1.3.6.1.4.1.2021.13.990 which is TRAP-TEST-MIB::demotraps) and the specific-trap value of the TRAP-TYPE macro (17)

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} <-> {oid} conversion</tasks> -- see TUT:Configuring snmptrapd#Trap_Handlers

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 custom MIB file (specific traps), the "generic-trap" field will always have the value 6, and the "specific-trap" field will have the value of the TRAP-TYPE macro. So the combined OID, identifying the trap will be 

 enterprise-oid.0.specific-trap

For predefined (generic traps), "generic-trap" field will have a number identifying the trap, "specific-trap" value is irrelevant. Combined OID will be 

 1.3.6.1.6.3.1.1.5.generic-trap+1

In fact, the SNMPv1 trap request actually contains five values - these three plus the "agent" field (IP address of the system generating the trap, useful if you have more than one network interface), and the sysUpTime of the generating application.

The snmptrap command will use sensible defaults for these two fields, so it's really just necessary to provide the enterprise-OID and the two trap values, plus the payload of the trap itself [OID, type, value]: 

 syntax:
 snmptrap -v 1 [COMMON OPTIONS] [-Ci] destination enterprise-oid agent generic-trap specific-trap uptime [OID TYPE VALUE]

  $ 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 snmpset command).

In case you don't have UCD-TRAP-TEST-MIB module defined (default installation on Redhat and Suse), you may try NET-SNMP-EXAMPLES-MIB module instead: 

  $ snmptrap -v 1 -c public host NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification "" 6 17 "" \
       netSnmpExampleHeartbeatRate i 123456

  $ snmptrap -v 1 -c public host NET-SNMP-EXAMPLES-MIB::netSnmpExampleNotification "" 6 17 "" \
       netSnmpExampleInteger i 123456

More examples: 

 $snmptrap -v 1 -c public host '1.2.3.4.5.6' '192.193.194.195' 6 99 '55' 1.11.12.13.14.15  s "teststring"

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 sysUpTime.0 following by snmpTrapOID.0. The value of this second varbind is the OID identifying the trap being sent.

The snmptrap 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"

In case you don't have UCD-TRAP-TEST-MIB module defined (default installation on Redhat and Suse), you may try NET-SNMP-EXAMPLES-MIB module instead: 

  $ snmptrap -v 2c -c public host "" NET-SNMP-EXAMPLES-MIB::netSnmpExampleHeartbeatNotification \
       netSnmpExampleHeartbeatRate i 123456

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

Tutorial Sections

About the SNMP Protocol

These tutorial links talk about SNMP generically and how the protocol itself works. They are good introductory reading material and the concepts are important to understand before diving into the later tutorials about Net-SNMP itself.

Net-SNMP Command Line Applications

These tutorial pages discuss the command line tools provided in the Net-SNMP suite of tools. Nearly all the example commands in these tutorials works if you try it yourself, as they're all examples that talk to our online Net-SNMP test agent. Given them a shot!

Application Configuration

All of our applications support configuration to allow you to customize how they behave.

Net-SNMP Daemons

Net-SNMP comes with two long-running daemons: a SNMP agent (snmpd) for responding to management requests and a notification receiver (snmptrapd) for receiving SNMP notifications.

Coding Tutorials

Net-SNMP comes with a highly flexible and extensible API. The API allows you to create your own commands, add extensions to the agent to support your own MIBs and perform specialized processing of notifications.

Debugging SNMP Applications and Agents

All our tools and applications have extensive debugging output. These tutorials talk about how the debugging system works and how you can add your own debugging statements to you code:

Operating System Specific Tutorials

Retrieved from "https://net-snmp.sourceforge.io/wiki/index.php?title=TUT:snmptrap&oldid=5114"