FreeBSD Manual Pages

home | help

SNMPD.CONF(5) Net-SNMP SNMPD.CONF(5)

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 op-
eration and the management information provided. These files (snmpd.conf
and snmpd.local.conf) can be located in one of several locations, as de-
scribed 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) manual 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 informa-
tion supplied by the agent, there are a handful of directives that control
the behaviour of snmpd considered simply as a daemon providing a network
service.

agentaddress [<transport-specifier>:]<transport-address>[,...]
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 ad-
dresses.

The default behaviour is to listen on UDP port 161 on all IPv4 in-
terfaces.

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 start-
ing with '#' (#UID).

leave_pidfile yes
instructs the agent to not remove its pid file on shutdown. Equiva-
lent to specifying "-U" on the command line.

maxGetbulkRepeats NUM
Sets the maximum number of responses allowed for a single variable
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,
setting this to unlimited is not considered safe if your user popu-
lation 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, setting this to unlimited is not considered safe if your
user population can not be trusted.

In general, the total number of responses will not be allowed to ex-
ceed 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 allowed to fit below this
number.

Also note that the processing of maxGetbulkRepeats is handled first.

ifmib_max_num_ifaces NUM
Sets the maximum number of interfaces included in IF-MIB data col-
lection. For servers with a large number of interfaces (ppp, dummy,
bridge, etc) the IF-MIB processing will take a large chunk of CPU
for ioctl calls (on Linux). Setting a reasonable maximum for the CPU
used will reduce the CPU load for IF-MIB processing. For example,
configuring "ifmib_max_num_ifaces 500" will include only the first
500 interfaces based on ifindex and ignore all others for IF-MIB
processing.

The default (without this configured) is to include all interfaces.

include_ifmib_iface_prefix PREFIX1 PREFIX2 ...
Sets the interface name prefixes to include in the IF-MIB data col-
lection. For servers with a large number of interfaces (ppp, dummy,
bridge, etc) the IF-MIB processing will take a large chunk of CPU
for ioctl calls (on Linux). A set of space-separated interface name
prefixes will reduce the CPU load for IF-MIB processing. For exam-
ple, configuring "include_ifmib_iface_prefix eth dummy lo" will in-
clude only interfaces with these prefixes and ignore all others for
IF-MIB processing. If regex support is compiled in, each of the pre-
fixes is a regular expression (which is not permitted to contain a
space or tab character).

The default (without this configured) is to include all interfaces.

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 originally de-
fined with a "User-based Security Model" (USM) [RFC3414] that required
maintaining an 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 contains partial support for
SNMPv3/SSH as well but has not been as extensively tested. It also con-
tains 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 manager supports
SNMP over (D)TLS or SNMP over SSH we suggest you use one of these mecha-
nisms instead of using USM, but as always with Net-SNMP we give you the op-
tions 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 proto-
col defines "engineIDs" that uniquely identify an agent. The string must
be consistent through time and should not change or conflict with another
agent's engineID. Ever. Internally, Net-SNMP by default creates a unique
engineID that is based off of the current system 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 prob-
lems.

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) performed a
study and presented it at an IETF meeting that showed that TCP-based proto-
cols are sufficient for stable networks but quickly become a problem in un-
stable 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 potentially 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 <specifier>
This token defines the default X.509 public key to use as the
server's identity. It should either be a fingerprint or a filename.
To create a public key for use, please run the "net-snmp-cert" util-
ity which will help you create the required certificate.

The default value for this is the certificate in the "snmpd" named
certificate file.

[snmp] tlsAlgorithms <algorithms>
This string will select the algorithms to use when negotiating secu-
rity during (D)TLS session establishment. See the openssl manual
page ciphers(1) for details on the format. Example strings include:

DEFAULT
ALL
HIGH
HIGH:!AES128-SHA

The default value is whatever openssl itself was configured with.

[snmp] x509CRLFile
If you are using a Certificate Authority (CA) that publishes a Cer-
tificate Revocation List (CRL) then this token can be used to spec-
ify 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 no-
ticed 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 an SNMPv3 username. Use the
--sn SECNAME flag to directly specify a securityName for a given
certificate. The other flags extract a particular component of the
certificate for use as an 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 subjecAlt-
Name fields may be used. Make sure once a securityName has been se-
lected that it is given authorization via the VACM controls dis-
cussed later in this manual 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 <specifier>
For X509 to properly verify a certificate, it should be verifiable
up until a trust anchor for it. This trust anchor is typically a CA
certificate but it could also be a self-signed certificate. 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 program
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 an 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 trans-
port 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 sepa-
rate out these two users to provide separate access control rights.
With the tsmUseTransportPrefix set to true, however, the security-
Names would be prefixed appropriately 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 pro-
tocol. The operational community, however, declared it a pain to manipu-
late yet another database and would prefer to use existing 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 authentication 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 yourself instead:

