1SNMPD.EXAMPLES(5)                  Net-SNMP                  SNMPD.EXAMPLES(5)
2
3
4

NAME

6       snmpd.examples - example configuration for the Net-SNMP agent
7

DESCRIPTION

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
13       This  companion  man  page  illustrates  these directives, showing some
14       practical examples of how they might be used.
15

AGENT BEHAVIOUR

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
33   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
43   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

ACCESS CONTROL

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" AES
59              createUser andI   MD5 "single pass phrase" AES "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
64       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
70   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
79       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
86       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  de‐
91       fault, and would need to be set up explicitly.
92
93              Note:  It  would  also  be a very good idea to change private to
94                     something a little less predictable!
95
96       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
103   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
110              #                  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
116              #              incl/excl   subtree     [mask]
117              view   all     included    .1
118              view   sysView included    system
119
120              #              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
124       There are several points to note in this example:
125
126       The  group  directives must be repeated for both SNMPv1 and SNMPv2c re‐
127       quests.
128
129       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
134       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
140       In  general,  it is advisible not to mix traditional and VACM-based ac‐
141       cess configuration settings, as these can sometimes interfere with each
142       other in unexpected ways.  Choose a particular style of access configu‐
143       ration, and stick to it.
144
145   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
150              authcommunity read       public  default      -v sys2View
151              authcommunity read,write private 10.10.10.0/8
152
153       This mechanism allows multi-subtree (or other non-simple) views  to  be
154       used with the one-line rocommunity style of configuration.
155
156       It  would  also support configuring "write-only" access, should this be
157       required.
158

SYSTEM INFORMATION

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
167              # 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
172              # Standard end-host behaviour
173              sysServices  72
174
175   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
192   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
199              # 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
204              # 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
209   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
217   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
224   Log File Monitoring
225       TODO
226              file FILE [MAXSIZE]
227              logmatch NAME PATH CYCLETIME REGEX
228

ACTIVE MONITORING

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
246       TODO - discuss SNMPv3 traps
247              trapsess  snmpv3 options  localhost:162
248
249       TODO - mention trapd access configuration
250
251
252   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
260              # Active the standard monitoring entries
261              defaultMonitors         yes
262              linkUpDownNotifications yes
263
264              # If there's a problem, then tell someone!
265              trap2sink localhost
266
267       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
271       Note that the DisMan directives are not themselves  sufficient  to  ac‐
272       tively  report problems - there also needs to be a suitable destination
273       configured to actually send the resulting notifications to.
274
275       A more detailed monitor example is given by:
276              monitor -u me -o  hrSWRunName  "high  process  memory"  hrSWRun‐
277              PerfMem > 10000
278
279       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
284       This entry also specifies an explicit user (me, as defined earlier) for
285       retrieving the monitored values, and building the trap.
286
287       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
291       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
295       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
300       The linkUpDownNotifications directive above is broadly equivalent to:
301              notificationEvent  linkUpTrap    linkUp   ifIndex ifAdminStatus ifOperStatus
302              notificationEvent  linkDownTrap  linkDown ifIndex ifAdminStatus ifOperStatus
303
304              monitor  -r 60 -e linkUpTrap   "Generate linkUp"   ifOperStatus != 2
305              monitor  -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
306
307       This defines the traps to be sent (using  notificationEvent),  and  ex‐
308       plicitly references the relevant notification in the corresponding mon‐
309       itor entry (rather than using the default DisMan traps).
310
311       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
321       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
327   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
332       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
336       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 us‐
338       ing:
339              at   13 13 13 * 5 snmpVirus.0 = 1
340

EXTENDING AGENT FUNCTIONALITY

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
351   MIB-Specific Extension Commands
352       One-Shot
353              "pass [-p priority] MIBOID PROG"
354
355              Persistent
356              "pass_persist [-p priority] MIBOID PROG"
357
358   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 di‐
364       rective.  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
370       This  relies  on the $agent object, defined in the example snmp_perl.pl
371       file.
372
373       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
379   Dynamically Loadable Modules
380       TODO
381              dlmod NAME PATH"
382
383   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
389              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
393       The same proxy directives would also work with  (incoming)  SNMPv3  re‐
394       quests,  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
398       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
402       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
408       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
414   SMUX Sub-Agents
415              smuxsocket 127.0.0.1
416              smuxpeer .1.3.6.1.2.1.14 ospf_pass
417
418   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
430       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
441       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  in‐
443       tervals  (600s  =  every 10 minutes), to ensure the connection is still
444       working.
445

OTHER CONFIGURATION

447              override sysDescr.0 octet_str "my own sysDescr"
448              injectHandler stash_cache NAME table_iterator
449

FILES

451       /etc/snmp/snmpd.conf
452

SEE ALSO

454       snmpconf(1), snmpd.conf(5), snmp.conf(5), snmp_config(5), snmpd(8), EX‐
455       AMPLE.conf, netsnmp_config_api(3).
456
457
458
459V5.9.1                            13 Oct 2006                SNMPD.EXAMPLES(5)
Impressum