snmptrapd.conf - configuration file for the Net-SNMP notification
receiver
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.
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.
- 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.
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.
- 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.
- 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.
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.
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.
- 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.