agent.pm
上传用户:wxp200602
上传日期:2007-10-30
资源大小:4028k
文件大小:13k
源码类别:

SNMP编程

开发平台:

Unix_Linux

  1. package NetSNMP::agent;
  2. use strict;
  3. use Carp;
  4. require Exporter;
  5. require DynaLoader;
  6. use AutoLoader;
  7. use NetSNMP::default_store (':all');
  8. use NetSNMP::agent::default_store (':all');
  9. use NetSNMP::OID (':all');
  10. use NetSNMP::agent::netsnmp_request_infoPtr;
  11. use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK @EXPORT $VERSION $AUTOLOAD);
  12. @ISA = qw(Exporter AutoLoader DynaLoader);
  13. # Items to export into callers namespace by default. Note: do not export
  14. # names by default without a very good reason. Use EXPORT_OK instead.
  15. # Do not simply export all your public functions/methods/constants.
  16. # This allows declaration use NetSNMP::agent ':all';
  17. # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
  18. # will save memory.
  19. %EXPORT_TAGS = ( 'all' => [ qw(
  20. MODE_GET
  21. MODE_GETBULK
  22. MODE_GETNEXT
  23. MODE_SET_ACTION
  24. MODE_SET_BEGIN
  25. MODE_SET_COMMIT
  26. MODE_SET_FREE
  27. MODE_SET_RESERVE1
  28. MODE_SET_RESERVE2
  29. MODE_SET_UNDO
  30. SNMP_ERR_NOERROR
  31. SNMP_ERR_TOOBIG
  32. SNMP_ERR_NOSUCHNAME
  33. SNMP_ERR_BADVALUE
  34. SNMP_ERR_READONLY
  35. SNMP_ERR_GENERR
  36. SNMP_ERR_NOACCESS
  37. SNMP_ERR_WRONGTYPE
  38. SNMP_ERR_WRONGLENGTH
  39. SNMP_ERR_WRONGENCODING
  40. SNMP_ERR_WRONGVALUE
  41. SNMP_ERR_NOCREATION
  42. SNMP_ERR_INCONSISTENTVALUE
  43. SNMP_ERR_RESOURCEUNAVAILABLE
  44. SNMP_ERR_COMMITFAILED
  45. SNMP_ERR_UNDOFAILED
  46. SNMP_ERR_AUTHORIZATIONERROR
  47. SNMP_ERR_NOTWRITABLE
  48. ) ] );
  49. @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
  50. @EXPORT = qw(
  51. MODE_GET
  52. MODE_GETBULK
  53. MODE_GETNEXT
  54. MODE_SET_ACTION
  55. MODE_SET_BEGIN
  56. MODE_SET_COMMIT
  57. MODE_SET_FREE
  58. MODE_SET_RESERVE1
  59. MODE_SET_RESERVE2
  60. MODE_SET_UNDO
  61. SNMP_ERR_NOERROR
  62. SNMP_ERR_TOOBIG
  63. SNMP_ERR_NOSUCHNAME
  64. SNMP_ERR_BADVALUE
  65. SNMP_ERR_READONLY
  66. SNMP_ERR_GENERR
  67. SNMP_ERR_NOACCESS
  68. SNMP_ERR_WRONGTYPE
  69. SNMP_ERR_WRONGLENGTH
  70. SNMP_ERR_WRONGENCODING
  71. SNMP_ERR_WRONGVALUE
  72. SNMP_ERR_NOCREATION
  73. SNMP_ERR_INCONSISTENTVALUE
  74. SNMP_ERR_RESOURCEUNAVAILABLE
  75. SNMP_ERR_COMMITFAILED
  76. SNMP_ERR_UNDOFAILED
  77. SNMP_ERR_AUTHORIZATIONERROR
  78. SNMP_ERR_NOTWRITABLE
  79. );
  80. $VERSION = '5.2.2';
  81. sub AUTOLOAD {
  82.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  83.     # XS function.  If a constant is not found then control is passed
  84.     # to the AUTOLOAD in AutoLoader.
  85.     my $constname;
  86.     ($constname = $AUTOLOAD) =~ s/.*:://;
  87.     croak "& not defined" if $constname eq 'constant';
  88.     my $val = constant($constname, @_ ? $_[0] : 0);
  89.     if ($! != 0) {
  90. if ($! =~ /Invalid/ || $!{EINVAL}) {
  91.     $AutoLoader::AUTOLOAD = $AUTOLOAD;
  92.     goto &AutoLoader::AUTOLOAD;
  93. }
  94. else {
  95.     croak "Your vendor has not defined NetSNMP::agent macro $constname";
  96. }
  97.     }
  98.     {
  99. no strict 'refs';
  100. # Fixed between 5.005_53 and 5.005_61
  101. # if ($] >= 5.00561) {
  102. #     *$AUTOLOAD = sub () { $val };
  103. # }
  104. # else {
  105.     *$AUTOLOAD = sub { $val };
  106. # }
  107.     }
  108.     goto &$AUTOLOAD;
  109. }
  110. {
  111.     my $haveinit = 0;
  112.     sub mark_init_agent_done {
  113. $haveinit = 1;
  114.     }
  115.     sub maybe_init_agent {
  116. return if ($haveinit);
  117. $haveinit = 1;
  118. snmp_enable_stderrlog();
  119. my $flags = $_[0];
  120. if ($flags->{'AgentX'}) {
  121.     netsnmp_ds_set_boolean(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_ROLE, 1);
  122. }
  123. init_agent($flags->{'Name'} || "perl");
  124. if ($flags->{'Ports'}) {
  125.     netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_PORTS, $flags->{'Ports'});
  126. }
  127. init_mib();
  128.     }
  129. }
  130. {
  131.     my $haveinit = 0;
  132.     sub mark_init_lib_done {
  133. $haveinit = 1;
  134.     }
  135.     sub maybe_init_lib {
  136. return if ($haveinit);
  137. $haveinit = 1;
  138. my $flags = $_[0];
  139. init_snmp($flags->{'Name'} || "perl");
  140. if (netsnmp_ds_get_boolean(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_ROLE) != 1) {
  141.     init_master_agent();
  142. }
  143.     }
  144. }
  145. sub new {
  146.     my $type = shift;
  147.     my ($self);
  148.     %$self = @_;
  149.     bless($self, $type);
  150.     if ($self->{'dont_init_agent'}) {
  151. $self->mark_init_agent_done();
  152.     } else {
  153. $self->maybe_init_agent();
  154.     }
  155.     if ($self->{'dont_init_lib'}) {
  156. $self->mark_init_lib_done();
  157.     }
  158.     return $self;
  159. }
  160. sub register($$$$) {
  161.     my ($self, $name, $oid, $sub) = @_;
  162.     my $reg = NetSNMP::agent::netsnmp_handler_registration::new($name, $oid, $sub);
  163.     $reg->register() if ($reg);
  164.     return $reg;
  165. }
  166. sub main_loop {
  167.     my $self = shift;
  168.     while(1) {
  169. $self->agent_check_and_process(1);
  170.     }
  171. }
  172. sub agent_check_and_process {
  173.     my ($self, $blocking) = @_;
  174.     $self->maybe_init_lib();
  175.     __agent_check_and_process($blocking || 0);
  176. }
  177. bootstrap NetSNMP::agent $VERSION;
  178. # Preloaded methods go here.
  179. # Autoload methods go after =cut, and are processed by the autosplit program.
  180. 1;
  181. __END__
  182. =head1 NAME
  183. NetSNMP::agent - Perl extension for the net-snmp agent.
  184. =head1 SYNOPSIS
  185.   use NetSNMP::agent;
  186.   my $agent = new NetSNMP::agent('Name' => 'my_agent_name');
  187. =head1 DESCRIPTION
  188. This module implements an API set to make a SNMP agent act as a snmp
  189. agent, a snmp subagent (using the AgentX subagent protocol) and/or
  190. embedded perl-APIs directly within the traditional net-snmp agent demon.
  191. Also see the tutorial about the genaral Net-SNMP C API, which this
  192. module implements in a perl-way, and a perl specific tutorial at:
  193.   http://www.net-snmp.org/tutorial-5/toolkit/
  194. =head1 EXAMPLES
  195. =head2 Sub-agent example
  196.      use NetSNMP::agent (':all');
  197.         my $value = "hello world";
  198. sub myhandler {
  199.     my ($handler, $registration_info, $request_info, $requests) = @_;
  200.     my $request;
  201.     for($request = $requests; $request; $request = $request->next()) {
  202. my $oid = $request->getOID();
  203. if ($request_info->getMode() == MODE_GET) {
  204.     # ... generally, you would calculate value from oid
  205.     if ($oid == new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0")) {
  206. $request->setValue(ASN_OCTET_STR, $value);
  207.     }
  208. } elsif ($request_info->getMode() == MODE_GETNEXT) {
  209.     # ... generally, you would calculate value from oid
  210.     if ($oid < new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0")) {
  211. $request->setOID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0");
  212. $request->setValue(ASN_OCTET_STR, $value);
  213.     }
  214. } elsif ($request_info->getMode() == MODE_SET_RESERVE1) {
  215.     if ($oid != new NetSNMP::OID(".1.3.6.1.4.1.8072.9999.9999.7375.1.0")) {  # do error checking here
  216. $request->setError($request_info, SNMP_ERR_NOSUCHNAME);
  217.     }
  218. } elsif ($request_info->getMode() == MODE_SET_ACTION) {
  219.     # ... (or use the value)
  220.     $value = $request->getValue();
  221. }
  222.     }
  223. }
  224. my $agent = new NetSNMP::agent(
  225. # makes the agent read a my_agent_name.conf file
  226.      'Name' => "my_agent_name",
  227.      'AgentX' => 1
  228.      );
  229. }
  230.      $agent->register("my_agent_name", ".1.3.6.1.4.1.8072.9999.9999.7375",
  231.                          &myhandler);
  232. my $running = 1;
  233. while($running) {
  234.      $agent->agent_check_and_process(1);
  235. }
  236. $agent->shutdown();
  237. =head2 Embedded agent example
  238.         # place this in a .pl file, and then in your snmpd.conf file put:
  239.         #    perl do '/path/to/file.pl';
  240. use NetSNMP::agent;
  241. my $agent;
  242. sub myhandler {
  243.     my ($handler, $registration_info, $request_info, $requests) = @_;
  244.     # ...
  245. }
  246. $agent = new NetSNMP::agent(
  247.      'Name' => 'my_agent_name'
  248.      );
  249.      $agent->register("my_agent_name", ".1.3.6.1.4.1.8072.9999.9999.7375",
  250.                          &myhandler);
  251. $agent->main_loop();
  252. =head1 CONSTRUCTOR
  253.     new ( OPTIONS )
  254. This is the constructor for a new NetSNMP::agent object.
  255.     Possible options are:
  256.      Name - Name of the agent (optional, defaults to "perl")
  257.                   (The snmp library will read a NAME.conf snmp
  258.                   configuration file based on this argument.)
  259.      AgentX - Make us a sub-agent (0 = false, 1 = true)
  260.                   (The Net-SNMP master agent must be running first)
  261.      Ports - Ports this agent will listen on (EG: "udp:161,tcp:161")
  262.     Example:
  263. $agent = new NetSNMP::agent(
  264.       'Name' => 'my_agent_name',
  265.       'AgentX' => 1
  266.       );
  267. =head1 METHODS
  268.     register (NAME, OID, &handler_routine )
  269.      Registers the callback handler with given OID.
  270.      $agent->register();
  271. A return code of 0 indicates no error.
  272.     agent_check_and_process ( BLOCKING )
  273.      Run one iteration of the main loop.
  274.      BLOCKING - Blocking or non-blocking call. 1 = true, 0 = false.
  275.      $agent->agent_check_and_process(1);
  276.     main_loop ()
  277.      Runs the agent in a loop. Does not return.
  278.     shutdown ()
  279. Nicely shuts down the agent or sub-agent.
  280. $agent->shutdown();
  281. =head1 HANDLER CALLBACKS
  282.     handler ( HANDLER, REGISTRATION_INFO, REQUEST_INFO, REQUESTS )
  283.      The handler is called with the following parameters:
  284. HANDLER  - FIXME
  285.      REGISTRATION_INFO  - what are the correct meanings of these?
  286.      REQUEST_INFO -
  287.      REQUESTS -
  288.     Example handler:
  289. sub myhandler {
  290.     my ($handler, $reg_info, $request_info, $requests) = @_;
  291.     # ...
  292. }
  293. The handler subroutine will be called when a SNMP request received by
  294. the agent for anything below the registered OID.  The handler is
  295. passed 4 arguments: $handler, $registration_info, $request_info,
  296. $requests.  These match the arguments passed to the C version of the
  297. same API.  Note that they are not entirely complete objects but are
  298. functional "enough" at this point in time.
  299. =head2 $request_info object functions
  300.     getMode ()
  301.      Returns the mode of the request. See the MODES section for
  302.      list of valid modes.
  303. $mode = $request->getMode();
  304.     getRootOID ()
  305. Returns a NetSNMP::OID object that describes the registration
  306. point that the handler is getting called for (in case you
  307. register one handler function with multiple OIDs, which should
  308. be rare anyway)
  309.      $root_oid = $request->getRootOID();
  310. =head2 $request object functions
  311.     next ()
  312.      Returns the next request in the list or undef if there is no
  313.      next request.
  314.      $request = $request->next();
  315.     getOID ()
  316. Returns the oid of the request (a NetSNMP::OID class).
  317. $oid = $request->getOID();
  318.     setOID (new NetSNMP::OID("someoid"))
  319. Sets the OID of the request to a passed oid value.  This
  320. should generally only be done during handling of GETNEXT
  321. requests.
  322. $request->setOID(new NetSNMP::OID("someoid"));
  323.     getValue ()
  324. Returns the value of the request. Used for example when
  325. setting values.
  326.      $value = $request->getValue();
  327.      FIXME: how to get the type of the value? Is it even available?
  328.                [Wes: no, not yet.]
  329.     setValue ( TYPE, DATA )
  330. Sets the data to be returned to the daemon.
  331.      Returns 1 on success, 0 on error.
  332.      TYPE - Type of the data. See NetSNMP::ASN for valid types.
  333.      DATA - The data to return.
  334. $ret = $request->setValue(ASN_OCTET_STR, "test");
  335.     setError ( REQUEST_INFO, ERROR_CODE )
  336. Sets the given error code for the request. See the ERROR CODES
  337. section for list of valid codes.
  338.      $request->setError($request_info, SNMP_ERR_NOTWRITABLE);
  339.     getProcessed ()
  340.      The processed flag indicates that a request does not need to
  341.      be dealt with because someone else (a higher handler) has
  342.      dealt with it already.
  343.      $processed = $request->getProcessed();
  344.     setProcessed ( PROCESSED )
  345. Sets the processed flag flag in the request.  You generally
  346. should not have to set this yourself.
  347. PROCESSED - 0 = false, 1 = true
  348. $request->setProcessed(1);
  349.     getDelegated ()
  350. If you can handle a request in the background or at a future
  351. time (EG, you're waiting on a file handle, or network traffic,
  352. or ...), the delegated flag can be set in the request.  When
  353. the request is processed in the future the flag should be set
  354. back to 0 so the agent will know that it can wrap up the
  355. original request and send it back to the manager.  This has
  356. not been tested within perl, but it hopefully should work.
  357. $delegated = $request->getDelegated();
  358.     setDelegated ( DELEGATED )
  359.      Sets the delegated flag.
  360.      DELEGATED - 0 = false, 1 = true
  361.      $request->setDelegated(1);
  362.     getRepeat ()
  363. The repeat flag indicates that a getbulk operation is being
  364. handled and this indicates how many answers need to be
  365. returned.  Generally, if you didn't register to directly
  366. handle getbulk support yourself, you won't need to deal with
  367. this value.
  368.      $repeat = $request->getRepeat();
  369.     setRepeat ( REPEAT )
  370. Sets the repeat count (decrement after answering requests if
  371. you handle getbulk requests yourself)
  372. REPEAT -  repeat count FIXME
  373. $request->setRepeat(5);
  374. =head1 MODES
  375. MODE_GET
  376. MODE_GETBULK
  377. MODE_GETNEXT
  378. MODE_SET_ACTION
  379. MODE_SET_BEGIN
  380. MODE_SET_COMMIT
  381. MODE_SET_FREE
  382. MODE_SET_RESERVE1
  383. MODE_SET_RESERVE2
  384. MODE_SET_UNDO
  385. =head1 ERROR CODES
  386. SNMP_ERR_NOERROR
  387. SNMP_ERR_TOOBIG
  388. SNMP_ERR_NOSUCHNAME
  389. SNMP_ERR_BADVALUE
  390. SNMP_ERR_READONLY
  391. SNMP_ERR_GENERR
  392. SNMP_ERR_NOACCESS
  393. SNMP_ERR_WRONGTYPE
  394. SNMP_ERR_WRONGLENGTH
  395. SNMP_ERR_WRONGENCODING
  396. SNMP_ERR_WRONGVALUE
  397. SNMP_ERR_NOCREATION
  398. SNMP_ERR_INCONSISTENTVALUE
  399. SNMP_ERR_RESOURCEUNAVAILABLE
  400. SNMP_ERR_COMMITFAILED
  401. SNMP_ERR_UNDOFAILED
  402. SNMP_ERR_AUTHORIZATIONERROR
  403. SNMP_ERR_NOTWRITABLE
  404. =head1 AUTHOR
  405. Please mail the net-snmp-users@lists.sourceforge.net mailing list for
  406. help, questions or comments about this module.
  407. Module written by:
  408.    Wes Hardaker  <hardaker@users.sourceforge.net>
  409. Documentation written by:
  410.    Toni Willberg <toniw@iki.fi>
  411.    Wes Hardaker  <hardaker@users.sourceforge.net>
  412. =head1 SEE ALSO
  413. NetSNMP::OID(3), NetSNMP::ASN(3), perl(1).
  414. =cut