createUser [-e ENGINEID] username (MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224)
authpassphrase [DES|AES] [privpassphrase]

MD5|SHA|SHA-512|SHA-384|SHA-256|SHA-224 are the authentication types
to use. DES and AES are the privacy protocols to use. If the pri-
vacy passphrase is not specified, it is assumed to be the same as
the authentication passphrase. Note that the users created will be
useless unless they are also added to the VACM access control tables
described above.

SHA|SHA-512|SHA-384|SHA-256|SHA-224 authentication and DES/AES pri-
vacy 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) command.

Instead of figuring out how to use this directive and where to put
it (see below), just run "net-snmp-config --create-snmpv3-user" in-
stead, 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 password for that user) and
replaced with the key that is derived from it. This key is a local-
ized 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 di-
rectly, 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 ex-
pected 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 direc-
tives 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 GET-
NEXT) or read-write (GET, GETNEXT and SET) access respectively. By
default, this will provide access to the full OID tree for authenti-
cated (including encrypted) SNMPv3 requests, using the default con-
text. 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 dif-
ferent security models and will be appropriately separated 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 com-
munity 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 distinct
OID subtrees, or different views for GET and SET requests) should use one
of the other access control mechanisms. Note that if several distinct com-
munities or SNMPv3 users need to be granted the same level of access, it
would also be more efficient to use the main VACM configuration directives.

VACM Configuration
The full flexibility of the VACM is available using four configuration di-
rectives - com2sec, group, view and access. These provide direct configu-
ration 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 - ei-
ther from a particular range of source addresses, or globally ("de-
fault"). A restricted source can either be a specific hostname (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. A restriction preceded by an exclamation mark (!)
denies access from that address or subnet, e.g., !10.10.10.0/24 de-
nies requests from sources in that subnet. Deny restrictions must
be before permit. E.g., the following example permits access from
all of 10.0.0.0/8 except for 10.10.10.0/24:
com2sec sec1 !10.10.10.0/24 public
com2sec sec1 10.0.0.0/8 public

Access from outside of 10.0.0.0/8 would still be denied.

The same community string can be specified in several separate di-
rectives (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. Otherwise 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 models
separately - a single com2sec (or equivalent) directive will typi-
cally 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 subidentifiers not cov-
ered by the mask).

More usefully, the mask can be used to define a view covering a par-
ticular row (or rows) in a table, by matching against the appropri-
ate table index value, but skipping the column subidentifier:

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 in-
dividual 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 security
model and minimum security level, and in a specific context) to one
of three views, depending on the request being processed.

LEVEL is one of noauth, auth, or priv. PREFX specifies how CONTEXT
should be matched against the context of the incoming request, ei-
ther exact or prefix. READ, WRITE and NOTIFY specifies 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, correspond-
ing to the READ and WRITE views of the main access directive. See the 'sn-
mptrapd.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 specifi-
cation can either be an OID subtree (as before), or a named view
(defined using the view directive) for greater flexibility. If this
is omitted, then access will be allowed to the full OID tree. If
CONTEXT is specified, access is configured within this SNMPv3 con-
text. 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 authcommu-
nity.

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 unauthenticated re-
quests, or require encryption respectively. Both authuser and auth-
group 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 in-
terpreted in the same way as for authgroup. If CONTEXT is speci-
fied, 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, typically
listing the view types as read or read,write as appropriate. (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). However, certain MIB ob-
jects 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. Or-
dinarily 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 direc-
tive 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 directives can be
used by a network administrator to configure suitable values for
them.

Interfaces Group
interface NAME TYPE SPEED
can be used to provide appropriate type and speed settings for in-
terfaces where the agent fails to determine this information cor-
rectly. 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 ap-
propriate interfaces have been removed from system (typically vari-
ous ppp, tap or tun interfaces). Timeout value is in seconds. De-
fault 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 inter-
face_fadeout seconds. This option ensures, that the old ppp0 inter-
face is removed even before the interface_fadeout timeout 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 implementation
code includes a list of disk device patterns appropriate 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 incon-
sistent 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 de-
termine the list of devices that will be scanned.

The pattern can include one or more wildcard expressions. See sn-
mpd.examples(5) for illustration of the wildcard syntax.

ignoremount [-r] STRING
controls which mounts should be omitted from the hrStorageTable. If
the Net-SNMP agent gets hung on accessing a filesystem, or the
filesystem is always mostly full (and thus leads to spurious
alerts), you can omit it by listing the full path in this directive.

If the "-r" option is provided, the pattern can include one or more
regular expressions.

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 filesys-
tems, you can try setting this to '1'.

Alternately, more granular control over which mounts should be omit-
ted from the hrStorageTable can be achieved via the ignoremount di-
rective.

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) Histor-
ically, the Net-SNMP agent has reported such file systems as 'Fixed
Disks', and this is still the default behaviour. Setting this di-
rective to '1' reports such file systems as 'Network Disks', as re-
quired by the Host Resources MIB.

