1SNMPD.EXAMPLES(5) Net-SNMP SNMPD.EXAMPLES(5)
2
6 snmpd.examples - example configuration for the Net-SNMP agent
7
9 The snmpd.conf(5) man page defines the syntax and behaviour of the var‐
10 ious configuration directives that can be used to control the operation
11 of the Net-SNMP agent, and the management information it provides.
12 This companion man page illustrates these directives, showing some
14 practical examples of how they might be used.
15
17 Listening addresses
18 The default agent behaviour (listing on the standard SNMP UDP port on
19 all interfaces) is equivalent to the directive:
20 agentaddress udp:161
21 or simply
22 agentaddress 161
23 The agent can be configured to only accept requests sent to the local
24 loopback interface (again listening on the SNMP UDP port), using:
25 agentaddress localhost:161 # (udp implicit)
26 or
27 agentaddress 127.0.0.1 # (udp and standard port implicit)
28 It can be configured to accept both UDP and TCP requests (over both
29 IPv4 and IPv6), using:
30 agentaddress udp:161,tcp:161,udp6:161,tcp6:161
31 Other combinations are also valid.
32 Run-time privileges
34 The agent can be configured to relinquish any privileged access once it
35 has opened the initial listening ports. Given a suitable "snmp" group
36 (defined in /etc/group), this could be done using the directives:
37 agentuser nobody
38 agentgroup snmp
39 A similar effect could be achieved using numeric UID and/or GID values:
40 agentuser #10
41 agentgroup #10
42 SNMPv3 Configuration
44 Rather than being generated pseudo-randomly, the engine ID for the
45 agent could be calculated based on the MAC address of the second net‐
46 work interface (eth1), using the directives:
47 engineIDType 3 engineIDNic eth1
48 or it could be calculated from the (first) IP address, using:
49 engineIDType 1
50 or it could be specified explicitly, using:
51 engineID "XXX - WHAT FORMAT"
52
54 SNMPv3 Users
55 The following directives will create three users, all using exactly the
56 same authentication and encryption settings:
57 createUser me MD5 "single pass phrase"
58 createUser myself MD5 "single pass phrase" DES
59 createUser andI MD5 "single pass phrase" DES "single pass phrase"
60 Note that this defines three distinct users, who could be granted dif‐
61 ferent levels of access. Changing the passphrase for any one of these
62 would not affect the other two.
63 Separate pass phrases can be specified for authentication and encryp‐
65 tion:
66 createUser onering SHA "to rule them all" AES "to bind them"
67 Remember that these createUser directives should be defined in the
68 /var/lib/net-snmp/snmpd.conf file, rather than the usual location.
69 Traditional Access Control
71 The SNMPv3 users defined above can be granted access to the full MIB
72 tree using the directives:
73 rouser me
74 rwuser onering
75 Or selective access to individual subtrees using:
76 rouser myself .1.3.6.1.2
77 rwuser andI system
78 Note that a combination repeating the same user, such as:
80 rouser onering
81 rwuser onering
82 should not be used. This would configure the user onering with read-
83 only access (and ignore the rwuser entry altogether). The same holds
84 for the community-based directives.
85 The directives:
87 rocommunity public
88 rwcommunity private
89 would define the commonly-expected read and write community strings for
90 SNMPv1 and SNMPv2c requests. This behaviour is not configured by
91 default, and would need to be set up explicitly.
92 Note: It would also be a very good idea to change private to
94 something a little less predictable!
95 A slightly less vulnerable configuration might restrict what informa‐
97 tion could be retrieved:
98 rocommunity public default system
99 or the management systems that settings could be manipulated from:
100 rwcommunity private 10.10.10.0/24
101 or a combination of the two.
102 VACM Configuration
104 This last pair of settings are equivalent to the full VACM definitions:
105 # sec.name source community
106 com2sec public default public
107 com2sec mynet 10.10.10.0/24 private
108 com2sec6 mynet fec0::/64 private
109 # sec.model sec.name
111 group worldGroup v1 public
112 group worldGroup v2c public
113 group myGroup v1 mynet
114 group myGroup v2c mynet
115 # incl/excl subtree [mask]
117 view all included .1
118 view sysView included system
119 # context model level prefix read write notify (unused)
121 access worldGroup "" any noauth exact system none none
122 access myGroup "" any noauth exact all all none
123 There are several points to note in this example:
125 The group directives must be repeated for both SNMPv1 and SNMPv2c
127 requests.
128 The com2sec security name is distinct from the community string that is
130 mapped to it. They can be the same ("public") or different
131 ("mynet"/"private") - but what appears in the group directive is the
132 security name, regardless of the original community string.
133 Both of the view directives are defining simple OID subtrees, so nei‐
135 ther of these require an explicit mask. The same holds for the "com‐
136 bined subtree2 view defined below. In fact, a mask field is only
137 needed when defining row slices across a table (or similar views), and
138 can almost always be omitted.
139 In general, it is advisible not to mix traditional and VACM-based
141 access configuration settings, as these can sometimes interfere with
142 each other in unexpected ways. Choose a particular style of access
143 configuration, and stick to it.
144 Typed-View Configuration
146 A similar configuration could also be configured as follows:
147 view sys2View included system
148 view sys2View included .1.3.6.1.2.1.25.1
149 authcommunity read public default -v sys2View
151 authcommunity read,write private 10.10.10.0/8
152 This mechanism allows multi-subtree (or other non-simple) views to be
154 used with the one-line rocommunity style of configuration.
155 It would also support configuring "write-only" access, should this be
157 required.
158
160 System Group
161 The full contents of the 'system' group (with the exception of sysUp‐
162 Time) can be explicitly configured using:
163 # Override 'uname -a' and hardcoded system OID - inherently read-only values
164 sysDescr Universal Turing Machine mk I
165 sysObjectID .1.3.6.1.4.1.8072.3.2.1066
166 # Override default values from 'configure' - makes these objects read-only
168 sysContact Alan.Turing@pre-cs.man.ac.uk
169 sysName tortoise.turing.com
170 sysLocation An idea in the mind of AT
171 # Standard end-host behaviour
173 sysServices 72
174 Host Resources Group
176 The list of devices probed for potential inclusion in the hrDiskStor‐
177 ageTable (and hrDeviceTable) can be amended using any of the following
178 directives:
179 ignoredisk /dev/rdsk/c0t2d0
180 which prevents the device /dev/rdsk/c0t2d0 from being scanned,
181 ignoredisk /dev/rdsk/c0t[!6]d0
182 ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0
183 either of which prevents all devices /dev/rdsk/c0tXd0 (except
184 .../c0t6d0) from being scanned,
185 ignoredisk /dev/rdsk/c1*
186 which prevents all devices whose device names start with /dev/rdsk/c1
187 from being scanned, or
188 ignoredisk /dev/rdsk/c?t0d0
189 which prevents all devices /dev/rdsk/cXt0d0 (where 'X' is any single
190 character) from being scanned.
191 Process Monitoring
193 The list of services running on a system can be monitored (and provi‐
194 sion made for correcting any problems), using:
195 # At least one web server process must be running at all times
196 proc httpd
197 procfix httpd /etc/rc.d/init.d/httpd restart
198 # There should never be more than 10 mail processes running
200 # (more implies a probable mail storm, so shut down the mail system)
201 proc sendmail 10
202 procfix sendmail /etc/rc.d/init.d/sendmail stop
203 # There should be a single network management agent running
205 # ("There can be only one")
206 proc snmpd 1 1
207 Also see the "DisMan Event MIB" section later on.
208 Disk Usage Monitoring
210 The state of disk storage can be monitored using:
211 includeAllDisks 10%
212 disk /var 20%
213 disk /usr 3%
214 # Keep 100 MB free for crash dumps
215 disk /mnt/crash 100000
216 System Load Monitoring
218 A simple check for an overloaded system might be:
219 load 10
220 A more refined check (to allow brief periods of heavy use, but recog‐
221 nise sustained medium-heavy load) might be:
222 load 30 10 5
223 Log File Monitoring
225 TODO
226 file FILE [MAXSIZE]
227 logmatch NAME PATH CYCLETIME REGEX
228
230 Notification Handling
231 Configuring the agent to report invalid access attempts might be done
232 by:
233 authtrapenable 1
234 trapcommunity public
235 trap2sink localhost
236 Alternatively, the second and third directives could be combined (and
237 an acknowledgement requested) using:
238 informsink localhost public
239 A configuration with repeated sink destinations, such as:
240 trapsink localhost
241 trap2sink localhost
242 informsink localhost
243 should NOT be used, as this will cause multiple copies of each trap to
244 be sent to the same trap receiver.
245 TODO - discuss SNMPv3 traps
247 trapsess snmpv3 options localhost:162
248 TODO - mention trapd access configuration
250 DisMan Event MIB
253 The simplest configuration for active self-monitoring of the agent, by
254 the agent, for the agent, is probably:
255 # Set up the credentials to retrieve monitored values
256 createUser _internal MD5 "the first sign of madness"
257 iquerySecName _internal
258 rouser _internal
259 # Active the standard monitoring entries
261 defaultMonitors yes
262 linkUpDownNotifications yes
263 # If there's a problem, then tell someone!
265 trap2sink localhost
266 The first block sets up a suitable user for retrieving the information
268 to by monitored, while the following pair of directives activates vari‐
269 ous built-in monitoring entries.
270 Note that the DisMan directives are not themselves sufficient to
272 actively report problems - there also needs to be a suitable destina‐
273 tion configured to actually send the resulting notifications to.
274 A more detailed monitor example is given by:
276 monitor -u me -o hrSWRunName "high process memory" hrSWRun‐
277 PerfMem > 10000
278 This defines an explicit boolean monitor entry, looking for any process
280 using more than 10MB of active memory. Such processes will be reported
281 using the (standard) DisMan trap mteTriggerFired, but adding an extra
282 (wildcarded) varbind hrSWRunName.
283 This entry also specifies an explicit user (me, as defined earlier) for
285 retrieving the monitored values, and building the trap.
286 Objects that could potentially fluctuate around the specified level are
288 better monitored using a threshold monitor entry:
289 monitor -D -r 10 "network traffic" ifInOctets 1000000 5000000
290 This will send a mteTriggerRising trap whenever the incoming traffic
292 rises above (roughly) 500 kB/s on any network interface, and a corre‐
293 sponding mteTriggerFalling trap when it falls below 100 kB/s again.
294 Note that this monitors the deltas between successive samples (-D)
296 rather than the actual sample values themselves. The same effect could
297 be obtained using:
298 monitor -r 10 "network traffic" ifInOctets - - 1000000 5000000
299 The linkUpDownNotifications directive above is broadly equivalent to:
301 notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus
302 notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus
303 monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2
305 monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
306 This defines the traps to be sent (using notificationEvent), and
308 explicitly references the relevant notification in the corresponding
309 monitor entry (rather than using the default DisMan traps).
310 The defaultMonitors directive above is equivalent to a series of (bool‐
312 ean) monitor entries:
313 monitor -o prNames -o prErrMessage "procTable" prErrorFlag != 0
314 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0
315 monitor -o extNames -o extOutput "extTable" extResult != 0
316 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0
317 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0
318 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
319 and will send a trap whenever any of these entries indicate a problem.
320 An alternative approach would be to automatically invoke the corre‐
322 sponding "fix" action:
323 setEvent prFixIt prErrFix = 1
324 monitor -e prFixIt "procTable" prErrorFlag != 0
325 (and similarly for any of the other defaultMonitor entries).
326 DisMan Schedule MIB
328 The agent could be configured to reload its configuration once an hour,
329 using:
330 repeat 3600 versionUpdateConfig.0 = 1
331 Alternatively this could be configured to be run at specific times of
333 day (perhaps following rotation of the logs):
334 cron 10 0 * * * versionUpdateConfig.0 = 1
335 The one-shot style of scheduling is rather less common, but the secret
337 SNMP virus could be activated on the next occurance of Friday 13th
338 using:
339 at 13 13 13 * 5 snmpVirus.0 = 1
340
342 Arbitrary Extension Commands
343 Old Style
344 exec [MIBOID] NAME PROG ARGS"
345 sh [MIBOID] NAME PROG ARGS"
346 execfix NAME PROG ARGS"
347 New Style
348 extend [MIBOID] NAME PROG ARGS"
349 extendfix [MIBOID] NAME PROG ARGS"
350 MIB-Specific Extension Commands
352 One-Shot
353 "pass [-p priority] MIBOID PROG"
354 Persistent
356 "pass_persist [-p priority] MIBOID PROG"
357 Embedded Perl Support
359 If embedded perl support is enabled in the agent, the default initiali‐
360 sation is equivalent to the directives:
361 disablePerl false
362 perlInitFile /usr/share/snmp/snmp_perl.pl
363 The main mechanism for defining embedded perl scripts is the perl
364 directive. A very simple (if somewhat pointless) MIB handler could be
365 registered using:
366 perl use Data::Dumper;
367 perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
368 perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
369 This relies on the $agent object, defined in the example snmp_perl.pl
371 file.
372 A more realistic MIB handler might be:
374 XXX - WHAT ???
375 Alternatively, this code could be stored in an external file, and
376 loaded using:
377 perl 'do /usr/share/snmp/perl_example.pl';
378 Dynamically Loadable Modules
380 TODO
381 dlmod NAME PATH"
382 Proxy Support
384 A configuration for acting as a simple proxy for two other SNMP agents
385 (running on remote systems) might be:
386 com2sec -Cn rem1context rem1user default remotehost1
387 com2sec -Cn rem2context rem2user default remotehost2
388 proxy -Cn rem1context -v 1 -c public remotehost1 .1.3
390 proxy -Cn rem2context -v 1 -c public remotehost2 .1.3
391 (plus suitable access control entries).
392 The same proxy directives would also work with (incoming) SNMPv3
394 requests, which can specify a context directly. It would probably be
395 more sensible to use contexts of remotehost1 and remotehost2 - the
396 names above were chosen to indicate how these directives work together.
397 Note that the administrative settings for the proxied request are spec‐
399 ified explicitly, and are independent of the settings from the incoming
400 request.
401 An alternative use for the proxy directive is to pass part of the OID
403 tree to another agent (either on a remote host or listening on a dif‐
404 ferent port on the same system), while handling the rest internally:
405 proxy -v 1 -c public localhost:6161 .1.3.6.1.4.1.99
406 This mechanism can be used to link together two separate SNMP agents.
407 A less usual approach is to map one subtree into a different area of
409 the overall MIB tree (either locally or on a remote system):
410 # uses SNMPv3 to access the MIB tree .1.3.6.1.2.1.1 on 'remotehost'
411 # and maps this to the local tree .1.3.6.1.3.10
412 proxy -v 3 -l noAuthNoPriv -u user remotehost .1.3.6.1.3.10 .1.3.6.1.2.1.1
413 SMUX Sub-Agents
415 smuxsocket 127.0.0.1
416 smuxpeer .1.3.6.1.2.1.14 ospf_pass
417 AgentX Sub-Agents
419 The Net-SNMP agent could be configured to operate as an AgentX master
420 agent (listening on a non-standard named socket, and running using the
421 access privileges defined earlier), using:
422 master agentx
423 agentXSocket /tmp/agentx/master
424 agentXPerms 0660 0550 nobody snmp
425 A sub-agent wishing to connect to this master agent would need the same
426 agentXSocket directive, or the equivalent code:
427 netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_X_SOCKET,
428 "/tmp/agentx/master");
429 A loopback networked AgentX configuration could be set up using:
431 agentXSocket tcp:localhost:705
432 agentXTimeout 5
433 agentXRetries 2
434 on the master side, and:
435 agentXSocket tcp:localhost:705
436 agentXTimeout 10
437 agentXRetries 1
438 agentXPingInterval 600
439 on the client.
440 Note that the timeout and retry settings can be asymmetric for the two
442 directions, and the sub-agent can poll the master agent at regular
443 intervals (600s = every 10 minutes), to ensure the connection is still
444 working.
445
447 override sysDescr.0 octet_str "my own sysDescr"
448 injectHandler stash_cache NAME table_iterator
449
451 /etc/snmp/snmpd.conf
452
454 snmpconf(1), snmpd.conf(5), snmp.conf(5), snmp_config(5), snmpd(8),
455 EXAMPLE.conf, netsnmp_config_api(3).
456V5.8 13 Oct 2006 SNMPD.EXAMPLES(5)