1agent(3) User Contributed Perl Documentation agent(3)
2
6 NetSNMP::agent - Perl extension for the net-snmp agent.
7
9 use NetSNMP::agent;
10 my $agent = new NetSNMP::agent('Name' => 'my_agent_name');
12
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 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 http://www.net-snmp.org/tutorial-5/toolkit/
23
25 Sub-agent example
26 use NetSNMP::agent (':all');
27 use NetSNMP::ASN qw(ASN_OCTET_STR);
28 my $value = "hello world";
30 sub myhandler {
31 my ($handler, $registration_info, $request_info, $requests) = @_;
32 my $request;
33 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 }
58 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 my $running = 1;
68 while($running) {
69 $agent->agent_check_and_process(1);
70 }
71 $agent->shutdown();
73 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 use NetSNMP::agent;
79 my $agent;
80 sub myhandler {
82 my ($handler, $registration_info, $request_info, $requests) = @_;
83 # ...
84 }
85 $agent = new NetSNMP::agent(
87 'Name' => 'my_agent_name'
88 );
89 $agent->register("my_agent_name", ".1.3.6.1.4.1.8072.9999.9999.7375",
91 \&myhandler);
92 $agent->main_loop();
94
96 new ( OPTIONS )
97 This is the constructor for a new NetSNMP::agent object.
98 Possible options are:
100 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 Example:
109 $agent = new NetSNMP::agent(
111 'Name' => 'my_agent_name',
112 'AgentX' => 1
113 );
114
116 register (NAME, OID, \&handler_routine )
117 Registers the callback handler with given OID.
118 $agent->register();
120 A return code of 0 indicates no error.
122 agent_check_and_process ( BLOCKING )
124 Run one iteration of the main loop.
125 BLOCKING - Blocking or non-blocking call. 1 = true, 0 = false.
127 $agent->agent_check_and_process(1);
129 main_loop ()
131 Runs the agent in a loop. Does not return.
132 shutdown ()
134 Nicely shuts down the agent or sub-agent.
135 $agent->shutdown();
137
139 handler ( HANDLER, REGISTRATION_INFO, REQUEST_INFO, REQUESTS )
140 The handler is called with the following parameters:
142 HANDLER - FIXME
144 REGISTRATION_INFO - what are the correct meanings of these?
145 REQUEST_INFO -
146 REQUESTS -
147 Example handler:
149 sub myhandler {
151 my ($handler, $reg_info, $request_info, $requests) = @_;
152 # ...
153 }
154 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 $request_info object functions
163 getMode ()
164 Returns the mode of the request. See the MODES section for
165 list of valid modes.
166 $mode = $request->getMode();
168 $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 $root_oid = $request->getRootOID();
177 $request object functions
179 next ()
180 Returns the next request in the list or undef if there is no
181 next request.
182 $request = $request->next();
184 getOID ()
186 Returns the oid of the request (a NetSNMP::OID class).
187 $oid = $request->getOID();
189 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 $request->setOID(new NetSNMP::OID("someoid"));
196 getValue ()
198 Returns the value of the request. Used for example when
199 setting values.
200 $value = $request->getValue();
202 FIXME: how to get the type of the value? Is it even available?
204 [Wes: no, not yet.]
205 setValue ( TYPE, DATA )
207 Sets the data to be returned to the daemon.
208 Returns 1 on success, 0 on error.
210 TYPE - Type of the data. See NetSNMP::ASN for valid types.
212 DATA - The data to return.
213 $ret = $request->setValue(ASN_OCTET_STR, "test");
215 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 $request->setError($request_info, SNMP_ERR_NOTWRITABLE);
221 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 $processed = $request->getProcessed();
228 setProcessed ( PROCESSED )
230 Sets the processed flag flag in the request. You generally
231 should not have to set this yourself.
232 PROCESSED - 0 = false, 1 = true
234 $request->setProcessed(1);
236 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 $delegated = $request->getDelegated();
247 setDelegated ( DELEGATED )
249 Sets the delegated flag.
250 DELEGATED - 0 = false, 1 = true
252 $request->setDelegated(1);
254 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 $repeat = $request->getRepeat();
263 setRepeat ( REPEAT )
265 Sets the repeat count (decrement after answering requests if
266 you handle getbulk requests yourself)
267 REPEAT - repeat count FIXME
269 $request->setRepeat(5);
271 getSourceIp ()
273 Gets the IPv4 address of the device making the request to the handler.
275 use Socket;
277 print "Source: ", inet_ntoa($request->getSourceIp()), "\n";
278 getDestIp ()
280 Gets the IPv4 address of the destination that the request was sent to.
282 use Socket;
284 print "Destination: ", inet_ntoa($request->getDestIp()), "\n";
285
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
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
319 Please mail the net-snmp-users@lists.sourceforge.net mailing list for
320 help, questions or comments about this module.
321 Module written by:
323 Wes Hardaker <hardaker@users.sourceforge.net>
324 Documentation written by:
326 Toni Willberg <toniw@iki.fi>
327 Wes Hardaker <hardaker@users.sourceforge.net>
328
330 NetSNMP::OID(3), NetSNMP::ASN(3), perl(1).
331perl v5.16.3 2012-10-09 agent(3)