realStorageUnits
controls how the agent reports hrStorageAllocationUnits, hrStorage-
Size and hrStorageUsed in hrStorageTable. For big storage drives
with small allocation units the agent re-calculates these values so
they all fit Integer32 and hrStorageAllocationUnits 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 hrStora-
geSize = 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 hrStorageSize
won't give real size of the storage.

Process Monitoring
The hrSWRun group of the Host Resources MIB provides information about in-
dividual 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 de-
fault build configuration).

proc NAME [MAX [MIN]]
monitors the number of processes called NAME (as reported by
"/bin/ps acx -J 0") 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 in-
stance.

Note: This situation will not automatically trigger a trap to re-
port 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 prErrFix
instance is set to 1.

Note: This command will not be invoked automatically.

The procfix directive must be specified after the matching proc di-
rective, and cannot be used on its own.

If no proc directives are defined, then walking the prTable will fail (no-
SuchObject).

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. Disks
mounted after the agent has started will not be monitored, unless
includeAllDisks option is specified.

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 corresponding dskError-
Flag 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 re-
port 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 dskTable is dynamically up-
dated, unmounted disks disappear from the table and newly mounted
disks are added to the table. The threshold for individual disks
can be adjusted using suitable disk directives (which can come ei-
ther before or after the includeAllDisks directive).

Note: Whether disk directives appear before or after includeAllD-
isks may affect the indexing of the dskTable.

Only one includeAllDisks directive should be specified - any subse-
quent copies will be ignored.

The list of mounted disks will be determined from HOST-RESOURCES-
MIB::hrFSTable.

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 configu-
ration directives.

On Linux systems, it is possible to exclude several classes of block de-
vices from the diskIOTable in order to avoid cluttering the table with use-
less zero statistics for pseudo-devices that often are not in use but are
configured by default to exist in most recent Linux distributions.

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"

diskio_exclude_md yes
Excludes all Linux RAID block devices, whose names start with "md",
e.g. "md0"

On Linux systems, it is also possible to report only explicitly whitelisted
devices. It may take a significant amount of time to process diskIOTable
data on systems with tens of thousands of block devices and whitelisting
only the important ones avoids large CPU consumption.

diskio <device>
Enables acceptlist of devices and adds the device to the acceptlist.
Only explicitly acceptlisted devices will be reported. This option
may be used multiple times.

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 configuration).

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 re-
port 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 thresh-
olds 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 memEr-
rorSwap object will be set to 1, and a suitable description message
reported via memSwapErrorMsg.

Note: This situation will not automatically trigger a trap to re-
port 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 suit-
able description message reported via the fileErrorMsg instance.

Note: This situation will not automatically trigger a trap to re-
port 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 pattern
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 logMatchName
under logMatch/logMatchTable/logMatchEntry/logMatchName 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 up-
date in seconds. Note: an SNMPGET* operation will also trig-
ger 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/ac-
cess.log-%Y-%m-%d 60 GET.*HTTP.*

This logmatch instance is named 'apache-GETs', uses
'GET.*HTTP.*' as its regular expression and it will monitor
the file named (assuming today is May 6th 2009): '/usr/lo-
cal/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 log-
MatchTable 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 community-based
trap destination directives that need to use it.

trapsink [-profile p] [-name n] [-tag t] [-s src] HOST [COMMUNITY [PORT]]

trap2sink [-profile p] [-name n] [-tag t] [-s src] HOST [COMMUNITY [PORT]]

informsink [-profile p] [-name n] [-tag t] [-s src] HOST [COMMUNITY [PORT]]
define the address of a notification receiver that should be sent
SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifications respec-
tively. 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 specifi-
cation, 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 in-
stead.

The optional name and tag parameters specifies the name or tag that
will be used for SNMP-NOTIFICATION-MIB table entries. The profile
specifies which notification filter profile entry will be used for
filtering outgoing notifications. (See notificationFilter)

The optional src parameter specifies the source address that will be
used when sending the trap packet to this sink. It is specified as
a <transport-address>, using the same <transport-specifier> as the
destination HOST. See the section LISTENING ADDRESSES in the sn-
mpd(8) manual page for more information about the format.

If several sink directives are specified, multiple copies of each
notification (in the appropriate formats) will be generated.

Note: It is not normally appropriate to list two (or all three)
sink directives with the same destination.

trapsess [-profile p] [-name n] [-tag t] [-s src] [SNMPCMD_ARGS] HOST
provides a more generic mechanism for defining notification destina-
tions. 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 gen-
erate an INFORM notification rather than an unacknowledged TRAP.

This is the appropriate directive for defining SNMPv3 trap re-
ceivers. See http://www.net-snmp.org/tutorial/tutorial-5/com-
mands/snmptrap-v3.html for more information about SNMPv3 notifica-
tion behaviour.

