1TrapReceiver(3)       User Contributed Perl Documentation      TrapReceiver(3)
2
3
4

NAME

6       NetSNMP::TrapReceiver - Embedded perl trap handling for Net-SNMP's
7       snmptrapd
8

SYNOPSIS

10       Put the following lines in your snmptrapd.conf file:
11
12         perl NetSNMP::TrapReceiver::register("trapOID", \&myfunc);
13

ABSTRACT

15       The NetSNMP::TrapReceiver module is used to register perl subroutines
16       into the Net-SNMP snmptrapd process.  Net-SNMP MUST have been
17       configured using --enable-embedded-perl.  Registration of functions is
18       then done through the snmptrapd.conf configuration file.  This module
19       can NOT be used in a normal perl script to receive traps.  It is
20       intended solely for embedded use within the snmptrapd demon.
21

DESCRIPTION

23       Within the snmptrapd.conf file, the keyword "perl" may be used to call
24       any perl expression and using this ability, you can use the
25       NetSNMP::TrapReceiver module to register functions which will be called
26       every time a given notification (a trap or an inform) is received.
27       Registered functions are called with 2 arguments.  The first is a
28       reference to a hash containing information about how the trap was
29       received (what version of the SNMP protocol was used, where it came
30       from, what SNMP user name or community name it was sent under, etc).
31       The second argument is a reference to an array containing the variable
32       bindings (OID and value information) that define the noification
33       itself.  Each variable is itself a reference to an array containing
34       three values: a NetSNMP::OID object, the value that came associated
35       with it, and the value's numeric type (see NetSNMP::ASN for further
36       details on SNMP typing information).
37
38       Registered functions should return one of the following values:
39
40       NETSNMPTRAPD_HANDLER_OK
41         Handling the trap succeeded, but lets the snmptrapd demon check for
42         further appropriate handlers.
43
44       NETSNMPTRAPD_HANDLER_FAIL
45         Handling the trap failed, but lets the snmptrapd demon check for
46         further appropriate handlers.
47
48       NETSNMPTRAPD_HANDLER_BREAK
49         Stops evaluating the list of handlers for this specific trap, but
50         lets the snmptrapd demon apply global handlers.
51
52       NETSNMPTRAPD_HANDLER_FINISH
53         Stops searching for further appropriate handlers.
54
55       If a handler function does not return anything appropriate or even
56       nothing at all, a return value of NETSNMPTRAPD_HANDLER_OK is assumed.
57
58       Subroutines are registered using the NetSNMP::TrapReceiver::register
59       function, which takes two arguments.  The first is a string describing
60       the notification you want to register for (such as "linkUp" or
61       "MyMIB::MyTrap" or ".1.3.6.1.4.1.2021....").  Two special keywords can
62       be used in place of an OID: "default" and "all".  The "default" keyword
63       indicates you want your handler to be called in the case where no other
64       handlers are called.  The "all" keyword indicates that the handler
65       should ALWAYS be called for every notification.
66

EXAMPLE

68       As an example, put the following code into a file (say
69       "/usr/local/share/snmp/mytrapd.pl"):
70
71         #!/usr/bin/perl
72
73         sub my_receiver {
74             print "********** PERL RECEIVED A NOTIFICATION:\n";
75
76             # print the PDU info (a hash reference)
77             print "PDU INFO:\n";
78             foreach my $k(keys(%{$_[0]})) {
79               if ($k eq "securityEngineID" || $k eq "contextEngineID") {
80                 printf "  %-30s 0x%s\n", $k, unpack('h*', $_[0]{$k});
81               }
82               else {
83                 printf "  %-30s %s\n", $k, $_[0]{$k};
84               }
85             }
86
87             # print the variable bindings:
88             print "VARBINDS:\n";
89             foreach my $x (@{$_[1]}) {
90                 printf "  %-30s type=%-2d value=%s\n", $x->[0], $x->[2], $x->[1];
91             }
92         }
93
94         NetSNMP::TrapReceiver::register("all", \&my_receiver) ||
95           warn "failed to register our perl trap handler\n";
96
97         print STDERR "Loaded the example perl snmptrapd handler\n";
98
99       Then, put the following line in your snmprapd.conf file:
100
101         perl do "/usr/local/share/snmp/mytrapd.pl";
102
103       Start snmptrapd (as root, and the following other opions make it stay
104       in the foreground and log to stderr):
105
106         snmptrapd -f -Le
107
108       You should see it start up and display the final message from the end
109       of the above perl script:
110
111         Loaded the perl snmptrapd handler
112         2004-02-11 10:08:45 NET-SNMP version 5.2 Started.
113
114       Then, if you send yourself a fake trap using the following example
115       command:
116
117         snmptrap -v 2c -c mycommunity localhost 0 linkUp ifIndex.1 i 1 \
118             ifAdminStatus.1 i up ifOperStatus.1 i up ifDescr s eth0
119
120       You should see the following output appear from snmptrapd as your perl
121       code gets executed:
122
123         ********** PERL RECEIVED A NOTIFICATION:
124         PDU INFO:
125           notificationtype               TRAP
126           receivedfrom                   127.0.0.1
127           version                        1
128           errorstatus                    0
129           messageid                      0
130           community                      mycommunity
131           transactionid                  2
132           errorindex                     0
133           requestid                      765160220
134         VARBINDS:
135           sysUpTimeInstance              type=67 value=0:0:00:00.00
136           snmpTrapOID.0                  type=6  value=linkUp
137           ifIndex.1                      type=2  value=1
138           ifAdminStatus.1                type=2  value=1
139           ifOperStatus.1                 type=2  value=1
140           ifDescr                        type=4  value="eth0"
141

EXPORT

143       None by default.
144
145       # =head2 Exportable constants
146
147       #   NETSNMPTRAPD_AUTH_HANDLER #   NETSNMPTRAPD_HANDLER_BREAK #
148       NETSNMPTRAPD_HANDLER_FAIL #   NETSNMPTRAPD_HANDLER_FINISH #
149       NETSNMPTRAPD_HANDLER_OK #   NETSNMPTRAPD_POST_HANDLER #
150       NETSNMPTRAPD_PRE_HANDLER
151

SEE ALSO

153       NetSNMP::OID, NetSNMP::ASN
154
155       snmptrapd.conf(5) for configuring the Net-SNMP trap receiver.
156
157       snmpd.conf(5) for configuring the Net-SNMP snmp agent for sending
158       traps.
159
160       http://www.Net-SNMP.org/
161

AUTHOR

163       W. Hardaker, <hardaker@users.sourceforge.net>
164
166       Copyright 2004 by W. Hardaker
167
168       This library is free software; you can redistribute it and/or modify it
169       under the same terms as Perl itself.
170
171
172
173perl v5.12.2                      2009-05-19                   TrapReceiver(3)
Impressum