1TrapReceiver(3) User Contributed Perl Documentation TrapReceiver(3)
2
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 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 daemon.
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 four values: a NetSNMP::OID object, a string representation of the
35 value that came associated with it, the value's numeric type (see
36 NetSNMP::ASN for further details on SNMP typing information), and the
37 raw value of the trap, encoded according to its type, 64-bit integer
38 types are returned as strings, integer types as integers, strings as
39 strings, object identifiers as NetSNMP::OID objects, and any other
40 types as undefs.
41 Registered functions should return one of the following values:
43 NETSNMPTRAPD_HANDLER_OK
45 Handling the trap succeeded, but lets the snmptrapd daemon check for
46 further appropriate handlers.
47 NETSNMPTRAPD_HANDLER_FAIL
49 Handling the trap failed, but lets the snmptrapd daemon check for
50 further appropriate handlers.
51 NETSNMPTRAPD_HANDLER_BREAK
53 Stops evaluating the list of handlers for this specific trap, but
54 lets the snmptrapd daemon apply global handlers.
55 NETSNMPTRAPD_HANDLER_FINISH
57 Stops searching for further appropriate handlers.
58 If a handler function does not return anything appropriate or even
60 nothing at all, a return value of NETSNMPTRAPD_HANDLER_OK is assumed.
61 Subroutines are registered using the NetSNMP::TrapReceiver::register
63 function, which takes two arguments. The first is a string describing
64 the notification you want to register for (such as "linkUp" or
65 "MyMIB::MyTrap" or ".1.3.6.1.4.1.2021...."). Two special keywords can
66 be used in place of an OID: "default" and "all". The "default" keyword
67 indicates you want your handler to be called in the case where no other
68 handlers are called. The "all" keyword indicates that the handler
69 should ALWAYS be called for every notification.
70
72 As an example, put the following code into a file (say
73 "/usr/local/share/snmp/mytrapd.pl"):
74 #!/usr/bin/perl
76 sub my_receiver {
78 print "********** PERL RECEIVED A NOTIFICATION:\n";
79 # print the PDU info (a hash reference)
81 print "PDU INFO:\n";
82 foreach my $k(keys(%{$_[0]})) {
83 if ($k eq "securityEngineID" || $k eq "contextEngineID") {
84 printf " %-30s 0x%s\n", $k, unpack('h*', $_[0]{$k});
85 }
86 else {
87 printf " %-30s %s\n", $k, $_[0]{$k};
88 }
89 }
90 # print the variable bindings:
92 print "VARBINDS:\n";
93 foreach my $x (@{$_[1]}) {
94 printf " %-30s type=%-2d value=%s\n", $x->[0], $x->[2], $x->[1];
95 }
96 }
97 NetSNMP::TrapReceiver::register("all", \&my_receiver) ||
99 warn "failed to register our perl trap handler\n";
100 print STDERR "Loaded the example perl snmptrapd handler\n";
102 Then, put the following line in your snmprapd.conf file:
104 perl do "/usr/local/share/snmp/mytrapd.pl";
106 Start snmptrapd (as root, and the following other opions make it stay
108 in the foreground and log to stderr):
109 snmptrapd -f -Le
111 You should see it start up and display the final message from the end
113 of the above perl script:
114 Loaded the perl snmptrapd handler
116 2004-02-11 10:08:45 NET-SNMP version 5.2 Started.
117 Then, if you send yourself a fake trap using the following example
119 command:
120 snmptrap -v 2c -c mycommunity localhost 0 linkUp ifIndex.1 i 1 \
122 ifAdminStatus.1 i up ifOperStatus.1 i up ifDescr s eth0
123 You should see the following output appear from snmptrapd as your perl
125 code gets executed:
126 ********** PERL RECEIVED A NOTIFICATION:
128 PDU INFO:
129 notificationtype TRAP
130 receivedfrom 127.0.0.1
131 version 1
132 errorstatus 0
133 messageid 0
134 community mycommunity
135 transactionid 2
136 errorindex 0
137 requestid 765160220
138 VARBINDS:
139 sysUpTimeInstance type=67 value=0:0:00:00.00
140 snmpTrapOID.0 type=6 value=linkUp
141 ifIndex.1 type=2 value=1
142 ifAdminStatus.1 type=2 value=1
143 ifOperStatus.1 type=2 value=1
144 ifDescr type=4 value="eth0"
145 Passing Arguments
147 If you need to pass arguments in to the script, you'll need to do it by
148 one of two methods:
149 Using Subroutines
151 You can either define a subroutine in the file rather than have the
153 file itself do something. IE, in the file if you put:
154 sub foo {
156 print "$_[0]\n";
157 }
158 and then put these lines in the snmptrapd.conf file:
160 perl do /path/to/script
162 perl foo("hello world");
163 perl foo("now I am passing something different");
164 It'd call the foo function twice, and print the results to the console
166 where snmptrapd was started.
167 Using Variables
169 Or you could always set a variable ahead of time:
171 perl $myVariable = 42;
173 perl do /path/to/script
174 And have the script look for and use the $myVariable value in the
176 script
177
179 None by default.
180 Exportable constants
182 NETSNMPTRAPD_AUTH_HANDLER
183 NETSNMPTRAPD_HANDLER_BREAK
184 NETSNMPTRAPD_HANDLER_FAIL
185 NETSNMPTRAPD_HANDLER_FINISH
186 NETSNMPTRAPD_HANDLER_OK
187 NETSNMPTRAPD_POST_HANDLER
188 NETSNMPTRAPD_PRE_HANDLER
189
191 NetSNMP::OID, NetSNMP::ASN
192 snmptrapd.conf(5) for configuring the Net-SNMP trap receiver.
194 snmpd.conf(5) for configuring the Net-SNMP snmp agent for sending
196 traps.
197 http://www.Net-SNMP.org/
199
201 W. Hardaker, <hardaker@users.sourceforge.net>
202
204 Copyright 2004 by W. Hardaker
205 This library is free software; you can redistribute it and/or modify it
207 under the same terms as Perl itself.
208perl v5.38.0 2023-08-16 TrapReceiver(3)