/contrib/bsnmp/snmpd/bsnmpd.1

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 280 lines · 280 code · 0 blank · 0 comment · 0 complexity · faf5d2c7e9ea5f235fd74c99361fa79f MD5 · raw file

  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.