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