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 mod‐
20 ule 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');
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 }
65 $agent->register("my_agent_name", ".1.3.6.1.4.1.8072.9999.9999.7375",
67 \&myhandler);
68 my $running = 1;
70 while($running) {
71 $agent->agent_check_and_process(1);
72 }
73 $agent->shutdown();
75 Embedded agent example
77 # place this in a .pl file, and then in your snmpd.conf file put:
79 # perl do '/path/to/file.pl';
80 use NetSNMP::agent;
82 my $agent;
83 sub myhandler {
85 my ($handler, $registration_info, $request_info, $requests) = @_;
86 # ...
87 }
88 $agent = new NetSNMP::agent(
90 'Name' => 'my_agent_name'
91 );
92 $agent->register("my_agent_name", ".1.3.6.1.4.1.8072.9999.9999.7375",
94 \&myhandler);
95 $agent->main_loop();
97
99 new ( OPTIONS )
100 This is the constructor for a new NetSNMP::agent object.
101 Possible options are:
103 Name - Name of the agent (optional, defaults to "perl")
105 (The snmp library will read a NAME.conf snmp
106 configuration file based on this argument.)
107 AgentX - Make us a sub-agent (0 = false, 1 = true)
108 (The Net-SNMP master agent must be running first)
109 Ports - Ports this agent will listen on (EG: "udp:161,tcp:161")
110 Example:
112 $agent = new NetSNMP::agent(
114 'Name' => 'my_agent_name',
115 'AgentX' => 1
116 );
117
119 register (NAME, OID, \&handler_routine )
120 Registers the callback handler with given OID.
121 $agent->register();
123 A return code of 0 indicates no error.
125 agent_check_and_process ( BLOCKING )
127 Run one iteration of the main loop.
128 BLOCKING - Blocking or non-blocking call. 1 = true, 0 = false.
130 $agent->agent_check_and_process(1);
132 main_loop ()
134 Runs the agent in a loop. Does not return.
135 shutdown ()
137 Nicely shuts down the agent or sub-agent.
138 $agent->shutdown();
140
142 handler ( HANDLER, REGISTRATION_INFO, REQUEST_INFO, REQUESTS )
143 The handler is called with the following parameters:
145 HANDLER - FIXME
147 REGISTRATION_INFO - what are the correct meanings of these?
148 REQUEST_INFO -
149 REQUESTS -
150 Example handler:
152 sub myhandler {
154 my ($handler, $reg_info, $request_info, $requests) = @_;
155 # ...
156 }
157 The handler subroutine will be called when a SNMP request received by
159 the agent for anything below the registered OID. The handler is passed
160 4 arguments: $handler, $registration_info, $request_info, $requests.
161 These match the arguments passed to the C version of the same API.
162 Note that they are not entirely complete objects but are functional
163 "enough" at this point in time.
164 $request_info object functions
166 getMode ()
168 Returns the mode of the request. See the MODES section for
169 list of valid modes.
170 $mode = $request->getMode();
172 getRootOID ()
174 Returns a NetSNMP::OID object that describes the registration
175 point that the handler is getting called for (in case you
176 register one handler function with multiple OIDs, which should
177 be rare anyway)
178 $root_oid = $request->getRootOID();
180 $request object functions
182 next ()
184 Returns the next request in the list or undef if there is no
185 next request.
186 $request = $request->next();
188 getOID ()
190 Returns the oid of the request (a NetSNMP::OID class).
191 $oid = $request->getOID();
193 setOID (new NetSNMP::OID("someoid"))
195 Sets the OID of the request to a passed oid value. This
196 should generally only be done during handling of GETNEXT
197 requests.
198 $request->setOID(new NetSNMP::OID("someoid"));
200 getValue ()
202 Returns the value of the request. Used for example when
203 setting values.
204 $value = $request->getValue();
206 FIXME: how to get the type of the value? Is it even available?
208 [Wes: no, not yet.]
209 setValue ( TYPE, DATA )
211 Sets the data to be returned to the daemon.
212 Returns 1 on success, 0 on error.
214 TYPE - Type of the data. See NetSNMP::ASN for valid types.
216 DATA - The data to return.
217 $ret = $request->setValue(ASN_OCTET_STR, "test");
219 setError ( REQUEST_INFO, ERROR_CODE )
221 Sets the given error code for the request. See the ERROR CODES
222 section for list of valid codes.
223 $request->setError($request_info, SNMP_ERR_NOTWRITABLE);
225 getProcessed ()
227 The processed flag indicates that a request does not need to
228 be dealt with because someone else (a higher handler) has
229 dealt with it already.
230 $processed = $request->getProcessed();
232 setProcessed ( PROCESSED )
234 Sets the processed flag flag in the request. You generally
235 should not have to set this yourself.
236 PROCESSED - 0 = false, 1 = true
238 $request->setProcessed(1);
240 getDelegated ()
242 If you can handle a request in the background or at a future
243 time (EG, you're waiting on a file handle, or network traffic,
244 or ...), the delegated flag can be set in the request. When
245 the request is processed in the future the flag should be set
246 back to 0 so the agent will know that it can wrap up the
247 original request and send it back to the manager. This has
248 not been tested within perl, but it hopefully should work.
249 $delegated = $request->getDelegated();
251 setDelegated ( DELEGATED )
253 Sets the delegated flag.
254 DELEGATED - 0 = false, 1 = true
256 $request->setDelegated(1);
258 getRepeat ()
260 The repeat flag indicates that a getbulk operation is being
261 handled and this indicates how many answers need to be
262 returned. Generally, if you didn't register to directly
263 handle getbulk support yourself, you won't need to deal with
264 this value.
265 $repeat = $request->getRepeat();
267 setRepeat ( REPEAT )
269 Sets the repeat count (decrement after answering requests if
270 you handle getbulk requests yourself)
271 REPEAT - repeat count FIXME
273 $request->setRepeat(5);
275
277 MODE_GET
278 MODE_GETBULK
279 MODE_GETNEXT
280 MODE_SET_ACTION
281 MODE_SET_BEGIN
282 MODE_SET_COMMIT
283 MODE_SET_FREE
284 MODE_SET_RESERVE1
285 MODE_SET_RESERVE2
286 MODE_SET_UNDO
287
289 SNMP_ERR_NOERROR
290 SNMP_ERR_TOOBIG
291 SNMP_ERR_NOSUCHNAME
292 SNMP_ERR_BADVALUE
293 SNMP_ERR_READONLY
294 SNMP_ERR_GENERR
295 SNMP_ERR_NOACCESS
296 SNMP_ERR_WRONGTYPE
297 SNMP_ERR_WRONGLENGTH
298 SNMP_ERR_WRONGENCODING
299 SNMP_ERR_WRONGVALUE
300 SNMP_ERR_NOCREATION
301 SNMP_ERR_INCONSISTENTVALUE
302 SNMP_ERR_RESOURCEUNAVAILABLE
303 SNMP_ERR_COMMITFAILED
304 SNMP_ERR_UNDOFAILED
305 SNMP_ERR_AUTHORIZATIONERROR
306 SNMP_ERR_NOTWRITABLE
307
309 Please mail the net-snmp-users@lists.sourceforge.net mailing list for
310 help, questions or comments about this module.
311 Module written by:
313 Wes Hardaker <hardaker@users.sourceforge.net>
314 Documentation written by:
316 Toni Willberg <toniw@iki.fi>
317 Wes Hardaker <hardaker@users.sourceforge.net>
318
320 NetSNMP::OID(3), NetSNMP::ASN(3), perl(1).
321perl v5.8.8 2004-10-08 agent(3)