notificationFilter NAME OID MASK TYPE
specifies a SNMP-NOTIFICATION-MIB notification filter profile, which
may be used to filter traps. TYPE must be included or excluded, Some
examples:

notificationFilter all_ok .1.3 0x00 included
notificationFilter no_coldstart .1.3 0x00 included
notificationFilter no_coldstart .1.3.6.1.6.3.1.1.5.1 0x00 excluded

trapsink -profile no_coldstart 192.168.1.3:3162 secret3

authtrapenable {1|2}
determines whether to generate authentication failure traps (en-
abled(1)) or not (disabled(2) - the default). Ordinarily the corre-
sponding 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. An
arbitrary local IPv4 address is chosen if this option is omitted.
This option is mainly useful when the agent is visible from the out-
side world by a specific address only (e.g. because of network ad-
dress 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 disman/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 signifi-
cant, but existing scripts may possibly need some minor ad-
justments.

iquerySecName NAME

agentSecName NAME
specifies the default SNMPv3 username, to be used when making inter-
nal queries to retrieve any necessary information (either for evalu-
ating the monitored expression, or building a notification 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 directive 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 ei-
ther 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). Each monitor line
must have a unique NAME. Monitor lines with a duplicate name are
discarded and cause snmpd to log a duplicate index complaint. 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 specifies 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 moni-
tored OID is detected. 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 white-
space 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 correctly.

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 differ-
ences between successive sample values.

OPTIONSThere are various options to control the behaviour of the monitored
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 OIDspecifies a discontinuity marker for validating delta differ-
ences. A -di object instance will be used exactly as given.
A -d object will have the instance subidentifiers 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 ex-
panded to cover all matching instances.

-i OID

-o OID define additional varbinds to be added to the notification
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 speci-
fied, then there is no difference between these two options.

See strictDisman for details of the ordering of notification
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 evaluated
when the agent first starts up. The first evaluation 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 behav-
iour.

Note: Notifications triggered by this initial evaluation
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 NOTIFICATION-TYPE de-
finition 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 notifi-
cation 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 ap-
pended to the notification payload, after the standard list. If the
monitor entry that triggered this event involved a wildcarded ex-
pression, 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 specified to the
monitor directive, then there is no difference between these two op-
tions.

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 monitor entry
by specifying the option -e ENAME (see above).

If the monitor entry that triggered this event involved a wildcarded
expression, the suffix of the matched instance will normally 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 de-
fined in the OBJECT clause should come first (in the order speci-
fied), followed by any "extra" varbinds that the notification gener-
ator feels might be useful. The most natural approach would be to
associate these mandatory varbinds with the notificationEvent entry,
and append any varbinds associated with the monitor entry that trig-
gered 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, followed 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 noti-
fications 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 net-
work 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 appropriate
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 iquerySec-
Name 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 particu-
lar 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 in-
stance 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 in-
stance OID, to be run at the times specified by the fields MINUTE to
WEEKDAY. These follow the same pattern as the equivalent 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 backwards from the end of the month.

at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
configures a one-shot SET assignment, to be run at the first match-
ing time as specified by the fields MINUTE to WEEKDAY. The inter-
pretation of these fields is exactly the same as for the cron direc-
tive.

Data Delivery via Notifications
Note: This functionality is only available if the deliver/deliverByNotify
mib module was compiled in to the agent

In some situations it may be advantageous to deliver SNMP data over SNMP
Notifications (TRAPs and INFORMs) rather than the typical process of having
the manager issue requests for the data (via GETs and GETNEXTs). Reasons
for doing this are numerous, but frequently corner cases. The most common
reason for wanting this behaviour might be to monitor devices that reside
behind NATs or Firewalls that prevent incoming SNMP traffic.

It should be noted that although most management software is capable of
logging notifications, very little (if any) management software will update
their "knowledge database" based on the contents of SNMP notifications.
IE, it won't (for example) update the interface traffic counter history
that is used to produce graphs. Most larger network management packages
have a separate database for storing data received via SNMP requests (GETs
and GETNEXTs) vs those received from notifications. Researching the capa-
bilities of your management station software is required before assuming
this functionality will solve your data delivery requirements.

Notifications generated via this mechanism will be sent to the standard set
of configured notification targets. See the "Notification Handling" sec-
tion of this document for further information.

deliverByNotify [-p] [-m] [-s MAXSIZE] FREQUENCY OID
This directive tells the SNMP agent to self-walk the OID, collect
all the data and send it out every FREQUENCY seconds, where FRE-
QUENCY is in seconds or optionally suffixed by one of s (for sec-
onds), m (for minutes), h (for hours), d (for days), or w (for
weeks). By default, scalars are included in the notification that
specify how often the notification will be sent (unless the -p op-
tion is specified) and which message number of how many messages a
particular notification is (unless -m is specified). To break the
notifications into manageable packet sizes, use the -s flag to spec-
ify the approximate maximum number of bytes that a notification mes-
sage should be limited to. If more than MAXSIZE of bytes is needed
then multiple notifications will be sent to deliver the data. Note
that the calculations for ensuring the maximum size is met are ap-
proximations and thus it can be absolutely guaranteed they'll be un-
der that size, so leave a padding buffer if it is critical that you
avoid fragmentation. A value of -1 indicates force everything into
a single message no matter how big it is.

Example usage: the following will deliver the contents of the
ifTable once an hour and the contents of the system group once every
2 hours:

deliverByNotify 3600 ifTable
deliverByNotify 7200 system

deliverByNotifyMaxPacketSize SIZEINBYTES
Sets the default notification size limit (see the -s flag above).

deliverByNotifyOid OID

deliverByNotifyFrequencyOid OID

deliverByNotifyMessageNumberOid OID

deliverByNotifyMaxMessageNumberOid OID
These set the data OID that the notification will be sent under, the
scalar OID, the message number OID, and the maximum message number
OID. These default to objects in the NET-SNMP-PERIODIC-NOTIFY-MIB.

EXTENDING AGENT FUNCTIONALITY
One of the first distinguishing features of the original UCD suite was the
ability to extend the functionality of the agent - not just by recompiling
with code for new MIB modules, but also by configuring the running agent to
report additional information. There are a number of techniques to support
this, including:

* running external commands (exec, extend, pass)

* loading new code dynamically (embedded perl, dlmod)

* communicating with other agents (proxy, SMUX, AgentX)

Arbitrary Extension Commands
The earliest extension mechanism was the ability to run arbitrary commands
or shell scripts. Such commands do not need to be aware of SNMP operations,
or conform to any particular behaviour - the MIB structures are designed to
accommodate any form of command output. Use of this mechanism requires
that the agent was built with support for the ucd-snmp/extensible and/or
agent/extend modules (which are both included as part of the default build
configuration).

exec [MIBOID] NAME PROG ARGS

sh [MIBOID] NAME PROG ARGS
invoke the named PROG with arguments of ARGS. By default the exit
status and first line of output from the command will be reported
via the extTable, discarding any additional output.

Note: Entries in this table appear in the order they are read from
the configuration file. This means that adding new exec (or
sh) directives and restarting the agent, may affect the in-
dexing of other entries.

The PROG argument for exec directives must be a full path to a real
binary, as it is executed via the exec() system call. To invoke a
shell script, use the sh directive instead.

If MIBOID is specified, then the results will be rooted at this
point in the OID tree, returning the exit statement as MIBOID.100.0
and the entire command output in a pseudo-table based at MIBNUM.101
- with one 'row' for each line of output.

Note: The layout of this "relocatable" form of exec (or sh) output
does not strictly form a valid MIB structure. This mechanism
is being deprecated - please see the extend directive (de-
scribed below) instead.

The agent does not cache the exit status or output of the executed
program.

execfix NAME PROG ARGS
registers a command that can be invoked on demand - typically to re-
spond to or fix errors with the corresponding exec or sh entry.
When the extErrFix instance for a given NAMEd entry is set to the
integer value of 1, this command will be called.

Note: This directive can only be used in combination with a corre-
sponding exec or sh directive, which must be defined first.
Attempting to define an unaccompanied execfix directive will
fail.

exec and sh extensions can only be configured via the snmpd.conf file.
They cannot be set up via SNMP SET requests.

extend [-cacheTime TIME] [-execType TYPE] [MIBOID] NAME PROG ARGS
works in a similar manner to the exec directive, but with a number
of improvements. The MIB tables (nsExtendConfigTable etc) are in-
dexed by the NAME token, so are unaffected by the order in which en-
tries are read from the configuration files. There are two result
tables - one (nsExtendOutput1Table) containing the exit status, the
first line and full output (as a single string) for each extend en-
try, and the other (nsExtendOutput2Table) containing the complete
output as a series of separate lines.

If -cacheTime is specified, then its argument is used as the cache
timeout (in whole seconds) for this extend entry. This mechanism
provides a non-volatile way to specify the cache timeout.

If -execType is specified and has a value of sh, then this extend
entry will be run in a shell. Otherwise it will be run in the de-
fault exec fashion. This mechanism provides a non-volatile way to
specify the exec type.

If MIBOID is specified, then the configuration and result tables
will be rooted at this point in the OID tree, but are otherwise
structured in exactly the same way. This means that several separate
extend directives can specify the same MIBOID root, without con-
flicting.

The exit status and output is cached for each entry individually,
and can be cleared (and the caching behaviour configured) using the
nsCacheTable.

extendfix NAME PROG ARGS
registers a command that can be invoked on demand, by setting the
appropriate nsExtendRunType instance to the value run-command(3).
Unlike the equivalent execfix, this directive does not need to be
paired with a corresponding extend entry, and can appear on its own.

Both extend and extendfix directives can be configured dynamically, using
SNMP SET requests to the NET-SNMP-EXTEND-MIB.

MIB-Specific Extension Commands
The first group of extension directives invoke arbitrary commands, and rely
on the MIB structure (and management applications) having the flexibility
to accommodate and interpret the output. This is a convenient way to make
information available quickly and simply, but is of no use when implement-
ing specific MIB objects, where the extension must conform to the structure
of the MIB (rather than vice versa). The remaining extension mechanisms
are all concerned with such MIB-specific situations - starting with "pass-
through" scripts. Use of this mechanism requires that the agent was built
with support for the ucd-snmp/pass and ucd-snmp/pass_persist modules (which
are both included as part of the default build configuration).

pass [-p priority] MIBOID PROG
will pass control of the subtree rooted at MIBOID to the specified
PROG command. GET and GETNEXT requests for OIDs within this tree
will trigger this command, called as:

PROG -g OID

PROG -n OID

respectively, where OID is the requested OID. The PROG command
should return the response varbind as three separate lines printed
to stdout - the first line should be the OID of the returned value,
the second should be its TYPE (one of the text strings integer,
gauge, counter, timeticks, ipaddress, objectid, octet, or string ),
and the third should be the value itself. (Note: octets are sent as
ASCII, space-separated hex strings, e.g. "00 3f dd 00 c6 be".)

If the command cannot return an appropriate varbind - e.g the speci-
fied OID did not correspond to a valid instance for a GET request,
or there were no following instances for a GETNEXT - then it should
exit without producing any output. This will result in an SNMP no-
SuchName error, or a noSuchInstance exception.

Note: The SMIv2 type counter64 and SNMPv2 noSuchObject ex-
ception are not supported.

A SET request will result in the command being called as:

PROG -s OID TYPE VALUE

where TYPE is one of the tokens listed above, indicating the type of
the value passed as the third parameter.

If the assignment is successful, the PROG command should exit with-
out producing any output. Errors should be indicated by writing one
of the strings not-writable, or wrong-type to stdout, and the agent
will generate the appropriate error response.

Note: The other SNMPv2 errors are not supported.

In either case, the command should exit once it has finished pro-
cessing. Each request (and each varbind within a single request)
will trigger a separate invocation of the command.

The default registration priority is 127. This can be changed by
supplying the optional -p flag, with lower priority registrations
being used in preference to higher priority values.

pass_persist [-p priority] MIBOID PROG
will also pass control of the subtree rooted at MIBOID to the speci-
fied PROG command. However this command will continue to run after
the initial request has been answered, so subsequent requests can be
processed without the startup overheads.

Upon initialization, PROG will be passed the string "PING\n" on
stdin, and should respond by printing "PONG\n" to stdout.

For GET and GETNEXT requests, PROG will be passed two lines on
stdin, the command (get or getnext) and the requested OID. It
should respond by printing three lines to stdout - the OID for the
result varbind, the TYPE and the VALUE itself - exactly as for the
pass directive above. If the command cannot return an appropriate
varbind, it should print print "NONE\n" to stdout (but continue run-
ning).

For SET requests, PROG will be passed three lines on stdin, the com-
mand (set) and the requested OID, followed by the type and value
(both on the same line). If the assignment is successful, the com-
mand should print "DONE\n" to stdout. Errors should be indicated by
writing one of the strings not-writable, wrong-type, wrong-length,
wrong-value or inconsistent-value to stdout, and the agent will gen-
erate the appropriate error response. In either case, the command
should continue running.

The registration priority can be changed using the optional -p flag,
just as for the pass directive.

pass and pass_persist extensions can only be configured via the snmpd.conf
file. They cannot be set up via SNMP SET requests.

Embedded Perl Support
Programs using the previous extension mechanisms can be written in any con-
venient programming language - including perl, which is a common choice for
pass-through extensions in particular. However the Net-SNMP agent also in-
cludes support for embedded perl technology (similar to mod_perl for the
Apache web server). This allows the agent to interpret perl scripts di-
rectly, thus avoiding the overhead of spawning processes and initializing
the perl system when a request is received.

Use of this mechanism requires that the agent was built with support for
the embedded perl mechanism, which is not part of the default build envi-
ronment. It must be explicitly included by specifying the '--enable-embed-
ded-perl' option to the configure script when the package is first built.

If enabled, the following directives will be recognised:

disablePerl true
will turn off embedded perl support entirely (e.g. if there are
problems with the perl installation).

perlInitFile FILE
loads the specified initialisation file (if present) immediately be-
fore the first perl directive is parsed. If not explicitly speci-
fied, the agent will look for the default initialisation file
/usr/local/share/snmp/snmp_perl.pl.

The default initialisation file creates an instance of a Net-
SNMP::agent object - a variable $agent which can be used to register
perl-based MIB handler routines.

perl EXPRESSION
evaluates the given expression. This would typically register a
handler routine to be called when a section of the OID tree was re-
quested:
perl use Data::Dumper;
perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);

