1TrapReceiver(3) User Contributed Perl Documentation TrapReceiver(3)
2
3
4
6 NetSNMP::TrapReceiver - Embedded perl trap handling for Net-SNMP's
7 snmptrapd
8
10 Put the following lines in your snmptrapd.conf file:
11
12 perl NetSNMP::TrapReceiver::register("trapOID", \&myfunc);
13
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
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
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
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
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
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)