1POE::Component::SNMP(3)User Contributed Perl DocumentatioPnOE::Component::SNMP(3)
2
3
4

NAME

6       POE::Component::SNMP - POE interface to Net::SNMP
7

SYNOPSIS

9         # this script is included in the distribution as eg/snmp_sample.pl
10         use POE qw/Component::SNMP/;
11
12         my %system = ( sysUptime   => '.1.3.6.1.2.1.1.3.0',
13                        sysName     => '.1.3.6.1.2.1.1.5.0',
14                        sysLocation => '.1.3.6.1.2.1.1.6.0',
15                      );
16         my @oids = values %system;
17         my $base_oid = '.1.3.6.1.2.1.1'; # system.*
18
19         POE::Session->create( inline_states =>
20                               { _start       => \&_start,
21                                 snmp_handler => \&snmp_handler,
22                               }
23                             );
24
25         sub _start {
26           my ($kernel, $heap) = @_[KERNEL, HEAP];
27
28           POE::Component::SNMP->create( alias     => 'snmp', # same as default
29                                         hostname  => 'localhost',
30                                         community => 'public',
31                                         version   => 'snmpv2c',
32                                         # debug => 0x0A,
33                                       );
34
35           $kernel->post( snmp => get     => snmp_handler =>
36                          -varbindlist    => \@oids );
37
38           # ... or maybe ...
39
40           $kernel->post( snmp => walk    => snmp_handler =>
41                          -baseoid        => $base_oid );
42
43           # ... or possibly even ...
44
45           my @callback_args = (1, 2, 3);
46           $kernel->post( snmp => getbulk => snmp_handler =>
47                          -varbindlist    => [ $base_oid ],
48                          -maxrepetitions => 6,
49                          -callback_args  => \@callback_args
50                        );
51
52           $heap->{pending} = 3;
53         }
54
55         sub snmp_handler {
56           my ($kernel, $heap, $request, $response) = @_[KERNEL, HEAP, ARG0, ARG1];
57           my ($alias, $host, $cmd, @args) = @$request;
58           my ($results, @callback_args)   = @$response;
59
60           if (ref $results) {
61             print "$host SNMP config ($cmd):\n";
62             print "sysName:     $results->{$system{sysName}}\n";
63             print "sysUptime:   $results->{$system{sysUptime}}\n";
64             print "sysLocation: $results->{$system{sysLocation}}\n";
65           } else {
66             print "$host SNMP error ($cmd => @args):\n$results\n";
67           }
68
69           print "Additional args: @callback_args\n";
70
71           if (--$heap->{pending} == 0) {
72             $kernel->post( $alias => 'finish' );
73           }
74         }
75
76         $poe_kernel->run();
77
78         # see the eg/ folder in the distribution archive for more samples
79

DESCRIPTION

81       POE::Component::SNMP is a POE-ized wrapper around the Net::SNMP module
82       written by David M. Town.  Most of its arguments aren't even evaluated
83       by POE, except for "-alias" and "-callback_args", as described below.
84

CREATING SNMP COMPONENTS

