1 .TH SNMPD.CONF 5 "28 Feb 2003" VVERSIONINFO "Net-SNMP"
4 SYSCONFDIR/snmp/snmpd.conf - configuration file for the Net-SNMP SNMP agent.
7 is the configuration file which defines how the Net-SNMP SNMP agent
8 operates. These files may contain any of the directives found in the
10 section below. This file is not required for the agent to
11 operate and respond to requests.
13 First, make sure you have read the
15 manual page that describes how the Net-SNMP configuration files
16 operate, where they are located and how they all work together.
18 Also, you might consider looking into the
20 application (perl script) which can help you build an snmpd.conf file
21 by prompting you for information. You should try it. Really. Go
22 ahead. Right now. Run:
24 .IP "snmpconf -g basic_setup"
27 to get you started. See the
29 manual page for more information.
32 The Net-SNMP SNMP agent reports much of its information through
33 queries to the EXTENSIBLEDOTMIB section of the MIB tree. Every MIB in
34 this section has the following table entries in it.
35 .IP ".MIBINDEX -- index"
36 This is the table's index numbers for each of the DIRECTIVES listed below.
37 .IP ".ERRORNAME -- name"
38 The name of the given table entry. This should be unique, but is not
40 .IP ".ERRORFLAG -- errorFlag"
41 This is a flag returning either the integer value 1 or 0 if an error
42 is detected for this table entry.
43 .IP ".ERRORMSG -- errorMsg"
44 This is a DISPLAY-STRING describing any error triggering the errorFlag above.
45 .IP ".ERRORFIX -- errorFix"
46 If this entry is set to the integer value of 1 AND the errorFlag
47 defined above is indeed a 1, a program or script will get executed
48 with the table entry name from above as the argument. The program to
49 be executed is configured in the config.h file at compile time.
53 .IP "proc NAME MAX MIN"
55 Checks to see if processes called NAME are running on the agent
56 machine. An error flag (1) and a description message are then passed
57 to the EXTENSIBLEDOTMIB.PROCMIBNUM.1.ERRORFLAG and
58 EXTENSIBLEDOTMIB.PROCMIBNUM.1.ERRORMSG MIB columns (respectively) if
59 the NAME'd program is not found in the process table as reported by
62 If MAX and MIN are not specified, MAX is assumed to be
64 and MIN is assumed to be 1.
66 If MAX is specified but MIN is not specified, MIN is assumed to be 0.
67 .IP "procfix NAME PROG ARGS"
68 This registers a command that knows how to fix errors with the given
69 process NAME. When EXTENSIBLEDOTMIB.PROCMIBNUM.1.ERRORFIX for a given
70 NAMEd program is set to the integer value of 1, this command will be
71 called. It defaults to a compiled value set using the PROCFIXCMD
72 definition in the config.h file.
73 .IP "exec NAME PROG ARGS"
74 .IP "exec MIBNUM NAME PROG ARGS"
76 If MIBNUM is not specified, the agent executes the named PROG with
77 arguments of ARGS and returns the exit status and the first line of
78 the STDOUT output of the PROG program to queries of the
79 EXTENSIBLEDOTMIB.SHELLMIBNUM.1.ERRORFLAG and
80 EXTENSIBLEDOTMIB.SHELLMIBNUM.1.ERRORMSG mib columns (respectively). All
81 STDOUT output beyond the first line is silently truncated.
83 If MIBNUM is specified, it acts as above but returns the exit status
84 to MIBNUM.ERRORFLAG.0 and the entire STDOUT output to the table
85 MIBNUM.ERRORMSG in a MIB table. In this case, the MIBNUM.ERRORMSG mib
86 contains the entire STDOUT output, one MIB table entry per line of
87 output (ie, the first line is output as MIBNUM.ERRORMSG.1, the second
88 at MIBNUM.ERRORMSG.2, etc...).
91 The MIBNUM must be specified in dotted-integer notation and can
92 not be specified as ".iso.org.dod.internet..." (should instead
95 The agent caches the exit status and STDOUT of the executed program
96 for 30 seconds after the initial query. This is to increase speed and
97 maintain consistency of information for consecutive table queries.
98 The cache can be flushed by a snmp-set request of integer(1) to
99 EXTENSIBLEDOTMIB.VERSIONMIBNUM.VERCLEARCACHE.
101 .IP "execfix NAME PROG ARGS"
102 This registers a command that knows how to fix errors with the given
103 exec or sh NAME. When EXTENSIBLEDOTMIB.SHELLMIBNUM.1.ERRORFIX for a
104 given NAMEd entry is set to the integer value of 1, this command will
105 be called. It defaults to a compiled value set using the EXECFIXCMD
106 definition in the config.h file.
108 .IP "disk PATH [ MINSPACE | MINPERCENT% ]"
110 Checks the named disks mounted at PATH for available disk space. If
111 the disk space is less than MINSPACE (kB) if specified or less than
112 MINPERCENT (%) if a % sign is specified, or DEFDISKMINIMUMSPACE (kB)
113 if not specified, the associated entry in the
114 EXTENSIBLEDOTMIB.DISKMIBNUM.1.ERRORFLAG MIB table will be set to (1) and
115 a descriptive error message will be returned to queries of
116 EXTENSIBLEDOTMIB.DISKMIBNUM.1.ERRORMSG.
119 .IP "load MAX1 MAX5 MAX15"
121 Checks the load average of the machine and returns an error flag (1),
122 and an text-string error message
123 to queries of EXTENSIBLEDOTMIB.LOADAVEMIBNUM.1.ERRORFLAG and
124 EXTENSIBLEDOTMIB.LOADAVEMIBNUM.1.ERRORMSG (respectively) when the
125 1-minute, 5-minute, or 15-minute averages exceed the associated
126 maximum values. If any of the MAX1, MAX5, or MAX15 values are
127 unspecified, they default to a value of DEFMAXLOADAVE.
128 .IP "file FILE [MAXSIZE]"
129 Monitors file sizes and makes sure they don't grow beyond a certain
130 size (in kilobytes). MAXSIZE defaults to infinite if not specified,
131 and only monitors the size without reporting errors about it.
132 A maximum of 20 files can be monitored.
135 Any errors in obtaining the above information are reported via the
136 EXTENSIBLEDOTMIB.ERRORMIBNUM.1.ERRORFLAG flag and the
137 EXTENSIBLEDOTMIB.ERRORMIBNUM.1.ERRORMSG text-string description.
138 .SH AGENTX SUB-AGENTS
139 To enable AgentX support in the SNMP master agent, put the following
140 line in your snmpd.conf file:
142 See README.agentx for further details.
143 .IP "AgentXSocket addr"
144 This defines the address the master agent listens at.
145 The default is /var/agentx/master. Another possibility is localhost:705
146 .IP "AgentXTimeout addr"
147 Defines the timeout period for an AgentX request.
149 .IP "AgentXRetries addr"
150 Defines the number of retries for an AgentX request.
151 Default is 5 retries.
153 To enable and SMUX based sub-agent, such as
158 .IP "smuxpeer OID PASS"
161 a sensible entry might be
162 .I smuxpeer .1.3.6.1.4.1.4.1.3 secret
163 .SH DYNAMICALLY LOADABLE MODULES
164 If the agent is built with support for the UCD-DLMOD-MIB it is capable
165 of loading agent MIB modules dynamically at startup through
166 the \fIdlmod\fR directive and during runtime through use of the UCD-DLMOD-MIB.
167 The following directive loads the shared object module file PATH which
168 uses the module name prefix NAME.
169 .IP "dlmod NAME PATH"
173 supports the View-Based Access Control Model (VACM) as defined in RFC
174 2575. To this end, it recognizes the following keywords in the
175 configuration file: \fIcom2sec\fR, \fIgroup\fR, \fIaccess\fR, and
176 \fIview\fR as well as some easier-to-use wrapper directives:
177 \fIrocommunity\fR, \fIrwcommunity\fR, \fIrouser\fR, \fIrwuser\fR. If
178 IPv6 support has been enabled, the \fIrocommunity6\fR and
179 \fIrwcommunity6\fR tokens will also be available. This section
180 defines how to configure the snmpd program to accept various types and
182 .IP "rouser USER [noauth|auth|priv] [OID]"
183 .IP "rwuser USER [noauth|auth|priv] [OID]"
184 Creates a SNMPv3 USM user in the VACM access configuration tables. It
185 is more efficient (and powerful) to use the combined \fIgroup\fR,
186 \fIaccess\fR, and \fIview\fR directives instead, but these wrapper
187 directives are much simpler.
189 The minimum level of authentication and privacy the user must use is
190 specified by the first token (which defaults to "auth"). The OID
191 parameter restricts access for that user to everything below the given
193 .IP "rocommunity COMMUNITY [SOURCE] [OID]"
194 .IP "rwcommunity COMMUNITY [SOURCE] [OID]"
195 These create read-only and read-write communities that can be used to
196 access the agent. They are a quick wrapper around the more complex
197 and powerful \fIcom2sec\fR, \fIgroup\fR, \fIaccess\fR, and \fIview\fR
198 directive lines. They are not as efficient either, as groups aren't
199 created so the tables are possibly larger. In other words: don't use
200 these if you have complex situations to set up. If your setup is
201 simple or you don't mind a small performance hit, use these
204 The format of the SOURCE is token is described in the \fIcom2sec\fR
205 directive section below. The OID token restricts access for that
206 community to everything below that given OID.
207 .IP "rocommunity6 COMMUNITY [SOURCE] [OID]"
208 .IP "rwcommunity6 COMMUNITY [SOURCE] [OID]"
209 They are the alternative directives to the \fIrocommunity\fR,
210 \fIrwcommunity\fR for the transport domain UDPIPv6. They are only
211 valid in specifing \fIUDPIPv6\fR as transport domain.
213 The format of the SOURCE is token is described in the \fIcom2sec6\fR
214 directive section below. The OID token restricts access for that
215 community to everything below that given OID.
216 .IP "com2sec NAME SOURCE COMMUNITY"
217 This directive specifies the mapping from a source/community pair to
218 a security name. SOURCE can be a hostname, a subnet, or the word
220 A subnet can be specified as IP/MASK or IP/BITS.
221 The first source/community combination that matches the incoming packet
223 .IP "com2sec6 NAME SOURCE COMMUNITY"
224 This directive is the IPv6 version of \fIcom2sec\fR.
225 A subnet can be specified as IPv6/IPv6MASK or IPv6/BITS.
226 It is only valid in specifing \fIUDPIPv6\fR as transport domain.
227 .IP "group NAME MODEL SECURITY"
228 This directive defines the mapping from securitymodel/securityname to group.
229 MODEL is one of \fIv1\fR, \fIv2c\fR, or \fIusm\fR.
230 .IP "access NAME CONTEXT MODEL LEVEL PREFX READ WRITE NOTIFY"
231 The access directive maps from group/security model/security level to
233 MODEL is one of \fIany\fR, \fIv1\fR, \fIv2c\fR, or \fIusm\fR.
234 LEVEL is one of \fInoauth\fR, \fIauth\fR, or \fIpriv\fR.
235 PREFX specifies how CONTEXT should be matched against the context of
236 the incoming pdu, either \fIexact\fR or \fIprefix\fR.
237 READ, WRITE and NOTIFY specifies the view to be used for the corresponding
239 For v1 or v2c access, LEVEL will be noauth, and CONTEXT will be empty.
240 .IP "view NAME TYPE SUBTREE [MASK]"
241 This defines the named view. TYPE is either \fIincluded\fR or \fIexcluded\fR.
242 MASK is a list of hex octets, separated by '.' or ':'. The MASK
243 defaults to "ff" if not specified.
245 The reason for the mask is, that it allows you to control access to
246 one row in a table, in a relatively simple way. As an example, as an ISP
247 you might consider giving each customer access to his or her own interface:
250 view cust1 included interfaces.ifTable.ifEntry.ifIndex.1 ff.a0
251 view cust2 included interfaces.ifTable.ifEntry.ifIndex.2 ff.a0
253 (interfaces.ifTable.ifEntry.ifIndex.1 == .1.3.6.1.2.1.2.2.1.1.1,
254 ff.a0 == 11111111.10100000. which nicely covers up and including
255 the row index, but lets the user vary the field of the row)
258 # sec.name source community
259 com2sec local localhost private
260 com2sec mynet 10.10.10.0/24 public
261 com2sec public default public
262 com2sec6 mynet fec0::/64 public
265 group mygroup v1 mynet
266 group mygroup v2c mynet
267 group mygroup usm mynet
269 group local v2c local
270 group local usm local
271 group public v1 public
272 group public v2c public
273 group public usm public
275 # incl/excl subtree mask
276 view all included .1 80
277 view system included system fe
278 view mib2 included .iso.org.dod.internet.mgmt.mib-2 fc
280 # context sec.model sec.level prefix read write notify
281 access mygroup "" any noauth exact mib2 none none
282 access public "" any noauth exact system none none
283 access local "" any noauth exact all all all
284 .IP "Default VACM model"
285 The default configuration of the agent, as shipped, is functionally
286 equivalent to the following entries:
288 com2sec public default public
289 group public v1 public
290 group public v2c public
291 group public usm public
293 access public "" any noauth exact all none none
294 .SH SNMPv3 CONFIGURATION
296 .IP "engineID STRING"
297 The snmpd agent needs to be configured with an engineID to be able to
298 respond to SNMPv3 messages. With this configuration file line, the
299 engineID will be configured from STRING. The default value of the
300 engineID is configured with the first IP address found for the
301 hostname of the machine.
302 .IP "createUser username (MD5|SHA) authpassphrase [DES] [privpassphrase]"
304 MD5 and SHA are the authentication types to use, but you must have
305 built the package with openssl installed in order to use SHA. The
306 only privacy protocol currently supported is DES. If the privacy
307 passphrase is not specified, it is assumed to be the same as the
308 authentication passphrase. Note that the users created will be
309 useless unless they are also added to the VACM access control tables
312 Warning: the minimum pass phrase length is 8 characters.
314 SNMPv3 users can be created at runtime using the
318 Instead of figuring out how to use this directive and where to put it
319 (see below), just run "net-snmp-config --create-snmpv3-user" instead,
320 which will add one of these lines to the right place.
322 This directive should be placed into the
323 PERSISTENT_DIRECTORY/snmpd.conf file instead of the other normal
324 locations. The reason is that the information is read from the file
325 and then the line is removed (eliminating the storage of the master
326 password for that user) and replaced with the key that is derived from
327 it. This key is a localized key, so that if it is stolen it can not
328 be used to access other agents. If the password is stolen, however,
331 .SH SETTING SYSTEM INFORMATION
332 .IP "syslocation STRING"
333 .IP "syscontact STRING"
335 Sets the system location, system contact or system name for the agent.
336 This information is reported in the 'system' group the mibII tree.
337 Ordinarily these objects (sysLocation.0, sysContact.0 and sysName.0)
338 are read-write. However, specifying the value for one of these
339 objects by giving the appropriate token makes the corresponding object
340 read-only, and attempts to set the value of the object will result in
341 a notWritable error response.
342 .IP "sysservices NUMBER"
343 Sets the value of the system.sysServices.0 object.
344 For a host, a good value is 72.
345 .IP "sysdescr STRING"
346 .IP "sysobjectid OID"
347 Sets the system description or object ID for the agent.
348 Although these values are not SNMP-writable, it is conceivable
349 that a network administrator may wish to configure them to something
350 other than the default values.
351 .IP "agentaddress [<transport-specifier>:]<transport-address>[,...]"
352 Makes the agent list on the specified comma-separated list of
353 listening addresses instead of the default behaviour, which is to
354 listen on UDP port 161 on all IPv4 interfaces. See the section
355 .B LISTENING ADDRESSES
358 manual page for more information about the format of listening
359 addresses. For example, specifying
360 .I "agentaddress 161,tcp:161,localhost:9161"
361 will make the agent listen on UDP port 161 on all IPv4 interfaces, TCP
362 port 161 on all IPv4 interfaces and UDP port 9161 only on the interface
363 associated with the localhost address.
364 .IP "agentgroup groupid"
365 Change to this gid after opening port. The groupid may refer to a group
366 by name or a number if the group number starts with '#'. For example,
369 will cause the agent to run as the snmp group or
371 will cause the agent to run as the group with groupid 10.
373 Change to this uid after opening port. The userid may refer to a user
374 by name or a number if the user number starts with '#'. For example,
377 will cause the agent to run as the snmp user or
379 will cause the agent to run as the user with userid 10.
380 .IP "interface NAME TYPE SPEED"
381 For interfaces where the agent fails to guess correctly on the type and
382 speed, this directive can supply additional information.
383 TYPE is a type value as given in the IANAifType-MIB.
384 .IP "ignoredisk STRING"
385 When scanning for available disk devices the agent might block in trying
386 to open all possible disk devices. This might lead to a timeout when
387 walking the device tree. Sometimes the next walk will run without timeout,
388 sometimes it will timeout every time you try it.
390 If you experience such behaviour you might add this directive and give all
391 device names not to be checked (i.e. opened). You might have more than one
392 such directive in your configuration file stating all devices not to be
393 opened. You might also specify those devices using wildcards similar to
394 the syntax you can use in a bourne shell (see examples below).
397 For a list of devices scanned for every system please consult the sources
398 (host/hr_disk.c) and check for the Add_HR_Disk_entry() calls relevant for
403 ignoredisk /dev/rdsk/c0t2d0
405 This directive prevents the device /dev/rdsk/c0t2d0 from being scanned.
407 ignoredisk /dev/rdsk/c0t[!6]d0
409 This directive prevents all devices /dev/rdsk/c0tXd0 except .../c0t6d0
410 from being scanned. For most systems similar is the following directive:
412 ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0
414 ignoredisk /dev/rdsk/c1*
416 This directive prevents all devices whose device names start with /dev/rdsk/c1
419 ignoredisk /dev/rdsk/c?t0d0
421 This directive prevents all devices /dev/rdsk/cXt0d0 ('X' might be any char)
424 You might use more than one such wildcard expression in any such directive.
425 .IP "storageUseNFS NUMBER"
426 Setting storageUseNFS to 1 causes all NFS and NFS-like file systems to be
427 marked as 'Network Disks' in the hrStorageTable. This is according to RFC 2790.
428 Not setting storageUseNFS or setting it to 2 causes NFS and NFS-like file
429 systems to be marked as 'Fixed Disks' as it has been in previous versions of
430 the ucd-snmp SNMP agent.
431 .IP "authtrapenable NUMBER"
432 Setting authtrapenable to 1 enables generation of authentication failure
433 traps. The default value is disabled(2). Ordinarily the corresponding
434 object (snmpEnableAuthenTraps.0) is read-write, but setting its value
435 via this token makes the object read-only, and attempts to set the
436 value of the object will result in a notWritable error response.
437 .IP "override OID TYPE VALUE"
438 This directive allows you to override a particular OID with a
439 different value (and possibly a different type of value).
440 .\" The -rw flag will allow snmp SETs to modify it's value as well.
443 override sysDescr.0 octet_str "my own sysDescr"
445 That line will set the sysDescr.0 value to "my own sysDescr" as well
446 as make it modifiable with SNMP SETs as well (which is actually
447 illegal according to the MIB specifications).
449 Note that care must be taken when using this. For example, if you try
450 to override a property of the 3rd interface in the ifTable with a new
451 value and later the numbering within the ifTable changes it's index
452 ordering you'll end up with problems and your modified value won't
453 appear in the right place in the table.
455 Valid TYPEs are: integer, uinteger, octet_str, bit_str, object_id,
456 counter, gauge, null. Note that setting an object to "null"
457 effectively delete's it as being accessible. No VALUE needs to be
458 given if the object type is null.
460 More types should be available in the future, as well as writable
462 .SH "SETTING UP TRAP AND/OR INFORM DESTINATIONS"
463 .IP "trapcommunity STRING"
464 This defines the default community string to be used when sending traps.
465 Note that this command must be used prior to any of the following three
466 commands that are intended use this community string.
467 .IP "trapsink HOST [COMMUNITY [PORT]]"
468 .IP "trap2sink HOST [COMMUNITY [PORT]]"
469 .IP "informsink HOST [COMMUNITY [PORT]]"
470 These commands define
471 the hosts to receive traps (and/or inform notifications). The
472 daemon sends a Cold Start trap when it starts up. If enabled, it also sends
473 traps on authentication failures. Multiple \fItrapsink\fR, \fItrap2sink\fR
474 and \fIinformsink\fR lines may be specified to specify multiple destinations.
475 Use \fItrap2sink\fR to send SNMPv2 traps and \fIinformsink\fR to send
476 inform notifications.
477 If COMMUNITY is not specified, the string from a preceding \fItrapcommunity\fR
478 directive will be used. If PORT is not specified, the well known SNMP trap
479 port (162) will be used.
480 .IP "trapsess [SNMPCMD_ARGS] HOST"
481 This is a more generic trap configuration token that allows any type
482 of trap destination to be specified with any version of SNMP. See the
484 manual page for further details on the arguments that can be passed as
486 In addition to the arguments listed there, the special argument
487 \fI-Ci\fR specifies that you want inform notifications to be used
488 instead of unacknowledged traps (this requires that you also specify a
489 version number of v2c or v3 as well).
491 .IP "proxy [-Cn CONTEXTNAME] [SNMPCMD ARGS] HOST OID [REMOTEOID]"
493 This token specifies that any incoming requests under OID should be
494 proxied on to another HOST instead. If a CONTEXTNAME is specified, it
495 assigns the proxied tree to a particular context name within the local
496 agent. This is the proper way to query multiple agents through a
497 single proxy. Assign each remote agent to a different context name.
498 Then you can use "snmpwalk -n contextname1" to walk one remote proxied
499 agent and "snmpwalk -n contextname2" to walk another, assuming you are
500 using SNMPv3 to talk to the proxy (snmpv1 and snmpv2c context mappings
501 aren't currently supported but might be in the future). Optionally,
502 relocate the local OID tree to the new location at the REMOTEOID. To
503 authenticate to HOST you should use the appropriate set of
507 manual page for details.
513 # assigns the entire mib tree on remotehost1 to the context of the
515 proxy -Cn remotehost1 -v 1 -c public remotehost1 .1.3
516 # ditto, but for remotehost 2
517 proxy -Cn remotehost2 -v 1 -c public remotehost2 .1.3
518 # proxies only the ucdavis enterprises tree to the remote host using snmpv1
519 proxy -v 1 -c public remotehost .1.3.6.1.4.1.2021
520 # uses v3 to access remotehost and converts the remote .1.3.6.1.2.1.1
521 # oid to local .1.3.6.1.3.10 oid (another way to access mulitple hosts
522 # without using contexts)
523 proxy -v 3 -l noAuthNoPriv -u user remotehost .1.3.6.1.3.10 .1.3.6.1.2.1.1
524 .SH "PASS-THROUGH CONTROL"
525 .IP "pass MIBOID EXEC"
526 (If you're writing perl scripts, please see the embedded perl support
527 information later in this manual page). Passes entire control of
528 MIBOID to the EXEC program. The EXEC program is called in one of the
529 following three ways:
534 These call lines match to SNMP get and getnext requests. It is
535 expected that the EXEC program will take the arguments passed to it
536 and return the appropriate response through it's stdout.
538 The first line of stdout should be the MIB OID of the returning value.
539 The second line should be the TYPE of value returned, where TYPE is
540 one of the text strings:
541 .B string, integer, unsigned, objectid, timeticks, ipaddress, counter,
544 The third line of stdout should be the VALUE corresponding with the
547 For instance, if a script was to return the value integer value "42"
548 when a request for .1.3.6.1.4.100 was requested, the script should
549 return the following 3 lines:
559 To indicate that the script is unable to comply with the request due
560 to an end-of-mib condition or an invalid request, simple exit and
561 return no output to stdout at all. An SNMP error will be generated
562 corresponding to the SNMP noSuchName response.
563 .IP "EXEC -s MIBOID TYPE VALUE"
565 For SNMP set requests, the above call method is used. The TYPE passed
566 to the EXEC program is one of the text strings:
567 .B integer, counter, gauge, timeticks, ipaddress, objid,
570 indicating the type of value passed in the next argument.
572 Return nothing to stdout, and the set will assumed to have been
573 successful. Otherwise, return one of the following error strings to
578 and the appropriate error response will be generated instead.
581 By default, the only community allowed to write (ie snmpset) to your
582 script will be the "private" community,or community #2 if defined
583 differently by the "community" token discussed above. Which
584 communities are allowed write access are controlled by the RWRITE
585 definition in the snmplib/snmp_impl.h source file.
589 Example (in snmpd.conf):
591 pass .1.3.6.1.4.1.2021.255 /path/to/local/passtest
593 .IP "pass_persist MIBOID EXEC"
594 Passes entire control of MIBOID to the EXEC program.
595 Similar to pass, but the EXEC program continues to run after the initial
598 Upon initialization, EXEC is passed the string "PING\\n" in stdin,
599 and it should respond by printing "PONG\\n" to stdout.
601 For get and getnext requests, EXEC program is passed two lines,
602 the command (get or getnext) and the MIB OID. It should return
603 three lines, the MIB OID, the TYPE of value returned,
604 the VALUE corresponding with the returned TYPE.
606 For example, if the value for .1.3.6.1.4.100 was requested, the following
607 2 lines would be passed in to stdin:
615 To return the value, say, 42, the script would write to stdout:
625 To indicate that the script is unable to comply with the request due
626 to an end-of-mib condition or an invalid request, print "NONE\\n" to
629 Example (in snmpd.conf):
631 pass_persist .1.3.6.1.4.1.2021.255 /path/to/local/pass_persisttest
633 .SH "EMBEDDED PERL SUPPORT"
635 Warning: though embedded perl is working, not much functionality has
636 been implemented yet and thus writing mib module pieces for the agent
637 within perl is not trivial at this point. It should get better in
640 The net-snmp package has ability to call perl scripts directly inside
641 the agent through embedded perl technology (similar to mod_perl for
642 the apache web server). This must be turned on at compile time by
643 passing --enable-embedded-perl to the configure script when the
644 package is built. To see if your package was built with embedded
645 perl, run "net-snmp-config --configure-options" and see if that flag
648 If compiled in, it defines the following snmpd.conf configuration
650 .IP "disablePerl true"
651 This will turn off perl support entirely. If the embedded perl
652 support stops working due to a change in perl, etc, this will stop any
653 calls to the perl core.
655 .IP "perlInitFile FILE"
656 Use FILE as the initialization file. This file is normally
657 DATADIR/snmp/snmp_perl.pl but this token can override that default.
658 This file performs any in-perl initialization that is needed before
659 the rest of the perl directives (below) are called. It is sourced
660 once just before the first perl directive is parsed. See the default
661 file for an example of the initialization it performs.
662 .IP "perl EXPRESSION"
663 Calls perl to evaluate an expression. Normally you'd want to do
664 something like register a function to call when an OID is requested,
665 but you can really do anything perl related you want. For example:
668 perl print "hello world\\n";
671 is the most basic hello world example.
673 The init script by default initializes a $agent variable which
674 is a pointer to a NetSnmp::agent object through which you can register
675 callbacks when a section of the OID tree is hit:
679 perl use Data::Dumper;
680 perl sub myroutine { print "got called: ",Dumper(@_),"\\n"; }
681 perl $agent->register('mylink', '.1.3.6.1.8765', \\&myroutine);
685 Sourcing an external file:
689 perl 'do /path/to/file.pl';
693 No better examples exist at the moment, unfortunately. Look for
694 improved support in future releases. Comments on how this looks as an
695 architecture are certainly appreciated now.
696 .SH "DISMAN-EVENT-MIB SUPPORT (READ: SENDING TRAPS ON ERRORS)"
698 Warning: this implementation has not been extensively tested and is
699 additionally not known to be entirely complete. The concepts defined
700 here should function appropriately, however, but no promises are made
703 If your agent was compiled with support for the DISMAN-EVENT-MIB (you
704 can enable this by running the net-snmp configure script with the
705 --with-mib-modules=disman/event-mib argument) you have support for
706 having the agent check its own data at regular intervals and to send
707 out traps when certain conditions occur. Traps are sent when
708 expressions are first noticed, not once per evaluation. Once a test
709 expression fires a trap, the test will have to fail again before a new
710 trap is sent. See the DISMAN-EVENT-MIB documentation for more
711 details. This can be configured either using the MIB tables themselves
712 or by using these special key words:
713 .IP "agentSecName NAME"
714 The DISMAN-EVENT-MIB support requires a valid user name for which to
715 scan your agent with. This can either be specified using the
716 agentSecName token or by explicitly list one on the "monitor" lines
717 described below using the -u switch. Either way, a "rouser" line (or
718 equivalent access control settings) must also be specified with the
719 same security name name. If you need an example, just do something
724 agentSecName internal
729 And everything below should work just fine.
730 .IP "monitor [OPTIONS] NAME EXPRESSION"
731 This token tells the agent to monitor itself for problems based on
732 EXPRESSION. Expression is a simple expression based on an oid, a
733 comparison operator (!=, ==, <, <=, >, >=) and an integer value (see
734 the examples below). NAME is merely an arbitrary name of your
735 choosing for administrative purposes only. OPTIONS include the
736 following possibilities:
739 Monitors the given expression every FREQUENCY seconds. The default is
742 Use the SECNAME security name for scanning the local host.
743 Specifically, this SECNAME must then be given access control rights
744 via something like the "rouser" snmpd.conf token for this expression
745 to be valid at all. If not specified, it uses the default security
746 name specified by the agentsecname snmpd.conf token. Either the -u
747 flag or a valid agentsecname token must be specified (and that name
748 must be given proper access control rights via a "rouser" token).
750 Specifies additional object values to be delivered with in the
751 resulting trap in addition to the normal trap objects. This is useful
752 for obtaining other columns in the table for the row that triggered
753 the expression. See the examples below for more details.
756 The following example configuration checks the hrSWRunPerfTable table
757 (listing running processes) for any process which is consuming > 10Mb
758 of memory. It performs this check every 600 seconds (the default).
759 For every process it finds exceeding the limit, it will end out
760 exactly one notification. In addition to the normal hrSWRunPerfMem
761 oid and value sent in the trap, the hrSWRunName object will also be
762 sent. Note that the hrSWRunName object actually occurs in a different
763 table, but since the indexes to the two tables are the same this works
769 monitor -u me -o sysUpTime.0 -o hrSWRunName "high process memory" hrSWRunPerfMem > 10000
773 The above line would produce a trap which, when formated by snmptrapd, would
778 2002-04-05 13:33:53 localhost.localdomain [udp:127.0.0.1:32931]:
779 sysUpTimeInstance = Timeticks: (1629) 0:00:16.29 snmpTrapOID.0 = OID: mteTriggerFired mteHotTrigger = high process memory mteHotTargetName = mteHotContextName = mteHotOID = OID: hrSWRunPerfMem.1968 mteHotValue = 28564 hrSWRunName.1968 = "xemacs"
783 This shows my xemacs process using 28Mb of resident memory. Which,
784 considering it's xemacs, is not that surprising.
785 .IP "defaultMonitors yes"
786 By default, the agent and the DISMAN-EVENT-MIB support do nothing
787 until configured. Typically people wish to watch a bunch of tables
788 within the UCD-SNMP-MIB which are designed specifically for reporting
789 problems. If the "defaultMonitors yes" line is put into the
790 snmpd.conf file (which must be accompanied by an appropriate
791 agentSecName line and a rouser line), the following monitoring
792 conditions will be installed:
796 monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
797 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
798 monitor -o extNames -o extOutput "extTable" extResult != 0
799 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
800 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
801 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
804 .SH "DEBUGGING AND OTHER EXTENSIBILITY NOTES"
805 If you're trying to figure out aspects of the various mib modules
806 (possibly some that you've added yourself), the following may help you
807 spit out some useful debugging information. First off, please read
808 the snmpd manual page on the -D flag. Then the following
809 configuration snmpd.conf token, combined with the -D flag, can produce
811 .IP "injectHandler HANDLER modulename"
812 This will insert new handlers into the section of the mib tree
813 referenced by "modulename". The types of handlers available for
817 debug - Prints out lots of debugging information when -Dhelper:debug
818 is passed to the snmpd application.
819 read_only - Forces turning off write support for the given module.
820 serialize - If a module is failing to handle multiple requests
821 properly (using the new 5.0 module API), this will force
822 the module to only receive one request at a time.
823 bulk_to_next - If a module registers to handle getbulk support, but
824 for some reason is failing to implement it properly,
825 this module will convert all getbulk requests to
826 getnext requests before the final module receives it.
829 .IP "Figuring out module names"
830 To figure out which modules you can inject things into, snmpwalk the
831 nsModuleTable which will give you a list of all named modules
832 registered within the agent.
833 .SH "EXAMPLE CONFIGURATION FILE"
834 See the EXAMPLE.CONF file in the top level source directory for a more
835 detailed example of how the above information is used in real
837 .SH "RE-READING snmpd.conf AND snmpd.local.conf"
838 The Net-SNMP agent can be forced to re-read its configuration files.
839 It can be told to do so by one of two ways:
841 An snmpset of integer(1) to UCD-SNMP-MIB::versionUpdateConfig.0
842 (.1.3.6.1.4.1.2021.100.11.0)
844 A "kill -HUP" signal sent to the snmpd agent process.
846 SYSCONFDIR/snmp/snmpd.conf
848 snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, read_config(3).
projects / bcm963xx.git / blob