snmptrapd.conf - configuration file for the Net-SNMP notification receiver
DESCRIPTION
The Net-SNMP notification receiver (trap daemon) uses one or more
configuration files to control its operation and how incoming traps
(and INFORM requests) should be processed.
This file (snmptrapd.conf) can be located in
one of several locations, as described in the
snmp_config(5)
manual page.
IMPORTANT
Previously,
snmptrapd
would accept all incoming notifications, and log them automatically
(even if no explicit configuration was provided).
Starting with release 5.3, access control checks will be applied to
incoming notifications. If
snmptrapd
is run without a suitable configuration file (or equivalent access
control settings), then such traps WILL NOT
be processed.
See the section ACCESS CONTROL for more details.
As with the agent configuration, the
snmptrapd.conf
directives can be divided into four distinct groups.
defines a list of listening addresses, on which to receive
incoming SNMP notifications.
See the section
LISTENING ADDRESSES
in the
snmpd(8)
manual page for more information about the format of listening
addresses.
The default behaviour is to
listen on UDP port 162 on all IPv4 interfaces.
doNotRetainNotificationLogs yes
disables support for the NOTIFICATION-LOG-MIB.
Normally the snmptrapd program keeps a record of the traps
received, which can be retrieved by querying
the nlmLogTable and nlmLogvariableTable tables.
This directive can be used to suppress this behaviour.
See the
snmptrapd(8)
manual page and the NOTIFICATION-LOG-MIB for details.
doNotLogTraps yes
disables the logging of notifications altogether.
This is useful if the snmptrapd application should
only run traphandle hooks and should not log traps to any location.
doNotFork yes
do not fork from the calling shell.
pidFile PATH
defines a file in which to store the process ID of the
notification receiver. By default, this ID is not saved.
ACCESS CONTROL
Starting with release 5.3, it is necessary to explicitly specify
who is authorised to send traps and informs to the notification
receiver (and what types of processing these are allowed to trigger).
This uses an extension of the VACM model, used in the main SNMP agent.
There are currently three types of processing that can be specified:
log
log the details of the notification - either in a specified file,
to standard output (or stderr), or via syslog (or similar).
execute
pass the details of the trap to a specified handler program, including
embedded perl.
net
forward the trap to another notification receiver.
In the following directives, TYPES will be a (comma-separated)
list of one or more of these tokens. Most commonly, this will
typically be log,execute,net to cover any style of processing
for a particular category of notification. But it is perfectly
possible (even desirable) to limit certain notification sources to
selected processing only.
authCommunity TYPES COMMUNITY [SOURCE [OID | -v VIEW ]]
authorises traps (and SNMPv2c INFORM requests) with the specified
community to trigger the types of processing listed.
By default, this will allow any notification using this community
to be processed. The SOURCE field can be used to specify that the
configuration should only apply to notifications received from
particular sources - see snmpd.conf(5) for more details.
authorises SNMPv3 notifications with the specified
user to trigger the types of processing listed.
By default, this will accept authenticated requests.
(authNoPriv or authPriv). The LEVEL field can
be used to allow unauthenticated notifications (noauth),
or to require encryption (priv), just as for the SNMP agent.
With both of these directives, the OID (or -v VIEW) field
can be used to retrict this configuration to the processing of
particular notifications.
Note:
Unlike the VACM processing described in RFC 3415, this view is
only matched against the snmpTrapOID value of the
incoming notification. It is not applied to the payload varbinds
held within that notification.
authAccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
setAccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
authorise notifications in the specified GROUP
(configured using the group directive)
to trigger the types of processing listed.
See snmpd.conf(5) for more details.
See the
snmpd.conf(5)
manual page for a description of how to create SNMPv3 users. This
is roughly the same, but the file name changes to snmptrapd.conf from
snmpd.conf.
disableAuthorization yes
will disable the above access control checks, and revert to the
previous behaviour of accepting all incoming notifications.
LOGGING
format1 FORMAT
format2 FORMAT
specify the format used to display SNMPv1 TRAPs and SNMPv2
notifications respectively. Note that SNMPv2c and SNMPv3
both use the same SNMPv2 PDU format.
See
snmptrapd(8)
for the layout characters available.
ignoreAuthFailure yes
instructs the receiver to ignore authenticationFailure traps.
Note:
This currently only affects the logging of such notifications.
authenticationFailure traps will still be passed to trap
handler scripts, and forwarded to other notification receivers.
This behaviour should not be relied on, as it is likely
to change in future versions.
logOption string
specifies where notifications should be logged - to standard
output, standard error, a specified file or via syslog.
See the section LOGGING OPTIONS in the
snmpcmd(1) manual page for details.
outputOption string
specifies various characteristics of how OIDs and other values
should be displayed.
See the section OUTPUT OPTIONS in the
snmpcmd(1) manual page for details.
printEventNumbers yes
enables specialised logging of event-related notifications from
the (long obsolete) M2M-MIB.
NOTIFICATION PROCESSING
As well as logging incoming notifications, they can also
be forwarded on to another notification receiver, or passed
to an external program for specialised processing.
traphandle OID|default PROGRAM [ARGS ...]
invokes the specified program (with the given arguments) whenever a
notification is received with a snmpTrapOID value matching the
OID token. If this field is default then the program will be
invoked for any notification not matching another (OID specific)
traphandle entry.
Note:
An SNMPv1 trap will be converted to an equivalent SNMPv2-style
notification (following RFC 2576), before selecting the trap
handler(s) to call. This will affect both the OIDs listed
in traphandle entries, and the format of the data passed
to the trap handler program.
The program is fed details about the notification to its standard input,
in the following format, one entry per line:
HOSTNAME
The name of the host that sent the notification, as determined by
gethostbyaddr(3).
IPADDRESS
The IP address of the host that sent the notification.
VARBINDS
A list of variable bindings describing the contents of the notification,
one per line. The first token on each line (up until a space) is the
OID of the varind, and the remainder of the line is its value.
The format of both of these are controlled by the outputOption
directive (or similar configuration).
The first OID should always be SNMPv2-MIB::sysUpTime.0,
and the second should be SNMPv2-MIB::snmpTrapOID.0.
The remaining lines will contain the payload varbind list.
For SNMPv1 traps, the final OID will be SNMPv2-MIB::snmpTrapEnterprise.0.
Example:
A traptoemail script has been included in the Net-SNMP package that
can be used within a traphandle directive:
forwards notifications that match the specified OID
to another receiver listening on DESTINATION.
The interpretation of OID (and default) is the same
as for the traphandle directive).
See the section
LISTENING ADDRESSES
in the
snmpd(8)
manual page for more information about the format of listening
addresses.
NOTES
o
The daemon blocks while executing the traphandle commands.
(This should
be fixed in the future with an appropriate signal catch and wait()
combination).
o
All directives listed with a value of "yes" actually accept a range
of boolean values. These will accept any of 1, yes or
true to enable the corresponding behaviour,
or any of 0, no or false to disable it.
The default in each case is for the feature to be turned off, so these
directives are typically only used to enable the appropriate behaviour.
