diff options
Diffstat (limited to 'man/systemd.device.xml')
| -rw-r--r-- | man/systemd.device.xml | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/man/systemd.device.xml b/man/systemd.device.xml new file mode 100644 index 0000000..529552e --- /dev/null +++ b/man/systemd.device.xml @@ -0,0 +1,171 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="systemd.device"> + <refentryinfo> + <title>systemd.device</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.device</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.device</refname> + <refpurpose>Device unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>device</replaceable>.device</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in <literal>.device</literal> encodes information about a + device unit as exposed in the + sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> device + tree. This may be used to define dependencies between devices and other units.</para> + + <para>This unit type has no specific options. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + 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.</para> + + <para>systemd will dynamically create device units for all kernel devices that are marked with the + <literal>systemd</literal> udev tag (by default all block and network devices, and a few others). Note + that <emphasis>if <filename>systemd-udevd.service</filename> is not running, no device units will be + available (for example in a typical container)</emphasis>.</para> + + <para>Device units are named after the <filename>/sys/</filename> + and <filename>/dev/</filename> paths they control. Example: the + device <filename index="false">/dev/sda5</filename> is exposed in + systemd as <filename>dev-sda5.device</filename>. For details about + the escaping logic used to convert a file system path to a unit + name see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>To tag a udev device, use <literal>TAG+="systemd"</literal> in the udev rules file, see + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details. + </para> + + <para>Device units will be reloaded by systemd whenever the + corresponding device generates a <literal>changed</literal> event. + Other units can use <varname>ReloadPropagatedFrom=</varname> to react + to that event.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <refsect2> + <title>Implicit Dependencies</title> + + <para>Many unit types automatically acquire dependencies on device + units of devices they require. For example, + <filename>.socket</filename> unit acquire dependencies on the + device units of the network interface specified in + <varname>BindToDevice=</varname>. Similar, swap and mount units + acquire dependencies on the units encapsulating their backing + block devices.</para> + </refsect2> + + <refsect2> + <title>Default Dependencies</title> + + <para>There are no default dependencies for device units.</para> + </refsect2> + </refsect1> + + <refsect1> + <title>The udev Database</title> + + <para>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:</para> + + <variablelist class='udev-directives'> + <varlistentry> + <term><varname>SYSTEMD_WANTS=</varname></term> + <term><varname>SYSTEMD_USER_WANTS=</varname></term> + <listitem><para>Adds dependencies of type <varname>Wants=</varname> from the device unit to the specified + units. <varname>SYSTEMD_WANTS=</varname> is read by the system service manager, + <varname>SYSTEMD_USER_WANTS=</varname> by user service manager instances. These properties may be used to + activate arbitrary units when a specific device becomes available.</para> + + <para>Note that this and the other udev device properties are not taken into account unless the device is + tagged with the <literal>systemd</literal> tag in the udev database, because otherwise the device is not + exposed as a systemd unit (see above).</para> + + <para>Note that systemd will only act on <varname>Wants=</varname> dependencies when a device first becomes + active. It will not act on them if they are added to devices that are already active. Use + <varname>SYSTEMD_READY=</varname> (see below) to configure when a udev device shall be considered active, and + thus when to trigger the dependencies.</para> + + <!-- Note that we don't document here that we actually apply unit_name_mangle() to all specified names, since + that's kinda ugly, and people should instead specify correctly escaped names --> + + <para>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 <literal>@</literal> character indicating a unit name to + use for multiple instantiation, but with an empty instance name following the <literal>@</literal>), it will be + automatically instantiated by the device's <literal>sysfs</literal> 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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_ALIAS=</varname></term> + <listitem><para>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.)</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SYSTEMD_READY=</varname></term> + <listitem><para>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.</para> + + <para>This option is useful for devices that initially show up in an uninitialized state in the tree, and for + which a <literal>changed</literal> event is generated the moment they are fully set up. Note that + <varname>SYSTEMD_WANTS=</varname> (see above) is not acted on as long as <varname>SYSTEMD_READY=0</varname> is + set for a device.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_MODEL_FROM_DATABASE=</varname></term> + <term><varname>ID_MODEL=</varname></term> + + <listitem><para>If set, this property is used as description + string for the device unit.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Device unit files may include [Unit] and [Install] sections, which are described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. No + options specific to this file type are supported.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |