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