[Pkg-net-snmp-commits] r158 - branches/net-snmp54/debian/patches
Jochen Friedrich
jochen at alioth.debian.org
Fri Apr 13 13:58:51 UTC 2007
Author: jochen
Date: 2007-04-13 13:58:50 +0000 (Fri, 13 Apr 2007)
New Revision: 158
Added:
branches/net-snmp54/debian/patches/39_manpage_snmpd.README
branches/net-snmp54/debian/patches/39_manpage_snmpd.patch
Log:
Fix snmpd.8 manpage from upstream svn
Added: branches/net-snmp54/debian/patches/39_manpage_snmpd.README
===================================================================
--- branches/net-snmp54/debian/patches/39_manpage_snmpd.README 2007-04-13 12:04:31 UTC (rev 157)
+++ branches/net-snmp54/debian/patches/39_manpage_snmpd.README 2007-04-13 13:58:50 UTC (rev 158)
@@ -0,0 +1 @@
+Patch buggy snmpd.8 from upstream
Added: branches/net-snmp54/debian/patches/39_manpage_snmpd.patch
===================================================================
--- branches/net-snmp54/debian/patches/39_manpage_snmpd.patch 2007-04-13 12:04:31 UTC (rev 157)
+++ branches/net-snmp54/debian/patches/39_manpage_snmpd.patch 2007-04-13 13:58:50 UTC (rev 158)
@@ -0,0 +1,1903 @@
+--- trunk/net-snmp/man/snmpd.8.def 2006/08/16 05:58:59 15009
++++ trunk/net-snmp/man/snmpd.8.def 2007/01/10 20:58:45 15748
+@@ -1,107 +1,87 @@
+-.\" /***********************************************************
+-.\" Copyright 1989 by Carnegie Mellon University
+-.\"
+-.\" All Rights Reserved
+-.\"
+-.\" Permission to use, copy, modify, and distribute this software and its
+-.\" documentation for any purpose and without fee is hereby granted,
+-.\" provided that the above copyright notice appear in all copies and that
+-.\" both that copyright notice and this permission notice appear in
+-.\" supporting documentation, and that the name of CMU not be
+-.\" used in advertising or publicity pertaining to distribution of the
+-.\" software without specific, written prior permission.
+-.\"
+-.\" CMU DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
+-.\" ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
+-.\" CMU BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
+-.\" ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+-.\" WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+-.\" ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+-.\" SOFTWARE.
+-.\" ******************************************************************/
+-.TH SNMPTRAPD 8 "15 Jan 2004" VVERSIONINFO "Net-SNMP"
++.TH SNMPD 8 "23 Jun 2005" VVERSIONINFO "Net-SNMP"
+ .UC 4
+ .SH NAME
+-snmptrapd - Receive and log SNMP trap messages.
++snmpd - daemon to respond to SNMP request packets.
+ .SH SYNOPSIS
+-.BR snmptrapd " [OPTIONS] [LISTENING ADDRESSES]"
++.B snmpd
++[OPTIONS] [LISTENING ADDRESSES]
+ .SH DESCRIPTION
+-.B snmptrapd
+-is an SNMP application that receives and logs SNMP TRAP and INFORM
+-messages.
+-.PP
+-Note: the default is to listen on UDP port 162 on all IPv4 interfaces.
+-Since 162 is a privileged port,
+-.B snmptrapd
+-must typically be run as root.
++.B snmpd
++is an SNMP agent which binds to a port and awaits requests from
++SNMP management software. Upon receiving a request, it processes the
++request(s), collects the requested information and/or performs the
++requested operation(s) and returns the information to the sender.
+ .SH OPTIONS
+ .TP 8
+ .B -a
+-Ignore authenticationFailure traps.
++Log the source addresses of incoming requests.
+ .TP
+ .B -A
+ Append to the log file rather than truncating it.
+ .TP
+-.BI "-c" " FILE"
++.B "-c" \fIFILE
+ Read
+ .I FILE
+-as a configuration file.
++as a configuration file
++(or a comma-separated list of configuration files). Note that the loaded
++file will only understand snmpd.conf tokens, unless the configuration type
++is specified in the file as described in the snmp_config man page under
++SWITCHING CONFIGURATION TYPES IN MID-FILE.
+ .TP
+ .B -C
+-Do not read any configuration files except the one optionally specified by the
++Do not read any configuration files except the ones optionally specified by the
++.B -c
++option.
++Note that this behaviour also covers the persistent configuration files.
++This may result in dynamically-assigned values being reset following an
++agent restart, unless the relevant persistent config files are
++explicitly loaded using the
+ .B -c
+ option.
+ .TP
+ .B -d
+ Dump (in hexadecimal) the sent and received SNMP packets.
+ .TP
+-.BI -D " TOKEN[,...]"
++.B -D\fI[TOKEN[,...]]
+ Turn on debugging output for the given
+ .IR "TOKEN" "(s)."
+-Try
++Without any tokens specified, it defaults to printing all the tokens
++(which is equivalent to the keyword "ALL").
++You might want to try
+ .IR ALL
+-for extremely verbose output.
+-.TP
+-.B -e
+-Print event numbers (rising/falling alarm etc.) from the (obsolete) M2M-MIB.
+-.br
+-This functionality is being deprecated and will be removed in due course.
++for extremely verbose output. Note: You can not put a space between
++the -D flag and the listed TOKENs.
+ .TP
+ .B -f
+ Do not fork() from the calling shell.
+ .TP
+-.BI -F " FORMAT"
+-When logging to standard output, use the format in the string
+-.IR FORMAT .
+-See the section
+-.B FORMAT SPECIFICATIONS
+-below for more details.
++.B -g \fIGID
++Change to the numerical group ID
++.I GID
++after opening listening sockets.
+ .TP
+ .B -h, --help
+ Display a brief usage message and then exit.
+ .TP
+ .B -H
+ Display a list of configuration file directives understood by the
+-trap daemon and then exit.
++agent and then exit.
+ .TP
+ .B -I \fI[-]INITLIST
+ Specifies which modules should (or should not) be initialized
+-when snmptrapd starts up. If the comma-separated
++when the agent starts up. If the comma-separated
+ .I INITLIST
+ is preceded
+ with a '-', it is the list of modules that should \fInot\fR be started.
+-.I not
+-want to be started. Otherwise,
+-.I INITLIST
+ Otherwise this is the list of the \fIonly\fR modules that should be started.
+
+-To get a list of compiled modules, run snmptrapd with the arguments
++To get a list of compiled modules, run the agent with the arguments
+ .I "-Dmib_init -H"
+ (assuming debugging support has been compiled in).
+ .TP
+ .B -L[efos]
+ Specify where logging output should be directed (standard error or output,
+-to a file or via syslog). See LOGGING OPTIONS in \fIsnmpcmd(1)\fR for details.
++to a file or via syslog). See LOGGING OPTIONS in snmpcmd(5) for details.
+ .TP
+ .BR -m " \fIMIBLIST"
+ Specifies a colon separated list of MIB modules to load for this
+@@ -113,1596 +93,183 @@
+ This overrides the environment variable MIBDIRS.
+ See \fIsnmpcmd(1)\fR for details.
+ .TP
+-.BR -n
+-Do not attempt to translate source addresses of incoming packets into
+-hostnames.
++.B -n \fINAME
++Set an alternative application name (which will affect the
++configuration files loaded).
++By default this will be \fIsnmpd\fR, regardless of the name
++of the actual binary.
+ .TP
+-.BI -p " FILE"
+-Save the process ID of the trap daemon in
++.B -p \fIFILE
++Save the process ID of the daemon in
+ .IR FILE "."
+-.TP
+-.BI -O " [abeEfnqQsStTuUvxX]"
+-Specifies how MIB objects and other output should be displayed.
+-See the section
+-.B OUTPUT OPTIONS
+-in the
+-.I snmpcmd(1)
+-manual page for details.
+-.TP
+-.BI -t
+-Do not log traps to syslog. This disables logging to syslog. This is
+-useful if you want the snmptrapd application to
+-.B only
+-run traphandle hooks and not to log any traps to any location.
++.TP
++.B -q
++Print simpler output for easier automated parsing.
++.TP
++.B -r
++Do not require root access to run the daemon. Specifically, do not exit
++if files only accessible to root (such as /dev/kmem etc.) cannot be
++opened.
++.TP
++.B -u \fIUID
++Change to the user ID
++.I UID
++(which can be given in numerical or textual form) after opening
++listening sockets.
++.TP
++.B -U
++Instructs the agent to not remove its pid file (see the
++.B -p
++option) on shutdown. Overrides the leave_pidfile token in the
++.I snmpd.conf
++file, see
++.I snmpd.conf(5).
+ .TP
+ .B -v, --version
+-Print version information for the trap daemon and then exit.
++Print version information for the agent and then exit.
++.TP
++.B -V
++Symbolically dump SNMP transactions.
+ .TP
+ .B -x \fIADDRESS
+-Connect to the AgentX master agent on the specified address,
+-rather than the default ''.
+-See \fIsnmpd(8)\fR for details of the format of such addresses.
++Listens for AgentX connections on the specified address
++rather than the default AGENTX_SOCKET.
++The address can either be a Unix domain socket path,
++or the address of a network interface. The format is the same as the
++format of listening addresses described below.
++.TP
++.B -X
++Run as an AgentX subagent rather than as an SNMP master agent.
+ .TP
+ .BI -- "name"="value"
+ Allows to specify any token ("name") supported in the
+-.I snmptrapd.conf
++.I snmpd.conf
+ file and sets its value to "value". Overrides the corresponding token in the
+-.I snmptrapd.conf
++.I snmpd.conf
+ file. See
+-.I snmptrapd.conf(5)
++.I snmpd.conf(5)
+ for the full list of tokens.
+-.SH FORMAT SPECIFICATIONS
+-.PP
+-.B snmptrapd
+-interprets format strings similarly to
+-.IR printf(3) .
+-It understands the following formatting sequences:
+-.RS 4
+-.TP 4
+-.B %%
+-a literal %
+-.TP
+-.B %a
+-the contents of the agent-addr field of the PDU (v1 TRAPs only)
+-.TP
+-.B %A
+-the hostname corresponding to the contents of the agent-addr field of
+-the PDU, if available, otherwise the contents of the agent-addr field
+-of the PDU (v1 TRAPs only).
+-.TP
+-.B %b
+-PDU source address (Note: this is not necessarily an IPv4
+-address)
+-.TP
+-.B %B
+-PDU source hostname if available, otherwise PDU source address (see
+-note above)
+-.TP
+-.B %h
+-current hour on the local system
+-.TP
+-.B %H
+-the hour field from the \fCsysUpTime.0\fR varbind
+-.TP
+-.B %j
+-current minute on the local system
+-.TP
+-.B %J
+-the minute field from the \fCsysUpTime.0\fR varbind
+-.TP
+-.B %k
+-current second on the local system
+-.TP
+-.B %K
+-the seconds field from the \fCsysUpTime.0\fR varbind
+-.TP
+-.B %l
+-current day of month on the local system
+-.TP
+-.B %L
+-the day of month field from the \fCsysUpTime.0\fR varbind
+-.TP
+-.B %m
+-current (numeric) month on the local system
+-.TP
+-.B %M
+-the numeric month field from the \fCsysUpTime.0\fR varbind
+-.TP
+-.B %N
+-enterprise string
+-.TP
+-.B %q
+-trap sub-type (numeric, in decimal)
+-.TP
+-.B %P
+-security information from the PDU (community name for v1/v2c,
+-user and context for v3)
+-.TP
+-.B %t
+-decimal number of seconds since the operating system epoch (as
+-returned by
+-.IR time(2) )
+-.TP
+-.B %T
+-the value of the \fCsysUpTime.0\fR varbind in seconds
+-.TP
+-.B %v
+-list of variable-bindings from the notification payload.
+-These will be separated by a tab,
+-or by a comma and a blank if the alternate form is requested
+-See also %V
+-.TP
+-.B %V
+-specifies the variable-bindings separator. This takes a sequence of
+-characters, up to the next % (to embed a % in the string, use \\%)
+-.TP
+-.B %w
+-trap type (numeric, in decimal)
+-.TP
+-.B %W
+-trap description
+-.TP
+-.B %y
+-current year on the local system
+-.TP
+-.B %Y
+-the year field from the \fCsysUpTime.0\fR varbind
+-.RE
+-.PP
+-In addition to these values, an optional field
+-width and precision may also be specified , just as in
+-.IR printf(3) ,
+-and a flag value. The following flags are supported:
+-.RS 4
+-.TP 4
+-.B -
+-left justify
+-.TP
+-.B 0
+-use leading zeros
+-.TP
+-.B #
+-use alternate form
+-.RE
+-.PP
+-The "use alternate form" flag changes the behavior of various format
+-string sequences:
+-.IP
+-Time information will be displayed based on GMT (rather than the local timezone)
+-.IP
+-The variable-bindings will be a comma-separated list (rather than a tab-separated one)
+-.IP
+-The system uptime will be broken down into a human-meaningful format (rather than being a simple integer)
+-.SS Examples:
+-.PP
+-To get a message like "14:03 TRAP3.1 from humpty.ucd.edu" you
+-could use something like this:
+-.PP
+-.RS
+-.nf
+-snmptrapd -P -F "%02.2h:%02.2j TRAP%w.%q from %A\en"
+-.fi
+-.RE
+-.PP
+-If you want the same thing but in GMT rather than local time, use
+-.PP
+-.RS
+-.nf
+-snmptrapd -P -F "%#02.2h:%#02.2j TRAP%w.%q from %A\en"
+-.fi
+-.RE
+ .SH LISTENING ADDRESSES
+ By default,
+-.B snmptrapd
+-listens for incoming SNMP TRAP and INFORM packets on UDP port 162 on
+-all IPv4 interfaces. However, it is possible to modify this behaviour
+-by specifying one or more listening addresses as arguments to
+-.BR snmptrapd .
+-See the
+-.I snmpd(8)
+-manual page for more information about the format of listening
+-addresses.
+-.SH NOTIFICATION-LOG-MIB SUPPORT
+-As of net-snmp 5.0, the snmptrapd application supports the
+-NOTIFICATION-LOG-MIB. It does this by opening an AgentX subagent
+-connection to the master snmpd agent and registering the notification
+-log tables. As long as the snmpd application is started first, it
+-will attach itself to it and thus you should be able to view the last
+-recorded notifications via the nlmLogTable and nlmLogVariableTable.
+-See the snmptrapd.conf file and the "dontRetainLogs" token for turning
+-off this support. See the NOTIFICATION-LOG-MIB for more details about
+-the MIB itself.
+-.SH EXTENSIBILITY AND CONFIGURATION
+-See the
+-.I snmptrapd.conf(5)
+-manual page.
+-.SH "SEE ALSO"
+-snmpcmd(1), snmpd(8), printf(3), snmptrapd.conf(5), syslog(8), variables(5)
+-.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
+-The Net-SNMP agent uses one or more configuration files
+-to control its operation and the management information
+-provided.
+-These files (\fBsnmpd.conf\fR and \fBsnmpd.local.conf\fR)
+-can be located in one of several locations, as described in the
+-.I snmp_config(5)
+-manual page.
+-.PP
+-The (perl) application
+-.B snmpconf
+-can be used to generate configuration files for the
+-most common agent requirements. See the
+-.I snmpconf(1)
+-manual page for more information, or try running the
+-command:
+-.RS
+-.IP "snmpconf -g basic_setup"
+-.RE
+-.PP
+-There are a large number of directives that can be specified,
+-but these mostly fall into four distinct categories:
+-.IP \(bu
+-those controlling who can access the agent
+-.IP \(bu
+-those configuring the information that is supplied by the agent
+-.IP \(bu
+-those controlling active monitoring of the local system
+-.IP \(bu
+-those concerned with extending the functionality of the agent.
+-.PP
+-Some directives don't fall naturally into any of these four
+-categories, but this covers the majority of the contents of
+-a typical
+-.B snmpd.conf
+-file.
+-A full list of recognised directives can be obtained by running
+-the command:
+-.RS
+-.IP "snmpd -H"
+-.RE
+-.SH AGENT BEHAVIOUR
+-Although most configuration directives are concerned with the MIB
+-information supplied by the agent, there are a handful of directives that
+-control the behaviour of \fIsnmpd\fR considered simply as a daemon
+-providing a network service.
+-.IP "agentaddress [<transport-specifier>:]<transport-address>[,...]"
+-defines a list of listening addresses, on which to receive incoming
+-SNMP requests.
+-See the section
+-.B LISTENING ADDRESSES
+-in the
+-.I snmpd(8)
+-manual page for more information about the format of listening
+-addresses.
+-.IP
+-The default behaviour is to
+-listen on UDP port 161 on all IPv4 interfaces.
+-.IP "agentgroup {GROUP|#GID}"
+-changes to the specified group after opening the listening port(s).
+-This may refer to a group by name (GROUP), or a numeric group ID
+-starting with '#' (#GID).
+-.IP "agentuser {USER|#UID}"
+-changes to the specified user after opening the listening port(s).
+-This may refer to a user by name (USER), or a numeric user ID
+-starting with '#' (#UID).
+-.IP "leave_pidfile yes"
+-instructs the agent to not remove its pid file on shutdown. Equivalent to
+-specifying "-U" on the command line.
+-.SS SNMPv3 Configuration
+-SNMPv3 requires an SNMP agent to define a unique "engine ID"
+-in order to respond to SNMPv3 requests.
+-This ID will normally be determined automatically, using two reasonably
+-non-predictable values - a (pseudo-)random number and the current
+-uptime in seconds. This is the recommended approach. However the
+-capacity exists to define the engineID in other ways:
+-.IP "engineID STRING"
+-specifies that the engineID should be built from the given text STRING.
+-.IP "engineIDType 1|2|3"
+-specifies that the engineID should be built from the IPv4 address (1),
+-IPv6 address (2) or MAC address (3). Note that changing the IP address
+-(or switching the network interface card) may cause problems.
+-.IP "engineIDNic INTERFACE"
+-defines which interface to use when determining the MAC address.
+-If \fIengineIDType 3\fR is not specified, then this directive
+-has no effect.
+-.IP
+-The default is to use eth0.
+-.\"
+-.\" What if this doesn't exist ?
+-.\"
+-.SH ACCESS CONTROL
+ .B snmpd
+-supports the View-Based Access Control Model (VACM) as defined in RFC
+-2575, to control who can retrieve or update information. To this end,
+-it recognizes various directives relating to access control.
+-These fall into four basic groups.
+-.SS SNMPv3 Users
+-.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).
+-.SS Traditional Access Control
+-Most simple access control requirements can be specified using the
+-directives \fIrouser\fR/\fIrwuser\fR (for SNMPv3) or
+-\fIrocommunity\fR/\fIrwcommunity\fR (for SNMPv1 or SNMPv2c).
+-.IP "rouser USER [noauth|auth|priv [OID]]"
+-.IP "rwuser USER [noauth|auth|priv [OID]]"
+-specify an SNMPv3 user that will be allowed read-only (GET and GETNEXT)
+-or read-write (GET, GETNEXT and SET) access respectively.
+-By default, this will provide access to the full OID tree for authenticated
+-(including encrypted) SNMPv3 requests.
+-An alternative minimum security level can be specified using \fInoauth\fR
+-(to allow unauthenticated requests), or \fIpriv\fR (to enforce use of
+-encryption). The OID field restricts access for that
+-user to the subtree rooted at the given OID.
+-.IP "rocommunity COMMUNITY [SOURCE [OID]]"
+-.IP "rwcommunity COMMUNITY [SOURCE [OID]]"
+-specify an SNMPv1 or SNMPv2c community that will be allowed read-only
+-(GET and GETNEXT) or read-write (GET, GETNEXT and SET) access respectively.
+-By default, this will provide access to the full OID tree for such requests,
+-regardless of where they were sent from. The SOURCE token can be used to
+-restrict access to requests from the specified system(s) - see
+-\fIcom2sec\fR for the full details. The OID field restricts access for
+-that community to the subtree rooted at the given OID.
+-.IP "rocommunity6 COMMUNITY [SOURCE [OID]]"
+-.IP "rwcommunity6 COMMUNITY [SOURCE [OID]]"
+-are directives relating to requests received using IPv6
+-(if the agent supports such transport domains).
+-The interpretation of the SOURCE and OID tokens are exactly the same as for
+-the IPv4 versions.
+-.PP
+-In each case, only one directive should be specified for a given SNMPv3 user,
+-or community string.
+-It is \fBnot\fR appropriate to specify both \fIrouser\fR
+-and \fIrwuser\fR directives referring to the same SNMPv3 user (or equivalent
+-community settings). The \fIrwuser\fR directive provides all the access
+-of \fIrouser\fR (as well as allowing SET support).
+-The same holds true for the community-based directives.
+-.PP
+-More complex access requirements (such as access to two
+-or more distinct OID subtrees, or different views for GET and SET requests)
+-should use one of the other access control mechanisms.
+-Note that if several distinct communities or SNMPv3 users need to be granted
+-the same level of access, it would also be more efficient to use the main VACM
+-configuration directives.
+-.SS VACM Configuration
+-The full flexibility of the VACM is available using four configuration
+-directives - \fIcom2sec\fR, \fIgroup\fR, \fIview\fR and \fIaccess\fR.
+-These provide direct configuration of the underlying VACM tables.
+-.IP "com2sec [-Cn CONTEXT] SECNAME SOURCE COMMUNITY"
+-.IP "com2sec6 [-Cn CONTEXT] SECNAME SOURCE COMMUNITY"
+-map an SNMPv1 or SNMPv2c community string to a security name - either from
+-a particular range of source addresses, or globally (\fI"default"\fR).
+-A restricted source can either be a specific hostname (or address), or
+-a subnet - represented as IP/MASK (e.g. 10.10.10.0/255.255.255.0), or
+-IP/BITS (e.g. 10.10.10.0/24), or the IPv6 equivalents.
+-.IP
+-The same community string can be specified in several separate directives
+-(presumably with different source tokens), and the first source/community
+-combination that matches the incoming request will be selected.
+-Various source/community combinations can also map to the same security name.
+-.IP
+-If a CONTEXT is specified (using \fI-Cn\fR), the community string will be
+-mapped to a security name in the named SNMPv3 context. Otherwise the
+-default context ("") will be used.
+-.IP "com2secunix [-Cn CONTEXT] SECNAME SOCKPATH COMMUNITY"
+-is the Unix domain sockets version of \fIcom2sec\fR.
+-.IP "group GROUP {v1|v2c|usm} SECNAME"
+-maps a security name (in the specified security model) into
+-a named group. Several \fIgroup\fR directives can specify the
+-same group name, allowing a single access setting to apply to several
+-users and/or community strings.
+-.IP
+-Note that groups must be set up for the two community-based models separately -
+-a single \fIcom2sec\fR (or equivalent) directive will typically be
+-accompanied by \fBtwo\fR \fIgroup\fR directives.
+-.IP "view VNAME TYPE OID [MASK]"
+-defines a named "view" - a subset of the overall OID tree. This is most
+-commonly a single subtree, but several \fIview\fR directives can be given
+-with the same view name, to build up a more complex collection of OIDs.
+-TYPE is either \fIincluded\fR or \fIexcluded\fR, which can again define
+-a more complex view (e.g by excluding certain sensitive objects
+-from an otherwise accessible subtree).
+-.IP
+-MASK is a list of hex octets (separated by '.' or ':') with the set bits
+-indicating which subidentifiers in the view OID to match against. This
+-can be used to define a view covering a particular row (or rows) in a
+-table. If not specified, this defaults to matching the OID exactly
+-(all bits set), thus defining a simple OID subtree.
+-.IP "access GROUP CONTEXT {any|v1|v2c|usm} LEVEL PREFX READ WRITE NOTIFY"
+-maps from a group of users/communities (with a particular security model
+-and minimum security level, and in a specific context) to one of three views,
+-depending on the request being processed.
+-.IP
+-LEVEL is one of \fInoauth\fR, \fIauth\fR, or \fIpriv\fR.
+-PREFX specifies how CONTEXT should be matched against the context of
+-the incoming request, either \fIexact\fR or \fIprefix\fR.
+-READ, WRITE and NOTIFY specifies the view to be used for GET*, SET
+-and TRAP/INFORM requests (althought the NOTIFY view is not currently used).
+-For v1 or v2c access, LEVEL will need to be \fInoauth\fR.
+-.SS Typed-View Configuration
+-The final group of directives extend the VACM approach into a more flexible
+-mechanism, which can be applied to other access control requirements. Rather than
+-the fixed three views of the standard VACM mechanism, this can be used to
+-configure various different view types. As far as the main SNMP agent is
+-concerned, the two main view types are \fIread\fR and \fIwrite\fR,
+-corresponding to the READ and WRITE views of the main \fIaccess\fR directive.
+-See the 'snmptrapd.conf(5)' man page for discussion of other view types.
+-.IP "authcommunity TYPES COMMUNITY [SOURCE [OID | -V VIEW]]"
+-is an alternative to the \fIrocommunity\fR/\fIrwcommunity\fR directives.
+-TYPES will usually be \fIread\fR or \fIread,write\fR respectively.
+-The view specification can either be an OID subtree (as before),
+-or a named view (defined using the
+-\fIview\fR directive) for greater flexibility. If this is omitted,
+-then access will be allowed to the full OID tree.
+-.IP "authuser TYPES [-s MODEL] USER [LEVEL [OID | -V VIEW]]"
+-is an alternative to the \fIrouser\fR/\fIrwuser\fR directives.
+-The fields TYPES, OID and VIEW have the same meaning as for
+-\fIauthcommunity\fR.
+-.IP "authgroup TYPES [-s MODEL] GROUP [LEVEL [OID | -V VIEW]]"
+-is a companion to the \fIauthuser\fR directive, specifying access
+-for a particular group (defined using the \fIgroup\fR directive as usual).
+-Both \fIauthuser\fR and \fIauthgroup\fR default to authenticated requests -
+-LEVEL can also be specified as \fInoauth\fR or \fIpriv\fR to allow
+-unauthenticated requests, or require encryption respectively.
+-Both \fIauthuser\fR and \fIauthgroup\fR directives also default to configuring
+-access for SNMPv3/USM requests - use the '-s' flag to specify an alternative
+-security model (using the same values as for \fIaccess\fR above).
+-.IP "authaccess TYPES [-s MODEL] GROUP VIEW [LEVEL [CONTEXT]]"
+-also configures the access for a particular group,
+-specifying the name and type of view to apply. The MODEL and LEVEL fields
+-are interpreted in the same way as for \fIauthgroup\fR.
+-If CONTEXT is specified, access is configured within this SNMPv3 context
+-(or contexts with this prefix if the CONTEXT field ends with '*').
+-Otherwise the default context ("") is used.
+-.IP "setaccess GROUP CONTEXT MODEL LEVEL PREFIX VIEW TYPES"
+-is a direct equivalent to the original \fIaccess\fR directive, typically
+-listing the view types as \fIread\fR or \fIread,write\fR as appropriate.
+-(or see 'snmptrapd.conf(5)' for other possibilities).
+-All other fields have the same interpretation as with \fIaccess\fR.
+-.SH SYSTEM INFORMATION
+-Most of the information reported by the Net-SNMP agent is retrieved
+-from the underlying system, or dynamically configured via SNMP SET requests
+-(and retained from one run of the agent to the next).
+-However, certain MIB objects can be configured or controlled via
+-the \fIsnmpd.conf(5)\fR file.
+-.SS System Group
+-Most of the scalar objects in the 'system' group can be configured
+-in this way:
+-.IP "sysLocation STRING"
+-.IP "sysContact STRING"
+-.IP "sysName STRING"
+-set the system location, system contact or system name
+-(\fCsysLocation.0\fR, \fCsysContact.0\fR and \fCsysName.0\fR) for the agent respectively.
+-Ordinarily these objects are writeable via suitably authorized SNMP SET
+-requests. However, specifying one of these directives makes the
+-corresponding object read-only, and attempts to SET it will result in
+-a \fInotWritable\fR error response.
+-.IP "sysServices NUMBER"
+-sets the value of the \fCsysServices.0\fR object.
+-For a host system, a good value is 72 (application + end-to-end layers).
+-If this directive is not specified, then no value will be reported
+-for the \fCsysServices.0\fR object.
+-.IP "sysDescr STRING"
+-.IP "sysObjectID OID"
+-sets the system description or object ID for the agent.
+-Although these MIB objects are not SNMP-writable, these directives can be
+-used by a network administrator to configure suitable values for them.
+-.SS Interfaces Group
+-.IP "interface NAME TYPE SPEED"
+-can be used to provide appropriate type and speed settings for
+-interfaces where the agent fails to determine this information correctly.
+-TYPE is a type value as given in the IANAifType-MIB,
+-and can be specified numerically or by name (assuming this MIB is loaded).
+-.SS Host Resources Group
+-This requires that the agent was built with support for the
+-\fIhost\fR module (which is now included as part of the default build
+-configuration on the major supported platforms).
+-.\"
+-.\" XXX - .IP "scandisk STRING"
+-.\"
+-.IP "ignoreDisk STRING"
+-controls which disk devices are scanned as part of populating the
+-\fChrDiskStorageTable\fR (and \fChrDeviceTable\fR).
+-The HostRes implementation code includes a list of disk device patterns
+-appropriate for the current operating system, some of which may cause
+-the agent to block when trying to open the corresponding disk devices.
+-This might lead to a timeout when walking these tables, possibly
+-resulting in inconsistent behaviour. This directive can be used
+-to specify particular devices (either individually or wildcarded)
+-that should not be checked.
+-.RS
+-.IP "Note:"
+-Please consult the source (\fIhost/hr_disk.c\fR) and check for the
+-\fIAdd_HR_Disk_entry\fR calls relevant for a particular O/S
+-to determine the list of devices that will be scanned.
+-.RE
+-.IP
+-The pattern can include one or more wildcard expressions.
+-See \fIsnmpd.examples(5)\fR for illustration of the wildcard syntax.
+-.IP "storageUseNFS [1|2]"
+-controls how NFS and NFS-like file systems should be reported
+-in the hrStorageTable.
+-as 'Network Disks' (1) or 'Fixed Disks' (2)
+-Historically, the Net-SNMP agent has reported such file systems
+-as 'Fixed Disks', and this is still the default behaviour.
+-Setting this directive to '1' reports such file systems as
+-'Network Disks', as required by the Host Resources MIB.
+-.SS Process Monitoring
+-The \fChrSWRun\fR group of the Host Resources MIB provides
+-information about individual processes running on the local system.
+-The \fCprTable\fR of the UCD-SNMP-MIB complements this by reporting
+-on selected services (which may involve multiple processes).
+-This requires that the agent was built with support for the
+-\fIucd-snmp/proc\fR module (which is included as part of the
+-default build configuration).
+-.IP "proc NAME [MAX [MIN]]"
+-monitors the number of processes called NAME (as reported by PSCMD)
+-running on the local system.
+-.IP
+-If the number of NAMEd processes is less than MIN or greater than MAX,
+-then the corresponding \fCprErrorFlag\fR instance will be
+-set to 1, and a suitable description message reported via the
+-\fCprErrMessage\fR instance.
+-.RS
+-.IP "Note:"
+-This situation will \fBnot\fR automatically trigger a trap to report
+-the problem - see the DisMan Event MIB section later.
+-.RE
+-.IP
+-If neither MAX nor MIN are specified (or are both 0), they will
+-default to \fBinfinity\fR and 1 respectively ("at least one").
+-If only MAX is specified, MIN will default to 0 ("no more than MAX").
+-.IP "procfix NAME PROG ARGS"
+-registers a command that can be run to fix errors with the given
+-process NAME. This will be invoked when the corresponding
+-\fCprErrFix\fR instance is set to 1.
+-.RS
+-.IP "Note:"
+-This command will \fBnot\fR be invoked automatically.
+-.\" XXX - but see the DisMan Event MIB section later ???
+-.RE
+-.IP
+-The \fIprocfix\fR directive must be specified \fBafter\fR the matching
+-\fIproc\fR directive, and cannot be used on its own.
+-.PP
+-If no \fIproc\fR directives are defined, then walking the
+-\fCprTable\fR will fail (\fInoSuchObject\fI).
+-.SS Disk Usage Monitoring
+-This requires that the agent was built with support for the
+-\fIucd-snmp/disk\fR module (which is included as part of the
+-default build configuration).
+-.IP "disk PATH [ MINSPACE | MINPERCENT% ]"
+-monitors the disk mounted at PATH for available disk space.
+-.IP
+-The minimum threshold can either be specified in Kb (MINSPACE) or
+-as a percentage of the total disk (MINPERCENT% with a '%' character),
+-defaulting to 100Kb if neither are specified.
+-If the free disk space falls below this threshold,
+-then the corresponding \fCdskErrorFlag\fR instance will be
+-set to 1, and a suitable description message reported via the
+-\fCdskErrorMsg\fR instance.
+-.RS
+-.IP "Note:"
+-This situation will \fBnot\fR automatically trigger a trap to report
+-the problem - see the DisMan Event MIB section later.
+-.RE
+-.IP "includeAllDisks MINPERCENT%"
+-configures monitoring of all disks found on the system,
+-using the specified (percentage) threshold.
+-The threshold for individual disks can be adjusted using suitable
+-\fIdisk\fR directives (which can come either before or after the
+-\fIincludeAllDisks\fR directive).
+-.RS
+-.IP "Note:"
+-Whether \fIdisk\fR directives appears before or after \fIincludeAllDisks\fR
+-may affect the indexing of the \fCdskTable\fR.
+-.RE
+-.IP
+-Only one \fIincludeAllDisks\fR directive should be specified - any
+-subsequent copies will be ignored.
+-.IP
+-The list of mounted disks will be determined when the agent starts 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 the root partition "/"
+-(which is assumed to exist on any UNIX based system) will be monitored.
+-Disks mounted after the agent has started will not be monitored.
+-.\"
+-.\" XXX - unless the config is re-read ??
+-.\"
+-.PP
+-If neither any \fIdisk\fR directives or \fIincludeAllDisks\fR are defined,
+-then walking the \fCdskTable\fR will fail (\fInoSuchObject\fI).
+-.SS System Load Monitoring
+-This requires that the agent was built with support for either the
+-\fIucd-snmp/loadave\fR module or the \fIucd-snmp/memory\fR module
+-respectively (both of which are included as part of the
+-default build configuration).
+-.IP "load MAX1 [MAX5 [MAX15]]"
+-monitors the load average of the local system, specifying
+-thresholds for the 1-minute, 5-minute and 15-minute averages.
+-If any of these loads exceed the associated maximum value,
+-then the corresponding \fClaErrorFlag\fR instance will be
+-set to 1, and a suitable description message reported via the
+-\fClaErrMessage\fR instance.
+-.RS
+-.IP "Note:"
+-This situation will \fBnot\fR automatically trigger a trap to report
+-the problem - see the DisMan Event MIB section later.
+-.RE
+-.IP
+-If the MAX15 threshold is omitted, it will default to the MAX5 value.
+-If both MAX5 and MAX15 are omitted, they will default to the MAX1 value.
+-If this directive is not specified, all three thresholds will
+-default to a value of DEFMAXLOADAVE.
+-.PP
+-Unlike the \fIproc\fR and \fIdisk\fR directives, walking the
+-walking the \fClaTable\fR will succeed (assuming the
+-\fIucd-snmp/loadave\fR module was configured into the agent),
+-even if the \fIload\fR directive is not present.
+-.IP "swap MIN "
+-monitors the amount of swap space available on the local system.
+-If this falls below the specified threshold (MIN Kb),
+-then the \fImemErrorSwap\fR object will be set to 1,
+-and a suitable description message reported via \fImemSwapErrorMsg\fR.
+-.RS
+-.IP "Note:"
+-This situation will \fBnot\fR automatically trigger a trap to report
+-the problem - see the DisMan Event MIB section later.
+-.RE
+-If this directive is not specified, the default threshold is 16 Mb.
+-.SS Log File Monitoring
+-This requires that the agent was built with support for either the
+-\fIucd-snmp/file\fR or \fIucd-snmp/logmatch\fR modules respectively
+-(both of which are included as part of the
+-default build configuration).
+-.IP "file FILE [MAXSIZE]"
+-monitors the size of the specified file (in Kb).
+-If MAXSIZE is specified, and the size of the file exceeds
+-this threshold, then the corresponding \fCfileErrorFlag\fR
+-instance will be set to 1, and a suitable description message reported
+-via the \fCfileErrorMsg\fR instance.
+-.RS
+-.IP "Note:"
+-This situation will \fBnot\fR automatically trigger a trap to report
+-the problem - see the DisMan Event MIB section later.
+-.RE
+-.IP
+-A maximum of 20 files can be monitored.
+-.PP
+-If no \fIfile\fR directives are defined, then walking the
+-\fCfileTable\fR will fail (\fInoSuchObject\fR).
+-.IP "logmatch NAME PATH CYCLETIME REGEX"
+-monitors the specified file for occurances of the specified
+-pattern REGEX.
+-.\"
+-.\" XXX - Need more details here!
+-.\"
+-.IP
+-A maximum of 50 files can be monitored.
+-.PP
+-If no \fIlogmatch\fR directives are defined, then walking the
+-\fClogMatchTable\fR will fail (\fInoSuchObject\fI).
+-.SH "ACTIVE MONITORING"
+-The usual behaviour of an SNMP agent is to wait for incoming SNMP requests
+-and respond to them - if no requests are received, an agent will typically
+-not initiate any actions. This section describes various directives that
+-can configure \fIsnmpd\fR to take a more active role.
+-.SS "Notification Handling"
+-.IP "trapcommunity STRING"
+-defines the default community string to be used when sending traps.
+-Note that this directive must be used prior to any community-based
+-trap destination directives that need to use it.
+-.IP "trapsink HOST [COMMUNITY [PORT]]"
+-.IP "trap2sink HOST [COMMUNITY [PORT]]"
+-.IP "informsink HOST [COMMUNITY [PORT]]"
+-define the address of a notification receiver that should be sent
+-SNMPv1 TRAPs, SNMPv2c TRAP2s, or SNMPv2 INFORM notifications respectively.
+-See the section
+-.B LISTENING ADDRESSES
+-in the
+-.I snmpd(8)
+-manual page for more information about the format of listening
+-addresses.
+-If COMMUNITY is not specified, the most recent \fItrapcommunity\fR
+-string will be used.
++listens for incoming SNMP requests on UDP port 161 on all IPv4 interfaces.
++However, it is possible to modify this behaviour by specifying one or more
++listening addresses as arguments to \fBsnmpd\fR.
++A listening address takes the form:
+ .IP
+-If the transport address does not include an explicit
+-port specification, then PORT will be used.
+-If this is not specified, the well known SNMP trap
+-port (162) will be used.
+-.RS
+-.IP Note:
+-This mechanism is being deprecated, and the listening port
+-should be specified via the transport specification HOST instead.
+-.RE
+-.IP
+-If several sink directives are specified, multiple
+-copies of each notification (in the appropriate formats)
+-will be generated.
+-.RS
+-.IP Note:
+-It is \fBnot\fR normally appropriate to list two (or all three)
+-sink directives with the same destination.
+-.RE
+-.IP "trapsess [SNMPCMD_ARGS] HOST"
+-provides a more generic mechanism for defining notification destinations.
+-.I "SNMPCMD_ARGS"
+-should be the command-line options required for an equivalent
+-\fIsnmptrap\fR (or \fIsnmpinform\fR) command to send the desired notification.
+-The option \fI-Ci\fR can be used (with \fI-v2c\fR or \fI-v3\fR) to generate
+-an INFORM notification rather than an unacknowledged TRAP.
+-.IP
+-This is the appropriate directive for defining SNMPv3 trap receivers.
+-See
+-http://www.net-snmp.org/tutorial/tutorial-5/commands/snmptrap-v3.html
+-for more information about SNMPv3 notification behaviour.
+-.IP "authtrapenable {1|2}"
+-determines whether to generate authentication failure traps
+-(\fIenabled(1)\fR) or not (\fIdisabled(2)\fR - the default).
+-Ordinarily the corresponding MIB
+-object (\fCsnmpEnableAuthenTraps.0\fR) is read-write, but specifying
+-this directive makes this object read-only, and attempts to set the
+-value via SET requests will result in a \fInotWritable\fR error response.
+-.SS "DisMan Event MIB"
+-The previous directives can be used to configure where traps should
+-be sent, but are not concerned with \fIwhen\fR to send such traps
+-(or what traps should be generated). This is the domain of the
+-Event MIB - developed by the Distributed Management (DisMan)
+-working group of the IETF.
+-.PP
+-This requires that the agent was built with support for the
+-\fIdisman/event\fR module (which is now included as part of the
+-default build configuration for the most recent distribution).
+-.RS
+-.IP "Note:"
+-The behaviour of the latest implementation differs in some minor
+-respects from the previous code - nothing too significant, but
+-existing scripts may possibly need some minor adjustments.
+-.RE
+-.IP "iquerySecName NAME"
+-.IP "agentSecName NAME"
+-specifies the default SNMPv3 username, to be used when making internal
+-queries to retrieve any necessary information (either for evaluating
+-the monitored expression, or building a notification payload).
+-.IP
+-Note that this user must also be explicitly created (\fIcreateUser\fR)
+-and given appropriate access rights (e.g. \fIrouser\fR). This
+-directive is purely concerned with defining \fIwhich\fR user should
+-be used - not with actually setting this user up.
+-.\"
+-.\" XXX - Should it create the user as well?
+-.\"
+-.\" .IP "iqueryVersion "
+-.\" .IP "iquerySecLevel "
+-.\"
+-.IP "monitor [OPTIONS] NAME EXPRESSION"
+-defines a MIB object to monitor.
+-If the EXPRESSION condition holds (see below), then this will trigger
+-the corresponding event, and either send a notification or apply
+-a SET assignment (or both).
+-Note that the event will only be triggered once, when the expression
+-first matches. This monitor entry will not fire again until the
+-monitored condition first becomes false, and then matches again.
+-NAME is an administrative name for this expression, and is used for
+-indexing the \fCmteTriggerTable\fR (and related tables).
+-.IP "\fIEXPRESSION\fR"
+-There are three types of monitor expression supported by the Event MIB -
+-existence, boolean and threshold tests.
+-.RS
+-.IP "OID | !OID | !=OID"
+-defines an \fIexistence(0)\fR monitor test.
+-A bare OID specifies a \fIpresent(0)\fR test, which will fire when
+-(an instance of) the monitored OID is created.
+-An expression of the form \fI!OID\fR specifies an \fIabsent(1)\fR test,
+-which will fire when the monitored OID is delected.
+-An expression of the form \fI!=OID\fR specifies a \fIchanged(2)\fR test,
+-which will fire whenever the monitored value(s) change.
+-.IP "OID OP VALUE"
+-defines a \fIboolean(1)\fR monitor test.
+-OP should be one of the defined
+-comparison operators (!=, ==, <, <=, >, >=) and VALUE should be an
+-integer value to compare against.
+-.IP "OID MIN MAX [DMIN DMAX]"
+-defines a \fIthreshold(2)\fR monitor test.
+-MIN and MAX are integer values, specifying lower and upper thresholds.
+-If the value of the monitored OID falls below the lower threshold (MIN)
+-or rises above the upper threshold (MAX), then the monitor entry will
+-trigger the corresponding event.
+-.IP
+-Note that the rising threshold event will only be re-armed when
+-the monitored value falls below the \fBlower\fR threshold (MIN).
+-Similarly, the falling threshold event will be re-armed by
+-the upper threshold (MAX).
+-.IP
+-The optional parameters DMIN and DMAX configure a pair of
+-similar threshold tests, but working with the delta
+-differences between successive sample values.
+-.RE
+-.IP "\fIOPTIONS\fR"
+-There are various options to control the behaviour of the monitored
+-expression. These include:
+-.RS
+-.IP "-D"
+-indicates that the expression should be evaluated using delta differences
+-between sample values (rather than the values themselves).
+-.IP "-d OID"
+-.IP "-di OID"
+-specifies a discontinuity marker for validating delta differences.
+-A \fI-di\fR object instance will be used exactly as given.
+-A \fI-d\fR object will have the instance subidentifiers from the
+-corresponding (wildcarded) expression object appended.
+-If the \fI-I\fR flag is specified, then there is no difference
+-between these two options.
+-.IP
+-This option also implies \fI-D\fR.
+-.IP "-e EVENT"
+-specifies the event to be invoked when this monitor entry is triggered.
+-If this option is not given, the monitor entry will generate one
+-of the standard notifications defined in the DISMAN-EVENT-MIB.
+-.IP "-I"
+-indicates that the monitored expression should be applied to the
+-specified OID as a single instance. By default, the OID will
+-be treated as a wildcarded object, and the monitor expanded
+-to cover all matching instances.
+-.IP "-i OID"
+-.IP "-o OID"
+-define additional varbinds to be added to the notification payload
+-when this monitor trigger fires.
+-For a wildcarded expression, the suffix of the matched instance
+-will be added to any OIDs specified using \fI-o\fR, while OIDs
+-specified using \fI-i\fR will be treated as exact instances.
+-If the \fI-I\fR flag is specified, then there is no difference
+-between these two options.
+-.IP
+-See \fIstrictDisman\fR for details of the ordering of notification payloads.
+-.IP "-r FREQUENCY"
+-monitors the given expression every FREQUENCY seconds.
+-By default, the expression will be evaluated every 600s (10 minutes).
+-.IP "-S"
+-indicates that the monitor expression should \fInot\fR be evaluated
+-when the agent first starts up. The first evaluation will be done
+-once the first repeat interval has expired.
+-.IP "-s"
+-indicates that the monitor expression \fIshould\fR be evaluated when the
+-agent first starts up. This is the default behaviour.
+-.RS
+-.IP "Note:"
+-Notifications triggered by this initial evaluation will be sent
+-\fIbefore\fR the \fCcoldStart\fR trap.
+-.RE
+-.IP "-u SECNAME"
+-specifies a security name to use for scanning the local host,
+-instead of the default \fIiquerySecName\fR.
+-Once again, this user must be explicitly created and given
+-suitable access rights.
+-.RE
+-.IP "notificationEvent ENAME NOTIFICATION [-n] [-i OID | -o OID ]*"
+-defines a notification event named ENAME.
+-This can be triggered from a given \fImonitor\fR entry by specifying
+-the option \fI-e ENAME\fR (see above).
+-NOTIFICATION should be the OID of the NOTIFICATION-TYPE definition
+-for the notification to be generated.
+-.IP
+-If the \fI-n\fR option is given, the notification payload will
+-include the standard varbinds as specified in the OBJECTS clause
+-of the notification MIB definition.
+-This option must come \fBafter\fR the NOTIFICATION OID
+-(and the relevant MIB file must be available and loaded by the agent).
+-Otherwise, these varbinds must
+-be listed explicitly (either here or in the corresponding
+-\fImonitor\fR directive).
+-.IP
+-The \fI-i OID\fR and \fI-o OID\fR options specify additional
+-varbinds to be appended to the notification payload, after the
+-standard list.
+-If the monitor entry that triggered this event involved a
+-wildcarded expression, the suffix of the matched instance
+-will be added to any OIDs specified using \fI-o\fR, while OIDs
+-specified using \fI-i\fR will be treated as exact instances.
+-If the \fI-I\fR flag was specified to the \fImonitor\fR directive,
+-then there is no difference between these two options.
+-.IP "setEvent ENAME [-I] OID = VALUE "
+-defines a set event named ENAME, assigning the (integer) VALUE
+-to the specified OID.
+-This can be triggered from a given \fImonitor\fR entry by specifying
+-the option \fI-e ENAME\fR (see above).
+-.IP
+-If the monitor entry that triggered this event involved a
+-wildcarded expression, the suffix of the matched instance
+-will normally be added to the OID.
+-If the \fI-I\fR flag was specified to either of the
+-\fImonitor\fR or \fIsetEvent\fR directives, the
+-specified OID will be regarded as an exact single instance.
+-.IP "strictDisman yes"
+-The definition of SNMP notifications states that the
+-varbinds defined in the OBJECT clause should come first
+-(in the order specified), followed by any "extra" varbinds
+-that the notification generator feels might be useful.
+-The most natural approach would be to associate these
+-mandatory varbinds with the \fInotificationEvent\fR entry,
+-and append any varbinds associated with the monitor entry
+-that triggered the notification to the end of this list.
+-This is the default behaviour of the Net-SNMP Event MIB implementation.
+-.IP
+-Unfortunately, the DisMan Event MIB specifications actually
+-state that the trigger-related varbinds should come \fBfirst\fR,
+-followed by the event-related ones. This directive can be used to
+-restore this strictly-correct (but inappropriate) behaviour.
+-.RS
+-.IP "Note:"
+-Strict DisMan ordering may result in generating invalid notifications
+-payload lists if the \fInotificationEvent -n\fR flag is used together
+-with \fImonitor -o\fR (or \fI-i\fR) varbind options.
+-.RE
+-.IP
+-If no \fImonitor\fR entries specify payload varbinds,
+-then the setting of this directive is irrelevant.
+-.IP "linkUpDownNotifications yes"
+-will configure the Event MIB tables to monitor the \fCifTable\fR
+-for network interfaces being taken up or down, and triggering
+-a \fIlinkUp\fR or \fIlinkDown\fR notification as appropriate.
+-.IP
+-This is exactly equivalent to the configuration:
+-.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"
+-will configure the Event MIB tables to monitor the various
+-\fCUCD-SNMP-MIB\fR tables for problems (as indicated by
+-the appropriate \fCxxErrFlag\fR column objects).
+-.IP
+-This is exactly equivalent to the configuration:
+-.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
+-.PP
+-In both these latter cases, the snmpd.conf must also contain a
+-\fIiquerySecName\fR directive, together with a corresponding
+-\fIcreateUser\fR entry and suitable access control configuration.
+-.SS "DisMan Schedule MIB"
+-The DisMan working group also produced a mechanism for scheduling
+-particular actions (a specified SET assignment) at given times.
+-This requires that the agent was built with support for the
+-\fIdisman/schedule\fR module (which is included as part of the
+-default build configuration for the most recent distribution).
+-.PP
+-There are three ways of specifying the scheduled action:
+-.IP "repeat FREQUENCY OID = VALUE"
+-configures a SET assignment of the (integer) VALUE to the MIB instance
+-OID, to be run every FREQUENCY seconds.
+-.IP "cron MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE"
+-configures a SET assignment of the (integer) VALUE to the MIB instance
+-OID, to be run at the times specified by the fields MINUTE to WEEKDAY.
+-These follow the same pattern as the equivalent \fIcrontab(5)\fR fields.
+-.RS
+-.IP "Note:"
+-These fields should be specified as a (comma-separated) list of numeric
+-values. Named values for the MONTH and WEEKDAY fields are not supported,
+-and neither are value ranges. A wildcard match can be specified as '*'.
+-.RE
+-.IP
+-The DAY field can also accept negative values, to indicate days counting
+-backwards from the end of the month.
+-.IP "at MINUTE HOUR DAY MONTH WEEKDAY OID = VALUE"
+-configures a one-shot SET assignment, to be run at the first matching
+-time as specified by the fields MINUTE to WEEKDAY. The interpretation
+-of these fields is exactly the same as for the \fIcron\fR directive.
+-.SH "EXTENDING AGENT FUNCTIONALITY"
+-One of the first distinguishing features of the original UCD suite was
+-the ability to extend the functionality of the agent - not just by
+-recompiling with code for new MIB modules, but also by configuring the running agent to
+-report additional information. There are a number of techniques to
+-support this, including:
+-.IP \(bu
+-running external commands (\fIexec\fR, \fIextend\fR, \fIpass\fR)
+-.IP \(bu
+-loading new code dynamically (embedded perl, \fIdlmod\fR)
+-.IP \(bu
+-communicating with other agents (\fIproxy\fR, SMUX, AgentX)
+-.SS "Arbitrary Extension Commands"
+-The earliest extension mechanism was the ability to run arbitrary
+-commands or shell scripts. Such commands do not need to be aware of
+-SNMP operations, or conform to any particular behaviour - the MIB
+-structures are designed to accommodate any form of command output.
+-Use of this mechanism requires that the agent was built with support for the
+-\fIucd-snmp/extensible\fR and/or \fIagent/extend\fR modules (which
+-are both included as part of the default build configuration).
+-.IP "exec [MIBOID] NAME PROG ARGS"
+-.IP "sh [MIBOID] NAME PROG ARGS"
+-invoke the named PROG with arguments of ARGS. By default the exit
+-status and first line of output from the command will be reported via
+-the \fCextTable\fR, discarding any additional output.
+-.RS
+-.IP Note:
+-Entries in this table appear in the order they are read from the
+-configuration file. This means that adding new \fIexec\fR (or \fIsh\fR)
+-directives and restarting the agent, may affect the indexing of other
+-entries.
+-.RE
+-.IP
+-The PROG argument for \fIexec\fR directives must be a full path
+-to a real binary, as it is executed via the exec() system call.
+-To invoke a shell script, use the \fIsh\fR directive instead.
+-.IP
+-If MIBOID is specified, then the results will be rooted at this point
+-in the OID tree, returning the exit statement as MIBOID.ERRORFLAG.0
+-and the entire command output in a pseudo-table based at
+-MIBNUM.ERRORMSG - with one 'row' for each line of output.
+-.RS
+-.IP Note:
+-The layout of this "relocatable" form of \fIexec\fR (or \fIsh\fR) output
+-does not strictly form a valid MIB structure. This mechanism is being
+-deprecated - please see the \fIextend\fR directive (described below) instead.
+-.RE
+-.IP
+-In either case, the exit statement and output will be cached for 30s
+-after the initial query. This cache can be flushed by a SET request of
+-the integer value 1\fR to the MIB instance \fCversionClearCache.0\fR.
+-.\"
+-.\" XXX - Is this still true ??
+-.\"
+-.IP "execfix NAME PROG ARGS"
+-registers a command that can be invoked on demand - typically to respond
+-to or fix errors with the corresponding \fIexec\fR or \fIsh\fR entry.
+-When the \fIextErrFix\fR instance for a given NAMEd entry is set to the
+-integer value of 1, this command will be called.
+-.RS
+-.IP "Note:"
+-This directive can only be used in combination with a corresponding
+-\fIexec\fR or \fIsh\fR directive, which must be defined first.
+-Attempting to define an unaccompanied \fIexecfix\fR directive will fail.
+-.RE
+-.PP
+-\fIexec\fR and \fIsh\fR extensions can only be configured via the
+-snmpd.conf file. They cannot be set up via SNMP SET requests.
+-.IP "extend [MIBOID] NAME PROG ARGS"
+-works in a similar manner to the \fIexec\fR directive, but with a number
+-of improvements. The MIB tables (\fInsExtendConfigTable\fR
+-etc) are indexed by the NAME token, so are unaffected by the order in
+-which entries are read from the configuration files.
+-There are \fItwo\fR result tables - one (\fInsExtendOutput1Table\fR)
+-containing the exit status, the first line and full output (as a single string)
+-for each \fIextend\fR entry, and the other (\fInsExtendOutput2Table\fR)
+-containing the complete output as a series of separate lines.
+-.IP
+-If MIBOID is specified, then the configuration and result tables will be rooted
+-at this point in the OID tree, but are otherwise structured in exactly
+-the same way. This means that several separate \fIextend\fR
+-directives can specify the same MIBOID root, without conflicting.
+-.IP
+-The exit status and output is cached for each entry individually, and
+-can be cleared (and the caching behaviour configured)
+-using the \fCnsCacheTable\fR.
+-.IP "extendfix NAME PROG ARGS"
+-registers a command that can be invoked on demand, by setting the
+-appropriate \fInsExtendRunType\fR instance to the value
+-\fIrun-command(3)\fR. Unlike the equivalent \fIexecfix\fR,
+-this directive does not need to be paired with a corresponding
+-\fIextend\fR entry, and can appear on its own.
+-.PP
+-Both \fIextend\fR and \fIextendfix\fR directives can be configured
+-dynamically, using SNMP SET requests to the NET-SNMP-EXTEND-MIB.
+-.SS "MIB-Specific Extension Commands"
+-The first group of extension directives invoke arbitrary commands,
+-and rely on the MIB structure (and management applications) having
+-the flexibility to accommodate and interpret the output. This is a
+-convenient way to make information available quickly and simply, but
+-is of no use when implementing specific MIB objects, where the extension
+-must conform to the structure of the MIB (rather than vice versa).
+-The remaining extension mechanisms are all concerned with such
+-MIB-specific situations - starting with "pass-through" scripts.
+-Use of this mechanism requires that the agent was built with support for the
+-\fIucd-snmp/pass\fR and \fIucd-snmp/pass_persist\fR modules (which
+-are both included as part of the default build configuration).
+-.IP "pass [-p priority] MIBOID PROG"
+-will pass control of the subtree rooted at MIBOID to the specified
+-PROG command. GET and GETNEXT requests for OIDs within this tree will
+-trigger this command, called as:
+-.RS
+-.IP
+-PROG -g OID
+-.IP
+-PROG -n OID
+-.RE
+-.IP
+-respectively, where OID is the requested OID.
+-The PROG command should return the response varbind as three separate
+-lines printed to stdout - the first line should be the OID of the returned
+-value, the second should be its TYPE (one of the text strings
+-.B integer, gauge, counter, timeticks, ipaddress, objectid,
+-or
+-.B string
+-), and the third should be the value itself.
+-.IP
+-If the command cannot return an appropriate varbind - e.g the specified
+-OID did not correspond to a valid instance for a GET request, or there
+-were no following instances for a GETNEXT - then it should exit without
+-producing any output. This will result in an SNMP \fInoSuchName\fR
+-error, or a \fInoSuchInstance\fR exception.
+-.RS
+-.RS
+-.IP "Note:"
+-The SMIv2 type \fBcounter64\fR
+-and SNMPv2 \fInoSuchObject\fR exception are not supported.
+-.RE
+-.RE
+-.IP
+-A SET request will result in the command being called as:
+-.RS
+-.IP
+-PROG -s OID TYPE VALUE
+-.RE
+-.IP
+-where TYPE is one of the tokens listed above, indicating the type of the
+-value passed as the third parameter.
+-.\".RS
+-.\".RS
+-.\".IP "Note:"
+-.\".B counter
+-.\"(and
+-.\".B counter64
+-.\") syntax objects are not valid for SETs
+-.\".RE
+-.\".RE
+-.IP
+-If the assignment is successful, the PROG command should exit without producing
+-any output. Errors should be indicated by writing one of the strings
+-.B not-writable,
+-or
+-.B wrong-type
+-to stdout,
+-and the agent will generate the appropriate error response.
+-.RS
+-.RS
+-.IP "Note:"
+-The other SNMPv2 errors are not supported.
+-.RE
+-.RE
+-.IP
+-In either case, the command should exit once it has finished processing.
+-Each request (and each varbind within a single request) will trigger
+-a separate invocation of the command.
+-.IP
+-The default registration priority is 127. This can be
+-changed by supplying the optional -p flag, with lower priority
+-registrations being used in preference to higher priority values.
+-.IP "pass_persist [-p priority] MIBOID PROG"
+-will also pass control of the subtree rooted at MIBOID to the specified
+-PROG command. However this command will continue to run after the initial
+-request has been answered, so subsequent requests can be processed without
+-the startup overheads.
+-.IP
+-Upon initialization, PROG will be passed the string "PING\\n" on stdin,
+-and should respond by printing "PONG\\n" to stdout.
+-.IP
+-For GET and GETNEXT requests, PROG will be passed two lines on stdin,
+-the command (\fIget\fR or \fIgetnext\fR) and the requested OID.
+-It should respond by printing three lines to stdout -
+-the OID for the result varbind, the TYPE and the VALUE itself -
+-exactly as for the \fIpass\fR directive above.
+-If the command cannot return an appropriate varbind,
+-it should print print "NONE\\n" to stdout (but continue running).
+-.IP
+-For SET requests, PROG will be passed three lines on stdin,
+-the command (\fIset\fR) and the requested OID,
+-followed by the type and value (both on the same line).
+-If the assignment is successful, the command should print
+-"DONE\\n" to stdout.
+-Errors should be indicated by writing one of the strings
+-.B not-writable,
+-or
+-.B wrong-type
+-to stdout,
+-and the agent will generate the appropriate error response.
+-In either case, the command should continue running.
+-.IP
+-The registration priority can be changed using the optional
+--p flag, just as for the \fIpass\fR directive.
+-.PP
+-\fIpass\fR and \fIpass_persist\fR extensions can only be configured via the
+-snmpd.conf file. They cannot be set up via SNMP SET requests.
+-.\"
+-.\" XXX - caching ??
+-.\"
+-.SS "Embedded Perl Support"
+-Programs using the previous extension mechanisms can be written in any convenient
+-programming language - including perl, which is a common choice for
+-pass-through extensions in particular. However the Net-SNMP agent
+-also includes support for embedded perl technology (similar to
+-\fImod_perl\fR for the Apache web server). This allows the agent
+-to interpret perl scripts directly, thus avoiding the overhead of
+-spawning processes and initializing the perl system when a request is received.
+-.PP
+-Use of this mechanism requires that the agent was built with support for the embedded
+-perl mechanism, which is not part of the default build environment. It
+-must be explicitly included by specifying the '--enable-embedded-perl'
+-option to the configure script when the package is first built.
+-.PP
+-If enabled, the following directives will be recognised:
+-.IP "disablePerl true"
+-will turn off embedded perl support entirely (e.g. if there are problems
+-with the perl installation).
+-.IP "perlInitFile FILE"
+-loads the specified initialisation file (if present)
+-immediately before the first \fIperl\fR directive is parsed.
+-If not explicitly specified, the agent will look for the default
+-initialisation file DATADIR/snmp/snmp_perl.pl.
+-.IP
+-The default initialisation file
+-creates an instance of a \fCNetSNMP::agent\fR object - a variable
+-\fC$agent\fR which can be used to register perl-based MIB handler routines.
+-.IP "perl EXPRESSION"
+-evaluates the given expression. This would typically register a
+-handler routine to be called when a section of the OID tree was
+-requested:
+-.RS
+-.RS
+-.nf
+-\fCperl use Data::Dumper;
+-perl sub myroutine { print "got called: ",Dumper(@_),"\\n"; }
+-perl $agent->register('mylink', '.1.3.6.1.8765', \\&myroutine);\fR
+-.fi
+-.RE
+-.RE
+-.IP
+-This expression could also source an external file:
+-.RS
+-.RS
+-\fCperl 'do /path/to/file.pl';\fR
+-.RE
+-.RE
+-.IP
+-or perform any other perl-based processing that might be required.
+-.\"
+-.\" Link to more examples
+-.\"
+-.SS Dynamically Loadable Modules
+-Most of the MIBs supported by the Net-SNMP agent are implemented as
+-C code modules, which were compiled and linked into the agent libraries
+-when the suite was first built. Such implementation modules can also be
+-compiled independently and loaded into the running agent once it has
+-started. Use of this mechanism requires that the agent was built with support for the
+-\fIucd-snmp/dlmod\fR module (which is included as part of the default
+-build configuration).
+-.IP "dlmod NAME PATH"
+-will load the shared object module from the file PATH (an absolute
+-filename), and call the initialisation routine \fIinit_NAME\fR.
+-.RS
+-.IP "Note:"
+-If the specified PATH is not a fully qualified filename, it will
+-be interpreted relative to LIBDIR/snmp/dlmod, and \fC.so\fR
+-will be appended to the filename.
+-.RE
+-.PP
+-This functionality can also be configured using SNMP SET requests
+-to the UCD-DLMOD-MIB.
+-.SS "Proxy Support"
+-Another mechanism for extending the functionality of the agent
+-is to pass selected requests (or selected varbinds) to another
+-SNMP agent, which can be running on the same host (presumably
+-listening on a different port), or on a remote system.
+-This can be viewed either as the main agent delegating requests to
+-the remote one, or acting as a proxy for it.
+-Use of this mechanism requires that the agent was built with support for the
+-\fIucd-snmp/proxy\fR module (which is included as part of the
+-default build configuration).
+-.IP "proxy [-Cn CONTEXTNAME] [SNMPCMD_ARGS] HOST OID [REMOTEOID]"
+-will pass any incoming requests under OID to the agent listening
+-on the port specified by the transport address HOST.
+-See the section
+-.B LISTENING ADDRESSES
+-in the
+-.I snmpd(8)
+-manual page for more information about the format of listening
+-addresses.
+-.RS
+-.IP "Note:"
+-To proxy the entire MIB tree, use the OID .1.3
+-(\fBnot\fR the top-level .1)
+-.RE
+-.PP
+-The \fISNMPCMD_ARGS\fR should provide sufficient version and
+-administrative information to generate a valid SNMP request
+-(see \fIsnmpcmd(1)\fR).
+-.IP "Note:"
+-The proxied request will \fInot\fR use the administrative
+-settings from the original request.
+-.RE
+-.PP
+-If a CONTEXTNAME is specified, this will register the proxy
+-delegation within the named context in the local agent.
+-Defining multiple \fIproxy\fR directives for the same OID but
+-different contexts can be used to query several remote agents
+-through a single proxy, by specifying the appropriate SNMPv3
+-context in the incoming request (or using suitable configured
+-community strings - see the \fIcom2sec\fR directive).
+-.PP
+-Specifying the REMOID parameter will map the local MIB tree
+-rooted at OID to an equivalent subtree rooted at REMOID
+-on the remote agent.
+-.SS SMUX Sub-Agents
+-The Net-SNMP agent supports the SMUX protocol (RFC 1227) to communicate
+-with SMUX-based subagents (such as \fIgated\fR, \fIzebra\fR or \fIquagga\fR).
+-Use of this mechanism requires that the agent was built with support for the
+-\fIsmux\fR module, which is not part of the default build environment, and
+-must be explicitly included by specifying the '--with-mib-modules=smux'
+-option to the configure script when the package is first built.
+-.RS
+-.IP "Note:"
+-This extension protocol has been officially deprecated in
+-favour of AgentX (see below).
+-.RE
+-.IP "smuxpeer OID PASS"
+-will register a subtree for SMUX-based processing, to be
+-authenticated using the password PASS. If a subagent
+-(or "peer") connects to the agent and registers this subtree
+-.\"
+-.\" Or a subtree of this subtree ??
+-.\"
+-then requests for OIDs within it will be passed to that
+-SMUX subagent for processing.
+-.IP
+-A suitable entry for an OSPF routing daemon (such as \fIgated\fR,
+-\fIzebra\fR or \fIquagga\fR) might be something like
+-.RS
+-.RS
+-.I smuxpeer .1.3.6.1.2.1.14 ospf_pass
+-.RE
+-.RE
+-.IP "smuxsocket [<transport-specifier>:]<transport-address>[,...]"
+-defines the address for SMUX peers to communicate with the Net-SNMP agent.
+-The default is to listen on TCP port 199 on all IPv4 interfaces, unless the
+-package has been configured with "--enable-local-smux" at build time,
+-which causes it to only listen on tcp:127.0.0.1:199 by default.
+-See the section
+-.B LISTENING ADDRESSES
+-in the
+-.I snmpd(8)
+-manual page for more information about the format of addresses.
+-.PP
+-Note the Net-SNMP agent will only operate as a SMUX \fImaster\fR
+-agent. It does not support acting in a SMUX subagent role.
+-.SS AgentX Sub-Agents
+-The Net-SNMP agent supports the AgentX protocol (RFC 2741) in
+-both master and subagent roles.
+-Use of this mechanism requires that the agent was built with support for the
+-\fIagentx\fR module (which is included as part of the
+-default build configuration), and also that this support is
+-explicitly enabled (e.g. via the \fIsnmpd.conf\fR file).
+-.PP
+-There are two directives specifically relevant to running as
+-an AgentX master agent:
+-.IP "master agentx"
+-will enable the AgentX functionality and cause the agent to
+-start listening for incoming AgentX registrations.
+-This can also be activated by specifying the '-x' command-line
+-option (to specify an alternative listening socket).
+-.IP "agentXPerms SOCKPERMS [DIRPERMS [USER|UID [GROUP|GID]]]"
+-Defines the permissions and ownership of the AgentX Unix Domain socket,
+-and the parent directories of this socket.
+-SOCKPERMS and DIRPERMS must be octal digits (see
+-.I chmod(1)
+-). By default this socket will only be accessible to subagents which
+-have the same userid as the agent.
+-.PP
+-There is one directive specifically relevant to running as
+-an AgentX sub-agent:
+-.IP "agentXPingInterval NUM"
+-will make the subagent try and reconnect every NUM seconds to the
+-master if it ever becomes (or starts) disconnected.
++[<transport-specifier>:]<transport-address>
+ .PP
+-The remaining directives are relevant to both AgentX master
+-and sub-agents:
+-.IP "agentXSocket [<transport-specifier>:]<transport-address>[,...]"
+-defines the address the master agent listens at, or the subagent
+-should connect to.
+-The default is the Unix Domain socket \fCAGENTX_SOCKET\fR.
+-Another common alternative is \fCtcp:localhost:705\fR.
+-See the section
+-.B LISTENING ADDRESSES
+-in the
+-.I snmpd(8)
+-manual page for more information about the format of addresses.
+-.RS
+-.IP "Note:"
+-Specifying an AgentX socket does \fBnot\fR automatically enable
+-AgentX functionality (unlike the '-x' command-line option).
+-.RE
+-.IP "agentXTimeout NUM"
+-defines the timeout period (NUM seconds) for an AgentX request.
+-Default is 1 second.
+-.IP "agentXRetries NUM"
+-defines the number of retries for an AgentX request.
+-Default is 5 retries.
+-.PP
+-net-snmp ships with both C and Perl APIs to develop your own AgentX
+-subagent.
+-.SH "OTHER CONFIGURATION"
+-.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:
+-.RS
+-.IP
+-\fCoverride sysDescr.0 octet_str "my own sysDescr"\fR
+-.RE
+-.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 gauges, 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.
++At its simplest, a listening address may consist only of a port
++number, in which case
++.B snmpd
++listens on that UDP port on all IPv4 interfaces. Otherwise, the
++<transport-address> part of the specification is parsed according to
++the following table:
++.RS 4
++.TP 28
++.BR "<transport-specifier>"
++.BR "<transport-address> format"
++.IP "udp \fI(default)\fR" 28
++hostname[:port]
++.I or
++IPv4-address[:port]
++.IP "tcp" 28
++hostname[:port]
++.I or
++IPv4-address[:port]
++.IP "unix" 28
++pathname
++.IP "ipx" 28
++[network]:node[/port]
++.TP 28
++.IR "" "aal5pvc " or " pvc"
++[interface.][VPI.]VCI
++.TP 28
++.IR "" "udp6 " or " udpv6 " or " udpipv6"
++hostname[:port]
++.I or
++IPv6-address[:port]
++.TP 28
++.IR "" "tcp6 " or " tcpv6 " or " tcpipv6"
++hostname[:port]
++.I or
++IPv6-address[:port]
++.RE
++.PP
++Note that <transport-specifier> strings are case-insensitive so that,
++for example, "tcp" and "TCP" are equivalent. Here are some examples,
++along with their interpretation:
++.TP 24
++.IR "127.0.0.1:161"
++listen on UDP port 161, but only on the loopback interface. This
++prevents
++.B snmpd
++being queried remotely. The port specification ":161" is
++not strictly necessary since that is the default SNMP port.
++.TP 24
++.IR "TCP:1161"
++listen on TCP port 1161 on all IPv4 interfaces.
++.TP 24
++.IR "ipx:/40000"
++listen on IPX port 40000 on all IPX interfaces.
++.TP 24
++.IR "unix:/tmp/local-agent"
++listen on the Unix domain socket \fI/tmp/local-agent\fR.
++.TP 24
++.IR "/tmp/local-agent"
++is identical to the previous specification, since the Unix domain is
++assumed if the first character of the <transport-address> is '/'.
++.TP 24
++.IR "PVC:161"
++listen on the AAL5 permanent virtual circuit with VPI=0 and VCI=161
++(decimal) on the first ATM adapter in the machine.
++.TP 24
++.IR "udp6:10161"
++listen on port 10161 on all IPv6 interfaces.
++.PP
++Note that not all the transport domains listed above will always be
++available; for instance, hosts with no IPv6 support will not be able
++to use udp6 transport addresses, and attempts to do so will result in
++the error "Error opening specified endpoint". Likewise, since AAL5
++PVC support is only currently available on Linux, it will fail with
++the same error on other platforms.
++.SH CONFIGURATION FILES
+ .PP
+-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
+-.IP 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:
+-
+- \fCinjectHandler stash_cache NAME table_iterator\fR
+-
+-If you want a table to play with, try walking the
+-\fCnsModuleTable\fR with and without this injected.
+-
+-.IP debug
+-Prints out lots of debugging information when
+-the -Dhelper:debug flag is passed to the snmpd
+-application.
+-
+-.IP read_only
+-Forces turning off write support for the given module.
+-
+-.IP 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.
+-
+-.IP 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.
+-.RE
+-.IP "dontLogTCPWrappersConnects"
+-If the \fBsnmpd\fR was compiled with TCP Wrapper support, it
+-logs every connection made to the agent. This setting disables
+-the log messages for accepted connections. Denied connections will
+-still be logged.
+-.IP "Figuring out module names"
+-To figure out which modules you can inject things into,
+-run \fBsnmpwalk\fR on the \fCnsModuleTable\fR which will give
+-a list of all named modules registered within the agent.
+-.SS Internal Data tables
+-.IP "table NAME"
+-.\" XXX: To Document
+-.IP "add_row NAME INDEX(ES) VALUE(S)"
+-.\" XXX: To Document
+-.SH NOTES
+-.IP o
+-The Net-SNMP agent can be instructed to re-read the various configuration files,
+-either via an \fBsnmpset\fR assignment of integer(1) to
+-\fCUCD-SNMP-MIB::versionUpdateConfig.0\fR (.1.3.6.1.4.1.2021.100.11.0),
+-or by sending a \fBkill -HUP\fR signal to the agent process.
+-.IP o
+-All directives listed with a value of "yes" actually accept a range
+-of boolean values. These will accept any of \fI1\fR, \fIyes\fR or
+-\fItrue\fR to enable the corresponding behaviour,
+-or any of \fI0\fR, \fIno\fR or \fIfalse\fR to disable it.
+-The default in each case is for the feature to be turned off, so these
+-directives are typically only used to enable the appropriate behaviour.
+-.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 "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).
++.B snmpd
++checks for the existence of and parses the following files:
++.TP 6
++.B SYSCONFDIR/snmp/snmp.conf
++Common configuration for the agent and applications. See
++.I snmp.conf(5)
++for details.
++.TP
++.B SYSCONFDIR/snmp/snmpd.conf
++.TP
++.B SYSCONFDIR/snmp/snmpd.local.conf
++Agent-specific configuration. See
++.I snmpd.conf(5)
++for details. These files are optional and may be used to configure
++access control, trap generation, subagent protocols and much else
++besides.
++.IP
++In addition to these two configuration files in SYSCONFDIR/snmp, the
++agent will read any files with the names
++.I snmpd.conf
++and
++.I snmpd.local.conf
++in a colon separated path specified in the
++SNMPCONFPATH environment variable.
++.TP
++.B DATADIR/snmp/mibs/
++The agent will also load all files in this directory as MIBs. It will
++not, however, load any file that begins with a '.' or descend into
++subdirectories.
++.SH SEE ALSO
++(in recommended reading order)
++.PP
++snmp_config(5),
++snmp.conf(5),
++snmpd.conf(5)
+ .\" Local Variables:
+ .\" mode: nroff
+ .\" End:
More information about the Pkg-net-snmp-commits
mailing list