Net-SNMP Tutorial -- 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 utitlity.

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 comes in two destinctly 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 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.conffile, 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 SNMPv2-MIB::snmpEnableAuthenTraps variable

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

Note: the current 4.0 version of Net-SNMP does not generate authentication failure traps. This will hopefully be corrected before the next release. [an error occurred while processing this directive]