snmpd.conf.5.def
上传用户:wxp200602
上传日期:2007-10-30
资源大小:4028k
文件大小:43k
- .TH SNMPD.CONF 5 "08 Feb 2002" VVERSIONINFO "Net-SNMP"
- .UC 4
- .SH NAME
- snmpd.conf - configuration file for the Net-SNMP SNMP agent
- .SH DESCRIPTION
- .B snmpd.conf
- is the configuration file which defines how the Net-SNMP SNMP agent
- operates. These files may contain any of the directives found in the
- .B DIRECTIVES
- section below. If this file is not found (or does not contain any
- access control directives), the agent will run but will not respond
- to any requests.
- .SH PLEASE READ FIRST
- First, make sure you have read the
- .I snmp_config(5)
- manual page that describes how the Net-SNMP configuration files
- operate, where they are located and how they all work together.
- .PP
- Also, you might consider looking into the
- .B snmpconf
- application (perl script) which can help you build an snmpd.conf file
- by prompting you for information. You should try it. Really. Go
- ahead. Right now. Run:
- .RS
- .IP "snmpconf -g basic_setup"
- .RE
- .PP
- to get you started. See the
- .I snmpconf(1)
- manual page for more information.
- .SH EXTENSIBLE-MIB
- .PP
- The Net-SNMP SNMP agent reports much of its information through
- queries to the EXTENSIBLEDOTMIB section of the MIB tree. Every MIB in
- this section has the following table entries in it.
- .IP ".MIBINDEX -- index"
- This is the table's index numbers for each of the DIRECTIVES listed below.
- .IP ".ERRORNAME -- name"
- The name of the given table entry. This should be unique, but is not
- required to be.
- .IP ".ERRORFLAG -- errorFlag"
- This is a flag returning either the integer value 1 or 0 if an error
- is detected for this table entry.
- .IP ".ERRORMSG -- errorMsg"
- This is a DISPLAY-STRING describing any error triggering the errorFlag above.
- .IP ".ERRORFIX -- errorFix"
- If this entry is set to the integer value of 1 AND the errorFlag
- defined above is indeed a 1, a program or script will get executed
- with the table entry name from above as the argument. The program to
- be executed is configured in the net-snmp-config.h file at compile time.
- .SS Directives
- .IP "proc NAME"
- .IP "proc NAME MAX"
- .IP "proc NAME MAX MIN"
- .IP
- Checks to see if processes called NAME are running on the agent
- machine. An error flag (1) and a description message are then passed
- to the EXTENSIBLEDOTMIB.PROCMIBNUM.1.ERRORFLAG and
- EXTENSIBLEDOTMIB.PROCMIBNUM.1.ERRORMSG MIB columns (respectively) if
- the NAME'd program is not found in the process table as reported by
- PSCMD.
- .IP
- If MAX and MIN are not specified, MAX is assumed to be
- .B infinity
- and MIN is assumed to be 1.
- .IP
- If MAX is specified but MIN is not specified, MIN is assumed to be 0.
- .IP "procfix NAME PROG ARGS"
- This registers a command that knows how to fix errors with the given
- process NAME. When EXTENSIBLEDOTMIB.PROCMIBNUM.1.ERRORFIX for a given
- NAMEd program is set to the integer value of 1, this command will be
- called. It defaults to a compiled value set using the PROCFIXCMD
- definition in the net-snmp-config.h file.
- .IP "exec NAME PROG ARGS"
- .IP "exec MIBNUM NAME PROG ARGS"
- .IP
- If MIBNUM is not specified, the agent executes the named PROG with
- arguments of ARGS and returns the exit status and the first line of
- the STDOUT output of the PROG program to queries of the
- EXTENSIBLEDOTMIB.SHELLMIBNUM.1.ERRORFLAG and
- EXTENSIBLEDOTMIB.SHELLMIBNUM.1.ERRORMSG mib columns (respectively). All
- STDOUT output beyond the first line is silently truncated.
- .IP
- If MIBNUM is specified, it acts as above but returns the exit status
- to MIBNUM.ERRORFLAG.0 and the entire STDOUT output to the table
- MIBNUM.ERRORMSG in a MIB table. In this case, the MIBNUM.ERRORMSG mib
- contains the entire STDOUT output, one MIB table entry per line of
- output (ie, the first line is output as MIBNUM.ERRORMSG.1, the second
- at MIBNUM.ERRORMSG.2, etc...).
- .RS
- .IP Note:
- The PROG argument must be a full path to a real binary, as it is
- executed under the exec() system call. IE, you can not specify a path
- to a shell script. If you want to invoke a shell script, please
- specify a path to the interpreter first as the PROG argument and then
- a path to the shell script. IE: "exec myscript /bin/sh
- /path/to/script arg1 ..."
- .IP Note:
- The MIBNUM must be specified in dotted-integer notation and can
- not be specified as ".iso.org.dod.internet..." (should instead
- be .1.3.6.1...).
- .IP Note:
- The agent caches the exit status and STDOUT of the executed program
- for 30 seconds after the initial query. This is to increase speed and
- maintain consistency of information for consecutive table queries.
- The cache can be flushed by a snmp-set request of integer(1) to
- EXTENSIBLEDOTMIB.VERSIONMIBNUM.VERCLEARCACHE.
- .RE
- .IP "extend NAME PROG ARGS"
- .IP "extend MIBNUM NAME PROG ARGS"
- .IP
- This is similar to the 'exec' directive, but uses a different MIB output
- structure (for both forms) which covers multi-line output as standard.
- See NET-SNMP-EXTEND-MIB for details.
- Output is cached for each entry separately, controlled by the
- NET-SNMP-AGENT-MIB::nsCacheTable.
- .IP "execfix NAME PROG ARGS"
- This registers a command that knows how to fix errors with the given
- exec or sh NAME. When EXTENSIBLEDOTMIB.SHELLMIBNUM.1.ERRORFIX for a
- given NAMEd entry is set to the integer value of 1, this command will
- be called. It defaults to a compiled value set using the EXECFIXCMD
- definition in the net-snmp-config.h file.
- .IP "disk PATH"
- .IP "disk PATH [ MINSPACE | MINPERCENT% ]"
- .IP
- Checks the named disks mounted at PATH for available disk space. If
- the disk space is less than MINSPACE (kB) if specified or less than
- MINPERCENT (%) if a % sign is specified, or DEFDISKMINIMUMSPACE (kB)
- if not specified, the associated entry in the
- EXTENSIBLEDOTMIB.DISKMIBNUM.1.ERRORFLAG MIB table will be set to (1) and
- a descriptive error message will be returned to queries of
- EXTENSIBLEDOTMIB.DISKMIBNUM.1.ERRORMSG.
- .IP "includeAllDisks MINPERCENT%"
- .IP
- Adds all the disks that can be found on the system using the
- setmntent(3) and getmntent(3), or fopen(3) and getmntent(3), or
- setfsent(3) and getfsent(3) system calls. If none of the above
- system calls are available then it adds the root partition "/",
- (which is assumed to exist on any UNIX based system) using the
- statfs(2) system call.
- .IP
- There can only be one 'includeAllDisks' directive in the config-
- uration file. It can be used in conjunction with the 'disk'
- directive. They may be used in any order. The 'disk' directive
- overrides the disk usage specified by the 'includeAllDisks'
- directive, no matter in which order they are specified in the
- configuration file.
- .IP
- The 'includeAllDisks' directive only includes the disks that are
- mounted when the snmpd daemon is started. It cannot include
- disks that are dynamically loadable, such as with automount. So
- the preferred way is to mount all the disks that will ever need
- to be monitored before starting the snmpd daemon.
- .IP "load MAX1"
- .IP "load MAX1 MAX5"
- .IP "load MAX1 MAX5 MAX15"
- .IP
- Checks the load average of the machine and returns an error flag (1),
- and an text-string error message
- to queries of EXTENSIBLEDOTMIB.LOADAVEMIBNUM.1.ERRORFLAG and
- EXTENSIBLEDOTMIB.LOADAVEMIBNUM.1.ERRORMSG (respectively) when the
- 1-minute, 5-minute, or 15-minute averages exceed the associated
- maximum values. If any of the MAX1, MAX5, or MAX15 values are
- unspecified, they default to a value of DEFMAXLOADAVE.
- .IP "file FILE [MAXSIZE]"
- Monitors file sizes and makes sure they don't grow beyond a certain
- size (in kilobytes). MAXSIZE defaults to infinite if not specified,
- and only monitors the size without reporting errors about it.
- A maximum of 20 files can be monitored.
- .IP "logmatch NAME PATH CYCLETIME REGEX"
- Configures log file monitoring that can be queried via the
- UCD-SNMP-MIB::logMatchTable.
- .SS "Errors"
- .PP
- Any errors in obtaining the above information are reported via the
- EXTENSIBLEDOTMIB.ERRORMIBNUM.1.ERRORFLAG flag and the
- EXTENSIBLEDOTMIB.ERRORMIBNUM.1.ERRORMSG text-string description.
- .SH AGENTX SUB-AGENTS
- To enable AgentX support in the SNMP master agent, put the following
- line in your snmpd.conf file:
- .IP "master agentx"
- See README.agentx for further details.
- .IP "AgentXSocket addr"
- This defines the address the master agent listens at.
- The default is /var/agentx/master. By default the Unix Domain socket is
- accessible only to subagents which have the same userid as the agent.
- Another possibility is localhost:705
- .IP "AgentXTimeout addr"
- Defines the timeout period for an AgentX request.
- Default is 1 second.
- .IP "AgentXRetries addr"
- Defines the number of retries for an AgentX request.
- Default is 5 retries.
- .IP "agentxperms socket_perms [directory_perms [username|userid [groupname|groupid]]]"
- Defines the permissions of the AgentX socket. socket_perms and directory_perms must be octal digits (see
- .I chmod(1)
- ).
- .P
- You can also put the following in your subagent.conf file (where
- "subagent" is the name you used in your init_snmp("subagent") api call:
- .IP "agentPingInterval NUM"
- This makes the subagent try and reconnect every NUM seconds to the
- master if it ever becomes (or starts) disconnected.
- .SH SMUX SUB-AGENTS
- To enable and SMUX based sub-agent, such as
- .IR gated ,
- use the
- .I smuxpeer
- configuration entry
- .IP "smuxpeer OID PASS"
- For
- .I gated
- a sensible entry might be
- .I smuxpeer .1.3.6.1.4.1.4.1.3 secret
- .SH DYNAMICALLY LOADABLE MODULES
- If the agent is built with support for the UCD-DLMOD-MIB it is capable
- of loading agent MIB modules dynamically at startup through
- the fIdlmodfR directive and during runtime through use of the UCD-DLMOD-MIB.
- The following directive loads the shared object module file PATH which
- uses the module name prefix NAME.
- .IP "dlmod NAME PATH"
- .IP
- .SH ACCESS CONTROL
- .B snmpd
- supports the View-Based Access Control Model (VACM) as defined in RFC
- 2575. To this end, it recognizes the following keywords in the
- configuration file: fIcom2secfR, fIgroupfR, fIaccessfR, and
- fIviewfR as well as some easier-to-use wrapper directives:
- fIrocommunityfR, fIrwcommunityfR, fIrouserfR, fIrwuserfR. If
- IPv6 support has been enabled, the fIrocommunity6fR and
- fIrwcommunity6fR tokens will also be available. This section
- defines how to configure the snmpd program to accept various types and
- levels of access.
- .IP "rouser USER [noauth|auth|priv [OID]]"
- .IP "rwuser USER [noauth|auth|priv [OID]]"
- Creates a SNMPv3 USM user in the VACM access configuration tables. It
- is more efficient (and powerful) to use the combined fIgroupfR,
- fIaccessfR, and fIviewfR directives instead, but these wrapper
- directives are much simpler.
- .IP
- The minimum level of authentication and privacy the user must use is
- specified by the first token (which defaults to "auth"). The OID
- parameter restricts access for that user to everything below the given
- OID.
- .IP "rocommunity COMMUNITY [SOURCE [OID]]"
- .IP "rwcommunity COMMUNITY [SOURCE [OID]]"
- These create read-only and read-write communities that can be used to
- access the agent. They are a quick wrapper around the more complex
- and powerful fIcom2secfR, fIgroupfR, fIaccessfR, and fIviewfR
- directive lines. They are not as efficient either, as groups aren't
- created so the tables are possibly larger. In other words: don't use
- these if you have complex situations to set up. If your setup is
- simple or you don't mind a small performance hit, use these
- directives.
- .IP
- The format of the SOURCE is token is described in the fIcom2secfR
- directive section below. The OID token restricts access for that
- community to everything below that given OID.
- .IP "rocommunity6 COMMUNITY [SOURCE [OID]]"
- .IP "rwcommunity6 COMMUNITY [SOURCE [OID]]"
- They are the alternative directives to the fIrocommunityfR,
- fIrwcommunityfR for the transport domain UDPIPv6. They are only
- valid in specifing fIUDPIPv6fR as transport domain.
- .IP
- The format of the SOURCE is token is described in the fIcom2sec6fR
- directive section below. The OID token restricts access for that
- community to everything below that given OID.
- .IP "com2sec [-Cn CONTEXT] NAME SOURCE COMMUNITY"
- This directive specifies the mapping from a source/community pair to
- a security name. SOURCE can be a hostname, a subnet, or the word
- fI"default"fR.
- A subnet can be specified as IP/MASK or IP/BITS.
- For example, given a directive
- "com2sec myLocal 10.10.10.0/24 public"
- then this would match requests from IP addresses 10.10.10.0 through
- to 10.10.10.255, but not one from 10.10.11.1 or similar.
- The first source/community combination that matches the incoming packet
- is selected. If a CONTEXT is specified, the community name gets
- mapped to the SNMPv3 CONTEXT of the same name, otherwise the default context
- ("") is used.
- .IP "com2sec6 [-Cn CONTEXT] NAME SOURCE COMMUNITY"
- This directive is the IPv6 version of fIcom2secfR.
- A subnet can be specified as IPv6/IPv6MASK or IPv6/BITS.
- It is only valid in specifing fIUDPIPv6fR as transport domain.
- .IP "com2secunix [-Cn CONTEXT] NAME SOCKPATH COMMUNITY"
- This directive is the Unix domain sockets version of fIcom2secfR.
- .IP "group NAME MODEL SECURITY"
- This directive defines the mapping from securitymodel/securityname to group.
- MODEL is one of fIv1fR, fIv2cfR, or fIusmfR.
- .IP "access NAME CONTEXT MODEL LEVEL PREFX READ WRITE NOTIFY"
- The access directive maps from group/security model/security level to
- a view.
- MODEL is one of fIanyfR, fIv1fR, fIv2cfR, or fIusmfR.
- LEVEL is one of fInoauthfR, fIauthfR, or fIprivfR.
- PREFX specifies how CONTEXT should be matched against the context of
- the incoming pdu, either fIexactfR or fIprefixfR.
- READ, WRITE and NOTIFY specifies the view to be used for the corresponding
- access.
- For v1 or v2c access, LEVEL will be noauth, and CONTEXT will be empty.
- .IP "view NAME TYPE SUBTREE [MASK]"
- This defines the named view. TYPE is either fIincludedfR or fIexcludedfR.
- MASK is a list of hex octets, separated by '.' or ':'. The MASK
- defaults to "ff" if not specified.
- .IP
- The reason for the mask is, that it allows you to control access to
- one row in a table, in a relatively simple way. As an example, as an ISP
- you might consider giving each customer access to his or her own interface:
- .IP
- .nf
- view cust1 included interfaces.ifTable.ifEntry.ifIndex.1 ff.a0
- view cust2 included interfaces.ifTable.ifEntry.ifIndex.2 ff.a0
- .IP
- (interfaces.ifTable.ifEntry.ifIndex.1 == .1.3.6.1.2.1.2.2.1.1.1,
- ff.a0 == 11111111.10100000. which nicely covers up and including
- the row index, but lets the user vary the field of the row)
- .IP "VACM Examples:"
- .nf
- # 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
- .IP "Default VACM model"
- The default configuration of the agent, as shipped, is functionally
- equivalent to the following entries:
- .nf
- 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
- .fi
- .RE
- .SH SNMPv3 CONFIGURATION
- .PP
- .IP "engineID STRING"
- The snmpd agent needs to be configured with a unique engineID to be able to
- respond to SNMPv3 messages. With this configuration file line, the
- engineID will be configured from STRING.
- .IP "engineIDType 1|2|3"
- Defines that the engineID should be built from the IPv4 address (1), IPv6 address (2) or MAC address (3). Beware that you might run into trouble on IP
- address changes!
- .IP "engineIDNic interface"
- Defines the interface (e.g. "eth1") that should be used to determine the MAC address in case of "engineIDType 3". Default is eth0.
- .P
- If neither an engineID, engineIDType or engineIDNic directive is present,
- the value of the engineID is built from 2 fairly random elements:
- a random number and the current time in seconds. This is the recommended
- approach.
- .IP "createUser [-e ENGINEID] username (MD5|SHA) authpassphrase [DES|AES] [privpassphrase]"
- .IP
- MD5 and SHA are the authentication types to use. DES and AES are the
- privacy protocols to use. 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.
- .IP
- SHA authentication and DES/AES privacy require OpenSSL to be installed and
- the agent to be built with OpenSSL support. MD5 authentication may be
- used without OpenSSL.
- .IP
- Warning: the minimum pass phrase length is 8 characters.
- .IP
- SNMPv3 users can be created at runtime using the
- .I snmpusm(1)
- command.
- .IP
- 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.
- .IP
- This directive should be placed into the
- PERSISTENT_DIRECTORY/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.
- .IP
- 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").
- .IP
- If you want to generate either your master or localized keys directly,
- replace the given password with a hexstring (preceeded by a "0x") and
- precede the hex string by a -m or -l token (respectively). EGs:
- .IP
- .RS
- .nf
- [these keys are *not* secure but are easy to visually parse for
- counting purposes. Please generate random keys instead of using
- these examples]
- createUser myuser SHA -l 0x0001020304050607080900010203040506070809 AES -l 0x00010203040506070809000102030405
- createUser myuser SHA -m 0x0001020304050607080900010203040506070809 AES -m 0x0001020304050607080900010203040506070809
- .fi
- .RE
- .IP
- Due to the way localization happens, localized privacy keys are
- expected to be the length needed by the algorithm (128 bits for all
- supported algorithms). Master encryption keys, though, need to be the
- length required by the authentication algorithm not the length
- required by the encrypting algorithm (MD5: 16 bytes, SHA: 20 bytes).
- .IP
- .SH SETTING SYSTEM INFORMATION
- .IP "syslocation STRING"
- .IP "syscontact STRING"
- .IP "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.
- .IP "sysservices NUMBER"
- Sets the value of the system.sysServices.0 object.
- For a host, a good value is 72.
- .IP "sysdescr STRING"
- .IP "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.
- .IP "leave_pidfile yes"
- Instructs the agent to not remove its pid file on shutdown. Equivalent to
- specifying "-U" on the command line.
- .IP "agentaddress [<transport-specifier>:]<transport-address>[,...]"
- 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
- .B LISTENING ADDRESSES
- in the
- .I snmpd(8)
- manual page for more information about the format of listening
- addresses. For example, specifying
- .I "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.
- .IP "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
- .I agentgroup snmp
- will cause the agent to run as the snmp group or
- .I agentgroup #10
- will cause the agent to run as the group with groupid 10.
- .IP "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
- .I agentuser snmp
- will cause the agent to run as the snmp user or
- .I agentuser #10
- will cause the agent to run as the user with userid 10.
- .IP "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.
- .IP "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.
- .IP
- 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).
- .IP
- .B 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.
- .IP
- Examples:
- .IP
- ignoredisk /dev/rdsk/c0t2d0
- .IP
- This directive prevents the device /dev/rdsk/c0t2d0 from being scanned.
- .IP
- ignoredisk /dev/rdsk/c0t[!6]d0
- .IP
- This directive prevents all devices /dev/rdsk/c0tXd0 except .../c0t6d0
- from being scanned. For most systems similar is the following directive:
- .IP
- ignoredisk /dev/rdsk/c0t[0-57-9a-f]d0
- .IP
- ignoredisk /dev/rdsk/c1*
- .IP
- This directive prevents all devices whose device names start with /dev/rdsk/c1
- from being scanned.
- .IP
- ignoredisk /dev/rdsk/c?t0d0
- .IP
- This directive prevents all devices /dev/rdsk/cXt0d0 ('X' might be any char)
- from being scanned.
- .IP
- You might use more than one such wildcard expression in any such directive.
- .IP "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.
- .IP "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.
- .IP "override [-rw] OID TYPE VALUE"
- This directive allows you to override a particular OID with a
- different value (and possibly a different type of value). The -rw
- flag will allow snmp SETs to modify it's value as well. (note that if
- you're overriding original functionality, that functionality will be
- entirely lost. Thus SETS will do nothing more than modify the
- internal overridden value and will not perform any of the original
- functionality intended to be provided by the MIB object. It's an
- emulation only.) An example:
- .IP
- override sysDescr.0 octet_str "my own sysDescr"
- .IP
- 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).
- .IP
- 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.
- .IP
- Valid TYPEs are: integer, uinteger, octet_str, object_id, counter,
- null (for gauge's, use "uinteger"; for bit strings, use "octet_str").
- 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.
- .IP
- More types should be available in the future.
- .SH "SETTING UP TRAP AND/OR INFORM DESTINATIONS"
- .IP "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.
- .IP "trapsink HOST [COMMUNITY [PORT]]"
- .IP "trap2sink HOST [COMMUNITY [PORT]]"
- .IP "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 fItrapsinkfR, fItrap2sinkfR
- and fIinformsinkfR lines may be specified to specify multiple destinations.
- Use fItrap2sinkfR to send SNMPv2 traps and fIinformsinkfR to send
- inform notifications.
- If COMMUNITY is not specified, the string from a preceding fItrapcommunityfR
- directive will be used. If PORT is not specified, the well known SNMP trap
- port (162) will be used.
- .IP "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
- .I snmpcmd(1)
- manual page for further details on the arguments that can be passed as
- .I "SNMPCMD ARGS".
- In addition to the arguments listed there, the special argument
- fI-CifR 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).
- .SH "PROXY SUPPORT"
- .IP "proxy [-Cn CONTEXTNAME] [SNMPCMD ARGS] HOST OID [REMOTEOID]"
- .IP
- This token specifies that any incoming requests under OID should be
- proxied on to another HOST instead. Use OID .1.3 (not just .1) to proxy
- the entire MIB tree. 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
- .I "SNMPCMD ARGS."
- See the
- .I snmpcmd(1)
- manual page for details.
- .IP
- Examples:
- .RS
- .nf
- # 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
- .fi
- .RE
- .SH "PASS-THROUGH CONTROL"
- .IP "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:
- .RS
- .IP "EXEC -g MIBOID"
- .IP "EXEC -n MIBOID"
- .IP
- 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.
- .IP
- 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:
- .B string, integer, unsigned, objectid, timeticks, ipaddress, counter,
- or
- .B gauge.
- The third line of stdout should be the VALUE corresponding with the
- returned TYPE.
- .IP
- 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:
- .br
- .RS
- .1.3.6.1.4.100
- .br
- integer
- .br
- 42
- .RE
- .IP
- 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.
- .IP "EXEC -s MIBOID TYPE VALUE"
- .IP
- For SNMP set requests, the above call method is used. The TYPE passed
- to the EXEC program is one of the text strings:
- .B integer, counter, gauge, timeticks, ipaddress, objid,
- or
- .B string,
- indicating the type of value passed in the next argument.
- .IP
- 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:
- .B not-writable,
- or
- .B wrong-type
- and the appropriate error response will be generated instead.
- .RS
- .IP 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.
- .RE
- .RE
- .IP
- Example (in snmpd.conf):
- .IP
- pass .1.3.6.1.4.1.2021.255 /path/to/local/passtest
- .RE
- .IP "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.
- .IP
- Upon initialization, EXEC is passed the string "PING\n" in stdin,
- and it should respond by printing "PONG\n" to stdout.
- .IP
- 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.
- .IP
- For example, if the value for .1.3.6.1.4.100 was requested, the following
- 2 lines would be passed in to stdin:
- .br
- .RS
- get
- .br
- .1.3.6.1.4.100
- .RE
- .IP
- To return the value, say, 42, the script would write to stdout:
- .br
- .RS
- .1.3.6.1.4.100
- .br
- integer
- .br
- 42
- .RE
- .IP
- 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.
- .IP
- Example (in snmpd.conf):
- .IP
- pass_persist .1.3.6.1.4.1.2021.255 /path/to/local/pass_persisttest
- .RE
- .SH "EMBEDDED PERL SUPPORT"
- .PP
- 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.
- .PP
- 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.
- .PP
- If compiled in, it defines the following snmpd.conf configuration
- directives:
- .IP "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.
- .IP "perlInitFile FILE"
- Use FILE as the initialization file. This file is normally
- DATADIR/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.
- .IP "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:
- .IP
- perl print "hello world\n";
- .IP
- is the most basic hello world example.
- .IP
- 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:
- .nf
- perl use Data::Dumper;
- perl sub myroutine { print "got called: ",Dumper(@_),"\n"; }
- perl $agent->register('mylink', '.1.3.6.1.8765', \&myroutine);
- .fi
- .IP
- Sourcing an external file:
- .RS
- .nf
- perl 'do /path/to/file.pl';
- .fi
- .RE
- .IP
- 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.
- .SH "DISMAN-EVENT-MIB SUPPORT (READ: SENDING TRAPS ON ERRORS)"
- .PP
- 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.
- .PP
- 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:
- .IP "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:
- .RS
- .IP
- .nf
- agentSecName internal
- rouser internal
- .fi
- .RE
- .IP
- And everything below should work just fine.
- .IP "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:
- .RS
- .IP "-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.
- .IP "-r FREQUENCY"
- Monitors the given expression every FREQUENCY seconds. The default is
- 600 (10 minutes).
- .IP "-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).
- .IP "-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.
- .IP "-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.
- .RE
- .IP
- 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.
- .RS
- .IP
- .nf
- rouser me
- monitor -u me -o sysUpTime.0 -o hrSWRunName "high process memory" hrSWRunPerfMem > 10000
- .fi
- .fi
- .RE
- .IP
- The above line would produce a trap which, when formated by snmptrapd, would
- look like:
- .RS
- .IP
- .nf
- 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"
- .fi
- .RE
- .IP
- This shows my xemacs process using 28Mb of resident memory. Which,
- considering it's xemacs, is not that surprising.
- .IP
- Threshold example:
- .RS
- .nf
- .IP
- monitor -t -r 15 -o prNames -o prErrMessage "process table" prErrorFlag 0 1
- .fi
- .RE
- .IP "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.
- .IP "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:
- .RS
- .IP
- .nf
- 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
- .fi
- .RE
- .IP "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:
- .RS
- .IP
- .nf
- 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
- .fi
- .RE
- .SH "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:
- .IP "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:
- .RS
- .nf
- 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.
- .fi
- .RE
- .IP "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.
- .SH "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.
- .SH "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:
- .IP 1.
- An snmpset of integer(1) to UCD-SNMP-MIB::versionUpdateConfig.0
- (.1.3.6.1.4.1.2021.100.11.0)
- .IP 2.
- A "kill -HUP" signal sent to the snmpd agent process.
- .SH "FILES"
- SYSCONFDIR/snmp/snmpd.conf
- .SH "SEE ALSO"
- snmpconf(1), snmpusm(1), snmp.conf(5), snmp_config(5), snmpd(8), EXAMPLE.conf, read_config(3).
- ." Local Variables:
- ." mode: nroff
- ." End: