xref: /freebsd/sbin/devd/devd.conf.5 (revision cddbc3b40812213ff00041f79174cac0be360a2a)
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 29, 2019
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
53A
54.Xr devd 8
55configuration consists of two general features, statements
56and comments.
57All statements end with a semicolon.
58Many statements can contain substatements, which are also
59terminated with a semicolon.
60.Pp
61The following statements are supported:
62.Bl -tag -width ".Ic options"
63.It Ic attach
64Specifies various matching criteria and actions to perform when
65a newly attached device matches said criteria.
66.It Ic detach
67Specifies various matching criteria and actions to perform when
68a newly detached device matches said criteria.
69.It Ic nomatch
70Specifies various matching criteria and actions to perform when
71no device driver currently loaded in the kernel claims a (new)
72device.
73.It Ic notify
74Specifies various matching criteria and actions to perform when the kernel
75sends an event notification to userland.
76.It Ic options
77Specifies various options and parameters for the operation of
78.Xr devd 8 .
79.El
80.Pp
81Statements may occur in any order in the configuration file, and may be
82repeated as often as required.
83Further details on the syntax and meaning of each statement and their
84substatements are explained below.
85.Pp
86Each statement, except
87.Ic options
88has a priority (an arbitrary number) associated with it, where
89.Ql 0
90is defined as the lowest priority.
91If two statements match the same event, only the action of the statement with
92highest priority will be executed.
93In this way generic statements can be overridden for devices or
94notifications that require special attention.
95.Pp
96The general syntax of a statement is:
97.Bd -literal -offset indent
98statement priority {
99	substatement "value";
100	...
101	substatement "value";
102};
103.Ed
104.Ss Sub-statements
105The following sub-statements are supported within the
106.Ic options
107statement.
108.Bl -tag -width ".Ic directory"
109.It Ic directory Qq Ar /some/path ;
110Adds the given directory to the list of directories from which
111.Xr devd 8
112will read all files named "*.conf" as further
113configuration files.
114Any number of
115.Ic directory
116statements can be used.
117.It Ic pid-file Qq Pa /var/run/devd.pid ;
118Specifies PID file.
119.It Ic set Ar regexp-name Qq Ar (some|regexp) ;
120Creates a regular expression and assigns it to the variable
121.Ar regexp-name .
122The variable is available throughout the rest of
123the configuration file.
124If the string begins with
125.Ql \&! ,
126it matches if the regular expression formed by the rest of the string
127does not match.
128All regular expressions have an implicit
129.Ql ^$
130around them.
131.El
132.Pp
133The following sub-statements are supported within the
134.Ic attach
135and
136.Ic detach
137statements.
138.Bl -tag -width ".Ic directory"
139.It Ic action Qq Ar command ;
140Command to execute upon a successful match.
141Example
142.Dq Li "/etc/pccard_ether $device-name start" .
143.It Ic class Qq Ar string ;
144This is shorthand for
145.Dq Ic match Qo Li class Qc Qq Ar string .
146.It Ic device-name Qq string ;
147This is shorthand for
148.Dq Ic match Qo Li device-name Qc Qq Ar string .
149This matches a device named
150.Ar string ,
151which is allowed to be a regular expression or a variable previously created
152containing a regular expression.
153The
154.Dq Li device-name
155variable
156is available for later use with the
157.Ic action
158statement.
159.It Ic match Qo Ar variable Qc Qq Ar value ;
160Matches the content of
161.Ar value
162against
163.Ar variable ;
164the content of
165.Ar value
166may be a regular expression.
167Not required during
168.Ic attach
169nor
170.Ic detach
171events since the
172.Ic device-name
173statement takes care of all device matching.
174For a partial list of variables, see below.
175.It Ic media-type Qq Ar string ;
176For network devices,
177.Ic media-type
178will match devices that have the given media type.
179Valid media types are:
180.Dq Li Ethernet ,
181.Dq Li Tokenring ,
182.Dq Li FDDI ,
183.Dq Li 802.11 ,
184and
185.Dq Li ATM .
186.It Ic subdevice Qq Ar string ;
187This is shorthand for
188.Dq Ic match Qo Li subdevice Qc Qq Ar string .
189.El
190.Pp
191The following sub-statements are supported within the
192.Ic nomatch
193statement.
194.Bl -tag -width ".Ic directory"
195.It Ic action Qq Ar command ;
196Same as above.
197.It Ic match Qo Ar variable Qc Qq Ar value ;
198Matches the content of
199.Ar value
200against
201.Ar variable ;
202the content of
203.Ar value
204may be a regular expression.
205For a partial list of variables, see below.
206.El
207.Pp
208The following sub-statements are supported within the
209.Ic notify
210statement.
211The
212.Dq Li notify
213variable is available inside this statement and contains, a value, depending
214on which system and subsystem that delivered the event.
215.Bl -tag -width ".Ic directory"
216.It Ic action Qq Ar command ;
217Command to execute upon a successful match.
218Example
219.Dq Li "/etc/rc.d/power_profile $notify" .
220.It Ic match Qo Ar system | subsystem | type | notify Qc Qq Ar value ;
221Any number of
222.Ic match
223statements can exist within a
224.Ic notify
225statement;
226.Ar value
227can be either a fixed string or a regular expression.
228Below is a list of available systems, subsystems, and types.
229.It Ic media-type Qq Ar string ;
230See above.
231.El
232.Ss Variables that can be used with the match statement
233A partial list of variables and their possible values that can be used together
234with the
235.Ic match
236statement.
237The variables are published by the bus based on characteristics of the device
238that generated the event (for device events).
239Variables for other classes of events are dependent on those events.
240.Pp
241.Bl -tag -width ".Li manufacturer" -compact
242.It Ic Variable
243.Ic Description
244.It Li *
245The entire message from the current event.
246.It Li _
247The entire message from the current event, after the initial type character.
248.It Li timestamp
249The time this event was processed, in seconds since 1970 dot fraction.
250.It Li bus
251Device name of parent bus.
252.It Li cdev
253Device node path if one is created by the
254.Xr devfs 5
255filesystem.
256.It Li cisproduct
257CIS-product.
258.It Li cisvendor
259CIS-vendor.
260.It Li class
261Device class.
262.It Li comm
263Executable name (kernel).
264.It Li core
265Path to core file (kernel).
266.It Li device
267Device ID.
268.It Li devclass
269Device Class (USB).
270.It Li devsubclass
271Device Sub-class (USB).
272.It Li device-name
273Name of attached/detached device.
274.It Li endpoints
275Endpoint count (USB).
276.It Li function
277Card functions.
278.It Li interface
279Interface ID (USB).
280.It Li intclass
281Interface Class (USB).
282.It Li intprotocol
283Interface Protocol (USB).
284.It Li intsubclass
285Interface Sub-class (USB).
286.It Li jail
287Jail name for the process triggering the rule (RCTL).
288.It Li manufacturer
289Manufacturer ID (pccard).
290.It Li mode
291Peripheral mode (USB).
292.It Li notify
293Match the value of the
294.Dq Li notify
295variable.
296.It Li parent
297Parent device.
298.It Li pid
299PID of the process triggering the rule (RCTL).
300.It Li port
301Hub port number (USB).
302.It Li product
303Product ID (pccard/USB).
304.It Li release
305Hardware revision (USB).
306.It Li ruid
307Real UID of the process triggering the rule (RCTL).
308.It Li rule
309Rule (RCTL).
310.It Li sernum
311Serial Number (USB).
312.It Li slot
313Card slot.
314.It Li subvendor
315Sub-vendor ID.
316.It Li subdevice
317Sub-device ID.
318.It Li subsystem
319Matches a subsystem of a system, see below.
320.It Li system
321Matches a system type, see below.
322.It Li type
323Type of notification, see below.
324.It Li vendor
325Vendor ID.
326.El
327.Ss Notify matching
328A partial list of systems, subsystems, and types used within the
329.Ic notify
330mechanism.
331.Pp
332.Bl -tag -width ".Li coretemp" -compact
333.It Sy System
334.It Li ACPI
335Events related to the ACPI subsystem.
336.Bl -tag -width ".Sy Subsystem" -compact
337.It Sy Subsystem
338.It Li ACAD
339AC line state ($notify=0x00 is offline, 0x01 is online).
340.It Li Button
341Button state ($notify=0x00 is power, 0x01 is sleep).
342.It Li CMBAT
343Battery events.
344.It Li Lid
345Lid state ($notify=0x00 is closed, 0x01 is open).
346.It Li PROCESSOR
347Processor state/configuration ($notify=0x81 is a change in available Cx states).
348.It Li Resume
349Resume notification.
350.It Li Suspend
351Suspend notification.
352.It Li Thermal
353Thermal zone events.
354.El
355.Pp
356.It Li CARP
357Events related to the
358.Xr carp 4
359protocol.
360.Bl -tag -width ".Sy Subsystem" -compact
361.It Sy Subsystem
362.It Ar vhid@interface
363The
364.Dq subsystem
365contains the actual CARP vhid and the name of the network interface
366on which the event took place.
367.Bl -tag -width ".Li MASTER" -compact
368.It Sy Type
369.It Li MASTER
370Node become the master for a virtual host.
371.It Li BACKUP
372Node become the backup for a virtual host.
373.El
374.El
375.Pp
376.It Li IFNET
377Events related to the network subsystem.
378.Bl -tag -width ".Sy Subsystem" -compact
379.It Sy Subsystem
380.It Ar interface
381The
382.Dq subsystem
383is the actual name of the network interface on which the event
384took place.
385.Bl -tag -width ".Li LINK_DOWN" -compact
386.It Sy Type
387.It Li LINK_UP
388Carrier status changed to UP.
389.It Li LINK_DOWN
390Carrier status changed to DOWN.
391.It Li ATTACH
392The network interface is attached to the system.
393.It Li DETACH
394The network interface is detached from the system.
395.El
396.El
397.Pp
398.It Li DEVFS
399Events related to the
400.Xr devfs 5
401filesystem.
402.Bl -tag -width ".Sy Subsystem" -compact
403.It Sy Subsystem
404.It Li CDEV
405.Bl -tag -width ".Li DESTROY" -compact
406.It Sy Type
407.It Li CREATE
408The
409.Xr devfs 5
410node is created.
411.It Li DESTROY
412The
413.Xr devfs 5
414node is destroyed.
415.El
416.El
417.Pp
418.It Li GEOM
419Events related to the
420.Xr geom 4
421framework.
422The difference compared to
423.Li DEVFS
424is that
425.Li GEOM
426only includes disk-like devices.
427.Bl -tag -width ".Sy Subsystem" -compact
428.It Sy Subsystem
429.It Li DEV
430.Bl -tag -width ".Li MEDIACHANGE" -compact
431.It Sy Type
432.It Li CREATE
433A
434.Xr geom 4
435provider is created.
436.It Li DESTROY
437A
438.Xr geom 4
439provider is destroyed.
440.It Li GEOM::physpath
441The physical path of a device has changed.
442.It Li MEDIACHANGE
443Physical media has changed.
444.It Li SIZECHANGE
445A
446.Xr geom 4
447provider size has changed.
448.El
449.El
450.Pp
451.It Li RCTL
452Events related to the
453.Xr rctl 8
454framework.
455.Bl -tag -width ".Sy Subsystem" -compact
456.It Sy Subsystem
457.It Li rule
458.Bl -tag -width ".Li matched" -compact
459.It Sy Type
460.It Li matched
461A rule with action specified as "devctl" was triggered.
462.El
463.El
464.Pp
465.It Li USB
466Events related to the USB subsystem.
467.Bl -tag -width ".Sy Subsystem" -compact
468.It Sy Subsystem
469.It Li DEVICE
470.Bl -tag -width ".Li DETACH" -compact
471.It Sy Type
472.It Li ATTACH
473USB device is attached to the system.
474.It Li DETACH
475USB device is detached from the system.
476.El
477.It Li INTERFACE
478.Bl -tag -width ".Li DETACH" -compact
479.It Sy Type
480.It Li ATTACH
481USB interface is attached to a device.
482.It Li DETACH
483USB interface is detached from a device.
484.El
485.El
486.Pp
487.It Li coretemp
488Events related to the
489.Xr coretemp 4
490device.
491.Bl -tag -width ".Sy Subsystem" -compact
492.It Sy Subsystem
493.It Li Thermal
494Notification that the CPU core has reached critical temperature.
495.Bl -tag -width ".Ar temperature" -compact
496.It Sy Type
497.It Ar temperature
498String containing the temperature of the core that has become too hot.
499.El
500.El
501.Pp
502.It Li kern
503Events related to the kernel.
504.Bl -tag -width ".Sy Subsystem" -compact
505.It Sy Subsystem
506.It Li power
507.Bl -tag -width ".li resume" -compact
508.It Sy Type
509.It Li resume
510Notification that the system has woken from the suspended state.
511.El
512.El
513.Pp
514.It Li kernel
515More events related to the kernel.
516.Bl -tag -width ".Sy Subsystem" -compact
517.It Sy Subsystem
518.It Li signal
519.Bl -tag -width ".li resume" -compact
520.It Sy Type
521.It Li coredump
522Notification that a process has crashed and dumped core.
523.El
524.El
525.Pp
526.It Li CAM
527Events related to the
528.Xr cam 4
529system.
530.Bl -tag -width ".Sy Subsystem" -compact
531.It Sy Subsystem
532.It Li periph
533Events related to peripheral devices.
534.Bl -tag -width ".li timeout" -compact
535.It Sy Type
536.It Li error
537Generic errors.
538.It Li timeout
539Command timeouts.
540.El
541.El
542.El
543.Pp
544A link state change to UP on the interface
545.Dq Li fxp0
546would result in the following notify event:
547.Bd -literal -offset indent
548system=IFNET, subsystem=fxp0, type=LINK_UP
549.Ed
550.Pp
551An AC line state change to
552.Dq offline
553would result in the following event:
554.Bd -literal -offset indent
555system=ACPI, subsystem=ACAD, notify=0x00
556.Ed
557.Ss Comments
558Comments may appear anywhere that whitespace may appear in a
559configuration file.
560To appeal to programmers of all kinds, they can
561be written in C, C++, or shell/Perl constructs.
562.Pp
563C-style comments start with the two characters
564.Ql /*
565(slash, star) and end with
566.Ql */
567(star, slash).
568Because they are completely delimited with these characters,
569they can be used to comment only a portion of a line or to span
570multiple lines.
571.Pp
572C-style comments cannot be nested.
573For example, the following is
574not valid because the entire comment ends with the first
575.Ql */ :
576.Bd -literal -offset indent
577/* This is the start of a comment.
578   This is still part of the comment.
579/* This is an incorrect attempt at nesting a comment. */
580   This is no longer in any comment. */
581.Ed
582.Pp
583C++-style comments start with the two characters
584.Ql //
585(slash, slash) and continue to the end of the physical line.
586They cannot be continued across multiple physical lines; to have
587one logical comment span multiple lines, each line must use the
588.Ql //
589pair.
590For example:
591.Bd -literal -offset indent
592// This is the start of a comment.  The next line
593// is a new comment, even though it is logically
594// part of the previous comment.
595.Ed
596.Sh FILES
597.Bl -tag -width ".Pa /etc/devd.conf" -compact
598.It Pa /etc/devd.conf
599The
600.Xr devd 8
601configuration file.
602.El
603.Sh EXAMPLES
604.Bd -literal
605#
606# This will catch link down events on the interfaces fxp0 and ath0
607#
608notify 0 {
609	match "system"			"IFNET";
610	match "subsystem"		"(fxp0|ath0)";
611	match "type"			"LINK_DOWN";
612	action "logger $subsystem is DOWN";
613};
614
615#
616# Match lid open/close events
617# These can be combined to a single event, by passing the
618# value of $notify to the external script.
619#
620notify 0 {
621	match "system"			"ACPI";
622	match "subsystem"		"Lid";
623	match "notify"			"0x00";
624	action "logger Lid closed, we can sleep now!";
625};
626
627notify 0 {
628	match "system"			"ACPI";
629	match "subsystem"		"Lid";
630	match "notify"			"0x01";
631	action "logger Lid opened, the sleeper must awaken!";
632};
633
634#
635# Match a USB device type
636#
637notify 0 {
638	match "system"			"USB";
639	match "subsystem"		"INTERFACE";
640	match "type"			"ATTACH";
641	match "intclass"		"0x0e";
642	action "logger USB video device attached";
643};
644
645#
646# Try to configure ath and wi devices with pccard_ether
647# as they are attached.
648#
649attach 0 {
650        device-name "(ath|wi)[0-9]+";
651        action "/etc/pccard_ether $device-name start";
652};
653
654#
655# Stop ath and wi devices as they are detached from
656# the system.
657#
658detach 0 {
659        device-name "(ath|wi)[0-9]+";
660        action "/etc/pccard_ether $device-name stop";
661};
662.Ed
663.Pp
664The installed
665.Pa /etc/devd.conf
666has many additional examples.
667.Sh SEE ALSO
668.Xr cam 4 ,
669.Xr coretemp 4 ,
670.Xr devfs 5 ,
671.Xr re_format 7 ,
672.Xr devd 8
673