man/systemd.device.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7   This file is part of systemd.
   8
   9   Copyright 2010 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24
  25 <refentry id="systemd.device">
  26         <refentryinfo>
  27                 <title>systemd.device</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>systemd.device</refentrytitle>
  42                 <manvolnum>5</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemd.device</refname>
  47                 <refpurpose>Device unit configuration</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <para><filename><replaceable>device</replaceable>.device</filename></para>
  52         </refsynopsisdiv>
  53
  54         <refsect1>
  55                 <title>Description</title>
  56
  57                 <para>A unit configuration file whose name ends in
  58                 <literal>.device</literal> encodes information about
  59                 a device unit as exposed in the
  60                 sysfs/<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  61                 device tree.</para>
  62
  63                 <para>This unit type has no specific options. See
  64                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  65                 for the common options of all unit configuration
  66                 files. The common configuration items are configured
  67                 in the generic <literal>[Unit]</literal> and
  68                 <literal>[Install]</literal> sections. A separate
  69                 <literal>[Device]</literal> section does not exist,
  70                 since no device-specific options may be
  71                 configured.</para>
  72
  73                 <para>systemd will dynamically create device units for
  74                 all kernel devices that are marked with the "systemd"
  75                 udev tag (by default all block and network devices,
  76                 and a few others). This may be used to define
  77                 dependencies between devices and other units. To tag a
  78                 udev device use <literal>TAG+="systemd"</literal> in
  79                 the udev rules file, see
  80                 <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  81                 for details.</para>
  82
  83                 <para>Device units are named after the
  84                 <filename>/sys</filename> and
  85                 <filename>/dev</filename> paths they control. Example:
  86                 the device <filename noindex='true'>/dev/sda5</filename> is exposed
  87                 in systemd as <filename>dev-sda5.device</filename>. For
  88                 details about the escaping logic used to convert a
  89                 file system path to a unit name see
  90                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  91
  92         </refsect1>
  93
  94         <refsect1>
  95                 <title>The udev Database</title>
  96
  97                 <para>The settings of device units may either be
  98                 configured via unit files, or directly from the udev
  99                 database (which is recommended). The following udev device
 100                 properties are understood by systemd:</para>
 101
 102                 <variablelist class='udev-directives'>
 103                         <varlistentry>
 104                                 <term><varname>SYSTEMD_WANTS=</varname></term>
 105                                 <listitem><para>Adds dependencies of
 106                                 type <varname>Wants</varname> from
 107                                 the device unit to all listed units. This
 108                                 may be used to activate arbitrary
 109                                 units when a specific device becomes
 110                                 available. Note that this and the
 111                                 other tags are not taken into account
 112                                 unless the device is tagged with the
 113                                 <literal>systemd</literal> string in
 114                                 the udev database, because otherwise
 115                                 the device is not exposed as systemd
 116                                 unit (see above). Note that systemd
 117                                 will only act on
 118                                 <varname>Wants</varname> dependencies
 119                                 when a device first becomes active, it
 120                                 will not act on them if they are added
 121                                 to devices that are already
 122                                 active. Use
 123                                 <varname>SYSTEMD_READY=</varname> (see
 124                                 below) to influence on which udev
 125                                 event to trigger the device
 126                                 dependencies.</para></listitem>
 127                         </varlistentry>
 128
 129                         <varlistentry>
 130                                 <term><varname>SYSTEMD_ALIAS=</varname></term>
 131                                 <listitem><para>Adds an additional
 132                                 alias name to the device unit. This
 133                                 must be an absolute path that is
 134                                 automatically transformed into a unit
 135                                 name. (See above.)</para></listitem>
 136                         </varlistentry>
 137
 138                         <varlistentry>
 139                                 <term><varname>SYSTEMD_READY=</varname></term>
 140                                 <listitem><para>If set to 0, systemd
 141                                 will consider this device unplugged
 142                                 even if it shows up in the udev
 143                                 tree. If this property is unset or set
 144                                 to 1, the device will be considered
 145                                 plugged the moment it shows up in the
 146                                 udev tree. This property has no
 147                                 influence on the behavior when a
 148                                 device disappears from the udev
 149                                 tree. This option is useful to support
 150                                 devices that initially show up in an
 151                                 uninitialized state in the tree, and
 152                                 for which a <literal>changed</literal>
 153                                 event is generated the moment they are
 154                                 fully set up. Note that
 155                                 <varname>SYSTEMD_WANTS=</varname> (see
 156                                 above) is not acted on as long as
 157                                 <varname>SYSTEMD_READY=0</varname> is
 158                                 set for a device.</para></listitem>
 159                         </varlistentry>
 160
 161                         <varlistentry>
 162                                 <term><varname>ID_MODEL_FROM_DATABASE=</varname></term>
 163                                 <term><varname>ID_MODEL=</varname></term>
 164
 165                                 <listitem><para>If set, this property is
 166                                 used as description string for the
 167                                 device unit.</para></listitem>
 168                         </varlistentry>
 169
 170                 </variablelist>
 171
 172
 173         </refsect1>
 174
 175         <refsect1>
 176                   <title>See Also</title>
 177                   <para>
 178                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 179                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 180                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 181                           <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 182                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 183                   </para>
 184         </refsect1>
 185
 186 </refentry>