{ "content": [ { "type": "text", "text": "# snmpd.examples (man)\n\n## NAME\n\nsnmpd.examples - example configuration for the Net-SNMP agent\n\n## DESCRIPTION\n\nThe snmpd.conf(5) man page defines the syntax and behaviour of the various configuration di‐\nrectives that can be used to control the operation of the Net-SNMP agent, and the management\ninformation it provides.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **AGENT BEHAVIOUR** (3 subsections)\n- **ACCESS CONTROL** (4 subsections)\n- **SYSTEM INFORMATION** (6 subsections)\n- **ACTIVE MONITORING** (3 subsections)\n- **EXTENDING AGENT FUNCTIONALITY** (7 subsections)\n- **OTHER CONFIGURATION**\n- **FILES**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "snmpd.examples", "section": "", "mode": "man", "summary": "snmpd.examples - example configuration for the Net-SNMP agent", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "snmpconf", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/snmpconf/1/json" }, { "name": "snmpd.conf", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/snmpd.conf/5/json" }, { "name": "snmp.conf", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/snmp.conf/5/json" }, { "name": "snmpconfig", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/snmpconfig/5/json" }, { "name": "snmpd", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/snmpd/8/json" }, { "name": "snmpconfigapi", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/snmpconfigapi/3/json" }, { "name": "SNMPD.EXAMPLES", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/SNMPD.EXAMPLES/5/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [] }, { "name": "AGENT BEHAVIOUR", "lines": 1, "subsections": [ { "name": "Listening addresses", "lines": 14 }, { "name": "Run-time privileges", "lines": 9 }, { "name": "SNMPv3 Configuration", "lines": 8 } ] }, { "name": "ACCESS CONTROL", "lines": 1, "subsections": [ { "name": "SNMPv3 Users", "lines": 13 }, { "name": "Traditional Access Control", "lines": 30 }, { "name": "VACM Configuration", "lines": 37 }, { "name": "Typed-View Configuration", "lines": 12 } ] }, { "name": "SYSTEM INFORMATION", "lines": 1, "subsections": [ { "name": "System Group", "lines": 14 }, { "name": "Host Resources Group", "lines": 13 }, { "name": "Process Monitoring", "lines": 16 }, { "name": "Disk Usage Monitoring", "lines": 7 }, { "name": "System Load Monitoring", "lines": 6 }, { "name": "Log File Monitoring", "lines": 4 } ] }, { "name": "ACTIVE MONITORING", "lines": 1, "subsections": [ { "name": "Notification Handling", "lines": 20 }, { "name": "DisMan Event MIB", "lines": 68 }, { "name": "DisMan Schedule MIB", "lines": 11 } ] }, { "name": "EXTENDING AGENT FUNCTIONALITY", "lines": 1, "subsections": [ { "name": "Arbitrary Extension Commands", "lines": 8 }, { "name": "MIB-Specific Extension Commands", "lines": 6 }, { "name": "Embedded Perl Support", "lines": 17 }, { "name": "Dynamically Loadable Modules", "lines": 3 }, { "name": "Proxy Support", "lines": 28 }, { "name": "SMUX Sub-Agents", "lines": 3 }, { "name": "AgentX Sub-Agents", "lines": 25 } ] }, { "name": "OTHER CONFIGURATION", "lines": 3, "subsections": [] }, { "name": "FILES", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "snmpd.examples - example configuration for the Net-SNMP agent\n", "subsections": [] }, "DESCRIPTION": { "content": "The snmpd.conf(5) man page defines the syntax and behaviour of the various configuration di‐\nrectives that can be used to control the operation of the Net-SNMP agent, and the management\ninformation it provides.\n\nThis companion man page illustrates these directives, showing some practical examples of how\nthey might be used.\n", "subsections": [] }, "AGENT BEHAVIOUR": { "content": "", "subsections": [ { "name": "Listening addresses", "content": "The default agent behaviour (listing on the standard SNMP UDP port on all interfaces) is\nequivalent to the directive:\nagentaddress udp:161\nor simply\nagentaddress 161\nThe agent can be configured to only accept requests sent to the local loopback interface\n(again listening on the SNMP UDP port), using:\nagentaddress localhost:161 # (udp implicit)\nor\nagentaddress 127.0.0.1 # (udp and standard port implicit)\nIt can be configured to accept both UDP and TCP requests (over both IPv4 and IPv6), using:\nagentaddress udp:161,tcp:161,udp6:161,tcp6:161\nOther combinations are also valid.\n" }, { "name": "Run-time privileges", "content": "The agent can be configured to relinquish any privileged access once it has opened the ini‐\ntial listening ports. Given a suitable \"snmp\" group (defined in /etc/group), this could be\ndone using the directives:\nagentuser nobody\nagentgroup snmp\nA similar effect could be achieved using numeric UID and/or GID values:\nagentuser #10\nagentgroup #10\n" }, { "name": "SNMPv3 Configuration", "content": "Rather than being generated pseudo-randomly, the engine ID for the agent could be calculated\nbased on the MAC address of the second network interface (eth1), using the directives:\nengineIDType 3 engineIDNic eth1\nor it could be calculated from the (first) IP address, using:\nengineIDType 1\nor it could be specified explicitly, using:\nengineID \"XXX - WHAT FORMAT\"\n" } ] }, "ACCESS CONTROL": { "content": "", "subsections": [ { "name": "SNMPv3 Users", "content": "The following directives will create three users, all using exactly the same authentication\nand encryption settings:\ncreateUser me MD5 \"single pass phrase\"\ncreateUser myself MD5 \"single pass phrase\" DES\ncreateUser andI MD5 \"single pass phrase\" DES \"single pass phrase\"\nNote that this defines three distinct users, who could be granted different levels of access.\nChanging the passphrase for any one of these would not affect the other two.\n\nSeparate pass phrases can be specified for authentication and encryption:\ncreateUser onering SHA \"to rule them all\" AES \"to bind them\"\nRemember that these createUser directives should be defined in the /var/lib/snmp/snmpd.conf\nfile, rather than the usual location.\n" }, { "name": "Traditional Access Control", "content": "The SNMPv3 users defined above can be granted access to the full MIB tree using the direc‐\ntives:\nrouser me\nrwuser onering\nOr selective access to individual subtrees using:\nrouser myself .1.3.6.1.2\nrwuser andI system\n\nNote that a combination repeating the same user, such as:\nrouser onering\nrwuser onering\nshould not be used. This would configure the user onering with read-only access (and ignore\nthe rwuser entry altogether). The same holds for the community-based directives.\n\nThe directives:\nrocommunity public\nrwcommunity private\nwould define the commonly-expected read and write community strings for SNMPv1 and SNMPv2c\nrequests. This behaviour is not configured by default, and would need to be set up explic‐\nitly.\n\nNote: It would also be a very good idea to change private to something a little less\npredictable!\n\nA slightly less vulnerable configuration might restrict what information could be retrieved:\nrocommunity public default system\nor the management systems that settings could be manipulated from:\nrwcommunity private 10.10.10.0/24\nor a combination of the two.\n" }, { "name": "VACM Configuration", "content": "This last pair of settings are equivalent to the full VACM definitions:\n# sec.name source community\ncom2sec public default public\ncom2sec mynet 10.10.10.0/24 private\ncom2sec6 mynet fec0::/64 private\n\n# sec.model sec.name\ngroup worldGroup v1 public\ngroup worldGroup v2c public\ngroup myGroup v1 mynet\ngroup myGroup v2c mynet\n\n# incl/excl subtree [mask]\nview all included .1\nview sysView included system\n\n# context model level prefix read write notify (unused)\naccess worldGroup \"\" any noauth exact system none none\naccess myGroup \"\" any noauth exact all all none\n\nThere are several points to note in this example:\n\nThe group directives must be repeated for both SNMPv1 and SNMPv2c requests.\n\nThe com2sec security name is distinct from the community string that is mapped to it. They\ncan be the same (\"public\") or different (\"mynet\"/\"private\") - but what appears in the group\ndirective is the security name, regardless of the original community string.\n\nBoth of the view directives are defining simple OID subtrees, so neither of these require an\nexplicit mask. The same holds for the \"combined subtree2 view defined below. In fact, a\nmask field is only needed when defining row slices across a table (or similar views), and can\nalmost always be omitted.\n\nIn general, it is advisible not to mix traditional and VACM-based access configuration set‐\ntings, as these can sometimes interfere with each other in unexpected ways. Choose a partic‐\nular style of access configuration, and stick to it.\n" }, { "name": "Typed-View Configuration", "content": "A similar configuration could also be configured as follows:\nview sys2View included system\nview sys2View included .1.3.6.1.2.1.25.1\n\nauthcommunity read public default -v sys2View\nauthcommunity read,write private 10.10.10.0/8\n\nThis mechanism allows multi-subtree (or other non-simple) views to be used with the one-line\nrocommunity style of configuration.\n\nIt would also support configuring \"write-only\" access, should this be required.\n" } ] }, "SYSTEM INFORMATION": { "content": "", "subsections": [ { "name": "System Group", "content": "The full contents of the 'system' group (with the exception of sysUpTime) can be explicitly\nconfigured using:\n# Override 'uname -a' and hardcoded system OID - inherently read-only values\nsysDescr Universal Turing Machine mk I\nsysObjectID .1.3.6.1.4.1.8072.3.2.1066\n\n# Override default values from 'configure' - makes these objects read-only\nsysContact Alan.Turing@pre-cs.man.ac.uk\nsysName tortoise.turing.com\nsysLocation An idea in the mind of AT\n\n# Standard end-host behaviour\nsysServices 72\n" }, { "name": "Host Resources Group", "content": "The list of devices probed for potential inclusion in the hrDiskStorageTable (and hrDevic‐\neTable) can be amended using any of the following directives:\nignoredisk /dev/rdsk/c0t2d0\nwhich prevents the device /dev/rdsk/c0t2d0 from being scanned,\nignoredisk /dev/rdsk/c0t[!6]d0\nignoredisk /dev/rdsk/c0t[0-57-9a-f]d0\neither of which prevents all devices /dev/rdsk/c0tXd0 (except .../c0t6d0) from being scanned,\nignoredisk /dev/rdsk/c1*\nwhich prevents all devices whose device names start with /dev/rdsk/c1 from being scanned, or\nignoredisk /dev/rdsk/c?t0d0\nwhich prevents all devices /dev/rdsk/cXt0d0 (where 'X' is any single character) from being\nscanned.\n" }, { "name": "Process Monitoring", "content": "The list of services running on a system can be monitored (and provision made for correcting\nany problems), using:\n# At least one web server process must be running at all times\nproc httpd\nprocfix httpd /etc/rc.d/init.d/httpd restart\n\n# There should never be more than 10 mail processes running\n# (more implies a probable mail storm, so shut down the mail system)\nproc sendmail 10\nprocfix sendmail /etc/rc.d/init.d/sendmail stop\n\n# There should be a single network management agent running\n# (\"There can be only one\")\nproc snmpd 1 1\nAlso see the \"DisMan Event MIB\" section later on.\n" }, { "name": "Disk Usage Monitoring", "content": "The state of disk storage can be monitored using:\nincludeAllDisks 10%\ndisk /var 20%\ndisk /usr 3%\n# Keep 100 MB free for crash dumps\ndisk /mnt/crash 100000\n" }, { "name": "System Load Monitoring", "content": "A simple check for an overloaded system might be:\nload 10\nA more refined check (to allow brief periods of heavy use, but recognise sustained medium-\nheavy load) might be:\nload 30 10 5\n" }, { "name": "Log File Monitoring", "content": "TODO\nfile FILE [MAXSIZE]\nlogmatch NAME PATH CYCLETIME REGEX\n" } ] }, "ACTIVE MONITORING": { "content": "", "subsections": [ { "name": "Notification Handling", "content": "Configuring the agent to report invalid access attempts might be done by:\nauthtrapenable 1\ntrapcommunity public\ntrap2sink localhost\nAlternatively, the second and third directives could be combined (and an acknowledgement re‐\nquested) using:\ninformsink localhost public\nA configuration with repeated sink destinations, such as:\ntrapsink localhost\ntrap2sink localhost\ninformsink localhost\nshould NOT be used, as this will cause multiple copies of each trap to be sent to the same\ntrap receiver.\n\nTODO - discuss SNMPv3 traps\ntrapsess snmpv3 options localhost:162\n\nTODO - mention trapd access configuration\n\n" }, { "name": "DisMan Event MIB", "content": "The simplest configuration for active self-monitoring of the agent, by the agent, for the\nagent, is probably:\n# Set up the credentials to retrieve monitored values\ncreateUser internal MD5 \"the first sign of madness\"\niquerySecName internal\nrouser internal\n\n# Active the standard monitoring entries\ndefaultMonitors yes\nlinkUpDownNotifications yes\n\n# If there's a problem, then tell someone!\ntrap2sink localhost\n\nThe first block sets up a suitable user for retrieving the information to by monitored, while\nthe following pair of directives activates various built-in monitoring entries.\n\nNote that the DisMan directives are not themselves sufficient to actively report problems -\nthere also needs to be a suitable destination configured to actually send the resulting noti‐\nfications to.\n\nA more detailed monitor example is given by:\nmonitor -u me -o hrSWRunName \"high process memory\" hrSWRunPerfMem > 10000\n\nThis defines an explicit boolean monitor entry, looking for any process using more than 10MB\nof active memory. Such processes will be reported using the (standard) DisMan trap mteTrig‐\ngerFired, but adding an extra (wildcarded) varbind hrSWRunName.\n\nThis entry also specifies an explicit user (me, as defined earlier) for retrieving the moni‐\ntored values, and building the trap.\n\nObjects that could potentially fluctuate around the specified level are better monitored us‐\ning a threshold monitor entry:\nmonitor -D -r 10 \"network traffic\" ifInOctets 1000000 5000000\n\nThis will send a mteTriggerRising trap whenever the incoming traffic rises above (roughly)\n500 kB/s on any network interface, and a corresponding mteTriggerFalling trap when it falls\nbelow 100 kB/s again.\n\nNote that this monitors the deltas between successive samples (-D) rather than the actual\nsample values themselves. The same effect could be obtained using:\nmonitor -r 10 \"network traffic\" ifInOctets - - 1000000 5000000\n\nThe linkUpDownNotifications directive above is broadly equivalent to:\nnotificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus\nnotificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus\n\nmonitor -r 60 -e linkUpTrap \"Generate linkUp\" ifOperStatus != 2\nmonitor -r 60 -e linkDownTrap \"Generate linkDown\" ifOperStatus == 2\n\nThis defines the traps to be sent (using notificationEvent), and explicitly references the\nrelevant notification in the corresponding monitor entry (rather than using the default Dis‐\nMan traps).\n\nThe defaultMonitors directive above is equivalent to a series of (boolean) monitor entries:\nmonitor -o prNames -o prErrMessage \"procTable\" prErrorFlag != 0\nmonitor -o memErrorName -o memSwapErrorMsg \"memory\" memSwapError != 0\nmonitor -o extNames -o extOutput \"extTable\" extResult != 0\nmonitor -o dskPath -o dskErrorMsg \"dskTable\" dskErrorFlag != 0\nmonitor -o laNames -o laErrMessage \"laTable\" laErrorFlag != 0\nmonitor -o fileName -o fileErrorMsg \"fileTable\" fileErrorFlag != 0\nand will send a trap whenever any of these entries indicate a problem.\n\nAn alternative approach would be to automatically invoke the corresponding \"fix\" action:\nsetEvent prFixIt prErrFix = 1\nmonitor -e prFixIt \"procTable\" prErrorFlag != 0\n(and similarly for any of the other defaultMonitor entries).\n" }, { "name": "DisMan Schedule MIB", "content": "The agent could be configured to reload its configuration once an hour, using:\nrepeat 3600 versionUpdateConfig.0 = 1\n\nAlternatively this could be configured to be run at specific times of day (perhaps following\nrotation of the logs):\ncron 10 0 * * * versionUpdateConfig.0 = 1\n\nThe one-shot style of scheduling is rather less common, but the secret SNMP virus could be\nactivated on the next occurance of Friday 13th using:\nat 13 13 13 * 5 snmpVirus.0 = 1\n" } ] }, "EXTENDING AGENT FUNCTIONALITY": { "content": "", "subsections": [ { "name": "Arbitrary Extension Commands", "content": "Old Style\nexec [MIBOID] NAME PROG ARGS\"\nsh [MIBOID] NAME PROG ARGS\"\nexecfix NAME PROG ARGS\"\nNew Style\nextend [MIBOID] NAME PROG ARGS\"\nextendfix [MIBOID] NAME PROG ARGS\"\n" }, { "name": "MIB-Specific Extension Commands", "content": "One-Shot\n\"pass [-p priority] MIBOID PROG\"\n\nPersistent\n\"passpersist [-p priority] MIBOID PROG\"\n" }, { "name": "Embedded Perl Support", "content": "If embedded perl support is enabled in the agent, the default initialisation is equivalent to\nthe directives:\ndisablePerl false\nperlInitFile /usr/share/snmp/snmpperl.pl\nThe main mechanism for defining embedded perl scripts is the perl directive. A very simple\n(if somewhat pointless) MIB handler could be registered using:\nperl use Data::Dumper;\nperl sub myroutine { print \"got called: \",Dumper(@),\"\\n\"; }\nperl $agent->register('mylink', '.1.3.6.1.8765', \\&myroutine);\n\nThis relies on the $agent object, defined in the example snmpperl.pl file.\n\nA more realistic MIB handler might be:\nXXX - WHAT ???\nAlternatively, this code could be stored in an external file, and loaded using:\nperl 'do /usr/share/snmp/perlexample.pl';\n" }, { "name": "Dynamically Loadable Modules", "content": "TODO\ndlmod NAME PATH\"\n" }, { "name": "Proxy Support", "content": "A configuration for acting as a simple proxy for two other SNMP agents (running on remote\nsystems) might be:\ncom2sec -Cn rem1context rem1user default remotehost1\ncom2sec -Cn rem2context rem2user default remotehost2\n\nproxy -Cn rem1context -v 1 -c public remotehost1 .1.3\nproxy -Cn rem2context -v 1 -c public remotehost2 .1.3\n(plus suitable access control entries).\n\nThe same proxy directives would also work with (incoming) SNMPv3 requests, which can specify\na context directly. It would probably be more sensible to use contexts of remotehost1 and\nremotehost2 - the names above were chosen to indicate how these directives work together.\n\nNote that the administrative settings for the proxied request are specified explicitly, and\nare independent of the settings from the incoming request.\n\nAn alternative use for the proxy directive is to pass part of the OID tree to another agent\n(either on a remote host or listening on a different port on the same system), while handling\nthe rest internally:\nproxy -v 1 -c public localhost:6161 .1.3.6.1.4.1.99\nThis mechanism can be used to link together two separate SNMP agents.\n\nA less usual approach is to map one subtree into a different area of the overall MIB tree\n(either locally or on a remote system):\n# uses SNMPv3 to access the MIB tree .1.3.6.1.2.1.1 on 'remotehost'\n# and maps this to the local tree .1.3.6.1.3.10\nproxy -v 3 -l noAuthNoPriv -u user remotehost .1.3.6.1.3.10 .1.3.6.1.2.1.1\n" }, { "name": "SMUX Sub-Agents", "content": "smuxsocket 127.0.0.1\nsmuxpeer .1.3.6.1.2.1.14 ospfpass\n" }, { "name": "AgentX Sub-Agents", "content": "The Net-SNMP agent could be configured to operate as an AgentX master agent (listening on a\nnon-standard named socket, and running using the access privileges defined earlier), using:\nmaster agentx\nagentXSocket /tmp/agentx/master\nagentXPerms 0660 0550 nobody snmp\nA sub-agent wishing to connect to this master agent would need the same agentXSocket direc‐\ntive, or the equivalent code:\nnetsnmpdssetstring(NETSNMPDSAPPLICATIONID, NETSNMPDSAGENTXSOCKET,\n\"/tmp/agentx/master\");\n\nA loopback networked AgentX configuration could be set up using:\nagentXSocket tcp:localhost:705\nagentXTimeout 5\nagentXRetries 2\non the master side, and:\nagentXSocket tcp:localhost:705\nagentXTimeout 10\nagentXRetries 1\nagentXPingInterval 600\non the client.\n\nNote that the timeout and retry settings can be asymmetric for the two directions, and the\nsub-agent can poll the master agent at regular intervals (600s = every 10 minutes), to ensure\nthe connection is still working.\n" } ] }, "OTHER CONFIGURATION": { "content": "override sysDescr.0 octetstr \"my own sysDescr\"\ninjectHandler stashcache NAME tableiterator\n", "subsections": [] }, "FILES": { "content": "/etc/snmp/snmpd.conf\n", "subsections": [] }, "SEE ALSO": { "content": "snmpconf(1), snmpd.conf(5), snmp.conf(5), snmpconfig(5), snmpd(8), EXAMPLE.conf, net‐\nsnmpconfigapi(3).\n\n\n\nV5.9.1 13 Oct 2006 SNMPD.EXAMPLES(5)", "subsections": [] } } } }