1
.TH SNMPD.CONF 5 "08 Feb 2002" VVERSIONINFO "Net-SNMP"
4
snmpd.conf - configuration file for the Net-SNMP SNMP agent
6
The Net-SNMP agent uses one or more configuration files
7
to control its operation and the management information
9
These files (\fBsnmpd.conf\fR and \fBsnmpd.local.conf\fR)
10
can be located in one of several locations, as described in the
14
The (perl) application
16
can be used to generate configuration files for the
17
most common agent requirements. See the
19
manual page for more information, or try running the
22
.IP "snmpconf -g basic_setup"
25
There are a large number of directives that can be specified,
26
but these mostly fall into four distinct categories:
28
those controlling who can access the agent
30
those configuring the information that is supplied by the agent
32
those controlling active monitoring of the local system
34
those concerned with extending the functionality of the agent.
36
Some directives don't fall naturally into any of these four
37
categories, but this covers the majority of the contents of
41
A full list of recognised directives can be obtained by running
47
Although most configuration directives are concerned with the MIB
48
information supplied by the agent, there are a handful of directives that
49
control the behaviour of \fIsnmpd\fR considered simply as a daemon
50
providing a network service.
51
.IP "agentaddress [<transport-specifier>:]<transport-address>[,...]"
52
defines a list of listening addresses, on which to receive incoming
55
.B LISTENING ADDRESSES
58
manual page for more information about the format of listening
61
The default behaviour is to
62
listen on UDP port 161 on all IPv4 interfaces.
63
.IP "agentgroup {GROUP|#GID}"
64
changes to the specified group after opening the listening port(s).
65
This may refer to a group by name (GROUP), or a numeric group ID
66
starting with '#' (#GID).
67
.IP "agentuser {USER|#UID}"
68
changes to the specified user after opening the listening port(s).
69
This may refer to a user by name (USER), or a numeric user ID
70
starting with '#' (#UID).
71
.IP "leave_pidfile yes"
72
instructs the agent to not remove its pid file on shutdown. Equivalent to
73
specifying "-U" on the command line.
74
.IP "maxGetbulkRepeats NUM"
75
Sets the maximum number of responses allowed for a single variable in
76
a getbulk request. Set to 0 to enable the default and set it to -1 to
77
enable unlimited. Because memory is allocated ahead of time, sitting
78
this to unlimited is not considered safe if your user population can
79
not be trusted. A repeat number greater than this will be truncated
82
This is set by default to -1.
83
.IP "maxGetbulkResponses NUM"
84
Sets the maximum number of responses allowed for a getbulk request.
85
This is set by default to 100. Set to 0 to enable the default and set
86
it to -1 to enable unlimited. Because memory is allocated ahead of
87
time, sitting this to unlimited is not considered safe if your user
88
population can not be trusted.
90
In general, the total number of responses will not be allowed to
91
exceed the maxGetbulkResponses number and the total number returned
92
will be an integer multiple of the number of variables requested times
93
the calculated number of repeats allow to fit below this number.
95
Also not that processing of maxGetbulkRepeats is handled first.
96
.SS SNMPv3 Configuration
97
SNMPv3 requires an SNMP agent to define a unique "engine ID"
98
in order to respond to SNMPv3 requests.
99
This ID will normally be determined automatically, using two reasonably
100
non-predictable values - a (pseudo-)random number and the current
101
uptime in seconds. This is the recommended approach. However the
102
capacity exists to define the engineID in other ways:
103
.IP "engineID STRING"
104
specifies that the engineID should be built from the given text STRING.
105
.IP "engineIDType 1|2|3"
106
specifies that the engineID should be built from the IPv4 address (1),
107
IPv6 address (2) or MAC address (3). Note that changing the IP address
108
(or switching the network interface card) may cause problems.
109
.IP "engineIDNic INTERFACE"
110
defines which interface to use when determining the MAC address.
111
If \fIengineIDType 3\fR is not specified, then this directive
114
The default is to use eth0.
116
.\" What if this doesn't exist ?
120
supports the View-Based Access Control Model (VACM) as defined in RFC
121
2575, to control who can retrieve or update information. To this end,
122
it recognizes various directives relating to access control.
123
These fall into four basic groups.
125
.IP "createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES] [privpassphrase]"
127
MD5 and SHA are the authentication types to use. DES and AES are the
128
privacy protocols to use. If the privacy
129
passphrase is not specified, it is assumed to be the same as the
130
authentication passphrase. Note that the users created will be
131
useless unless they are also added to the VACM access control tables
134
SHA authentication and DES/AES privacy require OpenSSL to be installed and
135
the agent to be built with OpenSSL support. MD5 authentication may be
136
used without OpenSSL.
138
Warning: the minimum pass phrase length is 8 characters.
140
SNMPv3 users can be created at runtime using the
144
Instead of figuring out how to use this directive and where to put it
145
(see below), just run "net-snmp-config --create-snmpv3-user" instead,
146
which will add one of these lines to the right place.
148
This directive should be placed into the
149
PERSISTENT_DIRECTORY/snmpd.conf file instead of the other normal
150
locations. The reason is that the information is read from the file
151
and then the line is removed (eliminating the storage of the master
152
password for that user) and replaced with the key that is derived from
153
it. This key is a localized key, so that if it is stolen it can not
154
be used to access other agents. If the password is stolen, however,
157
If you need to localize the user to a particular EngineID (this is
158
useful mostly in the similar snmptrapd.conf file), you can use the -e
159
argument to specify an EngineID as a hex value (EG, "0x01020304").
161
If you want to generate either your master or localized keys directly,
162
replace the given password with a hexstring (preceeded by a "0x") and
163
precede the hex string by a -m or -l token (respectively). EGs:
167
[these keys are *not* secure but are easy to visually parse for
168
counting purposes. Please generate random keys instead of using
171
createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
172
createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
176
Due to the way localization happens, localized privacy keys are
177
expected to be the length needed by the algorithm (128 bits for all
178
supported algorithms). Master encryption keys, though, need to be the
179
length required by the authentication algorithm not the length
180
required by the encrypting algorithm (MD5: 16 bytes, SHA: 20 bytes).
181
.SS Traditional Access Control
182
Most simple access control requirements can be specified using the
183
directives \fIrouser\fR/\fIrwuser\fR (for SNMPv3) or
184
\fIrocommunity\fR/\fIrwcommunity\fR (for SNMPv1 or SNMPv2c).
185
.IP "rouser USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]"
186
.IP "rwuser USER [noauth|auth|priv [OID | -V VIEW [CONTEXT]]]"
187
specify an SNMPv3 user that will be allowed read-only (GET and GETNEXT)
188
or read-write (GET, GETNEXT and SET) access respectively.
189
By default, this will provide access to the full OID tree for authenticated
190
(including encrypted) SNMPv3 requests, using the default context.
191
An alternative minimum security level can be specified using \fInoauth\fR
192
(to allow unauthenticated requests), or \fIpriv\fR (to enforce use of
193
encryption). The OID field restricts access for that
194
user to the subtree rooted at the given OID, or the named view.
195
An optional context can also be specified, or "context*" to denote a context
196
prefix. If no context field is specified (or the token "*" is used), the
197
directive will match all possible contexts.
198
.IP "rocommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]"
199
.IP "rwcommunity COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]"
200
specify an SNMPv1 or SNMPv2c community that will be allowed read-only
201
(GET and GETNEXT) or read-write (GET, GETNEXT and SET) access respectively.
202
By default, this will provide access to the full OID tree for such requests,
203
regardless of where they were sent from. The SOURCE token can be used to
204
restrict access to requests from the specified system(s) - see
205
\fIcom2sec\fR for the full details. The OID field restricts access for
206
that community to the subtree rooted at the given OID, or named view.
207
Contexts are typically less relevant to community-based SNMP versions,
208
but the same behaviour applies here.
209
.IP "rocommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]"
210
.IP "rwcommunity6 COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]"
211
are directives relating to requests received using IPv6
212
(if the agent supports such transport domains).
213
The interpretation of the SOURCE, OID, VIEW and CONTEXT tokens are exactly
214
the same as for the IPv4 versions.
216
In each case, only one directive should be specified for a given SNMPv3 user,
218
It is \fBnot\fR appropriate to specify both \fIrouser\fR
219
and \fIrwuser\fR directives referring to the same SNMPv3 user (or equivalent
220
community settings). The \fIrwuser\fR directive provides all the access
221
of \fIrouser\fR (as well as allowing SET support).
222
The same holds true for the community-based directives.
224
More complex access requirements (such as access to two
225
or more distinct OID subtrees, or different views for GET and SET requests)
226
should use one of the other access control mechanisms.
227
Note that if several distinct communities or SNMPv3 users need to be granted
228
the same level of access, it would also be more efficient to use the main VACM
229
configuration directives.
230
.SS VACM Configuration
231
The full flexibility of the VACM is available using four configuration
232
directives - \fIcom2sec\fR, \fIgroup\fR, \fIview\fR and \fIaccess\fR.
233
These provide direct configuration of the underlying VACM tables.
234
.IP "com2sec [-Cn CONTEXT] SECNAME SOURCE COMMUNITY"
235
.IP "com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY"
236
map an SNMPv1 or SNMPv2c community string to a security name - either from
237
a particular range of source addresses, or globally (\fI"default"\fR).
238
A restricted source can either be a specific hostname (or address), or
239
a subnet - represented as IP/MASK (e.g. 10.10.10.0/255.255.255.0), or
240
IP/BITS (e.g. 10.10.10.0/24), or the IPv6 equivalents.
242
The same community string can be specified in several separate directives
243
(presumably with different source tokens), and the first source/community
244
combination that matches the incoming request will be selected.
245
Various source/community combinations can also map to the same security name.
247
If a CONTEXT is specified (using \fI-Cn\fR), the community string will be
248
mapped to a security name in the named SNMPv3 context. Otherwise the
249
default context ("") will be used.
250
.IP "com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY"
251
is the Unix domain sockets version of \fIcom2sec\fR.
252
.IP "group GROUP {v1|v2c|usm} SECNAME"
253
maps a security name (in the specified security model) into
254
a named group. Several \fIgroup\fR directives can specify the
255
same group name, allowing a single access setting to apply to several
256
users and/or community strings.
258
Note that groups must be set up for the two community-based models separately -
259
a single \fIcom2sec\fR (or equivalent) directive will typically be
260
accompanied by \fBtwo\fR \fIgroup\fR directives.
261
.IP "view VNAME TYPE OID [MASK]"
262
defines a named "view" - a subset of the overall OID tree. This is most
263
commonly a single subtree, but several \fIview\fR directives can be given
264
with the same view name (VNAME), to build up a more complex collection of OIDs.
265
TYPE is either \fIincluded\fR or \fIexcluded\fR, which can again define
266
a more complex view (e.g by excluding certain sensitive objects
267
from an otherwise accessible subtree).
269
MASK is a list of hex octets (optionally separated by '.' or ':') with
270
the set bits indicating which subidentifiers in the view OID to match
271
against. If not specified, this defaults to matching the OID exactly
272
(all bits set), thus defining a simple OID subtree. So:
275
view iso1 included .iso 0xf0
277
view iso2 included .iso
279
view iso3 included .iso.org.dod.mgmt 0xf0
283
would all define the same view, covering the whole of the 'iso(1)' subtree
284
(with the third example ignoring the subidentifiers not covered by the mask).
286
More usefully, the mask can be used to define a view covering a particular
287
row (or rows) in a table, by matching against the appropriate table index
288
value, but skipping the column subidentifier:
291
.IP "view ifRow4 included .1.3.6.1.2.1.2.2.1.0.4 0xff:a0"
295
Note that a mask longer than 8 bits must use ':' to separate the individual
297
.IP "access GROUP CONTEXT {any|v1|v2c|usm} LEVEL PREFX READ WRITE NOTIFY"
298
maps from a group of users/communities (with a particular security model
299
and minimum security level, and in a specific context) to one of three views,
300
depending on the request being processed.
302
LEVEL is one of \fInoauth\fR, \fIauth\fR, or \fIpriv\fR.
303
PREFX specifies how CONTEXT should be matched against the context of
304
the incoming request, either \fIexact\fR or \fIprefix\fR.
305
READ, WRITE and NOTIFY specifies the view to be used for GET*, SET
306
and TRAP/INFORM requests (althought the NOTIFY view is not currently used).
307
For v1 or v2c access, LEVEL will need to be \fInoauth\fR.
308
.SS Typed-View Configuration
309
The final group of directives extend the VACM approach into a more flexible
310
mechanism, which can be applied to other access control requirements. Rather than
311
the fixed three views of the standard VACM mechanism, this can be used to
312
configure various different view types. As far as the main SNMP agent is
313
concerned, the two main view types are \fIread\fR and \fIwrite\fR,
314
corresponding to the READ and WRITE views of the main \fIaccess\fR directive.
315
See the 'snmptrapd.conf(5)' man page for discussion of other view types.
316
.IP "authcommunity TYPES COMMUNITY [SOURCE [OID | -V VIEW [CONTEXT]]]"
317
is an alternative to the \fIrocommunity\fR/\fIrwcommunity\fR directives.
318
TYPES will usually be \fIread\fR or \fIread,write\fR respectively.
319
The view specification can either be an OID subtree (as before),
320
or a named view (defined using the
321
\fIview\fR directive) for greater flexibility. If this is omitted,
322
then access will be allowed to the full OID tree.
323
If CONTEXT is specified, access is configured within this SNMPv3 context.
324
Otherwise the default context ("") is used.
325
.IP "authuser TYPES [-s MODEL] USER [LEVEL [OID | -V VIEW [CONTEXT]]]"
326
is an alternative to the \fIrouser\fR/\fIrwuser\fR directives.
327
The fields TYPES, OID, VIEW and CONTEXT have the same meaning as for
329
.IP "authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW [CONTEXT]]]"
330
is a companion to the \fIauthuser\fR directive, specifying access
331
for a particular group (defined using the \fIgroup\fR directive as usual).
332
Both \fIauthuser\fR and \fIauthgroup\fR default to authenticated requests -
333
LEVEL can also be specified as \fInoauth\fR or \fIpriv\fR to allow
334
unauthenticated requests, or require encryption respectively.
335
Both \fIauthuser\fR and \fIauthgroup\fR directives also default to configuring
336
access for SNMPv3/USM requests - use the '-s' flag to specify an alternative
337
security model (using the same values as for \fIaccess\fR above).
338
.IP "authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]"
339
also configures the access for a particular group,
340
specifying the name and type of view to apply. The MODEL and LEVEL fields
341
are interpreted in the same way as for \fIauthgroup\fR.
342
If CONTEXT is specified, access is configured within this SNMPv3 context
343
(or contexts with this prefix if the CONTEXT field ends with '*').
344
Otherwise the default context ("") is used.
345
.IP "setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES"
346
is a direct equivalent to the original \fIaccess\fR directive, typically
347
listing the view types as \fIread\fR or \fIread,write\fR as appropriate.
348
(or see 'snmptrapd.conf(5)' for other possibilities).
349
All other fields have the same interpretation as with \fIaccess\fR.
350
.SH SYSTEM INFORMATION
351
Most of the information reported by the Net-SNMP agent is retrieved
352
from the underlying system, or dynamically configured via SNMP SET requests
353
(and retained from one run of the agent to the next).
354
However, certain MIB objects can be configured or controlled via
355
the \fIsnmpd.conf(5)\fR file.
357
Most of the scalar objects in the 'system' group can be configured
359
.IP "sysLocation STRING"
360
.IP "sysContact STRING"
362
set the system location, system contact or system name
363
(\fCsysLocation.0\fR, \fCsysContact.0\fR and \fCsysName.0\fR) for the agent respectively.
364
Ordinarily these objects are writeable via suitably authorized SNMP SET
365
requests. However, specifying one of these directives makes the
366
corresponding object read-only, and attempts to SET it will result in
367
a \fInotWritable\fR error response.
368
.IP "sysServices NUMBER"
369
sets the value of the \fCsysServices.0\fR object.
370
For a host system, a good value is 72 (application + end-to-end layers).
371
If this directive is not specified, then no value will be reported
372
for the \fCsysServices.0\fR object.
373
.IP "sysDescr STRING"
374
.IP "sysObjectID OID"
375
sets the system description or object ID for the agent.
376
Although these MIB objects are not SNMP-writable, these directives can be
377
used by a network administrator to configure suitable values for them.
379
.IP "interface NAME TYPE SPEED"
380
can be used to provide appropriate type and speed settings for
381
interfaces where the agent fails to determine this information correctly.
382
TYPE is a type value as given in the IANAifType-MIB,
383
and can be specified numerically or by name (assuming this MIB is loaded).
384
.SS Host Resources Group
385
This requires that the agent was built with support for the
386
\fIhost\fR module (which is now included as part of the default build
387
configuration on the major supported platforms).
389
.\" XXX - .IP "scandisk STRING"
391
.IP "ignoreDisk STRING"
392
controls which disk devices are scanned as part of populating the
393
\fChrDiskStorageTable\fR (and \fChrDeviceTable\fR).
394
The HostRes implementation code includes a list of disk device patterns
395
appropriate for the current operating system, some of which may cause
396
the agent to block when trying to open the corresponding disk devices.
397
This might lead to a timeout when walking these tables, possibly
398
resulting in inconsistent behaviour. This directive can be used
399
to specify particular devices (either individually or wildcarded)
400
that should not be checked.
403
Please consult the source (\fIhost/hr_disk.c\fR) and check for the
404
\fIAdd_HR_Disk_entry\fR calls relevant for a particular O/S
405
to determine the list of devices that will be scanned.
408
The pattern can include one or more wildcard expressions.
409
See \fIsnmpd.examples(5)\fR for illustration of the wildcard syntax.
410
.IP "skipNFSInHostResources true"
411
controls whether NFS and NFS-like file systems should be omitted
412
from the hrStorageTable (true or 1) or not (false or 0, which is the default).
413
If the Net-SNMP agent gets hung on NFS-mounted filesystems, you
414
can try setting this to '1'.
415
.IP "storageUseNFS [1|2]"
416
controls how NFS and NFS-like file systems should be reported
417
in the hrStorageTable.
418
as 'Network Disks' (1) or 'Fixed Disks' (2)
419
Historically, the Net-SNMP agent has reported such file systems
420
as 'Fixed Disks', and this is still the default behaviour.
421
Setting this directive to '1' reports such file systems as
422
'Network Disks', as required by the Host Resources MIB.
423
.SS Process Monitoring
424
The \fChrSWRun\fR group of the Host Resources MIB provides
425
information about individual processes running on the local system.
426
The \fCprTable\fR of the UCD-SNMP-MIB complements this by reporting
427
on selected services (which may involve multiple processes).
428
This requires that the agent was built with support for the
429
\fIucd-snmp/proc\fR module (which is included as part of the
430
default build configuration).
431
.IP "proc NAME [MAX [MIN]]"
432
monitors the number of processes called NAME (as reported by PSCMD)
433
running on the local system.
435
If the number of NAMEd processes is less than MIN or greater than MAX,
436
then the corresponding \fCprErrorFlag\fR instance will be
437
set to 1, and a suitable description message reported via the
438
\fCprErrMessage\fR instance.
441
This situation will \fBnot\fR automatically trigger a trap to report
442
the problem - see the DisMan Event MIB section later.
445
If neither MAX nor MIN are specified (or are both 0), they will
446
default to \fBinfinity\fR and 1 respectively ("at least one").
447
If only MAX is specified, MIN will default to 0 ("no more than MAX").
448
.IP "procfix NAME PROG ARGS"
449
registers a command that can be run to fix errors with the given
450
process NAME. This will be invoked when the corresponding
451
\fCprErrFix\fR instance is set to 1.
454
This command will \fBnot\fR be invoked automatically.
455
.\" XXX - but see the DisMan Event MIB section later ???
458
The \fIprocfix\fR directive must be specified \fBafter\fR the matching
459
\fIproc\fR directive, and cannot be used on its own.
461
If no \fIproc\fR directives are defined, then walking the
462
\fCprTable\fR will fail (\fInoSuchObject\fI).
463
.SS Disk Usage Monitoring
464
This requires that the agent was built with support for the
465
\fIucd-snmp/disk\fR module (which is included as part of the
466
default build configuration).
467
.IP "disk PATH [ MINSPACE | MINPERCENT% ]"
468
monitors the disk mounted at PATH for available disk space.
470
The minimum threshold can either be specified in kB (MINSPACE) or
471
as a percentage of the total disk (MINPERCENT% with a '%' character),
472
defaulting to 100kB if neither are specified.
473
If the free disk space falls below this threshold,
474
then the corresponding \fCdskErrorFlag\fR instance will be
475
set to 1, and a suitable description message reported via the
476
\fCdskErrorMsg\fR instance.
479
This situation will \fBnot\fR automatically trigger a trap to report
480
the problem - see the DisMan Event MIB section later.
482
.IP "includeAllDisks MINPERCENT%"
483
configures monitoring of all disks found on the system,
484
using the specified (percentage) threshold.
485
The threshold for individual disks can be adjusted using suitable
486
\fIdisk\fR directives (which can come either before or after the
487
\fIincludeAllDisks\fR directive).
490
Whether \fIdisk\fR directives appears before or after \fIincludeAllDisks\fR
491
may affect the indexing of the \fCdskTable\fR.
494
Only one \fIincludeAllDisks\fR directive should be specified - any
495
subsequent copies will be ignored.
497
The list of mounted disks will be determined when the agent starts using the
498
setmntent(3) and getmntent(3), or fopen(3) and getmntent(3), or
499
setfsent(3) and getfsent(3) system calls. If none of the above
500
system calls are available then the root partition "/"
501
(which is assumed to exist on any UNIX based system) will be monitored.
502
Disks mounted after the agent has started will not be monitored.
504
.\" XXX - unless the config is re-read ??
507
If neither any \fIdisk\fR directives or \fIincludeAllDisks\fR are defined,
508
then walking the \fCdskTable\fR will fail (\fInoSuchObject\fI).
509
.SS System Load Monitoring
510
This requires that the agent was built with support for either the
511
\fIucd-snmp/loadave\fR module or the \fIucd-snmp/memory\fR module
512
respectively (both of which are included as part of the
513
default build configuration).
514
.IP "load MAX1 [MAX5 [MAX15]]"
515
monitors the load average of the local system, specifying
516
thresholds for the 1-minute, 5-minute and 15-minute averages.
517
If any of these loads exceed the associated maximum value,
518
then the corresponding \fClaErrorFlag\fR instance will be
519
set to 1, and a suitable description message reported via the
520
\fClaErrMessage\fR instance.
523
This situation will \fBnot\fR automatically trigger a trap to report
524
the problem - see the DisMan Event MIB section later.
527
If the MAX15 threshold is omitted, it will default to the MAX5 value.
528
If both MAX5 and MAX15 are omitted, they will default to the MAX1 value.
529
If this directive is not specified, all three thresholds will
530
default to a value of DEFMAXLOADAVE.
532
If a threshold value of 0 is given, the agent will not report errors
533
via the relevant \fClaErrorFlag\fR or \fClaErrMessage\fR instances,
534
regardless of the current load.
536
Unlike the \fIproc\fR and \fIdisk\fR directives, walking the
537
walking the \fClaTable\fR will succeed (assuming the
538
\fIucd-snmp/loadave\fR module was configured into the agent),
539
even if the \fIload\fR directive is not present.
541
monitors the amount of swap space available on the local system.
542
If this falls below the specified threshold (MIN kB),
543
then the \fImemErrorSwap\fR object will be set to 1,
544
and a suitable description message reported via \fImemSwapErrorMsg\fR.
547
This situation will \fBnot\fR automatically trigger a trap to report
548
the problem - see the DisMan Event MIB section later.
550
If this directive is not specified, the default threshold is 16 MB.
551
.SS Log File Monitoring
552
This requires that the agent was built with support for either the
553
\fIucd-snmp/file\fR or \fIucd-snmp/logmatch\fR modules respectively
554
(both of which are included as part of the
555
default build configuration).
556
.IP "file FILE [MAXSIZE]"
557
monitors the size of the specified file (in kB).
558
If MAXSIZE is specified, and the size of the file exceeds
559
this threshold, then the corresponding \fCfileErrorFlag\fR
560
instance will be set to 1, and a suitable description message reported
561
via the \fCfileErrorMsg\fR instance.
564
This situation will \fBnot\fR automatically trigger a trap to report
565
the problem - see the DisMan Event MIB section later.
568
Note: A maximum of 20 files can be monitored.
570
Note: If no \fIfile\fR directives are defined, then walking the
571
\fCfileTable\fR will fail (\fInoSuchObject\fR).
572
.IP "logmatch NAME FILE CYCLETIME REGEX"
573
monitors the specified file for occurances of the specified
574
pattern REGEX. The file position is stored internally so the entire file
575
is only read initially, every subsequent pass will only read the new lines
576
added to the file since the last read.
579
name of the logmatch instance (will appear as logMatchName under
580
logMatch/logMatchTable/logMatchEntry/logMatchName in the ucd-snmp MIB tree)
582
absolute path to the logfile to be monitored. Note that this path
583
can contain date/time directives (like in the UNIX 'date' command). See the
584
manual page for 'strftime' for the various directives accepted.
586
time interval for each logfile read and internal variable update in seconds.
587
Note: an SNMPGET* operation will also trigger an immediate logfile read and
590
the regular expression to be used. Note: DO NOT enclose the regular expression
591
in quotes even if there are spaces in the expression as the quotes will also
592
become part of the pattern to be matched!
598
logmatch apache-GETs /usr/local/apache/logs/access.log-%Y-%m-%d 60 GET.*HTTP.*
600
This logmatch instance is named 'apache-GETs', uses 'GET.*HTTP.*' as its
601
regular expression and it will monitor the file named
602
(assuming today is May 6th 2009): '/usr/local/apache/logs/access.log-2009-05-06',
603
tomorrow it will look for 'access.log-2009-05-07'. The logfile is read every 60
607
Note: A maximum of 250 logmatch directives can be specified.
609
Note: If no \fIlogmatch\fR directives are defined, then walking the
610
\fClogMatchTable\fR will fail (\fInoSuchObject\fI).
611
.SH "ACTIVE MONITORING"
612
The usual behaviour of an SNMP agent is to wait for incoming SNMP requests
613
and respond to them - if no requests are received, an agent will typically
614
not initiate any actions. This section describes various directives that
615
can configure \fIsnmpd\fR to take a more active role.
616
.SS "Notification Handling"
617
.IP "trapcommunity STRING"
618
defines the default community string to be used when sending traps.
619
Note that this directive must be used prior to any community-based
620
trap destination directives that need to use it.
621
.IP "trapsink HOST [COMMUNITY [PORT]]"
622
.IP "trap2sink HOST [COMMUNITY [PORT]]"
623
.IP "informsink HOST [COMMUNITY [PORT]]"
624
define the address of a notification receiver that should be sent
625
SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifications respectively.
627
.B LISTENING ADDRESSES
630
manual page for more information about the format of listening
632
If COMMUNITY is not specified, the most recent \fItrapcommunity\fR
635
If the transport address does not include an explicit
636
port specification, then PORT will be used.
637
If this is not specified, the well known SNMP trap
638
port (162) will be used.
641
This mechanism is being deprecated, and the listening port
642
should be specified via the transport specification HOST instead.
645
If several sink directives are specified, multiple
646
copies of each notification (in the appropriate formats)
650
It is \fBnot\fR normally appropriate to list two (or all three)
651
sink directives with the same destination.
653
.IP "trapsess [SNMPCMD_ARGS] HOST"
654
provides a more generic mechanism for defining notification destinations.
656
should be the command-line options required for an equivalent
657
\fIsnmptrap\fR (or \fIsnmpinform\fR) command to send the desired notification.
658
The option \fI-Ci\fR can be used (with \fI-v2c\fR or \fI-v3\fR) to generate
659
an INFORM notification rather than an unacknowledged TRAP.
661
This is the appropriate directive for defining SNMPv3 trap receivers.
663
http://www.net-snmp.org/tutorial/tutorial-5/commands/snmptrap-v3.html
664
for more information about SNMPv3 notification behaviour.
665
.IP "authtrapenable {1|2}"
666
determines whether to generate authentication failure traps
667
(\fIenabled(1)\fR) or not (\fIdisabled(2)\fR - the default).
668
Ordinarily the corresponding MIB
669
object (\fCsnmpEnableAuthenTraps.0\fR) is read-write, but specifying
670
this directive makes this object read-only, and attempts to set the
671
value via SET requests will result in a \fInotWritable\fR error response.
672
.SS "DisMan Event MIB"
673
The previous directives can be used to configure where traps should
674
be sent, but are not concerned with \fIwhen\fR to send such traps
675
(or what traps should be generated). This is the domain of the
676
Event MIB - developed by the Distributed Management (DisMan)
677
working group of the IETF.
679
This requires that the agent was built with support for the
680
\fIdisman/event\fR module (which is now included as part of the
681
default build configuration for the most recent distribution).
684
The behaviour of the latest implementation differs in some minor
685
respects from the previous code - nothing too significant, but
686
existing scripts may possibly need some minor adjustments.
688
.IP "iquerySecName NAME"
689
.IP "agentSecName NAME"
690
specifies the default SNMPv3 username, to be used when making internal
691
queries to retrieve any necessary information (either for evaluating
692
the monitored expression, or building a notification payload).
693
These internal queries always use SNMPv3, even if normal querying
694
of the agent is done using SNMPv1 or SNMPv2c.
696
Note that this user must also be explicitly created (\fIcreateUser\fR)
697
and given appropriate access rights (e.g. \fIrouser\fR). This
698
directive is purely concerned with defining \fIwhich\fR user should
699
be used - not with actually setting this user up.
701
.\" XXX - Should it create the user as well?
703
.\" .IP "iqueryVersion "
704
.\" .IP "iquerySecLevel "
706
.IP "monitor [OPTIONS] NAME EXPRESSION"
707
defines a MIB object to monitor.
708
If the EXPRESSION condition holds (see below), then this will trigger
709
the corresponding event, and either send a notification or apply
710
a SET assignment (or both).
711
Note that the event will only be triggered once, when the expression
712
first matches. This monitor entry will not fire again until the
713
monitored condition first becomes false, and then matches again.
714
NAME is an administrative name for this expression, and is used for
715
indexing the \fCmteTriggerTable\fR (and related tables).
716
Note also that such monitors use an internal SNMPv3 request to retrieve
717
the values being monitored (even if normal agent queries typically use
718
SNMPv1 or SNMPv2c). See the \fIiquerySecName\fP token described above.
719
.IP "\fIEXPRESSION\fR"
720
There are three types of monitor expression supported by the Event MIB -
721
existence, boolean and threshold tests.
723
.IP "OID | ! OID | != OID"
724
defines an \fIexistence(0)\fR monitor test.
725
A bare OID specifies a \fIpresent(0)\fR test, which will fire when
726
(an instance of) the monitored OID is created.
727
An expression of the form \fI! OID\fR specifies an \fIabsent(1)\fR test,
728
which will fire when the monitored OID is delected.
729
An expression of the form \fI!= OID\fR specifies a \fIchanged(2)\fR test,
730
which will fire whenever the monitored value(s) change.
731
Note that there \fBmust\fP be whitespace before the OID token.
733
defines a \fIboolean(1)\fR monitor test.
734
OP should be one of the defined
735
comparison operators (!=, ==, <, <=, >, >=) and VALUE should be an
736
integer value to compare against.
737
Note that there \fBmust\fP be whitespace around the OP token.
738
A comparison such as \fCOID !=0\fP will not be handled correctly.
739
.IP "OID MIN MAX [DMIN DMAX]"
740
defines a \fIthreshold(2)\fR monitor test.
741
MIN and MAX are integer values, specifying lower and upper thresholds.
742
If the value of the monitored OID falls below the lower threshold (MIN)
743
or rises above the upper threshold (MAX), then the monitor entry will
744
trigger the corresponding event.
746
Note that the rising threshold event will only be re-armed when
747
the monitored value falls below the \fBlower\fR threshold (MIN).
748
Similarly, the falling threshold event will be re-armed by
749
the upper threshold (MAX).
751
The optional parameters DMIN and DMAX configure a pair of
752
similar threshold tests, but working with the delta
753
differences between successive sample values.
756
There are various options to control the behaviour of the monitored
757
expression. These include:
760
indicates that the expression should be evaluated using delta differences
761
between sample values (rather than the values themselves).
764
specifies a discontinuity marker for validating delta differences.
765
A \fI-di\fR object instance will be used exactly as given.
766
A \fI-d\fR object will have the instance subidentifiers from the
767
corresponding (wildcarded) expression object appended.
768
If the \fI-I\fR flag is specified, then there is no difference
769
between these two options.
771
This option also implies \fI-D\fR.
773
specifies the event to be invoked when this monitor entry is triggered.
774
If this option is not given, the monitor entry will generate one
775
of the standard notifications defined in the DISMAN-EVENT-MIB.
777
indicates that the monitored expression should be applied to the
778
specified OID as a single instance. By default, the OID will
779
be treated as a wildcarded object, and the monitor expanded
780
to cover all matching instances.
783
define additional varbinds to be added to the notification payload
784
when this monitor trigger fires.
785
For a wildcarded expression, the suffix of the matched instance
786
will be added to any OIDs specified using \fI-o\fR, while OIDs
787
specified using \fI-i\fR will be treated as exact instances.
788
If the \fI-I\fR flag is specified, then there is no difference
789
between these two options.
791
See \fIstrictDisman\fR for details of the ordering of notification payloads.
793
monitors the given expression every FREQUENCY seconds.
794
By default, the expression will be evaluated every 600s (10 minutes).
796
indicates that the monitor expression should \fInot\fR be evaluated
797
when the agent first starts up. The first evaluation will be done
798
once the first repeat interval has expired.
800
indicates that the monitor expression \fIshould\fR be evaluated when the
801
agent first starts up. This is the default behaviour.
804
Notifications triggered by this initial evaluation will be sent
805
\fIbefore\fR the \fCcoldStart\fR trap.
808
specifies a security name to use for scanning the local host,
809
instead of the default \fIiquerySecName\fR.
810
Once again, this user must be explicitly created and given
811
suitable access rights.
813
.IP "notificationEvent ENAME NOTIFICATION [-m] [-i OID | -o OID ]*"
814
defines a notification event named ENAME.
815
This can be triggered from a given \fImonitor\fR entry by specifying
816
the option \fI-e ENAME\fR (see above).
817
NOTIFICATION should be the OID of the NOTIFICATION-TYPE definition
818
for the notification to be generated.
820
If the \fI-m\fR option is given, the notification payload will
821
include the standard varbinds as specified in the OBJECTS clause
822
of the notification MIB definition.
823
This option must come \fBafter\fR the NOTIFICATION OID
824
(and the relevant MIB file must be available and loaded by the agent).
825
Otherwise, these varbinds must
826
be listed explicitly (either here or in the corresponding
827
\fImonitor\fR directive).
829
The \fI-i OID\fR and \fI-o OID\fR options specify additional
830
varbinds to be appended to the notification payload, after the
832
If the monitor entry that triggered this event involved a
833
wildcarded expression, the suffix of the matched instance
834
will be added to any OIDs specified using \fI-o\fR, while OIDs
835
specified using \fI-i\fR will be treated as exact instances.
836
If the \fI-I\fR flag was specified to the \fImonitor\fR directive,
837
then there is no difference between these two options.
838
.IP "setEvent ENAME [-I] OID = VALUE "
839
defines a set event named ENAME, assigning the (integer) VALUE
840
to the specified OID.
841
This can be triggered from a given \fImonitor\fR entry by specifying
842
the option \fI-e ENAME\fR (see above).
844
If the monitor entry that triggered this event involved a
845
wildcarded expression, the suffix of the matched instance
846
will normally be added to the OID.
847
If the \fI-I\fR flag was specified to either of the
848
\fImonitor\fR or \fIsetEvent\fR directives, the
849
specified OID will be regarded as an exact single instance.
850
.IP "strictDisman yes"
851
The definition of SNMP notifications states that the
852
varbinds defined in the OBJECT clause should come first
853
(in the order specified), followed by any "extra" varbinds
854
that the notification generator feels might be useful.
855
The most natural approach would be to associate these
856
mandatory varbinds with the \fInotificationEvent\fR entry,
857
and append any varbinds associated with the monitor entry
858
that triggered the notification to the end of this list.
859
This is the default behaviour of the Net-SNMP Event MIB implementation.
861
Unfortunately, the DisMan Event MIB specifications actually
862
state that the trigger-related varbinds should come \fBfirst\fR,
863
followed by the event-related ones. This directive can be used to
864
restore this strictly-correct (but inappropriate) behaviour.
867
Strict DisMan ordering may result in generating invalid notifications
868
payload lists if the \fInotificationEvent -n\fR flag is used together
869
with \fImonitor -o\fR (or \fI-i\fR) varbind options.
872
If no \fImonitor\fR entries specify payload varbinds,
873
then the setting of this directive is irrelevant.
874
.IP "linkUpDownNotifications yes"
875
will configure the Event MIB tables to monitor the \fCifTable\fR
876
for network interfaces being taken up or down, and triggering
877
a \fIlinkUp\fR or \fIlinkDown\fR notification as appropriate.
879
This is exactly equivalent to the configuration:
883
notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
884
notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
886
monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
887
monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
890
.IP "defaultMonitors yes"
891
will configure the Event MIB tables to monitor the various
892
\fCUCD-SNMP-MIB\fR tables for problems (as indicated by
893
the appropriate \fCxxErrFlag\fR column objects).
895
This is exactly equivalent to the configuration:
899
monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0
900
monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
901
monitor -o extNames -o extOutput "extTable" extResult != 0
902
monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
903
monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
904
monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
908
In both these latter cases, the snmpd.conf must also contain a
909
\fIiquerySecName\fR directive, together with a corresponding
910
\fIcreateUser\fR entry and suitable access control configuration.
911
.SS "DisMan Schedule MIB"
912
The DisMan working group also produced a mechanism for scheduling
913
particular actions (a specified SET assignment) at given times.
914
This requires that the agent was built with support for the
915
\fIdisman/schedule\fR module (which is included as part of the
916
default build configuration for the most recent distribution).
918
There are three ways of specifying the scheduled action:
919
.IP "repeat FREQUENCY OID = VALUE"
920
configures a SET assignment of the (integer) VALUE to the MIB instance
921
OID, to be run every FREQUENCY seconds.
922
.IP "cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE"
923
configures a SET assignment of the (integer) VALUE to the MIB instance
924
OID, to be run at the times specified by the fields MINUTE to WEEKDAY.
925
These follow the same pattern as the equivalent \fIcrontab(5)\fR fields.
928
These fields should be specified as a (comma-separated) list of numeric
929
values. Named values for the MONTH and WEEKDAY fields are not supported,
930
and neither are value ranges. A wildcard match can be specified as '*'.
933
The DAY field can also accept negative values, to indicate days counting
934
backwards from the end of the month.
935
.IP "at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE"
936
configures a one-shot SET assignment, to be run at the first matching
937
time as specified by the fields MINUTE to WEEKDAY. The interpretation
938
of these fields is exactly the same as for the \fIcron\fR directive.
939
.SH "EXTENDING AGENT FUNCTIONALITY"
940
One of the first distinguishing features of the original UCD suite was
941
the ability to extend the functionality of the agent - not just by
942
recompiling with code for new MIB modules, but also by configuring the running agent to
943
report additional information. There are a number of techniques to
944
support this, including:
946
running external commands (\fIexec\fR, \fIextend\fR, \fIpass\fR)
948
loading new code dynamically (embedded perl, \fIdlmod\fR)
950
communicating with other agents (\fIproxy\fR, SMUX, AgentX)
951
.SS "Arbitrary Extension Commands"
952
The earliest extension mechanism was the ability to run arbitrary
953
commands or shell scripts. Such commands do not need to be aware of
954
SNMP operations, or conform to any particular behaviour - the MIB
955
structures are designed to accommodate any form of command output.
956
Use of this mechanism requires that the agent was built with support for the
957
\fIucd-snmp/extensible\fR and/or \fIagent/extend\fR modules (which
958
are both included as part of the default build configuration).
959
.IP "exec [MIBOID] NAME PROG ARGS"
960
.IP "sh [MIBOID] NAME PROG ARGS"
961
invoke the named PROG with arguments of ARGS. By default the exit
962
status and first line of output from the command will be reported via
963
the \fCextTable\fR, discarding any additional output.
966
Entries in this table appear in the order they are read from the
967
configuration file. This means that adding new \fIexec\fR (or \fIsh\fR)
968
directives and restarting the agent, may affect the indexing of other
972
The PROG argument for \fIexec\fR directives must be a full path
973
to a real binary, as it is executed via the exec() system call.
974
To invoke a shell script, use the \fIsh\fR directive instead.
976
If MIBOID is specified, then the results will be rooted at this point
977
in the OID tree, returning the exit statement as MIBOID.ERRORFLAG.0
978
and the entire command output in a pseudo-table based at
979
MIBNUM.ERRORMSG - with one 'row' for each line of output.
982
The layout of this "relocatable" form of \fIexec\fR (or \fIsh\fR) output
983
does not strictly form a valid MIB structure. This mechanism is being
984
deprecated - please see the \fIextend\fR directive (described below) instead.
987
The agent does not cache the exit status or output of the executed program.
989
.\" XXX - Is this still true ??
991
.IP "execfix NAME PROG ARGS"
992
registers a command that can be invoked on demand - typically to respond
993
to or fix errors with the corresponding \fIexec\fR or \fIsh\fR entry.
994
When the \fIextErrFix\fR instance for a given NAMEd entry is set to the
995
integer value of 1, this command will be called.
998
This directive can only be used in combination with a corresponding
999
\fIexec\fR or \fIsh\fR directive, which must be defined first.
1000
Attempting to define an unaccompanied \fIexecfix\fR directive will fail.
1003
\fIexec\fR and \fIsh\fR extensions can only be configured via the
1004
snmpd.conf file. They cannot be set up via SNMP SET requests.
1005
.IP "extend [MIBOID] NAME PROG ARGS"
1006
works in a similar manner to the \fIexec\fR directive, but with a number
1007
of improvements. The MIB tables (\fInsExtendConfigTable\fR
1008
etc) are indexed by the NAME token, so are unaffected by the order in
1009
which entries are read from the configuration files.
1010
There are \fItwo\fR result tables - one (\fInsExtendOutput1Table\fR)
1011
containing the exit status, the first line and full output (as a single string)
1012
for each \fIextend\fR entry, and the other (\fInsExtendOutput2Table\fR)
1013
containing the complete output as a series of separate lines.
1015
If MIBOID is specified, then the configuration and result tables will be rooted
1016
at this point in the OID tree, but are otherwise structured in exactly
1017
the same way. This means that several separate \fIextend\fR
1018
directives can specify the same MIBOID root, without conflicting.
1020
The exit status and output is cached for each entry individually, and
1021
can be cleared (and the caching behaviour configured)
1022
using the \fCnsCacheTable\fR.
1023
.IP "extendfix NAME PROG ARGS"
1024
registers a command that can be invoked on demand, by setting the
1025
appropriate \fInsExtendRunType\fR instance to the value
1026
\fIrun-command(3)\fR. Unlike the equivalent \fIexecfix\fR,
1027
this directive does not need to be paired with a corresponding
1028
\fIextend\fR entry, and can appear on its own.
1030
Both \fIextend\fR and \fIextendfix\fR directives can be configured
1031
dynamically, using SNMP SET requests to the NET-SNMP-EXTEND-MIB.
1032
.SS "MIB-Specific Extension Commands"
1033
The first group of extension directives invoke arbitrary commands,
1034
and rely on the MIB structure (and management applications) having
1035
the flexibility to accommodate and interpret the output. This is a
1036
convenient way to make information available quickly and simply, but
1037
is of no use when implementing specific MIB objects, where the extension
1038
must conform to the structure of the MIB (rather than vice versa).
1039
The remaining extension mechanisms are all concerned with such
1040
MIB-specific situations - starting with "pass-through" scripts.
1041
Use of this mechanism requires that the agent was built with support for the
1042
\fIucd-snmp/pass\fR and \fIucd-snmp/pass_persist\fR modules (which
1043
are both included as part of the default build configuration).
1044
.IP "pass [-p priority] MIBOID PROG"
1045
will pass control of the subtree rooted at MIBOID to the specified
1046
PROG command. GET and GETNEXT requests for OIDs within this tree will
1047
trigger this command, called as:
1055
respectively, where OID is the requested OID.
1056
The PROG command should return the response varbind as three separate
1057
lines printed to stdout - the first line should be the OID of the returned
1058
value, the second should be its TYPE (one of the text strings
1059
.B integer, gauge, counter, timeticks, ipaddress, objectid,
1062
), and the third should be the value itself.
1064
If the command cannot return an appropriate varbind - e.g the specified
1065
OID did not correspond to a valid instance for a GET request, or there
1066
were no following instances for a GETNEXT - then it should exit without
1067
producing any output. This will result in an SNMP \fInoSuchName\fR
1068
error, or a \fInoSuchInstance\fR exception.
1072
The SMIv2 type \fBcounter64\fR
1073
and SNMPv2 \fInoSuchObject\fR exception are not supported.
1077
A SET request will result in the command being called as:
1080
PROG -s OID TYPE VALUE
1083
where TYPE is one of the tokens listed above, indicating the type of the
1084
value passed as the third parameter.
1091
.\") syntax objects are not valid for SETs
1095
If the assignment is successful, the PROG command should exit without producing
1096
any output. Errors should be indicated by writing one of the strings
1101
and the agent will generate the appropriate error response.
1105
The other SNMPv2 errors are not supported.
1109
In either case, the command should exit once it has finished processing.
1110
Each request (and each varbind within a single request) will trigger
1111
a separate invocation of the command.
1113
The default registration priority is 127. This can be
1114
changed by supplying the optional -p flag, with lower priority
1115
registrations being used in preference to higher priority values.
1116
.IP "pass_persist [-p priority] MIBOID PROG"
1117
will also pass control of the subtree rooted at MIBOID to the specified
1118
PROG command. However this command will continue to run after the initial
1119
request has been answered, so subsequent requests can be processed without
1120
the startup overheads.
1122
Upon initialization, PROG will be passed the string "PING\\n" on stdin,
1123
and should respond by printing "PONG\\n" to stdout.
1125
For GET and GETNEXT requests, PROG will be passed two lines on stdin,
1126
the command (\fIget\fR or \fIgetnext\fR) and the requested OID.
1127
It should respond by printing three lines to stdout -
1128
the OID for the result varbind, the TYPE and the VALUE itself -
1129
exactly as for the \fIpass\fR directive above.
1130
If the command cannot return an appropriate varbind,
1131
it should print print "NONE\\n" to stdout (but continue running).
1133
For SET requests, PROG will be passed three lines on stdin,
1134
the command (\fIset\fR) and the requested OID,
1135
followed by the type and value (both on the same line).
1136
If the assignment is successful, the command should print
1137
"DONE\\n" to stdout.
1138
Errors should be indicated by writing one of the strings
1144
.B inconsistent-value
1146
and the agent will generate the appropriate error response.
1147
In either case, the command should continue running.
1149
The registration priority can be changed using the optional
1150
-p flag, just as for the \fIpass\fR directive.
1152
\fIpass\fR and \fIpass_persist\fR extensions can only be configured via the
1153
snmpd.conf file. They cannot be set up via SNMP SET requests.
1155
.\" XXX - caching ??
1157
.SS "Embedded Perl Support"
1158
Programs using the previous extension mechanisms can be written in any convenient
1159
programming language - including perl, which is a common choice for
1160
pass-through extensions in particular. However the Net-SNMP agent
1161
also includes support for embedded perl technology (similar to
1162
\fImod_perl\fR for the Apache web server). This allows the agent
1163
to interpret perl scripts directly, thus avoiding the overhead of
1164
spawning processes and initializing the perl system when a request is received.
1166
Use of this mechanism requires that the agent was built with support for the embedded
1167
perl mechanism, which is not part of the default build environment. It
1168
must be explicitly included by specifying the '--enable-embedded-perl'
1169
option to the configure script when the package is first built.
1171
If enabled, the following directives will be recognised:
1172
.IP "disablePerl true"
1173
will turn off embedded perl support entirely (e.g. if there are problems
1174
with the perl installation).
1175
.IP "perlInitFile FILE"
1176
loads the specified initialisation file (if present)
1177
immediately before the first \fIperl\fR directive is parsed.
1178
If not explicitly specified, the agent will look for the default
1179
initialisation file DATADIR/snmp/snmp_perl.pl.
1181
The default initialisation file
1182
creates an instance of a \fCNetSNMP::agent\fR object - a variable
1183
\fC$agent\fR which can be used to register perl-based MIB handler routines.
1184
.IP "perl EXPRESSION"
1185
evaluates the given expression. This would typically register a
1186
handler routine to be called when a section of the OID tree was
1191
\fCperl use Data::Dumper;
1192
perl sub myroutine { print "got called: ",Dumper(@_),"\\n"; }
1193
perl $agent->register('mylink', '.1.3.6.1.8765', \\&myroutine);\fR
1198
This expression could also source an external file:
1201
\fCperl 'do /path/to/file.pl';\fR
1205
or perform any other perl-based processing that might be required.
1207
.\" Link to more examples
1209
.SS Dynamically Loadable Modules
1210
Most of the MIBs supported by the Net-SNMP agent are implemented as
1211
C code modules, which were compiled and linked into the agent libraries
1212
when the suite was first built. Such implementation modules can also be
1213
compiled independently and loaded into the running agent once it has
1214
started. Use of this mechanism requires that the agent was built with support for the
1215
\fIucd-snmp/dlmod\fR module (which is included as part of the default
1216
build configuration).
1217
.IP "dlmod NAME PATH"
1218
will load the shared object module from the file PATH (an absolute
1219
filename), and call the initialisation routine \fIinit_NAME\fR.
1222
If the specified PATH is not a fully qualified filename, it will
1223
be interpreted relative to LIBDIR/snmp/dlmod, and \fC.so\fR
1224
will be appended to the filename.
1227
This functionality can also be configured using SNMP SET requests
1228
to the UCD-DLMOD-MIB.
1230
Another mechanism for extending the functionality of the agent
1231
is to pass selected requests (or selected varbinds) to another
1232
SNMP agent, which can be running on the same host (presumably
1233
listening on a different port), or on a remote system.
1234
This can be viewed either as the main agent delegating requests to
1235
the remote one, or acting as a proxy for it.
1236
Use of this mechanism requires that the agent was built with support for the
1237
\fIucd-snmp/proxy\fR module (which is included as part of the
1238
default build configuration).
1239
.IP "proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]"
1240
will pass any incoming requests under OID to the agent listening
1241
on the port specified by the transport address HOST.
1243
.B LISTENING ADDRESSES
1246
manual page for more information about the format of listening
1250
To proxy the entire MIB tree, use the OID .1.3
1251
(\fBnot\fR the top-level .1)
1254
The \fISNMPCMD_ARGS\fR should provide sufficient version and
1255
administrative information to generate a valid SNMP request
1256
(see \fIsnmpcmd(1)\fR).
1258
The proxied request will \fInot\fR use the administrative
1259
settings from the original request.
1262
If a CONTEXTNAME is specified, this will register the proxy
1263
delegation within the named context in the local agent.
1264
Defining multiple \fIproxy\fR directives for the same OID but
1265
different contexts can be used to query several remote agents
1266
through a single proxy, by specifying the appropriate SNMPv3
1267
context in the incoming request (or using suitable configured
1268
community strings - see the \fIcom2sec\fR directive).
1270
Specifying the REMOID parameter will map the local MIB tree
1271
rooted at OID to an equivalent subtree rooted at REMOID
1272
on the remote agent.
1274
The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
1275
with SMUX-based subagents (such as \fIgated\fR, \fIzebra\fR or \fIquagga\fR).
1276
Use of this mechanism requires that the agent was built with support for the
1277
\fIsmux\fR module, which is not part of the default build environment, and
1278
must be explicitly included by specifying the '--with-mib-modules=smux'
1279
option to the configure script when the package is first built.
1282
This extension protocol has been officially deprecated in
1283
favour of AgentX (see below).
1285
.IP "smuxpeer OID PASS"
1286
will register a subtree for SMUX-based processing, to be
1287
authenticated using the password PASS. If a subagent
1288
(or "peer") connects to the agent and registers this subtree
1290
.\" Or a subtree of this subtree ??
1292
then requests for OIDs within it will be passed to that
1293
SMUX subagent for processing.
1295
A suitable entry for an OSPF routing daemon (such as \fIgated\fR,
1296
\fIzebra\fR or \fIquagga\fR) might be something like
1299
.I smuxpeer .1.3.6.1.2.1.14 ospf_pass
1302
.IP "smuxsocket <IPv4-address>"
1303
defines the IPv4 address for SMUX peers to communicate with the Net-SNMP agent.
1304
The default is to listen on all IPv4 interfaces ("0.0.0.0"), unless the
1305
package has been configured with "--enable-local-smux" at build time, which
1306
causes it to only listen on 127.0.0.1 by default. SMUX uses the well-known
1309
Note the Net-SNMP agent will only operate as a SMUX \fImaster\fR
1310
agent. It does not support acting in a SMUX subagent role.
1311
.SS AgentX Sub-Agents
1312
The Net-SNMP agent supports the AgentX protocol (RFC 2741) in
1313
both master and subagent roles.
1314
Use of this mechanism requires that the agent was built with support for the
1315
\fIagentx\fR module (which is included as part of the
1316
default build configuration), and also that this support is
1317
explicitly enabled (e.g. via the \fIsnmpd.conf\fR file).
1319
There are two directives specifically relevant to running as
1320
an AgentX master agent:
1322
will enable the AgentX functionality and cause the agent to
1323
start listening for incoming AgentX registrations.
1324
This can also be activated by specifying the '-x' command-line
1325
option (to specify an alternative listening socket).
1326
.IP "agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]"
1327
Defines the permissions and ownership of the AgentX Unix Domain socket,
1328
and the parent directories of this socket.
1329
SOCKPERMS and DIRPERMS must be octal digits (see
1331
). By default this socket will only be accessible to subagents which
1332
have the same userid as the agent.
1334
There is one directive specifically relevant to running as
1335
an AgentX sub-agent:
1336
.IP "agentXPingInterval NUM"
1337
will make the subagent try and reconnect every NUM seconds to the
1338
master if it ever becomes (or starts) disconnected.
1340
The remaining directives are relevant to both AgentX master
1342
.IP "agentXSocket [<transport-specifier>:]<transport-address>[,...]"
1343
defines the address the master agent listens at, or the subagent
1345
The default is the Unix Domain socket \fCAGENTX_SOCKET\fR.
1346
Another common alternative is \fCtcp:localhost:705\fR.
1348
.B LISTENING ADDRESSES
1351
manual page for more information about the format of addresses.
1354
Specifying an AgentX socket does \fBnot\fR automatically enable
1355
AgentX functionality (unlike the '-x' command-line option).
1357
.IP "agentXTimeout NUM"
1358
defines the timeout period (NUM seconds) for an AgentX request.
1359
Default is 1 second.
1360
.IP "agentXRetries NUM"
1361
defines the number of retries for an AgentX request.
1362
Default is 5 retries.
1364
net-snmp ships with both C and Perl APIs to develop your own AgentX
1366
.SH "OTHER CONFIGURATION"
1367
.IP "override [-rw] OID TYPE VALUE"
1368
This directive allows you to override a particular OID with a
1369
different value (and possibly a different type of value). The -rw
1370
flag will allow snmp SETs to modify it's value as well. (note that if
1371
you're overriding original functionality, that functionality will be
1372
entirely lost. Thus SETS will do nothing more than modify the
1373
internal overridden value and will not perform any of the original
1374
functionality intended to be provided by the MIB object. It's an
1375
emulation only.) An example:
1378
\fCoverride sysDescr.0 octet_str "my own sysDescr"\fR
1381
That line will set the sysDescr.0 value to "my own sysDescr" as well
1382
as make it modifiable with SNMP SETs as well (which is actually
1383
illegal according to the MIB specifications).
1385
Note that care must be taken when using this. For example, if you try
1386
to override a property of the 3rd interface in the ifTable with a new
1387
value and later the numbering within the ifTable changes it's index
1388
ordering you'll end up with problems and your modified value won't
1389
appear in the right place in the table.
1391
Valid TYPEs are: integer, uinteger, octet_str, object_id, counter,
1392
null (for gauges, use "uinteger"; for bit strings, use "octet_str").
1393
Note that setting an object to "null" effectively delete's it as being
1394
accessible. No VALUE needs to be given if the object type is null.
1396
More types should be available in the future.
1398
If you're trying to figure out aspects of the various mib modules
1399
(possibly some that you've added yourself), the following may help you
1400
spit out some useful debugging information. First off, please read
1401
the snmpd manual page on the -D flag. Then the following
1402
configuration snmpd.conf token, combined with the -D flag, can produce
1404
.IP "injectHandler HANDLER modulename"
1405
This will insert new handlers into the section of the mib tree
1406
referenced by "modulename". The types of handlers available for
1410
Caches information returned from the lower level. This
1411
greatly help the performance of the agent, at the cost
1412
of caching the data such that its no longer "live" for
1413
30 seconds (in this future, this will be configurable).
1414
Note that this means snmpd will use more memory as well
1415
while the information is cached. Currently this only
1416
works for handlers registered using the table_iterator
1417
support, which is only a few mib tables. To use it,
1418
you need to make sure to install it before the
1419
table_iterator point in the chain, so to do this:
1421
\fCinjectHandler stash_cache NAME table_iterator\fR
1423
If you want a table to play with, try walking the
1424
\fCnsModuleTable\fR with and without this injected.
1427
Prints out lots of debugging information when
1428
the -Dhelper:debug flag is passed to the snmpd
1432
Forces turning off write support for the given module.
1435
If a module is failing to handle multiple requests
1436
properly (using the new 5.0 module API), this will force
1437
the module to only receive one request at a time.
1440
If a module registers to handle getbulk support, but
1441
for some reason is failing to implement it properly,
1442
this module will convert all getbulk requests to
1443
getnext requests before the final module receives it.
1445
.IP "dontLogTCPWrappersConnects"
1446
If the \fBsnmpd\fR was compiled with TCP Wrapper support, it
1447
logs every connection made to the agent. This setting disables
1448
the log messages for accepted connections. Denied connections will
1450
.IP "Figuring out module names"
1451
To figure out which modules you can inject things into,
1452
run \fBsnmpwalk\fR on the \fCnsModuleTable\fR which will give
1453
a list of all named modules registered within the agent.
1454
.SS Internal Data tables
1456
.\" XXX: To Document
1457
.IP "add_row NAME INDEX(ES) VALUE(S)"
1458
.\" XXX: To Document
1461
The Net-SNMP agent can be instructed to re-read the various configuration files,
1462
either via an \fBsnmpset\fR assignment of integer(1) to
1463
\fCUCD-SNMP-MIB::versionUpdateConfig.0\fR (.1.3.6.1.4.1.2021.100.11.0),
1464
or by sending a \fBkill -HUP\fR signal to the agent process.
1466
All directives listed with a value of "yes" actually accept a range
1467
of boolean values. These will accept any of \fI1\fR, \fIyes\fR or
1468
\fItrue\fR to enable the corresponding behaviour,
1469
or any of \fI0\fR, \fIno\fR or \fIfalse\fR to disable it.
1470
The default in each case is for the feature to be turned off, so these
1471
directives are typically only used to enable the appropriate behaviour.
1472
.SH "EXAMPLE CONFIGURATION FILE"
1473
See the EXAMPLE.CONF file in the top level source directory for a more
1474
detailed example of how the above information is used in real
1477
SYSCONFDIR/snmp/snmpd.conf
1479
snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, read_config(3).
1480
.\" Local Variables:
added
removed
.pc/56_manpage.patch/man/snmpd.conf.5.def
