| 1 |
'\" t |
| 2 |
.TH "SYSTEMD\&.DEVICE" "5" "" "systemd 261~rc3" "systemd.device" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
systemd.device \- Device unit configuration |
| 24 |
.SH "SYNOPSIS" |
| 25 |
.PP |
| 26 |
\fIdevice\fR\&.device |
| 27 |
.SH "DESCRIPTION" |
| 28 |
.PP |
| 29 |
A unit configuration file whose name ends in |
| 30 |
"\&.device" |
| 31 |
encodes information about a device unit as exposed in the sysfs/\fBudev\fR(7) |
| 32 |
device tree\&. This may be used to define dependencies between devices and other units\&. |
| 33 |
.PP |
| 34 |
This unit type has no specific options\&. See |
| 35 |
\fBsystemd.unit\fR(5) |
| 36 |
for the common options of all unit configuration files\&. The common configuration items are configured in the generic [Unit] and [Install] sections\&. A separate [Device] section does not exist, since no device\-specific options may be configured\&. |
| 37 |
.PP |
| 38 |
systemd will dynamically create device units for all kernel devices that are marked with the |
| 39 |
"systemd" |
| 40 |
udev tag (by default all block and network devices, and a few others)\&. Note that |
| 41 |
\fIif \fR\fIsystemd\-udevd\&.service\fR\fI is not running, no device units will be available (for example in a typical container)\fR\&. |
| 42 |
.PP |
| 43 |
Device units are named after the |
| 44 |
/sys/ |
| 45 |
and |
| 46 |
/dev/ |
| 47 |
paths they control\&. Example: the device |
| 48 |
/dev/sda5 |
| 49 |
is exposed in systemd as |
| 50 |
dev\-sda5\&.device\&. For details about the escaping logic used to convert a file system path to a unit name see |
| 51 |
\fBsystemd.unit\fR(5)\&. |
| 52 |
.PP |
| 53 |
To tag a udev device, use |
| 54 |
"TAG+="systemd"" |
| 55 |
in the udev rules file, see |
| 56 |
\fBudev\fR(7) |
| 57 |
for details\&. |
| 58 |
.PP |
| 59 |
Device units will be reloaded by systemd whenever the corresponding device generates a |
| 60 |
"changed" |
| 61 |
event\&. Other units can use |
| 62 |
\fIReloadPropagatedFrom=\fR |
| 63 |
to react to that event\&. |
| 64 |
.SH "AUTOMATIC DEPENDENCIES" |
| 65 |
.SS "Implicit Dependencies" |
| 66 |
.PP |
| 67 |
Many unit types automatically acquire dependencies on device units of devices they require\&. For example, |
| 68 |
\&.socket |
| 69 |
unit acquire dependencies on the device units of the network interface specified in |
| 70 |
\fIBindToDevice=\fR\&. Similar, swap and mount units acquire dependencies on the units encapsulating their backing block devices\&. |
| 71 |
.SS "Default Dependencies" |
| 72 |
.PP |
| 73 |
There are no default dependencies for device units\&. |
| 74 |
.SH "THE UDEV DATABASE" |
| 75 |
.PP |
| 76 |
Unit settings of device units may either be configured via unit files, or directly from the udev database\&. The following udev device properties are understood by the service manager: |
| 77 |
.PP |
| 78 |
\fISYSTEMD_WANTS=\fR, \fISYSTEMD_USER_WANTS=\fR |
| 79 |
.RS 4 |
| 80 |
Adds dependencies of type |
| 81 |
\fIWants=\fR |
| 82 |
from the device unit to the specified units\&. |
| 83 |
\fISYSTEMD_WANTS=\fR |
| 84 |
is read by the system service manager, |
| 85 |
\fISYSTEMD_USER_WANTS=\fR |
| 86 |
by user service manager instances\&. These properties may be used to activate arbitrary units when a specific device becomes available\&. |
| 87 |
.sp |
| 88 |
Note that this and the other udev device properties are not taken into account unless the device is tagged with the |
| 89 |
"systemd" |
| 90 |
tag in the udev database, because otherwise the device is not exposed as a systemd unit (see above)\&. |
| 91 |
.sp |
| 92 |
Note that systemd will only act on |
| 93 |
\fIWants=\fR |
| 94 |
dependencies when a device first becomes active\&. It will not act on them if they are added to devices that are already active\&. Use |
| 95 |
\fISYSTEMD_READY=\fR |
| 96 |
(see below) to configure when a udev device shall be considered active, and thus when to trigger the dependencies\&. |
| 97 |
.sp |
| 98 |
The specified property value should be a space\-separated list of valid unit names\&. If a unit template name is specified (that is, a unit name containing an |
| 99 |
"@" |
| 100 |
character indicating a unit name to use for multiple instantiation, but with an empty instance name following the |
| 101 |
"@"), it will be automatically instantiated by the device\*(Aqs |
| 102 |
"sysfs" |
| 103 |
path (that is: the path is escaped and inserted as instance name into the template unit name)\&. This is useful in order to instantiate a specific template unit once for each device that appears and matches specific properties\&. |
| 104 |
.RE |
| 105 |
.PP |
| 106 |
\fISYSTEMD_ALIAS=\fR |
| 107 |
.RS 4 |
| 108 |
Adds an additional alias name to the device unit\&. This must be an absolute path that is automatically transformed into a unit name\&. (See above\&.) |
| 109 |
.RE |
| 110 |
.PP |
| 111 |
\fISYSTEMD_READY=\fR |
| 112 |
.RS 4 |
| 113 |
If set to 0, systemd will consider this device unplugged even if it shows up in the udev tree\&. If this property is unset or set to 1, the device will be considered plugged if it is visible in the udev tree\&. |
| 114 |
.sp |
| 115 |
This option is useful for devices that initially show up in an uninitialized state in the tree, and for which a |
| 116 |
"changed" |
| 117 |
event is generated the moment they are fully set up\&. Note that |
| 118 |
\fISYSTEMD_WANTS=\fR |
| 119 |
(see above) is not acted on as long as |
| 120 |
\fISYSTEMD_READY=0\fR |
| 121 |
is set for a device\&. |
| 122 |
.RE |
| 123 |
.PP |
| 124 |
\fIID_MODEL_FROM_DATABASE=\fR, \fIID_MODEL=\fR |
| 125 |
.RS 4 |
| 126 |
If set, this property is used as description string for the device unit\&. |
| 127 |
.RE |
| 128 |
.SH "OPTIONS" |
| 129 |
.PP |
| 130 |
Device unit files may include [Unit] and [Install] sections, which are described in |
| 131 |
\fBsystemd.unit\fR(5)\&. No options specific to this file type are supported\&. |
| 132 |
.SH "SEE ALSO" |
| 133 |
.PP |
| 134 |
\fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd.unit\fR(5), \fBudev\fR(7), \fBsystemd.directives\fR(7) |