chiark / gitweb /
machined: optionally, allow registration of pre-existing units (scopes
[elogind.git] / 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                                 <term><varname>SYSTEMD_USER_WANTS=</varname></term>
106                                 <listitem><para>Adds dependencies of
107                                 type <varname>Wants</varname> from the
108                                 device unit to all listed units. The
109                                 first form is used by the system
110                                 systemd instance, the second by user
111                                 systemd instances. Those settings may
112                                 be used to activate arbitrary units
113                                 when a specific device becomes
114                                 available.</para>
115
116                                 <para>Note that this and the
117                                 other tags are not taken into account
118                                 unless the device is tagged with the
119                                 <literal>systemd</literal> string in
120                                 the udev database, because otherwise
121                                 the device is not exposed as a systemd
122                                 unit (see above).</para>
123
124                                 <para>Note that systemd will only act
125                                 on <varname>Wants</varname>
126                                 dependencies when a device first
127                                 becomes active. It will not act on
128                                 them if they are added to devices that
129                                 are already active. Use
130                                 <varname>SYSTEMD_READY=</varname> (see
131                                 below) to influence on which udev
132                                 event to trigger the dependencies.
133                                 </para></listitem>
134                         </varlistentry>
135
136                         <varlistentry>
137                                 <term><varname>SYSTEMD_ALIAS=</varname></term>
138                                 <listitem><para>Adds an additional
139                                 alias name to the device unit. This
140                                 must be an absolute path that is
141                                 automatically transformed into a unit
142                                 name. (See above.)</para></listitem>
143                         </varlistentry>
144
145                         <varlistentry>
146                                 <term><varname>SYSTEMD_READY=</varname></term>
147                                 <listitem><para>If set to 0, systemd
148                                 will consider this device unplugged
149                                 even if it shows up in the udev
150                                 tree. If this property is unset or set
151                                 to 1, the device will be considered
152                                 plugged if it is visible in the
153                                 udev tree. This property has no
154                                 influence on the behavior when a
155                                 device disappears from the udev
156                                 tree.</para>
157
158                                 <para>This option is useful to support
159                                 devices that initially show up in an
160                                 uninitialized state in the tree, and
161                                 for which a <literal>changed</literal>
162                                 event is generated the moment they are
163                                 fully set up. Note that
164                                 <varname>SYSTEMD_WANTS=</varname> (see
165                                 above) is not acted on as long as
166                                 <varname>SYSTEMD_READY=0</varname> is
167                                 set for a device.</para></listitem>
168                         </varlistentry>
169
170                         <varlistentry>
171                                 <term><varname>ID_MODEL_FROM_DATABASE=</varname></term>
172                                 <term><varname>ID_MODEL=</varname></term>
173
174                                 <listitem><para>If set, this property is
175                                 used as description string for the
176                                 device unit.</para></listitem>
177                         </varlistentry>
178
179                 </variablelist>
180
181
182         </refsect1>
183
184         <refsect1>
185                   <title>See Also</title>
186                   <para>
187                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
188                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
189                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
190                           <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
191                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
192                   </para>
193         </refsect1>
194
195 </refentry>