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 ignoremount [-r] STRING
662 controls which mounts should be omitted from the hrStorageTable.
663 If the Net-SNMP agent gets hung on accessing a filesystem, or
664 the filesystem is always mostly full (and thus leads to spurious
665 alerts), you can omit it by listing the full path in this direc‐
666 tive.
667 If the "-r" option is provided, the pattern can include one or
669 more regular expressions.
670 skipNFSInHostResources true
672 controls whether NFS and NFS-like file systems should be omitted
673 from the hrStorageTable (true or 1) or not (false or 0, which is
674 the default). If the Net-SNMP agent gets hung on NFS-mounted
675 filesystems, you can try setting this to '1'.
676 Alternately, more granular control over which mounts should be
678 omitted from the hrStorageTable can be achieved via the ignore‐
679 mount directive.
680 storageUseNFS [1|2]
682 controls how NFS and NFS-like file systems should be reported in
683 the hrStorageTable. as 'Network Disks' (1) or 'Fixed Disks' (2)
684 Historically, the Net-SNMP agent has reported such file systems
685 as 'Fixed Disks', and this is still the default behaviour. Set‐
686 ting this directive to '1' reports such file systems as ´Network
687 Disks', as required by the Host Resources MIB.
688 realStorageUnits
690 controlls how the agent reports hrStorageAllocationUnits,
691 hrStorageSize and hrStorageUsed in hrStorageTable. For big
692 storage drives with small allocation units the agent re-calcu‐
693 lates these values so they all fit Integer32 and hrStorageAllo‐
694 cationUnits x hrStorageSize gives real size of the storage.
695 Example:
697 Linux xfs 16TB filesystem with 4096 bytes large blocks
698 will be reported as hrStorageAllocationUnits = 8192 and
699 hrStorageSize = 2147483647, so 8192 x 2147483647 gives
700 real size of the filesystem (=16 TB).
701 Setting this directive to '1' turns off this calculation and the
703 agent reports real hrStorageAllocationUnits, but it might report
704 wrong hrStorageSize for big drives because the value won't fit
705 into Integer32. In this case, hrStorageAllocationUnits x hrStor‐
706 ageSize won't give real size of the storage.
707 Process Monitoring
709 The hrSWRun group of the Host Resources MIB provides information about
710 individual processes running on the local system. The prTable of the
711 UCD-SNMP-MIB complements this by reporting on selected services (which
712 may involve multiple processes). This requires that the agent was
713 built with support for the ucd-snmp/proc module (which is included as
714 part of the default build configuration).
715 proc NAME [MAX [MIN]]
717 monitors the number of processes called NAME (as reported by
718 "/usr/bin/ps -e") running on the local system.
719 If the number of NAMEd processes is less than MIN or greater
721 than MAX, then the corresponding prErrorFlag instance will be
722 set to 1, and a suitable description message reported via the
723 prErrMessage instance.
724 Note: This situation will not automatically trigger a trap to
726 report the problem - see the DisMan Event MIB section
727 later.
728 If neither MAX nor MIN are specified, they will default to in‐
730 finity and 1 respectively ("at least one"). If only MAX is
731 specified, MIN will default to 0 ("no more than MAX"). If MAX
732 is 0 (and MIN is not), this indicates infinity ("at least MIN").
733 If both MAX and MIN are 0, this indicates a process that should
734 not be running.
735 procfix NAME PROG ARGS
737 registers a command that can be run to fix errors with the given
738 process NAME. This will be invoked when the corresponding prE‐
739 rrFix instance is set to 1.
740 Note: This command will not be invoked automatically.
742 The procfix directive must be specified after the matching proc
744 directive, and cannot be used on its own.
745 If no proc directives are defined, then walking the prTable will fail
747 (noSuchObject).
748 Disk Usage Monitoring
750 This requires that the agent was built with support for the
751 ucd-snmp/disk module (which is included as part of the default build
752 configuration).
753 disk PATH [ MINSPACE | MINPERCENT% ]
755 monitors the disk mounted at PATH for available disk space.
756 Disks mounted after the agent has started will not be monitored,
757 unless includeAllDisks option is specified.
758 The minimum threshold can either be specified in kB (MINSPACE)
760 or as a percentage of the total disk (MINPERCENT% with a '%'
761 character), defaulting to 100kB if neither are specified. If
762 the free disk space falls below this threshold, then the corre‐
763 sponding dskErrorFlag instance will be set to 1, and a suitable
764 description message reported via the dskErrorMsg instance.
765 Note: This situation will not automatically trigger a trap to
767 report the problem - see the DisMan Event MIB section
768 later.
769 includeAllDisks MINPERCENT%
771 configures monitoring of all disks found on the system, using
772 the specified (percentage) threshold. The dskTable is dynami‐
773 cally updated, unmounted disks disappear from the table and
774 newly mounted disks are added to the table. The threshold for
775 individual disks can be adjusted using suitable disk directives
776 (which can come either before or after the includeAllDisks di‐
777 rective).
778 Note: Whether disk directives appears before or after in‐
780 cludeAllDisks may affect the indexing of the dskTable.
781 Only one includeAllDisks directive should be specified - any
783 subsequent copies will be ignored.
784 The list of mounted disks will be determined from HOST-RE‐
786 SOURCES-MIB::hrFSTable.
787 If neither any disk directives or includeAllDisks are defined, then
789 walking the dskTable will fail (noSuchObject).
790 Disk I/O Monitoring
792 This requires that the agent was built with support for the
793 ucd-snmp/diskio module (which is not included as part of the default
794 build configuration).
795 By default, all block devices known to the operating system are in‐
797 cluded in the diskIOTable. On platforms other than Linux, this module
798 has no configuration directives.
799 On Linux systems, it is possible to exclude several classes of block
801 devices from the diskIOTable in order to avoid cluttering the table
802 with useless zero statistics for pseudo-devices that often are not in
803 use but are configured by default to exist in most recent Linux distri‐
804 butions.
805 diskio_exclude_fd yes
807 Excludes all Linux floppy disk block devices, whose names start
808 with "fd", e.g. "fd0"
809 diskio_exclude_loop yes
811 Excludes all Linux loopback block devices, whose names start
812 with "loop", e.g. "loop0"
813 diskio_exclude_ram yes
815 Excludes all LInux ramdisk block devices, whose names start with
816 "ram", e.g. "ram0"
817 On Linux systems, it is also possible to report only explicitly ac‐
819 cepted devices. It may take significant amount of time to process
820 diskIOTable data on systems with tens of thousands of block devices and
821 accept only the important ones avoids large CPU consumption.
822 diskio <device>
824 Enables acceptlist of devices and adds the device to the ac‐
825 ceptlist. Only explicitly acceptlisted devices will be reported.
826 This option may be used multiple times.
827 System Load Monitoring
829 This requires that the agent was built with support for either the
830 ucd-snmp/loadave module or the ucd-snmp/memory module respectively
831 (both of which are included as part of the default build configura‐
832 tion).
833 load MAX1 [MAX5 [MAX15]]
835 monitors the load average of the local system, specifying
836 thresholds for the 1-minute, 5-minute and 15-minute averages.
837 If any of these loads exceed the associated maximum value, then
838 the corresponding laErrorFlag instance will be set to 1, and a
839 suitable description message reported via the laErrMessage in‐
840 stance.
841 Note: This situation will not automatically trigger a trap to
843 report the problem - see the DisMan Event MIB section
844 later.
845 If the MAX15 threshold is omitted, it will default to the MAX5
847 value. If both MAX5 and MAX15 are omitted, they will default to
848 the MAX1 value. If this directive is not specified, all three
849 thresholds will default to a value of DEFMAXLOADAVE.
850 If a threshold value of 0 is given, the agent will not report
852 errors via the relevant laErrorFlag or laErrMessage instances,
853 regardless of the current load.
854 Unlike the proc and disk directives, walking the walking the laTable
856 will succeed (assuming the ucd-snmp/loadave module was configured into
857 the agent), even if the load directive is not present.
858 swap MIN
860 monitors the amount of swap space available on the local system.
861 If this falls below the specified threshold (MIN kB), then the
862 memErrorSwap object will be set to 1, and a suitable description
863 message reported via memSwapErrorMsg.
864 Note: This situation will not automatically trigger a trap to
866 report the problem - see the DisMan Event MIB section
867 later.
868 If this directive is not specified, the default threshold is 16 MB.
869 Log File Monitoring
871 This requires that the agent was built with support for either the
872 ucd-snmp/file or ucd-snmp/logmatch modules respectively (both of which
873 are included as part of the default build configuration).
874 file FILE [MAXSIZE]
876 monitors the size of the specified file (in kB). If MAXSIZE is
877 specified, and the size of the file exceeds this threshold, then
878 the corresponding fileErrorFlag instance will be set to 1, and a
879 suitable description message reported via the fileErrorMsg in‐
880 stance.
881 Note: This situation will not automatically trigger a trap to
883 report the problem - see the DisMan Event MIB section
884 later.
885 Note: A maximum of 20 files can be monitored.
887 Note: If no file directives are defined, then walking the
889 fileTable will fail (noSuchObject).
890 logmatch NAME FILE CYCLETIME REGEX
892 monitors the specified file for occurances of the specified pat‐
893 tern REGEX. The file position is stored internally so the entire
894 file is only read initially, every subsequent pass will only
895 read the new lines added to the file since the last read.
896 NAME name of the logmatch instance (will appear as logMatch‐
898 Name under logMatch/logMatchTable/logMatchEntry/logMatch‐
899 Name in the ucd-snmp MIB tree)
900 FILE absolute path to the logfile to be monitored. Note that
902 this path can contain date/time directives (like in the
903 UNIX 'date' command). See the manual page for 'strftime'
904 for the various directives accepted.
905 CYCLETIME
907 time interval for each logfile read and internal variable
908 update in seconds. Note: an SNMPGET* operation will also
909 trigger an immediate logfile read and variable update.
910 REGEX the regular expression to be used. Note: DO NOT enclose
912 the regular expression in quotes even if there are spaces
913 in the expression as the quotes will also become part of
914 the pattern to be matched!
915 Example:
917 logmatch apache-GETs /usr/local/apache/logs/ac‐
919 cess.log-%Y-%m-%d 60 GET.*HTTP.*
920 This logmatch instance is named 'apache-GETs', uses
922 'GET.*HTTP.*' as its regular expression and it will moni‐
923 tor the file named (assuming today is May 6th 2009):
924 '/usr/local/apache/logs/access.log-2009-05-06', tomorrow
925 it will look for 'access.log-2009-05-07'. The logfile is
926 read every 60 seconds.
927 Note: A maximum of 250 logmatch directives can be specified.
929 Note: If no logmatch directives are defined, then walking the
931 logMatchTable will fail (noSuchObject).
932
934 The usual behaviour of an SNMP agent is to wait for incoming SNMP re‐
935 quests and respond to them - if no requests are received, an agent will
936 typically not initiate any actions. This section describes various di‐
937 rectives that can configure snmpd to take a more active role.
938 Notification Handling
940 trapcommunity STRING
941 defines the default community string to be used when sending
942 traps. Note that this directive must be used prior to any com‐
943 munity-based trap destination directives that need to use it.
944 trapsink [-profile p] [-name n] [-tag t] [-s src] HOST [COMMUNITY
946 [PORT]]
947 trap2sink [-profile p] [-name n] [-tag t] [-s src] HOST [COMMUNITY
949 [PORT]]
950 informsink [-profile p] [-name n] [-tag t] [-s src] HOST [COMMUNITY
952 [PORT]]
953 define the address of a notification receiver that should be
954 sent SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifica‐
955 tions respectively. See the section LISTENING ADDRESSES in the
956 snmpd(8) manual page for more information about the format of
957 listening addresses. If COMMUNITY is not specified, the most
958 recent trapcommunity string will be used.
959 If the transport address does not include an explicit port spec‐
961 ification, then PORT will be used. If this is not specified,
962 the well known SNMP trap port (162) will be used.
963 Note: This mechanism is being deprecated, and the listening
965 port should be specified via the transport specification
966 HOST instead.
967 The optional name and tag parameters specifies the name or tag
969 that will be used for SNMP-NOTIFICATION-MIB table entries. The
970 profile specifies which notification filter profile entry will
971 be used for filtering outgoing notifications. (See notification‐
972 Filter)
973 The optional src parameter specifies the source address that
975 will be used when sending the trap packet to this sink. It is
976 specified as a <transport-address>, using the same <transport-
977 specifier> as the destination HOST. See the section LISTENING
978 ADDRESSES in the snmpd(8) manual page for more information about
979 the format.
980 If several sink directives are specified, multiple copies of
982 each notification (in the appropriate formats) will be gener‐
983 ated.
984 Note: It is not normally appropriate to list two (or all three)
986 sink directives with the same destination.
987 trapsess [-profile p] [-name n] [-tag t] [-s src] [SNMPCMD_ARGS] HOST
989 provides a more generic mechanism for defining notification des‐
990 tinations. SNMPCMD_ARGS should be the command-line options re‐
991 quired for an equivalent snmptrap (or snmpinform) command to
992 send the desired notification. The option -Ci can be used (with
993 -v2c or -v3) to generate an INFORM notification rather than an
994 unacknowledged TRAP.
995 The optional name and tag parameters specifies the name or tag
997 that will be used for SNMP-NOTIFICATION-MIB table entries. The
998 profile specifies which notification filter profile entry will
999 be used for filtering outgoing notifications. (See notification‐
1000 Filter)
1001 This is the appropriate directive for defining SNMPv3 trap re‐
1003 ceivers. See http://www.net-snmp.org/tutorial/tutorial-5/com‐
1004 mands/snmptrap-v3.html for more information about SNMPv3 notifi‐
1005 cation behaviour.
1006 notificationFilter NAME OID MASK TYPE
1008 specifies a SNMP-NOTIFICATION-MIB notification filter profile,
1009 which may be used to filter traps. TYPE must be included or ex‐
1010 cluded, Some examples:
1011 notificationFilter all_ok .1.3 0x00 included
1013 notificationFilter no_coldstart .1.3 0x00 included
1014 notificationFilter no_coldstart .1.3.6.1.6.3.1.1.5.1 0x00 excluded
1015 trapsink -profile no_coldstart 192.168.1.3:3162 secret3
1017 authtrapenable {1|2}
1019 determines whether to generate authentication failure traps (en‐
1020 abled(1)) or not (disabled(2) - the default). Ordinarily the
1021 corresponding MIB object (snmpEnableAuthenTraps.0) is read-
1022 write, but specifying this directive makes this object read-
1023 only, and attempts to set the value via SET requests will result
1024 in a notWritable error response.
1025 v1trapaddress HOST
1027 defines the agent address, which is inserted into SNMPv1 TRAPs.
1028 Arbitrary local IPv4 address is chosen if this option is om‐
1029 mited. This option is useful mainly when the agent is visible
1030 from outside world by specific address only (e.g. because of
1031 network address translation or firewall).
1032 DisMan Event MIB
1034 The previous directives can be used to configure where traps should be
1035 sent, but are not concerned with when to send such traps (or what traps
1036 should be generated). This is the domain of the Event MIB - developed
1037 by the Distributed Management (DisMan) working group of the IETF.
1038 This requires that the agent was built with support for the dis‐
1040 man/event module (which is now included as part of the default build
1041 configuration for the most recent distribution).
1042 Note: The behaviour of the latest implementation differs in
1044 some minor respects from the previous code - nothing too
1045 significant, but existing scripts may possibly need some
1046 minor adjustments.
1047 iquerySecName NAME
1049 agentSecName NAME
1051 specifies the default SNMPv3 username, to be used when making
1052 internal queries to retrieve any necessary information (either
1053 for evaluating the monitored expression, or building a notifica‐
1054 tion payload). These internal queries always use SNMPv3, even
1055 if normal querying of the agent is done using SNMPv1 or SNMPv2c.
1056 Note that this user must also be explicitly created (createUser)
1058 and given appropriate access rights (e.g. rouser). This direc‐
1059 tive is purely concerned with defining which user should be used
1060 - not with actually setting this user up.
1061 monitor [OPTIONS] NAME EXPRESSION
1063 defines a MIB object to monitor. If the EXPRESSION condition
1064 holds (see below), then this will trigger the corresponding
1065 event, and either send a notification or apply a SET assignment
1066 (or both). Note that the event will only be triggered once,
1067 when the expression first matches. This monitor entry will not
1068 fire again until the monitored condition first becomes false,
1069 and then matches again. NAME is an administrative name for this
1070 expression, and is used for indexing the mteTriggerTable (and
1071 related tables). Each monitor line must have a unique NAME. Mon‐
1072 itor lines with a duplicate name are discarded and cause snmpd
1073 to log a duplicate index complaint. Note also that such moni‐
1074 tors use an internal SNMPv3 request to retrieve the values being
1075 monitored (even if normal agent queries typically use SNMPv1 or
1076 SNMPv2c). See the iquerySecName token described above.
1077 EXPRESSION
1079 There are three types of monitor expression supported by the
1080 Event MIB - existence, boolean and threshold tests.
1081 OID | ! OID | != OID
1083 defines an existence(0) monitor test. A bare OID speci‐
1084 fies a present(0) test, which will fire when (an instance
1085 of) the monitored OID is created. An expression of the
1086 form ! OID specifies an absent(1) test, which will fire
1087 when the monitored OID is delected. An expression of the
1088 form != OID specifies a changed(2) test, which will fire
1089 whenever the monitored value(s) change. Note that there
1090 must be whitespace before the OID token.
1091 OID OP VALUE
1093 defines a boolean(1) monitor test. OP should be one of
1094 the defined comparison operators (!=, ==, <, <=, >, >=)
1095 and VALUE should be an integer value to compare against.
1096 Note that there must be whitespace around the OP token.
1097 A comparison such as OID !=0 will not be handled cor‐
1098 rectly.
1099 OID MIN MAX [DMIN DMAX]
1101 defines a threshold(2) monitor test. MIN and MAX are in‐
1102 teger values, specifying lower and upper thresholds. If
1103 the value of the monitored OID falls below the lower
1104 threshold (MIN) or rises above the upper threshold (MAX),
1105 then the monitor entry will trigger the corresponding
1106 event.
1107 Note that the rising threshold event will only be re-
1109 armed when the monitored value falls below the lower
1110 threshold (MIN). Similarly, the falling threshold event
1111 will be re-armed by the upper threshold (MAX).
1112 The optional parameters DMIN and DMAX configure a pair of
1114 similar threshold tests, but working with the delta dif‐
1115 ferences between successive sample values.
1116 OPTIONS
1118 There are various options to control the behaviour of the moni‐
1119 tored expression. These include:
1120 -D indicates that the expression should be evaluated using
1122 delta differences between sample values (rather than the
1123 values themselves).
1124 -d OID
1126 -di OID
1128 specifies a discontinuity marker for validating delta
1129 differences. A -di object instance will be used exactly
1130 as given. A -d object will have the instance subidenti‐
1131 fiers from the corresponding (wildcarded) expression ob‐
1132 ject appended. If the -I flag is specified, then there
1133 is no difference between these two options.
1134 This option also implies -D.
1136 -e EVENT
1138 specifies the event to be invoked when this monitor entry
1139 is triggered. If this option is not given, the monitor
1140 entry will generate one of the standard notifications de‐
1141 fined in the DISMAN-EVENT-MIB.
1142 -I indicates that the monitored expression should be applied
1144 to the specified OID as a single instance. By default,
1145 the OID will be treated as a wildcarded object, and the
1146 monitor expanded to cover all matching instances.
1147 -i OID
1149 -o OID define additional varbinds to be added to the notifica‐
1151 tion payload when this monitor trigger fires. For a
1152 wildcarded expression, the suffix of the matched instance
1153 will be added to any OIDs specified using -o, while OIDs
1154 specified using -i will be treated as exact instances.
1155 If the -I flag is specified, then there is no difference
1156 between these two options.
1157 See strictDisman for details of the ordering of notifica‐
1159 tion payloads.
1160 -r FREQUENCY
1162 monitors the given expression every FREQUENCY, where FRE‐
1163 QUENCY is in seconds or optionally suffixed by one of s
1164 (for seconds), m (for minutes), h (for hours), d (for
1165 days), or w (for weeks). By default, the expression will
1166 be evaluated every 600s (10 minutes).
1167 -S indicates that the monitor expression should not be eval‐
1169 uated when the agent first starts up. The first evalua‐
1170 tion will be done once the first repeat interval has ex‐
1171 pired.
1172 -s indicates that the monitor expression should be evaluated
1174 when the agent first starts up. This is the default be‐
1175 haviour.
1176 Note: Notifications triggered by this initial evaluation
1178 will be sent before the coldStart trap.
1179 -u SECNAME
1181 specifies a security name to use for scanning the local
1182 host, instead of the default iquerySecName. Once again,
1183 this user must be explicitly created and given suitable
1184 access rights.
1185 notificationEvent ENAME NOTIFICATION [-m] [-i OID | -o OID ]*
1187 defines a notification event named ENAME. This can be triggered
1188 from a given monitor entry by specifying the option -e ENAME
1189 (see above). NOTIFICATION should be the OID of the NOTIFICA‐
1190 TION-TYPE definition for the notification to be generated.
1191 If the -m option is given, the notification payload will include
1193 the standard varbinds as specified in the OBJECTS clause of the
1194 notification MIB definition. This option must come after the
1195 NOTIFICATION OID (and the relevant MIB file must be available
1196 and loaded by the agent). Otherwise, these varbinds must be
1197 listed explicitly (either here or in the corresponding monitor
1198 directive).
1199 The -i OID and -o OID options specify additional varbinds to be
1201 appended to the notification payload, after the standard list.
1202 If the monitor entry that triggered this event involved a wild‐
1203 carded expression, the suffix of the matched instance will be
1204 added to any OIDs specified using -o, while OIDs specified using
1205 -i will be treated as exact instances. If the -I flag was spec‐
1206 ified to the monitor directive, then there is no difference be‐
1207 tween these two options.
1208 setEvent ENAME [-I] OID = VALUE
1210 defines a set event named ENAME, assigning the (integer) VALUE
1211 to the specified OID. This can be triggered from a given moni‐
1212 tor entry by specifying the option -e ENAME (see above).
1213 If the monitor entry that triggered this event involved a wild‐
1215 carded expression, the suffix of the matched instance will nor‐
1216 mally be added to the OID. If the -I flag was specified to ei‐
1217 ther of the monitor or setEvent directives, the specified OID
1218 will be regarded as an exact single instance.
1219 strictDisman yes
1221 The definition of SNMP notifications states that the varbinds
1222 defined in the OBJECT clause should come first (in the order
1223 specified), followed by any "extra" varbinds that the notifica‐
1224 tion generator feels might be useful. The most natural approach
1225 would be to associate these mandatory varbinds with the notifi‐
1226 cationEvent entry, and append any varbinds associated with the
1227 monitor entry that triggered the notification to the end of this
1228 list. This is the default behaviour of the Net-SNMP Event MIB
1229 implementation.
1230 Unfortunately, the DisMan Event MIB specifications actually
1232 state that the trigger-related varbinds should come first, fol‐
1233 lowed by the event-related ones. This directive can be used to
1234 restore this strictly-correct (but inappropriate) behaviour.
1235 Note: Strict DisMan ordering may result in generating invalid
1237 notifications payload lists if the notificationEvent -n
1238 flag is used together with monitor -o (or -i) varbind op‐
1239 tions.
1240 If no monitor entries specify payload varbinds, then the setting
1242 of this directive is irrelevant.
1243 linkUpDownNotifications yes
1245 will configure the Event MIB tables to monitor the ifTable for
1246 network interfaces being taken up or down, and triggering a
1247 linkUp or linkDown notification as appropriate.
1248 This is exactly equivalent to the configuration:
1250 notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
1252 notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
1253 monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
1255 monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
1256 defaultMonitors yes
1258 will configure the Event MIB tables to monitor the various
1259 UCD-SNMP-MIB tables for problems (as indicated by the appropri‐
1260 ate xxErrFlag column objects).
1261 This is exactly equivalent to the configuration:
1263 monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
1265 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
1266 monitor -o extNames -o extOutput "extTable" extResult != 0
1267 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
1268 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
1269 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
1270 In both these latter cases, the snmpd.conf must also contain a iquery‐
1272 SecName directive, together with a corresponding createUser entry and
1273 suitable access control configuration.
1274 DisMan Schedule MIB
1276 The DisMan working group also produced a mechanism for scheduling par‐
1277 ticular actions (a specified SET assignment) at given times. This re‐
1278 quires that the agent was built with support for the disman/schedule
1279 module (which is included as part of the default build configuration
1280 for the most recent distribution).
1281 There are three ways of specifying the scheduled action:
1283 repeat FREQUENCY OID = VALUE
1285 configures a SET assignment of the (integer) VALUE to the MIB
1286 instance OID, to be run every FREQUENCY seconds, where FREQUENCY
1287 is in seconds or optionally suffixed by one of s (for seconds),
1288 m (for minutes), h (for hours), d (for days), or w (for weeks).
1289 cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1291 configures a SET assignment of the (integer) VALUE to the MIB
1292 instance OID, to be run at the times specified by the fields
1293 MINUTE to WEEKDAY. These follow the same pattern as the equiva‐
1294 lent crontab(5) fields.
1295 Note: These fields should be specified as a (comma-separated)
1297 list of numeric values. Named values for the MONTH and
1298 WEEKDAY fields are not supported, and neither are value
1299 ranges. A wildcard match can be specified as '*'.
1300 The DAY field can also accept negative values, to indicate days
1302 counting backwards from the end of the month.
1303 at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1305 configures a one-shot SET assignment, to be run at the first
1306 matching time as specified by the fields MINUTE to WEEKDAY. The
1307 interpretation of these fields is exactly the same as for the
1308 cron directive.
1309 Data Delivery via Notfiications
1311 Note: this functionality is only available if the deliver/deliverByNo‐
1312 tify mib module was complied in to the agent
1313 In some situations it may be advantageous to deliver SNMP data over
1315 SNMP Notifications (TRAPs and INFORMs) rather than the typical process
1316 of having the manager issue requests for the data (via GETs and GET‐
1317 NEXTs). Reasons for doing this are numerous, but frequently corner
1318 cases. The most common reason for wanting this behaviour might be to
1319 monitor devices that reside behind NATs or Firewalls that prevent in‐
1320 coming SNMP traffic.
1321 It should be noted that although most management software is capable of
1323 logging notifications, very little (if any) management software will
1324 updated their "knowledge database" based on the contents of SNMP noti‐
1325 fications. IE, it won't (for example) update the interface traffic
1326 counter history that is used to produce graphs. Most larger network
1327 management packages have a separate database for storing data received
1328 via SNMP requests (GETs and GETNEXTs) vs those received from notifica‐
1329 tions. Researching the capabilities of your management station soft‐
1330 ware is required before assuming this functionality will solve your
1331 data delivery requirements.
1332 Notifications generated via this mechanism will be sent to the standard
1334 set of configured notification targets. See the "Notification Han‐
1335 dling" section of this document for further information.
1336 deliverByNotify [-p] [-m] [-s MAXSIZE] FREQUENCY OID
1338 This directive tells the SNMP agent to self-walk the OID, col‐
1339 lect all the data and send it out every FREQUENCY seconds, where
1340 FREQUENCY is in seconds or optionally suffixed by one of s (for
1341 seconds), m (for minutes), h (for hours), d (for days), or w
1342 (for weeks). By default scalars are included in the notifica‐
1343 tion that specify the how often the notification will be sent
1344 (unless the -p option is specified) and which message number of
1345 how many messages a particular notification is (unless -m is
1346 specified). To break the notifications into manageable packet
1347 sizes, use the -s flag to specify the approximate maximum number
1348 of bytes that a notification message should be limited to. If
1349 more than MAXSIZE of bytes is needed then multiple notifications
1350 will be sent to deliver the data. Note that the calculations
1351 for ensuring the maximum size is met are approximations and thus
1352 it can be absolutely guaranteed they'll be under that size, so
1353 leave a padding buffer if it is critical that you avoid fragmen‐
1354 tation. A value of -1 indicates force everything into a single
1355 message no matter how big it is.
1356 Example usage: the following will deliver the contents of the
1358 ifTable once an hour and the contents of the system group once
1359 every 2 hours:
1360 deliverByNotify 3600 ifTable
1362 deliverByNotify 7200 system
1363 deliverByNotifyMaxPacketSize SIZEINBYTES
1365 Sets the default notification size limit (see the -s flag
1366 above).
1367 deliverByNotifyOid OID
1369 deliverByNotifyFrequencyOid OID
1371 deliverByNotifyMessageNumberOid OID
1373 deliverByNotifyMaxMessageNumberOid OID
1375 These set the data OID that the notification will be sent under,
1376 the scalar OID, the message number OID, and the maximum message
1377 number OID. These default to objects in the NET-SNMP-PERI‐
1378 ODIC-NOTIFY-MIB.
1379
1381 One of the first distinguishing features of the original UCD suite was
1382 the ability to extend the functionality of the agent - not just by re‐
1383 compiling with code for new MIB modules, but also by configuring the
1384 running agent to report additional information. There are a number of
1385 techniques to support this, including:
1386 • running external commands (exec, extend, pass)
1388 • loading new code dynamically (embedded perl, dlmod)
1390 • communicating with other agents (proxy, SMUX, AgentX)
1392 Arbitrary Extension Commands
1394 The earliest extension mechanism was the ability to run arbitrary com‐
1395 mands or shell scripts. Such commands do not need to be aware of SNMP
1396 operations, or conform to any particular behaviour - the MIB structures
1397 are designed to accommodate any form of command output. Use of this
1398 mechanism requires that the agent was built with support for the
1399 ucd-snmp/extensible and/or agent/extend modules (which are both in‐
1400 cluded as part of the default build configuration).
1401 exec [MIBOID] NAME PROG ARGS
1403 sh [MIBOID] NAME PROG ARGS
1405 invoke the named PROG with arguments of ARGS. By default the
1406 exit status and first line of output from the command will be
1407 reported via the extTable, discarding any additional output.
1408 Note: Entries in this table appear in the order they are read
1410 from the configuration file. This means that adding new
1411 exec (or sh) directives and restarting the agent, may af‐
1412 fect the indexing of other entries.
1413 The PROG argument for exec directives must be a full path to a
1415 real binary, as it is executed via the exec() system call. To
1416 invoke a shell script, use the sh directive instead.
1417 If MIBOID is specified, then the results will be rooted at this
1419 point in the OID tree, returning the exit statement as MI‐
1420 BOID.100.0 and the entire command output in a pseudo-table based
1421 at MIBNUM.101 - with one 'row' for each line of output.
1422 Note: The layout of this "relocatable" form of exec (or sh)
1424 output does not strictly form a valid MIB structure.
1425 This mechanism is being deprecated - please see the ex‐
1426 tend directive (described below) instead.
1427 The agent does not cache the exit status or output of the exe‐
1429 cuted program.
1430 execfix NAME PROG ARGS
1432 registers a command that can be invoked on demand - typically to
1433 respond to or fix errors with the corresponding exec or sh en‐
1434 try. When the extErrFix instance for a given NAMEd entry is set
1435 to the integer value of 1, this command will be called.
1436 Note: This directive can only be used in combination with a
1438 corresponding exec or sh directive, which must be defined
1439 first. Attempting to define an unaccompanied execfix di‐
1440 rective will fail.
1441 exec and sh extensions can only be configured via the snmpd.conf file.
1443 They cannot be set up via SNMP SET requests.
1444 extend [-cacheTime TIME] [-execType TYPE] [MIBOID] NAME PROG ARGS
1446 works in a similar manner to the exec directive, but with a num‐
1447 ber of improvements. The MIB tables (nsExtendConfigTable etc)
1448 are indexed by the NAME token, so are unaffected by the order in
1449 which entries are read from the configuration files. There are
1450 two result tables - one (nsExtendOutput1Table) containing the
1451 exit status, the first line and full output (as a single string)
1452 for each extend entry, and the other (nsExtendOutput2Table) con‐
1453 taining the complete output as a series of separate lines.
1454 If -cacheTime is specified, then its argument is used as the
1456 cache timeout (in whole seconds) for this extend entry. This
1457 mechanism provides a non-volatile way to specify the cache time‐
1458 out.
1459 If -execType is specified and has a value of sh, then this ex‐
1461 tend entry will be run in a shell. Otherwise it will be run in
1462 the default exec fashion. This mechanism provides a non-volatile
1463 way to specify the exec type.
1464 If MIBOID is specified, then the configuration and result tables
1466 will be rooted at this point in the OID tree, but are otherwise
1467 structured in exactly the same way. This means that several sep‐
1468 arate extend directives can specify the same MIBOID root, with‐
1469 out conflicting.
1470 The exit status and output is cached for each entry individu‐
1472 ally, and can be cleared (and the caching behaviour configured)
1473 using the nsCacheTable.
1474 extendfix NAME PROG ARGS
1476 registers a command that can be invoked on demand, by setting
1477 the appropriate nsExtendRunType instance to the value run-com‐
1478 mand(3). Unlike the equivalent execfix, this directive does not
1479 need to be paired with a corresponding extend entry, and can ap‐
1480 pear on its own.
1481 Both extend and extendfix directives can be configured dynamically, us‐
1483 ing SNMP SET requests to the NET-SNMP-EXTEND-MIB.
1484 MIB-Specific Extension Commands
1486 The first group of extension directives invoke arbitrary commands, and
1487 rely on the MIB structure (and management applications) having the
1488 flexibility to accommodate and interpret the output. This is a conve‐
1489 nient way to make information available quickly and simply, but is of
1490 no use when implementing specific MIB objects, where the extension must
1491 conform to the structure of the MIB (rather than vice versa). The re‐
1492 maining extension mechanisms are all concerned with such MIB-specific
1493 situations - starting with "pass-through" scripts. Use of this mecha‐
1494 nism requires that the agent was built with support for the
1495 ucd-snmp/pass and ucd-snmp/pass_persist modules (which are both in‐
1496 cluded as part of the default build configuration).
1497 pass [-p priority] MIBOID PROG
1499 will pass control of the subtree rooted at MIBOID to the speci‐
1500 fied PROG command. GET and GETNEXT requests for OIDs within
1501 this tree will trigger this command, called as:
1502 PROG -g OID
1504 PROG -n OID
1506 respectively, where OID is the requested OID. The PROG command
1508 should return the response varbind as three separate lines
1509 printed to stdout - the first line should be the OID of the re‐
1510 turned value, the second should be its TYPE (one of the text
1511 strings integer, gauge, counter, timeticks, ipaddress, objectid,
1512 octet, or string ), and the third should be the value itself.
1513 (Note: octets are sent as ASCII, space-separated hex strings,
1514 e.g. "00 3f dd 00 c6 be".)
1515 If the command cannot return an appropriate varbind - e.g the
1517 specified OID did not correspond to a valid instance for a GET
1518 request, or there were no following instances for a GETNEXT -
1519 then it should exit without producing any output. This will re‐
1520 sult in an SNMP noSuchName error, or a noSuchInstance exception.
1521 Note: The SMIv2 type counter64 and SNMPv2 noSuchObject
1523 exception are not supported.
1524 A SET request will result in the command being called as:
1526 PROG -s OID TYPE VALUE
1528 where TYPE is one of the tokens listed above, indicating the
1530 type of the value passed as the third parameter.
1531 If the assignment is successful, the PROG command should exit
1533 without producing any output. Errors should be indicated by
1534 writing one of the strings not-writable, or wrong-type to std‐
1535 out, and the agent will generate the appropriate error response.
1536 Note: The other SNMPv2 errors are not supported.
1538 In either case, the command should exit once it has finished
1540 processing. Each request (and each varbind within a single re‐
1541 quest) will trigger a separate invocation of the command.
1542 The default registration priority is 127. This can be changed
1544 by supplying the optional -p flag, with lower priority registra‐
1545 tions being used in preference to higher priority values.
1546 pass_persist [-p priority] MIBOID PROG
1548 will also pass control of the subtree rooted at MIBOID to the
1549 specified PROG command. However this command will continue to
1550 run after the initial request has been answered, so subsequent
1551 requests can be processed without the startup overheads.
1552 Upon initialization, PROG will be passed the string "PING\n" on
1554 stdin, and should respond by printing "PONG\n" to stdout.
1555 For GET and GETNEXT requests, PROG will be passed two lines on
1557 stdin, the command (get or getnext) and the requested OID. It
1558 should respond by printing three lines to stdout - the OID for
1559 the result varbind, the TYPE and the VALUE itself - exactly as
1560 for the pass directive above. If the command cannot return an
1561 appropriate varbind, it should print print "NONE\n" to stdout
1562 (but continue running).
1563 For SET requests, PROG will be passed three lines on stdin, the
1565 command (set) and the requested OID, followed by the type and
1566 value (both on the same line). If the assignment is successful,
1567 the command should print "DONE\n" to stdout. Errors should be
1568 indicated by writing one of the strings not-writable,
1569 wrong-type, wrong-length, wrong-value or inconsistent-value to
1570 stdout, and the agent will generate the appropriate error re‐
1571 sponse. In either case, the command should continue running.
1572 The registration priority can be changed using the optional -p
1574 flag, just as for the pass directive.
1575 pass and pass_persist extensions can only be configured via the sn‐
1577 mpd.conf file. They cannot be set up via SNMP SET requests.
1578 Embedded Perl Support
1580 Programs using the previous extension mechanisms can be written in any
1581 convenient programming language - including perl, which is a common
1582 choice for pass-through extensions in particular. However the Net-SNMP
1583 agent also includes support for embedded perl technology (similar to
1584 mod_perl for the Apache web server). This allows the agent to inter‐
1585 pret perl scripts directly, thus avoiding the overhead of spawning pro‐
1586 cesses and initializing the perl system when a request is received.
1587 Use of this mechanism requires that the agent was built with support
1589 for the embedded perl mechanism, which is not part of the default build
1590 environment. It must be explicitly included by specifying the '--en‐
1591 able-embedded-perl' option to the configure script when the package is
1592 first built.
1593 If enabled, the following directives will be recognised:
1595 disablePerl true
1597 will turn off embedded perl support entirely (e.g. if there are
1598 problems with the perl installation).
1599 perlInitFile FILE
1601 loads the specified initialisation file (if present) immediately
1602 before the first perl directive is parsed. If not explicitly
1603 specified, the agent will look for the default initialisation
1604 file /usr/share/snmp/snmp_perl.pl.
1605 The default initialisation file creates an instance of a Net‐
1607 SNMP::agent object - a variable $agent which can be used to reg‐
1608 ister perl-based MIB handler routines.
1609 perl EXPRESSION
1611 evaluates the given expression. This would typically register a
1612 handler routine to be called when a section of the OID tree was
1613 requested:
1614 perl use Data::Dumper;
1615 perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
1616 perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
1617 This expression could also source an external file:
1619 perl 'do /path/to/file.pl';
1620 or perform any other perl-based processing that might be re‐
1622 quired.
1623 Dynamically Loadable Modules
1625 Most of the MIBs supported by the Net-SNMP agent are implemented as C
1626 code modules, which were compiled and linked into the agent libraries
1627 when the suite was first built. Such implementation modules can also
1628 be compiled independently and loaded into the running agent once it has
1629 started. Use of this mechanism requires that the agent was built with
1630 support for the ucd-snmp/dlmod module (which is included as part of the
1631 default build configuration).
1632 dlmod NAME PATH
1634 will load the shared object module from the file PATH (an abso‐
1635 lute filename), and call the initialisation routine init_NAME.
1636 Note: If the specified PATH is not a fully qualified filename,
1638 it will be interpreted relative to
1639 /usr/lib(64)/snmp/dlmod, and .so will be appended to the
1640 filename.
1641 This functionality can also be configured using SNMP SET requests to
1643 the UCD-DLMOD-MIB.
1644 Proxy Support
1646 Another mechanism for extending the functionality of the agent is to
1647 pass selected requests (or selected varbinds) to another SNMP agent,
1648 which can be running on the same host (presumably listening on a dif‐
1649 ferent port), or on a remote system. This can be viewed either as the
1650 main agent delegating requests to the remote one, or acting as a proxy
1651 for it. Use of this mechanism requires that the agent was built with
1652 support for the ucd-snmp/proxy module (which is included as part of the
1653 default build configuration).
1654 proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
1656 will pass any incoming requests under OID to the agent listening
1657 on the port specified by the transport address HOST. See the
1658 section LISTENING ADDRESSES in the snmpd(8) manual page for more
1659 information about the format of listening addresses.
1660 Note: To proxy the entire MIB tree, use the OID .1.3 (not the
1662 top-level .1)
1663 The SNMPCMD_ARGS should provide sufficient version and administrative
1665 information to generate a valid SNMP request (see snmpcmd(1)).
1666 Note: The proxied request will not use the administrative settings
1668 from the original request.
1669 If a CONTEXTNAME is specified, this will register the proxy delegation
1671 within the named context in the local agent. Defining multiple proxy
1672 directives for the same OID but different contexts can be used to query
1673 several remote agents through a single proxy, by specifying the appro‐
1674 priate SNMPv3 context in the incoming request (or using suitable con‐
1675 figured community strings - see the com2sec directive).
1676 Specifying the REMOID parameter will map the local MIB tree rooted at
1678 OID to an equivalent subtree rooted at REMOID on the remote agent.
1679 SMUX Sub-Agents
1681 The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1682 with SMUX-based subagents (such as gated, zebra or quagga). Use of
1683 this mechanism requires that the agent was built with support for the
1684 smux module, which is not part of the default build environment, and
1685 must be explicitly included by specifying the '--with-mib-modules=smux'
1686 option to the configure script when the package is first built.
1687 Note: This extension protocol has been officially deprecated in
1689 favour of AgentX (see below).
1690 smuxpeer OID PASS
1692 will register a subtree for SMUX-based processing, to be authen‐
1693 ticated using the password PASS. If a subagent (or "peer") con‐
1694 nects to the agent and registers this subtree then requests for
1695 OIDs within it will be passed to that SMUX subagent for process‐
1696 ing.
1697 A suitable entry for an OSPF routing daemon (such as gated, ze‐
1699 bra or quagga) might be something like
1700 smuxpeer .1.3.6.1.2.1.14 ospf_pass
1701 smuxsocket <IPv4-address>
1703 defines the IPv4 address for SMUX peers to communicate with the
1704 Net-SNMP agent. The default is to listen on all IPv4 interfaces
1705 ("0.0.0.0"), unless the package has been configured with "--en‐
1706 able-local-smux" at build time, which causes it to only listen
1707 on 127.0.0.1 by default. SMUX uses the well-known TCP port 199.
1708 Note the Net-SNMP agent will only operate as a SMUX master agent. It
1710 does not support acting in a SMUX subagent role.
1711 AgentX Sub-Agents
1713 The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both mas‐
1714 ter and subagent roles. Use of this mechanism requires that the agent
1715 was built with support for the agentx module (which is included as part
1716 of the default build configuration), and also that this support is ex‐
1717 plicitly enabled (e.g. via the snmpd.conf file).
1718 There are two directives specifically relevant to running as an AgentX
1720 master agent:
1721 master agentx
1723 will enable the AgentX functionality and cause the agent to
1724 start listening for incoming AgentX registrations. This can
1725 also be activated by specifying the '-x' command-line option (to
1726 specify an alternative listening socket).
1727 agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
1729 Defines the permissions and ownership of the AgentX Unix Domain
1730 socket, and the parent directories of this socket. SOCKPERMS
1731 and DIRPERMS must be octal digits (see chmod(1) ). By default
1732 this socket will only be accessible to subagents which have the
1733 same userid as the agent.
1734 There is one directive specifically relevant to running as an AgentX
1736 sub-agent:
1737 agentXPingInterval NUM
1739 will make the subagent try and reconnect every NUM seconds to
1740 the master if it ever becomes (or starts) disconnected.
1741 The remaining directives are relevant to both AgentX master and sub-
1743 agents:
1744 agentXSocket [<transport-specifier>:]<transport-address>[,...]
1746 defines the address the master agent listens at, or the subagent
1747 should connect to. The default is the Unix Domain socket
1748 "/var/agentx/master". Another common alternative is tcp:local‐
1749 host:705. See the section LISTENING ADDRESSES in the snmpd(8)
1750 manual page for more information about the format of addresses.
1751 Note: Specifying an AgentX socket does not automatically enable
1753 AgentX functionality (unlike the '-x' command-line op‐
1754 tion).
1755 agentXTimeout NUM
1757 defines the timeout period (NUM seconds) for an AgentX request.
1758 Default is 1 second. NUM also be specified with a suffix of one
1759 of s (for seconds), m (for minutes), h (for hours), d (for
1760 days), or w (for weeks).
1761 agentXRetries NUM
1763 defines the number of retries for an AgentX request. Default is
1764 5 retries.
1765 net-snmp ships with both C and Perl APIs to develop your own AgentX
1767 subagent.
1768
1770 override [-rw] OID TYPE VALUE
1771 This directive allows you to override a particular OID with a
1772 different value (and possibly a different type of value). The
1773 -rw flag will allow snmp SETs to modify it's value as well.
1774 (note that if you're overriding original functionality, that
1775 functionality will be entirely lost. Thus SETS will do nothing
1776 more than modify the internal overridden value and will not per‐
1777 form any of the original functionality intended to be provided
1778 by the MIB object. It's an emulation only.) An example:
1779 override sysDescr.0 octet_str "my own sysDescr"
1781 That line will set the sysDescr.0 value to "my own sysDescr" as
1783 well as make it modifiable with SNMP SETs as well (which is ac‐
1784 tually illegal according to the MIB specifications).
1785 Note that care must be taken when using this. For example, if
1787 you try to override a property of the 3rd interface in the
1788 ifTable with a new value and later the numbering within the
1789 ifTable changes it's index ordering you'll end up with problems
1790 and your modified value won't appear in the right place in the
1791 table.
1792 Valid TYPEs are: integer, uinteger, octet_str, object_id,
1794 counter, null (for gauges, use "uinteger"; for bit strings, use
1795 "octet_str"). Note that setting an object to "null" effectively
1796 delete's it as being accessible. No VALUE needs to be given if
1797 the object type is null.
1798 More types should be available in the future.
1800 If you're trying to figure out aspects of the various mib modules (pos‐
1802 sibly some that you've added yourself), the following may help you spit
1803 out some useful debugging information. First off, please read the sn‐
1804 mpd manual page on the -D flag. Then the following configuration sn‐
1805 mpd.conf token, combined with the -D flag, can produce useful output:
1806 injectHandler HANDLER modulename [beforeThis]
1808 This will insert new handlers into the section of the mib tree
1809 referenced by "modulename". If "beforeThis" is specified then
1810 the module will be injected before the named module. This is
1811 useful for getting a handler into the exact right position in
1812 the chain.
1813 The types of handlers available for insertion are:
1815 stash_cache
1817 Caches information returned from the lower level. This
1818 greatly help the performance of the agent, at the cost of
1819 caching the data such that its no longer "live" for 30
1820 seconds (in this future, this will be configurable).
1821 Note that this means snmpd will use more memory as well
1822 while the information is cached. Currently this only
1823 works for handlers registered using the table_iterator
1824 support, which is only a few mib tables. To use it, you
1825 need to make sure to install it before the table_iterator
1826 point in the chain, so to do this:
1827 injectHandler stash_cache NAME table_iterator
1829 If you want a table to play with, try walking the nsMod‐
1831 uleTable with and without this injected.
1832 debug Prints out lots of debugging information when the
1835 -Dhelper:debug flag is passed to the snmpd application.
1836 read_only
1839 Forces turning off write support for the given module.
1840 serialize
1843 If a module is failing to handle multiple requests prop‐
1844 erly (using the new 5.0 module API), this will force the
1845 module to only receive one request at a time.
1846 bulk_to_next
1849 If a module registers to handle getbulk support, but for
1850 some reason is failing to implement it properly, this
1851 module will convert all getbulk requests to getnext re‐
1852 quests before the final module receives it.
1853 dontLogTCPWrappersConnects
1855 If the snmpd was compiled with TCP Wrapper support, it logs ev‐
1856 ery connection made to the agent. This setting disables the log
1857 messages for accepted connections. Denied connections will still
1858 be logged.
1859 Figuring out module names
1861 To figure out which modules you can inject things into, run snm‐
1862 pwalk on the nsModuleTable which will give a list of all named
1863 modules registered within the agent.
1864 Internal Data tables
1866 table NAME
1867 add_row NAME INDEX(ES) VALUE(S)
1869
1871 o The Net-SNMP agent can be instructed to re-read the various con‐
1872 figuration files, either via an snmpset assignment of integer(1)
1873 to UCD-SNMP-MIB::versionUpdateConfig.0
1874 (.1.3.6.1.4.1.2021.100.11.0), or by sending a kill -HUP signal
1875 to the agent process.
1876 o All directives listed with a value of "yes" actually accept a
1878 range of boolean values. These will accept any of 1, yes or
1879 true to enable the corresponding behaviour, or any of 0, no or
1880 false to disable it. The default in each case is for the fea‐
1881 ture to be turned off, so these directives are typically only
1882 used to enable the appropriate behaviour.
1883
1885 See the EXAMPLE.CONF file in the top level source directory for a more
1886 detailed example of how the above information is used in real examples.
1887
1889 /etc/snmp/snmpd.conf
1890
1892 snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM‐
1893 PLE.conf, netsnmp_config_api(3).
1894V5.9.4.pre2 30 Jun 2010 SNMPD.CONF(5)