1SNMPD.CONF(5) Net-SNMP SNMPD.CONF(5)
2
6 snmpd.conf - configuration file for the Net-SNMP SNMP agent
7
9 The Net-SNMP agent uses one or more configuration files to control its
10 operation and the management information provided. These files
11 (snmpd.conf and snmpd.local.conf) can be located in one of several
12 locations, as described in the snmp_config(5) manual page.
13 The (perl) application snmpconf can be used to generate configuration
15 files for the most common agent requirements. See the snmpconf(1) man‐
16 ual page for more information, or try running the command:
17 snmpconf -g basic_setup
19 There are a large number of directives that can be specified, but these
21 mostly fall into four distinct categories:
22 · those controlling who can access the agent
24 · those configuring the information that is supplied by the agent
26 · those controlling active monitoring of the local system
28 · those concerned with extending the functionality of the agent.
30 Some directives don't fall naturally into any of these four categories,
32 but this covers the majority of the contents of a typical snmpd.conf
33 file. A full list of recognised directives can be obtained by running
34 the command:
35 snmpd -H
37
39 Although most configuration directives are concerned with the MIB
40 information supplied by the agent, there are a handful of directives
41 that control the behaviour of snmpd considered simply as a daemon pro‐
42 viding a network service.
43 agentaddress [<transport-specifier>:]<transport-address>[,...]
45 defines a list of listening addresses, on which to receive
46 incoming SNMP requests. See the section LISTENING ADDRESSES in
47 the snmpd(8) manual page for more information about the format
48 of listening addresses.
49 The default behaviour is to listen on UDP port 161 on all IPv4
51 interfaces.
52 agentgroup {GROUP|#GID}
54 changes to the specified group after opening the listening
55 port(s). This may refer to a group by name (GROUP), or a
56 numeric group ID starting with '#' (#GID).
57 agentuser {USER|#UID}
59 changes to the specified user after opening the listening
60 port(s). This may refer to a user by name (USER), or a numeric
61 user ID starting with '#' (#UID).
62 leave_pidfile yes
64 instructs the agent to not remove its pid file on shutdown.
65 Equivalent to specifying "-U" on the command line.
66 maxGetbulkRepeats NUM
68 Sets the maximum number of responses allowed for a single vari‐
69 able in a getbulk request. Set to 0 to enable the default and
70 set it to -1 to enable unlimited. Because memory is allocated
71 ahead of time, sitting this to unlimited is not considered safe
72 if your user population can not be trusted. A repeat number
73 greater than this will be truncated to this value.
74 This is set by default to -1.
76 maxGetbulkResponses NUM
78 Sets the maximum number of responses allowed for a getbulk
79 request. This is set by default to 100. Set to 0 to enable the
80 default and set it to -1 to enable unlimited. Because memory is
81 allocated ahead of time, sitting this to unlimited is not con‐
82 sidered safe if your user population can not be trusted.
83 In general, the total number of responses will not be allowed to
85 exceed the maxGetbulkResponses number and the total number
86 returned will be an integer multiple of the number of variables
87 requested times the calculated number of repeats allow to fit
88 below this number.
89 Also not that processing of maxGetbulkRepeats is handled first.
91 SNMPv3 Configuration - Real Security
93 SNMPv3 is added flexible security models to the SNMP packet structure
94 so that multiple security solutions could be used. SNMPv3 was original
95 defined with a "User-based Security Model" (USM) [RFC3414] that
96 required maintaining a SNMP-specific user database. This was later
97 determined to be troublesome to maintain and had some minor security
98 issues. The IETF has since added additional security models to tunnel
99 SNMP over SSH [RFC5592] and DTLS/TLS [RFC-to-be]. Net-SNMP contains
100 robust support for SNMPv3/USM, SNMPv3/TLS, and SNMPv3/DTLS. It con‐
101 tains partial support for SNMPv3/SSH as well but has not been as exten‐
102 sively tested. It also contains code for support for an experimental
103 Kerberos based SNMPv3 that never got standardized.
104 Hopefully more SNMP software and devices will eventually support SNMP
106 over (D)TLS or SSH, but it is likely that devices with original support
107 for SNMP will only contain support for USM users. If your network man‐
108 ager supports SNMP over (D)TLS or SNMP over SSH we suggest you use one
109 of these mechanisms instead of using USM, but as always with Net-SNMP
110 we give you the options to pick from so you can make the choice that is
111 best for you.
112 SNMPv3 generic parameters
114 These parameters are generic to all the forms of SNMPv3. The SNMPv3
115 protocol defines "engineIDs" that uniquely identify an agent. The
116 string must be consistent through time and should not change or con‐
117 flict with another agent's engineID. Ever. Internally, Net-SNMP by
118 default creates a unique engineID that is based off of the current sys‐
119 tem time and a random number. This should be sufficient for most users
120 unless you're embedding our agent in a device where these numbers won't
121 vary between boxes on the devices initial boot.
122 EngineIDs are used both as a "context" for selecting information
124 from the device and SNMPv3 with USM uses it to create unique
125 entries for users in its user table.
126 The Net-SNMP agent offers the following mechanisms for setting
128 the engineID, but again you should only use them if you know
129 what you're doing:
130 engineID STRING
132 specifies that the engineID should be built from the given text
133 STRING.
134 engineIDType 1|2|3
136 specifies that the engineID should be built from the IPv4
137 address (1), IPv6 address (2) or MAC address (3). Note that
138 changing the IP address (or switching the network interface
139 card) may cause problems.
140 engineIDNic INTERFACE
142 defines which interface to use when determining the MAC address.
143 If engineIDType 3 is not specified, then this directive has no
144 effect.
145 The default is to use eth0.
147 SNMPv3 over TLS
149 SNMPv3 may be tunneled over TLS and DTLS. TLS runs over TCP and DTLS
150 is the UDP equivalent. Wes Hardaker (the founder of Net-SNMP) per‐
151 formed a study and presented it at an IETF meeting that showed that TCP
152 based protocols are sufficient for stable networks but quickly becomes
153 a problem in unstable networks with even moderate levels of packet loss
154 (~ 20-30%). If you are going to use TLS or DTLS, you should use the
155 one appropriate for your networking environment. You should poten‐
156 tially turn them both on so your management system can access either
157 the UDP or the TCP port as needed.
158 Many of the configuration tokens described below are prefixed with a
160 '[snmp]' tag. If you place these tokens in your snmpd.conf file, this
161 take is required. See the snmp_config(5) manual page for the meaning
162 of this context switch.
163 [snmp] localCert <specifier>
165 This token defines the default X.509 public key to use as the
166 server's identity. It should either be a fingerprint or a file‐
167 name. To create a public key for use, please run the
168 "net-snmp-cert" utility which will help you create the required
169 certificate.
170 The default value for this is the certificate in the "snmpd"
172 named certificate file.
173 [snmp] tlsAlgorithms <algorithms>
175 This string will select the algorithms to use when negotiating
176 security during (D)TLS session establishment. See the openssl
177 manual page ciphers(1) for details on the format. Examples
178 strings include:
179 DEFAULT
181 ALL
182 HIGH
183 HIGH:!AES128-SHA
184 The default value is whatever openssl itself was configured
186 with.
187 [snmp] x059CRLFile
189 If you are using a Certificate Authority (CA) that publishes a
190 Certificate Revocation List (CRL) then this token can be used to
191 specify the location in the filesystem of a copy of the CRL
192 file. Note that Net-SNMP will not pull a CRL over http and this
193 must be a file, not a URL. Additionally, OpenSSL does not
194 reload a CRL file when it has changed so modifications or
195 updates to the file will only be noticed upon a restart of the
196 snmpd agent.
197 certSecName PRIORITY FINGERPRINT OPTIONS
200 OPTIONS can be one of <--sn SECNAME | --rfc822 | --dns | --ip |
201 --cn | --any>.
202 The certSecName token will specify how to map a certificate
204 field from the client's X.509 certificate to a SNMPv3 username.
205 Use the --sn SECNAME flag to directly specify a securityName for
206 a given certificate. The other flags extract a particular com‐
207 ponent of the certificate for use as a snmpv3 securityName.
208 These fields are one of: A SubjectAltName containing an rfc822
209 value (eg hardaker@net-snmp.org), A SubjectAltName containing a
210 dns name value (eg foo.net-snmp.org), an IP address (eg
211 192.0.2.1) or a common name "Wes Hardaker". The --any flag
212 specifies that any of the subjecAltName fields may be used.
213 Make sure once a securityName has been selected that it is given
214 authorization via the VACM controls discussed later in this man‐
215 ual page.
216 See the http://www.net-snmp.org/wiki/index.php/Using_DTLS web
218 page for more detailed instructions for setting up (D)TLS.
219 trustCert <specifier>
221 For X509 to properly verify a certificate, it should be verifi‐
222 able up until a trust anchor for it. This trust anchor is typi‐
223 cally a CA certificate but it could also be a self-signed cer‐
224 tificate. The "trustCert" token should be used to load specific
225 trust anchors into the verification engine.
226 SNMP over (D)TLS requires the use of the Transport Security Model
228 (TSM), so read the section on the usage of the Transport Security Model
229 as well. Make sure when you configure the VACM to accept connections
230 from (D)TLS that you use the "tsm" security model. E.G.:
231 rwuser -s tsm hardaker@net-snmp.org
233 SNMPv3 over SSH Support
235 To use SSH, you'll need to configure sshd to invoke the sshtosnmp pro‐
236 gram as well as configure the access control settings to allow access
237 through the tsm security model using the user name provided to snmpd by
238 the ssh transport.
239 SNMPv3 with the Transport Security Model (TSM)
241 The Transport Security Model [RFC5591] defines a SNMPv3 security system
242 for use with "tunneled" security protocols like TLS, DTLS and SSH. It
243 is a very simple security model that simply lets properly protected
244 packets to pass through into the snmp application. The transport is
245 required to pass a securityName to use to the TSM and the TSM may
246 optionally prefix this with a transport string (see below).
247 tsmUseTransportPrefix (1|yes|true|0|no|false)
249 If set to true, the TSM module will take every securityName
250 passed to it from the transports underneath and prefix it with a
251 string that specifically identities the transport it came from.
252 This is useful to avoid securityName clashes with transports
253 that generate identical security names. For example, if the ssh
254 security transport delivered the security name of "hardaker" for
255 a SSH connection and the TLS security transport also delivered
256 the security name of "hardaker" for a TLS connection then it
257 would be impossible to separate out these two users to provide
258 separate access control rights. With the tsmUseTransportPrefix
259 set to true, however, the securityNames would be prefixed appro‐
260 priately with one of: "tls:", "dtls:" or "ssh:".
261 SNMPv3 with the User-based Security Model (USM)
263 SNMPv3 was originally defined using the User-Based Security Model
264 (USM), which contains a private list of users and keys specific to the
265 SNMPv3 protocol. The operational community, however, declared it a
266 pain to manipulate yet another database and would prefer to use exist‐
267 ing infrastructure. To that end the IETF created the ISMS working
268 group to battle that problem, and the ISMS working group decided to
269 tunnel SNMP over SSH and DTLS to make use existing user and authentica‐
270 tion infrastructures.
271 SNMPv3 USM Users
273 To use the USM based SNMPv3-specific users, you'll need to create them.
274 It is recommended you use the net-snmp-config command to do this, but
275 you can also do it by directly specifying createUser directives your‐
276 self instead:
277 createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES]
279 [privpassphrase]
280 MD5 and SHA are the authentication types to use. DES and AES
282 are the privacy protocols to use. If the privacy passphrase is
283 not specified, it is assumed to be the same as the authentica‐
284 tion passphrase. Note that the users created will be useless
285 unless they are also added to the VACM access control tables
286 described above.
287 SHA authentication and DES/AES privacy require OpenSSL to be
289 installed and the agent to be built with OpenSSL support. MD5
290 authentication may be used without OpenSSL.
291 Warning: the minimum pass phrase length is 8 characters.
293 SNMPv3 users can be created at runtime using the snmpusm(1) com‐
295 mand.
296 Instead of figuring out how to use this directive and where to
298 put it (see below), just run "net-snmp-config --cre‐
299 ate-snmpv3-user" instead, which will add one of these lines to
300 the right place.
301 This directive should be placed into the /var/lib/net-
303 snmp/snmpd.conf file instead of the other normal locations. The
304 reason is that the information is read from the file and then
305 the line is removed (eliminating the storage of the master pass‐
306 word for that user) and replaced with the key that is derived
307 from it. This key is a localized key, so that if it is stolen
308 it can not be used to access other agents. If the password is
309 stolen, however, it can be.
310 If you need to localize the user to a particular EngineID (this
312 is useful mostly in the similar snmptrapd.conf file), you can
313 use the -e argument to specify an EngineID as a hex value (EG,
314 "0x01020304").
315 If you want to generate either your master or localized keys
317 directly, replace the given password with a hexstring (preceded
318 by a "0x") and precede the hex string by a -m or -l token
319 (respectively). EGs:
320 [these keys are *not* secure but are easy to visually parse for
322 counting purposes. Please generate random keys instead of using
323 these examples]
324 createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
326 createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
327 Due to the way localization happens, localized privacy keys are
329 expected to be the length needed by the algorithm (128 bits for
330 all supported algorithms). Master encryption keys, though, need
331 to be the length required by the authentication algorithm not
332 the length required by the encrypting algorithm (MD5: 16 bytes,
333 SHA: 20 bytes).
334
336 snmpd supports the View-Based Access Control Model (VACM) as defined in
337 RFC 2575, to control who can retrieve or update information. To this
338 end, it recognizes various directives relating to access control.
339 Traditional Access Control
341 Most simple access control requirements can be specified using the
342 directives rouser/rwuser (for SNMPv3) or rocommunity/rwcommunity (for
343 SNMPv1 or SNMPv2c).
344 rouser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
346 rwuser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
348 specify an SNMPv3 user that will be allowed read-only (GET and
349 GETNEXT) or read-write (GET, GETNEXT and SET) access respec‐
350 tively. By default, this will provide access to the full OID
351 tree for authenticated (including encrypted) SNMPv3 requests,
352 using the default context. An alternative minimum security
353 level can be specified using noauth (to allow unauthenticated
354 requests), or priv (to enforce use of encryption). The OID
355 field restricts access for that user to the subtree rooted at
356 the given OID, or the named view. An optional context can also
357 be specified, or "context*" to denote a context prefix. If no
358 context field is specified (or the token "*" is used), the
359 directive will match all possible contexts.
360 If SECMODEL is specified then it will be the security model
362 required for that user (note that identical user names may come
363 in over different security models and will be appropriately sep‐
364 arated via the access control settings). The default security
365 model is "usm" and the other common security models are likely
366 "tsm" when using (D)TLS or SSH support and "ksm" if the Kerberos
367 support has been compiled in.
368 rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
370 rwcommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
372 specify an SNMPv1 or SNMPv2c community that will be allowed
373 read-only (GET and GETNEXT) or read-write (GET, GETNEXT and SET)
374 access respectively. By default, this will provide access to
375 the full OID tree for such requests, regardless of where they
376 were sent from. The SOURCE token can be used to restrict access
377 to requests from the specified system(s) - see com2sec for the
378 full details. The OID field restricts access for that community
379 to the subtree rooted at the given OID, or named view. Contexts
380 are typically less relevant to community-based SNMP versions,
381 but the same behaviour applies here.
382 rocommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
384 rwcommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
386 are directives relating to requests received using IPv6 (if the
387 agent supports such transport domains). The interpretation of
388 the SOURCE, OID, VIEW and CONTEXT tokens are exactly the same as
389 for the IPv4 versions.
390 In each case, only one directive should be specified for a given SNMPv3
392 user, or community string. It is not appropriate to specify both
393 rouser and rwuser directives referring to the same SNMPv3 user (or
394 equivalent community settings). The rwuser directive provides all the
395 access of rouser (as well as allowing SET support). The same holds
396 true for the community-based directives.
397 More complex access requirements (such as access to two or more dis‐
399 tinct OID subtrees, or different views for GET and SET requests) should
400 use one of the other access control mechanisms. Note that if several
401 distinct communities or SNMPv3 users need to be granted the same level
402 of access, it would also be more efficient to use the main VACM config‐
403 uration directives.
404 VACM Configuration
406 The full flexibility of the VACM is available using four configuration
407 directives - com2sec, group, view and access. These provide direct
408 configuration of the underlying VACM tables.
409 com2sec [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
411 com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
413 map an SNMPv1 or SNMPv2c community string to a security name -
414 either from a particular range of source addresses, or globally
415 ("default"). A restricted source can either be a specific host‐
416 name (or address), or a subnet - represented as IP/MASK (e.g.
417 10.10.10.0/255.255.255.0), or IP/BITS (e.g. 10.10.10.0/24), or
418 the IPv6 equivalents.
419 The same community string can be specified in several separate
421 directives (presumably with different source tokens), and the
422 first source/community combination that matches the incoming
423 request will be selected. Various source/community combinations
424 can also map to the same security name.
425 If a CONTEXT is specified (using -Cn), the community string will
427 be mapped to a security name in the named SNMPv3 context. Other‐
428 wise the default context ("") will be used.
429 com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY
431 is the Unix domain sockets version of com2sec.
432 group GROUP {v1|v2c|usm|tsm|ksm} SECNAME
434 maps a security name (in the specified security model) into a
435 named group. Several group directives can specify the same
436 group name, allowing a single access setting to apply to several
437 users and/or community strings.
438 Note that groups must be set up for the two community-based mod‐
440 els separately - a single com2sec (or equivalent) directive will
441 typically be accompanied by two group directives.
442 view VNAME TYPE OID [MASK]
444 defines a named "view" - a subset of the overall OID tree. This
445 is most commonly a single subtree, but several view directives
446 can be given with the same view name (VNAME), to build up a more
447 complex collection of OIDs. TYPE is either included or
448 excluded, which can again define a more complex view (e.g by
449 excluding certain sensitive objects from an otherwise accessible
450 subtree).
451 MASK is a list of hex octets (optionally separated by '.' or
453 ':') with the set bits indicating which subidentifiers in the
454 view OID to match against. If not specified, this defaults to
455 matching the OID exactly (all bits set), thus defining a simple
456 OID subtree. So:
457 view iso1 included .iso 0xf0
458 view iso2 included .iso
459 view iso3 included .iso.org.dod.mgmt 0xf0
460 would all define the same view, covering the whole of the
462 'iso(1)' subtree (with the third example ignoring the subidenti‐
463 fiers not covered by the mask).
464 More usefully, the mask can be used to define a view covering a
466 particular row (or rows) in a table, by matching against the
467 appropriate table index value, but skipping the column subiden‐
468 tifier:
469 view ifRow4 included .1.3.6.1.2.1.2.2.1.0.4 0xff:a0
471 Note that a mask longer than 8 bits must use ':' to separate the
473 individual octets.
474 access GROUP CONTEXT {any|v1|v2c|usm|tsm|ksm} LEVEL PREFX READ WRITE
476 NOTIFY
477 maps from a group of users/communities (with a particular secu‐
478 rity model and minimum security level, and in a specific con‐
479 text) to one of three views, depending on the request being pro‐
480 cessed.
481 LEVEL is one of noauth, auth, or priv. PREFX specifies how CON‐
483 TEXT should be matched against the context of the incoming
484 request, either exact or prefix. READ, WRITE and NOTIFY speci‐
485 fies the view to be used for GET*, SET and TRAP/INFORM requests
486 (althought the NOTIFY view is not currently used). For v1 or
487 v2c access, LEVEL will need to be noauth.
488 Typed-View Configuration
490 The final group of directives extend the VACM approach into a more
491 flexible mechanism, which can be applied to other access control
492 requirements. Rather than the fixed three views of the standard VACM
493 mechanism, this can be used to configure various different view types.
494 As far as the main SNMP agent is concerned, the two main view types are
495 read and write, corresponding to the READ and WRITE views of the main
496 access directive. See the 'snmptrapd.conf(5)' man page for discussion
497 of other view types.
498 authcommunity TYPES COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
500 is an alternative to the rocommunity/rwcommunity directives.
501 TYPES will usually be read or read,write respectively. The view
502 specification can either be an OID subtree (as before), or a
503 named view (defined using the view directive) for greater flexi‐
504 bility. If this is omitted, then access will be allowed to the
505 full OID tree. If CONTEXT is specified, access is configured
506 within this SNMPv3 context. Otherwise the default context ("")
507 is used.
508 authuser TYPES [-s MODEL] USER [LEVEL [OID | -V VIEW [CONTEXT]]]
510 is an alternative to the rouser/rwuser directives. The fields
511 TYPES, OID, VIEW and CONTEXT have the same meaning as for auth‐
512 community.
513 authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW [CONTEXT]]]
515 is a companion to the authuser directive, specifying access for
516 a particular group (defined using the group directive as usual).
517 Both authuser and authgroup default to authenticated requests -
518 LEVEL can also be specified as noauth or priv to allow unauthen‐
519 ticated requests, or require encryption respectively. Both
520 authuser and authgroup directives also default to configuring
521 access for SNMPv3/USM requests - use the '-s' flag to specify an
522 alternative security model (using the same values as for access
523 above).
524 authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
526 also configures the access for a particular group, specifying
527 the name and type of view to apply. The MODEL and LEVEL fields
528 are interpreted in the same way as for authgroup. If CONTEXT is
529 specified, access is configured within this SNMPv3 context (or
530 contexts with this prefix if the CONTEXT field ends with '*').
531 Otherwise the default context ("") is used.
532 setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
534 is a direct equivalent to the original access directive, typi‐
535 cally listing the view types as read or read,write as appropri‐
536 ate. (or see 'snmptrapd.conf(5)' for other possibilities). All
537 other fields have the same interpretation as with access.
538
540 Most of the information reported by the Net-SNMP agent is retrieved
541 from the underlying system, or dynamically configured via SNMP SET
542 requests (and retained from one run of the agent to the next). How‐
543 ever, certain MIB objects can be configured or controlled via the
544 snmpd.conf(5) file.
545 System Group
547 Most of the scalar objects in the 'system' group can be configured in
548 this way:
549 sysLocation STRING
551 sysContact STRING
553 sysName STRING
555 set the system location, system contact or system name (sysLoca‐
556 tion.0, sysContact.0 and sysName.0) for the agent respectively.
557 Ordinarily these objects are writable via suitably authorized
558 SNMP SET requests. However, specifying one of these directives
559 makes the corresponding object read-only, and attempts to SET it
560 will result in a notWritable error response.
561 sysServices NUMBER
563 sets the value of the sysServices.0 object. For a host system,
564 a good value is 72 (application + end-to-end layers). If this
565 directive is not specified, then no value will be reported for
566 the sysServices.0 object.
567 sysDescr STRING
569 sysObjectID OID
571 sets the system description or object ID for the agent.
572 Although these MIB objects are not SNMP-writable, these direc‐
573 tives can be used by a network administrator to configure suit‐
574 able values for them.
575 Interfaces Group
577 interface NAME TYPE SPEED
578 can be used to provide appropriate type and speed settings for
579 interfaces where the agent fails to determine this information
580 correctly. TYPE is a type value as given in the IANAifType-MIB,
581 and can be specified numerically or by name (assuming this MIB
582 is loaded).
583 interface_fadeout TIMEOUT
585 specifies, for how long the agent keeps entries in ifTable after
586 appropriate interfaces have been removed from system (typically
587 various ppp, tap or tun interfaces). Timeout value is in sec‐
588 onds. Default value is 300 (=5 minutes).
589 interface_replace_old yes
591 can be used to remove already existing entries in ifTable when
592 an interface with the same name appears on the system. E.g. when
593 ppp0 interface is removed, it is still listed in the table for
594 interface_fadeout seconds. This option ensures, that the old
595 ppp0 interface is removed even before the interface_fadeout
596 timeour when new ppp0 (with different ifIndex) shows up.
597 Host Resources Group
599 This requires that the agent was built with support for the host module
600 (which is now included as part of the default build configuration on
601 the major supported platforms).
602 ignoreDisk STRING
604 controls which disk devices are scanned as part of populating
605 the hrDiskStorageTable (and hrDeviceTable). The HostRes imple‐
606 mentation code includes a list of disk device patterns appropri‐
607 ate for the current operating system, some of which may cause
608 the agent to block when trying to open the corresponding disk
609 devices. This might lead to a timeout when walking these
610 tables, possibly resulting in inconsistent behaviour. This
611 directive can be used to specify particular devices (either
612 individually or wildcarded) that should not be checked.
613 Note: Please consult the source (host/hr_disk.c) and check for
615 the Add_HR_Disk_entry calls relevant for a particular O/S
616 to determine the list of devices that will be scanned.
617 The pattern can include one or more wildcard expressions. See
619 snmpd.examples(5) for illustration of the wildcard syntax.
620 skipNFSInHostResources true
622 controls whether NFS and NFS-like file systems should be omitted
623 from the hrStorageTable (true or 1) or not (false or 0, which is
624 the default). If the Net-SNMP agent gets hung on NFS-mounted
625 filesystems, you can try setting this to '1'.
626 storageUseNFS [1|2]
628 controls how NFS and NFS-like file systems should be reported in
629 the hrStorageTable. as 'Network Disks' (1) or 'Fixed Disks' (2)
630 Historically, the Net-SNMP agent has reported such file systems
631 as 'Fixed Disks', and this is still the default behaviour. Set‐
632 ting this directive to '1' reports such file systems as ´Network
633 Disks', as required by the Host Resources MIB.
634 realStorageUnits
636 controlls how the agent reports hrStorageAllocationUnits,
637 hrStorageSize and hrStorageUsed in hrStorageTable. For big
638 storage drives with small allocation units the agent re-calcu‐
639 lates these values so they all fit Integer32 and hrStorageAllo‐
640 cationUnits x hrStorageSize gives real size of the storage.
641 Example:
643 Linux xfs 16TB filesystem with 4096 bytes large blocks
644 will be reported as hrStorageAllocationUnits = 8192 and
645 hrStorageSize = 2147483647, so 8192 x 2147483647 gives
646 real size of the filesystem (=16 TB).
647 Setting this directive to '1' turns off this calculation and the
649 agent reports real hrStorageAllocationUnits, but it might report
650 wrong hrStorageSize for big drives because the value won't fit
651 into Integer32. In this case, hrStorageAllocationUnits x hrStor‐
652 ageSize won't give real size of the storage.
653 Process Monitoring
655 The hrSWRun group of the Host Resources MIB provides information about
656 individual processes running on the local system. The prTable of the
657 UCD-SNMP-MIB complements this by reporting on selected services (which
658 may involve multiple processes). This requires that the agent was
659 built with support for the ucd-snmp/proc module (which is included as
660 part of the default build configuration).
661 proc NAME [MAX [MIN]]
663 monitors the number of processes called NAME (as reported by
664 "/usr/bin/ps -e") running on the local system.
665 If the number of NAMEd processes is less than MIN or greater
667 than MAX, then the corresponding prErrorFlag instance will be
668 set to 1, and a suitable description message reported via the
669 prErrMessage instance.
670 Note: This situation will not automatically trigger a trap to
672 report the problem - see the DisMan Event MIB section
673 later.
674 If neither MAX nor MIN are specified, they will default to
676 infinity and 1 respectively ("at least one"). If only MAX is
677 specified, MIN will default to 0 ("no more than MAX"). If MAX
678 is 0 (and MIN is not), this indicates infinity ("at least MIN").
679 If both MAX and MIN are 0, this indicates a process that should
680 not be running.
681 procfix NAME PROG ARGS
683 registers a command that can be run to fix errors with the given
684 process NAME. This will be invoked when the corresponding prE‐
685 rrFix instance is set to 1.
686 Note: This command will not be invoked automatically.
688 The procfix directive must be specified after the matching proc
690 directive, and cannot be used on its own.
691 If no proc directives are defined, then walking the prTable will fail
693 (noSuchObject).
694 Disk Usage Monitoring
696 This requires that the agent was built with support for the
697 ucd-snmp/disk module (which is included as part of the default build
698 configuration).
699 disk PATH [ MINSPACE | MINPERCENT% ]
701 monitors the disk mounted at PATH for available disk space.
702 Disks mounted after the agent has started will not be monitored,
703 unless includeAllDisks option is specified.
704 The minimum threshold can either be specified in kB (MINSPACE)
706 or as a percentage of the total disk (MINPERCENT% with a '%'
707 character), defaulting to 100kB if neither are specified. If
708 the free disk space falls below this threshold, then the corre‐
709 sponding dskErrorFlag instance will be set to 1, and a suitable
710 description message reported via the dskErrorMsg instance.
711 Note: This situation will not automatically trigger a trap to
713 report the problem - see the DisMan Event MIB section
714 later.
715 includeAllDisks MINPERCENT%
717 configures monitoring of all disks found on the system, using
718 the specified (percentage) threshold. The dskTable is dynami‐
719 cally updated, unmounted disks disappear from the table and
720 newly mounted disks are added to the table. The threshold for
721 individual disks can be adjusted using suitable disk directives
722 (which can come either before or after the includeAllDisks
723 directive).
724 Note: Whether disk directives appears before or after
726 includeAllDisks may affect the indexing of the dskTable.
727 Only one includeAllDisks directive should be specified - any
729 subsequent copies will be ignored.
730 The list of mounted disks will be determined from HOST-
732 RESOURCES-MIB::hrFSTable.
733 If neither any disk directives or includeAllDisks are defined, then
735 walking the dskTable will fail (noSuchObject).
736 Disk I/O Monitoring
738 This requires that the agent was built with support for the
739 ucd-snmp/diskio module (which is not included as part of the default
740 build configuration).
741 By default, all block devices known to the operating system are
743 included in the diskIOTable. On platforms other than Linux, this module
744 has no configuration directives.
745 On Linux systems, it is possible to exclude several classes of block
747 devices from the diskIOTable in order to avoid cluttering the table
748 with useless zero statistics for pseudo-devices that often are not in
749 use but are configured by default to exist in most recent Linux distri‐
750 butions.
751 diskio_exclude_fd yes
753 Excludes all Linux floppy disk block devices, whose names start
754 with "fd", e.g. "fd0"
755 diskio_exclude_loop yes
757 Excludes all Linux loopback block devices, whose names start
758 with "loop", e.g. "loop0"
759 diskio_exclude_ram yes
761 Excludes all LInux ramdisk block devices, whose names start with
762 "ram", e.g. "ram0"
763 On Linux systems, it is possible to report only explicitly whitelisted
765 devices. It may take significant amount of time to process diskIOTable
766 data on systems with tens of thousands of block devices and whitelist‐
767 ing only the important ones avoids large CPU consumption.
768 diskio <device>
770 Enables whitelisting of devices and adds the device to the
771 whitelist. Only explicitly whitelisted devices will be reported.
772 This option may be used multiple times.
773 System Load Monitoring
775 This requires that the agent was built with support for either the
776 ucd-snmp/loadave module or the ucd-snmp/memory module respectively
777 (both of which are included as part of the default build configura‐
778 tion).
779 load MAX1 [MAX5 [MAX15]]
781 monitors the load average of the local system, specifying
782 thresholds for the 1-minute, 5-minute and 15-minute averages.
783 If any of these loads exceed the associated maximum value, then
784 the corresponding laErrorFlag instance will be set to 1, and a
785 suitable description message reported via the laErrMessage
786 instance.
787 Note: This situation will not automatically trigger a trap to
789 report the problem - see the DisMan Event MIB section
790 later.
791 If the MAX15 threshold is omitted, it will default to the MAX5
793 value. If both MAX5 and MAX15 are omitted, they will default to
794 the MAX1 value. If this directive is not specified, all three
795 thresholds will default to a value of DEFMAXLOADAVE.
796 If a threshold value of 0 is given, the agent will not report
798 errors via the relevant laErrorFlag or laErrMessage instances,
799 regardless of the current load.
800 Unlike the proc and disk directives, walking the walking the laTable
802 will succeed (assuming the ucd-snmp/loadave module was configured into
803 the agent), even if the load directive is not present.
804 swap MIN
806 monitors the amount of swap space available on the local system.
807 If this falls below the specified threshold (MIN kB), then the
808 memErrorSwap object will be set to 1, and a suitable description
809 message reported via memSwapErrorMsg.
810 Note: This situation will not automatically trigger a trap to
812 report the problem - see the DisMan Event MIB section
813 later.
814 If this directive is not specified, the default threshold is 16 MB.
815 Log File Monitoring
817 This requires that the agent was built with support for either the
818 ucd-snmp/file or ucd-snmp/logmatch modules respectively (both of which
819 are included as part of the default build configuration).
820 file FILE [MAXSIZE]
822 monitors the size of the specified file (in kB). If MAXSIZE is
823 specified, and the size of the file exceeds this threshold, then
824 the corresponding fileErrorFlag instance will be set to 1, and a
825 suitable description message reported via the fileErrorMsg
826 instance.
827 Note: This situation will not automatically trigger a trap to
829 report the problem - see the DisMan Event MIB section
830 later.
831 Note: A maximum of 20 files can be monitored.
833 Note: If no file directives are defined, then walking the
835 fileTable will fail (noSuchObject).
836 logmatch NAME FILE CYCLETIME REGEX
838 monitors the specified file for occurances of the specified pat‐
839 tern REGEX. The file position is stored internally so the entire
840 file is only read initially, every subsequent pass will only
841 read the new lines added to the file since the last read.
842 NAME name of the logmatch instance (will appear as logMatch‐
844 Name under logMatch/logMatchTable/logMatchEntry/logMatch‐
845 Name in the ucd-snmp MIB tree)
846 FILE absolute path to the logfile to be monitored. Note that
848 this path can contain date/time directives (like in the
849 UNIX 'date' command). See the manual page for 'strftime'
850 for the various directives accepted.
851 CYCLETIME
853 time interval for each logfile read and internal variable
854 update in seconds. Note: an SNMPGET* operation will also
855 trigger an immediate logfile read and variable update.
856 REGEX the regular expression to be used. Note: DO NOT enclose
858 the regular expression in quotes even if there are spaces
859 in the expression as the quotes will also become part of
860 the pattern to be matched!
861 Example:
863 logmatch apache-GETs
865 /usr/local/apache/logs/access.log-%Y-%m-%d 60 GET.*HTTP.*
866 This logmatch instance is named 'apache-GETs', uses
868 'GET.*HTTP.*' as its regular expression and it will moni‐
869 tor the file named (assuming today is May 6th 2009):
870 '/usr/local/apache/logs/access.log-2009-05-06', tomorrow
871 it will look for 'access.log-2009-05-07'. The logfile is
872 read every 60 seconds.
873 Note: A maximum of 250 logmatch directives can be specified.
875 Note: If no logmatch directives are defined, then walking the
877 logMatchTable will fail (noSuchObject).
878
880 The usual behaviour of an SNMP agent is to wait for incoming SNMP
881 requests and respond to them - if no requests are received, an agent
882 will typically not initiate any actions. This section describes various
883 directives that can configure snmpd to take a more active role.
884 Notification Handling
886 trapcommunity STRING
887 defines the default community string to be used when sending
888 traps. Note that this directive must be used prior to any com‐
889 munity-based trap destination directives that need to use it.
890 trapsink HOST [COMMUNITY [PORT]]
892 trap2sink HOST [COMMUNITY [PORT]]
894 informsink HOST [COMMUNITY [PORT]]
896 define the address of a notification receiver that should be
897 sent SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifica‐
898 tions respectively. See the section LISTENING ADDRESSES in the
899 snmpd(8) manual page for more information about the format of
900 listening addresses. If COMMUNITY is not specified, the most
901 recent trapcommunity string will be used.
902 If the transport address does not include an explicit port spec‐
904 ification, then PORT will be used. If this is not specified,
905 the well known SNMP trap port (162) will be used.
906 Note: This mechanism is being deprecated, and the listening
908 port should be specified via the transport specification
909 HOST instead.
910 If several sink directives are specified, multiple copies of
912 each notification (in the appropriate formats) will be gener‐
913 ated.
914 Note: It is not normally appropriate to list two (or all three)
916 sink directives with the same destination.
917 trapsess [SNMPCMD_ARGS] HOST
919 provides a more generic mechanism for defining notification des‐
920 tinations. SNMPCMD_ARGS should be the command-line options
921 required for an equivalent snmptrap (or snmpinform) command to
922 send the desired notification. The option -Ci can be used (with
923 -v2c or -v3) to generate an INFORM notification rather than an
924 unacknowledged TRAP.
925 This is the appropriate directive for defining SNMPv3 trap
927 receivers. See http://www.net-snmp.org/tutorial/tutorial-5/com‐
928 mands/snmptrap-v3.html for more information about SNMPv3 notifi‐
929 cation behaviour.
930 authtrapenable {1|2}
932 determines whether to generate authentication failure traps
933 (enabled(1)) or not (disabled(2) - the default). Ordinarily the
934 corresponding MIB object (snmpEnableAuthenTraps.0) is read-
935 write, but specifying this directive makes this object read-
936 only, and attempts to set the value via SET requests will result
937 in a notWritable error response.
938 v1trapaddress HOST
940 defines the agent address, which is inserted into SNMPv1 TRAPs.
941 Arbitrary local IPv4 address is chosen if this option is
942 ommited. This option is useful mainly when the agent is visible
943 from outside world by specific address only (e.g. because of
944 network address translation or firewall).
945 DisMan Event MIB
947 The previous directives can be used to configure where traps should be
948 sent, but are not concerned with when to send such traps (or what traps
949 should be generated). This is the domain of the Event MIB - developed
950 by the Distributed Management (DisMan) working group of the IETF.
951 This requires that the agent was built with support for the dis‐
953 man/event module (which is now included as part of the default build
954 configuration for the most recent distribution).
955 Note: The behaviour of the latest implementation differs in
957 some minor respects from the previous code - nothing too
958 significant, but existing scripts may possibly need some
959 minor adjustments.
960 iquerySecName NAME
962 agentSecName NAME
964 specifies the default SNMPv3 username, to be used when making
965 internal queries to retrieve any necessary information (either
966 for evaluating the monitored expression, or building a notifica‐
967 tion payload). These internal queries always use SNMPv3, even
968 if normal querying of the agent is done using SNMPv1 or SNMPv2c.
969 Note that this user must also be explicitly created (createUser)
971 and given appropriate access rights (e.g. rouser). This direc‐
972 tive is purely concerned with defining which user should be used
973 - not with actually setting this user up.
974 monitor [OPTIONS] NAME EXPRESSION
976 defines a MIB object to monitor. If the EXPRESSION condition
977 holds (see below), then this will trigger the corresponding
978 event, and either send a notification or apply a SET assignment
979 (or both). Note that the event will only be triggered once,
980 when the expression first matches. This monitor entry will not
981 fire again until the monitored condition first becomes false,
982 and then matches again. NAME is an administrative name for this
983 expression, and is used for indexing the mteTriggerTable (and
984 related tables). Note also that such monitors use an internal
985 SNMPv3 request to retrieve the values being monitored (even if
986 normal agent queries typically use SNMPv1 or SNMPv2c). See the
987 iquerySecName token described above.
988 EXPRESSION
990 There are three types of monitor expression supported by the
991 Event MIB - existence, boolean and threshold tests.
992 OID | ! OID | != OID
994 defines an existence(0) monitor test. A bare OID speci‐
995 fies a present(0) test, which will fire when (an instance
996 of) the monitored OID is created. An expression of the
997 form ! OID specifies an absent(1) test, which will fire
998 when the monitored OID is delected. An expression of the
999 form != OID specifies a changed(2) test, which will fire
1000 whenever the monitored value(s) change. Note that there
1001 must be whitespace before the OID token.
1002 OID OP VALUE
1004 defines a boolean(1) monitor test. OP should be one of
1005 the defined comparison operators (!=, ==, <, <=, >, >=)
1006 and VALUE should be an integer value to compare against.
1007 Note that there must be whitespace around the OP token.
1008 A comparison such as OID !=0 will not be handled cor‐
1009 rectly.
1010 OID MIN MAX [DMIN DMAX]
1012 defines a threshold(2) monitor test. MIN and MAX are
1013 integer values, specifying lower and upper thresholds.
1014 If the value of the monitored OID falls below the lower
1015 threshold (MIN) or rises above the upper threshold (MAX),
1016 then the monitor entry will trigger the corresponding
1017 event.
1018 Note that the rising threshold event will only be re-
1020 armed when the monitored value falls below the lower
1021 threshold (MIN). Similarly, the falling threshold event
1022 will be re-armed by the upper threshold (MAX).
1023 The optional parameters DMIN and DMAX configure a pair of
1025 similar threshold tests, but working with the delta dif‐
1026 ferences between successive sample values.
1027 OPTIONS
1029 There are various options to control the behaviour of the moni‐
1030 tored expression. These include:
1031 -D indicates that the expression should be evaluated using
1033 delta differences between sample values (rather than the
1034 values themselves).
1035 -d OID
1037 -di OID
1039 specifies a discontinuity marker for validating delta
1040 differences. A -di object instance will be used exactly
1041 as given. A -d object will have the instance subidenti‐
1042 fiers from the corresponding (wildcarded) expression
1043 object appended. If the -I flag is specified, then there
1044 is no difference between these two options.
1045 This option also implies -D.
1047 -e EVENT
1049 specifies the event to be invoked when this monitor entry
1050 is triggered. If this option is not given, the monitor
1051 entry will generate one of the standard notifications
1052 defined in the DISMAN-EVENT-MIB.
1053 -I indicates that the monitored expression should be applied
1055 to the specified OID as a single instance. By default,
1056 the OID will be treated as a wildcarded object, and the
1057 monitor expanded to cover all matching instances.
1058 -i OID
1060 -o OID define additional varbinds to be added to the notifica‐
1062 tion payload when this monitor trigger fires. For a
1063 wildcarded expression, the suffix of the matched instance
1064 will be added to any OIDs specified using -o, while OIDs
1065 specified using -i will be treated as exact instances.
1066 If the -I flag is specified, then there is no difference
1067 between these two options.
1068 See strictDisman for details of the ordering of notifica‐
1070 tion payloads.
1071 -r FREQUENCY
1073 monitors the given expression every FREQUENCY, where FRE‐
1074 QUENCY is in seconds or optionally suffixed by one of s
1075 (for seconds), m (for minutes), h (for hours), d (for
1076 days), or w (for weeks). By default, the expression will
1077 be evaluated every 600s (10 minutes).
1078 -S indicates that the monitor expression should not be eval‐
1080 uated when the agent first starts up. The first evalua‐
1081 tion will be done once the first repeat interval has
1082 expired.
1083 -s indicates that the monitor expression should be evaluated
1085 when the agent first starts up. This is the default be‐
1086 haviour.
1087 Note: Notifications triggered by this initial evaluation
1089 will be sent before the coldStart trap.
1090 -u SECNAME
1092 specifies a security name to use for scanning the local
1093 host, instead of the default iquerySecName. Once again,
1094 this user must be explicitly created and given suitable
1095 access rights.
1096 notificationEvent ENAME NOTIFICATION [-m] [-i OID | -o OID ]*
1098 defines a notification event named ENAME. This can be triggered
1099 from a given monitor entry by specifying the option -e ENAME
1100 (see above). NOTIFICATION should be the OID of the NOTIFICA‐
1101 TION-TYPE definition for the notification to be generated.
1102 If the -m option is given, the notification payload will include
1104 the standard varbinds as specified in the OBJECTS clause of the
1105 notification MIB definition. This option must come after the
1106 NOTIFICATION OID (and the relevant MIB file must be available
1107 and loaded by the agent). Otherwise, these varbinds must be
1108 listed explicitly (either here or in the corresponding monitor
1109 directive).
1110 The -i OID and -o OID options specify additional varbinds to be
1112 appended to the notification payload, after the standard list.
1113 If the monitor entry that triggered this event involved a wild‐
1114 carded expression, the suffix of the matched instance will be
1115 added to any OIDs specified using -o, while OIDs specified using
1116 -i will be treated as exact instances. If the -I flag was spec‐
1117 ified to the monitor directive, then there is no difference
1118 between these two options.
1119 setEvent ENAME [-I] OID = VALUE
1121 defines a set event named ENAME, assigning the (integer) VALUE
1122 to the specified OID. This can be triggered from a given moni‐
1123 tor entry by specifying the option -e ENAME (see above).
1124 If the monitor entry that triggered this event involved a wild‐
1126 carded expression, the suffix of the matched instance will nor‐
1127 mally be added to the OID. If the -I flag was specified to
1128 either of the monitor or setEvent directives, the specified OID
1129 will be regarded as an exact single instance.
1130 strictDisman yes
1132 The definition of SNMP notifications states that the varbinds
1133 defined in the OBJECT clause should come first (in the order
1134 specified), followed by any "extra" varbinds that the notifica‐
1135 tion generator feels might be useful. The most natural approach
1136 would be to associate these mandatory varbinds with the notifi‐
1137 cationEvent entry, and append any varbinds associated with the
1138 monitor entry that triggered the notification to the end of this
1139 list. This is the default behaviour of the Net-SNMP Event MIB
1140 implementation.
1141 Unfortunately, the DisMan Event MIB specifications actually
1143 state that the trigger-related varbinds should come first, fol‐
1144 lowed by the event-related ones. This directive can be used to
1145 restore this strictly-correct (but inappropriate) behaviour.
1146 Note: Strict DisMan ordering may result in generating invalid
1148 notifications payload lists if the notificationEvent -n
1149 flag is used together with monitor -o (or -i) varbind
1150 options.
1151 If no monitor entries specify payload varbinds, then the setting
1153 of this directive is irrelevant.
1154 linkUpDownNotifications yes
1156 will configure the Event MIB tables to monitor the ifTable for
1157 network interfaces being taken up or down, and triggering a
1158 linkUp or linkDown notification as appropriate.
1159 This is exactly equivalent to the configuration:
1161 notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
1163 notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
1164 monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
1166 monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
1167 defaultMonitors yes
1169 will configure the Event MIB tables to monitor the various
1170 UCD-SNMP-MIB tables for problems (as indicated by the appropri‐
1171 ate xxErrFlag column objects).
1172 This is exactly equivalent to the configuration:
1174 monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
1176 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
1177 monitor -o extNames -o extOutput "extTable" extResult != 0
1178 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
1179 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
1180 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
1181 In both these latter cases, the snmpd.conf must also contain a iquery‐
1183 SecName directive, together with a corresponding createUser entry and
1184 suitable access control configuration.
1185 DisMan Schedule MIB
1187 The DisMan working group also produced a mechanism for scheduling par‐
1188 ticular actions (a specified SET assignment) at given times. This
1189 requires that the agent was built with support for the disman/schedule
1190 module (which is included as part of the default build configuration
1191 for the most recent distribution).
1192 There are three ways of specifying the scheduled action:
1194 repeat FREQUENCY OID = VALUE
1196 configures a SET assignment of the (integer) VALUE to the MIB
1197 instance OID, to be run every FREQUENCY seconds, where FREQUENCY
1198 is in seconds or optionally suffixed by one of s (for seconds),
1199 m (for minutes), h (for hours), d (for days), or w (for weeks).
1200 cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1202 configures a SET assignment of the (integer) VALUE to the MIB
1203 instance OID, to be run at the times specified by the fields
1204 MINUTE to WEEKDAY. These follow the same pattern as the equiva‐
1205 lent crontab(5) fields.
1206 Note: These fields should be specified as a (comma-separated)
1208 list of numeric values. Named values for the MONTH and
1209 WEEKDAY fields are not supported, and neither are value
1210 ranges. A wildcard match can be specified as '*'.
1211 The DAY field can also accept negative values, to indicate days
1213 counting backwards from the end of the month.
1214 at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1216 configures a one-shot SET assignment, to be run at the first
1217 matching time as specified by the fields MINUTE to WEEKDAY. The
1218 interpretation of these fields is exactly the same as for the
1219 cron directive.
1220 Data Delivery via Notfiications
1222 Note: this functionality is only available if the deliver/deliverByNo‐
1223 tify mib module was complied in to the agent
1224 In some situations it may be advantageous to deliver SNMP data over
1226 SNMP Notifications (TRAPs and INFORMs) rather than the typical process
1227 of having the manager issue requests for the data (via GETs and GET‐
1228 NEXTs). Reasons for doing this are numerous, but frequently corner
1229 cases. The most common reason for wanting this behaviour might be to
1230 monitor devices that reside behind NATs or Firewalls that prevent
1231 incoming SNMP traffic.
1232 It should be noted that although most management software is capable of
1234 logging notifications, very little (if any) management software will
1235 updated their "knowledge database" based on the contents of SNMP noti‐
1236 fications. IE, it won't (for example) update the interface traffic
1237 counter history that is used to produce graphs. Most larger network
1238 management packages have a separate database for storing data received
1239 via SNMP requests (GETs and GETNEXTs) vs those received from notifica‐
1240 tions. Researching the capabilities of your management station soft‐
1241 ware is required before assuming this functionality will solve your
1242 data delivery requirements.
1243 Notifications generated via this mechanism will be sent to the standard
1245 set of configured notification targets. See the "Notification Han‐
1246 dling" section of this document for further information.
1247 deliverByNotify [-p] [-m] [-s MAXSIZE] FREQUENCY OID
1249 This directive tells the SNMP agent to self-walk the OID, col‐
1250 lect all the data and send it out every FREQUENCY seconds, where
1251 FREQUENCY is in seconds or optionally suffixed by one of s (for
1252 seconds), m (for minutes), h (for hours), d (for days), or w
1253 (for weeks). By default scalars are included in the notifica‐
1254 tion that specify the how often the notification will be sent
1255 (unless the -p option is specified) and which message number of
1256 how many messages a particular notification is (unless -m is
1257 specified). To break the notifications into manageable packet
1258 sizes, use the -s flag to specify the approximate maximum number
1259 of bytes that a notification message should be limited to. If
1260 more than MAXSIZE of bytes is needed then multiple notifications
1261 will be sent to deliver the data. Note that the calculations
1262 for ensuring the maximum size is met are approximations and thus
1263 it can be absolutely guaranteed they'll be under that size, so
1264 leave a padding buffer if it is critical that you avoid fragmen‐
1265 tation. A value of -1 indicates force everything into a single
1266 message no matter how big it is.
1267 Example usage: the following will deliver the contents of the
1269 ifTable once an hour and the contents of the system group once
1270 every 2 hours:
1271 deliverByNotify 3600 ifTable
1273 deliverByNotify 7200 system
1274 deliverByNotifyMaxPacketSize SIZEINBYTES
1276 Sets the default notification size limit (see the -s flag
1277 above).
1278 deliverByNotifyOid OID
1280 deliverByNotifyFrequencyOid OID
1282 deliverByNotifyMessageNumberOid OID
1284 deliverByNotifyMaxMessageNumberOid OID
1286 These set the data OID that the notification will be sent under,
1287 the scalar OID, the message number OID, and the maximum message
1288 number OID. These default to objects in the NET-SNMP-PERI‐
1289 ODIC-NOTIFY-MIB.
1290
1292 One of the first distinguishing features of the original UCD suite was
1293 the ability to extend the functionality of the agent - not just by
1294 recompiling with code for new MIB modules, but also by configuring the
1295 running agent to report additional information. There are a number of
1296 techniques to support this, including:
1297 · running external commands (exec, extend, pass)
1299 · loading new code dynamically (embedded perl, dlmod)
1301 · communicating with other agents (proxy, SMUX, AgentX)
1303 Arbitrary Extension Commands
1305 The earliest extension mechanism was the ability to run arbitrary com‐
1306 mands or shell scripts. Such commands do not need to be aware of SNMP
1307 operations, or conform to any particular behaviour - the MIB structures
1308 are designed to accommodate any form of command output. Use of this
1309 mechanism requires that the agent was built with support for the
1310 ucd-snmp/extensible and/or agent/extend modules (which are both
1311 included as part of the default build configuration).
1312 exec [MIBOID] NAME PROG ARGS
1314 sh [MIBOID] NAME PROG ARGS
1316 invoke the named PROG with arguments of ARGS. By default the
1317 exit status and first line of output from the command will be
1318 reported via the extTable, discarding any additional output.
1319 Note: Entries in this table appear in the order they are read
1321 from the configuration file. This means that adding new
1322 exec (or sh) directives and restarting the agent, may
1323 affect the indexing of other entries.
1324 The PROG argument for exec directives must be a full path to a
1326 real binary, as it is executed via the exec() system call. To
1327 invoke a shell script, use the sh directive instead.
1328 If MIBOID is specified, then the results will be rooted at this
1330 point in the OID tree, returning the exit statement as
1331 MIBOID.100.0 and the entire command output in a pseudo-table
1332 based at MIBNUM.101 - with one 'row' for each line of output.
1333 Note: The layout of this "relocatable" form of exec (or sh)
1335 output does not strictly form a valid MIB structure.
1336 This mechanism is being deprecated - please see the
1337 extend directive (described below) instead.
1338 The agent does not cache the exit status or output of the exe‐
1340 cuted program.
1341 execfix NAME PROG ARGS
1343 registers a command that can be invoked on demand - typically to
1344 respond to or fix errors with the corresponding exec or sh
1345 entry. When the extErrFix instance for a given NAMEd entry is
1346 set to the integer value of 1, this command will be called.
1347 Note: This directive can only be used in combination with a
1349 corresponding exec or sh directive, which must be defined
1350 first. Attempting to define an unaccompanied execfix
1351 directive will fail.
1352 exec and sh extensions can only be configured via the snmpd.conf file.
1354 They cannot be set up via SNMP SET requests.
1355 extend [MIBOID] NAME PROG ARGS
1357 works in a similar manner to the exec directive, but with a num‐
1358 ber of improvements. The MIB tables (nsExtendConfigTable etc)
1359 are indexed by the NAME token, so are unaffected by the order in
1360 which entries are read from the configuration files. There are
1361 two result tables - one (nsExtendOutput1Table) containing the
1362 exit status, the first line and full output (as a single string)
1363 for each extend entry, and the other (nsExtendOutput2Table) con‐
1364 taining the complete output as a series of separate lines.
1365 If MIBOID is specified, then the configuration and result tables
1367 will be rooted at this point in the OID tree, but are otherwise
1368 structured in exactly the same way. This means that several sep‐
1369 arate extend directives can specify the same MIBOID root, with‐
1370 out conflicting.
1371 The exit status and output is cached for each entry individu‐
1373 ally, and can be cleared (and the caching behaviour configured)
1374 using the nsCacheTable.
1375 extendfix NAME PROG ARGS
1377 registers a command that can be invoked on demand, by setting
1378 the appropriate nsExtendRunType instance to the value run-com‐
1379 mand(3). Unlike the equivalent execfix, this directive does not
1380 need to be paired with a corresponding extend entry, and can
1381 appear on its own.
1382 Both extend and extendfix directives can be configured dynamically,
1384 using SNMP SET requests to the NET-SNMP-EXTEND-MIB.
1385 MIB-Specific Extension Commands
1387 The first group of extension directives invoke arbitrary commands, and
1388 rely on the MIB structure (and management applications) having the
1389 flexibility to accommodate and interpret the output. This is a conve‐
1390 nient way to make information available quickly and simply, but is of
1391 no use when implementing specific MIB objects, where the extension must
1392 conform to the structure of the MIB (rather than vice versa). The
1393 remaining extension mechanisms are all concerned with such MIB-specific
1394 situations - starting with "pass-through" scripts. Use of this mecha‐
1395 nism requires that the agent was built with support for the
1396 ucd-snmp/pass and ucd-snmp/pass_persist modules (which are both
1397 included as part of the default build configuration).
1398 pass [-p priority] MIBOID PROG
1400 will pass control of the subtree rooted at MIBOID to the speci‐
1401 fied PROG command. GET and GETNEXT requests for OIDs within
1402 this tree will trigger this command, called as:
1403 PROG -g OID
1405 PROG -n OID
1407 respectively, where OID is the requested OID. The PROG command
1409 should return the response varbind as three separate lines
1410 printed to stdout - the first line should be the OID of the
1411 returned value, the second should be its TYPE (one of the text
1412 strings integer, gauge, counter, timeticks, ipaddress, objectid,
1413 or string ), and the third should be the value itself.
1414 If the command cannot return an appropriate varbind - e.g the
1416 specified OID did not correspond to a valid instance for a GET
1417 request, or there were no following instances for a GETNEXT -
1418 then it should exit without producing any output. This will
1419 result in an SNMP noSuchName error, or a noSuchInstance excep‐
1420 tion.
1421 Note: The SMIv2 type counter64 and SNMPv2 noSuchObject
1423 exception are not supported.
1424 A SET request will result in the command being called as:
1426 PROG -s OID TYPE VALUE
1428 where TYPE is one of the tokens listed above, indicating the
1430 type of the value passed as the third parameter.
1431 If the assignment is successful, the PROG command should exit
1433 without producing any output. Errors should be indicated by
1434 writing one of the strings not-writable, or wrong-type to std‐
1435 out, and the agent will generate the appropriate error response.
1436 Note: The other SNMPv2 errors are not supported.
1438 In either case, the command should exit once it has finished
1440 processing. Each request (and each varbind within a single
1441 request) will trigger a separate invocation of the command.
1442 The default registration priority is 127. This can be changed
1444 by supplying the optional -p flag, with lower priority registra‐
1445 tions being used in preference to higher priority values.
1446 pass_persist [-p priority] MIBOID PROG
1448 will also pass control of the subtree rooted at MIBOID to the
1449 specified PROG command. However this command will continue to
1450 run after the initial request has been answered, so subsequent
1451 requests can be processed without the startup overheads.
1452 Upon initialization, PROG will be passed the string "PING\n" on
1454 stdin, and should respond by printing "PONG\n" to stdout.
1455 For GET and GETNEXT requests, PROG will be passed two lines on
1457 stdin, the command (get or getnext) and the requested OID. It
1458 should respond by printing three lines to stdout - the OID for
1459 the result varbind, the TYPE and the VALUE itself - exactly as
1460 for the pass directive above. If the command cannot return an
1461 appropriate varbind, it should print print "NONE\n" to stdout
1462 (but continue running).
1463 For SET requests, PROG will be passed three lines on stdin, the
1465 command (set) and the requested OID, followed by the type and
1466 value (both on the same line). If the assignment is successful,
1467 the command should print "DONE\n" to stdout. Errors should be
1468 indicated by writing one of the strings not-writable,
1469 wrong-type, wrong-length, wrong-value or inconsistent-value to
1470 stdout, and the agent will generate the appropriate error
1471 response. In either case, the command should continue running.
1472 The registration priority can be changed using the optional -p
1474 flag, just as for the pass directive.
1475 pass and pass_persist extensions can only be configured via the
1477 snmpd.conf file. They cannot be set up via SNMP SET requests.
1478 Embedded Perl Support
1480 Programs using the previous extension mechanisms can be written in any
1481 convenient programming language - including perl, which is a common
1482 choice for pass-through extensions in particular. However the Net-SNMP
1483 agent also includes support for embedded perl technology (similar to
1484 mod_perl for the Apache web server). This allows the agent to inter‐
1485 pret perl scripts directly, thus avoiding the overhead of spawning pro‐
1486 cesses and initializing the perl system when a request is received.
1487 Use of this mechanism requires that the agent was built with support
1489 for the embedded perl mechanism, which is not part of the default build
1490 environment. It must be explicitly included by specifying the
1491 '--enable-embedded-perl' option to the configure script when the pack‐
1492 age is first built.
1493 If enabled, the following directives will be recognised:
1495 disablePerl true
1497 will turn off embedded perl support entirely (e.g. if there are
1498 problems with the perl installation).
1499 perlInitFile FILE
1501 loads the specified initialisation file (if present) immediately
1502 before the first perl directive is parsed. If not explicitly
1503 specified, the agent will look for the default initialisation
1504 file /usr/share/snmp/snmp_perl.pl.
1505 The default initialisation file creates an instance of a Net‐
1507 SNMP::agent object - a variable $agent which can be used to reg‐
1508 ister perl-based MIB handler routines.
1509 perl EXPRESSION
1511 evaluates the given expression. This would typically register a
1512 handler routine to be called when a section of the OID tree was
1513 requested:
1514 perl use Data::Dumper;
1515 perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
1516 perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
1517 This expression could also source an external file:
1519 perl 'do /path/to/file.pl';
1520 or perform any other perl-based processing that might be
1522 required.
1523 Dynamically Loadable Modules
1525 Most of the MIBs supported by the Net-SNMP agent are implemented as C
1526 code modules, which were compiled and linked into the agent libraries
1527 when the suite was first built. Such implementation modules can also
1528 be compiled independently and loaded into the running agent once it has
1529 started. Use of this mechanism requires that the agent was built with
1530 support for the ucd-snmp/dlmod module (which is included as part of the
1531 default build configuration).
1532 dlmod NAME PATH
1534 will load the shared object module from the file PATH (an abso‐
1535 lute filename), and call the initialisation routine init_NAME.
1536 Note: If the specified PATH is not a fully qualified filename,
1538 it will be interpreted relative to
1539 /usr/lib(64)/snmp/dlmod, and .so will be appended to the
1540 filename.
1541 This functionality can also be configured using SNMP SET requests to
1543 the UCD-DLMOD-MIB.
1544 Proxy Support
1546 Another mechanism for extending the functionality of the agent is to
1547 pass selected requests (or selected varbinds) to another SNMP agent,
1548 which can be running on the same host (presumably listening on a dif‐
1549 ferent port), or on a remote system. This can be viewed either as the
1550 main agent delegating requests to the remote one, or acting as a proxy
1551 for it. Use of this mechanism requires that the agent was built with
1552 support for the ucd-snmp/proxy module (which is included as part of the
1553 default build configuration).
1554 proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
1556 will pass any incoming requests under OID to the agent listening
1557 on the port specified by the transport address HOST. See the
1558 section LISTENING ADDRESSES in the snmpd(8) manual page for more
1559 information about the format of listening addresses.
1560 Note: To proxy the entire MIB tree, use the OID .1.3 (not the
1562 top-level .1)
1563 The SNMPCMD_ARGS should provide sufficient version and administrative
1565 information to generate a valid SNMP request (see snmpcmd(1)).
1566 Note: The proxied request will not use the administrative settings
1568 from the original request.
1569 If a CONTEXTNAME is specified, this will register the proxy delegation
1571 within the named context in the local agent. Defining multiple proxy
1572 directives for the same OID but different contexts can be used to query
1573 several remote agents through a single proxy, by specifying the appro‐
1574 priate SNMPv3 context in the incoming request (or using suitable con‐
1575 figured community strings - see the com2sec directive).
1576 Specifying the REMOID parameter will map the local MIB tree rooted at
1578 OID to an equivalent subtree rooted at REMOID on the remote agent.
1579 SMUX Sub-Agents
1581 The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1582 with SMUX-based subagents (such as gated, zebra or quagga). Use of
1583 this mechanism requires that the agent was built with support for the
1584 smux module, which is not part of the default build environment, and
1585 must be explicitly included by specifying the '--with-mib-modules=smux'
1586 option to the configure script when the package is first built.
1587 Note: This extension protocol has been officially deprecated in
1589 favour of AgentX (see below).
1590 smuxpeer OID PASS
1592 will register a subtree for SMUX-based processing, to be authen‐
1593 ticated using the password PASS. If a subagent (or "peer") con‐
1594 nects to the agent and registers this subtree then requests for
1595 OIDs within it will be passed to that SMUX subagent for process‐
1596 ing.
1597 A suitable entry for an OSPF routing daemon (such as gated,
1599 zebra or quagga) might be something like
1600 smuxpeer .1.3.6.1.2.1.14 ospf_pass
1601 smuxsocket <IPv4-address>
1603 defines the IPv4 address for SMUX peers to communicate with the
1604 Net-SNMP agent. The default is to listen on all IPv4 interfaces
1605 ("0.0.0.0"), unless the package has been configured with
1606 "--enable-local-smux" at build time, which causes it to only
1607 listen on 127.0.0.1 by default. SMUX uses the well-known TCP
1608 port 199.
1609 Note the Net-SNMP agent will only operate as a SMUX master agent. It
1611 does not support acting in a SMUX subagent role.
1612 AgentX Sub-Agents
1614 The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both mas‐
1615 ter and subagent roles. Use of this mechanism requires that the agent
1616 was built with support for the agentx module (which is included as part
1617 of the default build configuration), and also that this support is
1618 explicitly enabled (e.g. via the snmpd.conf file).
1619 There are two directives specifically relevant to running as an AgentX
1621 master agent:
1622 master agentx
1624 will enable the AgentX functionality and cause the agent to
1625 start listening for incoming AgentX registrations. This can
1626 also be activated by specifying the '-x' command-line option (to
1627 specify an alternative listening socket).
1628 agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
1630 Defines the permissions and ownership of the AgentX Unix Domain
1631 socket, and the parent directories of this socket. SOCKPERMS
1632 and DIRPERMS must be octal digits (see chmod(1) ). By default
1633 this socket will only be accessible to subagents which have the
1634 same userid as the agent.
1635 There is one directive specifically relevant to running as an AgentX
1637 sub-agent:
1638 agentXPingInterval NUM
1640 will make the subagent try and reconnect every NUM seconds to
1641 the master if it ever becomes (or starts) disconnected.
1642 The remaining directives are relevant to both AgentX master and sub-
1644 agents:
1645 agentXSocket [<transport-specifier>:]<transport-address>[,...]
1647 defines the address the master agent listens at, or the subagent
1648 should connect to. The default is the Unix Domain socket
1649 "/var/agentx/master". Another common alternative is tcp:local‐
1650 host:705. See the section LISTENING ADDRESSES in the snmpd(8)
1651 manual page for more information about the format of addresses.
1652 Note: Specifying an AgentX socket does not automatically enable
1654 AgentX functionality (unlike the '-x' command-line
1655 option).
1656 agentXTimeout NUM
1658 defines the timeout period (NUM seconds) for an AgentX request.
1659 Default is 1 second. NUM also be specified with a suffix of one
1660 of s (for seconds), m (for minutes), h (for hours), d (for
1661 days), or w (for weeks).
1662 agentXRetries NUM
1664 defines the number of retries for an AgentX request. Default is
1665 5 retries.
1666 net-snmp ships with both C and Perl APIs to develop your own AgentX
1668 subagent.
1669
1671 override [-rw] OID TYPE VALUE
1672 This directive allows you to override a particular OID with a
1673 different value (and possibly a different type of value). The
1674 -rw flag will allow snmp SETs to modify it's value as well.
1675 (note that if you're overriding original functionality, that
1676 functionality will be entirely lost. Thus SETS will do nothing
1677 more than modify the internal overridden value and will not per‐
1678 form any of the original functionality intended to be provided
1679 by the MIB object. It's an emulation only.) An example:
1680 override sysDescr.0 octet_str "my own sysDescr"
1682 That line will set the sysDescr.0 value to "my own sysDescr" as
1684 well as make it modifiable with SNMP SETs as well (which is
1685 actually illegal according to the MIB specifications).
1686 Note that care must be taken when using this. For example, if
1688 you try to override a property of the 3rd interface in the
1689 ifTable with a new value and later the numbering within the
1690 ifTable changes it's index ordering you'll end up with problems
1691 and your modified value won't appear in the right place in the
1692 table.
1693 Valid TYPEs are: integer, uinteger, octet_str, object_id,
1695 counter, null (for gauges, use "uinteger"; for bit strings, use
1696 "octet_str"). Note that setting an object to "null" effectively
1697 delete's it as being accessible. No VALUE needs to be given if
1698 the object type is null.
1699 More types should be available in the future.
1701 If you're trying to figure out aspects of the various mib modules (pos‐
1703 sibly some that you've added yourself), the following may help you spit
1704 out some useful debugging information. First off, please read the
1705 snmpd manual page on the -D flag. Then the following configuration
1706 snmpd.conf token, combined with the -D flag, can produce useful output:
1707 injectHandler HANDLER modulename [beforeThis]
1709 This will insert new handlers into the section of the mib tree
1710 referenced by "modulename". If "beforeThis" is specified then
1711 the module will be injected before the named module. This is
1712 useful for getting a handler into the exact right position in
1713 the chain.
1714 The types of handlers available for insertion are:
1716 stash_cache
1718 Caches information returned from the lower level. This
1719 greatly help the performance of the agent, at the cost of
1720 caching the data such that its no longer "live" for 30
1721 seconds (in this future, this will be configurable).
1722 Note that this means snmpd will use more memory as well
1723 while the information is cached. Currently this only
1724 works for handlers registered using the table_iterator
1725 support, which is only a few mib tables. To use it, you
1726 need to make sure to install it before the table_iterator
1727 point in the chain, so to do this:
1728 injectHandler stash_cache NAME table_iterator
1730 If you want a table to play with, try walking the nsMod‐
1732 uleTable with and without this injected.
1733 debug Prints out lots of debugging information when the
1736 -Dhelper:debug flag is passed to the snmpd application.
1737 read_only
1740 Forces turning off write support for the given module.
1741 serialize
1744 If a module is failing to handle multiple requests prop‐
1745 erly (using the new 5.0 module API), this will force the
1746 module to only receive one request at a time.
1747 bulk_to_next
1750 If a module registers to handle getbulk support, but for
1751 some reason is failing to implement it properly, this
1752 module will convert all getbulk requests to getnext
1753 requests before the final module receives it.
1754 dontLogTCPWrappersConnects
1756 If the snmpd was compiled with TCP Wrapper support, it logs
1757 every connection made to the agent. This setting disables the
1758 log messages for accepted connections. Denied connections will
1759 still be logged.
1760 Figuring out module names
1762 To figure out which modules you can inject things into, run snm‐
1763 pwalk on the nsModuleTable which will give a list of all named
1764 modules registered within the agent.
1765 Internal Data tables
1767 table NAME
1768 add_row NAME INDEX(ES) VALUE(S)
1770
1772 o The Net-SNMP agent can be instructed to re-read the various con‐
1773 figuration files, either via an snmpset assignment of integer(1)
1774 to UCD-SNMP-MIB::versionUpdateConfig.0
1775 (.1.3.6.1.4.1.2021.100.11.0), or by sending a kill -HUP signal
1776 to the agent process.
1777 o All directives listed with a value of "yes" actually accept a
1779 range of boolean values. These will accept any of 1, yes or
1780 true to enable the corresponding behaviour, or any of 0, no or
1781 false to disable it. The default in each case is for the fea‐
1782 ture to be turned off, so these directives are typically only
1783 used to enable the appropriate behaviour.
1784
1786 See the EXAMPLE.CONF file in the top level source directory for a more
1787 detailed example of how the above information is used in real examples.
1788
1790 /etc/snmp/snmpd.conf
1791
1793 snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM‐
1794 PLE.conf, netsnmp_config_api(3).
1795V5.7.2 30 Jun 2010 SNMPD.CONF(5)