man/systemd.device.xml

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