xref: /freebsd/contrib/bsnmp/snmpd/bsnmpd.1 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
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 February 27, 2006
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 I Ar paths
46.Op Fl l Ar prefix
47.Op Fl m Ar variable Ns Op = Ns Ar value
48.Op Fl p Ar file
49.Sh DESCRIPTION
50The
51.Nm
52daemon server the internet SNMP (Simple Network Management Protocol).
53It is intended to serve only the absolute basic MIBs and implement all other
54MIBs through loadable modules.
55In this way the
56.Nm
57can be used in unexpected ways.
58.Pp
59The options are as follows:
60.Bl -tag -width ".It Fl D Ar options"
61.It Fl d
62This option is used for debugging
63.Nm
64and causes it not to daemonize itself.
65.It Fl h
66This option prints 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
78This option causes all sent and received PDUs to be dumped to the terminal.
79.It Cm events
80This causes the debugging level of the event library (see
81.Xr eventlib 3 )
82to be set to 10.
83.It Cm trace Ns Cm = Ns Cm level
84This option causes the snmp library trace flag to be set to the specified
85value.
86The value can be specified in the usual C-syntax for numbers.
87.El
88.It Fl I Ar paths
89This option specifies a colon separated list of directories to search for
90configuration include files.
91The default is
92.Pa /etc:/usr/etc/:/usr/local/etc .
93These paths are only searched for include specified within <> parentheses.
94.It Fl l Ar prefix
95The
96.Ar prefix
97is used as the default basename for the pid and the configuration files.
98.It Fl m Ar variable Ns Op = Ns Ar value
99Define a configuration variable.
100.It Fl p Ar file
101Specify an alternate pid file instead of the default one.
102.El
103.Sh CONFIGURATION
104The
105.Nm
106reads its configuration from either the default or the user specified
107configuration file.
108The configuration file consists of the following types of lines:
109.Bl -bullet -offset indent
110.It
111variable assignments
112.It
113section separators
114.It
115include directives
116.It
117MIB variable assignments
118.El
119.Pp
120If a line is too long it can be continued on the next line by ending it with
121a backslash.
122Empty lines and lines in which the first non-blank character is a
123.Dq #
124sign are ignored.
125.Pp
126All MIB variable assignments of the entire configuration (including nested
127configuration files) are handled as one transaction, i.e., as if they arrived
128in a single SET PDU.
129Any failure during the initial configuration read causes
130.Nm
131to exit.
132A failure during the configuration read caused by a module load
133causes the loading of the module to fail.
134.Pp
135The configuration is read during initialization of
136.Nm ,
137when a module is loaded and when
138.Nm
139receives a SIGHUP.
140.Ss VARIABLE ASSIGNMENTS
141Variable assignments can take one of two forms:
142.Bd -unfilled -offset indent
143variable := string
144variable ?= string
145.Ed
146.Pp
147The string reaches from the first non-blank character after the
148equal sign until the first new line or
149.Dq #
150character.
151In the first case
152the string is assigned to the variable unconditionally, in the second case the
153variable is only assigned if it does not exist yet.
154.Pp
155Variable names must begin with a letter or underscore and contain only letters,
156digits or underscores.
157.Ss SECTION SEPARATORS
158The configuration consists of named sections.
159The MIB variable assignments in the section named
160.Dq snmpd
161are executed only during initial setup or when
162.Nm
163receives a SIGHUP.
164All other sections are executed when either a module
165with the same name as the section is loaded or
166.Nm
167receives a SIGHUP and that module is already loaded.
168The default section at the start of the configuration is
169.Dq snmpd .
170One can switch to another section with the syntax
171.Bd -unfilled -offset indent
172%secname
173.Ed
174.Pp
175Where
176.Ar secname
177is the name of the section.
178The same
179.Ar secname
180can be used in more than one place in the configuration.
181All of these parts are collected into one section.
182.Ss INCLUDE DIRECTIVES
183Another configuration file can be included into the current one with the
184include directive that takes one of two forms:
185.Bd -unfilled -offset indent
186\&.include "file"
187\&.include <"file">
188.Ed
189.Pp
190The first form causes the file to be searched in the current directory, the
191second form causes the file to be searched in the directories specified in
192the system include path.
193Nesting depth is only restricted by available memory.
194.Ss MIB VARIABLE ASSIGNMENTS
195A MIB variable is assigned with the syntax
196.Bd -unfilled -offset indent
197oid [ suboids ] = value
198.Ed
199.Pp
200.Va oid
201is the name of the variable to be set.
202Only the last component of the entire name is used here.
203If the variable is a scalar, the index (.0) is automatically
204appended and need not to be specified.
205If the variable is a table column, the index
206.Pq Va suboids
207must be specified.
208The index consist of elements each separated from the
209previous one by a dot.
210Elements may be either numbers, strings or hostnames
211enclosed in [] brackets.
212If the element is a number it is appended
213to the current oid.
214If the element is a string, its length and the
215.Tn ASCII
216code of each of its characters are appended to the current oid.
217If the
218element is a hostname, the IP address of the host is looked up and the four
219elements of the IP address are appended to the oid.
220.Pp
221For example a oid of
222.Bd -unfilled -offset indent
223myvariable.27.foooll.[localhost]."&^!"
224.Ed
225.Pp
226results in the oid
227.Bd -unfilled -offset indent
228myvariable.27.6.102.111.111.111.108.108.127.0.0.1.38.94.33
229.Ed
230.Pp
231The value of the assignment may be either empty, a string or a number.
232If a string starts with a letter or an underscore and consists only of
233letters, digits, underscores and minus signs, it can be written without
234quotes.
235In all other cases the string must be enclosed in double quotes.
236.Sh SUBSTITUTIONS
237A variable substitution is written as
238.Bd -unfilled -offset indent
239$(variable)
240.Ed
241.Pp
242where
243.Ar variable
244is the name of the variable to substitute.
245Using an undefined variable is considered an error.
246.Sh FILES
247.Bl -tag -width ".It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid" -compact
248.It Pa /etc/ Ns Ao Ar prefix Ac Ns \&.config
249Default configuration file, where the default
250.Aq prefix
251is
252.Dq snmpd .
253.It Pa /var/run/ Ns Ao Ar prefix Ac Ns \&.pid
254Default pid file.
255.It Pa /etc:/usr/etc/:/usr/local/etc
256This is the default search path for system include files.
257.It Pa @MIBSPATH@FOKUS-MIB.txt
258.It Pa @MIBSPATH@BEGEMOT-MIB.txt
259.It Pa @MIBSPATH@BEGEMOT-SNMPD.txt
260The definitions for the MIBs implemented in the daemon.
261.It Pa /etc/hosts.allow, /etc/hosts.deny
262Access controls that should be enforced by TCP wrappers should be defined here.
263Further details are described in
264.Xr hosts_access 5 .
265.El
266.Sh SEE ALSO
267.Xr gensnmptree 1 ,
268.Xr hosts_access 5
269.Sh STANDARDS
270The
271.Nm
272conforms to the applicable IETF RFCs.
273.Sh AUTHORS
274.An Hartmut Brandt Aq harti@freebsd.org
275.Sh BUGS
276Sure.
277