This expression could also source an external file:
perl 'do /path/to/file.pl';

or perform any other perl-based processing that might be required.

Dynamically Loadable Modules
Most of the MIBs supported by the Net-SNMP agent are implemented as C code
modules, which were compiled and linked into the agent libraries when the
suite was first built. Such implementation modules can also be compiled
independently and loaded into the running agent once it has started. Use
of this mechanism requires that the agent was built with support for the
ucd-snmp/dlmod module (which is included as part of the default build con-
figuration).

dlmod NAME PATH
will load the shared object module from the file PATH (an absolute
filename), and call the initialisation routine init_NAME.

Note: If the specified PATH is not a fully qualified filename, it
will be interpreted relative to /usr/local/lib/snmp/dlmod,
and .so will be appended to the filename.

This functionality can also be configured using SNMP SET requests to the
UCD-DLMOD-MIB.

Proxy Support
Another mechanism for extending the functionality of the agent is to pass
selected requests (or selected varbinds) to another SNMP agent, which can
be running on the same host (presumably listening on a different port), or
on a remote system. This can be viewed either as the main agent delegating
requests to the remote one, or acting as a proxy for it. Use of this mech-
anism requires that the agent was built with support for the ucd-snmp/proxy
module (which is included as part of the default build configuration).

proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
will pass any incoming requests under OID to the agent listening on
the port specified by the transport address HOST. See the section
LISTENING ADDRESSES in the snmpd(8) manual page for more information
about the format of listening addresses.

