Manpages

SNMPD.CONF

NAME

DESCRIPTION

PLEASE READ FIRST

Also, you might consider looking into the snmpconf application (perl script) which can help you build a snmpd.conf file by prompting you for information. You should try it. Really. Go ahead. Right now. Run:

snmpconf -g basic_setup

to get you started.  

EXTENSIBLE-MIB

The ucd-snmp SNMP agent reports much of its information through queries to the 1.3.6.1.4.1.2021 section of the mib tree. Every mib in this section has the following table entries in it.

.1 -- index

This is the table's index numbers for each of the DIRECTIVES listed below.

.2 -- name

The name of the given table entry. This should be unique, but is not required to be.

.100 -- errorFlag

This is a flag returning either the integer value 1 or 0 if an error is detected for this table entry.

.101 -- errorMsg

This is a DISPLAY-STRING describing any error triggering the errorFlag above.

.102 -- errorFix

If this entry is SNMPset 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 config.h file at compile time.

Directives

proc NAME

proc NAME MAX

proc NAME MAX MIN

Checks to see if the NAME'd processes are running on the agent's machine. An error flag (1) and a description message are then passed to the 1.3.6.1.4.1.2021.2.1.100 and 1.3.6.1.4.1.2021.2.1.101 mib columns (respectively) if the NAME'd program is not found in the process table as reported by "/bin/ps -e".

If MAX and MIN are not specified, MAX is assumed to be infinity and MIN is assumed to be 1.

If MAX is specified but MIN is not specified, MIN is assumed to be 0.

procfix NAME PROG ARGS

This registers a command that knows how to fix errors with the given process NAME. When 1.3.6.1.4.1.2021.2.1.102 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 config.h file.

exec NAME PROG ARGS

exec MIBNUM NAME PROG ARGS

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 1.3.6.1.4.1.2021.8.1.100 and 1.3.6.1.4.1.2021.8.1.101 mib columns (respectively). All STDOUT output beyond the first line is silently truncated.

If MIBNUM is specified, it acts as above but returns the exit status to MIBNUM.100.0 and the entire STDOUT output to the table MIBNUM.101 in a mib table. In this case, the MIBNUM.101 mib contains the entire STDOUT output, one mib table entry per line of output (ie, the first line is output as MIBNUM.101.1, the second at MIBNUM.101.2, etc...).

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...).

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 1.3.6.1.4.1.2021.100.VERCLEARCACHE.

execfix NAME PROG ARGS

This registers a command that knows how to fix errors with the given exec or sh NAME. When 1.3.6.1.4.1.2021.8.1.102 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 config.h file.

disk PATH

disk PATH [ MINSPACE | MINPERCENT% ]

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 1.3.6.1.4.1.2021.9.1.100 mib table will be set to (1) and a descriptive error message will be returned to queries of 1.3.6.1.4.1.2021.9.1.101.

load MAX1

load MAX1 MAX5

load MAX1 MAX5 MAX15

Checks the load average of the machine and returns an error flag (1), and an text-string error message to queries of 1.3.6.1.4.1.2021.10.1.100 and 1.3.6.1.4.1.2021.10.1.101 (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.

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.

Errors

Any errors in obtaining the above information are reported via the 1.3.6.1.4.1.2021.101.1.100 flag and the 1.3.6.1.4.1.2021.101.1.101 text-string description.  

AGENTX SUB-AGENTS

master agentx

Note that this support is still experimental, and should not be used on production systems. See README.agentx for details.

SMUX SUB-AGENTS

smuxpeer OID PASS

For gated a sensible entry might be smuxpeer .1.3.6.1.4.1.4.1.3 secret

DYNAMICALLY LOADABLE MODULES

dlmod NAME PATH

ACCESS CONTROL

rocommunity COMMUNITY [SOURCE] [OID]

rwcommunity COMMUNITY [SOURCE] [OID]

These create read-only and read-write communities that can be used to access the agent. They are a quick method of using the following com2sec, group, access, and view 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.

The format of the SOURCE is token is described in the com2sec directive section below. The OID token restricts access for that community to everything below that given OID.

rouser USER [noauth|auth|priv] [OID]

rwuser USER [noauth|auth|priv] [OID]

Creates a SNMPv3 USM user in the VACM access configuration tables. Again, its more efficient (and powerful) to use the combined com2sec, group, access, and view directives instead.

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.

com2sec 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 "default". A subnet can be specified as IP/MASK or IP/BITS. The first source/community combination that matches the incoming packet is selected.

group NAME MODEL SECURITY

This directive defines the mapping from securitymodel/securityname to group. MODEL is one of v1, v2c, or usm.

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 any, v1, v2c, or usm. LEVEL is one of noauth, auth, or priv. PREFX specifies how CONTEXT should be matched against the context of the incoming pdu, either exact or prefix. 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.

view NAME TYPE SUBTREE [MASK]

The defines the named view. TYPE is either included or excluded. MASK is a list of hex octets, separated by '.' or ':'. The MASK defaults to "ff" if not specified.

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:

view cust1 included interfaces.ifTable.ifEntry.ifIndex.1 ff.a0
view cust2 included interfaces.ifTable.ifEntry.ifIndex.2 ff.a0
(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)
VACM Examples:
#       sec.name  source          community
com2sec local     localhost       private
com2sec mynet     10.10.10.0/24   public
com2sec public    default         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 username (MD5|SHA) authpassphrase [DES] [privpassphrase]

This directive should be placed into the "/var/lib/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.

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 command.

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.

agentaddress [(udp|tcp):]port[@address][,...]

Makes the agent list on the specified list of sockets instead of the default port, which is port 161. Multiple ports can be separated by commas. Transports can be specified by prepending the port number with the transport name ("udp" or "tcp") followed by a colon. Finally, to bind to a particular interface, you can specify the address you want it to bind with. For example, specifying agentaddress 161,tcp:161,9161@localhost will make the agent listen on: udp port 161 for any address, tcp port 161 for any address, and udp port 9161 on only the interface associated with the localhost address. Note that the -T flag changes the default transport mapping to use (in the above example, the default transport mapping is udp.

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.

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.

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 [COMMUNITY]

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 [SNMPCMD ARGS] HOST OID [REMOTEOID]

Warning: This functionality is at beta level support.

This token specifies that any incoming requests under OID should be proxied on to HOST instead. 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 man page for details.

Examples:

proxy -v 1 -c public remotehost .1.3.6.1.4.1.2021

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

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. A snmp error will be generated corresponding to the SNMP NO-SUCH-NAME 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.

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

EXAMPLE

RE-READING snmpd.conf and snmpd.local.conf

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

SEE ALSO

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

PROXY SUPPORT

PASS-THROUGH CONTROL

EXAMPLE

RE-READING snmpd.conf and snmpd.local.conf

FILES

SEE ALSO