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