view cust1 included interfaces.ifTable.ifEntry.ifIndex.1 ff.a0 view cust2 included interfaces.ifTable.ifEntry.ifIndex.2 ff.a0
- VACM Examples:
- # sec.name source community com2sec local localhost private com2sec mynet 10.10.10.0/24 public com2sec public default public com2sec6 mynet fec0::/64 public # sec.model sec.name group mygroup v1 mynet group mygroup v2c mynet group mygroup usm mynet group local v1 local group local v2c local group local usm local group public v1 public group public v2c public group public usm public # incl/excl subtree mask view all included .1 80 view system included system fe view mib2 included .iso.org.dod.internet.mgmt.mib-2 fc # context sec.model sec.level prefix read write notify access mygroup "" any noauth exact mib2 none none access public "" any noauth exact system none none access local "" any noauth exact all all all
- Default VACM model
- The default configuration of the agent, as shipped, is functionally equivalent to the following entries: com2sec public default public group public v1 public group public v2c public group public usm public view all included .1 access public "" any noauth exact all none none
SNMPv3 CONFIGURATION
- engineID STRING
- The snmpd agent needs to be configured with an engineID to be able to respond to SNMPv3 messages. With this configuration file line, the engineID will be configured from STRING. The default value of the engineID is configured with the first IP address found for the hostname of the machine.
- createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES] [privpassphrase]
- MD5 and SHA are the authentication types to use, but you must have built the package with openssl installed in order to use SHA. The only privacy protocol currently supported is DES. If the privacy passphrase is not specified, it is assumed to be the same as the authentication passphrase. Note that the users created will be useless unless they are also added to the VACM access control tables described above.
- Warning: the minimum pass phrase length is 8 characters.
- SNMPv3 users can be created at runtime using the snmpusm(1) command.
- Instead of figuring out how to use this directive and where to put it (see below), just run "net-snmp-config --create-snmpv3-user" instead, which will add one of these lines to the right place.
- This directive should be placed into the /var/net-snmp/snmpd.conf file instead of the other normal locations. The reason is that the information is read from the file and then the line is removed (eliminating the storage of the master password for that user) and replaced with the key that is derived from it. This key is a localized key, so that if it is stolen it can not be used to access other agents. If the password is stolen, however, it can be.
- If you need to localize the user to a particular EngineID (this is useful mostly in the similar snmptrapd.conf file), you can use the -e argument to specify an EngineID as a hex value (EG, "0x01020304").
SETTING SYSTEM INFORMATION
- syslocation STRING
- syscontact STRING
- sysname STRING
- Sets the system location, system contact or system name for the agent. This information is reported in the 'system' group the mibII tree. Ordinarily these objects (sysLocation.0, sysContact.0 and sysName.0) are read-write. However, specifying the value for one of these objects by giving the appropriate token makes the corresponding object read-only, and attempts to set the value of the object will result in a notWritable error response.
- sysservices NUMBER
- Sets the value of the system.sysServices.0 object. For a host, a good value is 72.
- sysdescr STRING
- sysobjectid OID
- Sets the system description or object ID for the agent. Although these values are not SNMP-writable, it is conceivable that a network administrator may wish to configure them to something other than the default values.
- agentaddress [
:] [,...] - Makes the agent list on the specified comma-separated list of listening addresses instead of the default behaviour, which is to listen on UDP port 161 on all IPv4 interfaces. See the section LISTENING ADDRESSES in the snmpd(8) manual page for more information about the format of listening addresses. For example, specifying agentaddress 161,tcp:161,localhost:9161 will make the agent listen on UDP port 161 on all IPv4 interfaces, TCP port 161 on all IPv4 interfaces and UDP port 9161 only on the interface associated with the localhost address.
- agentgroup groupid
- Change to this gid after opening port. The groupid may refer to a group by name or a number if the group number starts with '#'. For example, specifying agentgroup snmp will cause the agent to run as the snmp group or agentgroup #10 will cause the agent to run as the group with groupid 10.
- agentuser uid
- Change to this uid after opening port. The userid may refer to a user by name or a number if the user number starts with '#'. For example, specifying agentuser snmp will cause the agent to run as the snmp user or agentuser #10 will cause the agent to run as the user with userid 10.
- interface NAME TYPE SPEED
- For interfaces where the agent fails to guess correctly on the type and speed, this directive can supply additional information. TYPE is a type value as given in the IANAifType-MIB.
- ignoredisk STRING
- When scanning for available disk devices the agent might block in trying to open all possible disk devices. This might lead to a timeout when walking the device tree. Sometimes the next walk will run without timeout, sometimes it will timeout every time you try it.
- If you experience such behaviour you might add this directive and give all device names not to be checked (i.e. opened). You might have more than one such directive in your configuration file stating all devices not to be opened. You might also specify those devices using wildcards similar to the syntax you can use in a bourne shell (see examples below).
- Note: For a list of devices scanned for every system please consult the sources (host/hr_disk.c) and check for the Add_HR_Disk_entry() calls relevant for your type of OS.
- Examples:
- ignoredisk /dev/rdsk/c0t2d0
- This directive prevents the device /dev/rdsk/c0t2d0 from being scanned.
- ignoredisk /dev/rdsk/c0t[!6]d0
- This directive prevents all devices /dev/rdsk/c0tXd0 except .../c0t6d0 from being scanned. For most systems similar is the following directive:
- ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0
- ignoredisk /dev/rdsk/c1*
- This directive prevents all devices whose device names start with /dev/rdsk/c1 from being scanned.
- ignoredisk /dev/rdsk/c?t0d0
- This directive prevents all devices /dev/rdsk/cXt0d0 ('X' might be any char) from being scanned.
- You might use more than one such wildcard expression in any such directive.
- storageUseNFS NUMBER
- Setting storageUseNFS to 1 causes all NFS and NFS-like file systems to be marked as 'Network Disks' in the hrStorageTable. This is according to RFC 2790. Not setting storageUseNFS or setting it to 2 causes NFS and NFS-like file systems to be marked as 'Fixed Disks' as it has been in previous versions of the ucd-snmp SNMP agent.
- authtrapenable NUMBER
- Setting authtrapenable to 1 enables generation of authentication failure traps. The default value is disabled(2). Ordinarily the corresponding object (snmpEnableAuthenTraps.0) is read-write, but setting its value via this token makes the object read-only, and attempts to set the value of the object will result in a notWritable error response.
- override OID TYPE VALUE
- This directive allows you to override a particular OID with a different value (and possibly a different type of value). An example:
- override sysDescr.0 octet_str "my own sysDescr"
- That line will set the sysDescr.0 value to "my own sysDescr" as well as make it modifiable with SNMP SETs as well (which is actually illegal according to the MIB specifications).
- Note that care must be taken when using this. For example, if you try to override a property of the 3rd interface in the ifTable with a new value and later the numbering within the ifTable changes it's index ordering you'll end up with problems and your modified value won't appear in the right place in the table.
- Valid TYPEs are: integer, uinteger, octet_str, bit_str, object_id, counter, gauge, null. Note that setting an object to "null" effectively delete's it as being accessible. No VALUE needs to be given if the object type is null.
- More types should be available in the future, as well as writable object support.
SETTING UP TRAP AND/OR INFORM DESTINATIONS
- trapcommunity STRING
- This defines the default community string to be used when sending traps. Note that this command must be used prior to any of the following three commands that are intended use this community string.
- trapsink HOST [COMMUNITY [PORT]]
- trap2sink HOST [COMMUNITY [PORT]]
- informsink HOST [COMMUNITY [PORT]]
- These commands define the hosts to receive traps (and/or inform notifications). The daemon sends a Cold Start trap when it starts up. If enabled, it also sends traps on authentication failures. Multiple trapsink, trap2sink and informsink lines may be specified to specify multiple destinations. Use trap2sink to send SNMPv2 traps and informsink to send inform notifications. If COMMUNITY is not specified, the string from a preceding trapcommunity directive will be used. If PORT is not specified, the well known SNMP trap port (162) will be used.
- trapsess [SNMPCMD_ARGS] HOST
- This is a more generic trap configuration token that allows any type of trap destination to be specified with any version of SNMP. See the snmpcmd(1) manual page for further details on the arguments that can be passed as SNMPCMD ARGS. In addition to the arguments listed there, the special argument -Ci specifies that you want inform notifications to be used instead of unacknowledged traps (this requires that you also specify a version number of v2c or v3 as well).
PROXY SUPPORT
- proxy [-Cn CONTEXTNAME] [SNMPCMD ARGS] HOST OID [REMOTEOID]
- This token specifies that any incoming requests under OID should be proxied on to another HOST instead. If a CONTEXTNAME is specified, it assigns the proxied tree to a particular context name within the local agent. This is the proper way to query multiple agents through a single proxy. Assign each remote agent to a different context name. Then you can use "snmpwalk -n contextname1" to walk one remote proxied agent and "snmpwalk -n contextname2" to walk another, assuming you are using SNMPv3 to talk to the proxy (snmpv1 and snmpv2c context mappings aren't currently supported but might be in the future). Optionally, relocate the local OID tree to the new location at the REMOTEOID. To authenticate to HOST you should use the appropriate set of SNMPCMD ARGS. See the snmpcmd(1) manual page for details.
-
Examples:
-
-
# assigns the entire mib tree on remotehost1 to the context of the # same name: proxy -Cn remotehost1 -v 1 -c public remotehost1 .1.3 # ditto, but for remotehost 2 proxy -Cn remotehost2 -v 1 -c public remotehost2 .1.3 # proxies only the ucdavis enterprises tree to the remote host using snmpv1 proxy -v 1 -c public remotehost .1.3.6.1.4.1.2021 # uses v3 to access remotehost and converts the remote .1.3.6.1.2.1.1 # oid to local .1.3.6.1.3.10 oid (another way to access mulitple hosts # without using contexts) proxy -v 3 -l noAuthNoPriv -u user remotehost .1.3.6.1.3.10 .1.3.6.1.2.1.1
-
-
PASS-THROUGH CONTROL
- pass MIBOID EXEC
-
(If you're writing perl scripts, please see the embedded perl support information later in this manual page). Passes entire control of MIBOID to the EXEC program. The EXEC program is called in one of the following three ways:
-
- EXEC -g MIBOID
- EXEC -n MIBOID
- These call lines match to SNMP get and getnext requests. It is expected that the EXEC program will take the arguments passed to it and return the appropriate response through it's stdout.
- The first line of stdout should be the MIB OID of the returning value. The second line should be the TYPE of value returned, where TYPE is one of the text strings: string, integer, unsigned, objectid, timeticks, ipaddress, counter, or gauge. The third line of stdout should be the VALUE corresponding with the returned TYPE.
-
For instance, if a script was to return the value integer value "42" when a request for .1.3.6.1.4.100 was requested, the script should return the following 3 lines:
-
.1.3.6.1.4.100
integer
42
-
- To indicate that the script is unable to comply with the request due to an end-of-mib condition or an invalid request, simple exit and return no output to stdout at all. An SNMP error will be generated corresponding to the SNMP noSuchName response.
- EXEC -s MIBOID TYPE VALUE
- For SNMP set requests, the above call method is used. The TYPE passed to the EXEC program is one of the text strings: integer, counter, gauge, timeticks, ipaddress, objid, or string, indicating the type of value passed in the next argument.
-
Return nothing to stdout, and the set will assumed to have been successful. Otherwise, return one of the following error strings to signal an error: not-writable, or wrong-type and the appropriate error response will be generated instead.
-
- Note:
- By default, the only community allowed to write (ie snmpset) to your script will be the "private" community,or community #2 if defined differently by the "community" token discussed above. Which communities are allowed write access are controlled by the RWRITE definition in the snmplib/snmp_impl.h source file.
-
-
- Example (in snmpd.conf):
- pass .1.3.6.1.4.1.2021.255 /path/to/local/passtest
- pass_persist MIBOID EXEC
- Passes entire control of MIBOID to the EXEC program. Similar to pass, but the EXEC program continues to run after the initial request is answered. Also, pass and pass_persist block till they return.
- Upon initialization, EXEC is passed the string "PING\n" in stdin, and it should respond by printing "PONG\n" to stdout.
- For get and getnext requests, EXEC program is passed two lines, the command (get or getnext) and the MIB OID. It should return three lines, the MIB OID, the TYPE of value returned, the VALUE corresponding with the returned TYPE.
-
For example, if the value for .1.3.6.1.4.100 was requested, the following 2 lines would be passed in to stdin:
-
get
.1.3.6.1.4.100
-
-
To return the value, say, 42, the script would write to stdout:
-
.1.3.6.1.4.100
integer
42
-
- To indicate that the script is unable to comply with the request due to an end-of-mib condition or an invalid request, print "NONE\n" to stdout.
- Example (in snmpd.conf):
- pass_persist .1.3.6.1.4.1.2021.255 /path/to/local/pass_persisttest
EMBEDDED PERL SUPPORT
Warning: though embedded perl is working, not much functionality has been implemented yet and thus writing mib module pieces for the agent within perl is not trivial at this point. It should get better in future releases.
The net-snmp package has ability to call perl scripts directly inside the agent through embedded perl technology (similar to mod_perl for the apache web server). This must be turned on at compile time by passing --enable-embedded-perl to the configure script when the package is built. To see if your package was built with embedded perl, run "net-snmp-config --configure-options" and see if that flag was used.
If compiled in, it defines the following snmpd.conf configuration directives:
- disablePerl true
- This will turn off perl support entirely. If the embedded perl support stops working due to a change in perl, etc, this will stop any calls to the perl core.
- perlInitFile FILE
- Use FILE as the initialization file. This file is normally /usr/local/share/snmp/snmp_perl.pl but this token can override that default. This file performs any in-perl initialization that is needed before the rest of the perl directives (below) are called. It is sourced once just before the first perl directive is parsed. See the default file for an example of the initialization it performs.
- perl EXPRESSION
- Calls perl to evaluate an expression. Normally you'd want to do something like register a function to call when an OID is requested, but you can really do anything perl related you want. For example:
-
- perl print "hello world\n";
- is the most basic hello world example.
- The init script by default initializes a $agent variable which is a pointer to a NetSnmp::agent object through which you can register callbacks when a section of the OID tree is hit:
-
-
perl use Data::Dumper; perl sub myroutine { print "got called: ",Dumper(@_),"\n"; } perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
-
- Sourcing an external file:
-
-
perl 'do /path/to/file.pl';
-
- No better examples exist at the moment, unfortunately. Look for improved support in future releases. Comments on how this looks as an architecture are certainly appreciated now.
DISMAN-EVENT-MIB SUPPORT (READ: SENDING TRAPS ON ERRORS)
Warning: this implementation has not been extensively tested and is additionally not known to be entirely complete. The concepts defined here should function appropriately, however, but no promises are made at this time.
If your agent was compiled with support for the DISMAN-EVENT-MIB (you can enable this by running the net-snmp configure script with the --with-mib-modules=disman/event-mib argument) you have support for having the agent check its own data at regular intervals and to send out traps when certain conditions occur. Traps are sent when expressions are first noticed, not once per evaluation. Once a test expression fires a trap, the test will have to fail again before a new trap is sent. See the DISMAN-EVENT-MIB documentation for more details. This can be configured either using the MIB tables themselves or by using these special key words:
- agentSecName NAME
-
The DISMAN-EVENT-MIB support requires a valid user name for which to scan your agent with. This can either be specified using the agentSecName token or by explicitly list one on the "monitor" lines described below using the -u switch. Either way, a "rouser" line (or equivalent access control settings) must also be specified with the same security name name. If you need an example, just do something like this:
-
-
agentSecName internal rouser internal
-
-
- And everything below should work just fine.
- monitor [OPTIONS] NAME EXPRESSION
-
This token tells the agent to monitor itself for problems based on EXPRESSION. Expression is a simple expression based on an oid, a comparison operator (!=, ==, <, <=, >, >=) and an integer value (see the examples below). NAME is merely an arbitrary name of your choosing for administrative purposes only. OPTIONS include the following possibilities:
-
- -t
- Use a threshold monitor instead of a boolean monitor. This means that expression should be a low and high value. If the given OID passes beyond the high value, a rising alarm will triggered. A falling alarm will then be triggered after it falls below the low value.
- -r FREQUENCY
- Monitors the given expression every FREQUENCY seconds. The default is 600 (10 minutes).
- -u SECNAME
- Use the SECNAME security name for scanning the local host. Specifically, this SECNAME must then be given access control rights via something like the "rouser" snmpd.conf token for this expression to be valid at all. If not specified, it uses the default security name specified by the agentsecname snmpd.conf token. Either the -u flag or a valid agentsecname token must be specified (and that name must be given proper access control rights via a "rouser" token).
- -o OID
- Specifies additional object values to be delivered with in the resulting trap in addition to the normal trap objects. This is useful for obtaining other columns in the table for the row that triggered the expression. See the examples below for more details.
- -e EVENTNAME
- Specifies an event name that describes what to do when the trigger is fired. Currently, this must be the name of a notificationEvent event as described below.
-
-
The following example configuration checks the hrSWRunPerfTable table (listing running processes) for any process which is consuming > 10Mb of memory. It performs this check every 600 seconds (the default). For every process it finds exceeding the limit, it will end out exactly one notification. In addition to the normal hrSWRunPerfMem oid and value sent in the trap, the hrSWRunName object will also be sent. Note that the hrSWRunName object actually occurs in a different table, but since the indexes to the two tables are the same this works out alright.
-
-
rouser me monitor -u me -o sysUpTime.0 -o hrSWRunName "high process memory" hrSWRunPerfMem > 10000
-
-
-
The above line would produce a trap which, when formated by snmptrapd, would look like:
-
-
2002-04-05 13:33:53 localhost.localdomain [udp:127.0.0.1:32931]: sysUpTimeInstance = Timeticks: (1629) 0:00:16.29 snmpTrapOID.0 = OID: mteTriggerFired mteHotTrigger = high process memory mteHotTargetName = mteHotContextName = mteHotOID = OID: hrSWRunPerfMem.1968 mteHotValue = 28564 hrSWRunName.1968 = "xemacs"
-
-
- This shows my xemacs process using 28Mb of resident memory. Which, considering it's xemacs, is not that surprising.
-
Threshold example:
-
- monitor -t -r 15 -o prNames -o prErrMessage "process table" prErrorFlag 0 1
-
- notificationEvent NAME NOTIFICATION [[-w] OID_OBJECT ...]
- This will create a notification event, which can be fired by attaching it to a monitor using a monitor's -e switch and an identical NAME field. The NOTIFICATION to be sent should be the OID of a notification. Additional objects can be included, and by default the suffix of the row/object being monitored will be appended to the object identifier unless it's told not to be a wild-card object by prefixing it with the -w switch. EG, if you're monitoring the ifTable and you want your trap to include the ifDescr object for the row that was discovered, don't add the -w switch and the .INDEX field will be appended. If the OID is fully qualified (EG, "sysContact.0") and no instance suffix should be appended to it then add a -w switch before it. See the linkUpDownNotifications token below for example usage of this token to send the linkUp and linkDown traps.
- linkUpDownNotifications yes
-
This will make the DISMAN-EVENT-MIB support watch the ifTable to determine when a network interface is taken up or down. When this happens, a linkUp or linkDown notification will be triggered. This is exactly equivalent to doing:
-
-
notificationEvent linkUpTrap linkUp ifIndex ifAdminStatus ifOperStatus notificationEvent linkDownTrap linkDown ifIndex ifAdminStatus ifOperStatus monitor -r 60 -e linkUpTrap "Generate linkUp" ifOperStatus != 2 monitor -r 60 -e linkDownTrap "Generate linkDown" ifOperStatus == 2
-
-
- defaultMonitors yes
-
By default, the agent and the DISMAN-EVENT-MIB support do nothing until configured. Typically people wish to watch a bunch of tables within the UCD-SNMP-MIB which are designed specifically for reporting problems. If the "defaultMonitors yes" line is put into the snmpd.conf file (which must be accompanied by an appropriate agentSecName line and a rouser line), the following monitoring conditions will be installed:
-
-
monitor -o prNames -o prErrMessage "process table" prErrorFlag != 0 monitor -o memErrorName -o memSwapErrorMsg "memory" memSwapError != 0 monitor -o extNames -o extOutput "extTable" extResult != 0 monitor -o dskPath -o dskErrorMsg "dskTable" dskErrorFlag != 0 monitor -o laNames -o laErrMessage "laTable" laErrorFlag != 0 monitor -o fileName -o fileErrorMsg "fileTable" fileErrorFlag != 0
-
-
DEBUGGING AND OTHER EXTENSIBILITY NOTES
If you're trying to figure out aspects of the various mib modules (possibly some that you've added yourself), the following may help you spit out some useful debugging information. First off, please read the snmpd manual page on the -D flag. Then the following configuration snmpd.conf token, combined with the -D flag, can produce useful output:- injectHandler HANDLER modulename
-
This will insert new handlers into the section of the mib tree referenced by "modulename". The types of handlers available for insertion are:
-
stash_cache - Caches information returned from the lower level. This greatly help the performance of the agent, at the cost of caching the data such that its no longer "live" for 30 seconds (in this future, this will be configurable). Note that this means snmpd will use more memory as well while the information is cached. Currently this only works for handlers registered using the table_iterator support, which is only a few mib tables. To use it, you need to make sure to install it before the table_iterator point in the chain, so to do this: injectHandler stash_cache NAME table_iterator If you want a table to play with, try walking the nsModuleTable with and without this injected. debug - Prints out lots of debugging information when the -Dhelper:debug flag is passed to the snmpd application. read_only - Forces turning off write support for the given module. serialize - If a module is failing to handle multiple requests properly (using the new 5.0 module API), this will force the module to only receive one request at a time. bulk_to_next - If a module registers to handle getbulk support, but for some reason is failing to implement it properly, this module will convert all getbulk requests to getnext requests before the final module receives it.
-
- Figuring out module names
- To figure out which modules you can inject things into, snmpwalk the nsModuleTable which will give you a list of all named modules registered within the agent.
EXAMPLE CONFIGURATION FILE
See the EXAMPLE.CONF file in the top level source directory for a more detailed example of how the above information is used in real examples.RE-READING snmpd.conf AND snmpd.local.conf
The Net-SNMP agent can be forced to re-read its configuration files. It can be told to do so by one of two ways:- 1.
- An snmpset of integer(1) to UCD-SNMP-MIB::versionUpdateConfig.0 (.1.3.6.1.4.1.2021.100.11.0)
- 2.
- A "kill -HUP" signal sent to the snmpd agent process.
FILES
/usr/local/etc/snmp/snmpd.confSEE ALSO
snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, read_config(3).Index
- NAME
- DESCRIPTION
- PLEASE READ FIRST
- EXTENSIBLE-MIB
-
- Directives
- Errors
- AGENTX SUB-AGENTS
- SMUX SUB-AGENTS
- DYNAMICALLY LOADABLE MODULES
- ACCESS CONTROL
- SNMPv3 CONFIGURATION
- SETTING SYSTEM INFORMATION
- SETTING UP TRAP AND/OR INFORM DESTINATIONS
- PROXY SUPPORT
- PASS-THROUGH CONTROL
- EMBEDDED PERL SUPPORT
- DISMAN-EVENT-MIB SUPPORT (READ: SENDING TRAPS ON ERRORS)
- DEBUGGING AND OTHER EXTENSIBILITY NOTES
- EXAMPLE CONFIGURATION FILE
- RE-READING snmpd.conf AND snmpd.local.conf
- FILES
- SEE ALSO
This document was created by man2html, using the manual pages.
Time: 05:28:00 GMT, March 21, 2004
Powered by: