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