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 (sn‐
11 mpd.conf and snmpd.local.conf) can be located in one of several loca‐
12 tions, 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 in‐
40 formation supplied by the agent, there are a handful of directives that
41 control the behaviour of snmpd considered simply as a daemon providing
42 a network service.
43 agentaddress [<transport-specifier>:]<transport-address>[,...]
45 defines a list of listening addresses, on which to receive in‐
46 coming 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 nu‐
56 meric 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 re‐
79 quest. 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 re‐
86 turned 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 "in‐
112 clude_ifmib_iface_prefix eth dummy lo" will include only inter‐
113 faces with these prefixes and ignore all others for IF-MIB pro‐
114 cessing. If regex support is compiled in, each of the prefixes
115 is a regular expression (which is not permitted to contain a
116 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 re‐
125 quired maintaining a SNMP-specific user database. This was later de‐
126 termined to be troublesome to maintain and had some minor security is‐
127 sues. 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 en‐
154 tries 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 ad‐
166 dress (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 up‐
224 dates to the file will only be noticed upon a restart of the sn‐
225 mpd 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 op‐
275 tionally 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 ac‐
316 cess 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 --create-sn‐
330 mpv3-user" instead, which will add one of these lines to the
331 right place.
332 This directive should be placed into the /var/lib/net-snmp/sn‐
334 mpd.conf file instead of the other normal locations. The reason
335 is that the information is read from the file and then the line
336 is removed (eliminating the storage of the master password for
337 that user) and replaced with the key that is derived from it.
338 This key is a localized key, so that if it is stolen it can not
339 be used to access other agents. If the password is stolen, how‐
340 ever, 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 di‐
348 rectly, replace the given password with a hexstring (preceded by
349 a "0x") and precede the hex string by a -m or -l token (respec‐
350 tively). 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 di‐
373 rectives rouser/rwuser (for SNMPv3) or rocommunity/rwcommunity (for SN‐
374 MPv1 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 di‐
390 rective will match all possible contexts.
391 If SECMODEL is specified then it will be the security model re‐
393 quired for that user (note that identical user names may come in
394 over different security models and will be appropriately sepa‐
395 rated 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 re‐
463 quest 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 ex‐
488 cluded, which can again define a more complex view (e.g by ex‐
489 cluding 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 ap‐
507 propriate table index value, but skipping the column subidenti‐
508 fier:
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 re‐
524 quest, either exact or prefix. READ, WRITE and NOTIFY specifies
525 the view to be used for GET*, SET and TRAP/INFORM requests (al‐
526 thought the NOTIFY view is not currently used). For v1 or v2c
527 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 re‐
532 quirements. 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 au‐
560 thuser and authgroup directives also default to configuring ac‐
561 cess 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 re‐
582 quests (and retained from one run of the agent to the next). However,
583 certain MIB objects can be configured or controlled via the sn‐
584 mpd.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. Al‐
612 though these MIB objects are not SNMP-writable, these directives
613 can be used by a network administrator to configure suitable
614 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 ta‐
650 bles, possibly resulting in inconsistent behaviour. This direc‐
651 tive can be used to specify particular devices (either individu‐
652 ally 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 in‐
716 finity 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 di‐
763 rective).
764 Note: Whether disk directives appears before or after in‐
766 cludeAllDisks 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-RE‐
772 SOURCES-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 in‐
783 cluded 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 ac‐
805 cepted 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 ac‐
811 ceptlist. Only explicitly acceptlisted devices will be reported.
812 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 in‐
826 stance.
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 in‐
866 stance.
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 /usr/local/apache/logs/ac‐
905 cess.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 re‐
921 quests and respond to them - if no requests are received, an agent will
922 typically not initiate any actions. This section describes various di‐
923 rectives 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 re‐
977 quired 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 re‐
989 ceivers. 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 ex‐
996 cluded, 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 (en‐
1006 abled(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 om‐
1015 mited. 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 in‐
1088 teger values, specifying lower and upper thresholds. If
1089 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 ob‐
1118 ject 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 de‐
1127 fined 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 ex‐
1157 pired.
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 be‐
1193 tween 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 ei‐
1203 ther 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 op‐
1225 tions.
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 re‐
1264 quires 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 in‐
1306 coming 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 re‐
1369 compiling 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 in‐
1386 cluded 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 af‐
1398 fect 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 MI‐
1406 BOID.100.0 and the entire command output in a pseudo-table based
1407 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 ex‐
1412 tend 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 en‐
1420 try. When the extErrFix instance for a given NAMEd entry is set
1421 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 di‐
1426 rective 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 ex‐
1447 tend 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 ap‐
1466 pear on its own.
1467 Both extend and extendfix directives can be configured dynamically, us‐
1469 ing 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 re‐
1478 maining 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 in‐
1482 cluded 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 re‐
1496 turned 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 re‐
1506 sult in an SNMP noSuchName error, or a noSuchInstance exception.
1507 Note: The SMIv2 type counter64 and SNMPv2 noSuchObject
1509 exception are not supported.
1510 A SET request will result in the command being called as:
1512 PROG -s OID TYPE VALUE
1514 where TYPE is one of the tokens listed above, indicating the
1516 type of the value passed as the third parameter.
1517 If the assignment is successful, the PROG command should exit
1519 without producing any output. Errors should be indicated by
1520 writing one of the strings not-writable, or wrong-type to std‐
1521 out, and the agent will generate the appropriate error response.
1522 Note: The other SNMPv2 errors are not supported.
1524 In either case, the command should exit once it has finished
1526 processing. Each request (and each varbind within a single re‐
1527 quest) will trigger a separate invocation of the command.
1528 The default registration priority is 127. This can be changed
1530 by supplying the optional -p flag, with lower priority registra‐
1531 tions being used in preference to higher priority values.
1532 pass_persist [-p priority] MIBOID PROG
1534 will also pass control of the subtree rooted at MIBOID to the
1535 specified PROG command. However this command will continue to
1536 run after the initial request has been answered, so subsequent
1537 requests can be processed without the startup overheads.
1538 Upon initialization, PROG will be passed the string "PING\n" on
1540 stdin, and should respond by printing "PONG\n" to stdout.
1541 For GET and GETNEXT requests, PROG will be passed two lines on
1543 stdin, the command (get or getnext) and the requested OID. It
1544 should respond by printing three lines to stdout - the OID for
1545 the result varbind, the TYPE and the VALUE itself - exactly as
1546 for the pass directive above. If the command cannot return an
1547 appropriate varbind, it should print print "NONE\n" to stdout
1548 (but continue running).
1549 For SET requests, PROG will be passed three lines on stdin, the
1551 command (set) and the requested OID, followed by the type and
1552 value (both on the same line). If the assignment is successful,
1553 the command should print "DONE\n" to stdout. Errors should be
1554 indicated by writing one of the strings not-writable,
1555 wrong-type, wrong-length, wrong-value or inconsistent-value to
1556 stdout, and the agent will generate the appropriate error re‐
1557 sponse. In either case, the command should continue running.
1558 The registration priority can be changed using the optional -p
1560 flag, just as for the pass directive.
1561 pass and pass_persist extensions can only be configured via the sn‐
1563 mpd.conf file. They cannot be set up via SNMP SET requests.
1564 Embedded Perl Support
1566 Programs using the previous extension mechanisms can be written in any
1567 convenient programming language - including perl, which is a common
1568 choice for pass-through extensions in particular. However the Net-SNMP
1569 agent also includes support for embedded perl technology (similar to
1570 mod_perl for the Apache web server). This allows the agent to inter‐
1571 pret perl scripts directly, thus avoiding the overhead of spawning pro‐
1572 cesses and initializing the perl system when a request is received.
1573 Use of this mechanism requires that the agent was built with support
1575 for the embedded perl mechanism, which is not part of the default build
1576 environment. It must be explicitly included by specifying the '--en‐
1577 able-embedded-perl' option to the configure script when the package is
1578 first built.
1579 If enabled, the following directives will be recognised:
1581 disablePerl true
1583 will turn off embedded perl support entirely (e.g. if there are
1584 problems with the perl installation).
1585 perlInitFile FILE
1587 loads the specified initialisation file (if present) immediately
1588 before the first perl directive is parsed. If not explicitly
1589 specified, the agent will look for the default initialisation
1590 file /usr/share/snmp/snmp_perl.pl.
1591 The default initialisation file creates an instance of a Net‐
1593 SNMP::agent object - a variable $agent which can be used to reg‐
1594 ister perl-based MIB handler routines.
1595 perl EXPRESSION
1597 evaluates the given expression. This would typically register a
1598 handler routine to be called when a section of the OID tree was
1599 requested:
1600 perl use Data::Dumper;
1601 perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
1602 perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
1603 This expression could also source an external file:
1605 perl 'do /path/to/file.pl';
1606 or perform any other perl-based processing that might be re‐
1608 quired.
1609 Dynamically Loadable Modules
1611 Most of the MIBs supported by the Net-SNMP agent are implemented as C
1612 code modules, which were compiled and linked into the agent libraries
1613 when the suite was first built. Such implementation modules can also
1614 be compiled independently and loaded into the running agent once it has
1615 started. Use of this mechanism requires that the agent was built with
1616 support for the ucd-snmp/dlmod module (which is included as part of the
1617 default build configuration).
1618 dlmod NAME PATH
1620 will load the shared object module from the file PATH (an abso‐
1621 lute filename), and call the initialisation routine init_NAME.
1622 Note: If the specified PATH is not a fully qualified filename,
1624 it will be interpreted relative to
1625 /usr/lib(64)/snmp/dlmod, and .so will be appended to the
1626 filename.
1627 This functionality can also be configured using SNMP SET requests to
1629 the UCD-DLMOD-MIB.
1630 Proxy Support
1632 Another mechanism for extending the functionality of the agent is to
1633 pass selected requests (or selected varbinds) to another SNMP agent,
1634 which can be running on the same host (presumably listening on a dif‐
1635 ferent port), or on a remote system. This can be viewed either as the
1636 main agent delegating requests to the remote one, or acting as a proxy
1637 for it. Use of this mechanism requires that the agent was built with
1638 support for the ucd-snmp/proxy module (which is included as part of the
1639 default build configuration).
1640 proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
1642 will pass any incoming requests under OID to the agent listening
1643 on the port specified by the transport address HOST. See the
1644 section LISTENING ADDRESSES in the snmpd(8) manual page for more
1645 information about the format of listening addresses.
1646 Note: To proxy the entire MIB tree, use the OID .1.3 (not the
1648 top-level .1)
1649 The SNMPCMD_ARGS should provide sufficient version and administrative
1651 information to generate a valid SNMP request (see snmpcmd(1)).
1652 Note: The proxied request will not use the administrative settings
1654 from the original request.
1655 If a CONTEXTNAME is specified, this will register the proxy delegation
1657 within the named context in the local agent. Defining multiple proxy
1658 directives for the same OID but different contexts can be used to query
1659 several remote agents through a single proxy, by specifying the appro‐
1660 priate SNMPv3 context in the incoming request (or using suitable con‐
1661 figured community strings - see the com2sec directive).
1662 Specifying the REMOID parameter will map the local MIB tree rooted at
1664 OID to an equivalent subtree rooted at REMOID on the remote agent.
1665 SMUX Sub-Agents
1667 The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1668 with SMUX-based subagents (such as gated, zebra or quagga). Use of
1669 this mechanism requires that the agent was built with support for the
1670 smux module, which is not part of the default build environment, and
1671 must be explicitly included by specifying the '--with-mib-modules=smux'
1672 option to the configure script when the package is first built.
1673 Note: This extension protocol has been officially deprecated in
1675 favour of AgentX (see below).
1676 smuxpeer OID PASS
1678 will register a subtree for SMUX-based processing, to be authen‐
1679 ticated using the password PASS. If a subagent (or "peer") con‐
1680 nects to the agent and registers this subtree then requests for
1681 OIDs within it will be passed to that SMUX subagent for process‐
1682 ing.
1683 A suitable entry for an OSPF routing daemon (such as gated, ze‐
1685 bra or quagga) might be something like
1686 smuxpeer .1.3.6.1.2.1.14 ospf_pass
1687 smuxsocket <IPv4-address>
1689 defines the IPv4 address for SMUX peers to communicate with the
1690 Net-SNMP agent. The default is to listen on all IPv4 interfaces
1691 ("0.0.0.0"), unless the package has been configured with "--en‐
1692 able-local-smux" at build time, which causes it to only listen
1693 on 127.0.0.1 by default. SMUX uses the well-known TCP port 199.
1694 Note the Net-SNMP agent will only operate as a SMUX master agent. It
1696 does not support acting in a SMUX subagent role.
1697 AgentX Sub-Agents
1699 The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both mas‐
1700 ter and subagent roles. Use of this mechanism requires that the agent
1701 was built with support for the agentx module (which is included as part
1702 of the default build configuration), and also that this support is ex‐
1703 plicitly enabled (e.g. via the snmpd.conf file).
1704 There are two directives specifically relevant to running as an AgentX
1706 master agent:
1707 master agentx
1709 will enable the AgentX functionality and cause the agent to
1710 start listening for incoming AgentX registrations. This can
1711 also be activated by specifying the '-x' command-line option (to
1712 specify an alternative listening socket).
1713 agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
1715 Defines the permissions and ownership of the AgentX Unix Domain
1716 socket, and the parent directories of this socket. SOCKPERMS
1717 and DIRPERMS must be octal digits (see chmod(1) ). By default
1718 this socket will only be accessible to subagents which have the
1719 same userid as the agent.
1720 There is one directive specifically relevant to running as an AgentX
1722 sub-agent:
1723 agentXPingInterval NUM
1725 will make the subagent try and reconnect every NUM seconds to
1726 the master if it ever becomes (or starts) disconnected.
1727 The remaining directives are relevant to both AgentX master and sub-
1729 agents:
1730 agentXSocket [<transport-specifier>:]<transport-address>[,...]
1732 defines the address the master agent listens at, or the subagent
1733 should connect to. The default is the Unix Domain socket
1734 "/var/agentx/master". Another common alternative is tcp:local‐
1735 host:705. See the section LISTENING ADDRESSES in the snmpd(8)
1736 manual page for more information about the format of addresses.
1737 Note: Specifying an AgentX socket does not automatically enable
1739 AgentX functionality (unlike the '-x' command-line op‐
1740 tion).
1741 agentXTimeout NUM
1743 defines the timeout period (NUM seconds) for an AgentX request.
1744 Default is 1 second. NUM also be specified with a suffix of one
1745 of s (for seconds), m (for minutes), h (for hours), d (for
1746 days), or w (for weeks).
1747 agentXRetries NUM
1749 defines the number of retries for an AgentX request. Default is
1750 5 retries.
1751 net-snmp ships with both C and Perl APIs to develop your own AgentX
1753 subagent.
1754
1756 override [-rw] OID TYPE VALUE
1757 This directive allows you to override a particular OID with a
1758 different value (and possibly a different type of value). The
1759 -rw flag will allow snmp SETs to modify it's value as well.
1760 (note that if you're overriding original functionality, that
1761 functionality will be entirely lost. Thus SETS will do nothing
1762 more than modify the internal overridden value and will not per‐
1763 form any of the original functionality intended to be provided
1764 by the MIB object. It's an emulation only.) An example:
1765 override sysDescr.0 octet_str "my own sysDescr"
1767 That line will set the sysDescr.0 value to "my own sysDescr" as
1769 well as make it modifiable with SNMP SETs as well (which is ac‐
1770 tually illegal according to the MIB specifications).
1771 Note that care must be taken when using this. For example, if
1773 you try to override a property of the 3rd interface in the
1774 ifTable with a new value and later the numbering within the
1775 ifTable changes it's index ordering you'll end up with problems
1776 and your modified value won't appear in the right place in the
1777 table.
1778 Valid TYPEs are: integer, uinteger, octet_str, object_id,
1780 counter, null (for gauges, use "uinteger"; for bit strings, use
1781 "octet_str"). Note that setting an object to "null" effectively
1782 delete's it as being accessible. No VALUE needs to be given if
1783 the object type is null.
1784 More types should be available in the future.
1786 If you're trying to figure out aspects of the various mib modules (pos‐
1788 sibly some that you've added yourself), the following may help you spit
1789 out some useful debugging information. First off, please read the sn‐
1790 mpd manual page on the -D flag. Then the following configuration sn‐
1791 mpd.conf token, combined with the -D flag, can produce useful output:
1792 injectHandler HANDLER modulename [beforeThis]
1794 This will insert new handlers into the section of the mib tree
1795 referenced by "modulename". If "beforeThis" is specified then
1796 the module will be injected before the named module. This is
1797 useful for getting a handler into the exact right position in
1798 the chain.
1799 The types of handlers available for insertion are:
1801 stash_cache
1803 Caches information returned from the lower level. This
1804 greatly help the performance of the agent, at the cost of
1805 caching the data such that its no longer "live" for 30
1806 seconds (in this future, this will be configurable).
1807 Note that this means snmpd will use more memory as well
1808 while the information is cached. Currently this only
1809 works for handlers registered using the table_iterator
1810 support, which is only a few mib tables. To use it, you
1811 need to make sure to install it before the table_iterator
1812 point in the chain, so to do this:
1813 injectHandler stash_cache NAME table_iterator
1815 If you want a table to play with, try walking the nsMod‐
1817 uleTable with and without this injected.
1818 debug Prints out lots of debugging information when the
1821 -Dhelper:debug flag is passed to the snmpd application.
1822 read_only
1825 Forces turning off write support for the given module.
1826 serialize
1829 If a module is failing to handle multiple requests prop‐
1830 erly (using the new 5.0 module API), this will force the
1831 module to only receive one request at a time.
1832 bulk_to_next
1835 If a module registers to handle getbulk support, but for
1836 some reason is failing to implement it properly, this
1837 module will convert all getbulk requests to getnext re‐
1838 quests before the final module receives it.
1839 dontLogTCPWrappersConnects
1841 If the snmpd was compiled with TCP Wrapper support, it logs ev‐
1842 ery connection made to the agent. This setting disables the log
1843 messages for accepted connections. Denied connections will still
1844 be logged.
1845 Figuring out module names
1847 To figure out which modules you can inject things into, run snm‐
1848 pwalk on the nsModuleTable which will give a list of all named
1849 modules registered within the agent.
1850 Internal Data tables
1852 table NAME
1853 add_row NAME INDEX(ES) VALUE(S)
1855
1857 o The Net-SNMP agent can be instructed to re-read the various con‐
1858 figuration files, either via an snmpset assignment of integer(1)
1859 to UCD-SNMP-MIB::versionUpdateConfig.0
1860 (.1.3.6.1.4.1.2021.100.11.0), or by sending a kill -HUP signal
1861 to the agent process.
1862 o All directives listed with a value of "yes" actually accept a
1864 range of boolean values. These will accept any of 1, yes or
1865 true to enable the corresponding behaviour, or any of 0, no or
1866 false to disable it. The default in each case is for the fea‐
1867 ture to be turned off, so these directives are typically only
1868 used to enable the appropriate behaviour.
1869
1871 See the EXAMPLE.CONF file in the top level source directory for a more
1872 detailed example of how the above information is used in real examples.
1873
1875 /etc/snmp/snmpd.conf
1876
1878 snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM‐
1879 PLE.conf, netsnmp_config_api(3).
1880V5.9.3 30 Jun 2010 SNMPD.CONF(5)