1agent(3)              User Contributed Perl Documentation             agent(3)
2
3
4

NAME

6       NetSNMP::agent - Perl extension for the net-snmp agent.
7

SYNOPSIS

9         use NetSNMP::agent;
10
11         my $agent = new NetSNMP::agent('Name' => 'my_agent_name');
12

DESCRIPTION

14       This module implements an API set to make a SNMP agent act as a snmp
15       agent, a snmp subagent (using the AgentX subagent protocol) and/or
16       embedded perl-APIs directly within the traditional net-snmp agent
17       demon.
18
19       Also see the tutorial about the genaral Net-SNMP C API, which this
20       module implements in a perl-way, and a perl specific tutorial at:
21
22         http://www.net-snmp.org/tutorial-5/toolkit/
23

EXAMPLES

25   Sub-agent example
26               use NetSNMP::agent (':all');
27               use NetSNMP::ASN qw(ASN_OCTET_STR);
28
29               my $value = "hello world";
30               sub myhandler {
31                   my ($handler, $registration_info, $request_info, $requests) = @_;
32                   my $request;
33
34                   for($request = $requests; $request; $request = $request->next()) {
35                       my $oid = $request->getOID();
36                       if ($request_info->getMode() == MODE_GET) {
37                           # ... generally, you would calculate value from oid
38                           if ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0")) {
39                               $request->setValue(ASN_OCTET_STR, $value);
40                           }
41                       } elsif ($request_info->getMode() == MODE_GETNEXT) {
42                           # ... generally, you would calculate value from oid
43                           if ($oid < new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0")) {
44                               $request->setOID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0");
45                               $request->setValue(ASN_OCTET_STR, $value);
46                           }
47                       } elsif ($request_info->getMode() == MODE_SET_RESERVE1) {
48                           if ($oid != new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0")) {  # do error checking here
49                               $request->setError($request_info, SNMP_ERR_NOSUCHNAME);
50                           }
51                       } elsif ($request_info->getMode() == MODE_SET_ACTION) {
52                           # ... (or use the value)
53                           $value = $request->getValue();
54                       }
55                   }
56
57               }
58
59               my $agent = new NetSNMP::agent(
60                                       # makes the agent read a my_agent_name.conf file
61                                       'Name' => "my_agent_name",
62                                       'AgentX' => 1
63                                       );
64               $agent->register("my_agent_name", ".1.3.6.1.4.1.8072.9999.9999.7375",
65                                \&myhandler);
66
67               my $running = 1;
68               while($running) {
69                       $agent->agent_check_and_process(1);
70               }
71
72               $agent->shutdown();
73
74   Embedded agent example
75               # place this in a .pl file, and then in your snmpd.conf file put:
76               #    perl do '/path/to/file.pl';
77
78               use NetSNMP::agent;
79               my $agent;
80
81               sub myhandler {
82                   my ($handler, $registration_info, $request_info, $requests) = @_;
83                   # ...
84               }
85
86               $agent = new NetSNMP::agent(
87                                       'Name' => 'my_agent_name'
88                                       );
89
90               $agent->register("my_agent_name", ".1.3.6.1.4.1.8072.9999.9999.7375",
91                                \&myhandler);
92
93               $agent->main_loop();
94

CONSTRUCTOR

96           new ( OPTIONS )
97               This is the constructor for a new NetSNMP::agent object.
98
99           Possible options are:
100
101               Name    - Name of the agent (optional, defaults to "perl")
102                         (The snmp library will read a NAME.conf snmp
103                         configuration file based on this argument.)
104               AgentX  - Make us a sub-agent (0 = false, 1 = true)
105                         (The Net-SNMP master agent must be running first)
106               Ports   - Ports this agent will listen on (EG: "udp:161,tcp:161")
107
108           Example:
109
110               $agent = new NetSNMP::agent(
111                                        'Name' => 'my_agent_name',
112                                        'AgentX' => 1
113                                        );
114

METHODS

116           register (NAME, OID, \&handler_routine )
117               Registers the callback handler with given OID.
118
119               $agent->register();
120
121               A return code of 0 indicates no error.
122
123           agent_check_and_process ( BLOCKING )
124               Run one iteration of the main loop.
125
126               BLOCKING - Blocking or non-blocking call. 1 = true, 0 = false.
127
128               $agent->agent_check_and_process(1);
129
130           main_loop ()
131               Runs the agent in a loop. Does not return.
132
133           shutdown ()
134               Nicely shuts down the agent or sub-agent.
135
136               $agent->shutdown();
137

HANDLER CALLBACKS

