xref: /freebsd/sbin/devd/devd.8 (revision ec4deee4e4f2aef1b97d9424f25d04e91fd7dc10)
1.\"
2.\" Copyright (c) 2002 M. Warner Losh <imp@FreeBSD.org>
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
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.Dd October 5, 2016
28.Dt DEVD 8
29.Os
30.Sh NAME
31.Nm devd
32.Nd "device state change daemon"
33.Sh SYNOPSIS
34.Nm
35.Op Fl dnq
36.Op Fl f Ar file
37.Op Fl l Ar num
38.Sh DESCRIPTION
39The
40.Nm
41daemon provides a way to have userland programs run when certain
42kernel events happen.
43.Pp
44The following options are accepted.
45.Bl -tag -width ".Fl f Ar file"
46.It Fl d
47Run in the foreground instead of becoming a daemon and log additional information for debugging.
48.It Fl f Ar file
49Use configuration file
50.Ar file
51instead of the default
52.Pa /etc/devd.conf .
53If option
54.Fl f
55is specified more than once, the last file specified is used.
56.It Fl l Ar num
57Limit concurrent socket connections to
58.Ar num .
59The default connection limit is 10.
60.It Fl n
61Do not process all pending events before becoming a daemon.
62Instead, call daemon right away.
63.It Fl q
64Quiet mode.
65Only log messages at priority LOG_WARNING or above.
66.El
67.Sh IMPLEMENTATION NOTES
68The
69.Nm
70utility
71is a system daemon that runs in the background all the time.
72Whenever a device is added to or removed from the device tree,
73.Nm
74will execute actions specified in
75.Xr devd.conf 5 .
76For example,
77.Nm
78might execute
79.Xr dhclient 8
80when an Ethernet adapter is added to the system, and kill the
81.Xr dhclient 8
82instance when the same adapter is removed.
83Another example would be for
84.Nm
85to use a table to locate and load via
86.Xr kldload 8
87the proper driver for an unrecognized device that is added to the system.
88.Pp
89The
90.Nm
91utility
92hooks into the
93.Xr devctl 4
94device driver.
95This device driver has hooks into the device configuration system.
96When nodes are added or deleted from the tree, this device will
97deliver information about the event to
98.Nm .
99Once
100.Nm
101has parsed the message, it will search its action list for that kind
102of event and perform the action with the highest matching value.
103For most mundane uses, the default handlers are adequate.
104However, for more advanced users, the power is present to tweak every
105aspect of what happens.
106.Pp
107The
108.Nm
109utility
110reads
111.Pa /etc/devd.conf
112or the alternate configuration file specified with a
113.Fl f
114option and uses that file to drive the rest of the process.
115While the format of this file is described in
116.Xr devd.conf 5 ,
117some basics are covered here.
118In the
119.Ic options
120section, one can define multiple directories to search
121for config files.
122All files in these directories whose names match the pattern
123.Pa *.conf
124are parsed.
125These files are intended to be installed by third party vendors that
126wish to hook into the
127.Nm
128system without modifying the user's other
129config files.
130.Pp
131Since
132.Xr devctl 4
133allows only one active reader,
134.Nm
135multiplexes it, forwarding all events to any number of connected clients.
136Clients connect by opening the SOCK_SEQPACKET
137.Ux
138domain socket at
139.Pa /var/run/devd.seqpacket.pipe .
140.Sh FILES
141.Bl -tag -width ".Pa /var/run/devd.seqpacket.pipe" -compact
142.It Pa /etc/devd.conf
143The default
144.Nm
145configuration file.
146.It Pa /var/run/devd.seqpacket.pipe
147The socket used by
148.Nm
149to communicate with its clients.
150.It Pa /var/run/devd.pipe
151A deprecated socket retained for use with old clients.
152.El
153.Sh SEE ALSO
154.Xr devctl 4 ,
155.Xr devd.conf 5
156.Sh HISTORY
157The
158.Nm
159utility first appeared in
160.Fx 5.0 .
161.Sh AUTHORS
162.An M. Warner Losh
163