1SNMPD.CONF(5) Net-SNMP SNMPD.CONF(5)
2
6 snmpd.conf - configuration file for the Net-SNMP SNMP agent
7
9 The Net-SNMP agent uses one or more configuration files to control its
10 operation and the management information provided. These files
11 (snmpd.conf and snmpd.local.conf) can be located in one of several
12 locations, as described in the snmp_config(5) manual page.
13 The (perl) application snmpconf can be used to generate configuration
15 files for the most common agent requirements. See the snmpconf(1) man‐
16 ual page for more information, or try running the command:
17 snmpconf -g basic_setup
19 There are a large number of directives that can be specified, but these
21 mostly fall into four distinct categories:
22 · those controlling who can access the agent
24 · those configuring the information that is supplied by the agent
26 · those controlling active monitoring of the local system
28 · those concerned with extending the functionality of the agent.
30 Some directives don't fall naturally into any of these four categories,
32 but this covers the majority of the contents of a typical snmpd.conf
33 file. A full list of recognised directives can be obtained by running
34 the command:
35 snmpd -H
37
39 Although most configuration directives are concerned with the MIB
40 information supplied by the agent, there are a handful of directives
41 that control the behaviour of snmpd considered simply as a daemon pro‐
42 viding a network service.
43 agentaddress [<transport-specifier>:]<transport-address>[,...]
45 defines a list of listening addresses, on which to receive
46 incoming SNMP requests. See the section LISTENING ADDRESSES in
47 the snmpd(8) manual page for more information about the format
48 of listening addresses.
49 The default behaviour is to listen on UDP port 161 on all IPv4
51 interfaces.
52 agentgroup {GROUP|#GID}
54 changes to the specified group after opening the listening
55 port(s). This may refer to a group by name (GROUP), or a
56 numeric group ID starting with '#' (#GID).
57 agentuser {USER|#UID}
59 changes to the specified user after opening the listening
60 port(s). This may refer to a user by name (USER), or a numeric
61 user ID starting with '#' (#UID).
62 leave_pidfile yes
64 instructs the agent to not remove its pid file on shutdown.
65 Equivalent to specifying "-U" on the command line.
66 maxGetbulkRepeats NUM
68 Sets the maximum number of responses allowed for a single vari‐
69 able in a getbulk request. Set to 0 to enable the default and
70 set it to -1 to enable unlimited. Because memory is allocated
71 ahead of time, sitting this to unlimited is not considered safe
72 if your user population can not be trusted. A repeat number
73 greater than this will be truncated to this value.
74 This is set by default to -1.
76 maxGetbulkResponses NUM
78 Sets the maximum number of responses allowed for a getbulk
79 request. This is set by default to 100. Set to 0 to enable the
80 default and set it to -1 to enable unlimited. Because memory is
81 allocated ahead of time, sitting this to unlimited is not con‐
82 sidered safe if your user population can not be trusted.
83 In general, the total number of responses will not be allowed to
85 exceed the maxGetbulkResponses number and the total number
86 returned will be an integer multiple of the number of variables
87 requested times the calculated number of repeats allow to fit
88 below this number.
89 Also not that processing of maxGetbulkRepeats is handled first.
91 SNMPv3 Configuration
93 SNMPv3 requires an SNMP agent to define a unique "engine ID" in order
94 to respond to SNMPv3 requests. This ID will normally be determined
95 automatically, using two reasonably non-predictable values - a
96 (pseudo-)random number and the current time in seconds. This is the
97 recommended approach. However the capacity exists to define the
98 engineID in other ways:
99 engineID STRING
101 specifies that the engineID should be built from the given text
102 STRING.
103 engineIDType 1|2|3
105 specifies that the engineID should be built from the IPv4
106 address (1), IPv6 address (2) or MAC address (3). Note that
107 changing the IP address (or switching the network interface
108 card) may cause problems.
109 engineIDNic INTERFACE
111 defines which interface to use when determining the MAC address.
112 If engineIDType 3 is not specified, then this directive has no
113 effect.
114 The default is to use eth0.
116
118 SNMPv3 was originally defined using the User-Based Security Model
119 (USM), which contains a private list of users and keys specific to the
120 SNMPv3 protocol. The operational community, however, declared it a
121 pain to manipulate yet another database and would prefer to use exist‐
122 ing infrastructure. To that end the IETF created the ISMS working
123 group to battle that problem, and the ISMS working group decided to
124 tunnel SNMP over SSH and DTLS to make use existing user and authentica‐
125 tion infrastructures.
126 SNMPv3 USM Users
128 To use the USM based SNMPv3-specific users, you'll need to create them.
129 It is recommended you use the net-snmp-config command to do this, but
130 you can also do it by directly specifying createUser directives your‐
131 self instead:
132 createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES]
134 [privpassphrase]
135 MD5 and SHA are the authentication types to use. DES and AES
137 are the privacy protocols to use. If the privacy passphrase is
138 not specified, it is assumed to be the same as the authentica‐
139 tion passphrase. Note that the users created will be useless
140 unless they are also added to the VACM access control tables
141 described above.
142 SHA authentication and DES/AES privacy require OpenSSL to be
144 installed and the agent to be built with OpenSSL support. MD5
145 authentication may be used without OpenSSL.
146 Warning: the minimum pass phrase length is 8 characters.
148 SNMPv3 users can be created at runtime using the snmpusm(1) com‐
150 mand.
151 Instead of figuring out how to use this directive and where to
153 put it (see below), just run "net-snmp-config --create-
154 snmpv3-user" instead, which will add one of these lines to the
155 right place.
156 This directive should be placed into the /var/lib/net-
158 snmp/snmpd.conf file instead of the other normal locations. The
159 reason is that the information is read from the file and then
160 the line is removed (eliminating the storage of the master pass‐
161 word for that user) and replaced with the key that is derived
162 from it. This key is a localized key, so that if it is stolen
163 it can not be used to access other agents. If the password is
164 stolen, however, it can be.
165 If you need to localize the user to a particular EngineID (this
167 is useful mostly in the similar snmptrapd.conf file), you can
168 use the -e argument to specify an EngineID as a hex value (EG,
169 "0x01020304").
170 If you want to generate either your master or localized keys
172 directly, replace the given password with a hexstring (preceeded
173 by a "0x") and precede the hex string by a -m or -l token
174 (respectively). EGs:
175 [these keys are *not* secure but are easy to visually parse for
177 counting purposes. Please generate random keys instead of using
178 these examples]
179 createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
181 createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
182 Due to the way localization happens, localized privacy keys are
184 expected to be the length needed by the algorithm (128 bits for
185 all supported algorithms). Master encryption keys, though, need
186 to be the length required by the authentication algorithm not
187 the length required by the encrypting algorithm (MD5: 16 bytes,
188 SHA: 20 bytes).
189 SSH Support
191 To use SSH, you'll need to configure sshd to invoke sshtosnmp as well
192 as configure the access control settings to allow access through the
193 tsm security model using the user name provided to snmpd by the ssh
194 transport.
195 DTLS Support
197 For DTLS, snmpd will need to be configured with it's own X.509 certifi‐
198 cate as well as the certificates of the client users to be allowed to
199 connect to the agent. The access control will need to be set up as
200 well to allow access through the tsm security model. The CommonName of
201 the Subject from the X.509 certificate will be passed to snmpd as the
202 SNMPv3 username to use. See the http://www.net-
203 snmp.org/wiki/index.php/Using_DTLS web page for more detailed instruc‐
204 tions for setting up DTLS.
205 defX509ServerPub FILE
207 defX509ServerPriv FILE
209 These two directives specify the public and private key files
210 for the certificate that snmpd should present to incoming con‐
211 nections.
212 defX509ClientCerts FILE
214 This directive specifies a file containing all of the public
215 keys (or CAs of public keys) for clients to connect the server
216 with.
217
219 snmpd supports the View-Based Access Control Model (VACM) as defined in
220 RFC 2575, to control who can retrieve or update information. To this
221 end, it recognizes various directives relating to access control.
222 Traditional Access Control
224 Most simple access control requirements can be specified using the
225 directives rouser/rwuser (for SNMPv3) or rocommunity/rwcommunity (for
226 SNMPv1 or SNMPv2c).
227 rouser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
229 rwuser [-s SECMODEL] USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
231 specify an SNMPv3 user that will be allowed read-only (GET and
232 GETNEXT) or read-write (GET, GETNEXT and SET) access respec‐
233 tively. By default, this will provide access to the full OID
234 tree for authenticated (including encrypted) SNMPv3 requests,
235 using the default context. An alternative minimum security
236 level can be specified using noauth (to allow unauthenticated
237 requests), or priv (to enforce use of encryption). The OID
238 field restricts access for that user to the subtree rooted at
239 the given OID, or the named view. An optional context can also
240 be specified, or "context*" to denote a context prefix. If no
241 context field is specified (or the token "*" is used), the
242 directive will match all possible contexts.
243 If SECMODEL is specified then it will be the security model
245 required for that user (note that identical user names may come
246 in over different security models and will be appropriately sep‐
247 arated via the access control settings). The default security
248 model is "usm" and the other common security models are likely
249 "tsm" when using SSH or DTLS support and "ksm" if the Kerberos
250 support has been compiled in.
251 rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
253 rwcommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
255 specify an SNMPv1 or SNMPv2c community that will be allowed
256 read-only (GET and GETNEXT) or read-write (GET, GETNEXT and SET)
257 access respectively. By default, this will provide access to
258 the full OID tree for such requests, regardless of where they
259 were sent from. The SOURCE token can be used to restrict access
260 to requests from the specified system(s) - see com2sec for the
261 full details. The OID field restricts access for that community
262 to the subtree rooted at the given OID, or named view. Contexts
263 are typically less relevant to community-based SNMP versions,
264 but the same behaviour applies here.
265 rocommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
267 rwcommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
269 are directives relating to requests received using IPv6 (if the
270 agent supports such transport domains). The interpretation of
271 the SOURCE, OID, VIEW and CONTEXT tokens are exactly the same as
272 for the IPv4 versions.
273 In each case, only one directive should be specified for a given SNMPv3
275 user, or community string. It is not appropriate to specify both
276 rouser and rwuser directives referring to the same SNMPv3 user (or
277 equivalent community settings). The rwuser directive provides all the
278 access of rouser (as well as allowing SET support). The same holds
279 true for the community-based directives.
280 More complex access requirements (such as access to two or more dis‐
282 tinct OID subtrees, or different views for GET and SET requests) should
283 use one of the other access control mechanisms. Note that if several
284 distinct communities or SNMPv3 users need to be granted the same level
285 of access, it would also be more efficient to use the main VACM config‐
286 uration directives.
287 VACM Configuration
289 The full flexibility of the VACM is available using four configuration
290 directives - com2sec, group, view and access. These provide direct
291 configuration of the underlying VACM tables.
292 com2sec [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
294 com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
296 map an SNMPv1 or SNMPv2c community string to a security name -
297 either from a particular range of source addresses, or globally
298 ("default"). A restricted source can either be a specific host‐
299 name (or address), or a subnet - represented as IP/MASK (e.g.
300 10.10.10.0/255.255.255.0), or IP/BITS (e.g. 10.10.10.0/24), or
301 the IPv6 equivalents.
302 The same community string can be specified in several separate
304 directives (presumably with different source tokens), and the
305 first source/community combination that matches the incoming
306 request will be selected. Various source/community combinations
307 can also map to the same security name.
308 If a CONTEXT is specified (using -Cn), the community string will
310 be mapped to a security name in the named SNMPv3 context. Other‐
311 wise the default context ("") will be used.
312 com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY
314 is the Unix domain sockets version of com2sec.
315 group GROUP {v1|v2c|usm|tsm|ksm} SECNAME
317 maps a security name (in the specified security model) into a
318 named group. Several group directives can specify the same
319 group name, allowing a single access setting to apply to several
320 users and/or community strings.
321 Note that groups must be set up for the two community-based mod‐
323 els separately - a single com2sec (or equivalent) directive will
324 typically be accompanied by two group directives.
325 view VNAME TYPE OID [MASK]
327 defines a named "view" - a subset of the overall OID tree. This
328 is most commonly a single subtree, but several view directives
329 can be given with the same view name (VNAME), to build up a more
330 complex collection of OIDs. TYPE is either included or
331 excluded, which can again define a more complex view (e.g by
332 excluding certain sensitive objects from an otherwise accessible
333 subtree).
334 MASK is a list of hex octets (optionally separated by '.' or
336 ':') with the set bits indicating which subidentifiers in the
337 view OID to match against. If not specified, this defaults to
338 matching the OID exactly (all bits set), thus defining a simple
339 OID subtree. So:
340 view iso1 included .iso 0xf0
341 view iso2 included .iso
342 view iso3 included .iso.org.dod.mgmt 0xf0
343 would all define the same view, covering the whole of the
345 'iso(1)' subtree (with the third example ignoring the subidenti‐
346 fiers not covered by the mask).
347 More usefully, the mask can be used to define a view covering a
349 particular row (or rows) in a table, by matching against the
350 appropriate table index value, but skipping the column subiden‐
351 tifier:
352 view ifRow4 included .1.3.6.1.2.1.2.2.1.0.4 0xff:a0
354 Note that a mask longer than 8 bits must use ':' to separate the
356 individual octets.
357 access GROUP CONTEXT {any|v1|v2c|usm|tsm|ksm} LEVEL PREFX READ WRITE
359 NOTIFY
360 maps from a group of users/communities (with a particular secu‐
361 rity model and minimum security level, and in a specific con‐
362 text) to one of three views, depending on the request being pro‐
363 cessed.
364 LEVEL is one of noauth, auth, or priv. PREFX specifies how CON‐
366 TEXT should be matched against the context of the incoming
367 request, either exact or prefix. READ, WRITE and NOTIFY speci‐
368 fies the view to be used for GET*, SET and TRAP/INFORM requests
369 (althought the NOTIFY view is not currently used). For v1 or
370 v2c access, LEVEL will need to be noauth.
371 Typed-View Configuration
373 The final group of directives extend the VACM approach into a more
374 flexible mechanism, which can be applied to other access control
375 requirements. Rather than the fixed three views of the standard VACM
376 mechanism, this can be used to configure various different view types.
377 As far as the main SNMP agent is concerned, the two main view types are
378 read and write, corresponding to the READ and WRITE views of the main
379 access directive. See the 'snmptrapd.conf(5)' man page for discussion
380 of other view types.
381 authcommunity TYPES COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
383 is an alternative to the rocommunity/rwcommunity directives.
384 TYPES will usually be read or read,write respectively. The view
385 specification can either be an OID subtree (as before), or a
386 named view (defined using the view directive) for greater flexi‐
387 bility. If this is omitted, then access will be allowed to the
388 full OID tree. If CONTEXT is specified, access is configured
389 within this SNMPv3 context. Otherwise the default context ("")
390 is used.
391 authuser TYPES [-s MODEL] USER [LEVEL [OID | -V VIEW [CONTEXT]]]
393 is an alternative to the rouser/rwuser directives. The fields
394 TYPES, OID, VIEW and CONTEXT have the same meaning as for auth‐
395 community.
396 authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW [CONTEXT]]]
398 is a companion to the authuser directive, specifying access for
399 a particular group (defined using the group directive as usual).
400 Both authuser and authgroup default to authenticated requests -
401 LEVEL can also be specified as noauth or priv to allow unauthen‐
402 ticated requests, or require encryption respectively. Both
403 authuser and authgroup directives also default to configuring
404 access for SNMPv3/USM requests - use the '-s' flag to specify an
405 alternative security model (using the same values as for access
406 above).
407 authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
409 also configures the access for a particular group, specifying
410 the name and type of view to apply. The MODEL and LEVEL fields
411 are interpreted in the same way as for authgroup. If CONTEXT is
412 specified, access is configured within this SNMPv3 context (or
413 contexts with this prefix if the CONTEXT field ends with '*').
414 Otherwise the default context ("") is used.
415 setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
417 is a direct equivalent to the original access directive, typi‐
418 cally listing the view types as read or read,write as appropri‐
419 ate. (or see 'snmptrapd.conf(5)' for other possibilities). All
420 other fields have the same interpretation as with access.
421
423 Most of the information reported by the Net-SNMP agent is retrieved
424 from the underlying system, or dynamically configured via SNMP SET
425 requests (and retained from one run of the agent to the next). How‐
426 ever, certain MIB objects can be configured or controlled via the
427 snmpd.conf(5) file.
428 System Group
430 Most of the scalar objects in the 'system' group can be configured in
431 this way:
432 sysLocation STRING
434 sysContact STRING
436 sysName STRING
438 set the system location, system contact or system name (sysLoca‐
439 tion.0, sysContact.0 and sysName.0) for the agent respectively.
440 Ordinarily these objects are writeable via suitably authorized
441 SNMP SET requests. However, specifying one of these directives
442 makes the corresponding object read-only, and attempts to SET it
443 will result in a notWritable error response.
444 sysServices NUMBER
446 sets the value of the sysServices.0 object. For a host system,
447 a good value is 72 (application + end-to-end layers). If this
448 directive is not specified, then no value will be reported for
449 the sysServices.0 object.
450 sysDescr STRING
452 sysObjectID OID
454 sets the system description or object ID for the agent.
455 Although these MIB objects are not SNMP-writable, these direc‐
456 tives can be used by a network administrator to configure suit‐
457 able values for them.
458 Interfaces Group
460 interface NAME TYPE SPEED
461 can be used to provide appropriate type and speed settings for
462 interfaces where the agent fails to determine this information
463 correctly. TYPE is a type value as given in the IANAifType-MIB,
464 and can be specified numerically or by name (assuming this MIB
465 is loaded).
466 interface_fadeout TIMEOUT
468 specifies, for how long the agent keeps entries in ifTable after
469 appropriate interfaces have been removed from system (typically
470 various ppp, tap or tun interfaces). Timeout value is in sec‐
471 onds. Default value is 300 (=5 minutes).
472 interface_replace_old yes
474 can be used to remove already existing entries in ifTable when
475 an interface with the same name appears on the system. E.g. when
476 ppp0 interface is removed, it is still listed in the table for
477 interface_fadeout seconds. This option ensures, that the old
478 ppp0 interface is removed even before the interface_fadeout
479 timeour when new ppp0 (with different ifIndex) shows up.
480 Host Resources Group
482 This requires that the agent was built with support for the host module
483 (which is now included as part of the default build configuration on
484 the major supported platforms).
485 ignoreDisk STRING
487 controls which disk devices are scanned as part of populating
488 the hrDiskStorageTable (and hrDeviceTable). The HostRes imple‐
489 mentation code includes a list of disk device patterns appropri‐
490 ate for the current operating system, some of which may cause
491 the agent to block when trying to open the corresponding disk
492 devices. This might lead to a timeout when walking these
493 tables, possibly resulting in inconsistent behaviour. This
494 directive can be used to specify particular devices (either
495 individually or wildcarded) that should not be checked.
496 Note: Please consult the source (host/hr_disk.c) and check for
498 the Add_HR_Disk_entry calls relevant for a particular O/S
499 to determine the list of devices that will be scanned.
500 The pattern can include one or more wildcard expressions. See
502 snmpd.examples(5) for illustration of the wildcard syntax.
503 skipNFSInHostResources true
505 controls whether NFS and NFS-like file systems should be omitted
506 from the hrStorageTable (true or 1) or not (false or 0, which is
507 the default). If the Net-SNMP agent gets hung on NFS-mounted
508 filesystems, you can try setting this to '1'.
509 storageUseNFS [1|2]
511 controls how NFS and NFS-like file systems should be reported in
512 the hrStorageTable. as 'Network Disks' (1) or 'Fixed Disks' (2)
513 Historically, the Net-SNMP agent has reported such file systems
514 as 'Fixed Disks', and this is still the default behaviour. Set‐
515 ting this directive to '1' reports such file systems as ´Network
516 Disks', as required by the Host Resources MIB.
517 realStorageUnits
519 controlls how the agent reports hrStorageAllocationUnits,
520 hrStorageSize and hrStorageUsed in hrStorageTable. With this
521 option set to '0', the agent re-calculates these values for big
522 storage drives with small allocation units so hrStorageAlloca‐
523 tionUnits x hrStorageSize gives real size of the storage.
524 Example:
526 Linux xfs 16TB filesystem with 4096 bytes large blocks
527 will be reported as hrStorageAllocationUnits = 8192 and
528 hrStorageSize = 2147483647, so 8192 x 2147483647 gives
529 real size of the filesystem (=16 TB).
530 Setting this directive to '1' (=default) turns off this calcula‐
532 tion and the agent reports real hrStorageAllocationUnits, but it
533 might report wrong hrStorageSize for big drives because the
534 value won't fit into Integer32. In this case, hrStorageAlloca‐
535 tionUnits x hrStorageSize won't give real size of the storage.
536 Process Monitoring
538 The hrSWRun group of the Host Resources MIB provides information about
539 individual processes running on the local system. The prTable of the
540 UCD-SNMP-MIB complements this by reporting on selected services (which
541 may involve multiple processes). This requires that the agent was
542 built with support for the ucd-snmp/proc module (which is included as
543 part of the default build configuration).
544 proc NAME [MAX [MIN]]
546 monitors the number of processes called NAME (as reported by
547 "/bin/ps -e") running on the local system.
548 If the number of NAMEd processes is less than MIN or greater
550 than MAX, then the corresponding prErrorFlag instance will be
551 set to 1, and a suitable description message reported via the
552 prErrMessage instance.
553 Note: This situation will not automatically trigger a trap to
555 report the problem - see the DisMan Event MIB section
556 later.
557 If neither MAX nor MIN are specified (or are both 0), they will
559 default to infinity and 1 respectively ("at least one"). If
560 only MAX is specified, MIN will default to 0 ("no more than
561 MAX").
562 procfix NAME PROG ARGS
564 registers a command that can be run to fix errors with the given
565 process NAME. This will be invoked when the corresponding prE‐
566 rrFix instance is set to 1.
567 Note: This command will not be invoked automatically.
569 The procfix directive must be specified after the matching proc
571 directive, and cannot be used on its own.
572 If no proc directives are defined, then walking the prTable will fail
574 (noSuchObject).
575 Disk Usage Monitoring
577 This requires that the agent was built with support for the ucd-
578 snmp/disk module (which is included as part of the default build con‐
579 figuration).
580 disk PATH [ MINSPACE | MINPERCENT% ]
582 monitors the disk mounted at PATH for available disk space.
583 Disks mounted after the agent has started will not be monitored,
584 unless includeAllDisks option is specified.
585 The minimum threshold can either be specified in kB (MINSPACE)
587 or as a percentage of the total disk (MINPERCENT% with a '%'
588 character), defaulting to 100kB if neither are specified. If
589 the free disk space falls below this threshold, then the corre‐
590 sponding dskErrorFlag instance will be set to 1, and a suitable
591 description message reported via the dskErrorMsg instance.
592 Note: This situation will not automatically trigger a trap to
594 report the problem - see the DisMan Event MIB section
595 later.
596 includeAllDisks MINPERCENT%
598 configures monitoring of all disks found on the system, using
599 the specified (percentage) threshold. The dskTable is dynami‐
600 cally updated, unmounted disks disappear from the table and
601 newly mounted disks are added to the table. The threshold for
602 individual disks can be adjusted using suitable disk directives
603 (which can come either before or after the includeAllDisks
604 directive).
605 Note: Whether disk directives appears before or after
607 includeAllDisks may affect the indexing of the dskTable.
608 Only one includeAllDisks directive should be specified - any
610 subsequent copies will be ignored.
611 The list of mounted disks will be determined from HOST-
613 RESOURCES-MIB::hrFSTable.
614 If neither any disk directives or includeAllDisks are defined, then
616 walking the dskTable will fail (noSuchObject).
617 Disk I/O Monitoring
619 This requires that the agent was built with support for the
620 ucd-snmp/diskio module (which is not included as part of the default
621 build configuration).
622 By default, all block devices known to the operating system are
624 included in the diskIOTable. On platforms other than Linux, this module
625 has no configuration directives.
626 On Linux systems, it is possible to report only explicitly whitelisted
628 devices. It may take significant amount of time to process diskIOTable
629 data on systems with tens of thousands of block devices and whitelist‐
630 ing only the important ones avoids large CPU consumption.
631 diskio <device>
633 Enables whitelisting of devices and adds the device to the
634 whitelist. Only explicitly whitelisted devices will be reported.
635 This option may be used multiple times.
636 System Load Monitoring
638 This requires that the agent was built with support for either the ucd-
639 snmp/loadave module or the ucd-snmp/memory module respectively (both of
640 which are included as part of the default build configuration).
641 load MAX1 [MAX5 [MAX15]]
643 monitors the load average of the local system, specifying
644 thresholds for the 1-minute, 5-minute and 15-minute averages.
645 If any of these loads exceed the associated maximum value, then
646 the corresponding laErrorFlag instance will be set to 1, and a
647 suitable description message reported via the laErrMessage
648 instance.
649 Note: This situation will not automatically trigger a trap to
651 report the problem - see the DisMan Event MIB section
652 later.
653 If the MAX15 threshold is omitted, it will default to the MAX5
655 value. If both MAX5 and MAX15 are omitted, they will default to
656 the MAX1 value. If this directive is not specified, all three
657 thresholds will default to a value of DEFMAXLOADAVE.
658 If a threshold value of 0 is given, the agent will not report
660 errors via the relevant laErrorFlag or laErrMessage instances,
661 regardless of the current load.
662 Unlike the proc and disk directives, walking the walking the laTable
664 will succeed (assuming the ucd-snmp/loadave module was configured into
665 the agent), even if the load directive is not present.
666 swap MIN
668 monitors the amount of swap space available on the local system.
669 If this falls below the specified threshold (MIN kB), then the
670 memErrorSwap object will be set to 1, and a suitable description
671 message reported via memSwapErrorMsg.
672 Note: This situation will not automatically trigger a trap to
674 report the problem - see the DisMan Event MIB section
675 later.
676 If this directive is not specified, the default threshold is 16 MB.
677 Log File Monitoring
679 This requires that the agent was built with support for either the ucd-
680 snmp/file or ucd-snmp/logmatch modules respectively (both of which are
681 included as part of the default build configuration).
682 file FILE [MAXSIZE]
684 monitors the size of the specified file (in kB). If MAXSIZE is
685 specified, and the size of the file exceeds this threshold, then
686 the corresponding fileErrorFlag instance will be set to 1, and a
687 suitable description message reported via the fileErrorMsg
688 instance.
689 Note: This situation will not automatically trigger a trap to
691 report the problem - see the DisMan Event MIB section
692 later.
693 Note: A maximum of 20 files can be monitored.
695 Note: If no file directives are defined, then walking the
697 fileTable will fail (noSuchObject).
698 logmatch NAME FILE CYCLETIME REGEX
700 monitors the specified file for occurances of the specified pat‐
701 tern REGEX. The file position is stored internally so the entire
702 file is only read initially, every subsequent pass will only
703 read the new lines added to the file since the last read.
704 NAME name of the logmatch instance (will appear as logMatch‐
706 Name under logMatch/logMatchTable/logMatchEntry/logMatch‐
707 Name in the ucd-snmp MIB tree)
708 FILE absolute path to the logfile to be monitored. Note that
710 this path can contain date/time directives (like in the
711 UNIX 'date' command). See the manual page for 'strftime'
712 for the various directives accepted.
713 CYCLETIME
715 time interval for each logfile read and internal variable
716 update in seconds. Note: an SNMPGET* operation will also
717 trigger an immediate logfile read and variable update.
718 REGEX the regular expression to be used. Note: DO NOT enclose
720 the regular expression in quotes even if there are spaces
721 in the expression as the quotes will also become part of
722 the pattern to be matched!
723 Example:
725 logmatch apache-GETs
727 /usr/local/apache/logs/access.log-%Y-%m-%d 60 GET.*HTTP.*
728 This logmatch instance is named 'apache-GETs', uses
730 'GET.*HTTP.*' as its regular expression and it will moni‐
731 tor the file named (assuming today is May 6th 2009):
732 '/usr/local/apache/logs/access.log-2009-05-06', tomorrow
733 it will look for 'access.log-2009-05-07'. The logfile is
734 read every 60 seconds.
735 Note: A maximum of 250 logmatch directives can be specified.
737 Note: If no logmatch directives are defined, then walking the
739 logMatchTable will fail (noSuchObject).
740
742 The usual behaviour of an SNMP agent is to wait for incoming SNMP
743 requests and respond to them - if no requests are received, an agent
744 will typically not initiate any actions. This section describes various
745 directives that can configure snmpd to take a more active role.
746 Notification Handling
748 trapcommunity STRING
749 defines the default community string to be used when sending
750 traps. Note that this directive must be used prior to any com‐
751 munity-based trap destination directives that need to use it.
752 trapsink HOST [COMMUNITY [PORT]]
754 trap2sink HOST [COMMUNITY [PORT]]
756 informsink HOST [COMMUNITY [PORT]]
758 define the address of a notification receiver that should be
759 sent SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifica‐
760 tions respectively. See the section LISTENING ADDRESSES in the
761 snmpd(8) manual page for more information about the format of
762 listening addresses. If COMMUNITY is not specified, the most
763 recent trapcommunity string will be used.
764 If the transport address does not include an explicit port spec‐
766 ification, then PORT will be used. If this is not specified,
767 the well known SNMP trap port (162) will be used.
768 Note: This mechanism is being deprecated, and the listening
770 port should be specified via the transport specification
771 HOST instead.
772 If several sink directives are specified, multiple copies of
774 each notification (in the appropriate formats) will be gener‐
775 ated.
776 Note: It is not normally appropriate to list two (or all three)
778 sink directives with the same destination.
779 trapsess [SNMPCMD_ARGS] HOST
781 provides a more generic mechanism for defining notification des‐
782 tinations. SNMPCMD_ARGS should be the command-line options
783 required for an equivalent snmptrap (or snmpinform) command to
784 send the desired notification. The option -Ci can be used (with
785 -v2c or -v3) to generate an INFORM notification rather than an
786 unacknowledged TRAP.
787 This is the appropriate directive for defining SNMPv3 trap
789 receivers. See http://www.net-snmp.org/tutorial/tutorial-5/com‐
790 mands/snmptrap-v3.html for more information about SNMPv3 notifi‐
791 cation behaviour.
792 authtrapenable {1|2}
794 determines whether to generate authentication failure traps
795 (enabled(1)) or not (disabled(2) - the default). Ordinarily the
796 corresponding MIB object (snmpEnableAuthenTraps.0) is read-
797 write, but specifying this directive makes this object read-
798 only, and attempts to set the value via SET requests will result
799 in a notWritable error response.
800 v1trapaddress HOST
802 defines the agent address, which is inserted into SNMPv1 TRAPs.
803 Arbitrary local IPv4 address is chosen if this option is
804 ommited. This option is useful mainly when the agent is visible
805 from outside world by specific address only (e.g. because of
806 network address translation or firewall).
807 DisMan Event MIB
809 The previous directives can be used to configure where traps should be
810 sent, but are not concerned with when to send such traps (or what traps
811 should be generated). This is the domain of the Event MIB - developed
812 by the Distributed Management (DisMan) working group of the IETF.
813 This requires that the agent was built with support for the dis‐
815 man/event module (which is now included as part of the default build
816 configuration for the most recent distribution).
817 Note: The behaviour of the latest implementation differs in
819 some minor respects from the previous code - nothing too
820 significant, but existing scripts may possibly need some
821 minor adjustments.
822 iquerySecName NAME
824 agentSecName NAME
826 specifies the default SNMPv3 username, to be used when making
827 internal queries to retrieve any necessary information (either
828 for evaluating the monitored expression, or building a notifica‐
829 tion payload). These internal queries always use SNMPv3, even
830 if normal querying of the agent is done using SNMPv1 or SNMPv2c.
831 Note that this user must also be explicitly created (createUser)
833 and given appropriate access rights (e.g. rouser). This direc‐
834 tive is purely concerned with defining which user should be used
835 - not with actually setting this user up.
836 monitor [OPTIONS] NAME EXPRESSION
838 defines a MIB object to monitor. If the EXPRESSION condition
839 holds (see below), then this will trigger the corresponding
840 event, and either send a notification or apply a SET assignment
841 (or both). Note that the event will only be triggered once,
842 when the expression first matches. This monitor entry will not
843 fire again until the monitored condition first becomes false,
844 and then matches again. NAME is an administrative name for this
845 expression, and is used for indexing the mteTriggerTable (and
846 related tables). Note also that such monitors use an internal
847 SNMPv3 request to retrieve the values being monitored (even if
848 normal agent queries typically use SNMPv1 or SNMPv2c). See the
849 iquerySecName token described above.
850 EXPRESSION
852 There are three types of monitor expression supported by the
853 Event MIB - existence, boolean and threshold tests.
854 OID | ! OID | != OID
856 defines an existence(0) monitor test. A bare OID speci‐
857 fies a present(0) test, which will fire when (an instance
858 of) the monitored OID is created. An expression of the
859 form ! OID specifies an absent(1) test, which will fire
860 when the monitored OID is delected. An expression of the
861 form != OID specifies a changed(2) test, which will fire
862 whenever the monitored value(s) change. Note that there
863 must be whitespace before the OID token.
864 OID OP VALUE
866 defines a boolean(1) monitor test. OP should be one of
867 the defined comparison operators (!=, ==, <, <=, >, >=)
868 and VALUE should be an integer value to compare against.
869 Note that there must be whitespace around the OP token.
870 A comparison such as OID !=0 will not be handled cor‐
871 rectly.
872 OID MIN MAX [DMIN DMAX]
874 defines a threshold(2) monitor test. MIN and MAX are
875 integer values, specifying lower and upper thresholds.
876 If the value of the monitored OID falls below the lower
877 threshold (MIN) or rises above the upper threshold (MAX),
878 then the monitor entry will trigger the corresponding
879 event.
880 Note that the rising threshold event will only be re-
882 armed when the monitored value falls below the lower
883 threshold (MIN). Similarly, the falling threshold event
884 will be re-armed by the upper threshold (MAX).
885 The optional parameters DMIN and DMAX configure a pair of
887 similar threshold tests, but working with the delta dif‐
888 ferences between successive sample values.
889 OPTIONS
891 There are various options to control the behaviour of the moni‐
892 tored expression. These include:
893 -D indicates that the expression should be evaluated using
895 delta differences between sample values (rather than the
896 values themselves).
897 -d OID
899 -di OID
901 specifies a discontinuity marker for validating delta
902 differences. A -di object instance will be used exactly
903 as given. A -d object will have the instance subidenti‐
904 fiers from the corresponding (wildcarded) expression
905 object appended. If the -I flag is specified, then there
906 is no difference between these two options.
907 This option also implies -D.
909 -e EVENT
911 specifies the event to be invoked when this monitor entry
912 is triggered. If this option is not given, the monitor
913 entry will generate one of the standard notifications
914 defined in the DISMAN-EVENT-MIB.
915 -I indicates that the monitored expression should be applied
917 to the specified OID as a single instance. By default,
918 the OID will be treated as a wildcarded object, and the
919 monitor expanded to cover all matching instances.
920 -i OID
922 -o OID define additional varbinds to be added to the notifica‐
924 tion payload when this monitor trigger fires. For a
925 wildcarded expression, the suffix of the matched instance
926 will be added to any OIDs specified using -o, while OIDs
927 specified using -i will be treated as exact instances.
928 If the -I flag is specified, then there is no difference
929 between these two options.
930 See strictDisman for details of the ordering of notifica‐
932 tion payloads.
933 -r FREQUENCY
935 monitors the given expression every FREQUENCY seconds.
936 By default, the expression will be evaluated every 600s
937 (10 minutes).
938 -S indicates that the monitor expression should not be eval‐
940 uated when the agent first starts up. The first evalua‐
941 tion will be done once the first repeat interval has
942 expired.
943 -s indicates that the monitor expression should be evaluated
945 when the agent first starts up. This is the default be‐
946 haviour.
947 Note: Notifications triggered by this initial evaluation
949 will be sent before the coldStart trap.
950 -u SECNAME
952 specifies a security name to use for scanning the local
953 host, instead of the default iquerySecName. Once again,
954 this user must be explicitly created and given suitable
955 access rights.
956 notificationEvent ENAME NOTIFICATION [-m] [-i OID | -o OID ]*
958 defines a notification event named ENAME. This can be triggered
959 from a given monitor entry by specifying the option -e ENAME
960 (see above). NOTIFICATION should be the OID of the NOTIFICA‐
961 TION-TYPE definition for the notification to be generated.
962 If the -m option is given, the notification payload will include
964 the standard varbinds as specified in the OBJECTS clause of the
965 notification MIB definition. This option must come after the
966 NOTIFICATION OID (and the relevant MIB file must be available
967 and loaded by the agent). Otherwise, these varbinds must be
968 listed explicitly (either here or in the corresponding monitor
969 directive).
970 The -i OID and -o OID options specify additional varbinds to be
972 appended to the notification payload, after the standard list.
973 If the monitor entry that triggered this event involved a wild‐
974 carded expression, the suffix of the matched instance will be
975 added to any OIDs specified using -o, while OIDs specified using
976 -i will be treated as exact instances. If the -I flag was spec‐
977 ified to the monitor directive, then there is no difference
978 between these two options.
979 setEvent ENAME [-I] OID = VALUE
981 defines a set event named ENAME, assigning the (integer) VALUE
982 to the specified OID. This can be triggered from a given moni‐
983 tor entry by specifying the option -e ENAME (see above).
984 If the monitor entry that triggered this event involved a wild‐
986 carded expression, the suffix of the matched instance will nor‐
987 mally be added to the OID. If the -I flag was specified to
988 either of the monitor or setEvent directives, the specified OID
989 will be regarded as an exact single instance.
990 strictDisman yes
992 The definition of SNMP notifications states that the varbinds
993 defined in the OBJECT clause should come first (in the order
994 specified), followed by any "extra" varbinds that the notifica‐
995 tion generator feels might be useful. The most natural approach
996 would be to associate these mandatory varbinds with the notifi‐
997 cationEvent entry, and append any varbinds associated with the
998 monitor entry that triggered the notification to the end of this
999 list. This is the default behaviour of the Net-SNMP Event MIB
1000 implementation.
1001 Unfortunately, the DisMan Event MIB specifications actually
1003 state that the trigger-related varbinds should come first, fol‐
1004 lowed by the event-related ones. This directive can be used to
1005 restore this strictly-correct (but inappropriate) behaviour.
1006 Note: Strict DisMan ordering may result in generating invalid
1008 notifications payload lists if the notificationEvent -n
1009 flag is used together with monitor -o (or -i) varbind
1010 options.
1011 If no monitor entries specify payload varbinds, then the setting
1013 of this directive is irrelevant.
1014 linkUpDownNotifications yes
1016 will configure the Event MIB tables to monitor the ifTable for
1017 network interfaces being taken up or down, and triggering a
1018 linkUp or linkDown notification as appropriate.
1019 This is exactly equivalent to the configuration:
1021 notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
1023 notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
1024 monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
1026 monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
1027 defaultMonitors yes
1029 will configure the Event MIB tables to monitor the various UCD-
1030 SNMP-MIB tables for problems (as indicated by the appropriate
1031 xxErrFlag column objects).
1032 This is exactly equivalent to the configuration:
1034 monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
1036 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
1037 monitor -o extNames -o extOutput "extTable" extResult != 0
1038 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
1039 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
1040 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
1041 In both these latter cases, the snmpd.conf must also contain a iquery‐
1043 SecName directive, together with a corresponding createUser entry and
1044 suitable access control configuration.
1045 DisMan Schedule MIB
1047 The DisMan working group also produced a mechanism for scheduling par‐
1048 ticular actions (a specified SET assignment) at given times. This
1049 requires that the agent was built with support for the disman/schedule
1050 module (which is included as part of the default build configuration
1051 for the most recent distribution).
1052 There are three ways of specifying the scheduled action:
1054 repeat FREQUENCY OID = VALUE
1056 configures a SET assignment of the (integer) VALUE to the MIB
1057 instance OID, to be run every FREQUENCY seconds.
1058 cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1060 configures a SET assignment of the (integer) VALUE to the MIB
1061 instance OID, to be run at the times specified by the fields
1062 MINUTE to WEEKDAY. These follow the same pattern as the equiva‐
1063 lent crontab(5) fields.
1064 Note: These fields should be specified as a (comma-separated)
1066 list of numeric values. Named values for the MONTH and
1067 WEEKDAY fields are not supported, and neither are value
1068 ranges. A wildcard match can be specified as '*'.
1069 The DAY field can also accept negative values, to indicate days
1071 counting backwards from the end of the month.
1072 at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1074 configures a one-shot SET assignment, to be run at the first
1075 matching time as specified by the fields MINUTE to WEEKDAY. The
1076 interpretation of these fields is exactly the same as for the
1077 cron directive.
1078
1080 One of the first distinguishing features of the original UCD suite was
1081 the ability to extend the functionality of the agent - not just by
1082 recompiling with code for new MIB modules, but also by configuring the
1083 running agent to report additional information. There are a number of
1084 techniques to support this, including:
1085 · running external commands (exec, extend, pass)
1087 · loading new code dynamically (embedded perl, dlmod)
1089 · communicating with other agents (proxy, SMUX, AgentX)
1091 Arbitrary Extension Commands
1093 The earliest extension mechanism was the ability to run arbitrary com‐
1094 mands or shell scripts. Such commands do not need to be aware of SNMP
1095 operations, or conform to any particular behaviour - the MIB structures
1096 are designed to accommodate any form of command output. Use of this
1097 mechanism requires that the agent was built with support for the ucd-
1098 snmp/extensible and/or agent/extend modules (which are both included as
1099 part of the default build configuration).
1100 exec [MIBOID] NAME PROG ARGS
1102 sh [MIBOID] NAME PROG ARGS
1104 invoke the named PROG with arguments of ARGS. By default the
1105 exit status and first line of output from the command will be
1106 reported via the extTable, discarding any additional output.
1107 Note: Entries in this table appear in the order they are read
1109 from the configuration file. This means that adding new
1110 exec (or sh) directives and restarting the agent, may
1111 affect the indexing of other entries.
1112 The PROG argument for exec directives must be a full path to a
1114 real binary, as it is executed via the exec() system call. To
1115 invoke a shell script, use the sh directive instead.
1116 If MIBOID is specified, then the results will be rooted at this
1118 point in the OID tree, returning the exit statement as
1119 MIBOID.100.0 and the entire command output in a pseudo-table
1120 based at MIBNUM.101 - with one 'row' for each line of output.
1121 Note: The layout of this "relocatable" form of exec (or sh)
1123 output does not strictly form a valid MIB structure.
1124 This mechanism is being deprecated - please see the
1125 extend directive (described below) instead.
1126 The agent does not cache the exit status or output of the exe‐
1128 cuted program.
1129 execfix NAME PROG ARGS
1131 registers a command that can be invoked on demand - typically to
1132 respond to or fix errors with the corresponding exec or sh
1133 entry. When the extErrFix instance for a given NAMEd entry is
1134 set to the integer value of 1, this command will be called.
1135 Note: This directive can only be used in combination with a
1137 corresponding exec or sh directive, which must be defined
1138 first. Attempting to define an unaccompanied execfix
1139 directive will fail.
1140 exec and sh extensions can only be configured via the snmpd.conf file.
1142 They cannot be set up via SNMP SET requests.
1143 extend [MIBOID] NAME PROG ARGS
1145 works in a similar manner to the exec directive, but with a num‐
1146 ber of improvements. The MIB tables (nsExtendConfigTable etc)
1147 are indexed by the NAME token, so are unaffected by the order in
1148 which entries are read from the configuration files. There are
1149 two result tables - one (nsExtendOutput1Table) containing the
1150 exit status, the first line and full output (as a single string)
1151 for each extend entry, and the other (nsExtendOutput2Table) con‐
1152 taining the complete output as a series of separate lines.
1153 If MIBOID is specified, then the configuration and result tables
1155 will be rooted at this point in the OID tree, but are otherwise
1156 structured in exactly the same way. This means that several sep‐
1157 arate extend directives can specify the same MIBOID root, with‐
1158 out conflicting.
1159 The exit status and output is cached for each entry individu‐
1161 ally, and can be cleared (and the caching behaviour configured)
1162 using the nsCacheTable.
1163 extendfix NAME PROG ARGS
1165 registers a command that can be invoked on demand, by setting
1166 the appropriate nsExtendRunType instance to the value run-com‐
1167 mand(3). Unlike the equivalent execfix, this directive does not
1168 need to be paired with a corresponding extend entry, and can
1169 appear on its own.
1170 Both extend and extendfix directives can be configured dynamically,
1172 using SNMP SET requests to the NET-SNMP-EXTEND-MIB.
1173 MIB-Specific Extension Commands
1175 The first group of extension directives invoke arbitrary commands, and
1176 rely on the MIB structure (and management applications) having the
1177 flexibility to accommodate and interpret the output. This is a conve‐
1178 nient way to make information available quickly and simply, but is of
1179 no use when implementing specific MIB objects, where the extension must
1180 conform to the structure of the MIB (rather than vice versa). The
1181 remaining extension mechanisms are all concerned with such MIB-specific
1182 situations - starting with "pass-through" scripts. Use of this mecha‐
1183 nism requires that the agent was built with support for the ucd-
1184 snmp/pass and ucd-snmp/pass_persist modules (which are both included as
1185 part of the default build configuration).
1186 pass [-p priority] MIBOID PROG
1188 will pass control of the subtree rooted at MIBOID to the speci‐
1189 fied PROG command. GET and GETNEXT requests for OIDs within
1190 this tree will trigger this command, called as:
1191 PROG -g OID
1193 PROG -n OID
1195 respectively, where OID is the requested OID. The PROG command
1197 should return the response varbind as three separate lines
1198 printed to stdout - the first line should be the OID of the
1199 returned value, the second should be its TYPE (one of the text
1200 strings integer, gauge, counter, timeticks, ipaddress, objectid,
1201 or string ), and the third should be the value itself.
1202 If the command cannot return an appropriate varbind - e.g the
1204 specified OID did not correspond to a valid instance for a GET
1205 request, or there were no following instances for a GETNEXT -
1206 then it should exit without producing any output. This will
1207 result in an SNMP noSuchName error, or a noSuchInstance excep‐
1208 tion.
1209 Note: The SMIv2 type counter64 and SNMPv2 noSuchObject
1211 exception are not supported.
1212 A SET request will result in the command being called as:
1214 PROG -s OID TYPE VALUE
1216 where TYPE is one of the tokens listed above, indicating the
1218 type of the value passed as the third parameter.
1219 If the assignment is successful, the PROG command should exit
1221 without producing any output. Errors should be indicated by
1222 writing one of the strings not-writable, or wrong-type to std‐
1223 out, and the agent will generate the appropriate error response.
1224 Note: The other SNMPv2 errors are not supported.
1226 In either case, the command should exit once it has finished
1228 processing. Each request (and each varbind within a single
1229 request) will trigger a separate invocation of the command.
1230 The default registration priority is 127. This can be changed
1232 by supplying the optional -p flag, with lower priority registra‐
1233 tions being used in preference to higher priority values.
1234 pass_persist [-p priority] MIBOID PROG
1236 will also pass control of the subtree rooted at MIBOID to the
1237 specified PROG command. However this command will continue to
1238 run after the initial request has been answered, so subsequent
1239 requests can be processed without the startup overheads.
1240 Upon initialization, PROG will be passed the string "PING\n" on
1242 stdin, and should respond by printing "PONG\n" to stdout.
1243 For GET and GETNEXT requests, PROG will be passed two lines on
1245 stdin, the command (get or getnext) and the requested OID. It
1246 should respond by printing three lines to stdout - the OID for
1247 the result varbind, the TYPE and the VALUE itself - exactly as
1248 for the pass directive above. If the command cannot return an
1249 appropriate varbind, it should print print "NONE\n" to stdout
1250 (but continue running).
1251 For SET requests, PROG will be passed three lines on stdin, the
1253 command (set) and the requested OID, followed by the type and
1254 value (both on the same line). If the assignment is successful,
1255 the command should print "DONE\n" to stdout. Errors should be
1256 indicated by writing one of the strings not-writable, wrong-
1257 type, wrong-length, wrong-value or inconsistent-value to stdout,
1258 and the agent will generate the appropriate error response. In
1259 either case, the command should continue running.
1260 The registration priority can be changed using the optional -p
1262 flag, just as for the pass directive.
1263 pass and pass_persist extensions can only be configured via the
1265 snmpd.conf file. They cannot be set up via SNMP SET requests.
1266 Embedded Perl Support
1268 Programs using the previous extension mechanisms can be written in any
1269 convenient programming language - including perl, which is a common
1270 choice for pass-through extensions in particular. However the Net-SNMP
1271 agent also includes support for embedded perl technology (similar to
1272 mod_perl for the Apache web server). This allows the agent to inter‐
1273 pret perl scripts directly, thus avoiding the overhead of spawning pro‐
1274 cesses and initializing the perl system when a request is received.
1275 Use of this mechanism requires that the agent was built with support
1277 for the embedded perl mechanism, which is not part of the default build
1278 environment. It must be explicitly included by specifying the
1279 '--enable-embedded-perl' option to the configure script when the pack‐
1280 age is first built.
1281 If enabled, the following directives will be recognised:
1283 disablePerl true
1285 will turn off embedded perl support entirely (e.g. if there are
1286 problems with the perl installation).
1287 perlInitFile FILE
1289 loads the specified initialisation file (if present) immediately
1290 before the first perl directive is parsed. If not explicitly
1291 specified, the agent will look for the default initialisation
1292 file /usr/share/snmp/snmp_perl.pl.
1293 The default initialisation file creates an instance of a Net‐
1295 SNMP::agent object - a variable $agent which can be used to reg‐
1296 ister perl-based MIB handler routines.
1297 perl EXPRESSION
1299 evaluates the given expression. This would typically register a
1300 handler routine to be called when a section of the OID tree was
1301 requested:
1302 perl use Data::Dumper;
1303 perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
1304 perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
1305 This expression could also source an external file:
1307 perl 'do /path/to/file.pl';
1308 or perform any other perl-based processing that might be
1310 required.
1311 Dynamically Loadable Modules
1313 Most of the MIBs supported by the Net-SNMP agent are implemented as C
1314 code modules, which were compiled and linked into the agent libraries
1315 when the suite was first built. Such implementation modules can also
1316 be compiled independently and loaded into the running agent once it has
1317 started. Use of this mechanism requires that the agent was built with
1318 support for the ucd-snmp/dlmod module (which is included as part of the
1319 default build configuration).
1320 dlmod NAME PATH
1322 will load the shared object module from the file PATH (an abso‐
1323 lute filename), and call the initialisation routine init_NAME.
1324 Note: If the specified PATH is not a fully qualified filename,
1326 it will be interpreted relative to
1327 /usr/lib(64)/snmp/dlmod, and .so will be appended to the
1328 filename.
1329 This functionality can also be configured using SNMP SET requests to
1331 the UCD-DLMOD-MIB.
1332 Proxy Support
1334 Another mechanism for extending the functionality of the agent is to
1335 pass selected requests (or selected varbinds) to another SNMP agent,
1336 which can be running on the same host (presumably listening on a dif‐
1337 ferent port), or on a remote system. This can be viewed either as the
1338 main agent delegating requests to the remote one, or acting as a proxy
1339 for it. Use of this mechanism requires that the agent was built with
1340 support for the ucd-snmp/proxy module (which is included as part of the
1341 default build configuration).
1342 proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
1344 will pass any incoming requests under OID to the agent listening
1345 on the port specified by the transport address HOST. See the
1346 section LISTENING ADDRESSES in the snmpd(8) manual page for more
1347 information about the format of listening addresses.
1348 Note: To proxy the entire MIB tree, use the OID .1.3 (not the
1350 top-level .1)
1351 The SNMPCMD_ARGS should provide sufficient version and administrative
1353 information to generate a valid SNMP request (see snmpcmd(1)).
1354 Note: The proxied request will not use the administrative settings
1356 from the original request.
1357 If a CONTEXTNAME is specified, this will register the proxy delegation
1359 within the named context in the local agent. Defining multiple proxy
1360 directives for the same OID but different contexts can be used to query
1361 several remote agents through a single proxy, by specifying the appro‐
1362 priate SNMPv3 context in the incoming request (or using suitable con‐
1363 figured community strings - see the com2sec directive).
1364 Specifying the REMOID parameter will map the local MIB tree rooted at
1366 OID to an equivalent subtree rooted at REMOID on the remote agent.
1367 SMUX Sub-Agents
1369 The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1370 with SMUX-based subagents (such as gated, zebra or quagga). Use of
1371 this mechanism requires that the agent was built with support for the
1372 smux module, which is not part of the default build environment, and
1373 must be explicitly included by specifying the '--with-mib-modules=smux'
1374 option to the configure script when the package is first built.
1375 Note: This extension protocol has been officially deprecated in
1377 favour of AgentX (see below).
1378 smuxpeer OID PASS
1380 will register a subtree for SMUX-based processing, to be authen‐
1381 ticated using the password PASS. If a subagent (or "peer") con‐
1382 nects to the agent and registers this subtree then requests for
1383 OIDs within it will be passed to that SMUX subagent for process‐
1384 ing.
1385 A suitable entry for an OSPF routing daemon (such as gated,
1387 zebra or quagga) might be something like
1388 smuxpeer .1.3.6.1.2.1.14 ospf_pass
1389 smuxsocket <IPv4-address>
1391 defines the IPv4 address for SMUX peers to communicate with the
1392 Net-SNMP agent. The default is to listen on all IPv4 interfaces
1393 ("0.0.0.0"), unless the package has been configured with
1394 "--enable-local-smux" at build time, which causes it to only
1395 listen on 127.0.0.1 by default. SMUX uses the well-known TCP
1396 port 199.
1397 Note the Net-SNMP agent will only operate as a SMUX master agent. It
1399 does not support acting in a SMUX subagent role.
1400 AgentX Sub-Agents
1402 The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both mas‐
1403 ter and subagent roles. Use of this mechanism requires that the agent
1404 was built with support for the agentx module (which is included as part
1405 of the default build configuration), and also that this support is
1406 explicitly enabled (e.g. via the snmpd.conf file).
1407 There are two directives specifically relevant to running as an AgentX
1409 master agent:
1410 master agentx
1412 will enable the AgentX functionality and cause the agent to
1413 start listening for incoming AgentX registrations. This can
1414 also be activated by specifying the '-x' command-line option (to
1415 specify an alternative listening socket).
1416 agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
1418 Defines the permissions and ownership of the AgentX Unix Domain
1419 socket, and the parent directories of this socket. SOCKPERMS
1420 and DIRPERMS must be octal digits (see chmod(1) ). By default
1421 this socket will only be accessible to subagents which have the
1422 same userid as the agent.
1423 There is one directive specifically relevant to running as an AgentX
1425 sub-agent:
1426 agentXPingInterval NUM
1428 will make the subagent try and reconnect every NUM seconds to
1429 the master if it ever becomes (or starts) disconnected.
1430 The remaining directives are relevant to both AgentX master and sub-
1432 agents:
1433 agentXSocket [<transport-specifier>:]<transport-address>[,...]
1435 defines the address the master agent listens at, or the subagent
1436 should connect to. The default is the Unix Domain socket
1437 "/var/agentx/master". Another common alternative is tcp:local‐
1438 host:705. See the section LISTENING ADDRESSES in the snmpd(8)
1439 manual page for more information about the format of addresses.
1440 Note: Specifying an AgentX socket does not automatically enable
1442 AgentX functionality (unlike the '-x' command-line
1443 option).
1444 agentXTimeout NUM
1446 defines the timeout period (NUM seconds) for an AgentX request.
1447 Default is 1 second.
1448 agentXRetries NUM
1450 defines the number of retries for an AgentX request. Default is
1451 5 retries.
1452 net-snmp ships with both C and Perl APIs to develop your own AgentX
1454 subagent.
1455
1457 override [-rw] OID TYPE VALUE
1458 This directive allows you to override a particular OID with a
1459 different value (and possibly a different type of value). The
1460 -rw flag will allow snmp SETs to modify it's value as well.
1461 (note that if you're overriding original functionality, that
1462 functionality will be entirely lost. Thus SETS will do nothing
1463 more than modify the internal overridden value and will not per‐
1464 form any of the original functionality intended to be provided
1465 by the MIB object. It's an emulation only.) An example:
1466 override sysDescr.0 octet_str "my own sysDescr"
1468 That line will set the sysDescr.0 value to "my own sysDescr" as
1470 well as make it modifiable with SNMP SETs as well (which is
1471 actually illegal according to the MIB specifications).
1472 Note that care must be taken when using this. For example, if
1474 you try to override a property of the 3rd interface in the
1475 ifTable with a new value and later the numbering within the
1476 ifTable changes it's index ordering you'll end up with problems
1477 and your modified value won't appear in the right place in the
1478 table.
1479 Valid TYPEs are: integer, uinteger, octet_str, object_id,
1481 counter, null (for gauges, use "uinteger"; for bit strings, use
1482 "octet_str"). Note that setting an object to "null" effectively
1483 delete's it as being accessible. No VALUE needs to be given if
1484 the object type is null.
1485 More types should be available in the future.
1487 If you're trying to figure out aspects of the various mib modules (pos‐
1489 sibly some that you've added yourself), the following may help you spit
1490 out some useful debugging information. First off, please read the
1491 snmpd manual page on the -D flag. Then the following configuration
1492 snmpd.conf token, combined with the -D flag, can produce useful output:
1493 injectHandler HANDLER modulename
1495 This will insert new handlers into the section of the mib tree
1496 referenced by "modulename". The types of handlers available for
1497 insertion are:
1498 stash_cache
1500 Caches information returned from the lower level. This
1501 greatly help the performance of the agent, at the cost of
1502 caching the data such that its no longer "live" for 30
1503 seconds (in this future, this will be configurable).
1504 Note that this means snmpd will use more memory as well
1505 while the information is cached. Currently this only
1506 works for handlers registered using the table_iterator
1507 support, which is only a few mib tables. To use it, you
1508 need to make sure to install it before the table_iterator
1509 point in the chain, so to do this:
1510 injectHandler stash_cache NAME ta‐
1512 ble_iterator
1513 If you want a table to play with, try walking the nsMod‐
1515 uleTable with and without this injected.
1516 debug Prints out lots of debugging information when the
1519 -Dhelper:debug flag is passed to the snmpd application.
1520 read_only
1523 Forces turning off write support for the given module.
1524 serialize
1527 If a module is failing to handle multiple requests prop‐
1528 erly (using the new 5.0 module API), this will force the
1529 module to only receive one request at a time.
1530 bulk_to_next
1533 If a module registers to handle getbulk support, but for
1534 some reason is failing to implement it properly, this
1535 module will convert all getbulk requests to getnext
1536 requests before the final module receives it.
1537 dontLogTCPWrappersConnects
1539 If the snmpd was compiled with TCP Wrapper support, it logs
1540 every connection made to the agent. This setting disables the
1541 log messages for accepted connections. Denied connections will
1542 still be logged.
1543 Figuring out module names
1545 To figure out which modules you can inject things into, run snm‐
1546 pwalk on the nsModuleTable which will give a list of all named
1547 modules registered within the agent.
1548 Internal Data tables
1550 table NAME
1551 add_row NAME INDEX(ES) VALUE(S)
1553
1555 o The Net-SNMP agent can be instructed to re-read the various con‐
1556 figuration files, either via an snmpset assignment of integer(1)
1557 to UCD-SNMP-MIB::versionUpdateConfig.0
1558 (.1.3.6.1.4.1.2021.100.11.0), or by sending a kill -HUP signal
1559 to the agent process.
1560 o All directives listed with a value of "yes" actually accept a
1562 range of boolean values. These will accept any of 1, yes or
1563 true to enable the corresponding behaviour, or any of 0, no or
1564 false to disable it. The default in each case is for the fea‐
1565 ture to be turned off, so these directives are typically only
1566 used to enable the appropriate behaviour.
1567
1569 See the EXAMPLE.CONF file in the top level source directory for a more
1570 detailed example of how the above information is used in real examples.
1571
1573 /etc/snmp/snmpd.conf
1574
1576 snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM‐
1577 PLE.conf, read_config(3).
15784th Berkeley Distribution 08 Feb 2002 SNMPD.CONF(5)