86       create - create an SNMP session
87             POE::Component::SNMP->create(
88                 hostname  => $hostname,   # required
89                [alias     => $alias,    ] # default 'snmp'
90                [community => $community,] # default 'public'
91                [version   => $version,  ] # default '1', SNMPv1
92                [timeout   => $timeout,  ] # default 5.0 (seconds)
93                [retries   => $retries,  ] # default 1
94                [debug     => $debug,    ] # default 0
95                [ ... any other arguments Net::SNMP recognizes ... ]
96             );
97
98           create() passes all of its arguments to the constructor for a
99           Net::SNMP object untouched with the exception of "-alias".  See
100           Net::SNMP::session().  The constructor supports either of the
101           following two parameter naming styles:
102
103             $object->method(-parameter => $value);
104             $object->method( parameter => $value);
105
106           "-hostname" is required.  This differs from the behavior in
107           Net::SNMP which is to default to 'localhost'.
108
109           "-alias" is not required unless you want to query more than one
110           host.  See "Concurrency", below.
111
112   Concurrency
113       In order to access multiple SNMP hosts simultaneously, you must create
114       a separate instance of the component for each host, by giving each
115       component a different "-alias" parameter in the constructor.
116
117       Multiple requests to a particular instance are processed in FIFO order,
118       including retries ("-retries" defaults to 1).  This means that if you
119       have multiple pending requests to a single host, and one automatically
120       attempts retry for whatever reason, the retry request will "go to the
121       end of the line" behind any other queued requests.
122
123       There is no limit to how many simultaneous instances can be processing
124       requests.  It is possible to create multiple instances for the same
125       host.
126
127       The "-alias" and "-hostname" parameters, as well as additional request-
128       specific data, are passed back to callback events, as described in
129       "CALLBACKS" below, so the callback can determine what context the
130       current response (or timeout) is related to.
131
132       NOTE: It is an error to attempt to create more than one SNMP session
133       with the same "-alias".  It's not fatal unless you run POE with
134       ASSERT_USAGE, but it won't work regardless.
135
136   Sockets
137       By default, Net::SNMP creates a single socket per network interface.
138       This is possible because the Net::SNMP event loop processes all SNMP
139       requests in FIFO order and is thus able to reuse the same socket for
140       each request, regardless of its destination; however, it is not
141       multiplexed.  Since we can only watch one connection per socket at a
142       time, this creates a conflict if you want to contact more than one
143       remote host simultaneously.  The workaround used by the module is to
144       create each socket using a different randomly generated value for the
145       "-localport" parameter, specifying a unique local UDP port for each
146       instance of the component.  This could potentially interfere with
147       remote communications if your local firewall policy requires a specific
148       source port for outgoing SNMP requests (as noted by David Town, the
149       author of Net::SNMP).  In this situation, you can supply an explicit
150       "-localport" argument to the constructor, but remember that every
151       active session requires its own unique local port per session/host, per
152       interface.
153

REQUESTS

