.TH SNMPD.CONF 1 "21 Feb 1996"
.ds )H U.C. Davis
.ds ]W VVERSIONINFO
.UC 4
.SH NAME
DATADIR/snmp/snmpd.conf - configuration file for the ucd-snmp SNMP agent.
.SH DESCRIPTION
.B snmpd.conf
is the configuration file which defines how the ucd-smnp SNMP agent
operates.  These files may contain any of the directives found in the
DIRECTIVES section below.  This file is not required for the agent to
operate and report mib entries.
.SH PLEASE READ FIRST
First, make sure you have read the snmp_config(5) manual page that
describes how the ucd-snmp configuration files operate, where they
are located and how they all work together.
.SH EXTENSIBLE-MIB
.PP
The ucd-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 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.
.SS Directives
.IP "proc NAME"
.IP "proc NAME MAX"
.IP "proc NAME MAX MIN"
.IP
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 EXTENSIBLEDOTMIB.PROCMIBNUM.ERRORFLAG and
EXTENSIBLEDOTMIB.PROCMIBNUM.ERRORMSG mib tables (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.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 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.ERRORFLAG and
EXTENSIBLEDOTMIB.SHELLMIBNUM.ERRORMSG mib tables (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 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 "execfix NAME PROG ARGS"
This registers a command that knows how to fix errors with the given
exec or sh NAME.  When EXTENSIBLEDOTMIB.SHELLMIBNUM.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 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.ERRORFLAG mib table will be set to (1) and
a descriptive error message will be returned to queries of
EXTENSIBLEDOTMIB.DISKMIBNUM.ERRORMSG.
.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.ERRORFLAG and
EXTENSIBLEDOTMIB.LOADAVEMIBNUM.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.
.SS "Errors"
.PP
Any errors in obtaining the above information are reported via the
EXTENSIBLEDOTMIB.ERRORMIBNUM.ERRORFLAG flag and the
EXTENSIBLEDOTMIB.ERRORMIBNUM.ERRORMSG text-string description.
.SH ACCESS CONTROL
snmpd supports the View-Based Access Control Model (vacm)
as defined in RFC 2275.
To this end, it recognizes the following keywords in the configuration
file: \fIcom2sec\fR, \fIgroup\fR, \fIaccess\fR, and \fIview\fR.
.IP "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
\fI"default"\fR.
A subnet can be specified as IP/MASK or IP/BITS.
The first source/community combination that matches the incoming packet
is selected.
.IP "group NAME MODEL SECURITY"
This directive defines the mapping from securitymodel/securityname to group.
MODEL is one of \fIany\fR, \fIv1\fR, \fIv2c\fR, or \fIusm\fR.
.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 \fIany\fR, \fIv1\fR, \fIv2c\fR, or \fIusm\fR.
LEVEL is one of \fInoauth\fR, \fIauth\fR, or \fIpriv\fR.
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]"
The defines the named view. TYPE is either \fIincluded\fR or \fIexcluded\fR.
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

#             sec.model  sec.name
group mygroup v1         mynet
group mygroup v2c        mynet
group local   any        local
group public  any        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    0      mib2   none  none
access public  ""      any       noauth    0      system none  none
access local   ""      any       noauth    0      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	any	public
view 	all	.1
access	public	""	any	noauth	all	none	none
.SH SETTING SYSTEM INFORMATION
.IP "syslocation STRING"
.IP "syscontact STRING"
.IP
Sets the system location and the system contact for the agent.  This
information is reported by the 'system' table in the mibII tree.
.IP "authtrapenable NUMBER"
Setting authtrapenable to 1 enables generation of authentication failure
traps. The default value is 2 (disable).
.IP "trapcommunity STRING"
.IP "trapsink HOST [COMMUNITY]"
.IP "trap2sink HOST [COMMUNITY]"
This defines the host to receive traps. The daemon sends a Cold Start
trap when it starts up. If enabled, it also sends traps on
authentication failures.  Multiple \fItrapsink\fR lines may be specified
to specify multiple destinations.
Use \fItrap2sink\fR to send SNMPv2 traps.
If COMMUNITY is not specified, the string from a preceeding \fItrapcommunity\fR
directive will be used.
.SH "PASS-THROUGH CONTROL"
.IP "pass MIBOID EXEC"
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, 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.  A snmp error will be generated
corresponding to the SNMP NO-SUCH-NAME 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
.SH "EXAMPLE"
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 ucd-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 EXTENSIBLEDOTMIB.VERSIONMIBNUM.VERUPDATECONFIG.
.IP 2.
A "kill -HUP" signal sent to the snmpd agent process.
.SH "FILES"
DATADIR/snmp/snmpd.conf
.SH "SEE ALSO"
snmp_config(5), snmpd(1), EXAMPLE.conf, read_config(3).
.\" Local Variables:
.\"  mode: nroff
.\" End:
