SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from Trustix net-snmp-5.4-2tr.i586.rpm

SNMPD.CONF

Section: Net-SNMP (5)
Updated: 08 Feb 2002
Index 

NAME

snmpd.conf - configuration file for the Net-SNMP SNMP agent 

DESCRIPTION

The Net-SNMP agent uses one or more configuration filesto control its operation and the management informationprovided.These files (snmpd.conf and snmpd.local.conf)can be located in one of several locations, as described in thesnmp_config(5) manual page.

The (perl) applicationsnmpconfcan be used to generate configuration files for themost common agent requirements. See thesnmpconf(1)manual page for more information, or try running thecommand:

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 fourcategories, but this covers the majority of the contents ofa typicalsnmpd.conffile.A full list of recognised directives can be obtained by runningthe command:

snmpd -H
 

AGENT BEHAVIOUR

Although most configuration directives are concerned with the MIBinformation supplied by the agent, there are a handful of directives thatcontrol the behaviour of snmpd considered simply as a daemonproviding a network service.
agentaddress [<transport-specifier>:]<transport-address>[,...]
defines a list of listening addresses, on which to receive incomingSNMP requests.See the section LISTENING ADDRESSESin thesnmpd(8)manual page for more information about the format of listeningaddresses.
The default behaviour is tolisten 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 IDstarting 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 IDstarting with '#' (#UID).
leave_pidfile yes
instructs the agent to not remove its pid file on shutdown. Equivalent tospecifying "-U" on the command line.
 

SNMPv3 Configuration

SNMPv3 requires an SNMP agent to define a unique "engine ID"in order to respond to SNMPv3 requests.This ID will normally be determined automatically, using two reasonablynon-predictable values - a (pseudo-)random number and the currentuptime in seconds. This is the recommended approach. However thecapacity exists to define the engineID in other ways:
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 directivehas no effect.
The default is to use eth0.
 

ACCESS CONTROL

snmpdsupports the View-Based Access Control Model (VACM) as defined in RFC2575, to control who can retrieve or update information. To this end,it recognizes various directives relating to access control.These fall into four basic groups. 

SNMPv3 Users

createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES] [privpassphrase]
MD5 and SHA are the authentication types to use. DES and AES are theprivacy protocols to use. If the privacypassphrase is not specified, it is assumed to be the same as theauthentication passphrase. Note that the users created will beuseless unless they are also added to the VACM access control tablesdescribed above.
SHA authentication and DES/AES privacy require OpenSSL to be installed andthe agent to be built with OpenSSL support. MD5 authentication may beused without OpenSSL.
Warning: the minimum pass phrase length is 8 characters.
SNMPv3 users can be created at runtime using thesnmpusm(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" 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 normallocations. The reason is that the information is read from the fileand then the line is removed (eliminating the storage of the masterpassword for that user) and replaced with the key that is derived fromit. This key is a localized key, so that if it is stolen it can notbe 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 isuseful mostly in the similar snmptrapd.conf file), you can use the -eargument 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 (preceeded by a "0x") andprecede the hex string by a -m or -l token (respectively). EGs:
[these keys are *not* secure but are easy to visually parse forcounting purposes.  Please generate random keys instead of usingthese examples]createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
Due to the way localization happens, localized privacy keys areexpected to be the length needed by the algorithm (128 bits for allsupported algorithms). Master encryption keys, though, need to be thelength required by the authentication algorithm not the lengthrequired by the encrypting algorithm (MD5: 16 bytes, SHA: 20 bytes).
 

Traditional Access Control

Most simple access control requirements can be specified using thedirectives rouser/rwuser (for SNMPv3) orrocommunity/rwcommunity (for SNMPv1 or SNMPv2c).
rouser USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
rwuser 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 respectively.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 ofencryption). The OID field restricts access for thatuser to the subtree rooted at the given OID, or the named view.An optional context can also be specified, or "context*" to denote a contextprefix. If no context field is specified (or the token "*" is used), thedirective will match all possible contexts.
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 torestrict access to requests from the specified system(s) - seecom2sec for the full details. The OID field restricts access forthat 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 exactlythe 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 rouserand rwuser directives referring to the same SNMPv3 user (or equivalentcommunity settings). The rwuser directive provides all the accessof rouser (as well as allowing SET support).The same holds true for the community-based directives.

More complex access requirements (such as access to twoor 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 communities or SNMPv3 users need to be grantedthe same level of access, it would also be more efficient to use the main VACMconfiguration directives. 

VACM Configuration

The full flexibility of the VACM is available using four configurationdirectives - 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 froma particular range of source addresses, or globally ("default").A restricted source can either be a specific hostname (or address), ora subnet - represented as IP/MASK (e.g. 10.10.10.0/255.255.255.0), orIP/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/communitycombination 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 bemapped to a security name in the named SNMPv3 context. Otherwise thedefault context ("") will be used.
com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY
is the Unix domain sockets version of com2sec.
group GROUP {v1|v2c|usm} SECNAME
maps a security name (in the specified security model) intoa named group. Several group directives can specify thesame 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 typically beaccompanied by two group directives.
view VNAME TYPE OID [MASK]
defines a named "view" - a subset of the overall OID tree. This is mostcommonly a single subtree, but several view directives can be givenwith the same view name (VNAME), to build up a more complex collection of OIDs.TYPE is either included or excluded, which can again definea more complex view (e.g by excluding certain sensitive objectsfrom an otherwise accessible subtree).
MASK is a list of hex octets (optionally separated by '.' or ':') withthe set bits indicating which subidentifiers in the view OID to matchagainst. 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 covered by the mask).
More usefully, the mask can be used to define a view covering a particularrow (or rows) in a table, by matching against the appropriate table indexvalue, 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 individualoctets.
access GROUP CONTEXT {any|v1|v2c|usm} LEVEL PREFX READ WRITE NOTIFY
maps from a group of users/communities (with a particular security modeland 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 ofthe incoming request, either exact or prefix.READ, WRITE and NOTIFY specifies the view to be used for GET*, SETand 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 flexiblemechanism, which can be applied to other access control requirements. Rather thanthe fixed three views of the standard VACM mechanism, this can be used toconfigure various different view types. As far as the main SNMP agent isconcerned, 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 theview 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 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 forauthcommunity.
authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW [CONTEXT]]]
is a companion to the authuser directive, specifying accessfor 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 allowunauthenticated requests, or require encryption respectively.Both authuser and authgroup directives also default to configuringaccess for SNMPv3/USM requests - use the '-s' flag to specify an alternativesecurity 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 fieldsare 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, typicallylisting 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 retrievedfrom the underlying system, or dynamically configured via SNMP SET requests(and retained from one run of the agent to the next).However, certain MIB objects can be configured or controlled viathe snmpd.conf(5) file. 

System Group

Most of the scalar objects in the 'system' group can be configuredin this way:
sysLocation STRING
sysContact STRING
sysName STRING
set the system location, system contact or system name(sysLocation.0, sysContact.0 and sysName.0) for the agent respectively.Ordinarily these objects are writeable via suitably authorized SNMP SETrequests. However, specifying one of these directives makes thecorresponding object read-only, and attempts to SET it will result ina 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 reportedfor 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 beused 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 forinterfaces 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).
 

Host Resources Group

This requires that the agent was built with support for thehost 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 thehrDiskStorageTable (and hrDeviceTable).The HostRes implementation code includes a list of disk device patternsappropriate for the current operating system, some of which may causethe agent to block when trying to open the corresponding disk devices.This might lead to a timeout when walking these tables, possiblyresulting in inconsistent behaviour. This directive can be usedto specify particular devices (either individually or wildcarded)that should not be checked.
Note:
Please consult the source (host/hr_disk.c) and check for theAdd_HR_Disk_entry calls relevant for a particular O/Sto 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 omittedfrom 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, youcan try setting this to '1'.
storageUseNFS [1|2]
controls how NFS and NFS-like file systems should be reportedin the hrStorageTable.as 'Network Disks' (1) or 'Fixed Disks' (2)Historically, the Net-SNMP agent has reported such file systemsas 'Fixed Disks', and this is still the default behaviour.Setting this directive to '1' reports such file systems as
 

Process Monitoring

