1SNMPTRAPD(8) Net-SNMP SNMPTRAPD(8)
2
6 snmptrapd - Receive and log SNMP trap messages.
7
9 snmptrapd [OPTIONS] [LISTENING ADDRESSES]
10
12 snmptrapd is an SNMP application that receives and logs SNMP TRAP and
13 INFORM messages.
14 Note: the default is to listen on UDP port 162 on all IPv4 interfaces.
16 Since 162 is a privileged port, snmptrapd must typically be run as
17 root.
18
20 -a Ignore authenticationFailure traps.
21 -A Append to the log file rather than truncating it.
23 -c FILE Read FILE as a configuration file.
25 -C Do not read any configuration files except the one optionally
27 specified by the -c option.
28 -d Dump (in hexadecimal) the sent and received SNMP packets.
30 -D TOKEN[,...]
32 Turn on debugging output for the given TOKEN(s). Try ALL for
33 extremely verbose output.
34 -e Print event numbers (rising/falling alarm etc.) from the (obso‐
36 lete) M2M-MIB.
37 This functionality is being deprecated and will be removed in
38 due course.
39 -f Do not fork() from the calling shell.
41 -F FORMAT
43 When logging to standard output, use the format in the string
44 FORMAT. See the section FORMAT SPECIFICATIONS below for more
45 details.
46 -h, --help
48 Display a brief usage message and then exit.
49 -H Display a list of configuration file directives understood by
51 the trap daemon and then exit.
52 -I [-]INITLIST
54 Specifies which modules should (or should not) be initialized
55 when snmptrapd starts up. If the comma-separated INITLIST is
56 preceded with a '-', it is the list of modules that should not
57 be started. not want to be started. Otherwise, INITLIST Oth‐
58 erwise this is the list of the only modules that should be
59 started.
60 To get a list of compiled modules, run snmptrapd with the argu‐
62 ments -Dmib_init -H (assuming debugging support has been com‐
63 piled in).
64 -L[efos]
66 Specify where logging output should be directed (standard error
67 or output, to a file or via syslog). See LOGGING OPTIONS in
68 snmpcmd(1) for details.
69 -m MIBLIST
71 Specifies a colon separated list of MIB modules to load for
72 this application. This overrides the environment variable
73 MIBS. See snmpcmd(1) for details.
74 -M DIRLIST
76 Specifies a colon separated list of directories to search for
77 MIBs. This overrides the environment variable MIBDIRS. See
78 snmpcmd(1) for details.
79 -n Do not attempt to translate source addresses of incoming pack‐
81 ets into hostnames.
82 -p FILE Save the process ID of the trap daemon in FILE.
84 -O [abeEfnqQsStTuUvxX]
86 Specifies how MIB objects and other output should be displayed.
87 See the section OUTPUT OPTIONS in the snmpcmd(1) manual page
88 for details.
89 -t Do not log traps to syslog. This disables logging to syslog.
91 This is useful if you want the snmptrapd application to only
92 run traphandle hooks and not to log any traps to any location.
93 -v, --version
95 Print version information for the trap daemon and then exit.
96 -x ADDRESS
98 Connect to the AgentX master agent on the specified address,
99 rather than the default ''. See snmpd(8) for details of the
100 format of such addresses.
101 --name="value"
103 Allows to specify any token ("name") supported in the
104 snmptrapd.conf file and sets its value to "value". Overrides
105 the corresponding token in the snmptrapd.conf file. See
106 snmptrapd.conf(5) for the full list of tokens.
107
109 snmptrapd interprets format strings similarly to printf(3). It under‐
110 stands the following formatting sequences:
111 %% a literal %
113 %a the contents of the agent-addr field of the PDU (v1 TRAPs only)
115 %A the hostname corresponding to the contents of the agent-addr
117 field of the PDU, if available, otherwise the contents of the
118 agent-addr field of the PDU (v1 TRAPs only).
119 %b PDU source address (Note: this is not necessarily an IPv4
121 address)
122 %B PDU source hostname if available, otherwise PDU source address
124 (see note above)
125 %h current hour on the local system
127 %H the hour field from the sysUpTime.0 varbind
129 %j current minute on the local system
131 %J the minute field from the sysUpTime.0 varbind
133 %k current second on the local system
135 %K the seconds field from the sysUpTime.0 varbind
137 %l current day of month on the local system
139 %L the day of month field from the sysUpTime.0 varbind
141 %m current (numeric) month on the local system
143 %M the numeric month field from the sysUpTime.0 varbind
145 %N enterprise string
147 %q trap sub-type (numeric, in decimal)
149 %P security information from the PDU (community name for v1/v2c,
151 user and context for v3)
152 %t decimal number of seconds since the operating system epoch (as
154 returned by time(2))
155 %T the value of the sysUpTime.0 varbind in seconds
157 %v list of variable-bindings from the notification payload. These
159 will be separated by a tab, or by a comma and a blank if the
160 alternate form is requested See also %V
161 %V specifies the variable-bindings separator. This takes a
163 sequence of characters, up to the next % (to embed a % in the
164 string, use \%)
165 %w trap type (numeric, in decimal)
167 %W trap description
169 %y current year on the local system
171 %Y the year field from the sysUpTime.0 varbind
173 In addition to these values, an optional field width and precision may
175 also be specified , just as in printf(3), and a flag value. The follow‐
176 ing flags are supported:
177 - left justify
179 0 use leading zeros
181 # use alternate form
183 The "use alternate form" flag changes the behavior of various format
185 string sequences:
186 Time information will be displayed based on GMT (rather than the
188 local timezone)
189 The variable-bindings will be a comma-separated list (rather
191 than a tab-separated one)
192 The system uptime will be broken down into a human-meaningful
194 format (rather than being a simple integer)
195 Examples:
197 To get a message like "14:03 TRAP3.1 from humpty.ucd.edu" you could use
198 something like this:
199 snmptrapd -P -F "%02.2h:%02.2j TRAP%w.%q from %A\n"
201 If you want the same thing but in GMT rather than local time, use
203 snmptrapd -P -F "%#02.2h:%#02.2j TRAP%w.%q from %A\n"
205
207 By default, snmptrapd listens for incoming SNMP TRAP and INFORM packets
208 on UDP port 162 on all IPv4 interfaces. However, it is possible to
209 modify this behaviour by specifying one or more listening addresses as
210 arguments to snmptrapd. See the snmpd(8) manual page for more informa‐
211 tion about the format of listening addresses.
212
214 As of net-snmp 5.0, the snmptrapd application supports the NOTIFICA‐
215 TION-LOG-MIB. It does this by opening an AgentX subagent connection to
216 the master snmpd agent and registering the notification log tables. As
217 long as the snmpd application is started first, it will attach itself
218 to it and thus you should be able to view the last recorded notifica‐
219 tions via the nlmLogTable and nlmLogVariableTable. See the
220 snmptrapd.conf file and the "dontRetainLogs" token for turning off this
221 support. See the NOTIFICATION-LOG-MIB for more details about the MIB
222 itself.
223
225 See the snmptrapd.conf(5) manual page.
226
228 snmpcmd(1), snmpd(8), printf(3), snmptrapd.conf(5), syslog(8), vari‐
229 ables(5)
230SNMPD.CONF(5) Net-SNMP SNMPD.CONF(5)
234
238 snmpd.conf - configuration file for the Net-SNMP SNMP agent
239
241 The Net-SNMP agent uses one or more configuration files to control its
242 operation and the management information provided. These files
243 (snmpd.conf and snmpd.local.conf) can be located in one of several
244 locations, as described in the snmp_config(5) manual page.
245 The (perl) application snmpconf can be used to generate configuration
247 files for the most common agent requirements. See the snmpconf(1) man‐
248 ual page for more information, or try running the command:
249 snmpconf -g basic_setup
251 There are a large number of directives that can be specified, but these
253 mostly fall into four distinct categories:
254 · those controlling who can access the agent
256 · those configuring the information that is supplied by the agent
258 · those controlling active monitoring of the local system
260 · those concerned with extending the functionality of the agent.
262 Some directives don't fall naturally into any of these four categories,
264 but this covers the majority of the contents of a typical snmpd.conf
265 file. A full list of recognised directives can be obtained by running
266 the command:
267 snmpd -H
269
271 Although most configuration directives are concerned with the MIB
272 information supplied by the agent, there are a handful of directives
273 that control the behaviour of snmpd considered simply as a daemon pro‐
274 viding a network service.
275 agentaddress [<transport-specifier>:]<transport-address>[,...]
277 defines a list of listening addresses, on which to receive
278 incoming SNMP requests. See the section LISTENING ADDRESSES in
279 the snmpd(8) manual page for more information about the format
280 of listening addresses.
281 The default behaviour is to listen on UDP port 161 on all IPv4
283 interfaces.
284 agentgroup {GROUP|#GID}
286 changes to the specified group after opening the listening
287 port(s). This may refer to a group by name (GROUP), or a
288 numeric group ID starting with '#' (#GID).
289 agentuser {USER|#UID}
291 changes to the specified user after opening the listening
292 port(s). This may refer to a user by name (USER), or a numeric
293 user ID starting with '#' (#UID).
294 leave_pidfile yes
296 instructs the agent to not remove its pid file on shutdown.
297 Equivalent to specifying "-U" on the command line.
298 SNMPv3 Configuration
300 SNMPv3 requires an SNMP agent to define a unique "engine ID" in order
301 to respond to SNMPv3 requests. This ID will normally be determined
302 automatically, using two reasonably non-predictable values - a
303 (pseudo-)random number and the current uptime in seconds. This is the
304 recommended approach. However the capacity exists to define the
305 engineID in other ways:
306 engineID STRING
308 specifies that the engineID should be built from the given text
309 STRING.
310 engineIDType 1|2|3
312 specifies that the engineID should be built from the IPv4
313 address (1), IPv6 address (2) or MAC address (3). Note that
314 changing the IP address (or switching the network interface
315 card) may cause problems.
316 engineIDNic INTERFACE
318 defines which interface to use when determining the MAC address.
319 If engineIDType 3 is not specified, then this directive has no
320 effect.
321 The default is to use eth0.
323
325 snmpd supports the View-Based Access Control Model (VACM) as defined in
326 RFC 2575, to control who can retrieve or update information. To this
327 end, it recognizes various directives relating to access control.
328 These fall into four basic groups.
329 SNMPv3 Users
331 createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES]
332 [privpassphrase]
333 MD5 and SHA are the authentication types to use. DES and AES
335 are the privacy protocols to use. If the privacy passphrase is
336 not specified, it is assumed to be the same as the authentica‐
337 tion passphrase. Note that the users created will be useless
338 unless they are also added to the VACM access control tables
339 described above.
340 SHA authentication and DES/AES privacy require OpenSSL to be
342 installed and the agent to be built with OpenSSL support. MD5
343 authentication may be used without OpenSSL.
344 Warning: the minimum pass phrase length is 8 characters.
346 SNMPv3 users can be created at runtime using the snmpusm(1) com‐
348 mand.
349 Instead of figuring out how to use this directive and where to
351 put it (see below), just run "net-snmp-config --create-
352 snmpv3-user" instead, which will add one of these lines to the
353 right place.
354 This directive should be placed into the /var/net-
356 snmp/snmpd.conf file instead of the other normal locations. The
357 reason is that the information is read from the file and then
358 the line is removed (eliminating the storage of the master pass‐
359 word for that user) and replaced with the key that is derived
360 from it. This key is a localized key, so that if it is stolen
361 it can not be used to access other agents. If the password is
362 stolen, however, it can be.
363 If you need to localize the user to a particular EngineID (this
365 is useful mostly in the similar snmptrapd.conf file), you can
366 use the -e argument to specify an EngineID as a hex value (EG,
367 "0x01020304").
368 If you want to generate either your master or localized keys
370 directly, replace the given password with a hexstring (preceeded
371 by a "0x") and precede the hex string by a -m or -l token
372 (respectively). EGs:
373 [these keys are *not* secure but are easy to visually parse for
375 counting purposes. Please generate random keys instead of using
376 these examples]
377 createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
379 createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
380 Due to the way localization happens, localized privacy keys are
382 expected to be the length needed by the algorithm (128 bits for
383 all supported algorithms). Master encryption keys, though, need
384 to be the length required by the authentication algorithm not
385 the length required by the encrypting algorithm (MD5: 16 bytes,
386 SHA: 20 bytes).
387 Traditional Access Control
389 Most simple access control requirements can be specified using the
390 directives rouser/rwuser (for SNMPv3) or rocommunity/rwcommunity (for
391 SNMPv1 or SNMPv2c).
392 rouser USER [noauth|auth|priv [OID]]
394 rwuser USER [noauth|auth|priv [OID]]
396 specify an SNMPv3 user that will be allowed read-only (GET and
397 GETNEXT) or read-write (GET, GETNEXT and SET) access respec‐
398 tively. By default, this will provide access to the full OID
399 tree for authenticated (including encrypted) SNMPv3 requests.
400 An alternative minimum security level can be specified using
401 noauth (to allow unauthenticated requests), or priv (to enforce
402 use of encryption). The OID field restricts access for that
403 user to the subtree rooted at the given OID.
404 rocommunity COMMUNITY [SOURCE [OID]]
406 rwcommunity COMMUNITY [SOURCE [OID]]
408 specify an SNMPv1 or SNMPv2c community that will be allowed
409 read-only (GET and GETNEXT) or read-write (GET, GETNEXT and SET)
410 access respectively. By default, this will provide access to
411 the full OID tree for such requests, regardless of where they
412 were sent from. The SOURCE token can be used to restrict access
413 to requests from the specified system(s) - see com2sec for the
414 full details. The OID field restricts access for that community
415 to the subtree rooted at the given OID.
416 rocommunity6 COMMUNITY [SOURCE [OID]]
418 rwcommunity6 COMMUNITY [SOURCE [OID]]
420 are directives relating to requests received using IPv6 (if the
421 agent supports such transport domains). The interpretation of
422 the SOURCE and OID tokens are exactly the same as for the IPv4
423 versions.
424 In each case, only one directive should be specified for a given SNMPv3
426 user, or community string. It is not appropriate to specify both
427 rouser and rwuser directives referring to the same SNMPv3 user (or
428 equivalent community settings). The rwuser directive provides all the
429 access of rouser (as well as allowing SET support). The same holds
430 true for the community-based directives.
431 More complex access requirements (such as access to two or more dis‐
433 tinct OID subtrees, or different views for GET and SET requests) should
434 use one of the other access control mechanisms. Note that if several
435 distinct communities or SNMPv3 users need to be granted the same level
436 of access, it would also be more efficient to use the main VACM config‐
437 uration directives.
438 VACM Configuration
440 The full flexibility of the VACM is available using four configuration
441 directives - com2sec, group, view and access. These provide direct
442 configuration of the underlying VACM tables.
443 com2sec [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
445 com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY
447 map an SNMPv1 or SNMPv2c community string to a security name -
448 either from a particular range of source addresses, or globally
449 ("default"). A restricted source can either be a specific host‐
450 name (or address), or a subnet - represented as IP/MASK (e.g.
451 10.10.10.0/255.255.255.0), or IP/BITS (e.g. 10.10.10.0/24), or
452 the IPv6 equivalents.
453 The same community string can be specified in several separate
455 directives (presumably with different source tokens), and the
456 first source/community combination that matches the incoming
457 request will be selected. Various source/community combinations
458 can also map to the same security name.
459 If a CONTEXT is specified (using -Cn), the community string will
461 be mapped to a security name in the named SNMPv3 context. Other‐
462 wise the default context ("") will be used.
463 com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY
465 is the Unix domain sockets version of com2sec.
466 group GROUP {v1|v2c|usm} SECNAME
468 maps a security name (in the specified security model) into a
469 named group. Several group directives can specify the same
470 group name, allowing a single access setting to apply to several
471 users and/or community strings.
472 Note that groups must be set up for the two community-based mod‐
474 els separately - a single com2sec (or equivalent) directive will
475 typically be accompanied by two group directives.
476 view VNAME TYPE OID [MASK]
478 defines a named "view" - a subset of the overall OID tree. This
479 is most commonly a single subtree, but several view directives
480 can be given with the same view name, to build up a more complex
481 collection of OIDs. TYPE is either included or excluded, which
482 can again define a more complex view (e.g by excluding certain
483 sensitive objects from an otherwise accessible subtree).
484 MASK is a list of hex octets (separated by '.' or ':') with the
486 set bits indicating which subidentifiers in the view OID to
487 match against. This can be used to define a view covering a
488 particular row (or rows) in a table. If not specified, this
489 defaults to matching the OID exactly (all bits set), thus defin‐
490 ing a simple OID subtree.
491 access GROUP CONTEXT {any|v1|v2c|usm} LEVEL PREFX READ WRITE NOTIFY
493 maps from a group of users/communities (with a particular secu‐
494 rity model and minimum security level, and in a specific con‐
495 text) to one of three views, depending on the request being pro‐
496 cessed.
497 LEVEL is one of noauth, auth, or priv. PREFX specifies how CON‐
499 TEXT should be matched against the context of the incoming
500 request, either exact or prefix. READ, WRITE and NOTIFY speci‐
501 fies the view to be used for GET*, SET and TRAP/INFORM requests
502 (althought the NOTIFY view is not currently used). For v1 or
503 v2c access, LEVEL will need to be noauth.
504 Typed-View Configuration
506 The final group of directives extend the VACM approach into a more
507 flexible mechanism, which can be applied to other access control
508 requirements. Rather than the fixed three views of the standard VACM
509 mechanism, this can be used to configure various different view types.
510 As far as the main SNMP agent is concerned, the two main view types are
511 read and write, corresponding to the READ and WRITE views of the main
512 access directive. See the 'snmptrapd.conf(5)' man page for discussion
513 of other view types.
514 authcommunity TYPES COMMUNITY [SOURCE [OID | -V VIEW]]
516 is an alternative to the rocommunity/rwcommunity directives.
517 TYPES will usually be read or read,write respectively. The view
518 specification can either be an OID subtree (as before), or a
519 named view (defined using the view directive) for greater flexi‐
520 bility. If this is omitted, then access will be allowed to the
521 full OID tree.
522 authuser TYPES [-s MODEL] USER [LEVEL [OID | -V VIEW]]
524 is an alternative to the rouser/rwuser directives. The fields
525 TYPES, OID and VIEW have the same meaning as for authcommunity.
526 authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW]]
528 is a companion to the authuser directive, specifying access for
529 a particular group (defined using the group directive as usual).
530 Both authuser and authgroup default to authenticated requests -
531 LEVEL can also be specified as noauth or priv to allow unauthen‐
532 ticated requests, or require encryption respectively. Both
533 authuser and authgroup directives also default to configuring
534 access for SNMPv3/USM requests - use the '-s' flag to specify an
535 alternative security model (using the same values as for access
536 above).
537 authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]
539 also configures the access for a particular group, specifying
540 the name and type of view to apply. The MODEL and LEVEL fields
541 are interpreted in the same way as for authgroup. If CONTEXT is
542 specified, access is configured within this SNMPv3 context (or
543 contexts with this prefix if the CONTEXT field ends with '*').
544 Otherwise the default context ("") is used.
545 setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES
547 is a direct equivalent to the original access directive, typi‐
548 cally listing the view types as read or read,write as appropri‐
549 ate. (or see 'snmptrapd.conf(5)' for other possibilities). All
550 other fields have the same interpretation as with access.
551
553 Most of the information reported by the Net-SNMP agent is retrieved
554 from the underlying system, or dynamically configured via SNMP SET
555 requests (and retained from one run of the agent to the next). How‐
556 ever, certain MIB objects can be configured or controlled via the
557 snmpd.conf(5) file.
558 System Group
560 Most of the scalar objects in the 'system' group can be configured in
561 this way:
562 sysLocation STRING
564 sysContact STRING
566 sysName STRING
568 set the system location, system contact or system name (sysLoca‐
569 tion.0, sysContact.0 and sysName.0) for the agent respectively.
570 Ordinarily these objects are writeable via suitably authorized
571 SNMP SET requests. However, specifying one of these directives
572 makes the corresponding object read-only, and attempts to SET it
573 will result in a notWritable error response.
574 sysServices NUMBER
576 sets the value of the sysServices.0 object. For a host system,
577 a good value is 72 (application + end-to-end layers). If this
578 directive is not specified, then no value will be reported for
579 the sysServices.0 object.
580 sysDescr STRING
582 sysObjectID OID
584 sets the system description or object ID for the agent.
585 Although these MIB objects are not SNMP-writable, these direc‐
586 tives can be used by a network administrator to configure suit‐
587 able values for them.
588 Interfaces Group
590 interface NAME TYPE SPEED
591 can be used to provide appropriate type and speed settings for
592 interfaces where the agent fails to determine this information
593 correctly. TYPE is a type value as given in the IANAifType-MIB,
594 and can be specified numerically or by name (assuming this MIB
595 is loaded).
596 Host Resources Group
598 This requires that the agent was built with support for the host module
599 (which is now included as part of the default build configuration on
600 the major supported platforms).
601 ignoreDisk STRING
603 controls which disk devices are scanned as part of populating
604 the hrDiskStorageTable (and hrDeviceTable). The HostRes imple‐
605 mentation code includes a list of disk device patterns appropri‐
606 ate for the current operating system, some of which may cause
607 the agent to block when trying to open the corresponding disk
608 devices. This might lead to a timeout when walking these
609 tables, possibly resulting in inconsistent behaviour. This
610 directive can be used to specify particular devices (either
611 individually or wildcarded) that should not be checked.
612 Note: Please consult the source (host/hr_disk.c) and check for
614 the Add_HR_Disk_entry calls relevant for a particular O/S
615 to determine the list of devices that will be scanned.
616 The pattern can include one or more wildcard expressions. See
618 snmpd.examples(5) for illustration of the wildcard syntax.
619 storageUseNFS [1|2]
621 controls how NFS and NFS-like file systems should be reported in
622 the hrStorageTable. as 'Network Disks' (1) or 'Fixed Disks' (2)
623 Historically, the Net-SNMP agent has reported such file systems
624 as 'Fixed Disks', and this is still the default behaviour. Set‐
625 ting this directive to '1' reports such file systems as
626 Process Monitoring
628 The hrSWRun group of the Host Resources MIB provides information about
629 individual processes running on the local system. The prTable of the
630 UCD-SNMP-MIB complements this by reporting on selected services (which
631 may involve multiple processes). This requires that the agent was
632 built with support for the ucd-snmp/proc module (which is included as
633 part of the default build configuration).
634 proc NAME [MAX [MIN]]
636 monitors the number of processes called NAME (as reported by
637 "/bin/ps -e") running on the local system.
638 If the number of NAMEd processes is less than MIN or greater
640 than MAX, then the corresponding prErrorFlag instance will be
641 set to 1, and a suitable description message reported via the
642 prErrMessage instance.
643 Note: This situation will not automatically trigger a trap to
645 report the problem - see the DisMan Event MIB section
646 later.
647 If neither MAX nor MIN are specified (or are both 0), they will
649 default to infinity and 1 respectively ("at least one"). If
650 only MAX is specified, MIN will default to 0 ("no more than
651 MAX").
652 procfix NAME PROG ARGS
654 registers a command that can be run to fix errors with the given
655 process NAME. This will be invoked when the corresponding prE‐
656 rrFix instance is set to 1.
657 Note: This command will not be invoked automatically.
659 The procfix directive must be specified after the matching proc
661 directive, and cannot be used on its own.
662 If no proc directives are defined, then walking the prTable will fail
664 (noSuchObject).
665 Disk Usage Monitoring
667 This requires that the agent was built with support for the ucd-
668 snmp/disk module (which is included as part of the default build con‐
669 figuration).
670 disk PATH [ MINSPACE | MINPERCENT% ]
672 monitors the disk mounted at PATH for available disk space.
673 The minimum threshold can either be specified in Kb (MINSPACE)
675 or as a percentage of the total disk (MINPERCENT% with a '%'
676 character), defaulting to 100Kb if neither are specified. If
677 the free disk space falls below this threshold, then the corre‐
678 sponding dskErrorFlag instance will be set to 1, and a suitable
679 description message reported via the dskErrorMsg instance.
680 Note: This situation will not automatically trigger a trap to
682 report the problem - see the DisMan Event MIB section
683 later.
684 includeAllDisks MINPERCENT%
686 configures monitoring of all disks found on the system, using
687 the specified (percentage) threshold. The threshold for indi‐
688 vidual disks can be adjusted using suitable disk directives
689 (which can come either before or after the includeAllDisks
690 directive).
691 Note: Whether disk directives appears before or after
693 includeAllDisks may affect the indexing of the dskTable.
694 Only one includeAllDisks directive should be specified - any
696 subsequent copies will be ignored.
697 The list of mounted disks will be determined when the agent
699 starts using the setmntent(3) and getmntent(3), or fopen(3) and
700 getmntent(3), or setfsent(3) and getfsent(3) system calls. If
701 none of the above system calls are available then the root par‐
702 tition "/" (which is assumed to exist on any UNIX based sys‐
703 tem) will be monitored. Disks mounted after the agent has
704 started will not be monitored.
705 If neither any disk directives or includeAllDisks are defined, then
707 walking the dskTable will fail (noSuchObject).
708 System Load Monitoring
710 This requires that the agent was built with support for either the ucd-
711 snmp/loadave module or the ucd-snmp/memory module respectively (both of
712 which are included as part of the default build configuration).
713 load MAX1 [MAX5 [MAX15]]
715 monitors the load average of the local system, specifying
716 thresholds for the 1-minute, 5-minute and 15-minute averages.
717 If any of these loads exceed the associated maximum value, then
718 the corresponding laErrorFlag instance will be set to 1, and a
719 suitable description message reported via the laErrMessage
720 instance.
721 Note: This situation will not automatically trigger a trap to
723 report the problem - see the DisMan Event MIB section
724 later.
725 If the MAX15 threshold is omitted, it will default to the MAX5
727 value. If both MAX5 and MAX15 are omitted, they will default to
728 the MAX1 value. If this directive is not specified, all three
729 thresholds will default to a value of DEFMAXLOADAVE.
730 Unlike the proc and disk directives, walking the walking the laTable
732 will succeed (assuming the ucd-snmp/loadave module was configured into
733 the agent), even if the load directive is not present.
734 swap MIN
736 monitors the amount of swap space available on the local system.
737 If this falls below the specified threshold (MIN Kb), then the
738 memErrorSwap object will be set to 1, and a suitable description
739 message reported via memSwapErrorMsg.
740 Note: This situation will not automatically trigger a trap to
742 report the problem - see the DisMan Event MIB section
743 later.
744 If this directive is not specified, the default threshold is 16 Mb.
745 Log File Monitoring
747 This requires that the agent was built with support for either the ucd-
748 snmp/file or ucd-snmp/logmatch modules respectively (both of which are
749 included as part of the default build configuration).
750 file FILE [MAXSIZE]
752 monitors the size of the specified file (in Kb). If MAXSIZE is
753 specified, and the size of the file exceeds this threshold, then
754 the corresponding fileErrorFlag instance will be set to 1, and a
755 suitable description message reported via the fileErrorMsg
756 instance.
757 Note: This situation will not automatically trigger a trap to
759 report the problem - see the DisMan Event MIB section
760 later.
761 A maximum of 20 files can be monitored.
763 If no file directives are defined, then walking the fileTable will fail
765 (noSuchObject).
766 logmatch NAME PATH CYCLETIME REGEX
768 monitors the specified file for occurances of the specified pat‐
769 tern REGEX.
770 A maximum of 50 files can be monitored.
772 If no logmatch directives are defined, then walking the logMatchTable
774 will fail (noSuchObject).
775
777 The usual behaviour of an SNMP agent is to wait for incoming SNMP
778 requests and respond to them - if no requests are received, an agent
779 will typically not initiate any actions. This section describes various
780 directives that can configure snmpd to take a more active role.
781 Notification Handling
783 trapcommunity STRING
784 defines the default community string to be used when sending
785 traps. Note that this directive must be used prior to any com‐
786 munity-based trap destination directives that need to use it.
787 trapsink HOST [COMMUNITY [PORT]]
789 trap2sink HOST [COMMUNITY [PORT]]
791 informsink HOST [COMMUNITY [PORT]]
793 define the address of a notification receiver that should be
794 sent SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifica‐
795 tions respectively. See the section LISTENING ADDRESSES in the
796 snmpd(8) manual page for more information about the format of
797 listening addresses. If COMMUNITY is not specified, the most
798 recent trapcommunity string will be used.
799 If the transport address does not include an explicit port spec‐
801 ification, then PORT will be used. If this is not specified,
802 the well known SNMP trap port (162) will be used.
803 Note: This mechanism is being deprecated, and the listening
805 port should be specified via the transport specification
806 HOST instead.
807 If several sink directives are specified, multiple copies of
809 each notification (in the appropriate formats) will be gener‐
810 ated.
811 Note: It is not normally appropriate to list two (or all three)
813 sink directives with the same destination.
814 trapsess [SNMPCMD_ARGS] HOST
816 provides a more generic mechanism for defining notification des‐
817 tinations. SNMPCMD_ARGS should be the command-line options
818 required for an equivalent snmptrap (or snmpinform) command to
819 send the desired notification. The option -Ci can be used (with
820 -v2c or -v3) to generate an INFORM notification rather than an
821 unacknowledged TRAP.
822 This is the appropriate directive for defining SNMPv3 trap
824 receivers. See http://www.net-snmp.org/tutorial/tutorial-5/com‐
825 mands/snmptrap-v3.html for more information about SNMPv3 notifi‐
826 cation behaviour.
827 authtrapenable {1|2}
829 determines whether to generate authentication failure traps
830 (enabled(1)) or not (disabled(2) - the default). Ordinarily the
831 corresponding MIB object (snmpEnableAuthenTraps.0) is read-
832 write, but specifying this directive makes this object read-
833 only, and attempts to set the value via SET requests will result
834 in a notWritable error response.
835 DisMan Event MIB
837 The previous directives can be used to configure where traps should be
838 sent, but are not concerned with when to send such traps (or what traps
839 should be generated). This is the domain of the Event MIB - developed
840 by the Distributed Management (DisMan) working group of the IETF.
841 This requires that the agent was built with support for the dis‐
843 man/event module (which is now included as part of the default build
844 configuration for the most recent distribution).
845 Note: The behaviour of the latest implementation differs in
847 some minor respects from the previous code - nothing too
848 significant, but existing scripts may possibly need some
849 minor adjustments.
850 iquerySecName NAME
852 agentSecName NAME
854 specifies the default SNMPv3 username, to be used when making
855 internal queries to retrieve any necessary information (either
856 for evaluating the monitored expression, or building a notifica‐
857 tion payload).
858 Note that this user must also be explicitly created (createUser)
860 and given appropriate access rights (e.g. rouser). This direc‐
861 tive is purely concerned with defining which user should be used
862 - not with actually setting this user up.
863 monitor [OPTIONS] NAME EXPRESSION
865 defines a MIB object to monitor. If the EXPRESSION condition
866 holds (see below), then this will trigger the corresponding
867 event, and either send a notification or apply a SET assignment
868 (or both). Note that the event will only be triggered once,
869 when the expression first matches. This monitor entry will not
870 fire again until the monitored condition first becomes false,
871 and then matches again. NAME is an administrative name for this
872 expression, and is used for indexing the mteTriggerTable (and
873 related tables).
874 EXPRESSION
876 There are three types of monitor expression supported by the
877 Event MIB - existence, boolean and threshold tests.
878 OID | !OID | !=OID
880 defines an existence(0) monitor test. A bare OID speci‐
881 fies a present(0) test, which will fire when (an instance
882 of) the monitored OID is created. An expression of the
883 form !OID specifies an absent(1) test, which will fire
884 when the monitored OID is delected. An expression of the
885 form !=OID specifies a changed(2) test, which will fire
886 whenever the monitored value(s) change.
887 OID OP VALUE
889 defines a boolean(1) monitor test. OP should be one of
890 the defined comparison operators (!=, ==, <, <=, >, >=)
891 and VALUE should be an integer value to compare against.
892 OID MIN MAX [DMIN DMAX]
894 defines a threshold(2) monitor test. MIN and MAX are
895 integer values, specifying lower and upper thresholds.
896 If the value of the monitored OID falls below the lower
897 threshold (MIN) or rises above the upper threshold (MAX),
898 then the monitor entry will trigger the corresponding
899 event.
900 Note that the rising threshold event will only be re-
902 armed when the monitored value falls below the lower
903 threshold (MIN). Similarly, the falling threshold event
904 will be re-armed by the upper threshold (MAX).
905 The optional parameters DMIN and DMAX configure a pair of
907 similar threshold tests, but working with the delta dif‐
908 ferences between successive sample values.
909 OPTIONS
911 There are various options to control the behaviour of the moni‐
912 tored expression. These include:
913 -D indicates that the expression should be evaluated using
915 delta differences between sample values (rather than the
916 values themselves).
917 -d OID
919 -di OID
921 specifies a discontinuity marker for validating delta
922 differences. A -di object instance will be used exactly
923 as given. A -d object will have the instance subidenti‐
924 fiers from the corresponding (wildcarded) expression
925 object appended. If the -I flag is specified, then there
926 is no difference between these two options.
927 This option also implies -D.
929 -e EVENT
931 specifies the event to be invoked when this monitor entry
932 is triggered. If this option is not given, the monitor
933 entry will generate one of the standard notifications
934 defined in the DISMAN-EVENT-MIB.
935 -I indicates that the monitored expression should be applied
937 to the specified OID as a single instance. By default,
938 the OID will be treated as a wildcarded object, and the
939 monitor expanded to cover all matching instances.
940 -i OID
942 -o OID define additional varbinds to be added to the notifica‐
944 tion payload when this monitor trigger fires. For a
945 wildcarded expression, the suffix of the matched instance
946 will be added to any OIDs specified using -o, while OIDs
947 specified using -i will be treated as exact instances.
948 If the -I flag is specified, then there is no difference
949 between these two options.
950 See strictDisman for details of the ordering of notifica‐
952 tion payloads.
953 -r FREQUENCY
955 monitors the given expression every FREQUENCY seconds.
956 By default, the expression will be evaluated every 600s
957 (10 minutes).
958 -S indicates that the monitor expression should not be eval‐
960 uated when the agent first starts up. The first evalua‐
961 tion will be done once the first repeat interval has
962 expired.
963 -s indicates that the monitor expression should be evaluated
965 when the agent first starts up. This is the default be‐
966 haviour.
967 Note: Notifications triggered by this initial evaluation
969 will be sent before the coldStart trap.
970 -u SECNAME
972 specifies a security name to use for scanning the local
973 host, instead of the default iquerySecName. Once again,
974 this user must be explicitly created and given suitable
975 access rights.
976 notificationEvent ENAME NOTIFICATION [-n] [-i OID | -o OID ]*
978 defines a notification event named ENAME. This can be triggered
979 from a given monitor entry by specifying the option -e ENAME
980 (see above). NOTIFICATION should be the OID of the NOTIFICA‐
981 TION-TYPE definition for the notification to be generated.
982 If the -n option is given, the notification payload will include
984 the standard varbinds as specified in the OBJECTS clause of the
985 notification MIB definition. This option must come after the
986 NOTIFICATION OID (and the relevant MIB file must be available
987 and loaded by the agent). Otherwise, these varbinds must be
988 listed explicitly (either here or in the corresponding monitor
989 directive).
990 The -i OID and -o OID options specify additional varbinds to be
992 appended to the notification payload, after the standard list.
993 If the monitor entry that triggered this event involved a wild‐
994 carded expression, the suffix of the matched instance will be
995 added to any OIDs specified using -o, while OIDs specified using
996 -i will be treated as exact instances. If the -I flag was spec‐
997 ified to the monitor directive, then there is no difference
998 between these two options.
999 setEvent ENAME [-I] OID = VALUE
1001 defines a set event named ENAME, assigning the (integer) VALUE
1002 to the specified OID. This can be triggered from a given moni‐
1003 tor entry by specifying the option -e ENAME (see above).
1004 If the monitor entry that triggered this event involved a wild‐
1006 carded expression, the suffix of the matched instance will nor‐
1007 mally be added to the OID. If the -I flag was specified to
1008 either of the monitor or setEvent directives, the specified OID
1009 will be regarded as an exact single instance.
1010 strictDisman yes
1012 The definition of SNMP notifications states that the varbinds
1013 defined in the OBJECT clause should come first (in the order
1014 specified), followed by any "extra" varbinds that the notifica‐
1015 tion generator feels might be useful. The most natural approach
1016 would be to associate these mandatory varbinds with the notifi‐
1017 cationEvent entry, and append any varbinds associated with the
1018 monitor entry that triggered the notification to the end of this
1019 list. This is the default behaviour of the Net-SNMP Event MIB
1020 implementation.
1021 Unfortunately, the DisMan Event MIB specifications actually
1023 state that the trigger-related varbinds should come first, fol‐
1024 lowed by the event-related ones. This directive can be used to
1025 restore this strictly-correct (but inappropriate) behaviour.
1026 Note: Strict DisMan ordering may result in generating invalid
1028 notifications payload lists if the notificationEvent -n
1029 flag is used together with monitor -o (or -i) varbind
1030 options.
1031 If no monitor entries specify payload varbinds, then the setting
1033 of this directive is irrelevant.
1034 linkUpDownNotifications yes
1036 will configure the Event MIB tables to monitor the ifTable for
1037 network interfaces being taken up or down, and triggering a
1038 linkUp or linkDown notification as appropriate.
1039 This is exactly equivalent to the configuration:
1041 notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
1043 notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
1044 monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
1046 monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
1047 defaultMonitors yes
1049 will configure the Event MIB tables to monitor the various UCD-
1050 SNMP-MIB tables for problems (as indicated by the appropriate
1051 xxErrFlag column objects).
1052 This is exactly equivalent to the configuration:
1054 monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
1056 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
1057 monitor -o extNames -o extOutput "extTable" extResult != 0
1058 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
1059 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
1060 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
1061 In both these latter cases, the snmpd.conf must also contain a iquery‐
1063 SecName directive, together with a corresponding createUser entry and
1064 suitable access control configuration.
1065 DisMan Schedule MIB
1067 The DisMan working group also produced a mechanism for scheduling par‐
1068 ticular actions (a specified SET assignment) at given times. This
1069 requires that the agent was built with support for the disman/schedule
1070 module (which is included as part of the default build configuration
1071 for the most recent distribution).
1072 There are three ways of specifying the scheduled action:
1074 repeat FREQUENCY OID = VALUE
1076 configures a SET assignment of the (integer) VALUE to the MIB
1077 instance OID, to be run every FREQUENCY seconds.
1078 cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1080 configures a SET assignment of the (integer) VALUE to the MIB
1081 instance OID, to be run at the times specified by the fields
1082 MINUTE to WEEKDAY. These follow the same pattern as the equiva‐
1083 lent crontab(5) fields.
1084 Note: These fields should be specified as a (comma-separated)
1086 list of numeric values. Named values for the MONTH and
1087 WEEKDAY fields are not supported, and neither are value
1088 ranges. A wildcard match can be specified as '*'.
1089 The DAY field can also accept negative values, to indicate days
1091 counting backwards from the end of the month.
1092 at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE
1094 configures a one-shot SET assignment, to be run at the first
1095 matching time as specified by the fields MINUTE to WEEKDAY. The
1096 interpretation of these fields is exactly the same as for the
1097 cron directive.
1098
1100 One of the first distinguishing features of the original UCD suite was
1101 the ability to extend the functionality of the agent - not just by
1102 recompiling with code for new MIB modules, but also by configuring the
1103 running agent to report additional information. There are a number of
1104 techniques to support this, including:
1105 · running external commands (exec, extend, pass)
1107 · loading new code dynamically (embedded perl, dlmod)
1109 · communicating with other agents (proxy, SMUX, AgentX)
1111 Arbitrary Extension Commands
1113 The earliest extension mechanism was the ability to run arbitrary com‐
1114 mands or shell scripts. Such commands do not need to be aware of SNMP
1115 operations, or conform to any particular behaviour - the MIB structures
1116 are designed to accommodate any form of command output. Use of this
1117 mechanism requires that the agent was built with support for the ucd-
1118 snmp/extensible and/or agent/extend modules (which are both included as
1119 part of the default build configuration).
1120 exec [MIBOID] NAME PROG ARGS
1122 sh [MIBOID] NAME PROG ARGS
1124 invoke the named PROG with arguments of ARGS. By default the
1125 exit status and first line of output from the command will be
1126 reported via the extTable, discarding any additional output.
1127 Note: Entries in this table appear in the order they are read
1129 from the configuration file. This means that adding new
1130 exec (or sh) directives and restarting the agent, may
1131 affect the indexing of other entries.
1132 The PROG argument for exec directives must be a full path to a
1134 real binary, as it is executed via the exec() system call. To
1135 invoke a shell script, use the sh directive instead.
1136 If MIBOID is specified, then the results will be rooted at this
1138 point in the OID tree, returning the exit statement as
1139 MIBOID.100.0 and the entire command output in a pseudo-table
1140 based at MIBNUM.101 - with one 'row' for each line of output.
1141 Note: The layout of this "relocatable" form of exec (or sh)
1143 output does not strictly form a valid MIB structure.
1144 This mechanism is being deprecated - please see the
1145 extend directive (described below) instead.
1146 In either case, the exit statement and output will be cached for
1148 30s after the initial query. This cache can be flushed by a SET
1149 request of the integer value 1 to the MIB instance version‐
1150 ClearCache.0.
1151 execfix NAME PROG ARGS
1153 registers a command that can be invoked on demand - typically to
1154 respond to or fix errors with the corresponding exec or sh
1155 entry. When the extErrFix instance for a given NAMEd entry is
1156 set to the integer value of 1, this command will be called.
1157 Note: This directive can only be used in combination with a
1159 corresponding exec or sh directive, which must be defined
1160 first. Attempting to define an unaccompanied execfix
1161 directive will fail.
1162 exec and sh extensions can only be configured via the snmpd.conf file.
1164 They cannot be set up via SNMP SET requests.
1165 extend [MIBOID] NAME PROG ARGS
1167 works in a similar manner to the exec directive, but with a num‐
1168 ber of improvements. The MIB tables (nsExtendConfigTable etc)
1169 are indexed by the NAME token, so are unaffected by the order in
1170 which entries are read from the configuration files. There are
1171 two result tables - one (nsExtendOutput1Table) containing the
1172 exit status, the first line and full output (as a single string)
1173 for each extend entry, and the other (nsExtendOutput2Table) con‐
1174 taining the complete output as a series of separate lines.
1175 If MIBOID is specified, then the configuration and result tables
1177 will be rooted at this point in the OID tree, but are otherwise
1178 structured in exactly the same way. This means that several sep‐
1179 arate extend directives can specify the same MIBOID root, with‐
1180 out conflicting.
1181 The exit status and output is cached for each entry individu‐
1183 ally, and can be cleared (and the caching behaviour configured)
1184 using the nsCacheTable.
1185 extendfix NAME PROG ARGS
1187 registers a command that can be invoked on demand, by setting
1188 the appropriate nsExtendRunType instance to the value run-com‐
1189 mand(3). Unlike the equivalent execfix, this directive does not
1190 need to be paired with a corresponding extend entry, and can
1191 appear on its own.
1192 Both extend and extendfix directives can be configured dynamically,
1194 using SNMP SET requests to the NET-SNMP-EXTEND-MIB.
1195 MIB-Specific Extension Commands
1197 The first group of extension directives invoke arbitrary commands, and
1198 rely on the MIB structure (and management applications) having the
1199 flexibility to accommodate and interpret the output. This is a conve‐
1200 nient way to make information available quickly and simply, but is of
1201 no use when implementing specific MIB objects, where the extension must
1202 conform to the structure of the MIB (rather than vice versa). The
1203 remaining extension mechanisms are all concerned with such MIB-specific
1204 situations - starting with "pass-through" scripts. Use of this mecha‐
1205 nism requires that the agent was built with support for the ucd-
1206 snmp/pass and ucd-snmp/pass_persist modules (which are both included as
1207 part of the default build configuration).
1208 pass [-p priority] MIBOID PROG
1210 will pass control of the subtree rooted at MIBOID to the speci‐
1211 fied PROG command. GET and GETNEXT requests for OIDs within
1212 this tree will trigger this command, called as:
1213 PROG -g OID
1215 PROG -n OID
1217 respectively, where OID is the requested OID. The PROG command
1219 should return the response varbind as three separate lines
1220 printed to stdout - the first line should be the OID of the
1221 returned value, the second should be its TYPE (one of the text
1222 strings integer, gauge, counter, timeticks, ipaddress, objectid,
1223 or string ), and the third should be the value itself.
1224 If the command cannot return an appropriate varbind - e.g the
1226 specified OID did not correspond to a valid instance for a GET
1227 request, or there were no following instances for a GETNEXT -
1228 then it should exit without producing any output. This will
1229 result in an SNMP noSuchName error, or a noSuchInstance excep‐
1230 tion.
1231 Note: The SMIv2 type counter64 and SNMPv2 noSuchObject
1233 exception are not supported.
1234 A SET request will result in the command being called as:
1236 PROG -s OID TYPE VALUE
1238 where TYPE is one of the tokens listed above, indicating the
1240 type of the value passed as the third parameter.
1241 If the assignment is successful, the PROG command should exit
1243 without producing any output. Errors should be indicated by
1244 writing one of the strings not-writable, or wrong-type to std‐
1245 out, and the agent will generate the appropriate error response.
1246 Note: The other SNMPv2 errors are not supported.
1248 In either case, the command should exit once it has finished
1250 processing. Each request (and each varbind within a single
1251 request) will trigger a separate invocation of the command.
1252 The default registration priority is 127. This can be changed
1254 by supplying the optional -p flag, with lower priority registra‐
1255 tions being used in preference to higher priority values.
1256 pass_persist [-p priority] MIBOID PROG
1258 will also pass control of the subtree rooted at MIBOID to the
1259 specified PROG command. However this command will continue to
1260 run after the initial request has been answered, so subsequent
1261 requests can be processed without the startup overheads.
1262 Upon initialization, PROG will be passed the string "PING\n" on
1264 stdin, and should respond by printing "PONG\n" to stdout.
1265 For GET and GETNEXT requests, PROG will be passed two lines on
1267 stdin, the command (get or getnext) and the requested OID. It
1268 should respond by printing three lines to stdout - the OID for
1269 the result varbind, the TYPE and the VALUE itself - exactly as
1270 for the pass directive above. If the command cannot return an
1271 appropriate varbind, it should print print "NONE\n" to stdout
1272 (but continue running).
1273 For SET requests, PROG will be passed three lines on stdin, the
1275 command (set) and the requested OID, followed by the type and
1276 value (both on the same line). If the assignment is successful,
1277 the command should print "DONE\n" to stdout. Errors should be
1278 indicated by writing one of the strings not-writable, or wrong-
1279 type to stdout, and the agent will generate the appropriate
1280 error response. In either case, the command should continue
1281 running.
1282 The registration priority can be changed using the optional -p
1284 flag, just as for the pass directive.
1285 pass and pass_persist extensions can only be configured via the
1287 snmpd.conf file. They cannot be set up via SNMP SET requests.
1288 Embedded Perl Support
1290 Programs using the previous extension mechanisms can be written in any
1291 convenient programming language - including perl, which is a common
1292 choice for pass-through extensions in particular. However the Net-SNMP
1293 agent also includes support for embedded perl technology (similar to
1294 mod_perl for the Apache web server). This allows the agent to inter‐
1295 pret perl scripts directly, thus avoiding the overhead of spawning pro‐
1296 cesses and initializing the perl system when a request is received.
1297 Use of this mechanism requires that the agent was built with support
1299 for the embedded perl mechanism, which is not part of the default build
1300 environment. It must be explicitly included by specifying the
1301 '--enable-embedded-perl' option to the configure script when the pack‐
1302 age is first built.
1303 If enabled, the following directives will be recognised:
1305 disablePerl true
1307 will turn off embedded perl support entirely (e.g. if there are
1308 problems with the perl installation).
1309 perlInitFile FILE
1311 loads the specified initialisation file (if present) immediately
1312 before the first perl directive is parsed. If not explicitly
1313 specified, the agent will look for the default initialisation
1314 file /usr/share/snmp/snmp_perl.pl.
1315 The default initialisation file creates an instance of a Net‐
1317 SNMP::agent object - a variable $agent which can be used to reg‐
1318 ister perl-based MIB handler routines.
1319 perl EXPRESSION
1321 evaluates the given expression. This would typically register a
1322 handler routine to be called when a section of the OID tree was
1323 requested:
1324 perl use Data::Dumper;
1325 perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
1326 perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
1327 This expression could also source an external file:
1329 perl 'do /path/to/file.pl';
1330 or perform any other perl-based processing that might be
1332 required.
1333 Dynamically Loadable Modules
1335 Most of the MIBs supported by the Net-SNMP agent are implemented as C
1336 code modules, which were compiled and linked into the agent libraries
1337 when the suite was first built. Such implementation modules can also
1338 be compiled independently and loaded into the running agent once it has
1339 started. Use of this mechanism requires that the agent was built with
1340 support for the ucd-snmp/dlmod module (which is included as part of the
1341 default build configuration).
1342 dlmod NAME PATH
1344 will load the shared object module from the file PATH (an abso‐
1345 lute filename), and call the initialisation routine init_NAME.
1346 Note: If the specified PATH is not a fully qualified filename,
1348 it will be interpreted relative to /usr/lib64/snmp/dlmod,
1349 and .so will be appended to the filename.
1350 This functionality can also be configured using SNMP SET requests to
1352 the UCD-DLMOD-MIB.
1353 Proxy Support
1355 Another mechanism for extending the functionality of the agent is to
1356 pass selected requests (or selected varbinds) to another SNMP agent,
1357 which can be running on the same host (presumably listening on a dif‐
1358 ferent port), or on a remote system. This can be viewed either as the
1359 main agent delegating requests to the remote one, or acting as a proxy
1360 for it. Use of this mechanism requires that the agent was built with
1361 support for the ucd-snmp/proxy module (which is included as part of the
1362 default build configuration).
1363 proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]
1365 will pass any incoming requests under OID to the agent listening
1366 on the port specified by the transport address HOST. See the
1367 section LISTENING ADDRESSES in the snmpd(8) manual page for more
1368 information about the format of listening addresses.
1369 Note: To proxy the entire MIB tree, use the OID .1.3 (not the
1371 top-level .1)
1372 The SNMPCMD_ARGS should provide sufficient version and administrative
1374 information to generate a valid SNMP request (see snmpcmd(1)).
1375 Note: The proxied request will not use the administrative settings
1377 from the original request.
1378 If a CONTEXTNAME is specified, this will register the proxy delegation
1380 within the named context in the local agent. Defining multiple proxy
1381 directives for the same OID but different contexts can be used to query
1382 several remote agents through a single proxy, by specifying the appro‐
1383 priate SNMPv3 context in the incoming request (or using suitable con‐
1384 figured community strings - see the com2sec directive).
1385 Specifying the REMOID parameter will map the local MIB tree rooted at
1387 OID to an equivalent subtree rooted at REMOID on the remote agent.
1388 SMUX Sub-Agents
1390 The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1391 with SMUX-based subagents (such as gated, zebra or quagga). Use of
1392 this mechanism requires that the agent was built with support for the
1393 smux module, which is not part of the default build environment, and
1394 must be explicitly included by specifying the '--with-mib-modules=smux'
1395 option to the configure script when the package is first built.
1396 Note: This extension protocol has been officially deprecated in
1398 favour of AgentX (see below).
1399 smuxpeer OID PASS
1401 will register a subtree for SMUX-based processing, to be authen‐
1402 ticated using the password PASS. If a subagent (or "peer") con‐
1403 nects to the agent and registers this subtree then requests for
1404 OIDs within it will be passed to that SMUX subagent for process‐
1405 ing.
1406 A suitable entry for an OSPF routing daemon (such as gated,
1408 zebra or quagga) might be something like
1409 smuxpeer .1.3.6.1.2.1.14 ospf_pass
1410 smuxsocket [<transport-specifier>:]<transport-address>[,...]
1412 defines the address for SMUX peers to communicate with the Net-
1413 SNMP agent. The default is to listen on TCP port 199 on all
1414 IPv4 interfaces, unless the package has been configured with
1415 "--enable-local-smux" at build time, which causes it to only
1416 listen on tcp:127.0.0.1:199 by default. See the section LISTEN‐
1417 ING ADDRESSES in the snmpd(8) manual page for more information
1418 about the format of addresses.
1419 Note the Net-SNMP agent will only operate as a SMUX master agent. It
1421 does not support acting in a SMUX subagent role.
1422 AgentX Sub-Agents
1424 The Net-SNMP agent supports the AgentX protocol (RFC 2741) in both mas‐
1425 ter and subagent roles. Use of this mechanism requires that the agent
1426 was built with support for the agentx module (which is included as part
1427 of the default build configuration), and also that this support is
1428 explicitly enabled (e.g. via the snmpd.conf file).
1429 There are two directives specifically relevant to running as an AgentX
1431 master agent:
1432 master agentx
1434 will enable the AgentX functionality and cause the agent to
1435 start listening for incoming AgentX registrations. This can
1436 also be activated by specifying the '-x' command-line option (to
1437 specify an alternative listening socket).
1438 agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]
1440 Defines the permissions and ownership of the AgentX Unix Domain
1441 socket, and the parent directories of this socket. SOCKPERMS
1442 and DIRPERMS must be octal digits (see chmod(1) ). By default
1443 this socket will only be accessible to subagents which have the
1444 same userid as the agent.
1445 There is one directive specifically relevant to running as an AgentX
1447 sub-agent:
1448 agentXPingInterval NUM
1450 will make the subagent try and reconnect every NUM seconds to
1451 the master if it ever becomes (or starts) disconnected.
1452 The remaining directives are relevant to both AgentX master and sub-
1454 agents:
1455 agentXSocket [<transport-specifier>:]<transport-address>[,...]
1457 defines the address the master agent listens at, or the subagent
1458 should connect to. The default is the Unix Domain socket
1459 "/var/agentx/master". Another common alternative is tcp:local‐
1460 host:705. See the section LISTENING ADDRESSES in the snmpd(8)
1461 manual page for more information about the format of addresses.
1462 Note: Specifying an AgentX socket does not automatically enable
1464 AgentX functionality (unlike the '-x' command-line
1465 option).
1466 agentXTimeout NUM
1468 defines the timeout period (NUM seconds) for an AgentX request.
1469 Default is 1 second.
1470 agentXRetries NUM
1472 defines the number of retries for an AgentX request. Default is
1473 5 retries.
1474 net-snmp ships with both C and Perl APIs to develop your own AgentX
1476 subagent.
1477
1479 override [-rw] OID TYPE VALUE
1480 This directive allows you to override a particular OID with a
1481 different value (and possibly a different type of value). The
1482 -rw flag will allow snmp SETs to modify it's value as well.
1483 (note that if you're overriding original functionality, that
1484 functionality will be entirely lost. Thus SETS will do nothing
1485 more than modify the internal overridden value and will not per‐
1486 form any of the original functionality intended to be provided
1487 by the MIB object. It's an emulation only.) An example:
1488 override sysDescr.0 octet_str "my own sysDescr"
1490 That line will set the sysDescr.0 value to "my own sysDescr" as
1492 well as make it modifiable with SNMP SETs as well (which is
1493 actually illegal according to the MIB specifications).
1494 Note that care must be taken when using this. For example, if
1496 you try to override a property of the 3rd interface in the
1497 ifTable with a new value and later the numbering within the
1498 ifTable changes it's index ordering you'll end up with problems
1499 and your modified value won't appear in the right place in the
1500 table.
1501 Valid TYPEs are: integer, uinteger, octet_str, object_id,
1503 counter, null (for gauges, use "uinteger"; for bit strings, use
1504 "octet_str"). Note that setting an object to "null" effectively
1505 delete's it as being accessible. No VALUE needs to be given if
1506 the object type is null.
1507 More types should be available in the future.
1509 If you're trying to figure out aspects of the various mib modules (pos‐
1511 sibly some that you've added yourself), the following may help you spit
1512 out some useful debugging information. First off, please read the
1513 snmpd manual page on the -D flag. Then the following configuration
1514 snmpd.conf token, combined with the -D flag, can produce useful output:
1515 injectHandler HANDLER modulename
1517 This will insert new handlers into the section of the mib tree
1518 referenced by "modulename". The types of handlers available for
1519 insertion are:
1520 stash_cache
1522 Caches information returned from the lower level. This
1523 greatly help the performance of the agent, at the cost of
1524 caching the data such that its no longer "live" for 30
1525 seconds (in this future, this will be configurable).
1526 Note that this means snmpd will use more memory as well
1527 while the information is cached. Currently this only
1528 works for handlers registered using the table_iterator
1529 support, which is only a few mib tables. To use it, you
1530 need to make sure to install it before the table_iterator
1531 point in the chain, so to do this:
1532 injectHandler stash_cache NAME ta‐
1534 ble_iterator
1535 If you want a table to play with, try walking the nsMod‐
1537 uleTable with and without this injected.
1538 debug Prints out lots of debugging information when the
1541 -Dhelper:debug flag is passed to the snmpd application.
1542 read_only
1545 Forces turning off write support for the given module.
1546 serialize
1549 If a module is failing to handle multiple requests prop‐
1550 erly (using the new 5.0 module API), this will force the
1551 module to only receive one request at a time.
1552 bulk_to_next
1555 If a module registers to handle getbulk support, but for
1556 some reason is failing to implement it properly, this
1557 module will convert all getbulk requests to getnext
1558 requests before the final module receives it.
1559 dontLogTCPWrappersConnects
1561 If the snmpd was compiled with TCP Wrapper support, it logs
1562 every connection made to the agent. This setting disables the
1563 log messages for accepted connections. Denied connections will
1564 still be logged.
1565 Figuring out module names
1567 To figure out which modules you can inject things into, run snm‐
1568 pwalk on the nsModuleTable which will give a list of all named
1569 modules registered within the agent.
1570 Internal Data tables
1572 table NAME
1573 add_row NAME INDEX(ES) VALUE(S)
1575
1577 o The Net-SNMP agent can be instructed to re-read the various con‐
1578 figuration files, either via an snmpset assignment of integer(1)
1579 to UCD-SNMP-MIB::versionUpdateConfig.0
1580 (.1.3.6.1.4.1.2021.100.11.0), or by sending a kill -HUP signal
1581 to the agent process.
1582 o All directives listed with a value of "yes" actually accept a
1584 range of boolean values. These will accept any of 1, yes or
1585 true to enable the corresponding behaviour, or any of 0, no or
1586 false to disable it. The default in each case is for the fea‐
1587 ture to be turned off, so these directives are typically only
1588 used to enable the appropriate behaviour.
1589
1591 See the EXAMPLE.CONF file in the top level source directory for a more
1592 detailed example of how the above information is used in real examples.
1593
1595 /etc/snmp/snmpd.conf
1596
1598 snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAM‐
1599 PLE.conf, read_config(3).
16004th Berkeley Distribution 08 Feb 2002 SNMPD.CONF(5)