MAN page from Trustix net-snmp-5.4-2tr.i586.rpm


Section: Net-SNMP (5)
Updated: 05 Dec 2005


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


Thesnmpd.conf(5)man page defines the syntax and behaviour of the variousconfiguration directives that can be used to control theoperation of the Net-SNMP agent, and the management informationit provides.

This companion man page illustrates these directives, showingsome practical examples of how they might be used. 



Listening addresses

The default agent behaviour (listing on the standard SNMP UDP port onall interfaces) is equivalent to the directive:
agentaddress udp:161
or simply
agentaddress 161
The agent can be configured to only accept requests sent to thelocal loopback interface (again listening on the SNMP UDP port), using:
agentaddress localhost:161 # (udp implicit)
agentaddress # (udp and standard port implicit)
It can be configured to accept both UDP and TCP requests (over both IPv4and IPv6), using:
agentaddress udp:161,tcp:161,udp6:161,tcp6:161
Other combinations are also valid. 

Run-time privileges

The agent can be configured to relinquish any privileged access once ithas opened the initial listening ports. Given a suitable "snmp" group(defined in /etc/group), this could be done using the directives:
agentuser  nobodyagentgroup snmp
A similar effect could be achieved using numeric UID and/or GID values:
agentuser  #10agentgroup #10

SNMPv3 Configuration

Rather than being generated pseudo-randomly,the engine ID for the agent could be calculated based on the MAC addressof the second network interface (eth1), using the directives:
engineIDType 3engineIDNic eth1
or it could be calculated from the (first) IP address, using:
engineIDType 1
or it could be specified explicitly, using:



SNMPv3 Users

The following directives will create three users, all using exactlythe same authentication and encryption settings:
createUser me     MD5 "single pass phrase"createUser myself MD5 "single pass phrase" DEScreateUser andI   MD5 "single pass phrase" DES "single pass phrase"
Note that this defines three distinct users, who could be granteddifferent levels of access. Changing the passphrase for any one ofthese would not affect the other two.

Separate pass phrases can be specified for authentication andencryption:

createUser onering SHA "to rule them all" AES "to bind them"
Remember that these createUser directives should be defined in the/var/net-snmp/snmpd.conf file, rather than the usual location. 

Traditional Access Control

The SNMPv3 users defined above can be granted access to the fullMIB tree using the directives:
rouser merwuser onering
Or selective access to individual subtrees using:
rouser myself   . andI     system

Note that a combination repeating the same user, such as:

rouser oneringrwuser onering
should not be used. This would configure the user oneringwith read-only access (and ignore the rwuser entry altogether).The same holds for the community-based directives.

The directives:

rocommunity publicrwcommunity private
would define the commonly-expected read and write community stringsfor SNMPv1 and SNMPv2c requests. This behaviour is notconfigured by default, and would need to be set up explicitly.
It would also be a very good idea to change private to somethinga little less predictable!

A slightly less vulnerable configuration might restrict what informationcould be retrieved:

rocommunity public default system
or the management systems that settings could be manipulated from:
rwcommunity private
or a combination of the two. 

VACM Configuration

This last pair of settings are equivalent to the full VACM definitions:
#  source        communitycom2sec   public    default       publiccom2sec   mynet privatecom2sec6  mynet     fec0::/64     private#                  sec.model  sec.namegroup  worldGroup  v1         publicgroup  worldGroup  v2c        publicgroup  myGroup     v1         mynetgroup  myGroup     v2c        mynet#              incl/excl   subtree     [mask]view   all     included    .1view   sysView included    system#              context model level   prefix  read    write  notify (unused)access  worldGroup  ""  any  noauth  exact   system  none   noneaccess  myGroup     ""  any  noauth  exact   all     all    none

There are several points to note in this example:

The group directives must be repeated for both SNMPv1 and SNMPv2c requests.

The com2sec security name is distinct from the communitystring that is mapped to it. They can be the same ("public")or different ("mynet"/"private") - but what appears in thegroup directive is the security name, regardless ofthe original community string.

Both of the view directives are defining simple OIDsubtrees, so neither of these require an explicit mask.The same holds for the "combined subtree2 view defined below.In fact, a mask field is only needed when defining row slicesacross a table (or similar views), and can almost always be omitted.

In general, it is advisible not to mix traditional and VACM-basedaccess configuration settings, as these can sometimes interferewith each other in unexpected ways. Choose a particular styleof access configuration, and stick to it. 

Typed-View Configuration

A similar configuration could also be configured as follows:
view   sys2View included    systemview   sys2View included    . read       public  default      -v sys2Viewauthcommunity read,write private

This mechanism allows multi-subtree (or other non-simple) views tobe used with the one-line rocommunity style of configuration.

It would also support configuring "write-only" access, should thisbe required. 



System Group

The full contents of the 'system' group (with the exception of sysUpTime)can be explicitly configured using:
# Override 'uname -a' and hardcoded system OID - inherently read-only valuessysDescr     Universal Turing Machine mk IsysObjectID  . Override default values from 'configure' - makes these objects read-onlysysContact      tortoise.turing.comsysLocation  An idea in the mind of AT# Standard end-host behavioursysServices  72