The hrSWRun group of the Host Resources MIB providesinformation about individual processes running on the local system.The prTable of the UCD-SNMP-MIB complements this by reportingon selected services (which may involve multiple processes).This requires that the agent was built with support for theucd-snmp/proc module (which is included as part of thedefault 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 beset to 1, and a suitable description message reported via theprErrMessage instance.
Note:
This situation will not automatically trigger a trap to reportthe problem - see the DisMan Event MIB section later.
If neither MAX nor MIN are specified (or are both 0), they willdefault to infinity and 1 respectively ("at least one").If only MAX is specified, MIN will default to 0 ("no more than MAX").
procfix NAME PROG ARGS
registers a command that can be run to fix errors with the givenprocess NAME. This will be invoked when the correspondingprErrFix instance is set to 1.
Note:
This command will not be invoked automatically.
The procfix directive must be specified after the matchingproc directive, and cannot be used on its own.

If no proc directives are defined, then walking theprTable will fail (noSuchObject). 

Disk Usage Monitoring

This requires that the agent was built with support for theucd-snmp/disk module (which is included as part of thedefault 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) oras 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 dskErrorFlag instance will beset to 1, and a suitable description message reported via thedskErrorMsg instance.
Note:
This situation will not automatically trigger a trap to reportthe 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 individual disks can be adjusted using suitabledisk directives (which can come either before or after theincludeAllDisks directive).
Note:
Whether disk directives appears before or after includeAllDisks may affect the indexing of the dskTable.
Only one includeAllDisks directive should be specified - anysubsequent copies will be ignored.
The list of mounted disks will be determined when the agent starts using thesetmntent(3) and getmntent(3), or fopen(3) and getmntent(3), orsetfsent(3) and getfsent(3) system calls. If none of the abovesystem calls are available then the root partition "/"(which is assumed to exist on any UNIX based system) 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). 

System Load Monitoring

This requires that the agent was built with support for either theucd-snmp/loadave module or the ucd-snmp/memory modulerespectively (both of which are included as part of thedefault build configuration).
load MAX1 [MAX5 [MAX15]]
monitors the load average of the local system, specifyingthresholds 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 beset to 1, and a suitable description message reported via thelaErrMessage instance.
Note:
This situation will not automatically trigger a trap to reportthe 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 willdefault to a value of DEFMAXLOADAVE.