Note: To proxy the entire MIB tree, use the OID .1.3 (not the top-
level .1)

The SNMPCMD_ARGS should provide sufficient version and administrative in-
formation to generate a valid SNMP request (see snmpcmd(1)).

Note: The proxied request will not use the administrative settings from
the original request.

If a CONTEXTNAME is specified, this will register the proxy delegation
within the named context in the local agent. Defining multiple proxy di-
rectives for the same OID but different contexts can be used to query sev-
eral remote agents through a single proxy, by specifying the appropriate
SNMPv3 context in the incoming request (or using suitable configured commu-
nity strings - see the com2sec directive).

Specifying the REMOID parameter will map the local MIB tree rooted at OID
to an equivalent subtree rooted at REMOID on the remote agent.

SMUX Sub-Agents
The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
with SMUX-based subagents (such as gated, zebra or quagga). Use of this
mechanism requires that the agent was built with support for the smux mod-
ule, which is not part of the default build environment, and must be ex-
plicitly included by specifying the '--with-mib-modules=smux' option to the
configure script when the package is first built.

Note: This extension protocol has been officially deprecated in
favour of AgentX (see below).

smuxpeer OID PASS
will register a subtree for SMUX-based processing, to be authenti-
cated using the password PASS. If a subagent (or "peer") connects
to the agent and registers this subtree then requests for OIDs
within it will be passed to that SMUX subagent for processing.

