1
.TH SNMPD.EXAMPLES 5 "05 Dec 2005" VVERSIONINFO "Net-SNMP"
4
snmpd.examples - example configuration for the Net-SNMP agent
8
man page defines the syntax and behaviour of the various
9
configuration directives that can be used to control the
10
operation of the Net-SNMP agent, and the management information
13
This companion man page illustrates these directives, showing
14
some practical examples of how they might be used.
16
.SS "Listening addresses"
17
The default agent behaviour (listing on the standard SNMP UDP port on
18
all interfaces) is equivalent to the directive:
26
The agent can be configured to \fIonly\fR accept requests sent to the
27
local loopback interface (again listening on the SNMP UDP port), using:
29
agentaddress localhost:161 \fI# (udp implicit)\fR
33
agentaddress 127.0.0.1 \fI# (udp and standard port implicit)\fR
35
It can be configured to accept both UDP and TCP requests (over both IPv4
38
agentaddress udp:161,tcp:161,udp6:161,tcp6:161
41
.\" Can the agent handle the same port for both IPv4 & IPv6
43
Other combinations are also valid.
44
.SS "Run-time privileges"
45
The agent can be configured to relinquish any privileged access once it
46
has opened the initial listening ports. Given a suitable "snmp" group
47
(defined in \fI/etc/group\fR), this could be done using the directives:
54
A similar effect could be achieved using numeric UID and/or GID values:
62
.\" What effect will/may this have on the information returned.
63
.\" ??? Mention this in the main man page.
65
.SS SNMPv3 Configuration
66
Rather than being generated pseudo-randomly,
67
the engine ID for the agent could be calculated based on the MAC address
68
of the second network interface (\fIeth1\fR), using the directives:
73
or it could be calculated from the (first) IP address, using:
77
or it could be specified explicitly, using:
79
engineID "XXX - WHAT FORMAT"
82
.\" Does engineID override the other directives, or what?
86
The following directives will create three users, all using exactly
87
the same authentication and encryption settings:
90
createUser me MD5 "single pass phrase"
91
createUser myself MD5 "single pass phrase" DES
92
createUser andI MD5 "single pass phrase" DES "single pass phrase"
95
Note that this defines three \fIdistinct\fR users, who could be granted
96
different levels of access. Changing the passphrase for any one of
97
these would not affect the other two.
99
Separate pass phrases can be specified for authentication and
102
createUser onering SHA "to rule them all" AES "to bind them"
104
Remember that these \fIcreateUser\fR directives should be defined in the
105
PERSISTENT_DIRECTORY/snmpd.conf file, rather than the usual location.
108
.\" ??? Illustrate "-e", "-l" and "-m" forms ??
110
.SS Traditional Access Control
111
The SNMPv3 users defined above can be granted access to the full
112
MIB tree using the directives:
119
Or selective access to individual subtrees using:
122
rouser myself .1.3.6.1.2
127
Note that a combination repeating the same user, such as:
134
should \fBnot\fR be used. This would configure the user \fIonering\fR
135
with read-only access (and ignore the \fIrwuser\fR entry altogether).
136
The same holds for the community-based directives.
145
would define the commonly-expected read and write community strings
146
for SNMPv1 and SNMPv2c requests. This behaviour is \fBnot\fR
147
configured by default, and would need to be set up explicitly.
150
It would also be a very good idea to change \fIprivate\fR to something
151
a little less predictable!
154
A slightly less vulnerable configuration might restrict what information
157
rocommunity public default system
159
or the management systems that settings could be manipulated from:
161
rwcommunity private 10.10.10.0/24
163
or a combination of the two.
164
.SS VACM Configuration
165
This last pair of settings are equivalent to the full VACM definitions:
168
\fI# sec.name source community\fR
169
com2sec public default public
170
com2sec mynet 10.10.10.0/24 private
171
com2sec6 mynet fec0::/64 private
173
\fI# sec.model sec.name\fR
174
group worldGroup v1 public
175
group worldGroup v2c public
176
group myGroup v1 mynet
177
group myGroup v2c mynet
179
\fI# incl/excl subtree [mask]\fR
181
view sysView included system
183
\fI# context model level prefix read write notify (unused)\fR
184
access worldGroup "" any noauth exact system none none
185
access myGroup "" any noauth exact all all none
189
There are several points to note in this example:
191
The \fIgroup\fR directives must be repeated for
192
both SNMPv1 and SNMPv2c requests.
194
The \fIcom2sec\fR security name is distinct from the community
195
string that is mapped to it. They can be the same ("public")
196
or different ("mynet"/"private") - but what appears in the
197
\fIgroup\fR directive is the security name, regardless of
198
the original community string.
200
Both of the \fIview\fR directives are defining simple OID
201
subtrees, so neither of these require an explicit mask.
202
The same holds for the "combined subtree2 view defined below.
203
In fact, a mask field is only needed when defining row slices
204
across a table (or similar views), and can almost always be omitted.
206
In general, it is advisible not to mix traditional and VACM-based
207
access configuration settings, as these can sometimes interfere
208
with each other in unexpected ways. Choose a particular style
209
of access configuration, and stick to it.
211
.\" Mention/use hardwired views '_all_' and '_none_'
213
.\" Illustrate other, more flexible configurations
214
.\" including SNMPv3 access.
216
.SS Typed-View Configuration
217
A similar configuration could also be configured as follows:
220
view sys2View included system
221
view sys2View included .1.3.6.1.2.1.25.1
223
authcommunity read public default -v sys2View
224
authcommunity read,write private 10.10.10.0/8
228
This mechanism allows multi-subtree (or other non-simple) views to
229
be used with the one-line \fIrocommunity\fR style of configuration.
231
It would also support configuring "write-only" access, should this
234
.\" Expand this example
236
.SH SYSTEM INFORMATION
238
The full contents of the 'system' group (with the exception of \fCsysUpTime\fR)
239
can be explicitly configured using:
242
\fI# Override 'uname -a' and hardcoded system OID - inherently read-only values\fR
243
sysDescr Universal Turing Machine mk I
244
sysObjectID .1.3.6.1.4.1.8072.3.2.1066
246
\fI# Override default values from 'configure' - makes these objects read-only\fR
247
sysContact Alan.Turing@pre-cs.man.ac.uk
248
sysName tortoise.turing.com
249
sysLocation An idea in the mind of AT
251
\fI# Standard end-host behaviour\fR
255
.SS Host Resources Group
256
The list of devices probed for potential inclusion in the
257
\fChrDiskStorageTable\fR (and \fChrDeviceTable\fR) can be amended using
258
any of the following directives:
260
ignoredisk /dev/rdsk/c0t2d0
262
which prevents the device \fI/dev/rdsk/c0t2d0\fR from being scanned,
265
ignoredisk /dev/rdsk/c0t[!6]d0
266
ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0
269
either of which prevents all devices \fI/dev/rdsk/c0t\fRX\fId0\fR
270
(except .../\fIc0t6d0\fR) from being scanned,
272
ignoredisk /dev/rdsk/c1*
274
which prevents all devices whose device names start with \fI/dev/rdsk/c1\fR
275
from being scanned, or
277
ignoredisk /dev/rdsk/c?t0d0
279
which prevents all devices \fI/dev/rdsk/c\fRX\fIt0d0\fR
280
(where 'X' is any single character) from being scanned.
281
.SS Process Monitoring
282
The list of services running on a system can be monitored
283
(and provision made for correcting any problems), using:
286
\fI# At least one web server process must be running at all times\fR
288
procfix httpd /etc/rc.d/init.d/httpd restart
290
\fI# There should never be more than 10 mail processes running
291
# (more implies a probable mail storm, so shut down the mail system)\fR
293
procfix sendmail /etc/rc.d/init.d/sendmail stop
295
\fI# There should be a single network management agent running
296
# ("There can be only one")\fR
300
Also see the "DisMan Event MIB" section later on.
301
.SS Disk Usage Monitoring
302
The state of disk storage can be monitored using:
308
\fI# Keep 100 Mb free for crash dumps\fR
309
disk /mnt/crash 100000
312
.SS System Load Monitoring
313
A simple check for an overloaded system might be:
317
A more refined check (to allow brief periods of heavy use,
318
but recognise sustained medium-heavy load) might be:
322
.SS Log File Monitoring
328
logmatch NAME PATH CYCLETIME REGEX
330
.SH "ACTIVE MONITORING"
331
.SS "Notification Handling"
332
Configuring the agent to report invalid access attempts might be done by:
340
Alternatively, the second and third directives could be combined
341
(and an acknowledgement requested) using:
343
informsink localhost public
345
A configuration with repeated sink destinations, such as:
353
should \fBNOT\fR be used, as this will cause multiple copies
354
of each trap to be sent to the same trap receiver.
356
.I "TODO - discuss SNMPv3 traps"
358
trapsess \fIsnmpv3 options\fR localhost:162
361
.I "TODO - mention trapd access configuration"
363
.SS "DisMan Event MIB"
364
The simplest configuration for active self-monitoring of
365
the agent, by the agent, for the agent, is probably:
368
\fI# Set up the credentials to retrieve monitored values\fR
369
createUser _internal MD5 "the first sign of madness"
370
iquerySecName _internal
373
\fI# Active the standard monitoring entries\fR
375
linkUpDownNotifications yes
377
\fI# If there's a problem, then tell someone!\fR
382
The first block sets up a suitable user for retrieving the
383
information to by monitored, while the following pair of
384
directives activates various built-in monitoring entries.
386
Note that the DisMan directives are not themselves sufficient to
387
actively report problems - there also needs to be a suitable
388
destination configured to actually send the resulting notifications to.
390
A more detailed monitor example is given by:
392
monitor -u me -o hrSWRunName "high process memory" hrSWRunPerfMem > 10000
395
This defines an explicit boolean monitor entry, looking for any process
396
using more than 10Mb of active memory. Such processes will be reported
397
using the (standard) DisMan trap \fCmteTriggerFired\fR,
398
but adding an extra (wildcarded) varbind \fChrSWRunName\fR.
400
This entry also specifies an explicit user (\fIme\fR, as defined
401
earlier) for retrieving the monitored values, and building the trap.
403
Objects that could potentially fluctuate around the specified level
404
are better monitored using a threshold monitor entry:
406
monitor -D -r 10 "network traffic" ifInOctets 1000000 5000000
409
This will send a \fCmteTriggerRising\fR trap whenever the incoming
410
traffic rises above (roughly) 500 kB/s on any network interface,
411
and a corresponding \fCmteTriggerFalling\fR trap when it falls below
414
Note that this monitors the deltas between successive samples (\fI-D\fR)
415
rather than the actual sample values themselves. The same effect
416
could be obtained using:
418
monitor -r 10 "network traffic" ifInOctets - - 1000000 5000000
421
The \fIlinkUpDownNotifications\fR directive above is broadly
425
notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
426
notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
428
monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
429
monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
433
This defines the traps to be sent (using \fInotificationEvent\fR),
434
and explicitly references the relevant notification in the corresponding
435
monitor entry (rather than using the default DisMan traps).
437
The \fIdefaultMonitors\fR directive above is equivalent to a series
438
of (boolean) monitor entries:
441
monitor -o prNames -o prErrMessage "procTable" prErrorFlag != 0
442
monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
443
monitor -o extNames -o extOutput "extTable" extResult != 0
444
monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
445
monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
446
monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
449
and will send a trap whenever any of these entries indicate a problem.
451
An alternative approach would be to automatically invoke the corresponding
455
setEvent prFixIt prErrFix = 1
456
monitor -e prFixIt "procTable" prErrorFlag != 0
459
(and similarly for any of the other \fIdefaultMonitor\fR entries).
460
.SS "DisMan Schedule MIB"
461
The agent could be configured to reload its configuration
464
repeat 3600 versionUpdateConfig.0 = 1
467
Alternatively this could be configured to be run at specific
468
times of day (perhaps following rotation of the logs):
470
cron 10 0 * * * versionUpdateConfig.0 = 1
473
The one-shot style of scheduling is rather less common, but the
474
secret SNMP virus could be activated on the next occurance of Friday 13th using:
476
at 13 13 13 * 5 snmpVirus.0 = 1
478
.SH "EXTENDING AGENT FUNCTIONALITY"
479
.SS "Arbitrary Extension Commands"
483
exec [MIBOID] NAME PROG ARGS"
484
sh [MIBOID] NAME PROG ARGS"
485
execfix NAME PROG ARGS"
491
extend [MIBOID] NAME PROG ARGS"
492
extendfix [MIBOID] NAME PROG ARGS"
495
.SS "MIB-Specific Extension Commands"
498
"pass [-p priority] MIBOID PROG"
503
"pass_persist [-p priority] MIBOID PROG"
505
.SS "Embedded Perl Support"
506
If embedded perl support is enabled in the agent, the default
507
initialisation is equivalent to the directives:
511
perlInitFile DATADIR/snmp/snmp_perl.pl
514
The main mechanism for defining embedded perl scripts is the
515
\fIperl\fR directive. A very simple (if somewhat pointless)
516
MIB handler could be registered using:
519
perl use Data::Dumper;
520
perl sub myroutine { print "got called: ",Dumper(@_),"\\n"; }
521
perl $agent->register('mylink', '.1.3.6.1.8765', \\&myroutine);
525
This relies on the \fI$agent\fR object, defined in the example
526
\fCsnmp_perl.pl\fR file.
528
A more realistic MIB handler might be:
534
Alternatively, this code could be stored in an external file,
537
perl 'do DATADIR/snmp/perl_example.pl';
540
.\" XXX - does this last entry need the quotes ??
542
.SS Dynamically Loadable Modules
548
A configuration for acting as a simple proxy for two other
549
SNMP agents (running on remote systems) might be:
552
com2sec -Cn rem1context rem1user default remotehost1
553
com2sec -Cn rem2context rem2user default remotehost2
555
proxy -Cn rem1context -v 1 -c public remotehost1 .1.3
556
proxy -Cn rem2context -v 1 -c public remotehost2 .1.3
559
(plus suitable access control entries).
561
The same \fIproxy\fR directives would also work with
562
(incoming) SNMPv3 requests, which can specify a context directly.
563
It would probably be more sensible to use contexts of
564
\fIremotehost1\fR and \fIremotehost2\fR - the names above were
565
chosen to indicate how these directives work together.
567
Note that the administrative settings for the proxied request
568
are specified explicitly, and are independent of the settings
569
from the incoming request.
571
An alternative use for the \fiproxy\fR directive is to pass
572
part of the OID tree to another agent (either on a remote host
573
or listening on a different port on the same system),
574
while handling the rest internally:
576
proxy -v 1 -c public localhost:6161 .1.3.6.1.4.1.99
578
This mechanism can be used to link together two separate SNMP agents.
580
A less usual approach is to map one subtree into a different area
581
of the overall MIB tree (either locally or on a remote system):
584
\fI# uses SNMPv3 to access the MIB tree .1.3.6.1.2.1.1 on 'remotehost'
585
# and maps this to the local tree .1.3.6.1.3.10\fR
586
proxy -v 3 -l noAuthNoPriv -u user remotehost .1.3.6.1.3.10 .1.3.6.1.2.1.1
592
smuxsocket [<transport-specifier>:]<transport-address>[,...]"
593
smuxpeer .1.3.6.1.2.1.14 ospf_pass
596
.SS AgentX Sub-Agents
597
The Net-SNMP agent could be configured to operate as an AgentX master
598
agent (listening on a non-standard named socket, and running using
599
the access privileges defined earlier), using:
603
agentXSocket /tmp/agentx/master
604
agentXPerms 0660 0550 nobody snmp
608
.\" XXX - do numeric UID/GID take a leading '#' ??
611
A sub-agent wishing to connect to this master agent would need
612
the same \fIagentXSocket\fR directive, or the equivalent code:
615
netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_X_SOCKET,
616
"/tmp/agentx/master");
620
A loopback networked AgentX configuration could be set up using:
623
agentXSocket tcp:localhost:705
628
on the master side, and:
631
agentXSocket tcp:localhost:705
634
agentPingInterval 600
639
Note that the timeout and retry settings can be asymmetric
640
for the two directions, and the sub-agent can poll the master agent
641
at regular intervals (600s = every 10 minutes), to ensure the
642
connection is still working.
643
.SH "OTHER CONFIGURATION"
645
override sysDescr.0 octet_str "my own sysDescr"
648
injectHandler stash_cache NAME table_iterator
651
SYSCONFDIR/snmp/snmpd.conf
653
snmpconf(1), snmpd.conf(5), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, read_config(3).
added
removed
man/snmpd.examples.5.def