155       Most of the events accept a list of arguments which are passed directly
156       to a Net::SNMP session.  See "METHODS" in Net::SNMP for more
157       information on these arguments.
158
159       Requests take the form:
160
161         $poe_kernel->post( $session_alias => $request =>
162                            $callback_state => @snmp_args );
163
164       See the "SYNOPSIS" and the following per-request specifics for
165       examples.
166
167       "get"
168             $poe_kernel->post( snmp => get => parse_get_results =>
169                                               #  system.sysUptime
170                                varbindlist => [ '.1.3.6.1.2.1.1.3.0' ] );
171
172           See Net::SNMP::get_request().
173
174       "getnext"
175             $poe_kernel->post( snmp => get => parse_getnext_results =>
176                                               #  system.*
177                                varbindlist => [ '.1.3.6.1.2.1.1.1.0',
178                                                 '.1.3.6.1.2.1.1.2.0',
179                                                 '.1.3.6.1.2.1.1.3.0',
180                                                 '.1.3.6.1.2.1.1.4.0',
181                                                 '.1.3.6.1.2.1.1.5.0',
182                                                 '.1.3.6.1.2.1.1.6.0',
183                                                 '.1.3.6.1.2.1.1.7.0',
184                                                 '.1.3.6.1.2.1.1.8.0',
185                                               ] );
186
187           See Net::SNMP::get_next_request().
188
189       "getbulk"
190             $poe_kernel->post( snmp => getbulk => parse_getbulk_results =>
191                                maxrepetitions => 8,
192                                               #  system.*
193                                varbindlist => [ '.1.3.6.1.2.1.1' ] );
194
195           See Net::SNMP::get_bulk_request().
196
197       "walk"
198             $poe_kernel->post( snmp => walk => parse_walk_results =>
199                                           #  system.*
200                                baseoid => [ '.1.3.6.1.2.1.1' ] );
201
202           See Net::SNMP::get_table().
203
204       "getentries"
205           See Net::SNMP::get_entries().
206
207       "inform"
208           See Net::SNMP::inform_request().
209
210       "set"
211             $poe_kernel->post( snmp => set => snmp_set_callback =>
212                                               #  system.sysContact
213                                varbindlist => [ '.1.3.6.1.2.1.1.4.0',
214                                                 'OCTET_STRING', 'test@test.com'] );
215
216           See Net::SNMP::set_request().
217
218       "trap"
219             $kernel->post( snmp => trap => @snmp_args );
220             # or, even better:
221             my $status = $kernel->call( snmp => trap => @snmp_args );
222
223           Send a SNMPv1 trap message.  See Net::SNMP::trap().  This method
224           differs from the requests in that it does not take a state name as
225           a callback parameter.  If the method is invoked with
226           POE::Kernel::call(), the return value is that of Net::SNMP::trap().
227           A false value indicates an error, and the error message can be
228           retrieved using "errmsg", below.
229
230       "trap2c"
231             $kernel->post( snmp => trap2c => @snmp_args );
232             # or, even better:
233             my $status = $kernel->call( snmp => trap2c => @snmp_args );
234
235           Send a SNMPv2c trap message.  See Net::SNMP::snmpv2_trap().  This
236           method differs from the others in that it does not take a state
237           name as a callback parameter.  If the method is invoked with
238           POE::Kernel::call(), the return value is that of snmpv2_trap(). A
239           false value indicates an error, and the error message can be
240           retrieved via "errmsg", below.
241
242       "errmsg"
243             my $last_snmp_error_message = $kernel->call( snmp => 'errmsg' );
244
245           Retrieves the last error message, if any, from the specified SNMP
246           session.
247
248       "finish"
249             $kernel->post( snmp => 'finish' );
250
251           Shut down the specified SNMP component.  All current and pending
252           requests are cancelled immediately and the session is closed.  If
253           the component is currently dispatching a request (waiting for a
254           reply) when this request is received, the response NOT be delivered
255           to the designated callback.
256
257           NOTE: Things break if you use POE::Kernel's call() method to issue
258           a request to a component and then call() a "finish" to the same
259           component within the same event/subroutine.  So don't do that.
260           Stick with post() and you'll be fine.
261

CALLBACKS

263       When a request receives a response (or times out), the supplied
264       callback event (a POE event name defined in the session that called the
265       SNMP component) is invoked.  (See POE::Session for more information
266       about $_[_ARG0] and $_[_ARG1])
267
268       The callback's $_[ARG0] parameter is an array reference containing the
269       request information: the component alias, hostname, the method called
270       (e.g. 'get'), and parameters supplied to the request.
271
272       The callback's $_[ARG1] parameter is an array reference containing the
273       response information.  The first element ("$_[ARG1][0]") is either a
274       hash reference containing response data or a scalar error message
275       string.  If any arguments have been passed to the request via
276       "-callback_args" (below), they will be returned as additional elements
277       in $_[ARG1].
278
279       NOTE: This is a change from older versions of the module!  Previously,
280       errors were returned in "$_[ARG1][1]".
281
282       "-callback_args"
283             # $callback_state receives @args in $_[_ARG1]
284             $kernel->post( $alias => get => $callback_state =>
285                            -callback_args => \@args,
286                            -varbindlist   => \@oids );
287
288           This optional parameter to all component requests returning a
289           response sets a list of additional values to be passed to the POE
290           state as parameters.  The argument must be an array reference,
291           which will be dereferenced as a list of additional response
292           parameters after the SNMP response data.
293

SEE ALSO

295         Net::SNMP
296         POE
297

AUTHOR

299       Adopted and maintained by Rob Bloodgood <rdb@cpan.org>
300
301       Originally by Todd Caine <tcaine@eli.net>
302
304       Copyright 2004-2008 by Rob Bloodgood
305
306       Copyright 2003 by Todd Caine
307
308       This library is free software; you can redistribute it and/or modify it
309       under the same terms as Perl itself.
310
311
312
313perl v5.38.0                      2023-07-21           POE::Component::SNMP(3)
Impressum