A suitable entry for an OSPF routing daemon (such as gated, zebra or
quagga) might be something like
smuxpeer .1.3.6.1.2.1.14 ospf_pass

smuxsocket <IPv4-address>
defines the IPv4 address for SMUX peers to communicate with the Net-
SNMP agent. The default is to listen on all IPv4 interfaces
("0.0.0.0"), unless the package has been configured with "--en-
able-local-smux" at build time, which causes it to only listen on
127.0.0.1 by default. SMUX uses the well-known TCP port 199.

Note the Net-SNMP agent will only operate as a SMUX master agent. It does
not support acting in an SMUX subagent role.

AgentX Sub-Agents
The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both master
and subagent roles. Use of this mechanism requires that the agent was
built with support for the agentx module (which is included as part of the
default build configuration), and also that this support is explicitly en-
abled (e.g. via the snmpd.conf file).

There are two directives specifically relevant to running as an AgentX mas-
ter agent:

master agentx
will enable the AgentX functionality and cause the agent to start
listening for incoming AgentX registrations. This can also be acti-
vated by specifying the '-x' command-line option (to specify an al-
ternative listening socket).

agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
Defines the permissions and ownership of the AgentX Unix Domain
socket, and the parent directories of this socket. SOCKPERMS and
DIRPERMS must be octal digits (see chmod(1) ). By default, this
socket will only be accessible to subagents which have the same
userid as the agent.

There is one directive specifically relevant to running as an AgentX sub-
agent:

agentXPingInterval NUM
will make the subagent try and reconnect every NUM seconds to the
master if it ever becomes (or starts) disconnected.

The remaining directives are relevant to both AgentX master and sub-agents:

