Difference between revisions of "TUT:snmptrap"

Revision as of 15:49, 31 October 2007

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 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} <-> {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

Unserprisingly, 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 sysUpTime of the generating application.

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

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

Processing traps

Generating traps is only half of the battle. We also need something to receive the notification, and respond accordingly. The Net-SNMP suite includes an application snmptrapd which can accept and process such notifications.

By default, it will simply log all incoming notifications via syslog. The two snmptrap commands above would be logged as:

 1999-11-12 23:26:07 localhost [127.0.0.1] UCD-TRAP-TEST-MIB::demotraps:
       Enterprise Specific Trap (demoTrap) Uptime: 1 day, 5:34:06
       SNMPv2-MIB::sysLocation.0 = "Just here"

and

 1999-11-13 08:31:33 localhost [127.0.0.1]:
       SNMPv2-MIB::sysUpTime.0 = Timeticks: (13917129) 1 day, 14:39:31.29
       SNMPv2-MIB::snmpTrapOID.0 = OID: UCD-NOTIFICATION-TEST-MIB::demoNotif
       SNMPv2-MIB::sysLocation.0 = "just here"

respectively.

Trap Handlers

The snmptrapd utility also has the ability to execute other programs on the reception of a trap. This is controlled by the traphandle directive, with the syntax

 traphandle OID command

Notice, that this only takes an OID to determine which trap (or notification) is received. This means that SNMPv1 traps need to be represented in SNMPv2 format, which is described in RFC 2089. Basically, the OID for our above defined trap is created by taking the ENTERPRISE parameter and adding the sub-ids 0 and 17. Similarly, OID values for the generic SNMPv1 traps are defined to be the same as for SNMPv2.

The command specifies a command to be executed by snmptrapd upon reception by the command. This command is executed with the data of the trap as its standard input. The first line is the host name, the second the IP address of the trap sender, and the following lines consists of an OID VALUE pair with the data from the received trap.

A simple shell script to be called from snmptrapd is the following:

 #!/bin/sh
 
 read host
 read ip
 vars=
 
 while read oid val
 do
   if [ "$vars" = "" ]
   then
     vars="$oid = $val"
   else
     vars="$vars, $oid = $val"
   fi
 done
 
 echo trap: $1 $host $ip $vars

Now, given the following sample snmptrapd.conf file,

 # the generic traps
 traphandle SNMPv2-MIB::coldStart    /home/nba/bin/traps cold
 traphandle SNMPv2-MIB::warmStart    /home/nba/bin/traps warm
 traphandle IF-MIB::linkDown         /home/nba/bin/traps down
 traphandle IF-MIB::linkUp           /home/nba/bin/traps up
 traphandle SNMPv2-MIB::authenticationFailure /home/nba/bin/traps auth
 # this one is deprecated
 traphandle .1.3.6.1.6.3.1.1.5.6     /home/nba/bin/traps egp-neighbor-loss
 
 # enterprise specific traps
 traphandle UCD-TRAP-TEST-MIB::demoTrap /home/nba/bin/traps demo-trap
 traphandle UCD-NOTIFICATION-TEST-MIB::demoNotif /home/nba/bin/traps demo-notif

The following snmptrap invocation, to issue a generic Link down trap,

 % snmptrap -v 1 -c public localhost TRAP-TEST-MIB::demotraps localhost 2 0 "" \
       IF-MIB::ifIndex i 1

results in the following output from snmptrapd:

 1999-11-13 12:46:49 localhost [127.0.0.1]  TRAP-TEST-MIB::traps:
       Link Down Trap (0) Uptime: 1 day, 18:54:46.27
       IF-MIB::ifIndex.0 = 1

and the following output from the handler:

 trap: down localhost 127.0.0.1 SNMPv2-MIB::sysUpTime = 1:18:54:46.27, SNMPv2-MIB::snmpTrapOID = IF-MIB::linkDown, IF-MIB::ifIndex.0 = 1, SNMPv2-MIB::snmpTrapEnterprise = TRAP-TEST-MIB::traps

and issuing our enterprise specific trap gives this output from our handler:

 trap: demoTrap localhost 127.0.0.1 SNMPv2-MIB::sysUpTime = 1:19:00:48.01, SNMPv2-MIB::snmpTrapOID = UCD-TRAP-TEST-MIB::demoTrap, SNMPv2-MIB::sysLocation.0 = "just here", SNMPv2-MIB::snmpTrapEnterprise = UCD-TRAP-TEST-MIB::traps

and finally our enterprise specific notification:

 trap: demoNotif localhost 127.0.0.1 SNMPv2-MIB::sysUpTime.0 = 1:19:02:06.33, SNMPv2-MIB::snmpTrapOID.0 = UCD-NOTIFICATION-TEST-MIB::demoNotif, SNMPv2-MIB::sysLocation.0 = "just here"

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.

How SNMP Works: About the protocol itself (GETs, GETNEXTs, etc)
What data is in SNMP: All about SNMP Management Information Bases (MIBs)
Securing SNMP: How to use the SNMP protocol securely

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!

snmptranslate: learning about the MIB tree.
snmpget: retrieving data from a host.
snmpgetnext: retrieving unknown indexed data.
snmpwalk: retrieving lots of data at once!
snmptable: displaying a table.
snmpset: peforming write operations.
snmpbulkget: communicates with a network entity using SNMP GETBULK request
snmpbulkwalk: retrieve a sub-tree of management values using SNMP GETBULK requests.
snmptrap: Sending and receiving traps, and acting upon them.
- Traps/informs with SNMPv3/USM: Sending and receiving SNMPv3/USM TRAPs and INFORMs
- Sending Traps/Informs via AgentX: Sending notifications from the command line through snmpd
Common command line options:
Writing mib2c config files

Application Configuration

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

Configuration files for Net-SNMP applications

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.

SNMP Agent (snmpd) Configuration
SNMP Notification Receiver (snmptrapd)
Agent Monitoring
- DisMan Monitoring
- Monitoring with MRTG

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.

Client / Manager Coding Tutorials
- Writing a simple application
- Writing a simple asynchronous application
Agent Coding Tutorials
- The Agent Architecture page might be worth reading before or after the agent coding tutorials, and describes how the Agent Helpers work under the hood.
- Writing a mib module to serve information described by an SNMP MIB, and how to compile it into the net-snmp snmpd agent.
- Writing a Dynamically Loadable Object that can be loaded into the SNMP agent.
- Writing a Subagent that can be run to attach to the snmpd master agent.
- Writing a perl plugin to extend the agent using the NetSNMP::agent module.
- Writing shell scripts to extend the agent
- Using mib2c to help write an agent code template for you
Header files and autoconf

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

Building With Visual Studio 2005 Express
- Using the command line and nmake
Building Net-SNMP 64-bit with Visual C++ 2010 Express
- Using the command line and nmake (VC++ 2010 Express)
Net-Snmp on Ubuntu
Net-SNMP and lm-sensors on Ubuntu 10.04
Net-SNMP for windows:
- How to install: [1]
- How to configure: [2]

@@ Line 73: / Line 73: @@
 object listed, in the order that they appear.
-''<tasks>[2] Object vs Instance</tasks>''
+''<tasks>[ ] Object vs Instance</tasks>''
@@ Line 84: / Line 84: @@
 the case in this tutorial as well!)
-''<tasks>[2] describe {enterprises}.0.{value} &lt;-&gt; {oid} conversion</tasks>''
+''<tasks>[ ] describe {enterprises}.0.{value} &lt;-&gt; {oid} conversion</tasks>''
 == SNMP Traps ==
@@ Line 135: / Line 135: @@
 === SNMPv2 Informs ===
-''<tasks>[2] Similar to Traps, but acknowledged - i.e. resend if no response</tasks>''
+''<tasks>[ ] Similar to Traps, but acknowledged - i.e. resend if no response</tasks>''
 === SNMPv3 Notifications ===
-''<tasks>[2] Same as SNMPv2, but v3 admin</tasks>''
+''<tasks>[ ] Same as SNMPv2, but v3 admin</tasks>''
 == Agent Traps ==
@@ Line 252: / Line 252: @@
    trap: demoNotif localhost 127.0.0.1 SNMPv2-MIB::sysUpTime.0 = 1:19:02:06.33, SNMPv2-MIB::snmpTrapOID.0 = UCD-NOTIFICATION-TEST-MIB::demoNotif, SNMPv2-MIB::sysLocation.0 = "just here"
+<hr>
 {{TUT:LIST}}