/contrib/bsnmp/snmpd/bsnmpd.1

  1.\"
  2.\" Copyright (c) 2004-2005
  3.\"	Hartmut Brandt.
  4.\"	All rights reserved.
  5.\" Copyright (c) 2001-2003
  6.\"	Fraunhofer Institute for Open Communication Systems (FhG Fokus).
  7.\"	All rights reserved.
  8.\"
  9.\" Author: Harti Brandt <harti@FreeBSD.org>
 10.\" 
 11.\" Redistribution and use in source and binary forms, with or without
 12.\" modification, are permitted provided that the following conditions
 13.\" are met:
 14.\" 1. Redistributions of source code must retain the above copyright
 15.\"    notice, this list of conditions and the following disclaimer.
 16.\" 2. Redistributions in binary form must reproduce the above copyright
 17.\"    notice, this list of conditions and the following disclaimer in the
 18.\"    documentation and/or other materials provided with the distribution.
 19.\" 
 20.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 23.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 30.\" SUCH DAMAGE.
 31.\"
 32.\" $Begemot: bsnmp/snmpd/bsnmpd.1,v 1.12 2006/02/27 09:50:03 brandt_h Exp $
 33.\"
 34.Dd September 9, 2010
 35.Dt BSNMPD 1
 36.Os
 37.Sh NAME
 38.Nm bsnmpd
 39.Nd "simple and extensible SNMP daemon"
 40.Sh SYNOPSIS
 41.Nm
 42.Op Fl dh
 43.Op Fl c Ar file
 44.Op Fl D Ar options
 45.Op Fl e Ar file
 46.Op Fl I Ar paths
 47.Op Fl l Ar prefix
 48.Op Fl m Ar variable Ns Op = Ns Ar value
 49.Op Fl p Ar file
 50.Sh DESCRIPTION
 51The
 52.Nm
 53daemon serves the internet SNMP (Simple Network Management Protocol).
 54It is intended to serve only the absolute basic MIBs and implement all other
 55MIBs through loadable modules.
 56In this way the
 57.Nm
 58can be used in unexpected ways.
 59.Pp
 60The options are as follows:
 61.Bl -tag -width ".It Fl D Ar options"
 62.It Fl d
 63Do not daemonize.
 64Used for debugging.
 65.It Fl h
 66Print a short usage message.
 67.It Fl c Ar file
 68Use
 69.Ar file
 70as configuration file instead of the standard one.
 71.It Fl D Ar options
 72Debugging options are specified with a
 73.Fl o
 74flag followed by a comma separated string of options.
 75The following options are available.
 76.Bl -tag -width ".It Cm trace Ns Cm = Ns Cm level"
 77.It Cm dump
 78Dump all sent and received PDUs to the terminal.
 79.It Cm events
 80Set the debugging level of the event library (see
 81.Xr eventlib 3 )
 82to 10.
 83.It Cm trace Ns Cm = Ns Cm level
 84Set the snmp library trace flag to the specified
 85value.
 86.El
 87The value can be specified in the usual C-syntax for numbers.
 88.It Fl e Ar file
 89Specify an alternate file where the agent's engine id and number of boots
 90are saved.
 91.It Fl I Ar paths
 92Specify a colon separated list of directories to search for configuration
 93include files.
 94The default is
 95.Pa /etc:/usr/etc/:/usr/local/etc .
 96These paths are only searched for include specified within <> parentheses.
 97.It Fl l Ar prefix
 98Use
 99.Ar prefix