139           handler ( HANDLER, REGISTRATION_INFO, REQUEST_INFO, REQUESTS )
140
141               The handler is called with the following parameters:
142
143               HANDLER                 - FIXME
144               REGISTRATION_INFO       - what are the correct meanings of these?
145               REQUEST_INFO            -
146               REQUESTS                -
147
148           Example handler:
149
150               sub myhandler {
151                   my ($handler, $reg_info, $request_info, $requests) = @_;
152                   # ...
153               }
154
155       The handler subroutine will be called when a SNMP request received by
156       the agent for anything below the registered OID.  The handler is passed
157       4 arguments: $handler, $registration_info, $request_info, $requests.
158       These match the arguments passed to the C version of the same API.
159       Note that they are not entirely complete objects but are functional
160       "enough" at this point in time.
161
162   $request_info object functions
163           getMode ()
164               Returns the mode of the request. See the MODES section for
165               list of valid modes.
166
167               $mode = $request->getMode();
168
169   $registration_info object functions
170           getRootOID ()
171               Returns a NetSNMP::OID object that describes the registration
172               point that the handler is getting called for (in case you
173               register one handler function with multiple OIDs, which should
174               be rare anyway)
175
176               $root_oid = $request->getRootOID();
177
178   $request object functions
179           next ()
180               Returns the next request in the list or undef if there is no
181               next request.
182
183               $request = $request->next();
184
185           getOID ()
186               Returns the oid of the request (a NetSNMP::OID class).
187
188               $oid = $request->getOID();
189
190           setOID (new NetSNMP::OID("someoid"))
191               Sets the OID of the request to a passed oid value.  This
192               should generally only be done during handling of GETNEXT
193               requests.
194
195               $request->setOID(new NetSNMP::OID("someoid"));
196
197           getValue ()
198               Returns the value of the request. Used for example when
199               setting values.
200
201               $value = $request->getValue();
202
203               FIXME: how to get the type of the value? Is it even available?
204                      [Wes: no, not yet.]
205
206           setValue ( TYPE, DATA )
207               Sets the data to be returned to the daemon.
208
209               Returns 1 on success, 0 on error.
210
211               TYPE - Type of the data. See NetSNMP::ASN for valid types.
212               DATA - The data to return.
213
214               $ret = $request->setValue(ASN_OCTET_STR, "test");
215
216           setError ( REQUEST_INFO, ERROR_CODE )
217               Sets the given error code for the request. See the ERROR CODES
218               section for list of valid codes.
219
220               $request->setError($request_info, SNMP_ERR_NOTWRITABLE);
221
222           getProcessed ()
223               The processed flag indicates that a request does not need to
224               be dealt with because someone else (a higher handler) has
225               dealt with it already.
226
227               $processed = $request->getProcessed();
228
229           setProcessed ( PROCESSED )
230               Sets the processed flag flag in the request.  You generally
231               should not have to set this yourself.
232
233               PROCESSED - 0 = false, 1 = true
234
235               $request->setProcessed(1);
236
237           getDelegated ()
238               If you can handle a request in the background or at a future
239               time (EG, you're waiting on a file handle, or network traffic,
240               or ...), the delegated flag can be set in the request.  When
241               the request is processed in the future the flag should be set
242               back to 0 so the agent will know that it can wrap up the
243               original request and send it back to the manager.  This has
244               not been tested within perl, but it hopefully should work.
245
246               $delegated = $request->getDelegated();
247
248           setDelegated ( DELEGATED )
249               Sets the delegated flag.
250
251               DELEGATED - 0 = false, 1 = true
252
253               $request->setDelegated(1);
254
255           getRepeat ()
256               The repeat flag indicates that a getbulk operation is being
257               handled and this indicates how many answers need to be
258               returned.  Generally, if you didn't register to directly
259               handle getbulk support yourself, you won't need to deal with
260               this value.
261
262               $repeat = $request->getRepeat();
263
264           setRepeat ( REPEAT )
265               Sets the repeat count (decrement after answering requests if
266               you handle getbulk requests yourself)
267
268               REPEAT -  repeat count FIXME
269
270               $request->setRepeat(5);
271
272           getSourceIp ()
273
274               Gets the IPv4 address of the device making the request to the handler.
275
276               use Socket;
277               print "Source: ", inet_ntoa($request->getSourceIp()), "\n";
278
279           getDestIp ()
280
281               Gets the IPv4 address of the destination that the request was sent to.
282
283               use Socket;
284               print "Destination: ", inet_ntoa($request->getDestIp()), "\n";
285

MODES

287               MODE_GET
288               MODE_GETBULK
289               MODE_GETNEXT
290               MODE_SET_ACTION
291               MODE_SET_BEGIN
292               MODE_SET_COMMIT
293               MODE_SET_FREE
294               MODE_SET_RESERVE1
295               MODE_SET_RESERVE2
296               MODE_SET_UNDO
297

ERROR CODES

299               SNMP_ERR_NOERROR
300               SNMP_ERR_TOOBIG
301               SNMP_ERR_NOSUCHNAME
302               SNMP_ERR_BADVALUE
303               SNMP_ERR_READONLY
304               SNMP_ERR_GENERR
305               SNMP_ERR_NOACCESS
306               SNMP_ERR_WRONGTYPE
307               SNMP_ERR_WRONGLENGTH
308               SNMP_ERR_WRONGENCODING
309               SNMP_ERR_WRONGVALUE
310               SNMP_ERR_NOCREATION
311               SNMP_ERR_INCONSISTENTVALUE
312               SNMP_ERR_RESOURCEUNAVAILABLE
313               SNMP_ERR_COMMITFAILED
314               SNMP_ERR_UNDOFAILED
315               SNMP_ERR_AUTHORIZATIONERROR
316               SNMP_ERR_NOTWRITABLE
317

AUTHOR

319       Please mail the net-snmp-users@lists.sourceforge.net mailing list for
320       help, questions or comments about this module.
321
322       Module written by:
323          Wes Hardaker  <hardaker@users.sourceforge.net>
324
325       Documentation written by:
326          Toni Willberg <toniw@iki.fi>
327          Wes Hardaker  <hardaker@users.sourceforge.net>
328

SEE ALSO

330       NetSNMP::OID(3), NetSNMP::ASN(3), perl(1).
331
332
333
334perl v5.16.3                      2012-10-09                          agent(3)
Impressum