BSD 4_3_Net_2 development

[unix-history] / usr / src / contrib / isode / snmp / snmpd.8c

.TH SNMPD 8C "14 Sep 1989"
.\" $Header: /f/osi/snmp/RCS/snmpd.8c,v 7.20 91/02/22 09:44:13 mrose Interim $
.\"
.\" Contributed by NYSERNet Inc.  This work was partially supported by the
.\" U.S. Defense Advanced Research Projects Agency and the Rome Air Development
.\" Center of the U.S. Air Force Systems Command under contract number
.\" F30602-88-C-0016.
.\"
.\"
.\" $Log:	snmpd.8c,v $
.\" Revision 7.20  91/02/22  09:44:13  mrose
.\" Interim 6.8
.\" 
.\" Revision 7.19  91/01/11  15:35:08  mrose
.\" sets
.\" 
.\" Revision 7.18  90/10/18  11:34:05  mrose
.\" psi
.\" 
.\" Revision 7.17  90/09/07  11:11:32  mrose
.\" update
.\" 
.\" Revision 7.16  90/09/03  12:57:37  mrose
.\" update
.\" 
.\" Revision 7.15  90/08/29  15:04:12  mrose
.\" doc
.\" 
.\" Revision 7.14  90/06/23  01:33:10  mrose
.\" proxy again
.\" 
.\" Revision 7.13  90/06/21  21:27:03  mrose
.\" proxy
.\" 
.\" Revision 7.12  90/06/20  23:52:55  mrose
.\" again
.\" 
.\" Revision 7.11  90/06/20  21:38:29  mrose
.\" update
.\" 
.\" Revision 7.10  90/06/13  17:58:41  mrose
.\" defaultView
.\" 
.\" Revision 7.9  90/06/12  05:19:02  mrose
.\" again
.\" 
.\" Revision 7.8  90/06/12  02:06:20  mrose
.\" views ...
.\" 
.\" Revision 7.7  90/06/12  02:05:32  mrose
.\" views ...
.\" 
.\" Revision 7.6  90/05/23  18:08:55  mrose
.\" 1158
.\" 
.\" Revision 7.5  90/05/13  17:54:37  mrose
.\" views again
.\" 
.\" Revision 7.4  90/05/13  16:08:10  mrose
.\" again
.\" 
.\" Revision 7.3  90/05/13  15:55:55  mrose
.\" update
.\" 
.\" Revision 7.2  90/02/19  19:17:01  mrose
.\" again
.\" 
.\" Revision 7.1  90/01/11  18:34:30  mrose
.\" real-sync
.\" 
.\" Revision 7.0  89/11/23  22:23:25  mrose
.\" Release 6.0
.\" 
.SH NAME
snmpd \- SNMP agent for BSD UNIX
.SH SYNOPSIS
.in +.5i
.ti -.5i
.B \*(SDsnmpd
\%[-b\ size]
\%[-d]
\%[\-t] \%[\-x] \%[\-z]
\%[-p\  portno]
\%[\-a\ x121address] \%[\-i\ pid]
\%[-r] \%[-s]
.in -.5i
(under /etc/rc.local)
.SH DESCRIPTION
The \fIsnmpd\fR server acts as a management agent,
implementing the Simple Network Management Protocol for Berkeley UNIX systems.
Upon receipt of a message,
it \*(lqauthenticates\*(rq the request,
attempts the operation,
and then returns a response.
.PP
The managed objects manipulated by \fIsnmpd\fR are defined in the file
\fBsnmpd.defs\fR,
kept in the system administrator's area.
These objects conform to the Internet-standard
\fIManagement Information Base\fR (commonly referred to as MIB-I),
which is defined in RFC 1156.
The rules used for naming and describing objects are taken from the
Internet-standard
\fIStructure of Management Information\fR (SMI),
which is defined in RFC 1155.
.PP
Most objects are realized via reading \fB/dev/kmem\fR.
There are some exceptions,
which can be set via a configuration file,
which is read once,
when the daemon starts.
.SH TRANSPORTS
For a UDP\-based network service,
the server listens on port 161 for SNMP messages.
The `\-p' option overrides the default UDP port.
.PP
For an X.25\-based network service,
the server implements the transport class 0 protocol,
decodes the connection request packet,
and execs the appropriate program to enter the protocol and provide the
service.
The `\-a' switch is used to specify the X.121 address of the local host
\(em this overrides the entry in the \fBisotailor\fP file.
In addition,
the `\-i' switch is used to specify the protocol ID to listen on
\(em the default is 03018200.
Note that on most X.25 implementations,
if the local X.121 address is not present in the \fBisotailor\fR file,
then the `-a' switch must be used in order for the server to
receive incoming calls.
.PP
For a TP4\-based transport service,
the server simply listens to any incoming connections for selector
\*(lqsnmp\*(rq.
.PP
By default,
all network services are enabled
(if defined in the configuration).
The `\-t' option specifies TCP\-only operation,
the `\-x' option specifies X.25\-only operation,
and the `\-z' option specifies TP4\-only operation.
.SH SMUX
The agent supports the SNMP Multiplexing (SMUX) protocol.
To disable this,
use the `\-s' option.
.SH CONFIGURATION
The \fBsnmpd.rc\fR file,
which is kept in the system administrator's area,
contains customization commands.
This file must be owned by root unless the `-r' option is given.
At present,
the directives are:
.TP
.B community\fR\0name\0address\0access\0view
defines an SNMP community called `name' with the indicated level of `access'.
The `address' token is either a hostname, an IP-address, or a
network address (using Kille's string syntax).
If present and a value other than 0.0.0.0 is used,
then incoming messages claiming to belong to the named community must
come from this address.
The `access' token,
if present,
is one of \*(lqreadOnly\*(rq, \*(lqreadWrite\*(rq, or \*(lqnone\*(rq,
and defaults to \*(lqreadOnly\*(rq.
The `view' token,
if present,
is an object identifier,
which names the corresponding view of MIB objects that this community
may access;
otherwise,
it defaults to a view containing all variables known to the agent.
.TP
.B view\fR\0name\0subtree\0...
defines a collection of manageable objects
with the given object identifier as its name.
All variables scoped by the `subtree' tokens,
each an object identifier,
given in the directive are placed in the view.
If no subtress are listed,
the view contains all variables known to the agent.
.TP
.B proxy\fR\0name\0domain\0address\0community
defines an SNMP proxy relationship,
in terms of a view called `name'.
Management requests for this view will be encapsulated via the access
method for `domain' and sent to the named address/community.
At present,
only the domain `rfc1157' (SNMP over UDP) is supported,
and the format of the `address' token is identical to that used by the
\fBcommunity\fR directive.
.TP
.B logging\fR\0ava\0...
sets the logging parameters accordingly.
The one or more `ava' tokens are of the form \*(lqattribute=value\*(rq.
The attributes are:
\fIfile\fR,
which is the filename for the log,
this is interpreted relative to the ISODE logging area,
unless the value starts with a slash;
\fIsize\fR,
which takes an integer value describing the maximum file size
(in KBytes) that the log should be allowed to grow;
\fIslevel\fR,
which takes a string value indicating which events should be logged
(one of \fInone\fR, \fIfatal\fR, \fIexceptions\fR, \fInotice\fR, \fItrace\fR,
\fIpdus\fR, \fIdebug\fR, or \fIall\fR);
\fIdlevel\fR,
which says which events should not be logged;
\fIsflags\fR,
which takes a string value indicating logging options should be enabled
(one of \fIclose\fR (to close the log after each entry),
\fIcreate\fR (to create the log if it does not already exist),
\fIzero\fR (to reset the log if the size is exceeded),
and \fItty\fR (to log events to the user's terminal in addition to the file));
and,
\fIdflags\fR,
which says which logging options should be disabled.
.TP
.B trap\fR\0name\0address\0view
defines a trap sink for the SNMP community called `name',
on the indicated address,
which is either a hostname, an IP-address, or a
network address (using Kille's string syntax).
Note that at present,
traps sinks must be reachable via UDP
(the network address must be an IP-address).
By default,
a view is not named for the trap sink.
.TP
.B variable\fR\0name\0value
sets the named variable to the indicated value.
At present,
these variables may be set:
\fIsysDescr\fR,
which takes a string value describing the management agent;
\fIsysObjectID\fR,
which takes an OBJECT IDENTIFIER value containing similar information;
\fIsysContact\fR,
which takes a string value describing the person responsible for the
node;
\fIsysName\fR,
which takes a string value giving an administratively assigned name
for the node;
\fIsysLocation\fR,
which takes a string value describing the location of the node;
and,
\fIsysServices\fR,
which takes an integer describing the services offered by the node.
See RFC 1156 for a more thorough explanation of these objects.
(The last four are defined in MIB-II, RFC 1158,
the follow-on to RFC 1156.)
.TP
.B variable\0snmpEnableAuthTraps\fR\0[ enabled | disabled ]
enables (or disables) the generation of authenticationFailure traps.
.TP
.B variable\0interface\fR\0name\0ava\0...
sets attributes for the named interface.
The `name' token is an interface name as reported by \*(lqnetstat\0-i\*(rq.
The one or more `ava' tokens are of the form \*(lqattribute=value\*(rq.
At present,
only three attributes may be set for each interface:
\fIifType\fR,
which takes an integer value describing the kind of interface;
\fIifSpeed\fR,
which takes an integer value describing the speed of the interface;
and,
\fIifAdminStatus\fR,
which takes an integer value describing the adminstrative state of the
interface.
See RFC 1156 for a more thorough explanation of these objects.
.SH "DEBUG OPERATION"
If \fIsnmpd\fR is started interactively,
or if the `\-d' switch is given,
then debug mode is entered.
In this case,
all logging activity is displayed on the user's terminal.
In addition,
the logging information is more verbose.
.PP
The `-b' switch can be used to specify the maximum message size
supported by the daemon.
(This is useful for testing how management stations recover from
tooBig errors.)
.SH FILES
.nf
.ta \w'\*(LDsnmpd.log  'u
\*(EDsnmpd.defs	MIB definitions
\*(EDsnmpd.rc	configuration file
\*(LDsnmpd.log	log file
/etc/snmpd.pid	daemon PID file
.re
.fi
.SH "NOTE WELL"
The names of the objects in \fBsnmpd.defs\fR are case sensitive.
This was necessary to improve the efficiency of the hashing algorithm
used for object lookup.
.SH "SEE ALSO"
RFCs 1155, 1156, and 1157.
.PP
S.E.\0Kille,
\fIA string encoding of Presentation Address\fR,
Research Note RN/89/14,
Department of Computer Science,
University College London,
(February, 1989).
.SH AUTHOR
Marshall T. Rose,
Performance Systems International
.PP
This work was partially supported by the
U.S. Defense Advanced Research Projects Agency and the Rome Air Development
Center of the U.S. Air Force Systems Command under contract number
F30602-88-C-0016.
.PP
Although this package is distributed with the ISODE,
it is not an OSI program, per se.
Inasmuch as the continued survival of the Internet hinges on all nodes
becoming network manageable,
this package was developed using the ISODE and is being freely
distributed with releases of Berkeley UNIX.
.PP
It must be stressed that this package is not a complete network management
system.
In particular,
whilst \fIsnmpd\fR provides a minimal agent functionality,
there are no Network Operation Center (NOC) tools--\fIsnmpi\fR is a
debugging aid only.