Host Resources Group

The list of devices probed for potential inclusion in thehrDiskStorageTable (and hrDeviceTable) can be amended usingany of the following directives:
ignoredisk /dev/rdsk/c0t2d0
which prevents the device /dev/rdsk/c0t2d0 from being scanned,
ignoredisk /dev/rdsk/c0t[!6]d0ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0
either of which prevents all devices /dev/rdsk/c0tXd0(except .../c0t6d0) from being scanned,
ignoredisk /dev/rdsk/c1*
which prevents all devices whose device names start with /dev/rdsk/c1from being scanned, or
ignoredisk /dev/rdsk/c?t0d0
which prevents all devices /dev/rdsk/cXt0d0(where 'X' is any single character) from being scanned. 

Process Monitoring

The list of services running on a system can be monitored(and provision made for correcting any problems), using:
# At least one web server process must be running at all timesproc    httpdprocfix httpd  /etc/rc.d/init.d/httpd restart# There should never be more than 10 mail processes running#    (more implies a probable mail storm, so shut down the mail system)proc    sendmail   10procfix sendmail  /etc/rc.d/init.d/sendmail stop# There should be a single network management agent running#   ("There can be only one")proc    snmpd    1  1
Also see the "DisMan Event MIB" section later on. 

Disk Usage Monitoring

The state of disk storage can be monitored using:
includeAllDisks 10%disk /var 20%disk /usr  3%#  Keep 100 Mb free for crash dumpsdisk /mnt/crash  100000

System Load Monitoring

A simple check for an overloaded system might be:
load 10
A more refined check (to allow brief periods of heavy use,but recognise sustained medium-heavy load) might be:
load 30 10 5

Log File Monitoring




Notification Handling

Configuring the agent to report invalid access attempts might be done by:
authtrapenable 1trapcommunity  publictrap2sink      localhost
Alternatively, the second and third directives could be combined(and an acknowledgement requested) using:
informsink localhost public
A configuration with repeated sink destinations, such as:
trapsink       localhosttrap2sink      localhostinformsink     localhost
should NOT be used, as this will cause multiple copiesof each trap to be sent to the same trap receiver.

TODO - discuss SNMPv3 traps

trapsess snmpv3 options localhost:162

TODO - mention trapd access configuration


DisMan Event MIB

The simplest configuration for active self-monitoring ofthe agent, by the agent, for the agent, is probably:
# Set up the credentials to retrieve monitored valuescreateUser    _internal MD5 "the first sign of madness"iquerySecName _internalrouser        _internal# Active the standard monitoring entriesdefaultMonitors         yeslinkUpDownNotifications yes# If there's a problem, then tell someone!trap2sink localhost

The first block sets up a suitable user for retrieving theinformation to by monitored, while the following pair ofdirectives activates various built-in monitoring entries.

Note that the DisMan directives are not themselves sufficient toactively report problems - there also needs to be a suitabledestination configured to actually send the resulting notifications to.

A more detailed monitor example is given by:

monitor -u me -o hrSWRunName "high process memory" hrSWRunPerfMem > 10000

This defines an explicit boolean monitor entry, looking for any processusing more than 10Mb of active memory. Such processes will be reportedusing the (standard) DisMan trap mteTriggerFired,but adding an extra (wildcarded) varbind hrSWRunName.

This entry also specifies an explicit user (me, as definedearlier) for retrieving the monitored values, and building the trap.

Objects that could potentially fluctuate around the specified levelare better monitored using a threshold monitor entry:

monitor -D -r 10 "network traffic" ifInOctets 1000000 5000000

This will send a mteTriggerRising trap whenever the incomingtraffic rises above (roughly) 500 kB/s on any network interface,and a corresponding mteTriggerFalling trap when it falls below100 kB/s again.

Note that this monitors the deltas between successive samples (-D)rather than the actual sample values themselves. The same effectcould be obtained using:

monitor -r 10 "network traffic" ifInOctets - - 1000000 5000000

The linkUpDownNotifications directive above is broadlyequivalent to:

notificationEvent  linkUpTrap    linkUp   ifIndex ifAdminStatus ifOperStatusnotificationEvent  linkDownTrap  linkDown ifIndex ifAdminStatus ifOperStatusmonitor  -r 60 -e linkUpTrap   "Generate linkUp"   ifOperStatus != 2monitor  -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2

This defines the traps to be sent (using notificationEvent),and explicitly references the relevant notification in the correspondingmonitor entry (rather than using the default DisMan traps).

The defaultMonitors directive above is equivalent to a seriesof (boolean) monitor entries:

monitor -o prNames      -o prErrMessage  "procTable" prErrorFlag   != 0monitor -o memErrorName -o memSwapErrorMsg "memory"  memSwapError  != 0monitor -o extNames     -o extOutput     "extTable"  extResult     != 0monitor -o dskPath      -o dskErrorMsg   "dskTable"  dskErrorFlag  != 0monitor -o laNames      -o laErrMessage  "laTable"   laErrorFlag   != 0monitor -o fileName     -o fileErrorMsg  "fileTable" fileErrorFlag != 0
and will send a trap whenever any of these entries indicate a problem.

An alternative approach would be to automatically invoke the corresponding"fix" action:

setEvent   prFixIt  prErrFix = 1monitor -e prFixIt "procTable" prErrorFlag   != 0
(and similarly for any of the other defaultMonitor entries). 

DisMan Schedule MIB

The agent could be configured to reload its configurationonce an hour, using:
repeat 3600 versionUpdateConfig.0 = 1

Alternatively this could be configured to be run at specifictimes of day (perhaps following rotation of the logs):

cron 10 0 * * * versionUpdateConfig.0 = 1

The one-shot style of scheduling is rather less common, but thesecret SNMP virus could be activated on the next occurance of Friday 13th using:

at 13 13 13 * 5 snmpVirus.0 = 1



Arbitrary Extension Commands

Old Style
New Style

MIB-Specific Extension Commands

"pass [-p priority] MIBOID PROG"
"pass_persist [-p priority] MIBOID PROG"

Embedded Perl Support

If embedded perl support is enabled in the agent, the defaultinitialisation is equivalent to the directives:
disablePerl  falseperlInitFile /usr/share/snmp/
The main mechanism for defining embedded perl scripts is theperl directive. A very simple (if somewhat pointless)MIB handler could be registered using:
perl use Data::Dumper;perl sub myroutine  { print "got called: ",Dumper(@_),"\n"; }perl $agent->register('mylink', '.', \&myroutine);

This relies on the $agent object, defined in the file.

A more realistic MIB handler might be:

XXX - WHAT ???
Alternatively, this code could be stored in an external file,and loaded using:
perl 'do /usr/share/snmp/';

Dynamically Loadable Modules

dlmod NAME PATH"

Proxy Support

A configuration for acting as a simple proxy for two otherSNMP agents (running on remote systems) might be:
com2sec -Cn rem1context  rem1user default  remotehost1com2sec -Cn rem2context  rem2user default  remotehost2proxy -Cn rem1context  -v 1 -c public  remotehost1  .1.3proxy -Cn rem2context  -v 1 -c public  remotehost2  .1.3
(plus suitable access control entries).

The same proxy directives would also work with(incoming) SNMPv3 requests, which can specify a context directly.It would probably be more sensible to use contexts ofremotehost1 and remotehost2 - the names above werechosen to indicate how these directives work together.

Note that the administrative settings for the proxied requestare specified explicitly, and are independent of the settingsfrom the incoming request.

An alternative use for the proxy directive is to passpart of the OID tree to another agent (either on a remote hostor listening on a different port on the same system),while handling the rest internally:

proxy -v 1 -c public localhost:6161 .
This mechanism can be used to link together two separate SNMP agents.

A less usual approach is to map one subtree into a different areaof the overall MIB tree (either locally or on a remote system):

# uses SNMPv3 to access the MIB tree . on 'remotehost'# and maps this to the local tree . -v 3 -l noAuthNoPriv -u user remotehost . .

SMUX Sub-Agents

smuxsocket . ospf_pass

AgentX Sub-Agents

The Net-SNMP agent could be configured to operate as an AgentX masteragent (listening on a non-standard named socket, and running usingthe access privileges defined earlier), using:
master agentxagentXSocket /tmp/agentx/masteragentXPerms  0660 0550 nobody snmp
A sub-agent wishing to connect to this master agent would needthe same agentXSocket directive, or the equivalent code:
netsnmp_ds_set_string(NETSNMP_DS_APPLICATION_ID, NETSNMP_DS_AGENT_X_SOCKET,                       "/tmp/agentx/master");

A loopback networked AgentX configuration could be set up using:

agentXSocket   tcp:localhost:705agentXTimeout  5agentXRetries  2
on the master side, and:
agentXSocket   tcp:localhost:705agentXTimeout  10agentXRetries  1agentXPingInterval 600
on the client.

Note that the timeout and retry settings can be asymmetricfor the two directions, and the sub-agent can poll the master agentat regular intervals (600s = every 10 minutes), to ensure theconnection is still working. 


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




snmpconf(1), snmpd.conf(5), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, read_config(3).



Listening addresses
Run-time privileges
SNMPv3 Configuration
SNMPv3 Users
Traditional Access Control
VACM Configuration
Typed-View Configuration
System Group
Host Resources Group
Process Monitoring
Disk Usage Monitoring
System Load Monitoring
Log File Monitoring
Notification Handling
DisMan Event MIB
DisMan Schedule MIB
Arbitrary Extension Commands
MIB-Specific Extension Commands
Embedded Perl Support
Dynamically Loadable Modules
Proxy Support
SMUX Sub-Agents
AgentX Sub-Agents

This document was created byman2html,using the manual pages.