'\" te
.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TrapReceiver 3"
.TH TrapReceiver 3 "2007-05-22" "perl v5.12.5" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
NetSNMP::TrapReceiver \- Embedded perl trap handling for Net\-SNMP's snmptrapd
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Put the following lines in your snmptrapd.conf file:
.PP
.Vb 1
\&  perl NetSNMP::TrapReceiver::register("trapOID", \e&myfunc);
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
The NetSNMP::TrapReceiver module is used to register perl
subroutines into the Net-SNMP snmptrapd process.  Net-SNMP \s-1MUST\s0 have
been configured using \-\-enable\-embedded\-perl.  Registration of
functions is then done through the snmptrapd.conf configuration
file.  This module can \s-1NOT\s0 be used in a normal perl script to
receive traps.  It is intended solely for embedded use within the
snmptrapd demon.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Within the snmptrapd.conf file, the keyword \*(L"perl\*(R" 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 \s-1SNMP\s0 protocol was used, where
it came from, what \s-1SNMP\s0 user name or community name it was sent under,
etc).  The second argument is a reference to an array containing the
variable bindings (\s-1OID\s0 and value information) that define the
noification itself.  Each variable is itself a reference to an array
containing three values: a NetSNMP::OID object, the value that came
associated with it, and the value's numeric type (see NetSNMP::ASN for
further details on \s-1SNMP\s0 typing information).
.PP
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 \*(L"linkUp\*(R" or
\&\*(L"MyMIB::MyTrap\*(R" or \*(L".1.3.6.1.4.1.2021....\*(R").  Two special keywords can
be used in place of an \s-1OID:\s0 \*(L"default\*(R" and \*(L"all\*(R".  The \*(L"default\*(R"
keyword indicates you want your handler to be called in the case where
no other handlers are called.  The \*(L"all\*(R" keyword indicates that the
handler should \s-1ALWAYS\s0 be called for every notification.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
As an example, put the following code into a file (say
\&\*(L"/usr/local/share/snmp/mytrapd.pl\*(R"):
.PP
.Vb 1
\&  #!/usr/bin/perl
\&
\&  sub my_receiver {
\&      print "********** PERL RECEIVED A NOTIFICATION:\en";
\&
\&      # print the PDU info (a hash reference)
\&      print "PDU INFO:\en";
\&      foreach my $k(keys(%{$_[0]})) {
\&        printf "  %\-30s %s\en", $k, $_[0]{$k};
\&      }
\&
\&      # print the variable bindings:
\&      print "VARBINDS:\en";
\&      foreach my $x (@{$_[1]}) { 
\&          printf "  %\-30s type=%\-2d value=%s\en", $x\->[0], $x\->[2], $x\->[1]; 
\&      }
\&  }
\&
\&  NetSNMP::TrapReceiver::register("all", \e&my_receiver) || 
\&    warn "failed to register our perl trap handler\en";
\&
\&  print STDERR "Loaded the example perl snmptrapd handler\en";
.Ve
.PP
Then, put the following line in your snmprapd.conf file:
.PP
.Vb 1
\&  perl do "/usr/local/share/snmp/mytrapd.pl";
.Ve
.PP
Start snmptrapd (as root, and the following other opions make it stay
in the foreground and log to stderr):
.PP
.Vb 1
\&  snmptrapd \-f \-Le
.Ve
.PP
You should see it start up and display the final message from the end
of the above perl script:
.PP
.Vb 2
\&  Loaded the perl snmptrapd handler
\&  2004\-02\-11 10:08:45 NET\-SNMP version 5.2 Started.
.Ve
.PP
Then, if you send yourself a fake trap using the following example command:
.PP
.Vb 2
\&  snmptrap \-v 2c \-c mycommunity localhost 0 linkUp ifIndex.1 i 1 \e
\&      ifAdminStatus.1 i up ifOperStatus.1 i up ifDescr s eth0
.Ve
.PP
You should see the following output appear from snmptrapd as your perl
code gets executed:
.PP
.Vb 10
\&  ********** 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"
.Ve
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.PP
# =head2 Exportable constants
.PP
#   \s-1NETSNMPTRAPD_AUTH_HANDLER\s0
#   \s-1NETSNMPTRAPD_HANDLER_BREAK\s0
#   \s-1NETSNMPTRAPD_HANDLER_FAIL\s0
#   \s-1NETSNMPTRAPD_HANDLER_FINISH\s0
#   \s-1NETSNMPTRAPD_HANDLER_OK\s0
#   \s-1NETSNMPTRAPD_POST_HANDLER\s0
#   \s-1NETSNMPTRAPD_PRE_HANDLER\s0

.\" Oracle has added the ARC stability level to this manual page
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE 
=
Availability	system/management/snmp/net-snmp
=
Stability	Volatile
.TE 
.PP
.SH "SEE ALSO"
.IX Header "SEE ALSO"
NetSNMP::OID, NetSNMP::ASN
.PP
\&\fIsnmptrapd.conf\fR\|(5) for configuring the Net-SNMP trap receiver.
.PP
\&\fIsnmpd.conf\fR\|(5) for configuring the Net-SNMP snmp agent for sending traps.
.PP
http://www.Net\-SNMP.org/
.SH "AUTHOR"
.IX Header "AUTHOR"
W. Hardaker, <hardaker@users.sourceforge.net>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2004 by W. Hardaker
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.


.SH NOTES

.\" Oracle has added source availability information to this manual page
This software was built from source available at https://java.net/projects/solaris-userland.  The original community source was downloaded from  http://ftp.ntua.gr/mirror/net-snmp/OldFiles/net-snmp-5.4.x/5.4.1/net-snmp-5.4.1.tar.gz

Further information about this software can be found on the open source community website at http://www.net-snmp.org/.