TUT:snmptrap

From Net-SNMP Wiki
Revision as of 14:48, 14 August 2007 by Pczaja (Talk | contribs) (typos)

Jump to: navigation, search

SNMP Traps

Traps can be used by network entities to signal abnormal conditions to management stations. The following paragraphs will describe how traps are defined in MIB files, how they are generated by the snmptrap utlity, and how they are received and processed by the snmptrapd utility.

Note: as I prefer the OID notations using the MODULE::identifier notation, this is used throughout in the following examples, and the snmptrapd output similarly assumes the -OS option.

Definition of traps

Traps come in two distinctly different forms, SNMPv1 traps, and SNMPv2 traps (or notifications)

The SNMPv1 trap

The SNMPv1 trap is defined in the MIB file using the TRAP-TYPE macro, as in the following example 

 TRAP-TEST-MIB DEFINITIONS ::= BEGIN
       IMPORTS ucdExperimental FROM UCD-SNMP-MIB;
 
 demotraps OBJECT IDENTIFIER ::= { ucdExperimental 990 }
 
 demo-trap TRAP-TYPE
       STATUS current
       ENTERPRISE demotraps
       VARIABLES { sysLocation }
       DESCRIPTION "This is just a demo"
       ::= 17
 
 END

This defines a single enterprise specific trap, that can be issued as follows 

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

and when received by snmptrapd is displayed as follows: 

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

The SNMPv2 notification

The format of the SNMPv2 notification is somewhat different. The definition in the MIB file looks as follows 

 NOTIFICATION-TEST-MIB DEFINITIONS ::= BEGIN
       IMPORTS ucdavis FROM UCD-SNMP-MIB;

 demonotifs OBJECT IDENTIFIER ::= { ucdavis 991 }
 
 demo-notif NOTIFICATION-TYPE
         STATUS current
         OBJECTS { sysLocation }
         DESCRIPTION "Just a test notification"
         ::= { demonotifs 17 }
 
 END

This is a definition that is similar to the SNMPv1 trap given above. Issuing this notification looks as follows 

 % snmptrap -v 2c -c public localhost "" NOTIFICATION-TEST-MIB::demo-notif \
         SNMPv2-MIB::sysLocation.0 s "just here"

and the resulting output from the trap daemon is: 

 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: NOTIFICATION-TEST-MIB::demo-notif
       SNMPv2-MIB::sysLocation.0 = "just here"

Defining snmptrapd trap handlers

The snmptrapd utility 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 TRAP-TEST-MIB::demo-trap /home/nba/bin/traps demo-trap
 traphandle NOTIFICATION-TEST-MIB::demo-notif /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: demo-trap localhost 127.0.0.1 SNMPv2-MIB::sysUpTime = 1:19:00:48.01, SNMPv2-MIB::snmpTrapOID = TRAP-TEST-MIB::demo-trap, SNMPv2-MIB::sysLocation.0 = "just here", SNMPv2-MIB::snmpTrapEnterprise = TRAP-TEST-MIB::traps

and finally our enterprise specific notification: 

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

Generating traps from the agent

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

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=2751"