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 uptime 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 snmpd supports the View-Based Access Control Model (VACM) as defined in
119 RFC 2575, to control who can retrieve or update information. To this
120 end, it recognizes various directives relating to access control.
121 These fall into four basic groups.
122 SNMPv3 Users
124 createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES]
125 [privpassphrase]
126 MD5 and SHA are the authentication types to use. DES and AES
128 are the privacy protocols to use. If the privacy passphrase is
129 not specified, it is assumed to be the same as the authentica‐
130 tion passphrase. Note that the users created will be useless
131 unless they are also added to the VACM access control tables
132 described above.
133 SHA authentication and DES/AES privacy require OpenSSL to be
135 installed and the agent to be built with OpenSSL support. MD5
136 authentication may be used without OpenSSL.
137 Warning: the minimum pass phrase length is 8 characters.
139 SNMPv3 users can be created at runtime using the snmpusm(1) com‐
141 mand.
142 Instead of figuring out how to use this directive and where to
144 put it (see below), just run "net-snmp-config --create-
145 snmpv3-user" instead, which will add one of these lines to the
146 right place.
147 This directive should be placed into the /var/net-
149 snmp/snmpd.conf file instead of the other normal locations. The
150 reason is that the information is read from the file and then
151 the line is removed (eliminating the storage of the master pass‐
152 word for that user) and replaced with the key that is derived
153 from it. This key is a localized key, so that if it is stolen
154 it can not be used to access other agents. If the password is
155 stolen, however, it can be.
156 If you need to localize the user to a particular EngineID (this
158 is useful mostly in the similar snmptrapd.conf file), you can
159 use the -e argument to specify an EngineID as a hex value (EG,
160 "0x01020304").
161 If you want to generate either your master or localized keys
163 directly, replace the given password with a hexstring (preceeded
164 by a "0x") and precede the hex string by a -m or -l token
165 (respectively). EGs:
166 [these keys are *not* secure but are easy to visually parse for
168 counting purposes. Please generate random keys instead of using
169 these examples]
170 createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
172 createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
173 Due to the way localization happens, localized privacy keys are
175 expected to be the length needed by the algorithm (128 bits for
176 all supported algorithms). Master encryption keys, though, need
177 to be the length required by the authentication algorithm not
178 the length required by the encrypting algorithm (MD5: 16 bytes,
179 SHA: 20 bytes).
180 Traditional Access Control
182 Most simple access control requirements can be specified using the
183 directives rouser/rwuser (for SNMPv3) or rocommunity/rwcommunity (for
184 SNMPv1 or SNMPv2c).
185 rouser USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
187 rwuser USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]
189 specify an SNMPv3 user that will be allowed read-only (GET and
190 GETNEXT) or read-write (GET, GETNEXT and SET) access respec‐
191 tively. By default, this will provide access to the full OID
192 tree for authenticated (including encrypted) SNMPv3 requests,
193 using the default context. An alternative minimum security
194 level can be specified using noauth (to allow unauthenticated
195 requests), or priv (to enforce use of encryption). The OID
196 field restricts access for that user to the subtree rooted at
197 the given OID, or the named view. An optional context can also
198 be specified, or "context*" to denote a context prefix. If no
199 context field is specified (or the token "*" is used), the
200 directive will match all possible contexts.
201 rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
203 rwcommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
205 specify an SNMPv1 or SNMPv2c community that will be allowed
206 read-only (GET and GETNEXT) or read-write (GET, GETNEXT and SET)
207 access respectively. By default, this will provide access to
208 the full OID tree for such requests, regardless of where they
209 were sent from. The SOURCE token can be used to restrict access
210 to requests from the specified system(s) - see com2sec for the
211 full details. The OID field restricts access for that community
212 to the subtree rooted at the given OID, or named view. Contexts
213 are typically less relevant to community-based SNMP versions,
214 but the same behaviour applies here.
215 rocommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
217 rwcommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
219 are directives relating to requests received using IPv6 (if the
220 agent supports such transport domains). The interpretation of
221 the SOURCE, OID, VIEW and CONTEXT tokens are exactly the same as
222 for the IPv4 versions.
223 In each case, only one directive should be specified for a given SNMPv3
225 user, or community string. It is not appropriate to specify both
226 rouser and rwuser directives referring to the same SNMPv3 user (or
227 equivalent community settings). The rwuser directive provides all the
228 access of rouser (as well as allowing SET support). The same holds
229 true for the community-based directives.
230 More complex access requirements (such as access to two or more dis‐
232 tinct OID subtrees, or different views for GET and SET requests) should
233 use one of the other access control mechanisms. Note that if several
234 distinct communities or SNMPv3 users need to be granted the same level
235 of access, it would also be more efficient to use the main VACM config‐
236 uration directives.
237 VACM Configuration
239 The full flexibility of the VACM is available using four configuration
240 directives - com2sec, group, view and access. These provide direct
241 configuration of the underlying VACM tables.
242 com2sec [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
244 com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
246 map an SNMPv1 or SNMPv2c community string to a security name -
247 either from a particular range of source addresses, or globally
248 ("default"). A restricted source can either be a specific host‐
249 name (or address), or a subnet - represented as IP/MASK (e.g.
250 10.10.10.0/255.255.255.0), or IP/BITS (e.g. 10.10.10.0/24), or
251 the IPv6 equivalents.
252 The same community string can be specified in several separate
254 directives (presumably with different source tokens), and the
255 first source/community combination that matches the incoming
256 request will be selected. Various source/community combinations
257 can also map to the same security name.
258 If a CONTEXT is specified (using -Cn), the community string will
260 be mapped to a security name in the named SNMPv3 context. Other‐
261 wise the default context ("") will be used.
262 com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY
264 is the Unix domain sockets version of com2sec.
265 group GROUP {v1|v2c|usm} SECNAME
267 maps a security name (in the specified security model) into a
268 named group. Several group directives can specify the same
269 group name, allowing a single access setting to apply to several
270 users and/or community strings.
271 Note that groups must be set up for the two community-based mod‐
273 els separately - a single com2sec (or equivalent) directive will
274 typically be accompanied by two group directives.
275 view VNAME TYPE OID [MASK]
277 defines a named "view" - a subset of the overall OID tree. This
278 is most commonly a single subtree, but several view directives
279 can be given with the same view name (VNAME), to build up a more
280 complex collection of OIDs. TYPE is either included or
281 excluded, which can again define a more complex view (e.g by
282 excluding certain sensitive objects from an otherwise accessible
283 subtree).
284 MASK is a list of hex octets (optionally separated by '.' or
286 ':') with the set bits indicating which subidentifiers in the
287 view OID to match against. If not specified, this defaults to
288 matching the OID exactly (all bits set), thus defining a simple
289 OID subtree. So:
290 view iso1 included .iso 0xf0
291 view iso2 included .iso
292 view iso3 included .iso.org.dod.mgmt 0xf0
293 would all define the same view, covering the whole of the
295 'iso(1)' subtree (with the third example ignoring the subidenti‐
296 fiers not covered by the mask).
297 More usefully, the mask can be used to define a view covering a
299 particular row (or rows) in a table, by matching against the
300 appropriate table index value, but skipping the column subiden‐
301 tifier:
302 view ifRow4 included .1.3.6.1.2.1.2.2.1.0.4 0xff:a0
304 Note that a mask longer than 8 bits must use ':' to separate the
306 individual octets.
307 access GROUP CONTEXT {any|v1|v2c|usm} LEVEL PREFX READ WRITE NOTIFY
309 maps from a group of users/communities (with a particular secu‐
310 rity model and minimum security level, and in a specific con‐
311 text) to one of three views, depending on the request being pro‐
312 cessed.
313 LEVEL is one of noauth, auth, or priv. PREFX specifies how CON‐
315 TEXT should be matched against the context of the incoming
316 request, either exact or prefix. READ, WRITE and NOTIFY speci‐
317 fies the view to be used for GET*, SET and TRAP/INFORM requests
318 (althought the NOTIFY view is not currently used). For v1 or
319 v2c access, LEVEL will need to be noauth.
320 Typed-View Configuration
322 The final group of directives extend the VACM approach into a more
323 flexible mechanism, which can be applied to other access control
324 requirements. Rather than the fixed three views of the standard VACM
325 mechanism, this can be used to configure various different view types.
326 As far as the main SNMP agent is concerned, the two main view types are
327 read and write, corresponding to the READ and WRITE views of the main
328 access directive. See the 'snmptrapd.conf(5)' man page for discussion
329 of other view types.
330 authcommunity TYPES COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]
332 is an alternative to the rocommunity/rwcommunity directives.
333 TYPES will usually be read or read,write respectively. The view
334 specification can either be an OID subtree (as before), or a
335 named view (defined using the view directive) for greater flexi‐
336 bility. If this is omitted, then access will be allowed to the
337 full OID tree. If CONTEXT is specified, access is configured
338 within this SNMPv3 context. Otherwise the default context ("")
339 is used.
340 authuser TYPES [-s MODEL] USER [LEVEL [OID | -V VIEW [CONTEXT]]]
342 is an alternative to the rouser/rwuser directives. The fields
343 TYPES, OID, VIEW and CONTEXT have the same meaning as for auth‐
344 community.
345 authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW [CONTEXT]]]
347 is a companion to the authuser directive, specifying access for
348 a particular group (defined using the group directive as usual).
349 Both authuser and authgroup default to authenticated requests -
350 LEVEL can also be specified as noauth or priv to allow unauthen‐
351 ticated requests, or require encryption respectively. Both
352 authuser and authgroup directives also default to configuring
353 access for SNMPv3/USM requests - use the '-s' flag to specify an
354 alternative security model (using the same values as for access
355 above).
356 authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
358 also configures the access for a particular group, specifying
359 the name and type of view to apply. The MODEL and LEVEL fields
360 are interpreted in the same way as for authgroup. If CONTEXT is
361 specified, access is configured within this SNMPv3 context (or
362 contexts with this prefix if the CONTEXT field ends with '*').
363 Otherwise the default context ("") is used.
364 setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
366 is a direct equivalent to the original access directive, typi‐
367 cally listing the view types as read or read,write as appropri‐
368 ate. (or see 'snmptrapd.conf(5)' for other possibilities). All
369 other fields have the same interpretation as with access.
370
372 Most of the information reported by the Net-SNMP agent is retrieved
373 from the underlying system, or dynamically configured via SNMP SET
374 requests (and retained from one run of the agent to the next). How‐
375 ever, certain MIB objects can be configured or controlled via the
376 snmpd.conf(5) file.
377 System Group
379 Most of the scalar objects in the 'system' group can be configured in
380 this way:
381 sysLocation STRING
383 sysContact STRING
385 sysName STRING
387 set the system location, system contact or system name (sysLoca‐
388 tion.0, sysContact.0 and sysName.0) for the agent respectively.
389 Ordinarily these objects are writeable via suitably authorized
390 SNMP SET requests. However, specifying one of these directives
391 makes the corresponding object read-only, and attempts to SET it
392 will result in a notWritable error response.
393 sysServices NUMBER
395 sets the value of the sysServices.0 object. For a host system,
396 a good value is 72 (application + end-to-end layers). If this
397 directive is not specified, then no value will be reported for
398 the sysServices.0 object.
399 sysDescr STRING
401 sysObjectID OID
403 sets the system description or object ID for the agent.
404 Although these MIB objects are not SNMP-writable, these direc‐
405 tives can be used by a network administrator to configure suit‐
406 able values for them.
407 Interfaces Group
409 interface NAME TYPE SPEED
410 can be used to provide appropriate type and speed settings for
411 interfaces where the agent fails to determine this information
412 correctly. TYPE is a type value as given in the IANAifType-MIB,
413 and can be specified numerically or by name (assuming this MIB
414 is loaded).
415 Host Resources Group
417 This requires that the agent was built with support for the host module
418 (which is now included as part of the default build configuration on
419 the major supported platforms).
420 ignoreDisk STRING
422 controls which disk devices are scanned as part of populating
423 the hrDiskStorageTable (and hrDeviceTable). The HostRes imple‐
424 mentation code includes a list of disk device patterns appropri‐
425 ate for the current operating system, some of which may cause
426 the agent to block when trying to open the corresponding disk
427 devices. This might lead to a timeout when walking these
428 tables, possibly resulting in inconsistent behaviour. This
429 directive can be used to specify particular devices (either
430 individually or wildcarded) that should not be checked.
431 Note: Please consult the source (host/hr_disk.c) and check for
433 the Add_HR_Disk_entry calls relevant for a particular O/S
434 to determine the list of devices that will be scanned.
435 The pattern can include one or more wildcard expressions. See
437 snmpd.examples(5) for illustration of the wildcard syntax.
438 skipNFSInHostResources true
440 controls whether NFS and NFS-like file systems should be omitted
441 from the hrStorageTable (true or 1) or not (false or 0, which is
442 the default). If the Net-SNMP agent gets hung on NFS-mounted
443 filesystems, you can try setting this to '1'.
444 storageUseNFS [1|2]
446 controls how NFS and NFS-like file systems should be reported in
447 the hrStorageTable. as 'Network Disks' (1) or 'Fixed Disks' (2)
448 Historically, the Net-SNMP agent has reported such file systems
449 as 'Fixed Disks', and this is still the default behaviour. Set‐
450 ting this directive to '1' reports such file systems as
451 Process Monitoring
453 The hrSWRun group of the Host Resources MIB provides information about
454 individual processes running on the local system. The prTable of the
455 UCD-SNMP-MIB complements this by reporting on selected services (which
456 may involve multiple processes). This requires that the agent was
457 built with support for the ucd-snmp/proc module (which is included as
458 part of the default build configuration).
459 proc NAME [MAX [MIN]]
461 monitors the number of processes called NAME (as reported by
462 "/bin/ps -e") running on the local system.
463 If the number of NAMEd processes is less than MIN or greater
465 than MAX, then the corresponding prErrorFlag instance will be
466 set to 1, and a suitable description message reported via the
467 prErrMessage instance.
468 Note: This situation will not automatically trigger a trap to
470 report the problem - see the DisMan Event MIB section
471 later.
472 If neither MAX nor MIN are specified (or are both 0), they will
474 default to infinity and 1 respectively ("at least one"). If
475 only MAX is specified, MIN will default to 0 ("no more than
476 MAX").
477 procfix NAME PROG ARGS
479 registers a command that can be run to fix errors with the given
480 process NAME. This will be invoked when the corresponding prE‐
481 rrFix instance is set to 1.
482 Note: This command will not be invoked automatically.
484 The procfix directive must be specified after the matching proc
486 directive, and cannot be used on its own.
487 If no proc directives are defined, then walking the prTable will fail
489 (noSuchObject).
490 Disk Usage Monitoring
492 This requires that the agent was built with support for the ucd-
493 snmp/disk module (which is included as part of the default build con‐
494 figuration).
495 disk PATH [ MINSPACE | MINPERCENT% ]
497 monitors the disk mounted at PATH for available disk space.
498 The minimum threshold can either be specified in Kb (MINSPACE)
500 or as a percentage of the total disk (MINPERCENT% with a '%'
501 character), defaulting to 100Kb if neither are specified. If
502 the free disk space falls below this threshold, then the corre‐
503 sponding dskErrorFlag instance will be set to 1, and a suitable
504 description message reported via the dskErrorMsg instance.
505 Note: This situation will not automatically trigger a trap to
507 report the problem - see the DisMan Event MIB section
508 later.
509 includeAllDisks MINPERCENT%
511 configures monitoring of all disks found on the system, using
512 the specified (percentage) threshold. The threshold for indi‐
513 vidual disks can be adjusted using suitable disk directives
514 (which can come either before or after the includeAllDisks
515 directive).
516 Note: Whether disk directives appears before or after
518 includeAllDisks may affect the indexing of the dskTable.
519 Only one includeAllDisks directive should be specified - any
521 subsequent copies will be ignored.
522 The list of mounted disks will be determined when the agent
524 starts using the setmntent(3) and getmntent(3), or fopen(3) and
525 getmntent(3), or setfsent(3) and getfsent(3) system calls. If
526 none of the above system calls are available then the root par‐
527 tition "/" (which is assumed to exist on any UNIX based sys‐
528 tem) will be monitored. Disks mounted after the agent has
529 started will not be monitored.
530 If neither any disk directives or includeAllDisks are defined, then
532 walking the dskTable will fail (noSuchObject).
533 System Load Monitoring
535 This requires that the agent was built with support for either the ucd-
536 snmp/loadave module or the ucd-snmp/memory module respectively (both of
537 which are included as part of the default build configuration).
538 load MAX1 [MAX5 [MAX15]]
540 monitors the load average of the local system, specifying
541 thresholds for the 1-minute, 5-minute and 15-minute averages.
542 If any of these loads exceed the associated maximum value, then
543 the corresponding laErrorFlag instance will be set to 1, and a
544 suitable description message reported via the laErrMessage
545 instance.
546 Note: This situation will not automatically trigger a trap to
548 report the problem - see the DisMan Event MIB section
549 later.
550 If the MAX15 threshold is omitted, it will default to the MAX5
552 value. If both MAX5 and MAX15 are omitted, they will default to
553 the MAX1 value. If this directive is not specified, all three
554 thresholds will default to a value of DEFMAXLOADAVE.
555 Unlike the proc and disk directives, walking the walking the laTable
557 will succeed (assuming the ucd-snmp/loadave module was configured into
558 the agent), even if the load directive is not present.
559 swap MIN
561 monitors the amount of swap space available on the local system.
562 If this falls below the specified threshold (MIN Kb), then the
563 memErrorSwap object will be set to 1, and a suitable description
564 message reported via memSwapErrorMsg.
565 Note: This situation will not automatically trigger a trap to
567 report the problem - see the DisMan Event MIB section
568 later.
569 If this directive is not specified, the default threshold is 16 Mb.
570 Log File Monitoring
572 This requires that the agent was built with support for either the ucd-
573 snmp/file or ucd-snmp/logmatch modules respectively (both of which are
574 included as part of the default build configuration).
575 file FILE [MAXSIZE]
577 monitors the size of the specified file (in Kb). If MAXSIZE is
578 specified, and the size of the file exceeds this threshold, then
579 the corresponding fileErrorFlag instance will be set to 1, and a
580 suitable description message reported via the fileErrorMsg
581 instance.
582 Note: This situation will not automatically trigger a trap to
584 report the problem - see the DisMan Event MIB section
585 later.
586 A maximum of 20 files can be monitored.
588 If no file directives are defined, then walking the fileTable will fail
590 (noSuchObject).
591 logmatch NAME PATH CYCLETIME REGEX
593 monitors the specified file for occurances of the specified pat‐
594 tern REGEX.
595 A maximum of 50 files can be monitored.
597 If no logmatch directives are defined, then walking the logMatchTable
599 will fail (noSuchObject).
600
602 The usual behaviour of an SNMP agent is to wait for incoming SNMP
603 requests and respond to them - if no requests are received, an agent
604 will typically not initiate any actions. This section describes various
605 directives that can configure snmpd to take a more active role.
606 Notification Handling
608 trapcommunity STRING
609 defines the default community string to be used when sending
610 traps. Note that this directive must be used prior to any com‐
611 munity-based trap destination directives that need to use it.
612 trapsink HOST [COMMUNITY [PORT]]
614 trap2sink HOST [COMMUNITY [PORT]]
616 informsink HOST [COMMUNITY [PORT]]
618 define the address of a notification receiver that should be
619 sent SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifica‐
620 tions respectively. See the section LISTENING ADDRESSES in the
621 snmpd(8) manual page for more information about the format of
622 listening addresses. If COMMUNITY is not specified, the most
623 recent trapcommunity string will be used.
624 If the transport address does not include an explicit port spec‐
626 ification, then PORT will be used. If this is not specified,
627 the well known SNMP trap port (162) will be used.
628 Note: This mechanism is being deprecated, and the listening
630 port should be specified via the transport specification
631 HOST instead.
632 If several sink directives are specified, multiple copies of
634 each notification (in the appropriate formats) will be gener‐
635 ated.
636 Note: It is not normally appropriate to list two (or all three)
638 sink directives with the same destination.
639 trapsess [SNMPCMD_ARGS] HOST
641 provides a more generic mechanism for defining notification des‐
642 tinations. SNMPCMD_ARGS should be the command-line options
643 required for an equivalent snmptrap (or snmpinform) command to
644 send the desired notification. The option -Ci can be used (with
645 -v2c or -v3) to generate an INFORM notification rather than an
646 unacknowledged TRAP.
647 This is the appropriate directive for defining SNMPv3 trap
649 receivers. See http://www.net-snmp.org/tutorial/tutorial-5/com‐
650 mands/snmptrap-v3.html for more information about SNMPv3 notifi‐
651 cation behaviour.
652 authtrapenable {1|2}
654 determines whether to generate authentication failure traps
655 (enabled(1)) or not (disabled(2) - the default). Ordinarily the
656 corresponding MIB object (snmpEnableAuthenTraps.0) is read-
657 write, but specifying this directive makes this object read-
658 only, and attempts to set the value via SET requests will result
659 in a notWritable error response.
660 DisMan Event MIB
662 The previous directives can be used to configure where traps should be
663 sent, but are not concerned with when to send such traps (or what traps
664 should be generated). This is the domain of the Event MIB - developed
665 by the Distributed Management (DisMan) working group of the IETF.
666 This requires that the agent was built with support for the dis‐
668 man/event module (which is now included as part of the default build
669 configuration for the most recent distribution).
670 Note: The behaviour of the latest implementation differs in
672 some minor respects from the previous code - nothing too
673 significant, but existing scripts may possibly need some
674 minor adjustments.
675 iquerySecName NAME
677 agentSecName NAME
679 specifies the default SNMPv3 username, to be used when making
680 internal queries to retrieve any necessary information (either
681 for evaluating the monitored expression, or building a notifica‐
682 tion payload).
683 Note that this user must also be explicitly created (createUser)
685 and given appropriate access rights (e.g. rouser). This direc‐
686 tive is purely concerned with defining which user should be used
687 - not with actually setting this user up.
688 monitor [OPTIONS] NAME EXPRESSION
690 defines a MIB object to monitor. If the EXPRESSION condition
691 holds (see below), then this will trigger the corresponding
692 event, and either send a notification or apply a SET assignment
693 (or both). Note that the event will only be triggered once,
694 when the expression first matches. This monitor entry will not
695 fire again until the monitored condition first becomes false,
696 and then matches again. NAME is an administrative name for this
697 expression, and is used for indexing the mteTriggerTable (and
698 related tables).
699 EXPRESSION
701 There are three types of monitor expression supported by the
702 Event MIB - existence, boolean and threshold tests.
703 OID | !OID | !=OID
705 defines an existence(0) monitor test. A bare OID speci‐
706 fies a present(0) test, which will fire when (an instance
707 of) the monitored OID is created. An expression of the
708 form !OID specifies an absent(1) test, which will fire
709 when the monitored OID is delected. An expression of the
710 form !=OID specifies a changed(2) test, which will fire
711 whenever the monitored value(s) change.
712 OID OP VALUE
714 defines a boolean(1) monitor test. OP should be one of
715 the defined comparison operators (!=, ==, <, <=, >, >=)
716 and VALUE should be an integer value to compare against.
717 Note that there must be whitespace around the OP token.
718 A comparison such as OID !=0 will not be handled cor‐
719 rectly.
720 OID MIN MAX [DMIN DMAX]
722 defines a threshold(2) monitor test. MIN and MAX are
723 integer values, specifying lower and upper thresholds.
724 If the value of the monitored OID falls below the lower
725 threshold (MIN) or rises above the upper threshold (MAX),
726 then the monitor entry will trigger the corresponding
727 event.
728 Note that the rising threshold event will only be re-
730 armed when the monitored value falls below the lower
731 threshold (MIN). Similarly, the falling threshold event
732 will be re-armed by the upper threshold (MAX).
733 The optional parameters DMIN and DMAX configure a pair of
735 similar threshold tests, but working with the delta dif‐
736 ferences between successive sample values.
737 OPTIONS
739 There are various options to control the behaviour of the moni‐
740 tored expression. These include:
741 -D indicates that the expression should be evaluated using
743 delta differences between sample values (rather than the
744 values themselves).
745 -d OID
747 -di OID
749 specifies a discontinuity marker for validating delta
750 differences. A -di object instance will be used exactly
751 as given. A -d object will have the instance subidenti‐
752 fiers from the corresponding (wildcarded) expression
753 object appended. If the -I flag is specified, then there
754 is no difference between these two options.
755 This option also implies -D.
757 -e EVENT
759 specifies the event to be invoked when this monitor entry
760 is triggered. If this option is not given, the monitor
761 entry will generate one of the standard notifications
762 defined in the DISMAN-EVENT-MIB.
763 -I indicates that the monitored expression should be applied
765 to the specified OID as a single instance. By default,
766 the OID will be treated as a wildcarded object, and the
767 monitor expanded to cover all matching instances.
768 -i OID
770 -o OID define additional varbinds to be added to the notifica‐
772 tion payload when this monitor trigger fires. For a
773 wildcarded expression, the suffix of the matched instance
774 will be added to any OIDs specified using -o, while OIDs
775 specified using -i will be treated as exact instances.
776 If the -I flag is specified, then there is no difference
777 between these two options.
778 See strictDisman for details of the ordering of notifica‐
780 tion payloads.
781 -r FREQUENCY
783 monitors the given expression every FREQUENCY seconds.
784 By default, the expression will be evaluated every 600s
785 (10 minutes).
786 -S indicates that the monitor expression should not be eval‐
788 uated when the agent first starts up. The first evalua‐
789 tion will be done once the first repeat interval has
790 expired.
791 -s indicates that the monitor expression should be evaluated
793 when the agent first starts up. This is the default be‐
794 haviour.
795 Note: Notifications triggered by this initial evaluation
797 will be sent before the coldStart trap.
798 -u SECNAME
800 specifies a security name to use for scanning the local
801 host, instead of the default iquerySecName. Once again,
802 this user must be explicitly created and given suitable
803 access rights.
804 notificationEvent ENAME NOTIFICATION [-n] [-i OID | -o OID ]*
806 defines a notification event named ENAME. This can be triggered
807 from a given monitor entry by specifying the option -e ENAME
808 (see above). NOTIFICATION should be the OID of the NOTIFICA‐
809 TION-TYPE definition for the notification to be generated.
810 If the -n option is given, the notification payload will include
812 the standard varbinds as specified in the OBJECTS clause of the
813 notification MIB definition. This option must come after the
814 NOTIFICATION OID (and the relevant MIB file must be available
815 and loaded by the agent). Otherwise, these varbinds must be
816 listed explicitly (either here or in the corresponding monitor
817 directive).
818 The -i OID and -o OID options specify additional varbinds to be
820 appended to the notification payload, after the standard list.
821 If the monitor entry that triggered this event involved a wild‐
822 carded expression, the suffix of the matched instance will be
823 added to any OIDs specified using -o, while OIDs specified using
824 -i will be treated as exact instances. If the -I flag was spec‐
825 ified to the monitor directive, then there is no difference
826 between these two options.
827 setEvent ENAME [-I] OID = VALUE
829 defines a set event named ENAME, assigning the (integer) VALUE
830 to the specified OID. This can be triggered from a given moni‐
831 tor entry by specifying the option -e ENAME (see above).
832 If the monitor entry that triggered this event involved a wild‐
834 carded expression, the suffix of the matched instance will nor‐
835 mally be added to the OID. If the -I flag was specified to
836 either of the monitor or setEvent directives, the specified OID
837 will be regarded as an exact single instance.
838 strictDisman yes
840 The definition of SNMP notifications states that the varbinds
841 defined in the OBJECT clause should come first (in the order
842 specified), followed by any "extra" varbinds that the notifica‐
843 tion generator feels might be useful. The most natural approach
844 would be to associate these mandatory varbinds with the notifi‐
845 cationEvent entry, and append any varbinds associated with the
846 monitor entry that triggered the notification to the end of this
847 list. This is the default behaviour of the Net-SNMP Event MIB
848 implementation.
849 Unfortunately, the DisMan Event MIB specifications actually
851 state that the trigger-related varbinds should come first, fol‐
852 lowed by the event-related ones. This directive can be used to
853 restore this strictly-correct (but inappropriate) behaviour.
854 Note: Strict DisMan ordering may result in generating invalid
856 notifications payload lists if the notificationEvent -n
857 flag is used together with monitor -o (or -i) varbind
858 options.
859 If no monitor entries specify payload varbinds, then the setting
861 of this directive is irrelevant.
862 linkUpDownNotifications yes
864 will configure the Event MIB tables to monitor the ifTable for
865 network interfaces being taken up or down, and triggering a
866 linkUp or linkDown notification as appropriate.
867 This is exactly equivalent to the configuration:
869 notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
871 notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
872 monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
874 monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
875 defaultMonitors yes
877 will configure the Event MIB tables to monitor the various UCD-
878 SNMP-MIB tables for problems (as indicated by the appropriate
879 xxErrFlag column objects).
880 This is exactly equivalent to the configuration:
882 monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
884 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
885 monitor -o extNames -o extOutput "extTable" extResult != 0
886 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
887 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
888 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
889 In both these latter cases, the snmpd.conf must also contain a iquery‐
891 SecName directive, together with a corresponding createUser entry and
892 suitable access control configuration.
893 DisMan Schedule MIB
895 The DisMan working group also produced a mechanism for scheduling par‐
896 ticular actions (a specified SET assignment) at given times. This
897 requires that the agent was built with support for the disman/schedule
898 module (which is included as part of the default build configuration
899 for the most recent distribution).
900 There are three ways of specifying the scheduled action:
902 repeat FREQUENCY OID = VALUE
904 configures a SET assignment of the (integer) VALUE to the MIB
905 instance OID, to be run every FREQUENCY seconds.
906 cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
908 configures a SET assignment of the (integer) VALUE to the MIB
909 instance OID, to be run at the times specified by the fields
910 MINUTE to WEEKDAY. These follow the same pattern as the equiva‐
911 lent crontab(5) fields.
912 Note: These fields should be specified as a (comma-separated)
914 list of numeric values. Named values for the MONTH and
915 WEEKDAY fields are not supported, and neither are value
916 ranges. A wildcard match can be specified as '*'.
917 The DAY field can also accept negative values, to indicate days
919 counting backwards from the end of the month.
920 at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
922 configures a one-shot SET assignment, to be run at the first
923 matching time as specified by the fields MINUTE to WEEKDAY. The
924 interpretation of these fields is exactly the same as for the
925 cron directive.
926
928 One of the first distinguishing features of the original UCD suite was
929 the ability to extend the functionality of the agent - not just by
930 recompiling with code for new MIB modules, but also by configuring the
931 running agent to report additional information. There are a number of
932 techniques to support this, including:
933 · running external commands (exec, extend, pass)
935 · loading new code dynamically (embedded perl, dlmod)
937 · communicating with other agents (proxy, SMUX, AgentX)
939 Arbitrary Extension Commands
941 The earliest extension mechanism was the ability to run arbitrary com‐
942 mands or shell scripts. Such commands do not need to be aware of SNMP
943 operations, or conform to any particular behaviour - the MIB structures
944 are designed to accommodate any form of command output. Use of this
945 mechanism requires that the agent was built with support for the ucd-
946 snmp/extensible and/or agent/extend modules (which are both included as
947 part of the default build configuration).
948 exec [MIBOID] NAME PROG ARGS
950 sh [MIBOID] NAME PROG ARGS
952 invoke the named PROG with arguments of ARGS. By default the
953 exit status and first line of output from the command will be
954 reported via the extTable, discarding any additional output.
955 Note: Entries in this table appear in the order they are read
957 from the configuration file. This means that adding new
958 exec (or sh) directives and restarting the agent, may
959 affect the indexing of other entries.
960 The PROG argument for exec directives must be a full path to a
962 real binary, as it is executed via the exec() system call. To
963 invoke a shell script, use the sh directive instead.
964 If MIBOID is specified, then the results will be rooted at this
966 point in the OID tree, returning the exit statement as
967 MIBOID.100.0 and the entire command output in a pseudo-table
968 based at MIBNUM.101 - with one 'row' for each line of output.
969 Note: The layout of this "relocatable" form of exec (or sh)
971 output does not strictly form a valid MIB structure.
972 This mechanism is being deprecated - please see the
973 extend directive (described below) instead.
974 In either case, the exit statement and output will be cached for
976 30s after the initial query. This cache can be flushed by a SET
977 request of the integer value 1 to the MIB instance version‐
978 ClearCache.0.
979 execfix NAME PROG ARGS
981 registers a command that can be invoked on demand - typically to
982 respond to or fix errors with the corresponding exec or sh
983 entry. When the extErrFix instance for a given NAMEd entry is
984 set to the integer value of 1, this command will be called.
985 Note: This directive can only be used in combination with a
987 corresponding exec or sh directive, which must be defined
988 first. Attempting to define an unaccompanied execfix
989 directive will fail.
990 exec and sh extensions can only be configured via the snmpd.conf file.
992 They cannot be set up via SNMP SET requests.
993 extend [MIBOID] NAME PROG ARGS
995 works in a similar manner to the exec directive, but with a num‐
996 ber of improvements. The MIB tables (nsExtendConfigTable etc)
997 are indexed by the NAME token, so are unaffected by the order in
998 which entries are read from the configuration files. There are
999 two result tables - one (nsExtendOutput1Table) containing the
1000 exit status, the first line and full output (as a single string)
1001 for each extend entry, and the other (nsExtendOutput2Table) con‐
1002 taining the complete output as a series of separate lines.
1003 If MIBOID is specified, then the configuration and result tables
1005 will be rooted at this point in the OID tree, but are otherwise
1006 structured in exactly the same way. This means that several sep‐
1007 arate extend directives can specify the same MIBOID root, with‐
1008 out conflicting.
1009 The exit status and output is cached for each entry individu‐
1011 ally, and can be cleared (and the caching behaviour configured)
1012 using the nsCacheTable.
1013 extendfix NAME PROG ARGS
1015 registers a command that can be invoked on demand, by setting
1016 the appropriate nsExtendRunType instance to the value run-com‐
1017 mand(3). Unlike the equivalent execfix, this directive does not
1018 need to be paired with a corresponding extend entry, and can
1019 appear on its own.
1020 Both extend and extendfix directives can be configured dynamically,
1022 using SNMP SET requests to the NET-SNMP-EXTEND-MIB.
1023 MIB-Specific Extension Commands
1025 The first group of extension directives invoke arbitrary commands, and
1026 rely on the MIB structure (and management applications) having the
1027 flexibility to accommodate and interpret the output. This is a conve‐
1028 nient way to make information available quickly and simply, but is of
1029 no use when implementing specific MIB objects, where the extension must
1030 conform to the structure of the MIB (rather than vice versa). The
1031 remaining extension mechanisms are all concerned with such MIB-specific
1032 situations - starting with "pass-through" scripts. Use of this mecha‐
1033 nism requires that the agent was built with support for the ucd-
1034 snmp/pass and ucd-snmp/pass_persist modules (which are both included as
1035 part of the default build configuration).
1036 pass [-p priority] MIBOID PROG
1038 will pass control of the subtree rooted at MIBOID to the speci‐
1039 fied PROG command. GET and GETNEXT requests for OIDs within
1040 this tree will trigger this command, called as:
1041 PROG -g OID
1043 PROG -n OID
1045 respectively, where OID is the requested OID. The PROG command
1047 should return the response varbind as three separate lines
1048 printed to stdout - the first line should be the OID of the
1049 returned value, the second should be its TYPE (one of the text
1050 strings integer, gauge, counter, timeticks, ipaddress, objectid,
1051 or string ), and the third should be the value itself.
1052 If the command cannot return an appropriate varbind - e.g the
1054 specified OID did not correspond to a valid instance for a GET
1055 request, or there were no following instances for a GETNEXT -
1056 then it should exit without producing any output. This will
1057 result in an SNMP noSuchName error, or a noSuchInstance excep‐
1058 tion.
1059 Note: The SMIv2 type counter64 and SNMPv2 noSuchObject
1061 exception are not supported.
1062 A SET request will result in the command being called as:
1064 PROG -s OID TYPE VALUE
1066 where TYPE is one of the tokens listed above, indicating the
1068 type of the value passed as the third parameter.
1069 If the assignment is successful, the PROG command should exit
1071 without producing any output. Errors should be indicated by
1072 writing one of the strings not-writable, or wrong-type to std‐
1073 out, and the agent will generate the appropriate error response.
1074 Note: The other SNMPv2 errors are not supported.
1076 In either case, the command should exit once it has finished
1078 processing. Each request (and each varbind within a single
1079 request) will trigger a separate invocation of the command.
1080 The default registration priority is 127. This can be changed
1082 by supplying the optional -p flag, with lower priority registra‐
1083 tions being used in preference to higher priority values.
1084 pass_persist [-p priority] MIBOID PROG
1086 will also pass control of the subtree rooted at MIBOID to the
1087 specified PROG command. However this command will continue to
1088 run after the initial request has been answered, so subsequent
1089 requests can be processed without the startup overheads.
1090 Upon initialization, PROG will be passed the string "PING\n" on
1092 stdin, and should respond by printing "PONG\n" to stdout.
1093 For GET and GETNEXT requests, PROG will be passed two lines on
1095 stdin, the command (get or getnext) and the requested OID. It
1096 should respond by printing three lines to stdout - the OID for
1097 the result varbind, the TYPE and the VALUE itself - exactly as
1098 for the pass directive above. If the command cannot return an
1099 appropriate varbind, it should print print "NONE\n" to stdout
1100 (but continue running).
1101 For SET requests, PROG will be passed three lines on stdin, the
1103 command (set) and the requested OID, followed by the type and
1104 value (both on the same line). If the assignment is successful,
1105 the command should print "DONE\n" to stdout. Errors should be
1106 indicated by writing one of the strings not-writable, wrong-
1107 type, wrong-length, wrong-value or inconsistent-value to stdout,
1108 and the agent will generate the appropriate error response. In
1109 either case, the command should continue running.
1110 The registration priority can be changed using the optional -p
1112 flag, just as for the pass directive.
1113 pass and pass_persist extensions can only be configured via the
1115 snmpd.conf file. They cannot be set up via SNMP SET requests.
1116 Embedded Perl Support
1118 Programs using the previous extension mechanisms can be written in any
1119 convenient programming language - including perl, which is a common
1120 choice for pass-through extensions in particular. However the Net-SNMP
1121 agent also includes support for embedded perl technology (similar to
1122 mod_perl for the Apache web server). This allows the agent to inter‐
1123 pret perl scripts directly, thus avoiding the overhead of spawning pro‐
1124 cesses and initializing the perl system when a request is received.
1125 Use of this mechanism requires that the agent was built with support
1127 for the embedded perl mechanism, which is not part of the default build
1128 environment. It must be explicitly included by specifying the
1129 '--enable-embedded-perl' option to the configure script when the pack‐
1130 age is first built.
1131 If enabled, the following directives will be recognised:
1133 disablePerl true
1135 will turn off embedded perl support entirely (e.g. if there are
1136 problems with the perl installation).
1137 perlInitFile FILE
1139 loads the specified initialisation file (if present) immediately
1140 before the first perl directive is parsed. If not explicitly
1141 specified, the agent will look for the default initialisation
1142 file /usr/share/snmp/snmp_perl.pl.
1143 The default initialisation file creates an instance of a Net‐
1145 SNMP::agent object - a variable $agent which can be used to reg‐
1146 ister perl-based MIB handler routines.
1147 perl EXPRESSION
1149 evaluates the given expression. This would typically register a
1150 handler routine to be called when a section of the OID tree was
1151 requested:
1152 perl use Data::Dumper;
1153 perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
1154 perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
1155 This expression could also source an external file:
1157 perl 'do /path/to/file.pl';
1158 or perform any other perl-based processing that might be
1160 required.
1161 Dynamically Loadable Modules
1163 Most of the MIBs supported by the Net-SNMP agent are implemented as C
1164 code modules, which were compiled and linked into the agent libraries
1165 when the suite was first built. Such implementation modules can also
1166 be compiled independently and loaded into the running agent once it has
1167 started. Use of this mechanism requires that the agent was built with
1168 support for the ucd-snmp/dlmod module (which is included as part of the
1169 default build configuration).
1170 dlmod NAME PATH
1172 will load the shared object module from the file PATH (an abso‐
1173 lute filename), and call the initialisation routine init_NAME.
1174 Note: If the specified PATH is not a fully qualified filename,
1176 it will be interpreted relative to /usr/lib64/snmp/dlmod,
1177 and .so will be appended to the filename.
1178 This functionality can also be configured using SNMP SET requests to
1180 the UCD-DLMOD-MIB.
1181 Proxy Support
1183 Another mechanism for extending the functionality of the agent is to
1184 pass selected requests (or selected varbinds) to another SNMP agent,
1185 which can be running on the same host (presumably listening on a dif‐
1186 ferent port), or on a remote system. This can be viewed either as the
1187 main agent delegating requests to the remote one, or acting as a proxy
1188 for it. Use of this mechanism requires that the agent was built with
1189 support for the ucd-snmp/proxy module (which is included as part of the
1190 default build configuration).
1191 proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
1193 will pass any incoming requests under OID to the agent listening
1194 on the port specified by the transport address HOST. See the
1195 section LISTENING ADDRESSES in the snmpd(8) manual page for more
1196 information about the format of listening addresses.
1197 Note: To proxy the entire MIB tree, use the OID .1.3 (not the
1199 top-level .1)
1200 The SNMPCMD_ARGS should provide sufficient version and administrative
1202 information to generate a valid SNMP request (see snmpcmd(1)).
1203 Note: The proxied request will not use the administrative settings
1205 from the original request.
1206 If a CONTEXTNAME is specified, this will register the proxy delegation
1208 within the named context in the local agent. Defining multiple proxy
1209 directives for the same OID but different contexts can be used to query
1210 several remote agents through a single proxy, by specifying the appro‐
1211 priate SNMPv3 context in the incoming request (or using suitable con‐
1212 figured community strings - see the com2sec directive).
1213 Specifying the REMOID parameter will map the local MIB tree rooted at
1215 OID to an equivalent subtree rooted at REMOID on the remote agent.
1216 SMUX Sub-Agents
1218 The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1219 with SMUX-based subagents (such as gated, zebra or quagga). Use of
1220 this mechanism requires that the agent was built with support for the
1221 smux module, which is not part of the default build environment, and
1222 must be explicitly included by specifying the '--with-mib-modules=smux'
1223 option to the configure script when the package is first built.
1224 Note: This extension protocol has been officially deprecated in
1226 favour of AgentX (see below).
1227 smuxpeer OID PASS
1229 will register a subtree for SMUX-based processing, to be authen‐
1230 ticated using the password PASS. If a subagent (or "peer") con‐
1231 nects to the agent and registers this subtree then requests for
1232 OIDs within it will be passed to that SMUX subagent for process‐
1233 ing.
1234 A suitable entry for an OSPF routing daemon (such as gated,
1236 zebra or quagga) might be something like
1237 smuxpeer .1.3.6.1.2.1.14 ospf_pass
1238 smuxsocket <IPv4-address>
1240 defines the IPv4 address for SMUX peers to communicate with the
1241 Net-SNMP agent. The default is to listen on all IPv4 interfaces
1242 ("0.0.0.0"), unless the package has been configured with
1243 "--enable-local-smux" at build time, which causes it to only
1244 listen on 127.0.0.1 by default. SMUX uses the well-known TCP
1245 port 199.
1246 Note the Net-SNMP agent will only operate as a SMUX master agent. It
1248 does not support acting in a SMUX subagent role.
1249 AgentX Sub-Agents
1251 The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both mas‐
1252 ter and subagent roles. Use of this mechanism requires that the agent
1253 was built with support for the agentx module (which is included as part
1254 of the default build configuration), and also that this support is
1255 explicitly enabled (e.g. via the snmpd.conf file).
1256 There are two directives specifically relevant to running as an AgentX
1258 master agent:
1259 master agentx
1261 will enable the AgentX functionality and cause the agent to
1262 start listening for incoming AgentX registrations. This can
1263 also be activated by specifying the '-x' command-line option (to
1264 specify an alternative listening socket).
1265 agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
1267 Defines the permissions and ownership of the AgentX Unix Domain
1268 socket, and the parent directories of this socket. SOCKPERMS
1269 and DIRPERMS must be octal digits (see chmod(1) ). By default
1270 this socket will only be accessible to subagents which have the
1271 same userid as the agent.
1272 There is one directive specifically relevant to running as an AgentX
1274 sub-agent:
1275 agentXPingInterval NUM
1277 will make the subagent try and reconnect every NUM seconds to
1278 the master if it ever becomes (or starts) disconnected.
1279 The remaining directives are relevant to both AgentX master and sub-
1281 agents:
1282 agentXSocket [<transport-specifier>:]<transport-address>[,...]
1284 defines the address the master agent listens at, or the subagent
1285 should connect to. The default is the Unix Domain socket
1286 "/var/agentx/master". Another common alternative is tcp:local‐
1287 host:705. See the section LISTENING ADDRESSES in the snmpd(8)
1288 manual page for more information about the format of addresses.
1289 Note: Specifying an AgentX socket does not automatically enable
1291 AgentX functionality (unlike the '-x' command-line
1292 option).
1293 agentXTimeout NUM
1295 defines the timeout period (NUM seconds) for an AgentX request.
1296 Default is 1 second.
1297 agentXRetries NUM
1299 defines the number of retries for an AgentX request. Default is
1300 5 retries.
1301 net-snmp ships with both C and Perl APIs to develop your own AgentX
1303 subagent.
1304
1306 override [-rw] OID TYPE VALUE
1307 This directive allows you to override a particular OID with a
1308 different value (and possibly a different type of value). The
1309 -rw flag will allow snmp SETs to modify it's value as well.
1310 (note that if you're overriding original functionality, that
1311 functionality will be entirely lost. Thus SETS will do nothing
1312 more than modify the internal overridden value and will not per‐
1313 form any of the original functionality intended to be provided
1314 by the MIB object. It's an emulation only.) An example:
1315 override sysDescr.0 octet_str "my own sysDescr"
1317 That line will set the sysDescr.0 value to "my own sysDescr" as
1319 well as make it modifiable with SNMP SETs as well (which is
1320 actually illegal according to the MIB specifications).
1321 Note that care must be taken when using this. For example, if
1323 you try to override a property of the 3rd interface in the
1324 ifTable with a new value and later the numbering within the
1325 ifTable changes it's index ordering you'll end up with problems
1326 and your modified value won't appear in the right place in the
1327 table.
1328 Valid TYPEs are: integer, uinteger, octet_str, object_id,
1330 counter, null (for gauges, use "uinteger"; for bit strings, use
1331 "octet_str"). Note that setting an object to "null" effectively
1332 delete's it as being accessible. No VALUE needs to be given if
1333 the object type is null.
1334 More types should be available in the future.
1336 If you're trying to figure out aspects of the various mib modules (pos‐
1338 sibly some that you've added yourself), the following may help you spit
1339 out some useful debugging information. First off, please read the
1340 snmpd manual page on the -D flag. Then the following configuration
1341 snmpd.conf token, combined with the -D flag, can produce useful output:
1342 injectHandler HANDLER modulename
1344 This will insert new handlers into the section of the mib tree
1345 referenced by "modulename". The types of handlers available for
1346 insertion are:
1347 stash_cache
1349 Caches information returned from the lower level. This
1350 greatly help the performance of the agent, at the cost of
1351 caching the data such that its no longer "live" for 30
1352 seconds (in this future, this will be configurable).
1353 Note that this means snmpd will use more memory as well
1354 while the information is cached. Currently this only
1355 works for handlers registered using the table_iterator
1356 support, which is only a few mib tables. To use it, you
1357 need to make sure to install it before the table_iterator
1358 point in the chain, so to do this:
1359 injectHandler stash_cache NAME ta‐
1361 ble_iterator
1362 If you want a table to play with, try walking the nsMod‐
1364 uleTable with and without this injected.
1365 debug Prints out lots of debugging information when the
1368 -Dhelper:debug flag is passed to the snmpd application.
1369 read_only
1372 Forces turning off write support for the given module.
1373 serialize
1376 If a module is failing to handle multiple requests prop‐
1377 erly (using the new 5.0 module API), this will force the
1378 module to only receive one request at a time.
1379 bulk_to_next
1382 If a module registers to handle getbulk support, but for
1383 some reason is failing to implement it properly, this
1384 module will convert all getbulk requests to getnext
1385 requests before the final module receives it.
1386 dontLogTCPWrappersConnects
1388 If the snmpd was compiled with TCP Wrapper support, it logs
1389 every connection made to the agent. This setting disables the
1390 log messages for accepted connections. Denied connections will
1391 still be logged.
1392 Figuring out module names
1394 To figure out which modules you can inject things into, run snm‐
1395 pwalk on the nsModuleTable which will give a list of all named
1396 modules registered within the agent.
1397 Internal Data tables
1399 table NAME
1400 add_row NAME INDEX(ES) VALUE(S)
1402
1404 o The Net-SNMP agent can be instructed to re-read the various con‐
1405 figuration files, either via an snmpset assignment of integer(1)
1406 to UCD-SNMP-MIB::versionUpdateConfig.0
1407 (.1.3.6.1.4.1.2021.100.11.0), or by sending a kill -HUP signal
1408 to the agent process.
1409 o All directives listed with a value of "yes" actually accept a
1411 range of boolean values. These will accept any of 1, yes or
1412 true to enable the corresponding behaviour, or any of 0, no or
1413 false to disable it. The default in each case is for the fea‐
1414 ture to be turned off, so these directives are typically only
1415 used to enable the appropriate behaviour.
1416
1418 See the EXAMPLE.CONF file in the top level source directory for a more
1419 detailed example of how the above information is used in real examples.
1420
1422 /etc/snmp/snmpd.conf
1423
1425 snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM‐
1426 PLE.conf, read_config(3).
14274th Berkeley Distribution 08 Feb 2002 SNMPD.CONF(5)