Provided by: snmptrapd_5.9.3+dfsg-2ubuntu3_amd64 
NAME
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.
TRAPD BEHAVIOUR
snmpTrapdAddr [<transport-specifier>:]<transport-address>[,...]
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.
authUser TYPES [-s MODEL] USER [LEVEL [OID | -v VIEW ]]
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.
authGroup TYPES [-s MODEL] GROUP [LEVEL [OID | -v VIEW ]]
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.
createUser [-e ENGINEID] username (MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224)
authpassphrase [DES|AES]
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.
format DESTINATION FORMAT
specify the format used for different destinations. DESTINATION is one of: print,
print1, print2, syslog, syslog1, syslog2, execute, execute1, execute2. print1 is
used for printing SNMPv1 traps, print2 is for SNMPv2. print is used for both
versions. syslog is similarly used when sending traps to syslog, and execute used
when sending traps to a program such as traptoemail(1).
The default formats are
format print1 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b] (via %A [%a]): %N\n\t%W Trap
(%q) Uptime: %#T\n%v\n
format print2 %.4y-%.2m-%.2l %.2h:%.2j:%.2k %B [%b]:\n%v\n
format syslog1 %a: %W Trap (%q) Uptime: %#T%#v\n
format syslog2 %B [%b]: Trap %#v\n
format execute %B\n%b\n%V\n%v\n
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.
MySQL Logging
There are two configuration variables that work together to control when queued traps are
logged to the MySQL database. A non-zero value must be specified for sqlSaveInterval to
enable MySQL logging.
sqlMaxQueue max
specifies the maximum number of traps to queue before a forced flush to the MySQL
database.
sqlSaveInterval seconds
specified the number of seconds between periodic queue flushes. A value of 0 for
will disable MySQL logging.
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 that matches the OID token. For SNMPv2c and SNMPv3 notifications, this
token will be compared against the snmpTrapOID value taken from the notification.
For SNMPv1 traps, the generic and specific trap values and the enterprise OID will
be converted into the equivalent OID (following RFC 2576).
Typically, the OID token will be the name (or numeric OID) of a NOTIFICATION-TYPE
object, and the specified program will be invoked for notifications that match this
OID exactly. However this token also supports a simple form of wildcard suffixing.
By appending the character ยด*' to the OID token, the corresponding program will be
invoked for any notification based within subtree rooted at the specified OID. For
example, an OID token of .1.3.6.1.4.1* would match any enterprise specific
notification (including the specified OID itself). An OID token of .1.3.6.1.4.1.*
would would work in much the same way, but would not match this exact OID - just
notifications that lay strictly below this root. Note that this syntax does not
support full regular expressions or wildcards - an OID token of the form
oid.*.subids is not valid.
If the OID field is the token default then the program will be invoked for any
notification not matching another (OID specific) traphandle entry.
Details of the notification are fed to the program via its standard input. Note that this
will always use the SNMPv2-style notification format, with SNMPv1 traps being converted as
per RFC 2576, before being passed to the program. The input format is, if you use the
default set by the "format execute %B\n%b\n%V\n%v\n", one entry per line:
HOSTNAME
The name of the host that sent the notification, as determined by
gethostbyaddr(3).
ADDRESS
The transport address, like
"[UDP: [172.16.10.12]:23456->[10.150.0.8]]"
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:
traphandle default /usr/bin/perl /usr/bin/traptoemail -s
mysmtp.somewhere.com -f admin@somewhere.com me@somewhere.com
forward OID|default DESTINATION
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.
addForwarderInfo 1|yes|true|0|no|false
Each time a trap is forwarded, add an OID with the IP address of the system from
which the trap has been received. The following OID is added: .1.3.6.1.6.3.18.1.3.x
(SNMP-COMMUNITY-MIB::snmpTrapAddress.x) where x is the lowest index >= 0 that does
not yet occur in the trap payload. The end recipient (i.e. the monitoring system)
can determine the IPv4 address of the original sender by looking for the varbind
with OID snmpTrapAddress.0. If that OID is not populated it means that the trap has
been sent directly or in other words that it has not been forwarded.
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.
FILES
/etc/snmp/snmptrapd.conf
SEE ALSO
snmp_config(5), snmptrapd(8), syslog(8), traptoemail(1), variables(5),
netsnmp_config_api(3).