.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "TrapReceiver 3pm"
.TH TrapReceiver 3pm "2021-01-28" "perl v5.28.1" "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
Registered functions should return one of the following values:
.IP "\s-1NETSNMPTRAPD_HANDLER_OK\s0" 2
.IX Item "NETSNMPTRAPD_HANDLER_OK"
Handling the trap succeeded, but lets the snmptrapd demon check for
further appropriate handlers.
.IP "\s-1NETSNMPTRAPD_HANDLER_FAIL\s0" 2
.IX Item "NETSNMPTRAPD_HANDLER_FAIL"
Handling the trap failed, but lets the snmptrapd demon check for
further appropriate handlers.
.IP "\s-1NETSNMPTRAPD_HANDLER_BREAK\s0" 2
.IX Item "NETSNMPTRAPD_HANDLER_BREAK"
Stops evaluating the list of handlers for this specific trap, but lets
the snmptrapd demon apply global handlers.
.IP "\s-1NETSNMPTRAPD_HANDLER_FINISH\s0" 2
.IX Item "NETSNMPTRAPD_HANDLER_FINISH"
Stops searching for further appropriate handlers.
.PP
If a handler function does not return anything appropriate or even
nothing at all, a return value of \s-1NETSNMPTRAPD_HANDLER_OK\s0 is assumed.
.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]})) {
\&        if ($k eq "securityEngineID" || $k eq "contextEngineID") {
\&          printf "  %\-30s 0x%s\en", $k, unpack(\*(Aqh*\*(Aq, $_[0]{$k});
\&        }
\&        else {
\&          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
.SH "SEE ALSO"
.IX Header "SEE ALSO"
NetSNMP::OID, NetSNMP::ASN
.PP
\&\fBsnmptrapd.conf\fR\|(5) for configuring the Net-SNMP trap receiver.
.PP
\&\fBsnmpd.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.