agentXSocket [<transport-specifier>:]<transport-address>[,...]
defines the address the master agent listens at, or the subagent
should connect to. The default is the Unix Domain socket
"/var/agentx/master". Another common alternative is tcp:local-
host:705. See the section LISTENING ADDRESSES in the snmpd(8) man-
ual page for more information about the format of addresses.

Note: Specifying an AgentX socket does not automatically enable
AgentX functionality (unlike the '-x' command-line option).

agentXTimeout NUM
defines the timeout period (NUM seconds) for an AgentX request. De-
fault is 1 second. NUM also be specified with a suffix of one of s
(for seconds), m (for minutes), h (for hours), d (for days), or w
(for weeks).

agentXRetries NUM
defines the number of retries for an AgentX request. Default is 5
retries.

net-snmp ships with both C and Perl APIs to develop your own AgentX sub-
agent.

OTHER CONFIGURATION
override [-rw] OID TYPE VALUE
This directive allows you to override a particular OID with a dif-
ferent value (and possibly a different type of value). The -rw flag
will allow snmp SETs to modify its value as well. (note that if
you're overriding original functionality, that functionality will be
entirely lost. Thus SETS will do nothing more than modify the in-
ternal overridden value and will not perform any of the original
functionality intended to be provided by the MIB object. It's an
emulation only.) An example:

override sysDescr.0 octet_str "my own sysDescr"

That line will set the sysDescr.0 value to "my own sysDescr" as well
as make it modifiable with SNMP SETs as well (which is actually il-
legal according to the MIB specifications).

Note that care must be taken when using this. For example, if you
try to override a property of the 3rd interface in the ifTable with
a new value and later the numbering within the ifTable changes it's
index ordering you'll end up with problems and your modified value
won't appear in the right place in the table.

Valid TYPEs are: integer, uinteger, octet_str, object_id, counter,
null (for gauges, use "uinteger"; for bit strings, use "octet_str").
Note that setting an object to "null" effectively delete's it as be-
ing accessible. No VALUE needs to be given if the object type is
null.

More types should be available in the future.

If you're trying to figure out aspects of the various mib modules (possibly
some that you've added yourself), the following may help you spit out some
useful debugging information. First off, please read the snmpd manual page
on the -D flag. Then the following configuration snmpd.conf token, com-
bined with the -D flag, can produce useful output:

injectHandler HANDLER modulename [beforeThis]
This will insert new handlers into the section of the mib tree ref-
erenced by "modulename". If "beforeThis" is specified then the mod-
ule will be injected before the named module. This is useful for
getting a handler into the exact right position in the chain.

The types of handlers available for insertion are:

stash_cache
Caches information returned from the lower level. This
greatly helps the performance of the agent, at the cost of
caching the data such that it's no longer "live" for 30 sec-
onds (in the future, this will be configurable). Note that
this means snmpd will use more memory as well while the in-
formation is cached. Currently this only works for handlers
registered using the table_iterator support, which is only a
few mib tables. To use it, you need to make sure to install
it before the table_iterator point in the chain, so to do
this:

injectHandler stash_cache NAME table_iterator

If you want a table to play with, try walking the nsMod-
uleTable with and without this injected.

debug Prints out lots of debugging information when the
-Dhelper:debug flag is passed to the snmpd application.

read_only
Forces turning off write support for the given module.

serialize
If a module is failing to handle multiple requests properly
(using the new 5.0 module API), this will force the module to
only receive one request at a time.

bulk_to_next
If a module registers to handle getbulk support, but for some
reason is failing to implement it properly, this module will
convert all getbulk requests to getnext requests before the
final module receives it.

dontLogTCPWrappersConnects
If the snmpd was compiled with TCP Wrapper support, it logs every
connection made to the agent. This setting disables the log messages
for accepted connections. Denied connections will still be logged.

Figuring out module names
To figure out which modules you can inject things into, run snmpwalk
on the nsModuleTable which will give a list of all named modules
registered within the agent.

Internal Data tables
table NAME

add_row NAME INDEX(ES) VALUE(S)

NOTES
o The Net-SNMP agent can be instructed to re-read the various configu-
ration files, either via an snmpset assignment of integer(1) to
UCD-SNMP-MIB::versionUpdateConfig.0 (.1.3.6.1.4.1.2021.100.11.0), or
by sending a kill -HUP signal to the agent process.

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 en-
able the corresponding behaviour, or any of 0, no or false to dis-
able it. The default in each case is for the feature to be turned
off, so these directives are typically only used to enable the ap-
propriate behaviour.

EXAMPLE CONFIGURATION FILE
See the EXAMPLE.CONF file in the top-level source directory for a more de-
tailed example of how the above information is used in real examples.

FILES
/usr/local/etc/snmp/snmpd.conf

SEE ALSO
snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM-
PLE.conf, netsnmp_config_api(3).

V5.9.5.2 30 Jun 2010 SNMPD.CONF(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=snmpd.conf&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages