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