man/systemd.device.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd.device">
   7   <refentryinfo>
   8     <title>systemd.device</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>systemd.device</refentrytitle>
  14     <manvolnum>5</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>systemd.device</refname>
  19     <refpurpose>Device unit configuration</refpurpose>
  20   </refnamediv>
  21
  22   <refsynopsisdiv>
  23     <para><filename><replaceable>device</replaceable>.device</filename></para>
  24   </refsynopsisdiv>
  25
  26   <refsect1>
  27     <title>Description</title>
  28
  29     <para>A unit configuration file whose name ends in <literal>.device</literal> encodes information about a
  30     device unit as exposed in the
  31     sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> device
  32     tree. This may be used to define dependencies between devices and other units.</para>
  33
  34     <para>This unit type has no specific options. See
  35     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  36     for the common options of all unit configuration files. The common
  37     configuration items are configured in the generic
  38     [Unit] and [Install]
  39     sections. A separate [Device] section does not
  40     exist, since no device-specific options may be configured.</para>
  41
  42     <para>systemd will dynamically create device units for all kernel devices that are marked with the
  43     <literal>systemd</literal> udev tag (by default all block and network devices, and a few others). Note
  44     that <emphasis>if <filename>systemd-udevd.service</filename> is not running, no device units will be
  45     available (for example in a typical container)</emphasis>.</para>
  46
  47     <para>Device units are named after the <filename>/sys/</filename>
  48     and <filename>/dev/</filename> paths they control. Example: the
  49     device <filename index="false">/dev/sda5</filename> is exposed in
  50     systemd as <filename>dev-sda5.device</filename>. For details about
  51     the escaping logic used to convert a file system path to a unit
  52     name see
  53     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  54
  55     <para>To tag a udev device, use <literal>TAG+="systemd"</literal> in the udev rules file, see
  56     <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details.
  57     </para>
  58
  59     <para>Device units will be reloaded by systemd whenever the
  60     corresponding device generates a <literal>changed</literal> event.
  61     Other units can use <varname>ReloadPropagatedFrom=</varname> to react
  62     to that event.</para>
  63   </refsect1>
  64
  65   <refsect1>
  66     <title>Automatic Dependencies</title>
  67
  68     <refsect2>
  69       <title>Implicit Dependencies</title>
  70
  71       <para>Many unit types automatically acquire dependencies on device
  72       units of devices they require. For example,
  73       <filename>.socket</filename> unit acquire dependencies on the
  74       device units of the network interface specified in
  75       <varname>BindToDevice=</varname>. Similar, swap and mount units
  76       acquire dependencies on the units encapsulating their backing
  77       block devices.</para>
  78     </refsect2>
  79
  80     <refsect2>
  81       <title>Default Dependencies</title>
  82
  83       <para>There are no default dependencies for device units.</para>
  84     </refsect2>
  85   </refsect1>
  86
  87   <refsect1>
  88     <title>The udev Database</title>
  89
  90     <para>Unit settings of device units may either be configured via unit files, or directly from the udev
  91     database. The following udev device properties are understood by the service manager:</para>
  92
  93     <variablelist class='udev-directives'>
  94       <varlistentry>
  95         <term><varname>SYSTEMD_WANTS=</varname></term>
  96         <term><varname>SYSTEMD_USER_WANTS=</varname></term>
  97         <listitem><para>Adds dependencies of type <varname>Wants=</varname> from the device unit to the specified
  98         units. <varname>SYSTEMD_WANTS=</varname> is read by the system service manager,
  99         <varname>SYSTEMD_USER_WANTS=</varname> by user service manager instances. These properties may be used to
 100         activate arbitrary units when a specific device becomes available.</para>
 101
 102         <para>Note that this and the other udev device properties are not taken into account unless the device is
 103         tagged with the <literal>systemd</literal> tag in the udev database, because otherwise the device is not
 104         exposed as a systemd unit (see above).</para>
 105
 106         <para>Note that systemd will only act on <varname>Wants=</varname> dependencies when a device first becomes
 107         active. It will not act on them if they are added to devices that are already active. Use
 108         <varname>SYSTEMD_READY=</varname> (see below) to configure when a udev device shall be considered active, and
 109         thus when to trigger the dependencies.</para>
 110
 111         <!-- Note that we don't document here that we actually apply unit_name_mangle() to all specified names, since
 112              that's kinda ugly, and people should instead specify correctly escaped names -->
 113
 114         <para>The specified property value should be a space-separated list of valid unit names. If a unit template
 115         name is specified (that is, a unit name containing an <literal>@</literal> character indicating a unit name to
 116         use for multiple instantiation, but with an empty instance name following the <literal>@</literal>), it will be
 117         automatically instantiated by the device's <literal>sysfs</literal> path (that is: the path is escaped and
 118         inserted as instance name into the template unit name). This is useful in order to instantiate a specific
 119         template unit once for each device that appears and matches specific properties.</para></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><varname>SYSTEMD_ALIAS=</varname></term>
 124         <listitem><para>Adds an additional alias name to the device
 125         unit. This must be an absolute path that is automatically
 126         transformed into a unit name. (See above.)</para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><varname>SYSTEMD_READY=</varname></term>
 131         <listitem><para>If set to 0, systemd will consider this device unplugged even if it shows up in the udev
 132         tree. If this property is unset or set to 1, the device will be considered plugged if it is visible in the udev
 133         tree.</para>
 134
 135         <para>This option is useful for devices that initially show up in an uninitialized state in the tree, and for
 136         which a <literal>changed</literal> event is generated the moment they are fully set up. Note that
 137         <varname>SYSTEMD_WANTS=</varname> (see above) is not acted on as long as <varname>SYSTEMD_READY=0</varname> is
 138         set for a device.</para></listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term><varname>ID_MODEL_FROM_DATABASE=</varname></term>
 143         <term><varname>ID_MODEL=</varname></term>
 144
 145         <listitem><para>If set, this property is used as description
 146         string for the device unit.</para></listitem>
 147       </varlistentry>
 148
 149     </variablelist>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Options</title>
 154
 155     <para>Device unit files may include [Unit] and [Install] sections, which are described in
 156     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. No
 157     options specific to this file type are supported.</para>
 158   </refsect1>
 159
 160   <refsect1>
 161       <title>See Also</title>
 162       <para>
 163         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 164         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 165         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 166         <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 167         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 168       </para>
 169   </refsect1>
 170
 171 </refentry>