sbin/devd/devd.conf.5

   1 .\"
   2 .\" Copyright (c) 2002 M. Warner Losh
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. The name of the author may not be used to endorse or promote products
  11 .\"    derived from this software without specific prior written permission.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .\" The section on comments was taken from named.conf.5, which has the
  28 .\" following copyright:
  29 .\" Copyright (c) 1999-2000 by Internet Software Consortium
  30 .\"
  31 .\" Permission to use, copy, modify, and distribute this software for any
  32 .\" purpose with or without fee is hereby granted, provided that the above
  33 .\" copyright notice and this permission notice appear in all copies.
  34 .\"
  35 .\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
  36 .\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
  37 .\" OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
  38 .\" CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  39 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  40 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  41 .\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  42 .\" SOFTWARE.
  43 .\"
  44 .Dd October 7, 2006
  45 .Dt DEVD.CONF 5
  46 .Os
  47 .Sh NAME
  48 .Nm devd.conf
  49 .Nd configuration file for
  50 .Xr devd 8
  51 .Sh DESCRIPTION
  52 .Ss General Syntax
  53 A
  54 .Xr devd 8
  55 configuration consists of two general features, statements
  56 and comments.
  57 All statements end with a semicolon.
  58 Many statements can contain substatements, which are also
  59 terminated with a semicolon.
  60 .Pp
  61 The following statements are supported:
  62 .Bl -tag -width ".Ic options"
  63 .It Ic attach
  64 Specifies various matching criteria and actions to perform when
  65 a newly attached device matches said criteria.
  66 .It Ic detach
  67 Specifies various matching criteria and actions to perform when
  68 a newly detached device matches said criteria.
  69 .It Ic nomatch
  70 Specifies various matching criteria and actions to perform when
  71 no device driver currently loaded in the kernel claims a (new)
  72 device.
  73 .It Ic notify
  74 Specifies various matching criteria and actions to perform when the kernel
  75 sends an event notification to userland.
  76 .It Ic options
  77 Specifies various options and parameters for the operation of
  78 .Xr devd 8 .
  79 .El
  80 .Pp
  81 Statements may occur in any order in the configuration file, and may be
  82 repeated as often as required.
  83 Further details on the syntax and meaning of each statement and their
  84 substatements are explained below.
  85 .Pp
  86 Each statement, except
  87 .Dq options
  88 has a priority (an arbitrary number) associated with it, where
  89 .Ql 0
  90 is defined as the lowest priority.
  91 If two statements match the same event, only the action of the statement with
  92 highest priority will be executed.
  93 In this way generic statements can be overridden for devices or
  94 notifications that require special attention.
  95 .Pp
  96 The general syntax of a statement is:
  97 .Pp
  98 .Bd -literal -offset indent
  99 statement priority {
 100         substatement "value";
 101         ...
 102         substatement "value";
 103 };
 104 .Ed
 105 .Pp
 106 .Ss Sub-statements
 107 The following sub-statements are supported within the
 108 .Dq options
 109 statement.
 110 .Bl -tag -width ".Ic directory"
 111 .It Ic directory \*q/some/path\*q;
 112 Adds the given directory to the list of directories from which
 113 .Xr devd 8
 114 will read
 115 configuration files. Any number of
 116 .Dq directory
 117 statements can be used.
 118 .It Ic pid-file \*q/var/run/devd.pid\*q;
 119 Specifies pid file.
 120 .It Ic set regexp-name \*q(some|regexp)\*q;
 121 Creates a regular expression and assigns it to the variable
 122 .Va regexp-name .
 123 The variable is avaiable throughout the rest of
 124 the configuration file.
 125 All regular expressions have an implicit
 126 .Ql Li ^$
 127 around them.
 128 .El
 129 .Pp
 130 The following sub-statements are supported within the
 131 .Dq attach
 132 and
 133 .Dq detach
 134 statements.
 135 .Bl -tag -width ".Ic directory"
 136 .It Ic action \*qcommand\*q;
 137 Command to execute upon a successful match.
 138 Example
 139 .Ic /etc/pccard_ether $device-name start
 140 .It Ic class \*qstring\*q;
 141 This is shorthand for
 142 .Dq match \*qclass\*q .
 143 .It Ic device-name \*qstring\*q;
 144 This is shorthand for
 145 .Dq match \*qdevice-name\*q .
 146 This matches a device named
 147 .Va string ;
 148 which is allowed to be a regular expression or a variable previously created
 149 containing a regular expression.
 150 The
 151 .Va device-name
 152 variable
 153 is avaiable for later use with the action-statement.
 154 .It Ic match \*qvariable\*q \*qvalue\*q;
 155 Matches the content of
 156 .Va value
 157 against
 158 .Va variable ,
 159 the content of
 160 .Va value
 161 may be a regular expression.
 162 Not required during
 163 .Dq Li attach
 164 nor
 165 .Dq Li detach
 166 events since the
 167 .Dq Li device-name
 168 statement takes care of all device matching.
 169 For a partial list of variables, see below.
 170 .It Ic media-type \*qstring\*q;
 171 This is shorthand for
 172 .Dq match \*qdevice-name\*q .
 173 .It Ic subdevice \*qstring\*q;
 174 This is shorthand for
 175 .Dq match \*qsubdevice\*q .
 176 .El
 177 .Pp
 178 The following sub-statements are supported within the
 179 .Dq nomatch
 180 statement.
 181 .Bl -tag -width ".Ic directory"
 182 .It Ic action \*qcommand\*q;
 183 Same as above.
 184 .It Ic match \*qvariable\*q \*qvalue\*q;
 185 Matches the content of
 186 .Va value
 187 against
 188 .Va variable ,
 189 the content of
 190 .Va value
 191 may be a regular expression.
 192 For a partial list of variables, see below.
 193 .El
 194 .Pp
 195 The following sub-statements are supported within the
 196 .Dq notify
 197 statement.
 198 The
 199 .Dq Li notify
 200 variable is avaiable inside this statement and contains, a value, depending
 201 on which system and subsystem that delivered the event.
 202 .Bl -tag -width ".Ic directory"
 203 .It Ic action \*qcommand\*q;
 204 Command to execute upon a successful match. Example
 205 .Ic /etc/rc.d/power_profile $notify
 206 .It Ic match \*qsystem|subsystem|type|notify\*q \*qvalue\*q;
 207 Any number of
 208 .Dq match
 209 statements can exists within a
 210 .Dq notify
 211 statement.
 212 .Va value
 213 can be either a fixed string or a regular expression.
 214 Below is a list of avaiable systems, subsystems, and types.
 215 .El
 216 .Ss Variables that can be used with the match statement
 217 A partial list of variables and their possible values that can be used together
 218 with the
 219 .Dq match
 220 statement.
 221 .Pp
 222 .Bl -tag -width "manufacturer" -compact
 223 .It Ic Variable
 224 .Ic Description
 225 .It bus
 226 Device name of parent bus
 227 .It cisproduct
 228 CIS-product
 229 .It cisvendor
 230 CIS-vendor
 231 .It class
 232 Device class
 233 .It device
 234 Device ID
 235 .It device-name
 236 Name of attached/detached device
 237 .It function
 238 Card functions
 239 .It manufacturer
 240 Manufacturer ID (pccard)
 241 .It notify
 242 Match the value of the
 243 .Dq Li notify
 244 variable.
 245 .It product
 246 Product ID (pccard)
 247 .It serial
 248 Serial Number (USB)
 249 .It slot
 250 Card slot
 251 .It subvendor
 252 Sub-vendor ID
 253 .It subdevice
 254 Sub-device ID
 255 .It subsystem
 256 Matches a subsystem of a system, see below
 257 .It system
 258 Matches a system type, see below
 259 .It type
 260 Type of notification, see below
 261 .It vendor
 262 Vendor ID
 263 .El
 264 .Ss Notify matching
 265 A Partial list of systems, subsystems, and types used within the
 266 .Dq notify
 267 mechanism.
 268 .Pp
 269 .Bl -tag -width "IFNET" -compact
 270 .It Ic System
 271 .It ACPI
 272 Events related to the ACPI subsystem.
 273 .Bl -tag -compact
 274 .It Ic Subsystem
 275 .It ACAD
 276 AC Line state ($notify=0x00 is offline, 0x01 is online).
 277 .It Button
 278 Button state ($notify=0x00 is power, 0x01 is sleep).
 279 .It CMBAT
 280 Battery events.
 281 .It Lid
 282 Lid state ($notify=0x00 is closed, 0x01 is open).
 283 .It Thermal
 284 Thermal zone events.
 285 .El
 286 .Pp
 287 .It IFNET
 288 Events related to the network subsystem.
 289 .Bl -tag -compact
 290 .It Ic Subsystem
 291 .It [interface]
 292 The
 293 .Dq subsystem
 294 is the actual name of the network interface on which the event
 295 took place.
 296 .Bl -tag -compact
 297 .It Ic Type
 298 .It LINK_UP
 299 Carrier status changed to UP.
 300 .It LINK_DOWN
 301 Carrier status changed to DOWN.
 302 .El
 303 .El
 304 .El
 305 .Pp
 306 A link state change to UP on the interface
 307 .Dq fxp0
 308 would result in the following notify event:
 309 .Bd -literal -offset indent
 310 system=IFNET, subsystem=fxp0, type=LINK_UP
 311 .Ed
 312 .Pp
 313 An AC line state change to
 314 .Dq offline
 315 would result in the following event:
 316 .Bd -literal -offset indent
 317 system=ACPI, subsystem=ACAD, notify=0x00
 318 .Ed
 319 .Ss Comments
 320 Comments may appear anywhere that whitespace may appear in a
 321 configuration file.
 322 To appeal to programmers of all kinds, they can
 323 be written in C, C++, or shell/Perl constructs.
 324 .Pp
 325 C-style comments start with the two characters
 326 .Ql /*
 327 (slash, star) and end with
 328 .Ql */
 329 (star, slash).
 330 Because they are completely delimited with these characters,
 331 they can be used to comment only a portion of a line or to span
 332 multiple lines.
 333 .Pp
 334 C-style comments cannot be nested.
 335 For example, the following is
 336 not valid because the entire comment ends with the first
 337 .Ql */ :
 338 .Bd -literal -offset indent
 339 /* This is the start of a comment.
 340    This is still part of the comment.
 341 /* This is an incorrect attempt at nesting a comment. */
 342    This is no longer in any comment. */
 343 .Ed
 344 .Pp
 345 C++-style comments start with the two characters
 346 .Ql //
 347 (slash, slash) and continue to the end of the physical line.
 348 They cannot be continued across multiple physical lines; to have
 349 one logical comment span multiple lines, each line must use the
 350 .Dq //
 351 pair.
 352 For example:
 353 .Bd -literal -offset indent
 354 // This is the start of a comment.  The next line
 355 // is a new comment, even though it is logically
 356 // part of the previous comment.
 357 .Ed
 358 .Sh EXAMPLES
 359 .Bd -literal
 360 #
 361 # This will catch link down events on the interfaces fxp0 and ath0
 362 #
 363 notify 0 {
 364         match "system"                  "IFNET";
 365         match "subsystem"               "(fxp0|ath0)";
 366         match "type"                    "LINK_DOWN";
 367         action "logger $subsystem is DOWN";
 368 };
 369
 370 #
 371 # Match lid open/close events
 372 # These can be combined to a single event, by passing the
 373 # value of $notify to the external script.
 374 #
 375 notify 0 {
 376         match "system"                  "ACPI";
 377         match "subsystem"               "Lid";
 378         match "notify"                  "0x00";
 379         action "logger Lid closed, we can sleep now!";
 380 };
 381
 382 notify 0 {
 383         match "system"                  "ACPI";
 384         match "subsystem"               "Lid";
 385         match "notify"                  "0x01";
 386         action "logger Lid opened, the sleeper must awaken!";
 387 };
 388
 389 #
 390 # Try to configure ath and wi devices with pccard_ether
 391 # as they are attached.
 392 #
 393 attach 0 {
 394         device-name "(ath|wi)[0-9]+";
 395         action "/etc/pccard_ether $device-name start";
 396 };
 397
 398 #
 399 # Stop ath and wi devices as they are detached from
 400 # the system.
 401 #
 402 detach 0 {
 403         device-name "(ath|wi)[0-9]+";
 404         action "/etc/pccard_ether $device-name stop";
 405 };
 406 .Ed
 407 .Pp
 408 The installed
 409 .Pa /etc/devd.conf
 410 has many additional examples.
 411 .Sh FILES
 412 .Bl -tag -width ".Pa /etc/devd.conf" -compact
 413 .It Pa /etc/devd.conf
 414 The
 415 .Xr devd 8
 416 configuration file.
 417 .El
 418 .Sh SEE ALSO
 419 .Xr devd 8