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 March 8, 2009
  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 .Ic 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 .Bd -literal -offset indent
  98 statement priority {
  99         substatement "value";
 100         ...
 101         substatement "value";
 102 };
 103 .Ed
 104 .Ss Sub-statements
 105 The following sub-statements are supported within the
 106 .Ic options
 107 statement.
 108 .Bl -tag -width ".Ic directory"
 109 .It Ic directory Qq Ar /some/path ;
 110 Adds the given directory to the list of directories from which
 111 .Xr devd 8
 112 will read all files named "*.conf" as further
 113 configuration files.
 114 Any number of
 115 .Ic directory
 116 statements can be used.
 117 .It Ic pid-file Qq Pa /var/run/devd.pid ;
 118 Specifies PID file.
 119 .It Ic set Ar regexp-name Qq Ar (some|regexp) ;
 120 Creates a regular expression and assigns it to the variable
 121 .Ar regexp-name .
 122 The variable is available throughout the rest of
 123 the configuration file.
 124 All regular expressions have an implicit
 125 .Ql ^$
 126 around them.
 127 .El
 128 .Pp
 129 The following sub-statements are supported within the
 130 .Ic attach
 131 and
 132 .Ic detach
 133 statements.
 134 .Bl -tag -width ".Ic directory"
 135 .It Ic action Qq Ar command ;
 136 Command to execute upon a successful match.
 137 Example
 138 .Dq Li "/etc/pccard_ether $device-name start" .
 139 .It Ic class Qq Ar string ;
 140 This is shorthand for
 141 .Dq Ic match Qo Li class Qc Qq Ar string .
 142 .It Ic device-name Qq string ;
 143 This is shorthand for
 144 .Dq Ic match Qo Li device-name Qc Qq Ar string .
 145 This matches a device named
 146 .Ar string ,
 147 which is allowed to be a regular expression or a variable previously created
 148 containing a regular expression.
 149 The
 150 .Dq Li device-name
 151 variable
 152 is available for later use with the
 153 .Ic action
 154 statement.
 155 .It Ic match Qo Ar variable Qc Qq Ar value ;
 156 Matches the content of
 157 .Ar value
 158 against
 159 .Ar variable ;
 160 the content of
 161 .Ar value
 162 may be a regular expression.
 163 Not required during
 164 .Ic attach
 165 nor
 166 .Ic detach
 167 events since the
 168 .Ic device-name
 169 statement takes care of all device matching.
 170 For a partial list of variables, see below.
 171 .It Ic media-type Qq Ar string ;
 172 For network devices,
 173 .Ic media-type
 174 will match devices that have the given media type.
 175 Valid media types are:
 176 .Dq Li Ethernet ,
 177 .Dq Li Tokenring ,
 178 .Dq Li FDDI ,
 179 .Dq Li 802.11 ,
 180 .Dq Li ATM ,
 181 and
 182 .Dq Li CARP .
 183 .It Ic subdevice Qq Ar string ;
 184 This is shorthand for
 185 .Dq Ic match Qo Li subdevice Qc Qq Ar string .
 186 .El
 187 .Pp
 188 The following sub-statements are supported within the
 189 .Ic nomatch
 190 statement.
 191 .Bl -tag -width ".Ic directory"
 192 .It Ic action Qq Ar command ;
 193 Same as above.
 194 .It Ic match Qo Ar variable Qc Qq Ar value ;
 195 Matches the content of
 196 .Ar value
 197 against
 198 .Ar variable ;
 199 the content of
 200 .Ar value
 201 may be a regular expression.
 202 For a partial list of variables, see below.
 203 .El
 204 .Pp
 205 The following sub-statements are supported within the
 206 .Ic notify
 207 statement.
 208 The
 209 .Dq Li notify
 210 variable is available inside this statement and contains, a value, depending
 211 on which system and subsystem that delivered the event.
 212 .Bl -tag -width ".Ic directory"
 213 .It Ic action Qq Ar command ;
 214 Command to execute upon a successful match.
 215 Example
 216 .Dq Li "/etc/rc.d/power_profile $notify" .
 217 .It Ic match Qo Ar system | subsystem | type | notify Qc Qq Ar value ;
 218 Any number of
 219 .Ic match
 220 statements can exist within a
 221 .Ic notify
 222 statement;
 223 .Ar value
 224 can be either a fixed string or a regular expression.
 225 Below is a list of available systems, subsystems, and types.
 226 .It Ic media-type Qq Ar string ;
 227 See above.
 228 .El
 229 .Ss Variables that can be used with the match statement
 230 A partial list of variables and their possible values that can be used together
 231 with the
 232 .Ic match
 233 statement.
 234 .Pp
 235 .Bl -tag -width ".Li manufacturer" -compact
 236 .It Ic Variable
 237 .Ic Description
 238 .It Li bus
 239 Device name of parent bus.
 240 .It Li cdev
 241 Device node path if one is created by the
 242 .Xr devfs 5
 243 filesystem.
 244 .It Li cisproduct
 245 CIS-product.
 246 .It Li cisvendor
 247 CIS-vendor.
 248 .It Li class
 249 Device class.
 250 .It Li device
 251 Device ID.
 252 .It Li devclass
 253 Device Class (USB)
 254 .It Li devsubclass
 255 Device Sub-class (USB)
 256 .It Li device-name
 257 Name of attached/detached device.
 258 .It Li endpoints
 259 Endpoint count (USB)
 260 .It Li function
 261 Card functions.
 262 .It Li interface
 263 Interface ID (USB)
 264 .It Li intclass
 265 Interface Class (USB)
 266 .It Li intprotocol
 267 Interface Protocol  (USB)
 268 .It Li intsubclass
 269 Interface Sub-class (USB)
 270 .It Li manufacturer
 271 Manufacturer ID (pccard).
 272 .It Li mode
 273 Peripheral mode (USB)
 274 .It Li notify
 275 Match the value of the
 276 .Dq Li notify
 277 variable.
 278 .It Li parent
 279 Parent device
 280 .It Li port
 281 Hub port number (USB)
 282 .It Li product
 283 Product ID (pccard/USB).
 284 .It Li release
 285 Hardware revision (USB)
 286 .It Li sernum
 287 Serial Number (USB).
 288 .It Li slot
 289 Card slot.
 290 .It Li subvendor
 291 Sub-vendor ID.
 292 .It Li subdevice
 293 Sub-device ID.
 294 .It Li subsystem
 295 Matches a subsystem of a system, see below.
 296 .It Li system
 297 Matches a system type, see below.
 298 .It Li type
 299 Type of notification, see below.
 300 .It Li vendor
 301 Vendor ID.
 302 .El
 303 .Ss Notify matching
 304 A partial list of systems, subsystems, and types used within the
 305 .Ic notify
 306 mechanism.
 307 .Pp
 308 .Bl -tag -width ".Li coretemp" -compact
 309 .It Sy System
 310 .It Li ACPI
 311 Events related to the ACPI subsystem.
 312 .Bl -tag -width ".Sy Subsystem" -compact
 313 .It Sy Subsystem
 314 .It Li ACAD
 315 AC line state ($notify=0x00 is offline, 0x01 is online).
 316 .It Li Button
 317 Button state ($notify=0x00 is power, 0x01 is sleep).
 318 .It Li CMBAT
 319 Battery events.
 320 .It Li Lid
 321 Lid state ($notify=0x00 is closed, 0x01 is open).
 322 .It Li Thermal
 323 Thermal zone events.
 324 .El
 325 .Pp
 326 .It Li IFNET
 327 Events related to the network subsystem.
 328 .Bl -tag -width ".Sy Subsystem" -compact
 329 .It Sy Subsystem
 330 .It Ar interface
 331 The
 332 .Dq subsystem
 333 is the actual name of the network interface on which the event
 334 took place.
 335 .Bl -tag -width ".Li LINK_DOWN" -compact
 336 .It Sy Type
 337 .It Li LINK_UP
 338 Carrier status changed to UP.
 339 .It Li LINK_DOWN
 340 Carrier status changed to DOWN.
 341 .It Li ATTACH
 342 The network interface is attached to the system.
 343 .It Li DETACH
 344 The network interface is detached from the system.
 345 .El
 346 .El
 347 .It Li DEVFS
 348 Events related to the
 349 .Xr devfs 5
 350 filesystem.
 351 .Bl -tag -width ".Sy Subsystem" -compact
 352 .It Sy Subsystem
 353 .It Li CDEV
 354 .Bl -tag -width ".Li DESTROY" -compact
 355 .It Sy Type
 356 .It Li CREATE
 357 The
 358 .Xr devfs 5
 359 node is created.
 360 .It Li DESTROY
 361 The
 362 .Xr devfs 5
 363 node is destroyed.
 364 .El
 365 .El
 366 .It Li USB
 367 Events related to the USB subsystem.
 368 .Bl -tag -width ".Sy Subsystem" -compact
 369 .It Sy Subsystem
 370 .It Li DEVICE
 371 .Bl -tag -width ".Li DETACH" -compact
 372 .It Sy Type
 373 .It Li ATTACH
 374 USB device is attached to the system.
 375 .It Li DETACH
 376 USB device is detached from the system.
 377 .El
 378 .It Li INTERFACE
 379 .Bl -tag -width ".Li DETACH" -compact
 380 .It Sy Type
 381 .It Li ATTACH
 382 USB interface is attached to a device.
 383 .It Li DETACH
 384 USB interface is detached from a device.
 385 .El
 386 .El
 387 .It Li coretemp
 388 Events related to the
 389 .Xr coretemp 4
 390 device.
 391 .Bl -tag -width ".Sy Subsystem" -compact
 392 .It Sy Subsystem
 393 .It Li Thermal
 394 Notification that the CPU core has reached critical temperature.
 395 .Bl -tag -width ".Ar temperature" -compact
 396 .It Sy Type
 397 .It Ar temperature
 398 String containing the temperature of the core that has become too hot.
 399 .El
 400 .El
 401 .It Li kern
 402 Events related to the kernel.
 403 .Bl -tag -width ".Sy Subsystem" -compact
 404 .It Sy Subsystem
 405 .It Li power
 406 Information about the state of the system.
 407 .Bl -tag -width ".li resume" -compact
 408 .It Sy Type
 409 .It Li resume
 410 Notification that the system has woken from the suspended state.
 411 .El
 412 .El
 413 .El
 414 .Pp
 415 A link state change to UP on the interface
 416 .Dq Li fxp0
 417 would result in the following notify event:
 418 .Bd -literal -offset indent
 419 system=IFNET, subsystem=fxp0, type=LINK_UP
 420 .Ed
 421 .Pp
 422 An AC line state change to
 423 .Dq offline
 424 would result in the following event:
 425 .Bd -literal -offset indent
 426 system=ACPI, subsystem=ACAD, notify=0x00
 427 .Ed
 428 .Ss Comments
 429 Comments may appear anywhere that whitespace may appear in a
 430 configuration file.
 431 To appeal to programmers of all kinds, they can
 432 be written in C, C++, or shell/Perl constructs.
 433 .Pp
 434 C-style comments start with the two characters
 435 .Ql /*
 436 (slash, star) and end with
 437 .Ql */
 438 (star, slash).
 439 Because they are completely delimited with these characters,
 440 they can be used to comment only a portion of a line or to span
 441 multiple lines.
 442 .Pp
 443 C-style comments cannot be nested.
 444 For example, the following is
 445 not valid because the entire comment ends with the first
 446 .Ql */ :
 447 .Bd -literal -offset indent
 448 /* This is the start of a comment.
 449    This is still part of the comment.
 450 /* This is an incorrect attempt at nesting a comment. */
 451    This is no longer in any comment. */
 452 .Ed
 453 .Pp
 454 C++-style comments start with the two characters
 455 .Ql //
 456 (slash, slash) and continue to the end of the physical line.
 457 They cannot be continued across multiple physical lines; to have
 458 one logical comment span multiple lines, each line must use the
 459 .Ql //
 460 pair.
 461 For example:
 462 .Bd -literal -offset indent
 463 // This is the start of a comment.  The next line
 464 // is a new comment, even though it is logically
 465 // part of the previous comment.
 466 .Ed
 467 .Sh FILES
 468 .Bl -tag -width ".Pa /etc/devd.conf" -compact
 469 .It Pa /etc/devd.conf
 470 The
 471 .Xr devd 8
 472 configuration file.
 473 .El
 474 .Sh EXAMPLES
 475 .Bd -literal
 476 #
 477 # This will catch link down events on the interfaces fxp0 and ath0
 478 #
 479 notify 0 {
 480         match "system"                  "IFNET";
 481         match "subsystem"               "(fxp0|ath0)";
 482         match "type"                    "LINK_DOWN";
 483         action "logger $subsystem is DOWN";
 484 };
 485
 486 #
 487 # Match lid open/close events
 488 # These can be combined to a single event, by passing the
 489 # value of $notify to the external script.
 490 #
 491 notify 0 {
 492         match "system"                  "ACPI";
 493         match "subsystem"               "Lid";
 494         match "notify"                  "0x00";
 495         action "logger Lid closed, we can sleep now!";
 496 };
 497
 498 notify 0 {
 499         match "system"                  "ACPI";
 500         match "subsystem"               "Lid";
 501         match "notify"                  "0x01";
 502         action "logger Lid opened, the sleeper must awaken!";
 503 };
 504
 505 #
 506 # Match a USB device type
 507 #
 508 notify 0 {
 509         match "system"                  "USB";
 510         match "subsystem"               "INTERFACE";
 511         match "type"                    "ATTACH";
 512         match "intclass"                "0x0e";
 513         action "logger USB video device attached";
 514 };
 515
 516 #
 517 # Try to configure ath and wi devices with pccard_ether
 518 # as they are attached.
 519 #
 520 attach 0 {
 521         device-name "(ath|wi)[0-9]+";
 522         action "/etc/pccard_ether $device-name start";
 523 };
 524
 525 #
 526 # Stop ath and wi devices as they are detached from
 527 # the system.
 528 #
 529 detach 0 {
 530         device-name "(ath|wi)[0-9]+";
 531         action "/etc/pccard_ether $device-name stop";
 532 };
 533 .Ed
 534 .Pp
 535 The installed
 536 .Pa /etc/devd.conf
 537 has many additional examples.
 538 .Sh SEE ALSO
 539 .Xr coretemp 4 ,
 540 .Xr devfs 5 ,
 541 .Xr devd 8