Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TrapReceiver(3)	      User Contributed Perl Documentation      TrapReceiver(3)

NAME
       NetSNMP::TrapReceiver - Embedded	perl trap handling for Net-SNMP's
       snmptrapd

SYNOPSIS
       Put the following lines in your snmptrapd.conf file:

	 perl NetSNMP::TrapReceiver::register("trapOID", \&myfunc);

ABSTRACT
       The NetSNMP::TrapReceiver module	is used	to register perl subroutines
       into the	Net-SNMP snmptrapd process.  Net-SNMP MUST have	been
       configured using	--enable-embedded-perl.	 Registration of functions is
       then done through the snmptrapd.conf configuration file.	 This module
       can NOT be used in a normal perl	script to receive traps.  It is
       intended	solely for embedded use	within the snmptrapd demon.

DESCRIPTION
       Within the snmptrapd.conf file, the keyword "perl" may be used to call
       any perl	expression and using this ability, you can use the
       NetSNMP::TrapReceiver module to register	functions which	will be	called
       every time a given notification (a trap or an inform) is	received.
       Registered functions are	called with 2 arguments.  The first is a
       reference to a hash containing information about	how the	trap was
       received	(what version of the SNMP protocol was used, where it came
       from, what SNMP user name or community name it was sent under, etc).
       The second argument is a	reference to an	array containing the variable
       bindings	(OID and value information) that define	the noification
       itself.	Each variable is itself	a reference to an array	containing
       four values: a NetSNMP::OID object, a string representation of the
       value that came associated with it, the value's numeric type (see
       NetSNMP::ASN for	further	details	on SNMP	typing information), and the
       raw value of the	trap, encoded according	to its type, 64-bit integer
       types are returned as strings, integer types as integers, strings as
       strings,	object identifiers as NetSNMP::OID objects, and	any other
       types as	undefs.

       Registered functions should return one of the following values:

       NETSNMPTRAPD_HANDLER_OK
	 Handling the trap succeeded, but lets the snmptrapd demon check for
	 further appropriate handlers.

       NETSNMPTRAPD_HANDLER_FAIL
	 Handling the trap failed, but lets the	snmptrapd demon	check for
	 further appropriate handlers.

       NETSNMPTRAPD_HANDLER_BREAK
	 Stops evaluating the list of handlers for this	specific trap, but
	 lets the snmptrapd demon apply	global handlers.

       NETSNMPTRAPD_HANDLER_FINISH
	 Stops searching for further appropriate handlers.

       If a handler function does not return anything appropriate or even
       nothing at all, a return	value of NETSNMPTRAPD_HANDLER_OK is assumed.

       Subroutines are registered using	the NetSNMP::TrapReceiver::register
       function, which takes two arguments.  The first is a string describing
       the notification	you want to register for (such as "linkUp" or
       "MyMIB::MyTrap" or ".1.3.6.1.4.1.2021....").  Two special keywords can
       be used in place	of an OID: "default" and "all".	 The "default" keyword
       indicates you want your handler to be called in the case	where no other
       handlers	are called.  The "all" keyword indicates that the handler
       should ALWAYS be	called for every notification.

EXAMPLE
       As an example, put the following	code into a file (say
       "/usr/local/share/snmp/mytrapd.pl"):

	 #!/usr/bin/perl

	 sub my_receiver {
	     print "********** PERL RECEIVED A NOTIFICATION:\n";

	     # print the PDU info (a hash reference)
	     print "PDU	INFO:\n";
	     foreach my	$k(keys(%{$_[0]})) {
	       if ($k eq "securityEngineID" || $k eq "contextEngineID")	{
		 printf	"  %-30s 0x%s\n", $k, unpack('h*', $_[0]{$k});
	       }
	       else {
		 printf	"  %-30s %s\n",	$k, $_[0]{$k};
	       }
	     }

	     # print the variable bindings:
	     print "VARBINDS:\n";
	     foreach my	$x (@{$_[1]}) {
		 printf	"  %-30s type=%-2d value=%s\n",	$x->[0], $x->[2], $x->[1];
	     }
	 }

	 NetSNMP::TrapReceiver::register("all",	\&my_receiver) ||
	   warn	"failed	to register our	perl trap handler\n";

	 print STDERR "Loaded the example perl snmptrapd handler\n";

       Then, put the following line in your snmprapd.conf file:

	 perl do "/usr/local/share/snmp/mytrapd.pl";

       Start snmptrapd (as root, and the following other opions	make it	stay
       in the foreground and log to stderr):

	 snmptrapd -f -Le

       You should see it start up and display the final	message	from the end
       of the above perl script:

	 Loaded	the perl snmptrapd handler
	 2004-02-11 10:08:45 NET-SNMP version 5.2 Started.

       Then, if	you send yourself a fake trap using the	following example
       command:

	 snmptrap -v 2c	-c mycommunity localhost 0 linkUp ifIndex.1 i 1	\
	     ifAdminStatus.1 i up ifOperStatus.1 i up ifDescr s	eth0

       You should see the following output appear from snmptrapd as your perl
       code gets executed:

	 ********** PERL RECEIVED A NOTIFICATION:
	 PDU INFO:
	   notificationtype		  TRAP
	   receivedfrom			  127.0.0.1
	   version			  1
	   errorstatus			  0
	   messageid			  0
	   community			  mycommunity
	   transactionid		  2
	   errorindex			  0
	   requestid			  765160220
	 VARBINDS:
	   sysUpTimeInstance		  type=67 value=0:0:00:00.00
	   snmpTrapOID.0		  type=6  value=linkUp
	   ifIndex.1			  type=2  value=1
	   ifAdminStatus.1		  type=2  value=1
	   ifOperStatus.1		  type=2  value=1
	   ifDescr			  type=4  value="eth0"

   Passing Arguments
       If you need to pass arguments in	to the script, you'll need to do it by
       one of two methods:

       Using Subroutines

       You can either define a subroutine in the file rather than have the
       file itself do something.  IE, in the file if you put:

	 sub foo {
	    print "$_[0]\n";
	 }

       and then	put these lines	in the snmptrapd.conf file:

	 perl do /path/to/script
	 perl foo("hello world");
	 perl foo("now I am passing something different");

       It'd call the foo function twice, and print the results to the console
       where snmptrapd was started.

       Using Variables

       Or you could always set a variable ahead	of time:

	 perl $myVariable = 42;
	 perl do /path/to/script

       And have	the script look	for and	use the	$myVariable value in the
       script

EXPORT
       None by default.

   Exportable constants
	 NETSNMPTRAPD_AUTH_HANDLER
	 NETSNMPTRAPD_HANDLER_BREAK
	 NETSNMPTRAPD_HANDLER_FAIL
	 NETSNMPTRAPD_HANDLER_FINISH
	 NETSNMPTRAPD_HANDLER_OK
	 NETSNMPTRAPD_POST_HANDLER
	 NETSNMPTRAPD_PRE_HANDLER

SEE ALSO
       NetSNMP::OID, NetSNMP::ASN

       snmptrapd.conf(5) for configuring the Net-SNMP trap receiver.

       snmpd.conf(5) for configuring the Net-SNMP snmp agent for sending
       traps.

       http://www.Net-SNMP.org/

AUTHOR
       W. Hardaker, <hardaker@users.sourceforge.net>

COPYRIGHT AND LICENSE
       Copyright 2004 by W. Hardaker

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2020-08-14		       TrapReceiver(3)

NAME | SYNOPSIS | ABSTRACT | DESCRIPTION | EXAMPLE | EXPORT | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=NetSNMP::TrapReceiver&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help