NetSNMP::agent(3pm)

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           getRootOID ()
170               Returns a NetSNMP::OID object that describes the registration
171               point that the handler is getting called for (in case you
172               register one handler function with multiple OIDs, which should
173               be rare anyway)
174
175               $root_oid = $request->getRootOID();
176
177   $request object functions
178           next ()
179               Returns the next request in the list or undef if there is no
180               next request.
181
182               $request = $request->next();
183
184           getOID ()
185               Returns the oid of the request (a NetSNMP::OID class).
186
187               $oid = $request->getOID();
188
189           setOID (new NetSNMP::OID("someoid"))
190               Sets the OID of the request to a passed oid value.  This
191               should generally only be done during handling of GETNEXT
192               requests.
193
194               $request->setOID(new NetSNMP::OID("someoid"));
195
196           getValue ()
197               Returns the value of the request. Used for example when
198               setting values.
199
200               $value = $request->getValue();
201
202               FIXME: how to get the type of the value? Is it even available?
203                      [Wes: no, not yet.]
204
205           setValue ( TYPE, DATA )
206               Sets the data to be returned to the daemon.
207
208               Returns 1 on success, 0 on error.
209
210               TYPE - Type of the data. See NetSNMP::ASN for valid types.
211               DATA - The data to return.
212
213               $ret = $request->setValue(ASN_OCTET_STR, "test");
214
215           setError ( REQUEST_INFO, ERROR_CODE )
216               Sets the given error code for the request. See the ERROR CODES
217               section for list of valid codes.
218
219               $request->setError($request_info, SNMP_ERR_NOTWRITABLE);
220
221           getProcessed ()
222               The processed flag indicates that a request does not need to
223               be dealt with because someone else (a higher handler) has
224               dealt with it already.
225
226               $processed = $request->getProcessed();
227
228           setProcessed ( PROCESSED )
229               Sets the processed flag flag in the request.  You generally
230               should not have to set this yourself.
231
232               PROCESSED - 0 = false, 1 = true
233
234               $request->setProcessed(1);
235
236           getDelegated ()
237               If you can handle a request in the background or at a future
238               time (EG, you're waiting on a file handle, or network traffic,
239               or ...), the delegated flag can be set in the request.  When
240               the request is processed in the future the flag should be set
241               back to 0 so the agent will know that it can wrap up the
242               original request and send it back to the manager.  This has
243               not been tested within perl, but it hopefully should work.
244
245               $delegated = $request->getDelegated();
246
247           setDelegated ( DELEGATED )
248               Sets the delegated flag.
249
250               DELEGATED - 0 = false, 1 = true
251
252               $request->setDelegated(1);
253
254           getRepeat ()
255               The repeat flag indicates that a getbulk operation is being
256               handled and this indicates how many answers need to be
257               returned.  Generally, if you didn't register to directly
258               handle getbulk support yourself, you won't need to deal with
259               this value.
260
261               $repeat = $request->getRepeat();
262
263           setRepeat ( REPEAT )
264               Sets the repeat count (decrement after answering requests if
265               you handle getbulk requests yourself)
266
267               REPEAT -  repeat count FIXME
268
269               $request->setRepeat(5);
270
271           getSourceIp ()
272
273               Gets the IPv4 address of the device making the request to the handler.
274
275               use Socket;
276               print "Source: ", inet_ntoa($request->getSourceIp()), "\n";
277
278           getDestIp ()
279
280               Gets the IPv4 address of the destination that the request was sent to.
281
282               use Socket;
283               print "Destination: ", inet_ntoa($request->getDestIp()), "\n";
284

MODES

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

ERROR CODES

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

AUTHOR

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