sbin/devd/devd.8

   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. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd October 5, 2016
  29 .Dt DEVD 8
  30 .Os
  31 .Sh NAME
  32 .Nm devd
  33 .Nd "device state change daemon"
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl dnq
  37 .Op Fl f Ar file
  38 .Op Fl l Ar num
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 daemon provides a way to have userland programs run when certain
  43 kernel events happen.
  44 .Pp
  45 The following options are accepted.
  46 .Bl -tag -width ".Fl f Ar file"
  47 .It Fl d
  48 Run in the foreground instead of becoming a daemon and log additional information for debugging.
  49 .It Fl f Ar file
  50 Use configuration file
  51 .Ar file
  52 instead of the default
  53 .Pa /etc/devd.conf .
  54 If option
  55 .Fl f
  56 is specified more than once, the last file specified is used.
  57 .It Fl l Ar num
  58 Limit concurrent socket connections to
  59 .Ar num .
  60 The default connection limit is 10.
  61 .It Fl n
  62 Do not process all pending events before becoming a daemon.
  63 Instead, call daemon right away.
  64 .It Fl q
  65 Quiet mode.
  66 Only log messages at priority LOG_WARNING or above.
  67 .El
  68 .Sh IMPLEMENTATION NOTES
  69 The
  70 .Nm
  71 utility
  72 is a system daemon that runs in the background all the time.
  73 Whenever a device is added to or removed from the device tree,
  74 .Nm
  75 will execute actions specified in
  76 .Xr devd.conf 5 .
  77 For example,
  78 .Nm
  79 might execute
  80 .Xr dhclient 8
  81 when an Ethernet adapter is added to the system, and kill the
  82 .Xr dhclient 8
  83 instance when the same adapter is removed.
  84 Another example would be for
  85 .Nm
  86 to use a table to locate and load via
  87 .Xr kldload 8
  88 the proper driver for an unrecognized device that is added to the system.
  89 .Pp
  90 The
  91 .Nm
  92 utility
  93 hooks into the
  94 .Xr devctl 4
  95 device driver.
  96 This device driver has hooks into the device configuration system.
  97 When nodes are added or deleted from the tree, this device will
  98 deliver information about the event to
  99 .Nm .
 100 Once
 101 .Nm
 102 has parsed the message, it will search its action list for that kind
 103 of event and perform the action with the highest matching value.
 104 For most mundane uses, the default handlers are adequate.
 105 However, for more advanced users, the power is present to tweak every
 106 aspect of what happens.
 107 .Pp
 108 The
 109 .Nm
 110 utility
 111 reads
 112 .Pa /etc/devd.conf
 113 or the alternate configuration file specified with a
 114 .Fl f
 115 option and uses that file to drive the rest of the process.
 116 While the format of this file is described in
 117 .Xr devd.conf 5 ,
 118 some basics are covered here.
 119 In the
 120 .Ic options
 121 section, one can define multiple directories to search
 122 for config files.
 123 All files in these directories whose names match the pattern
 124 .Pa *.conf
 125 are parsed.
 126 These files are intended to be installed by third party vendors that
 127 wish to hook into the
 128 .Nm
 129 system without modifying the user's other
 130 config files.
 131 .Pp
 132 Since
 133 .Xr devctl 4
 134 allows only one active reader,
 135 .Nm
 136 multiplexes it, forwarding all events to any number of connected clients.
 137 Clients connect by opening the SOCK_SEQPACKET
 138 .Ux
 139 domain socket at
 140 .Pa /var/run/devd.seqpacket.pipe .
 141 .Sh FILES
 142 .Bl -tag -width ".Pa /var/run/devd.seqpacket.pipe" -compact
 143 .It Pa /etc/devd.conf
 144 The default
 145 .Nm
 146 configuration file.
 147 .It Pa /var/run/devd.seqpacket.pipe
 148 The socket used by
 149 .Nm
 150 to communicate with its clients.
 151 .It Pa /var/run/devd.pipe
 152 A deprecated socket retained for use with old clients.
 153 .El
 154 .Sh SEE ALSO
 155 .Xr devctl 4 ,
 156 .Xr devd.conf 5
 157 .Sh HISTORY
 158 The
 159 .Nm
 160 utility first appeared in
 161 .Fx 5.0 .
 162 .Sh AUTHORS
 163 .An M. Warner Losh