Unlike the proc and disk directives, walking thewalking the laTable will succeed (assuming theucd-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 reportthe 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 theucd-snmp/file or ucd-snmp/logmatch modules respectively(both of which are included as part of thedefault build configuration).
file FILE [MAXSIZE]
monitors the size of the specified file (in Kb).If MAXSIZE is specified, and the size of the file exceedsthis threshold, then the corresponding fileErrorFlaginstance will be set to 1, and a suitable description message reportedvia the fileErrorMsg instance.
Note:
This situation will not automatically trigger a trap to reportthe problem - see the DisMan Event MIB section later.
A maximum of 20 files can be monitored.

If no file directives are defined, then walking thefileTable will fail (noSuchObject).

logmatch NAME PATH CYCLETIME REGEX
monitors the specified file for occurances of the specifiedpattern REGEX.
A maximum of 50 files can be monitored.

If no logmatch directives are defined, then walking thelogMatchTable will fail (noSuchObject). 

ACTIVE MONITORING

The usual behaviour of an SNMP agent is to wait for incoming SNMP requestsand respond to them - if no requests are received, an agent will typicallynot initiate any actions. This section describes various directives thatcan 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-basedtrap 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 sentSNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifications respectively.See the section LISTENING ADDRESSESin thesnmpd(8)manual page for more information about the format of listeningaddresses.If COMMUNITY is not specified, the most recent trapcommunitystring will be used.
If the transport address does not include an explicitport specification, then PORT will be used.If this is not specified, the well known SNMP trapport (162) will be used.
Note:
This mechanism is being deprecated, and the listening portshould be specified via the transport specification HOST instead.
If several sink directives are specified, multiplecopies 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 [SNMPCMD_ARGS] HOST
provides a more generic mechanism for defining notification destinations.SNMPCMD_ARGSshould be the command-line options required for an equivalentsnmptrap (or snmpinform) command to send the desired notification.The option -Ci can be used (with -v2c or -v3) to generatean INFORM notification rather than an unacknowledged TRAP.
This is the appropriate directive for defining SNMPv3 trap receivers.Seehttp://www.net-snmp.org/tutorial/tutorial-5/commands/snmptrap-v3.htmlfor more information about SNMPv3 notification behaviour.
authtrapenable {1|2}
determines whether to generate authentication failure traps(enabled(1)) or not (disabled(2) - the default).Ordinarily the corresponding MIBobject (snmpEnableAuthenTraps.0) is read-write, but specifyingthis directive makes this object read-only, and attempts to set thevalue via SET requests will result in a notWritable error response.
 

DisMan Event MIB

The previous directives can be used to configure where traps shouldbe sent, but are not concerned with when to send such traps(or what traps should be generated). This is the domain of theEvent MIB - developed by the Distributed Management (DisMan)working group of the IETF.

This requires that the agent was built with support for thedisman/event module (which is now included as part of thedefault build configuration for the most recent distribution).

Note:
The behaviour of the latest implementation differs in some minorrespects from the previous code - nothing too significant, butexisting scripts may possibly need some minor adjustments.
iquerySecName NAME
agentSecName NAME
specifies the default SNMPv3 username, to be used when making internalqueries to retrieve any necessary information (either for evaluatingthe monitored expression, or building a notification payload).
Note that this user must also be explicitly created (createUser)and given appropriate access rights (e.g. rouser). Thisdirective is purely concerned with defining which user shouldbe 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 triggerthe corresponding event, and either send a notification or applya SET assignment (or both).Note that the event will only be triggered once, when the expressionfirst matches. This monitor entry will not fire again until themonitored condition first becomes false, and then matches again.NAME is an administrative name for this expression, and is used forindexing the mteTriggerTable (and related tables).
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 monitored OID is delected.An expression of the form !=OID specifies a changed(2) test,which will fire whenever the monitored value(s) change.
OID OP VALUE
defines a boolean(1) monitor test.OP should be one of the definedcomparison operators (!=, ==, <, <=, >, >=) and VALUE should be aninteger 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 willtrigger the corresponding event.
Note that the rising threshold event will only be re-armed whenthe monitored value falls below the lower threshold (MIN).Similarly, the falling threshold event will be re-armed bythe upper threshold (MAX).
The optional parameters DMIN and DMAX configure a pair ofsimilar threshold tests, but working with the deltadifferences between successive sample values.
OPTIONS
There are various options to control the behaviour of the monitoredexpression. These include:
-D
indicates that the expression should be evaluated using delta differencesbetween 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 subidentifiers from thecorresponding (wildcarded) expression object appended.If the -I flag is specified, then there is no differencebetween 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 oneof the standard notifications defined in the DISMAN-EVENT-MIB.
-I
indicates that the monitored expression should be applied to thespecified OID as a single instance. By default, the OID willbe treated as a wildcarded object, and the monitor expandedto cover all matching instances.
-i OID
-o OID
define additional varbinds to be added to the notification payloadwhen this monitor trigger fires.For a wildcarded expression, the suffix of the matched instancewill be added to any OIDs specified using -o, while OIDsspecified using -i will be treated as exact instances.If the -I flag is specified, then there is no differencebetween these two options.
See strictDisman for details of the ordering of notification payloads.
-r FREQUENCY
monitors the given expression every FREQUENCY seconds.By default, the expression will be evaluated every 600s (10 minutes).
-S
indicates that the monitor expression should not be evaluatedwhen the agent first starts up. The first evaluation will be doneonce the first repeat interval has expired.
-s
indicates that the monitor expression should be evaluated when theagent first starts up. This is the default behaviour.
Note:
Notifications triggered by this initial evaluation will be sentbefore 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 givensuitable access rights.
notificationEvent ENAME NOTIFICATION [-n] [-i OID | -o OID ]*
defines a notification event named ENAME.This can be triggered from a given monitor entry by specifyingthe option -e ENAME (see above).NOTIFICATION should be the OID of the NOTIFICATION-TYPE definitionfor the notification to be generated.
If the -n option is given, the notification payload willinclude the standard varbinds as specified in the OBJECTS clauseof 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 mustbe listed explicitly (either here or in the correspondingmonitor directive).
The -i OID and -o OID options specify additionalvarbinds to be appended to the notification payload, after thestandard list.If the monitor entry that triggered this event involved awildcarded expression, the suffix of the matched instancewill be added to any OIDs specified using -o, while OIDsspecified 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 options.
setEvent ENAME [-I] OID = VALUE
defines a set event named ENAME, assigning the (integer) VALUEto the specified OID.This can be triggered from a given monitor entry by specifyingthe option -e ENAME (see above).
If the monitor entry that triggered this event involved awildcarded expression, the suffix of the matched instancewill normally be added to the OID.If the -I flag was specified to either of themonitor or setEvent directives, thespecified OID will be regarded as an exact single instance.
strictDisman yes
The definition of SNMP notifications states that thevarbinds defined in the OBJECT clause should come first(in the order specified), followed by any "extra" varbindsthat the notification generator feels might be useful.The most natural approach would be to associate thesemandatory varbinds with the notificationEvent entry,and append any varbinds associated with the monitor entrythat 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 actuallystate that the trigger-related varbinds should come first,followed by the event-related ones. This directive can be used torestore this strictly-correct (but inappropriate) behaviour.
Note:
Strict DisMan ordering may result in generating invalid notificationspayload lists if the notificationEvent -n flag is used togetherwith 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 ifTablefor network interfaces being taken up or down, and triggeringa linkUp or linkDown notification as appropriate.
This is exactly equivalent to the configuration:
notificationEvent  linkUpTrap    linkUp   ifIndex ifAdminStatus ifOperStatusnotificationEvent  linkDownTrap  linkDown ifIndex ifAdminStatus ifOperStatusmonitor  -r 60 -e linkUpTrap   "Generate linkUp" ifOperStatus != 2monitor  -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
defaultMonitors yes
will configure the Event MIB tables to monitor the variousUCD-SNMP-MIB tables for problems (as indicated bythe appropriate xxErrFlag column objects).
This is exactly equivalent to the configuration:
monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0monitor -o extNames -o extOutput "extTable" extResult != 0monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0monitor -o laNames -o laErrMessage  "laTable" laErrorFlag != 0monitor -o fileName -o fileErrorMsg  "fileTable" fileErrorFlag != 0

In both these latter cases, the snmpd.conf must also contain aiquerySecName directive, together with a correspondingcreateUser entry and suitable access control configuration. 

DisMan Schedule MIB

The DisMan working group also produced a mechanism for schedulingparticular actions (a specified SET assignment) at given times.This requires that the agent was built with support for thedisman/schedule module (which is included as part of thedefault 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 instanceOID, to be run every FREQUENCY seconds.
cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
configures a SET assignment of the (integer) VALUE to the MIB instanceOID, 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 numericvalues. 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 countingbackwards 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 matchingtime as specified by the fields MINUTE to WEEKDAY. The interpretationof these fields is exactly the same as for the cron directive.
 

EXTENDING AGENT FUNCTIONALITY

One of the first distinguishing features of the original UCD suite wasthe ability to extend the functionality of the agent - not just byrecompiling with code for new MIB modules, but also by configuring the running agent toreport additional information. There are a number of techniques tosupport 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 arbitrarycommands or shell scripts. Such commands do not need to be aware ofSNMP operations, or conform to any particular behaviour - the MIBstructures are designed to accommodate any form of command output.Use of this mechanism requires that the agent was built with support for theucd-snmp/extensible and/or agent/extend modules (whichare 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 exitstatus and first line of output from the command will be reported viathe extTable, discarding any additional output.
Note:
Entries in this table appear in the order they are read from theconfiguration file. This means that adding new exec (or sh)directives and restarting the agent, may affect the indexing of otherentries.
The PROG argument for exec directives must be a full pathto 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 pointin the OID tree, returning the exit statement as MIBOID.100.0and the entire command output in a pseudo-table based atMIBNUM.101 - with one 'row' for each line of output.
Note:
The layout of this "relocatable" form of exec (or sh) outputdoes not strictly form a valid MIB structure. This mechanism is beingdeprecated - please see the extend directive (described below) instead.
In either case, the exit statement and output will be cached for 30safter the initial query. This cache can be flushed by a SET request ofthe integer value 1 to the MIB instance versionClearCache.0.
execfix NAME PROG ARGS
registers a command that can be invoked on demand - typically to respondto or fix errors with the corresponding exec or sh entry.When the extErrFix instance for a given NAMEd entry is set to theinteger value of 1, this command will be called.
Note:
This directive can only be used in combination with a correspondingexec 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 thesnmpd.conf file. They cannot be set up via SNMP SET requests.

extend [MIBOID] NAME PROG ARGS
works in a similar manner to the exec directive, but with a numberof improvements. The MIB tables (nsExtendConfigTableetc) are indexed by the NAME token, so are unaffected by the order inwhich entries 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 entry, and the other (nsExtendOutput2Table)containing the complete output as a series of separate lines.
If MIBOID is specified, then the configuration and result tables will be rootedat this point in the OID tree, but are otherwise structured in exactlythe same way. This means that several separate extenddirectives can specify the same MIBOID root, without conflicting.
The exit status and output is cached for each entry individually, andcan 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 theappropriate nsExtendRunType instance to the valuerun-command(3). Unlike the equivalent execfix,this directive does not need to be paired with a correspondingextend entry, and can appear on its own.

Both extend and extendfix directives can be configureddynamically, 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) havingthe flexibility to accommodate and interpret the output. This is aconvenient way to make information available quickly and simply, butis of no use when implementing specific MIB objects, where the extensionmust conform to the structure of the MIB (rather than vice versa).The remaining extension mechanisms are all concerned with suchMIB-specific situations - starting with "pass-through" scripts.Use of this mechanism requires that the agent was built with support for theucd-snmp/pass and ucd-snmp/pass_persist modules (whichare 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 specifiedPROG command. GET and GETNEXT requests for OIDs within this tree willtrigger 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 separatelines printed to stdout - the first line should be the OID of the returnedvalue, the second should be its TYPE (one of the text stringsinteger, gauge, counter, timeticks, ipaddress, objectid,orstring), and the third should be the value itself.
If the command cannot return an appropriate varbind - e.g the specifiedOID did not correspond to a valid instance for a GET request, or therewere no following instances for a GETNEXT - then it should exit withoutproducing any output. This will result in an SNMP noSuchNameerror, or a noSuchInstance exception.
Note:
The SMIv2 type counter64and SNMPv2 noSuchObject exception 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 thevalue passed as the third parameter.
If the assignment is successful, the PROG command should exit without producingany output. Errors should be indicated by writing one of the stringsnot-writable, or wrong-typeto 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 processing.Each request (and each varbind within a single request) will triggera separate invocation of the command.
The default registration priority is 127. This can bechanged by supplying the optional -p flag, with lower priorityregistrations 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 specifiedPROG command. However this command will continue to run after the initialrequest has been answered, so subsequent requests can be processed withoutthe 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 running).
For SET requests, PROG will be passed three lines on stdin,the command (set) and the requested OID,followed by the type and value (both on the same line).If the assignment is successful, the command should print"DONE\n" to stdout.Errors should be indicated by writing one of the stringsnot-writable, wrong-type,wrong-length,wrong-valueorinconsistent-valueto stdout,and the agent will generate 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 thesnmpd.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 convenientprogramming language - including perl, which is a common choice forpass-through extensions in particular. However the Net-SNMP agentalso includes support for embedded perl technology (similar tomod_perl for the Apache web server). This allows the agentto interpret perl scripts directly, thus avoiding the overhead ofspawning 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 embeddedperl mechanism, which is not part of the default build environment. Itmust be explicitly included by specifying the '--enable-embedded-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 problemswith the perl installation).
perlInitFile FILE
loads the specified initialisation file (if present)immediately before the first perl directive is parsed.If not explicitly specified, the agent will look for the defaultinitialisation file /usr/share/snmp/snmp_perl.pl.
The default initialisation filecreates an instance of a NetSNMP::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 ahandler routine to be called when a section of the OID tree wasrequested:
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 asC code modules, which were compiled and linked into the agent librarieswhen the suite was first built. Such implementation modules can also becompiled independently and loaded into the running agent once it hasstarted. Use of this mechanism requires that the agent was built with support for theucd-snmp/dlmod module (which is included as part of the defaultbuild configuration).
dlmod NAME PATH
will load the shared object module from the file PATH (an absolutefilename), and call the initialisation routine init_NAME.
Note:
If the specified PATH is not a fully qualified filename, it willbe interpreted relative to /usr/lib/snmp/dlmod, and .sowill be appended to the filename.

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

Proxy Support

Another mechanism for extending the functionality of the agentis to pass selected requests (or selected varbinds) to anotherSNMP agent, which can be running on the same host (presumablylistening on a different port), or on a remote system.This can be viewed either as the main agent delegating requests tothe remote one, or acting as a proxy for it.Use of this mechanism requires that the agent was built with support for theucd-snmp/proxy module (which is included as part of thedefault build configuration).
proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
will pass any incoming requests under OID to the agent listeningon the port specified by the transport address HOST.See the section LISTENING ADDRESSESin thesnmpd(8)manual page for more information about the format of listeningaddresses.
Note:
To proxy the entire MIB tree, use the OID .1.3(not the top-level .1)

The SNMPCMD_ARGS should provide sufficient version andadministrative information to generate a valid SNMP request(see snmpcmd(1)).

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

If a CONTEXTNAME is specified, this will register the proxydelegation within the named context in the local agent.Defining multiple proxy directives for the same OID butdifferent contexts can be used to query several remote agentsthrough a single proxy, by specifying the appropriate SNMPv3context in the incoming request (or using suitable configuredcommunity strings - see the com2sec directive).

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

SMUX Sub-Agents

The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicatewith SMUX-based subagents (such as gated, zebra or quagga).Use of this mechanism requires that the agent was built with support for thesmux module, which is not part of the default build environment, andmust be explicitly 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 infavour of AgentX (see below).
smuxpeer OID PASS
will register a subtree for SMUX-based processing, to beauthenticated using the password PASS. If a subagent(or "peer") connects to the agent and registers this subtreethen requests for OIDs within it will be passed to thatSMUX 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 "--enable-local-smux" at build time, which causes it to only listen on 127.0.0.1 by default. SMUX uses the well-knownTCP port 199.

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

AgentX Sub-Agents

The Net-SNMP agent supports the AgentX protocol (RFC 2741) inboth master and subagent roles.Use of this mechanism requires that the agent was built with support for theagentx module (which is included as part of thedefault build configuration), and also that this support isexplicitly enabled (e.g. via the snmpd.conf file).

There are two directives specifically relevant to running asan AgentX master agent:

master agentx
will enable the AgentX functionality and cause the agent tostart listening for incoming AgentX registrations.This can also be activated by specifying the '-x' command-lineoption (to specify an alternative 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 asan AgentX sub-agent:

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

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

agentXSocket [<transport-specifier>:]<transport-address>[,...]
defines the address the master agent listens at, or the subagentshould connect to.The default is the Unix Domain socket "/var/agentx/master".Another common alternative is tcp:localhost:705.See the sectionLISTENING ADDRESSESin thesnmpd(8)manual page for more information about the format of addresses.
Note:
Specifying an AgentX socket does not automatically enableAgentX functionality (unlike the '-x' command-line option).
agentXTimeout NUM
defines the timeout period (NUM seconds) for an AgentX request.Default is 1 second.
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 AgentXsubagent. 

OTHER CONFIGURATION

override [-rw] OID TYPE VALUE
This directive allows you to override a particular OID with adifferent value (and possibly a different type of value). The -rwflag will allow snmp SETs to modify it's value as well. (note that ifyou're overriding original functionality, that functionality will beentirely lost. Thus SETS will do nothing more than modify theinternal overridden value and will not perform any of the originalfunctionality intended to be provided by the MIB object. It's anemulation only.) An example:
override sysDescr.0 octet_str "my own sysDescr"
That line will set the sysDescr.0 value to "my own sysDescr" as wellas make it modifiable with SNMP SETs as well (which is actuallyillegal according to the MIB specifications).
Note that care must be taken when using this. For example, if you tryto override a property of the 3rd interface in the ifTable with a newvalue and later the numbering within the ifTable changes it's indexordering you'll end up with problems and your modified value won'tappear 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 beingaccessible. 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 youspit out some useful debugging information. First off, please readthe snmpd manual page on the -D flag. Then the followingconfiguration snmpd.conf token, combined with the -D flag, can produceuseful output:

injectHandler HANDLER modulename
This will insert new handlers into the section of the mib treereferenced by "modulename". The types of handlers available forinsertion are:
stash_cache
Caches information returned from the lower level. Thisgreatly help the performance of the agent, at the costof caching the data such that its no longer "live" for30 seconds (in this future, this will be configurable).Note that this means snmpd will use more memory as wellwhile the information is cached. Currently this onlyworks for handlers registered using the table_iteratorsupport, which is only a few mib tables. To use it,you need to make sure to install it before thetable_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 thensModuleTable with and without this injected.

debug
Prints out lots of debugging informati