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
101 following 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
114 a separate instance of the component for each host, by giving each
115 component a different "-alias" parameter in the constructor.
116 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 responses, and one automatically attempts retry
120 for whatever reason, the retry request will "go to the end of the line"
121 behind any other pending requests.
122 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 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 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 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
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 Requests take the form:
160 $poe_kernel->post( $session_alias => $request =>
162 $callback_state => @snmp_args );
163 See the "SYNOPSIS" and the following per-request specifics for
165 examples.
166 "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 See Net::SNMP::get_request().
173 "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 See Net::SNMP::get_next_request().
188 "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 See Net::SNMP::get_bulk_request().
196 "walk"
198 $poe_kernel->post( snmp => walk => parse_walk_results =>
199 # system.*
200 baseoid => [ '.1.3.6.1.2.1.1' ] );
201 See Net::SNMP::get_table().
203 "getentries"
205 See Net::SNMP::get_entries().
206 "inform"
208 See Net::SNMP::inform_request().
209 "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 See Net::SNMP::set_request().
217 "trap"
219 $kernel->post( snmp => trap => @snmp_args );
220 # or, even better:
221 my $status = $kernel->call( snmp => trap => @snmp_args );
222 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 "trap2c"
231 $kernel->post( snmp => trap2c => @snmp_args );
232 # or, even better:
233 my $status = $kernel->call( snmp => trap2c => @snmp_args );
234 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()".
239 A false value indicates an error, and the error message can be
240 retrieved via "errmsg", below.
241 "errmsg"
243 my $last_snmp_error_message = $kernel->call( snmp => 'errmsg' );
244 Retrieves the last error message, if any, from the specified SNMP
246 session.
247 "finish"
249 $kernel->post( snmp => 'finish' );
250 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 NOTE: Things break if you use POE::Kernel's "call()" method to
258 issue a request to a component and then "call()" a "finish" to the
259 same component within the same event/subroutine. So don't do that.
260 Stick with "post()" and you'll be fine.
261
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 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 The callback's $_[ARG1] parameter is an array reference containing the
273 response information. The first element ($_[ARG1][0]) is either a hash
274 reference containing response data or a scalar error message string.
275 If any arguments have been passed to the request via "-callback_args"
276 (below), they will be returned as additional elements in $_[ARG1].
277 NOTE: This is a change from older versions of the module! Previously,
279 errors were returned in $_[ARG1][1].
280 "-callback_args"
282 # $callback_state receives @args in $_[_ARG1]
283 $kernel->post( $alias => get => $callback_state =>
284 -callback_args => \@args,
285 -varbindlist => \@oids );
286 This optional parameter to all component requests returning a
288 response sets a list of additional values to be passed to the POE
289 state as parameters. The argument must be an array reference,
290 which will be dereferenced as a list of additional response
291 parameters after the SNMP response data.
292
294 Net::SNMP
295 POE
296
298 Adopted and maintained by Rob Bloodgood <rdb@cpan.org>
299 Originally by Todd Caine <tcaine@eli.net>
301
303 Copyright 2004-2008 by Rob Bloodgood
304 Copyright 2003 by Todd Caine
306 This library is free software; you can redistribute it and/or modify it
308 under the same terms as Perl itself.
309perl v5.12.0 2008-08-01 POE::Component::SNMP(3)