제7장 SNMP
2. man snmpd.conf
NAME
snmpd.conf - configuration file for the Net-SNMP SNMP agent
DESCRIPTION
The Net-SNMP agent uses one or more configuration files to control its
operation and the management information provided. These files
(snmpd.conf and snmpd.local.conf) can be located in one of several
locations, as described in the snmp_config(5) manual page.
The (perl) application snmpconf can be used to generate configuration
files for the most common agent requirements. See the snmpconf(1) man-
ual page for more information, or try running the command:
snmpconf -g basic_setup
There are a large number of directives that can be specified, but these
mostly fall into four distinct categories:
· those controlling who can access the agent
· those configuring the information that is supplied by the agent
· those controlling active monitoring of the local system
· those concerned with extending the functionality of the agent.
Some directives don’t fall naturally into any of these four categories,
but this covers the majority of the contents of a typical snmpd.conf
file. A full list of recognised directives can be obtained by running
the command:
snmpd -H
AGENT BEHAVIOUR
Although most configuration directives are concerned with the MIB
information supplied by the agent, there are a handful of directives
that control the behaviour of snmpd considered simply as a daemon pro-
viding a network service.
agentaddress [:][,...]
defines a list of listening addresses, on which to receive
incoming SNMP requests. 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 161 on all IPv4
interfaces.
agentgroup {GROUP|#GID}
changes to the specified group after opening the listening
port(s). This may refer to a group by name (GROUP), or a
numeric group ID starting with ’#’ (#GID).
agentuser {USER|#UID}
changes to the specified user after opening the listening
port(s). This may refer to a user by name (USER), or a numeric
user ID starting with ’#’ (#UID).
leave_pidfile yes
instructs the agent to not remove its pid file on shutdown.
Equivalent to specifying "-U" on the command line.
maxGetbulkRepeats NUM
Sets the maximum number of responses allowed for a single vari-
able in a getbulk request. Set to 0 to enable the default and
set it to -1 to enable unlimited. Because memory is allocated
ahead of time, sitting this to unlimited is not considered safe
if your user population can not be trusted. A repeat number
greater than this will be truncated to this value.
This is set by default to -1.
maxGetbulkResponses NUM
Sets the maximum number of responses allowed for a getbulk
request. This is set by default to 100. Set to 0 to enable the
default and set it to -1 to enable unlimited. Because memory is
allocated ahead of time, sitting this to unlimited is not con-
sidered safe if your user population can not be trusted.
In general, the total number of responses will not be allowed to
exceed the maxGetbulkResponses number and the total number
returned will be an integer multiple of the number of variables
requested times the calculated number of repeats allow to fit
below this number.
Also not that processing of maxGetbulkRepeats is handled first.
SNMPv3 Configuration - Real Security
SNMPv3 is added flexible security models to the SNMP packet structure
so that multiple security solutions could be used. SNMPv3 was original
defined with a "User-based Security Model" (USM) [RFC3414] that
required maintaining a SNMP-specific user database. This was later
determined to be troublesome to maintain and had some minor security
issues. The IETF has since added additional security models to tunnel
SNMP over SSH [RFC5592] and DTLS/TLS [RFC-to-be]. Net-SNMP contains
robust support for SNMPv3/USM, SNMPv3/TLS, and SNMPv3/DTLS. It con-
tains partial support for SNMPv3/SSH as well but has not been as exten-
sively tested. It also contains code for support for an experimental
Kerberos based SNMPv3 that never got standardized.
Hopefully more SNMP software and devices will eventually support SNMP
over (D)TLS or SSH, but it is likely that devices with original support
for SNMP will only contain support for USM users. If your network man-
ager supports SNMP over (D)TLS or SNMP over SSH we suggest you use one
of these mechanisms instead of using USM, but as always with Net-SNMP
we give you the options to pick from so you can make the choice that is
best for you.
SNMPv3 generic parameters
These parameters are generic to all the forms of SNMPv3. The SNMPv3
protocol defines "engineIDs" that uniquely identify an agent. The
string must be consistent through time and should not change or con-
flict with another agent’s engineID. Ever. Internally, Net-SNMP by
default creates a unique engineID that is based off of the current sys-
tem time and a random number. This should be sufficient for most users
unless you’re embedding our agent in a device where these numbers won’t
vary between boxes on the devices initial boot.
EngineIDs are used both as a "context" for selecting information
from the device and SNMPv3 with USM uses it to create unique
entries for users in its user table.
The Net-SNMP agent offers the following mechanisms for setting
the engineID, but again you should only use them if you know
what you’re doing:
engineID STRING
specifies that the engineID should be built from the given text
STRING.
engineIDType 1|2|3
specifies that the engineID should be built from the IPv4
address (1), IPv6 address (2) or MAC address (3). Note that
changing the IP address (or switching the network interface
card) may cause problems.
engineIDNic INTERFACE
defines which interface to use when determining the MAC address.
If engineIDType 3 is not specified, then this directive has no
effect.
The default is to use eth0.
SNMPv3 over TLS
SNMPv3 may be tunneled over TLS and DTLS. TLS runs over TCP and DTLS
is the UDP equivalent. Wes Hardaker (the founder of Net-SNMP) per-
formed a study and presented it at an IETF meeting that showed that TCP
based protocols are sufficient for stable networks but quickly becomes
a problem in unstable networks with even moderate levels of packet loss
(~ 20-30%). If you are going to use TLS or DTLS, you should use the
one appropriate for your networking environment. You should poten-
tially turn them both on so your management system can access either
the UDP or the TCP port as needed.
Many of the configuration tokens described below are prefixed with a
’[snmp]’ tag. If you place these tokens in your snmpd.conf file, this
take is required. See the snmp_config(5) manual page for the meaning
of this context switch.
[snmp] localCert
This token defines the default X.509 public key to use as the
server’s identity. It should either be a fingerprint or a file-
name. To create a public key for use, please run the
"net-snmp-cert" utility which will help you create the required
certificate.
The default value for this is the certificate in the "snmpd"
named certificate file.
[snmp] tlsAlgorithms
This string will select the algorithms to use when negotiating
security during (D)TLS session establishment. See the openssl
manual page ciphers(1) for details on the format. Examples
strings include:
DEFAULT
ALL
HIGH
HIGH:!AES128-SHA
The default value is whatever openssl itself was configured
with.
[snmp] x059CRLFile
If you are using a Certificate Authority (CA) that publishes a
Certificate Revocation List (CRL) then this token can be used to
specify the location in the filesystem of a copy of the CRL
file. Note that Net-SNMP will not pull a CRL over http and this
must be a file, not a URL. Additionally, OpenSSL does not
reload a CRL file when it has changed so modifications or
updates to the file will only be noticed upon a restart of the
snmpd agent.
certSecName PRIORITY FINGERPRINT OPTIONS
OPTIONS can be one of <--sn SECNAME | --rfc822 | --dns | --ip |
--cn | --any>.
The certSecName token will specify how to map a certificate
field from the client’s X.509 certificate to a SNMPv3 username.
Use the --sn SECNAME flag to directly specify a securityName for
a given certificate. The other flags extract a particular com-
ponent of the certificate for use as a snmpv3 securityName.
These fields are one of: A SubjectAltName containing an rfc822
value (eg hardaker@net-snmp.org), A SubjectAltName containing a
dns name value (eg foo.net-snmp.org), an IP address (eg
192.0.2.1) or a common name "Wes Hardaker". The --any flag
specifies that any of the subjecAltName fields may be used.
Make sure once a securityName has been selected that it is given
authorization via the VACM controls discussed later in this man-
ual page.
See the http://www.net-snmp.org/wiki/index.php/Using_DTLS web
page for more detailed instructions for setting up (D)TLS.
trustCert
For X509 to properly verify a certificate, it should be verifi-
able up until a trust anchor for it. This trust anchor is typi-
cally a CA certificate but it could also be a self-signed cer-
tificate. The "trustCert" token should be used to load specific
trust anchors into the verification engine.
SNMP over (D)TLS requires the use of the Transport Security Model
(TSM), so read the section on the usage of the Transport Security Model
as well. Make sure when you configure the VACM to accept connections
from (D)TLS that you use the "tsm" security model. E.G.:
rwuser -s tsm hardaker@net-snmp.org
SNMPv3 over SSH Support
To use SSH, you’ll need to configure sshd to invoke the sshtosnmp pro-
gram as well as configure the access control settings to allow access
through the tsm security model using the user name provided to snmpd by
the ssh transport.
SNMPv3 with the Transport Security Model (TSM)
The Transport Security Model [RFC5591] defines a SNMPv3 security system
for use with "tunneled" security protocols like TLS, DTLS and SSH. It
is a very simple security model that simply lets properly protected
packets to pass through into the snmp application. The transport is
required to pass a securityName to use to the TSM and the TSM may
optionally prefix this with a transport string (see below).
tsmUseTransportPrefix (1|yes|true|0|no|false)
If set to true, the TSM module will take every securityName
passed to it from the transports underneath and prefix it with a
string that specifically identities the transport it came from.
This is useful to avoid securityName clashes with transports
that generate identical security names. For example, if the ssh
security transport delivered the security name of "hardaker" for
a SSH connection and the TLS security transport also delivered
the security name of "hardaker" for a TLS connection then it
would be impossible to separate out these two users to provide
separate access control rights. With the tsmUseTransportPrefix
set to true, however, the securityNames would be prefixed appro-
priately with one of: "tls:", "dtls:" or "ssh:".
SNMPv3 with the User-based Security Model (USM)
SNMPv3 was originally defined using the User-Based Security Model
(USM), which contains a private list of users and keys specific to the
SNMPv3 protocol. The operational community, however, declared it a
pain to manipulate yet another database and would prefer to use exist-
ing infrastructure. To that end the IETF created the ISMS working
group to battle that problem, and the ISMS working group decided to
tunnel SNMP over SSH and DTLS to make use existing user and authentica-
tion infrastructures.
SNMPv3 USM Users
To use the USM based SNMPv3-specific users, you’ll need to create them.
It is recommended you use the net-snmp-config command to do this, but
you can also do it by directly specifying createUser directives your-
self instead:
createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES]
[privpassphrase]
MD5 and SHA are the authentication types to use. DES and AES
are the privacy protocols to use. If the privacy passphrase is
not specified, it is assumed to be the same as the authentica-
tion passphrase. Note that the users created will be useless
unless they are also added to the VACM access control tables
described above.
SHA authentication and DES/AES privacy require OpenSSL to be
installed and the agent to be built with OpenSSL support. MD5
authentication may be used without OpenSSL.
Warning: the minimum pass phrase length is 8 characters.
SNMPv3 users can be created at runtime using the snmpusm(1) com-
mand.
Instead of figuring out how to use this directive and where to
put it (see below), just run "net-snmp-config --cre-
ate-snmpv3-user" instead, which will add one of these lines to
the right place.
This directive should be placed into the /var/net-
snmp/snmpd.conf file instead of the other normal locations. The
reason is that the information is read from the file and then
the line is removed (eliminating the storage of the master pass-
word for that user) and replaced with the key that is derived
from it. This key is a localized key, so that if it is stolen
it can not be used to access other agents. If the password is
stolen, however, it can be.
If you need to localize the user to a particular EngineID (this
is useful mostly in the similar snmptrapd.conf file), you can
use the -e argument to specify an EngineID as a hex value (EG,
"0x01020304").
If you want to generate either your master or localized keys
directly, replace the given password with a hexstring (preceded
by a "0x") and precede the hex string by a -m or -l token
(respectively). EGs:
[these keys are *not* secure but are easy to visually parse for
counting purposes. Please generate random keys instead of using
these examples]
createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
Due to the way localization happens, localized privacy keys are
expected to be the length needed by the algorithm (128 bits for
all supported algorithms). Master encryption keys, though, need
to be the length required by the authentication algorithm not
the length required by the encrypting algorithm (MD5: 16 bytes,
SHA: 20 bytes).
ACCESS CONTROL
snmpd supports the View-Based Access Control Model (VACM) as defined in
RFC 2575, to control who can retrieve or update information. To this
end, it recognizes various directives relating to access control.
Traditional Access Control
Most simple access control requirements can be specified using the
directives rouser/rwuser (for SNMPv3) or rocommunity/rwcommunity (for
SNMPv1 or SNMPv2c).
rouser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
rwuser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
specify an SNMPv3 user that will be allowed read-only (GET and
GETNEXT) or read-write (GET, GETNEXT and SET) access respec-
tively. By default, this will provide access to the full OID
tree for authenticated (including encrypted) SNMPv3 requests,
using the default context. An alternative minimum security
level can be specified using noauth (to allow unauthenticated
requests), or priv (to enforce use of encryption). The OID
field restricts access for that user to the subtree rooted at
the given OID, or the named view. An optional context can also
be specified, or "context*" to denote a context prefix. If no
context field is specified (or the token "*" is used), the
directive will match all possible contexts.
If SECMODEL is specified then it will be the security model
required for that user (note that identical user names may come
in over different security models and will be appropriately sep-
arated via the access control settings). The default security
model is "usm" and the other common security models are likely
"tsm" when using (D)TLS or SSH support and "ksm" if the Kerberos
support has been compiled in.
rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
rwcommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
specify an SNMPv1 or SNMPv2c community that will be allowed
read-only (GET and GETNEXT) or read-write (GET, GETNEXT and SET)
access respectively. By default, this will provide access to
the full OID tree for such requests, regardless of where they
were sent from. The SOURCE token can be used to restrict access
to requests from the specified system(s) - see com2sec for the
full details. The OID field restricts access for that community
to the subtree rooted at the given OID, or named view. Contexts
are typically less relevant to community-based SNMP versions,
but the same behaviour applies here.
rocommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
rwcommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
are directives relating to requests received using IPv6 (if the
agent supports such transport domains). The interpretation of
the SOURCE, OID, VIEW and CONTEXT tokens are exactly the same as
for the IPv4 versions.
In each case, only one directive should be specified for a given SNMPv3
user, or community string. It is not appropriate to specify both
rouser and rwuser directives referring to the same SNMPv3 user (or
equivalent community settings). The rwuser directive provides all the
access of rouser (as well as allowing SET support). The same holds
true for the community-based directives.
More complex access requirements (such as access to two or more dis-
tinct OID subtrees, or different views for GET and SET requests) should
use one of the other access control mechanisms. Note that if several
distinct communities or SNMPv3 users need to be granted the same level
of access, it would also be more efficient to use the main VACM config-
uration directives.
VACM Configuration
The full flexibility of the VACM is available using four configuration
directives - com2sec, group, view and access. These provide direct
configuration of the underlying VACM tables.
com2sec [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
map an SNMPv1 or SNMPv2c community string to a security name -
either from a particular range of source addresses, or globally
("default"). A restricted source can either be a specific host-
name (or address), or a subnet - represented as IP/MASK (e.g.
10.10.10.0/255.255.255.0), or IP/BITS (e.g. 10.10.10.0/24), or
the IPv6 equivalents.
The same community string can be specified in several separate
directives (presumably with different source tokens), and the
first source/community combination that matches the incoming
request will be selected. Various source/community combinations
can also map to the same security name.
If a CONTEXT is specified (using -Cn), the community string will
be mapped to a security name in the named SNMPv3 context. Other-
wise the default context ("") will be used.
com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY
is the Unix domain sockets version of com2sec.
group GROUP {v1|v2c|usm|tsm|ksm} SECNAME
maps a security name (in the specified security model) into a
named group. Several group directives can specify the same
group name, allowing a single access setting to apply to several
users and/or community strings.
Note that groups must be set up for the two community-based mod-
els separately - a single com2sec (or equivalent) directive will
typically be accompanied by two group directives.
view VNAME TYPE OID [MASK]
defines a named "view" - a subset of the overall OID tree. This
is most commonly a single subtree, but several view directives
can be given with the same view name (VNAME), to build up a more
complex collection of OIDs. TYPE is either included or
excluded, which can again define a more complex view (e.g by
excluding certain sensitive objects from an otherwise accessible
subtree).
MASK is a list of hex octets (optionally separated by ’.’ or
’:’) with the set bits indicating which subidentifiers in the
view OID to match against. If not specified, this defaults to
matching the OID exactly (all bits set), thus defining a simple
OID subtree. So:
view iso1 included .iso 0xf0
view iso2 included .iso
view iso3 included .iso.org.dod.mgmt 0xf0
would all define the same view, covering the whole of the
’iso(1)’ subtree (with the third example ignoring the subidenti-
fiers not covered by the mask).
More usefully, the mask can be used to define a view covering a
particular row (or rows) in a table, by matching against the
appropriate table index value, but skipping the column subiden-
tifier:
view ifRow4 included .1.3.6.1.2.1.2.2.1.0.4 0xff:a0
Note that a mask longer than 8 bits must use ’:’ to separate the
individual octets.
access GROUP CONTEXT {any|v1|v2c|usm|tsm|ksm} LEVEL PREFX READ WRITE
NOTIFY
maps from a group of users/communities (with a particular secu-
rity model and minimum security level, and in a specific con-
text) to one of three views, depending on the request being pro-
cessed.
LEVEL is one of noauth, auth, or priv. PREFX specifies how CON-
TEXT should be matched against the context of the incoming
request, either exact or prefix. READ, WRITE and NOTIFY speci-
fies the view to be used for GET*, SET and TRAP/INFORM requests
(althought the NOTIFY view is not currently used). For v1 or
v2c access, LEVEL will need to be noauth.
Typed-View Configuration
The final group of directives extend the VACM approach into a more
flexible mechanism, which can be applied to other access control
requirements. Rather than the fixed three views of the standard VACM
mechanism, this can be used to configure various different view types.
As far as the main SNMP agent is concerned, the two main view types are
read and write, corresponding to the READ and WRITE views of the main
access directive. See the ’snmptrapd.conf(5)’ man page for discussion
of other view types.
authcommunity TYPES COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
is an alternative to the rocommunity/rwcommunity directives.
TYPES will usually be read or read,write respectively. The view
specification can either be an OID subtree (as before), or a
named view (defined using the view directive) for greater flexi-
bility. If this is omitted, then access will be allowed to the
full OID tree. If CONTEXT is specified, access is configured
within this SNMPv3 context. Otherwise the default context ("")
is used.
authuser TYPES [-s MODEL] USER [LEVEL [OID | -V VIEW [CONTEXT]]]
is an alternative to the rouser/rwuser directives. The fields
TYPES, OID, VIEW and CONTEXT have the same meaning as for auth-
community.
authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW [CONTEXT]]]
is a companion to the authuser directive, specifying access for
a particular group (defined using the group directive as usual).
Both authuser and authgroup default to authenticated requests -
LEVEL can also be specified as noauth or priv to allow unauthen-
ticated requests, or require encryption respectively. Both
authuser and authgroup directives also default to configuring
access for SNMPv3/USM requests - use the ’-s’ flag to specify an
alternative security model (using the same values as for access
above).
authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
also configures the access for a particular group, specifying
the name and type of view to apply. The MODEL and LEVEL fields
are interpreted in the same way as for authgroup. If CONTEXT is
specified, access is configured within this SNMPv3 context (or
contexts with this prefix if the CONTEXT field ends with ’*’).
Otherwise the default context ("") is used.
setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
is a direct equivalent to the original access directive, typi-
cally listing the view types as read or read,write as appropri-
ate. (or see ’snmptrapd.conf(5)’ for other possibilities). All
other fields have the same interpretation as with access.
SYSTEM INFORMATION
Most of the information reported by the Net-SNMP agent is retrieved
from the underlying system, or dynamically configured via SNMP SET
requests (and retained from one run of the agent to the next). How-
ever, certain MIB objects can be configured or controlled via the
snmpd.conf(5) file.
System Group
Most of the scalar objects in the ’system’ group can be configured in
this way:
sysLocation STRING
sysContact STRING
sysName STRING
set the system location, system contact or system name (sysLoca-
tion.0, sysContact.0 and sysName.0) for the agent respectively.
Ordinarily these objects are writable via suitably authorized
SNMP SET requests. However, specifying one of these directives
makes the corresponding object read-only, and attempts to SET it
will result in a notWritable error response.
sysServices NUMBER
sets the value of the sysServices.0 object. For a host system,
a good value is 72 (application + end-to-end layers). If this
directive is not specified, then no value will be reported for
the sysServices.0 object.
sysDescr STRING
sysObjectID OID
sets the system description or object ID for the agent.
Although these MIB objects are not SNMP-writable, these direc-
tives can be used by a network administrator to configure suit-
able values for them.
Interfaces Group
interface NAME TYPE SPEED
can be used to provide appropriate type and speed settings for
interfaces where the agent fails to determine this information
correctly. TYPE is a type value as given in the IANAifType-MIB,
and can be specified numerically or by name (assuming this MIB
is loaded).
interface_fadeout TIMEOUT
specifies, for how long the agent keeps entries in ifTable after
appropriate interfaces have been removed from system (typically
various ppp, tap or tun interfaces). Timeout value is in sec-
onds. Default value is 300 (=5 minutes).
interface_replace_old yes
can be used to remove already existing entries in ifTable when
an interface with the same name appears on the system. E.g. when
ppp0 interface is removed, it is still listed in the table for
interface_fadeout seconds. This option ensures, that the old
ppp0 interface is removed even before the interface_fadeout
timeour when new ppp0 (with different ifIndex) shows up.
Host Resources Group
This requires that the agent was built with support for the host module
(which is now included as part of the default build configuration on
the major supported platforms).
ignoreDisk STRING
controls which disk devices are scanned as part of populating
the hrDiskStorageTable (and hrDeviceTable). The HostRes imple-
mentation code includes a list of disk device patterns appropri-
ate for the current operating system, some of which may cause
the agent to block when trying to open the corresponding disk
devices. This might lead to a timeout when walking these
tables, possibly resulting in inconsistent behaviour. This
directive can be used to specify particular devices (either
individually or wildcarded) that should not be checked.
Note: Please consult the source (host/hr_disk.c) and check for
the Add_HR_Disk_entry calls relevant for a particular O/S
to determine the list of devices that will be scanned.
The pattern can include one or more wildcard expressions. See
snmpd.examples(5) for illustration of the wildcard syntax.
skipNFSInHostResources true
controls whether NFS and NFS-like file systems should be omitted
from the hrStorageTable (true or 1) or not (false or 0, which is
the default). If the Net-SNMP agent gets hung on NFS-mounted
filesystems, you can try setting this to ’1’.
storageUseNFS [1|2]
controls how NFS and NFS-like file systems should be reported in
the hrStorageTable. as ’Network Disks’ (1) or ’Fixed Disks’ (2)
Historically, the Net-SNMP agent has reported such file systems
as ’Fixed Disks’, and this is still the default behaviour. Set-
ting this directive to ’1’ reports such file systems as ´Network
Disks’, as required by the Host Resources MIB.
realStorageUnits
controlls how the agent reports hrStorageAllocationUnits,
hrStorageSize and hrStorageUsed in hrStorageTable. For big
storage drives with small allocation units the agent re-calcu-
lates these values so they all fit Integer32 and hrStorageAllo-
cationUnits x hrStorageSize gives real size of the storage.
Example:
Linux xfs 16TB filesystem with 4096 bytes large blocks
will be reported as hrStorageAllocationUnits = 8192 and
hrStorageSize = 2147483647, so 8192 x 2147483647 gives
real size of the filesystem (=16 TB).
Setting this directive to ’1’ turns off this calculation and the
agent reports real hrStorageAllocationUnits, but it might report
wrong hrStorageSize for big drives because the value won’t fit
into Integer32. In this case, hrStorageAllocationUnits x hrStor-
ageSize won’t give real size of the storage.
Process Monitoring
The hrSWRun group of the Host Resources MIB provides information about
individual processes running on the local system. The prTable of the
UCD-SNMP-MIB complements this by reporting on selected services (which
may involve multiple processes). This requires that the agent was
built with support for the ucd-snmp/proc module (which is included as
part of the default build configuration).
proc NAME [MAX [MIN]]
monitors the number of processes called NAME (as reported by
"/bin/ps -e") running on the local system.
If the number of NAMEd processes is less than MIN or greater
than MAX, then the corresponding prErrorFlag instance will be
set to 1, and a suitable description message reported via the
prErrMessage instance.
Note: This situation will not automatically trigger a trap to
report the problem - see the DisMan Event MIB section
later.
If neither MAX nor MIN are specified, they will default to
infinity and 1 respectively ("at least one"). If only MAX is
specified, MIN will default to 0 ("no more than MAX"). If MAX
is 0 (and MIN is not), this indicates infinity ("at least MIN").
If both MAX and MIN are 0, this indicates a process that should
not be running.
procfix NAME PROG ARGS
registers a command that can be run to fix errors with the given
process NAME. This will be invoked when the corresponding prE-
rrFix instance is set to 1.
Note: This command will not be invoked automatically.
The procfix directive must be specified after the matching proc
directive, and cannot be used on its own.
If no proc directives are defined, then walking the prTable will fail
(noSuchObject).
Disk Usage Monitoring
This requires that the agent was built with support for the
ucd-snmp/disk module (which is included as part of the default build
configuration).
disk PATH [ MINSPACE | MINPERCENT% ]
monitors the disk mounted at PATH for available disk space.
The minimum threshold can either be specified in kB (MINSPACE)
or as a percentage of the total disk (MINPERCENT% with a ’%’
character), defaulting to 100kB if neither are specified. If
the free disk space falls below this threshold, then the corre-
sponding dskErrorFlag instance will be set to 1, and a suitable
description message reported via the dskErrorMsg instance.
Note: This situation will not automatically trigger a trap to
report the problem - see the DisMan Event MIB section
later.
includeAllDisks MINPERCENT%
configures monitoring of all disks found on the system, using
the specified (percentage) threshold. The threshold for indi-
vidual disks can be adjusted using suitable disk directives
(which can come either before or after the includeAllDisks
directive).
Note: Whether disk directives appears before or after
includeAllDisks may affect the indexing of the dskTable.
Only one includeAllDisks directive should be specified - any
subsequent copies will be ignored.
The list of mounted disks will be determined when the agent
starts using the setmntent(3) and getmntent(3), or fopen(3) and
getmntent(3), or setfsent(3) and getfsent(3) system calls. If
none of the above system calls are available then the root par-
tition "/" (which is assumed to exist on any UNIX based sys-
tem) will be monitored. Disks mounted after the agent has
started will not be monitored.
If neither any disk directives or includeAllDisks are defined, then
walking the dskTable will fail (noSuchObject).
Disk I/O Monitoring
This requires that the agent was built with support for the
ucd-snmp/diskio module (which is not included as part of the default
build configuration).
By default, all block devices known to the operating system are
included in the diskIOTable. On platforms other than Linux, this module
has no configuration directives.
On Linux systems, it is possible to exclude several classes of block
devices from the diskIOTable in order to avoid cluttering the table
with useless zero statistics for pseudo-devices that often are not in
use but are configured by default to exist in most recent Linux distri-
butions.
diskio_exclude_fd yes
Excludes all Linux floppy disk block devices, whose names start
with "fd", e.g. "fd0"
diskio_exclude_loop yes
Excludes all Linux loopback block devices, whose names start
with "loop", e.g. "loop0"
diskio_exclude_ram yes
Excludes all LInux ramdisk block devices, whose names start with
"ram", e.g. "ram0"
System Load Monitoring
This requires that the agent was built with support for either the
ucd-snmp/loadave module or the ucd-snmp/memory module respectively
(both of which are included as part of the default build configura-
tion).
load MAX1 [MAX5 [MAX15]]
monitors the load average of the local system, specifying
thresholds for the 1-minute, 5-minute and 15-minute averages.
If any of these loads exceed the associated maximum value, then
the corresponding laErrorFlag instance will be set to 1, and a
suitable description message reported via the laErrMessage
instance.
Note: This situation will not automatically trigger a trap to
report the problem - see the DisMan Event MIB section
later.
If the MAX15 threshold is omitted, it will default to the MAX5
value. If both MAX5 and MAX15 are omitted, they will default to
the MAX1 value. If this directive is not specified, all three
thresholds will default to a value of DEFMAXLOADAVE.
If a threshold value of 0 is given, the agent will not report
errors via the relevant laErrorFlag or laErrMessage instances,
regardless of the current load.
Unlike the proc and disk directives, walking the walking the laTable
will succeed (assuming the ucd-snmp/loadave module was configured into
the agent), even if the load directive is not present.
swap MIN
monitors the amount of swap space available on the local system.
If this falls below the specified threshold (MIN kB), then the
memErrorSwap object will be set to 1, and a suitable description
message reported via memSwapErrorMsg.
Note: This situation will not automatically trigger a trap to
report the problem - see the DisMan Event MIB section
later.
If this directive is not specified, the default threshold is 16 MB.
Log File Monitoring
This requires that the agent was built with support for either the
ucd-snmp/file or ucd-snmp/logmatch modules respectively (both of which
are included as part of the default build configuration).
file FILE [MAXSIZE]
monitors the size of the specified file (in kB). If MAXSIZE is
specified, and the size of the file exceeds this threshold, then
the corresponding fileErrorFlag instance will be set to 1, and a
suitable description message reported via the fileErrorMsg
instance.
Note: This situation will not automatically trigger a trap to
report the problem - see the DisMan Event MIB section
later.
Note: A maximum of 20 files can be monitored.
Note: If no file directives are defined, then walking the
fileTable will fail (noSuchObject).
logmatch NAME FILE CYCLETIME REGEX
monitors the specified file for occurances of the specified pat-
tern REGEX. The file position is stored internally so the entire
file is only read initially, every subsequent pass will only
read the new lines added to the file since the last read.
NAME name of the logmatch instance (will appear as logMatch-
Name under logMatch/logMatchTable/logMatchEntry/logMatch-
Name in the ucd-snmp MIB tree)
FILE absolute path to the logfile to be monitored. Note that
this path can contain date/time directives (like in the
UNIX ’date’ command). See the manual page for ’strftime’
for the various directives accepted.
CYCLETIME
time interval for each logfile read and internal variable
update in seconds. Note: an SNMPGET* operation will also
trigger an immediate logfile read and variable update.
REGEX the regular expression to be used. Note: DO NOT enclose
the regular expression in quotes even if there are spaces
in the expression as the quotes will also become part of
the pattern to be matched!
Example:
logmatch apache-GETs
/usr/local/apache/logs/access.log-%Y-%m-%d 60 GET.*HTTP.*
This logmatch instance is named ’apache-GETs’, uses
’GET.*HTTP.*’ as its regular expression and it will moni-
tor the file named (assuming today is May 6th 2009):
’/usr/local/apache/logs/access.log-2009-05-06’, tomorrow
it will look for ’access.log-2009-05-07’. The logfile is
read every 60 seconds.
Note: A maximum of 250 logmatch directives can be specified.
Note: If no logmatch directives are defined, then walking the
logMatchTable will fail (noSuchObject).
ACTIVE MONITORING
The usual behaviour of an SNMP agent is to wait for incoming SNMP
requests and respond to them - if no requests are received, an agent
will typically not initiate any actions. This section describes various
directives that can configure snmpd to take a more active role.
Notification Handling
trapcommunity STRING
defines the default community string to be used when sending
traps. Note that this directive must be used prior to any com-
munity-based trap destination directives that need to use it.
trapsink HOST [COMMUNITY [PORT]]
trap2sink HOST [COMMUNITY [PORT]]
informsink HOST [COMMUNITY [PORT]]
define the address of a notification receiver that should be
sent SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifica-
tions respectively. See the section LISTENING ADDRESSES in the
snmpd(8) manual page for more information about the format of
listening addresses. If COMMUNITY is not specified, the most
recent trapcommunity string will be used.
If the transport address does not include an explicit port spec-
ification, then PORT will be used. If this is not specified,
the well known SNMP trap port (162) will be used.
Note: This mechanism is being deprecated, and the listening
port should be specified via the transport specification
HOST instead.
If several sink directives are specified, multiple copies of
each notification (in the appropriate formats) will be gener-
ated.
Note: It is not normally appropriate to list two (or all three)
sink directives with the same destination.
trapsess [SNMPCMD_ARGS] HOST
provides a more generic mechanism for defining notification des-
tinations. SNMPCMD_ARGS should be the command-line options
required for an equivalent snmptrap (or snmpinform) command to
send the desired notification. The option -Ci can be used (with
-v2c or -v3) to generate an INFORM notification rather than an
unacknowledged TRAP.
This is the appropriate directive for defining SNMPv3 trap
receivers. See http://www.net-snmp.org/tutorial/tutorial-5/com-
mands/snmptrap-v3.html for more information about SNMPv3 notifi-
cation behaviour.
authtrapenable {1|2}
determines whether to generate authentication failure traps
(enabled(1)) or not (disabled(2) - the default). Ordinarily the
corresponding MIB object (snmpEnableAuthenTraps.0) is read-
write, but specifying this directive makes this object read-
only, and attempts to set the value via SET requests will result
in a notWritable error response.
v1trapaddress HOST
defines the agent address, which is inserted into SNMPv1 TRAPs.
Arbitrary local IPv4 address is chosen if this option is
ommited. This option is useful mainly when the agent is visible
from outside world by specific address only (e.g. because of
network address translation or firewall).
DisMan Event MIB
The previous directives can be used to configure where traps should be
sent, but are not concerned with when to send such traps (or what traps
should be generated). This is the domain of the Event MIB - developed
by the Distributed Management (DisMan) working group of the IETF.
This requires that the agent was built with support for the dis-
man/event module (which is now included as part of the default build
configuration for the most recent distribution).
Note: The behaviour of the latest implementation differs in
some minor respects from the previous code - nothing too
significant, but existing scripts may possibly need some
minor adjustments.
iquerySecName NAME
agentSecName NAME
specifies the default SNMPv3 username, to be used when making
internal queries to retrieve any necessary information (either
for evaluating the monitored expression, or building a notifica-
tion payload). These internal queries always use SNMPv3, even
if normal querying of the agent is done using SNMPv1 or SNMPv2c.
Note that this user must also be explicitly created (createUser)
and given appropriate access rights (e.g. rouser). This direc-
tive is purely concerned with defining which user should be used
- not with actually setting this user up.
monitor [OPTIONS] NAME EXPRESSION
defines a MIB object to monitor. If the EXPRESSION condition
holds (see below), then this will trigger the corresponding
event, and either send a notification or apply a SET assignment
(or both). Note that the event will only be triggered once,
when the expression first matches. This monitor entry will not
fire again until the monitored condition first becomes false,
and then matches again. NAME is an administrative name for this
expression, and is used for indexing the mteTriggerTable (and
related tables). Note also that such monitors use an internal
SNMPv3 request to retrieve the values being monitored (even if
normal agent queries typically use SNMPv1 or SNMPv2c). See the
iquerySecName token described above.
EXPRESSION
There are three types of monitor expression supported by the
Event MIB - existence, boolean and threshold tests.
OID | ! OID | != OID
defines an existence(0) monitor test. A bare OID speci-
fies a present(0) test, which will fire when (an instance
of) the monitored OID is created. An expression of the
form ! OID specifies an absent(1) test, which will fire
when the monitored OID is delected. An expression of the
form != OID specifies a changed(2) test, which will fire
whenever the monitored value(s) change. Note that there
must be whitespace before the OID token.
OID OP VALUE
defines a boolean(1) monitor test. OP should be one of
the defined comparison operators (!=, ==, <, <=, >, >=)
and VALUE should be an integer value to compare against.
Note that there must be whitespace around the OP token.
A comparison such as OID !=0 will not be handled cor-
rectly.
OID MIN MAX [DMIN DMAX]
defines a threshold(2) monitor test. MIN and MAX are
integer values, specifying lower and upper thresholds.
If the value of the monitored OID falls below the lower
threshold (MIN) or rises above the upper threshold (MAX),
then the monitor entry will trigger the corresponding
event.
Note that the rising threshold event will only be re-
armed when the monitored value falls below the lower
threshold (MIN). Similarly, the falling threshold event
will be re-armed by the upper threshold (MAX).
The optional parameters DMIN and DMAX configure a pair of
similar threshold tests, but working with the delta dif-
ferences between successive sample values.
OPTIONS
There are various options to control the behaviour of the moni-
tored expression. These include:
-D indicates that the expression should be evaluated using
delta differences between sample values (rather than the
values themselves).
-d OID
-di OID
specifies a discontinuity marker for validating delta
differences. A -di object instance will be used exactly
as given. A -d object will have the instance subidenti-
fiers from the corresponding (wildcarded) expression
object appended. If the -I flag is specified, then there
is no difference between these two options.
This option also implies -D.
-e EVENT
specifies the event to be invoked when this monitor entry
is triggered. If this option is not given, the monitor
entry will generate one of the standard notifications
defined in the DISMAN-EVENT-MIB.
-I indicates that the monitored expression should be applied
to the specified OID as a single instance. By default,
the OID will be treated as a wildcarded object, and the
monitor expanded to cover all matching instances.
-i OID
-o OID define additional varbinds to be added to the notifica-
tion payload when this monitor trigger fires. For a
wildcarded expression, the suffix of the matched instance
will be added to any OIDs specified using -o, while OIDs
specified using -i will be treated as exact instances.
If the -I flag is specified, then there is no difference
between these two options.
See strictDisman for details of the ordering of notifica-
tion payloads.
-r FREQUENCY
monitors the given expression every FREQUENCY, where FRE-
QUENCY is in seconds or optionally suffixed by one of s
(for seconds), m (for minutes), h (for hours), d (for
days), or w (for weeks). By default, the expression will
be evaluated every 600s (10 minutes).
-S indicates that the monitor expression should not be eval-
uated when the agent first starts up. The first evalua-
tion will be done once the first repeat interval has
expired.
-s indicates that the monitor expression should be evaluated
when the agent first starts up. This is the default
behaviour.
Note: Notifications triggered by this initial evalua-
tion will be sent before the coldStart trap.
-u SECNAME
specifies a security name to use for scanning the local
host, instead of the default iquerySecName. Once again,
this user must be explicitly created and given suitable
access rights.
notificationEvent ENAME NOTIFICATION [-m] [-i OID | -o OID ]*
defines a notification event named ENAME. This can be triggered
from a given monitor entry by specifying the option -e ENAME
(see above). NOTIFICATION should be the OID of the NOTIFICA-
TION-TYPE definition for the notification to be generated.
If the -m option is given, the notification payload will include
the standard varbinds as specified in the OBJECTS clause of the
notification MIB definition. This option must come after the
NOTIFICATION OID (and the relevant MIB file must be available
and loaded by the agent). Otherwise, these varbinds must be
listed explicitly (either here or in the corresponding monitor
directive).
The -i OID and -o OID options specify additional varbinds to be
appended to the notification payload, after the standard list.
If the monitor entry that triggered this event involved a wild-
carded expression, the suffix of the matched instance will be
added to any OIDs specified using -o, while OIDs specified using
-i will be treated as exact instances. If the -I flag was spec-
ified to the monitor directive, then there is no difference
between these two options.
setEvent ENAME [-I] OID = VALUE
defines a set event named ENAME, assigning the (integer) VALUE
to the specified OID. This can be triggered from a given moni-
tor entry by specifying the option -e ENAME (see above).
If the monitor entry that triggered this event involved a wild-
carded expression, the suffix of the matched instance will nor-
mally be added to the OID. If the -I flag was specified to
either of the monitor or setEvent directives, the specified OID
will be regarded as an exact single instance.
strictDisman yes
The definition of SNMP notifications states that the varbinds
defined in the OBJECT clause should come first (in the order
specified), followed by any "extra" varbinds that the notifica-
tion generator feels might be useful. The most natural approach
would be to associate these mandatory varbinds with the notifi-
cationEvent entry, and append any varbinds associated with the
monitor entry that triggered the notification to the end of this
list. This is the default behaviour of the Net-SNMP Event MIB
implementation.
Unfortunately, the DisMan Event MIB specifications actually
state that the trigger-related varbinds should come first, fol-
lowed by the event-related ones. This directive can be used to
restore this strictly-correct (but inappropriate) behaviour.
Note: Strict DisMan ordering may result in generating invalid
notifications payload lists if the notificationEvent -n
flag is used together with monitor -o (or -i) varbind
options.
If no monitor entries specify payload varbinds, then the setting
of this directive is irrelevant.
linkUpDownNotifications yes
will configure the Event MIB tables to monitor the ifTable for
network interfaces being taken up or down, and triggering a
linkUp or linkDown notification as appropriate.
This is exactly equivalent to the configuration:
notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
defaultMonitors yes
will configure the Event MIB tables to monitor the various
UCD-SNMP-MIB tables for problems (as indicated by the appropri-
ate xxErrFlag column objects).
This is exactly equivalent to the configuration:
monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
monitor -o extNames -o extOutput "extTable" extResult !=0
monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
In both these latter cases, the snmpd.conf must also contain a iquery-
SecName directive, together with a corresponding createUser entry and
suitable access control configuration.
DisMan Schedule MIB
The DisMan working group also produced a mechanism for scheduling par-
ticular actions (a specified SET assignment) at given times. This
requires that the agent was built with support for the disman/schedule
module (which is included as part of the default build configuration
for the most recent distribution).
There are three ways of specifying the scheduled action:
repeat FREQUENCY OID = VALUE
configures a SET assignment of the (integer) VALUE to the MIB
for the most recent distribution).
There are three ways of specifying the scheduled action:
repeat FREQUENCY OID = VALUE
configures a SET assignment of the (integer) VALUE to the MIB
instance OID, to be run every FREQUENCY seconds, where FREQUENCY
is in seconds or optionally suffixed by one of s (for seconds),
m (for minutes), h (for hours), d (for days), or w (for weeks).
cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
configures a SET assignment of the (integer) VALUE to the MIB
instance OID, to be run at the times specified by the fields
MINUTE to WEEKDAY. These follow the same pattern as the equiva-
lent crontab(5) fields.
Note: These fields should be specified as a (comma-separated)
list of numeric values. Named values for the MONTH and
WEEKDAY fields are not supported, and neither are value
ranges. A wildcard match can be specified as ’*’.
The DAY field can also accept negative values, to indicate days
counting backwar
|
