contrib/bsnmp/snmpd/bsnmpd.1

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