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       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
42       Registered functions should return one of the following values:
43
44       NETSNMPTRAPD_HANDLER_OK
45         Handling the trap succeeded, but lets the snmptrapd demon check for
46         further appropriate handlers.
47
48       NETSNMPTRAPD_HANDLER_FAIL
49         Handling the trap failed, but lets the snmptrapd demon check for
50         further appropriate handlers.
51
52       NETSNMPTRAPD_HANDLER_BREAK
53         Stops evaluating the list of handlers for this specific trap, but
54         lets the snmptrapd demon apply global handlers.
55
56       NETSNMPTRAPD_HANDLER_FINISH
57         Stops searching for further appropriate handlers.
58
59       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
62       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

EXAMPLE

72       As an example, put the following code into a file (say
73       "/usr/local/share/snmp/mytrapd.pl"):
74
75         #!/usr/bin/perl
76
77         sub my_receiver {
78             print "********** PERL RECEIVED A NOTIFICATION:\n";
79
80             # 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
91             # 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
98         NetSNMP::TrapReceiver::register("all", \&my_receiver) ||
99           warn "failed to register our perl trap handler\n";
100
101         print STDERR "Loaded the example perl snmptrapd handler\n";
102
103       Then, put the following line in your snmprapd.conf file:
104
105         perl do "/usr/local/share/snmp/mytrapd.pl";
106
107       Start snmptrapd (as root, and the following other opions make it stay
108       in the foreground and log to stderr):
109
110         snmptrapd -f -Le
111
112       You should see it start up and display the final message from the end
113       of the above perl script:
114
115         Loaded the perl snmptrapd handler
116         2004-02-11 10:08:45 NET-SNMP version 5.2 Started.
117
118       Then, if you send yourself a fake trap using the following example
119       command:
120
121         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
124       You should see the following output appear from snmptrapd as your perl
125       code gets executed:
126
127         ********** 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
146   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
150       Using Subroutines
151
152       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
155         sub foo {
156            print "$_[0]\n";
157         }
158
159       and then put these lines in the snmptrapd.conf file:
160
161         perl do /path/to/script
162         perl foo("hello world");
163         perl foo("now I am passing something different");
164
165       It'd call the foo function twice, and print the results to the console
166       where snmptrapd was started.
167
168       Using Variables
169
170       Or you could always set a variable ahead of time:
171
172         perl $myVariable = 42;
173         perl do /path/to/script
174
175       And have the script look for and use the $myVariable value in the
176       script
177

EXPORT

179       None by default.
180
181   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

SEE ALSO

191       NetSNMP::OID, NetSNMP::ASN
192
193       snmptrapd.conf(5) for configuring the Net-SNMP trap receiver.
194
195       snmpd.conf(5) for configuring the Net-SNMP snmp agent for sending
196       traps.
197
198       http://www.Net-SNMP.org/
199

AUTHOR

201       W. Hardaker, <hardaker@users.sourceforge.net>
202
204       Copyright 2004 by W. Hardaker
205
206       This library is free software; you can redistribute it and/or modify it
207       under the same terms as Perl itself.
208
209
210
211perl v5.34.0                      2021-07-29                   TrapReceiver(3)
Impressum