1POE::Component::SNMP(3)User Contributed Perl DocumentatioPnOE::Component::SNMP(3)
2
6 POE::Component::SNMP - POE interface to Net::SNMP
7
9 # this script is included in the distribution as eg/snmp_sample.pl
10 use POE qw/Component::SNMP/;
11 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 POE::Session->create( inline_states =>
20 { _start => \&_start,
21 snmp_handler => \&snmp_handler,
22 }
23 );
24 sub _start {
26 my ($kernel, $heap) = @_[KERNEL, HEAP];
27 POE::Component::SNMP->create( alias => 'snmp', # same as default
29 hostname => 'localhost',
30 community => 'public',
31 version => 'snmpv2c',
32 # debug => 0x0A,
33 );
34 $kernel->post( snmp => get => snmp_handler =>
36 -varbindlist => \@oids );
37 # ... or maybe ...
39 $kernel->post( snmp => walk => snmp_handler =>
41 -baseoid => $base_oid );
42 # ... or possibly even ...
44 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 $heap->{pending} = 3;
53 }
54 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 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 print "Additional args: @callback_args\n";
70 if (--$heap->{pending} == 0) {
72 $kernel->post( $alias => 'finish' );
73 }
74 }
75 $poe_kernel->run();
77 # see the eg/ folder in the distribution archive for more samples
79
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
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 "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 fol‐
101 lowing two parameter naming styles:
102 $object->method(-parameter => $value);
104 $object->method( parameter => $value);
105 "-hostname" is required. This differs from the behavior in
107 Net::SNMP which is to default to 'localhost'.
108 "-alias" is not required unless you want to query more than one
110 host. See "Concurrency", below.
111 Concurrency
113 In order to access multiple SNMP hosts simultaneously, you must create
115 a separate instance of the component for each host, by giving each com‐
116 ponent a different "-alias" parameter in the constructor.
117 The "-alias" and "-hostname" parameters, as well as additional request-
119 specific data, are passed back to callback events, as described in
120 "CALLBACKS" below, so the callback can determine what context the cur‐
121 rent response (or timeout) is related to.
122 NOTE: It is an error to attempt to create more than one SNMP session
124 with the same "-alias". It's not fatal unless you run POE with
125 ASSERT_USAGE, but it won't work regardless.
126 Sockets
128 By default, Net::SNMP creates a single socket per network interface.
130 This is possible because the Net::SNMP event loop processes all SNMP
131 requests in FIFO order and is thus able to reuse the same socket for
132 each request; however, it is not asynchronous. Since we can only watch
133 one connection per socket at a time, this creates a conflict if you
134 want to contact more than one remote host simultaneously. The work‐
135 around used by the module is to create each socket using a different
136 randomly generated value for the "-localport" parameter, specifying a
137 unique local UDP port for each instance of the component. This could
138 potentially interfere with remote communications if your local firewall
139 policy requires a specific source port for outgoing SNMP requests (as
140 noted by David Town, the author of Net::SNMP). In this situation, you
141 can supply an explicit "-localport" argument to the constructor, but
142 remember that every active session requires its own unique local port
143 per session/host, per interface.
144
146 Most of the events accept a list of arguments which are passed directly
147 to a Net::SNMP session. See "METHODS" in Net::SNMP for more informa‐
148 tion on these arguments.
149 Requests take the form:
151 $poe_kernel->post( $session_alias => $request =>
153 $callback_state => @snmp_args );
154 See the SYNOPSIS for specific examples.
156 "get"
158 See Net::SNMP::get_request().
159 "getnext"
161 See Net::SNMP::get_next_request().
162 "getbulk"
164 See Net::SNMP::get_bulk_request().
165 "walk"
167 See Net::SNMP::get_table().
168 "inform"
170 See Net::SNMP::inform_request().
171 "set"
173 See Net::SNMP::set_request().
174 "trap"
176 $kernel->post( snmp => trap => @snmp_args );
177 # or, even better:
178 my $status = $kernel->call( snmp => trap => @snmp_args );
179 Send a SNMPv1 trap message. See Net::SNMP::trap(). This method
181 differs from the requests in that it does not take a state name as
182 a callback parameter. If the method is invoked with POE::Ker‐
183 nel::call(), the return value is that of Net::SNMP::trap(). A false
184 value indicates an error, and the error message can be retrieved
185 using "errmsg", below.
186 "trap2c"
188 $kernel->post( snmp => trap2c => @snmp_args );
189 # or, even better:
190 my $status = $kernel->call( snmp => trap2c => @snmp_args );
191 Send a SNMPv2c trap message. See Net::SNMP::snmpv2_trap(). This
193 method differs from the others in that it does not take a state
194 name as a callback parameter. If the method is invoked with
195 "POE::Kernel::call()", the return value is that of
196 Net::SNMP::snmpv2_trap(). A false value indicates an error, and the
197 error message can be retrieved using calling "errmsg", below.
198 "errmsg"
200 my $last_snmp_error_message = $kernel->call( snmp => 'errmsg' );
201 Retrieves the last error message, if any, from the specified SNMP
203 session.
204 "finish"
206 $kernel->post( snmp => 'finish' );
207 Shut down the SNMP component. Cancels all current and pending
209 requests immediately and closes the session. If the component is
210 currently dispatching a request (waiting for a reply) when this
211 request is received, the response NOT be delivered.
212
214 When a request receives a response (or times out), the supplied call‐
215 back event (a POE event name defined in the session that called the
216 SNMP component) is invoked. (See POE::Session for more information
217 about $_[_ARG0] and $_[_ARG1])
218 The callback's $_[ARG0] parameter is an array reference containing the
220 request information: the component alias, hostname, the method called
221 (e.g. 'get'), and parameters supplied to the request.
222 The callback's $_[ARG1] parameter is an array reference containing the
224 response information. The first element ($_[ARG1][0]) is either a hash
225 reference containing response data or a scalar error message string.
226 If any arguments have been passed to the request via "-callback_args"
227 (below), they will be returned as additional elements in $_[ARG1].
228 NOTE: This is a change from older versions of the module! Previously,
230 errors were returned in $_[ARG1][1].
231 "-callback_args"
233 # $callback_state receives @args in $_[_ARG1]
234 $kernel->post( $alias => get => $callback_state =>
235 -callback_args => \@args,
236 -varbindlist => \@oids );
237 This optional parameter to all component requests returning a
239 response sets a list of additional values to be passed to the POE
240 state as parameters. The argument must be an array reference,
241 which will be dereferenced as a list of additional response parame‐
242 ters after the SNMP response data.
243
245 Net::SNMP
246 POE
247
249 Adopted and maintained by Rob Bloodgood <rdb@cpan.org>
250 Originally by Todd Caine <tcaine@eli.net>
252
254 Copyright 2004-2006 by Rob Bloodgood
255 Copyright 2003 by Todd Caine
257 This library is free software; you can redistribute it and/or modify it
259 under the same terms as Perl itself.
260perl v5.8.8 2006-09-27 POE::Component::SNMP(3)