100as the default basename for the pid and the configuration files.
101.It Fl m Ar variable Ns Op = Ns Ar value
102Define a configuration variable.
103.It Fl p Ar file
104Specify an alternate pid file instead of the default one.
105.El
106.Sh CONFIGURATION
107.Nm
108reads its configuration from either the default or the user specified
109configuration file.
110The configuration file consists of the following types of lines:
111.Bl -bullet -offset indent
112.It
113variable assignments
114.It
115section separators
116.It
117include directives
118.It
119MIB variable assignments
120.El
121.Pp
122If a line is too long it can be continued on the next line by ending it with
123a backslash.
124Empty lines and lines in which the first non-blank character is a
125.Dq #
126sign are ignored.
127.Pp
128All MIB variable assignments of the entire configuration (including nested
129configuration files) are handled as one transaction, i.e., as if they arrived
130in a single SET PDU.
131Any failure during the initial configuration read causes
132.Nm
133to exit.
134A failure during the configuration read caused by a module load
135causes the loading of the module to fail.
136.Pp
137The configuration is read during initialization of
138.Nm ,
139when a module is loaded and when
140.Nm
141receives a SIGHUP.
142.Ss VARIABLE ASSIGNMENTS
143Variable assignments can take one of two forms:
144.Bd -unfilled -offset indent
145variable := string
146variable ?= string
147.Ed
148.Pp
149The string reaches from the first non-blank character after the
150equal sign until the first new line or
151.Dq #
152character.
153In the first case
154the string is assigned to the variable unconditionally, in the second case the
155variable is only assigned if it does not exist yet.
156.Pp
157Variable names must begin with a letter or underscore and contain only letters,
158digits or underscores.
159.Ss SECTION SEPARATORS
160The configuration consists of named sections.
161The MIB variable assignments in the section named
162.Dq snmpd
163are executed only during initial setup or when
164.Nm
165receives a SIGHUP.
166All other sections are executed when either a module
167with the same name as the section is loaded or
168.Nm
169receives a SIGHUP and that module is already loaded.
170The default section at the start of the configuration is
171.Dq snmpd .
172One can switch to another section with the syntax
173.Bd -unfilled -offset indent
174%secname
175.Ed
176.Pp
177Where
178.Ar secname
179is the name of the section.
180The same
181.Ar secname
182can be used in more than one place in the configuration.
183All of these parts are collected into one section.
184.Ss INCLUDE DIRECTIVES
185Another configuration file can be included into the current one with the
186include directive that takes one of two forms:
187.Bd -unfilled -offset indent
188\&.include "file"
189\&.include <"file">
190.Ed
191.Pp
192The first form causes the file to be searched in the current directory, the
193second form causes the file to be searched in the directories specified in
194the system include path.
195Nesting depth is only restricted by available memory.
196.Ss MIB VARIABLE ASSIGNMENTS
197A MIB variable is assigned with the syntax
198.Bd -unfilled -offset indent
199oid [ suboids ] = value
200.Ed
201.Pp
202.Va oid
203is the name of the variable to be set.
204Only the last component of the entire name is used here.
205If the variable is a scalar, the index (.0) is automatically
206appended and need not to be specified.
207If the variable is a table column, the index
208.Pq Va suboids
209must be specified.
210The index consist of elements each separated from the
211previous one by a dot.
212Elements may be either numbers, strings or hostnames
213enclosed in [] brackets.
214If the element is a number it is appended
215to the current oid.
216If the element is a string, its length and the
217.Tn ASCII
218code of each of its characters are appended to the current oid.
219If the
220element is a hostname, the IP address of the host is looked up and the four
221elements of the IP address are appended to the oid.
222.Pp
223For example, an oid of
224.Bd -unfilled -offset indent
225myvariable.27.foooll.[localhost]."&^!"
226.Ed
227.Pp
228results in the oid
229.Bd -unfilled -offset indent
230myvariable.27.6.102.111.111.111.108.108.127.0.0.1.38.94.33
231.Ed
232.Pp
233The value of the assignment may be either empty, a string or a number.
234If a string starts with a letter or an underscore and consists only of
235letters, digits, underscores and minus signs, it can be written without
236quotes.
237In all other cases the string must be enclosed in double quotes.
238.Sh SUBSTITUTIONS
239A variable substitution is written as
240.Bd -unfilled -offset indent
241$(variable)
242.Ed
243.Pp
244where
245.Ar variable
246is the name of the variable to substitute.
247Using an undefined variable is considered an error.
248.Sh FILES
249.Bl -tag -width ".It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid" -compact
250.It Pa /etc/ Ns Ao Ar prefix Ac Ns \&.config
251Default configuration file, where the default
252.Aq prefix
253is
254.Dq snmpd .
255.It Pa /var/ Ns Ao Ar prefix Ac Ns \&.engine
256Default engine id file.
257.It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid
258Default pid file.
259.It Pa /etc:/usr/etc/:/usr/local/etc
260Default search path for system include files.
261.It Pa @MIBSPATH@FOKUS-MIB.txt
262.It Pa @MIBSPATH@BEGEMOT-MIB.txt
263.It Pa @MIBSPATH@BEGEMOT-SNMPD.txt
264Definitions for the MIBs implemented in the daemon.
265.It Pa /etc/hosts.allow, /etc/hosts.deny
266Access controls that should be enforced by TCP wrappers are defined here.
267Further details are described in
268.Xr hosts_access 5 .
269.El
270.Sh SEE ALSO
271.Xr gensnmptree 1 ,
272.Xr hosts_access 5
273.Sh STANDARDS
274The
275.Nm
276conforms to the applicable IETF RFCs.
277.Sh AUTHORS
278.An Hartmut Brandt Aq harti@FreeBSD.org
279.Sh BUGS
280Sure.