chiark / gitweb /
include <poll.h> instead of <sys/poll.h>
[elogind.git] / man / systemd.unit.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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
5 %entities;
6 ]>
7
8 <!--
9   This file is part of systemd.
10
11   Copyright 2010 Lennart Poettering
12
13   systemd is free software; you can redistribute it and/or modify it
14   under the terms of the GNU Lesser General Public License as published by
15   the Free Software Foundation; either version 2.1 of the License, or
16   (at your option) any later version.
17
18   systemd is distributed in the hope that it will be useful, but
19   WITHOUT ANY WARRANTY; without even the implied warranty of
20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21   Lesser General Public License for more details.
22
23   You should have received a copy of the GNU Lesser General Public License
24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
25 -->
26
27 <refentry id="systemd.unit">
28
29   <refentryinfo>
30     <title>systemd.unit</title>
31     <productname>systemd</productname>
32
33     <authorgroup>
34       <author>
35         <contrib>Developer</contrib>
36         <firstname>Lennart</firstname>
37         <surname>Poettering</surname>
38         <email>lennart@poettering.net</email>
39       </author>
40     </authorgroup>
41   </refentryinfo>
42
43   <refmeta>
44     <refentrytitle>systemd.unit</refentrytitle>
45     <manvolnum>5</manvolnum>
46   </refmeta>
47
48   <refnamediv>
49     <refname>systemd.unit</refname>
50     <refpurpose>Unit configuration</refpurpose>
51   </refnamediv>
52
53   <refsynopsisdiv>
54     <para><filename><replaceable>service</replaceable>.service</filename>,
55     <filename><replaceable>socket</replaceable>.socket</filename>,
56     <filename><replaceable>device</replaceable>.device</filename>,
57     <filename><replaceable>mount</replaceable>.mount</filename>,
58     <filename><replaceable>automount</replaceable>.automount</filename>,
59     <filename><replaceable>swap</replaceable>.swap</filename>,
60     <filename><replaceable>target</replaceable>.target</filename>,
61     <filename><replaceable>path</replaceable>.path</filename>,
62     <filename><replaceable>timer</replaceable>.timer</filename>,
63     <filename><replaceable>snapshot</replaceable>.snapshot</filename>,
64     <filename><replaceable>slice</replaceable>.slice</filename>,
65     <filename><replaceable>scope</replaceable>.scope</filename></para>
66
67     <para><literallayout><filename>/etc/systemd/system/*</filename>
68 <filename>/run/systemd/system/*</filename>
69 <filename>/usr/lib/systemd/system/*</filename>
70 <filename>...</filename>
71     </literallayout></para>
72
73     <para><literallayout><filename>$XDG_CONFIG_HOME/systemd/user/*</filename>
74 <filename>$HOME/.config/systemd/user/*</filename>
75 <filename>/etc/systemd/user/*</filename>
76 <filename>$XDG_RUNTIME_DIR/systemd/user/*</filename>
77 <filename>/run/systemd/user/*</filename>
78 <filename>$XDG_DATA_HOME/systemd/user/*</filename>
79 <filename>$HOME/.local/share/systemd/user/*</filename>
80 <filename>/usr/lib/systemd/user/*</filename>
81 <filename>...</filename>
82     </literallayout></para>
83   </refsynopsisdiv>
84
85   <refsect1>
86     <title>Description</title>
87
88     <para>A unit configuration file encodes information about a
89     service, a socket, a device, a mount point, an automount point, a
90     swap file or partition, a start-up target, a watched file system
91     path, a timer controlled and supervised by
92     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
93     a temporary system state snapshot, a resource management slice or
94     a group of externally created processes. The syntax is inspired by
95     <ulink
96     url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
97     Desktop Entry Specification</ulink> <filename>.desktop</filename>
98     files, which are in turn inspired by Microsoft Windows
99     <filename>.ini</filename> files.</para>
100
101     <para>This man page lists the common configuration options of all
102     the unit types. These options need to be configured in the [Unit]
103     or [Install] sections of the unit files.</para>
104
105     <para>In addition to the generic [Unit] and [Install] sections
106     described here, each unit may have a type-specific section, e.g.
107     [Service] for a service unit. See the respective man pages for
108     more information:
109     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
110     <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
111     <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
112     <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
113     <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
114     <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
115     <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
116     <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
117     <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
118     <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
119     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
120     <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
121     </para>
122
123     <para>Various settings are allowed to be specified more than once,
124     in which case the interpretation depends on the setting. Often,
125     multiple settings form a list, and setting to an empty value
126     "resets", which means that previous assignments are ignored. When
127     this is allowed, it is mentioned in the description of the
128     setting. Note that using multiple assignments to the same value
129     makes the unit file incompatible with parsers for the XDG
130     <filename>.desktop</filename> file format.</para>
131
132     <para>Unit files are loaded from a set of paths determined during
133     compilation, described in the next section.</para>
134
135     <para>Unit files may contain additional options on top of those
136     listed here. If systemd encounters an unknown option, it will
137     write a warning log message but continue loading the unit. If an
138     option or section name is prefixed with <option>X-</option>, it is
139     ignored completely by systemd. Options within an ignored section
140     do not need the prefix. Applications may use this to include
141     additional information in the unit files.</para>
142
143     <para>Boolean arguments used in unit files can be written in
144     various formats. For positive settings the strings
145     <option>1</option>, <option>yes</option>, <option>true</option>
146     and <option>on</option> are equivalent. For negative settings, the
147     strings <option>0</option>, <option>no</option>,
148     <option>false</option> and <option>off</option> are
149     equivalent.</para>
150
151     <para>Time span values encoded in unit files can be written in
152     various formats. A stand-alone number specifies a time in seconds.
153     If suffixed with a time unit, the unit is honored. A concatenation
154     of multiple values with units is supported, in which case the
155     values are added up. Example: "50" refers to 50 seconds; "2min
156     200ms" refers to 2 minutes plus 200 milliseconds, i.e. 120200ms.
157     The following time units are understood: s, min, h, d, w, ms, us.
158     For details see
159     <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
160
161     <para>Empty lines and lines starting with # or ; are
162     ignored. This may be used for commenting. Lines ending
163     in a backslash are concatenated with the following
164     line while reading and the backslash is replaced by a
165     space character. This may be used to wrap long lines.</para>
166
167     <para>Along with a unit file <filename>foo.service</filename>, the
168     directory <filename>foo.service.wants/</filename> may exist. All
169     unit files symlinked from such a directory are implicitly added as
170     dependencies of type <varname>Wants=</varname> to the unit. This
171     is useful to hook units into the start-up of other units, without
172     having to modify their unit files. For details about the semantics
173     of <varname>Wants=</varname>, see below. The preferred way to
174     create symlinks in the <filename>.wants/</filename> directory of a
175     unit file is with the <command>enable</command> command of the
176     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
177     tool which reads information from the [Install] section of unit
178     files (see below). A similar functionality exists for
179     <varname>Requires=</varname> type dependencies as well, the
180     directory suffix is <filename>.requires/</filename> in this
181     case.</para>
182
183     <para>Along with a unit file <filename>foo.service</filename>, a
184     directory <filename>foo.service.d/</filename> may exist. All files
185     with the suffix <literal>.conf</literal> from this directory will
186     be parsed after the file itself is parsed. This is useful to alter
187     or add configuration settings to a unit, without having to modify
188     their unit files. Make sure that the file that is included has the
189     appropriate section headers before any directive. Note that for
190     instanced units this logic will first look for the instance
191     <literal>.d/</literal> subdirectory and read its
192     <literal>.conf</literal> files, followed by the template
193     <literal>.d/</literal> subdirectory and reads its
194     <literal>.conf</literal> files.</para>
195
196     <!-- Note that we do not document .include here, as we
197          consider it mostly obsolete, and want people to
198          use .d/ drop-ins instead. -->
199
200     <para>Note that while systemd offers a flexible dependency system
201     between units it is recommended to use this functionality only
202     sparingly and instead rely on techniques such as bus-based or
203     socket-based activation which make dependencies implicit,
204     resulting in a both simpler and more flexible system.</para>
205
206     <para>Some unit names reflect paths existing in the file system
207     namespace. Example: a device unit
208     <filename>dev-sda.device</filename> refers to a device with the
209     device node <filename noindex='true'>/dev/sda</filename> in the
210     file system namespace. If this applies, a special way to escape
211     the path name is used, so that the result is usable as part of a
212     filename. Basically, given a path, "/" is replaced by "-" and all
213     other characters which are not ASCII alphanumerics are replaced by
214     C-style "\x2d" escapes (except that "_" is never replaced and "."
215     is only replaced when it would be the first character in the
216     escaped path). The root directory "/" is encoded as single dash,
217     while otherwise the initial and ending "/" are removed from all
218     paths during transformation. This escaping is reversible. Properly
219     escaped paths can be generated using the
220     <citerefentry><refentrytitle>systemd-escape</refentrytitle><manvolnum>1</manvolnum></citerefentry>
221     command.</para>
222
223     <para>Optionally, units may be instantiated from a
224     template file at runtime. This allows creation of
225     multiple units from a single configuration file. If
226     systemd looks for a unit configuration file, it will
227     first search for the literal unit name in the
228     file system. If that yields no success and the unit
229     name contains an <literal>@</literal> character, systemd will look for a
230     unit template that shares the same name but with the
231     instance string (i.e. the part between the <literal>@</literal> character
232     and the suffix) removed. Example: if a service
233     <filename>getty@tty3.service</filename> is requested
234     and no file by that name is found, systemd will look
235     for <filename>getty@.service</filename> and
236     instantiate a service from that configuration file if
237     it is found.</para>
238
239     <para>To refer to the instance string from within the
240     configuration file you may use the special <literal>%i</literal>
241     specifier in many of the configuration options. See below for
242     details.</para>
243
244     <para>If a unit file is empty (i.e. has the file size 0) or is
245     symlinked to <filename>/dev/null</filename>, its configuration
246     will not be loaded and it appears with a load state of
247     <literal>masked</literal>, and cannot be activated. Use this as an
248     effective way to fully disable a unit, making it impossible to
249     start it even manually.</para>
250
251     <para>The unit file format is covered by the
252     <ulink
253     url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
254     Stability Promise</ulink>.</para>
255
256   </refsect1>
257
258   <refsect1>
259     <title>Unit Load Path</title>
260
261     <para>Unit files are loaded from a set of paths determined during
262     compilation, described in the two tables below. Unit files found
263     in directories listed earlier override files with the same name in
264     directories lower in the list.</para>
265
266     <para>When systemd is running in user mode
267     (<option>--user</option>) and the variable
268     <varname>$SYSTEMD_UNIT_PATH</varname> is set, the contents of this
269     variable overrides the unit load path. If
270     <varname>$SYSTEMD_UNIT_PATH</varname> ends with an empty component
271     (<literal>:</literal>), the usual unit load path will be appended
272     to the contents of the variable.</para>
273
274     <table>
275       <title>
276         Load path when running in system mode (<option>--system</option>).
277       </title>
278
279       <tgroup cols='2'>
280         <colspec colname='path' />
281         <colspec colname='expl' />
282         <thead>
283           <row>
284       <entry>Path</entry>
285       <entry>Description</entry>
286           </row>
287         </thead>
288         <tbody>
289           <row>
290       <entry><filename>/etc/systemd/system</filename></entry>
291       <entry>Local configuration</entry>
292           </row>
293           <row>
294       <entry><filename>/run/systemd/system</filename></entry>
295       <entry>Runtime units</entry>
296           </row>
297           <row>
298       <entry><filename>/usr/lib/systemd/system</filename></entry>
299       <entry>Units of installed packages</entry>
300           </row>
301         </tbody>
302       </tgroup>
303     </table>
304
305     <table>
306       <title>
307         Load path when running in user mode (<option>--user</option>).
308       </title>
309
310       <tgroup cols='2'>
311         <colspec colname='path' />
312         <colspec colname='expl' />
313         <thead>
314           <row>
315       <entry>Path</entry>
316       <entry>Description</entry>
317           </row>
318         </thead>
319         <tbody>
320           <row>
321       <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry>
322       <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry>
323           </row>
324           <row>
325       <entry><filename>$HOME/.config/systemd/user</filename></entry>
326       <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry>
327           </row>
328           <row>
329       <entry><filename>/etc/systemd/user</filename></entry>
330       <entry>Local configuration</entry>
331           </row>
332           <row>
333       <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry>
334       <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry>
335           </row>
336           <row>
337       <entry><filename>/run/systemd/user</filename></entry>
338       <entry>Runtime units</entry>
339           </row>
340           <row>
341       <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry>
342       <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry>
343           </row>
344           <row>
345       <entry><filename>$HOME/.local/share/systemd/user</filename></entry>
346       <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry>
347           </row>
348           <row>
349       <entry><filename>/usr/lib/systemd/user</filename></entry>
350       <entry>Units of packages that have been installed system-wide</entry>
351           </row>
352         </tbody>
353       </tgroup>
354     </table>
355
356     <para>Additional units might be loaded into systemd ("linked")
357     from directories not on the unit load path. See the
358     <command>link</command> command for
359     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
360     Also, some units are dynamically created via generators <ulink
361     url="http://www.freedesktop.org/wiki/Software/systemd/Generators/">Generators</ulink>.
362     </para>
363   </refsect1>
364
365   <refsect1>
366     <title>[Unit] Section Options</title>
367
368     <para>Unit file may include a [Unit] section, which carries
369     generic information about the unit that is not dependent on the
370     type of unit:</para>
371
372     <variablelist class='unit-directives'>
373
374       <varlistentry>
375         <term><varname>Description=</varname></term>
376         <listitem><para>A free-form string describing the unit. This
377         is intended for use in UIs to show descriptive information
378         along with the unit name. The description should contain a
379         name that means something to the end user. <literal>Apache2
380         Web Server</literal> is a good example. Bad examples are
381         <literal>high-performance light-weight HTTP server</literal>
382         (too generic) or <literal>Apache2</literal> (too specific and
383         meaningless for people who do not know
384         Apache).</para></listitem>
385       </varlistentry>
386
387       <varlistentry>
388         <term><varname>Documentation=</varname></term>
389         <listitem><para>A space-separated list of URIs referencing
390         documentation for this unit or its configuration. Accepted are
391         only URIs of the types <literal>http://</literal>,
392         <literal>https://</literal>, <literal>file:</literal>,
393         <literal>info:</literal>, <literal>man:</literal>. For more
394         information about the syntax of these URIs, see <citerefentry
395         project='man-pages'><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
396         The URIs should be listed in order of relevance, starting with
397         the most relevant. It is a good idea to first reference
398         documentation that explains what the unit's purpose is,
399         followed by how it is configured, followed by any other
400         related documentation. This option may be specified more than
401         once, in which case the specified list of URIs is merged. If
402         the empty string is assigned to this option, the list is reset
403         and all prior assignments will have no
404         effect.</para></listitem>
405       </varlistentry>
406
407       <varlistentry>
408         <term><varname>Requires=</varname></term>
409
410         <listitem><para>Configures requirement dependencies on other
411         units. If this unit gets activated, the units listed here will
412         be activated as well. If one of the other units gets
413         deactivated or its activation fails, this unit will be
414         deactivated. This option may be specified more than once or
415         multiple space-separated units may be specified in one option
416         in which case requirement dependencies for all listed names
417         will be created. Note that requirement dependencies do not
418         influence the order in which services are started or stopped.
419         This has to be configured independently with the
420         <varname>After=</varname> or <varname>Before=</varname>
421         options. If a unit <filename>foo.service</filename> requires a
422         unit <filename>bar.service</filename> as configured with
423         <varname>Requires=</varname> and no ordering is configured
424         with <varname>After=</varname> or <varname>Before=</varname>,
425         then both units will be started simultaneously and without any
426         delay between them if <filename>foo.service</filename> is
427         activated. Often it is a better choice to use
428         <varname>Wants=</varname> instead of
429         <varname>Requires=</varname> in order to achieve a system that
430         is more robust when dealing with failing services.</para>
431
432         <para>Note that dependencies of this type may also be
433         configured outside of the unit configuration file by adding a
434         symlink to a <filename>.requires/</filename> directory
435         accompanying the unit file. For details see
436         above.</para></listitem>
437       </varlistentry>
438
439       <varlistentry>
440         <term><varname>RequiresOverridable=</varname></term>
441
442         <listitem><para>Similar to <varname>Requires=</varname>.
443         Dependencies listed in <varname>RequiresOverridable=</varname>
444         which cannot be fulfilled or fail to start are ignored if the
445         startup was explicitly requested by the user. If the start-up
446         was pulled in indirectly by some dependency or automatic
447         start-up of units that is not requested by the user, this
448         dependency must be fulfilled and otherwise the transaction
449         fails. Hence, this option may be used to configure
450         dependencies that are normally honored unless the user
451         explicitly starts up the unit, in which case whether they
452         failed or not is irrelevant.</para></listitem>
453
454       </varlistentry>
455       <varlistentry>
456         <term><varname>Requisite=</varname></term>
457         <term><varname>RequisiteOverridable=</varname></term>
458
459         <listitem><para>Similar to <varname>Requires=</varname> and
460         <varname>RequiresOverridable=</varname>, respectively.
461         However, if the units listed here are not started already,
462         they will not be started and the transaction will fail
463         immediately. </para></listitem>
464       </varlistentry>
465
466       <varlistentry>
467         <term><varname>Wants=</varname></term>
468
469         <listitem><para>A weaker version of
470         <varname>Requires=</varname>. Units listed in this option will
471         be started if the configuring unit is. However, if the listed
472         units fail to start or cannot be added to the transaction,
473         this has no impact on the validity of the transaction as a
474         whole. This is the recommended way to hook start-up of one
475         unit to the start-up of another unit.</para>
476
477         <para>Note that dependencies of this type may also be
478         configured outside of the unit configuration file by adding
479         symlinks to a <filename>.wants/</filename> directory
480         accompanying the unit file. For details, see
481         above.</para></listitem>
482       </varlistentry>
483
484       <varlistentry>
485         <term><varname>BindsTo=</varname></term>
486
487         <listitem><para>Configures requirement dependencies, very
488         similar in style to <varname>Requires=</varname>, however in
489         addition to this behavior, it also declares that this unit is
490         stopped when any of the units listed suddenly disappears.
491         Units can suddenly, unexpectedly disappear if a service
492         terminates on its own choice, a device is unplugged or a mount
493         point unmounted without involvement of
494         systemd.</para></listitem>
495       </varlistentry>
496
497       <varlistentry>
498         <term><varname>PartOf=</varname></term>
499
500         <listitem><para>Configures dependencies similar to
501         <varname>Requires=</varname>, but limited to stopping and
502         restarting of units. When systemd stops or restarts the units
503         listed here, the action is propagated to this unit. Note that
504         this is a one-way dependency — changes to this unit do not
505         affect the listed units. </para></listitem>
506       </varlistentry>
507
508       <varlistentry>
509         <term><varname>Conflicts=</varname></term>
510
511         <listitem><para>A space-separated list of unit names.
512         Configures negative requirement dependencies. If a unit has a
513         <varname>Conflicts=</varname> setting on another unit,
514         starting the former will stop the latter and vice versa. Note
515         that this setting is independent of and orthogonal to the
516         <varname>After=</varname> and <varname>Before=</varname>
517         ordering dependencies.</para>
518
519         <para>If a unit A that conflicts with a unit B is scheduled to
520         be started at the same time as B, the transaction will either
521         fail (in case both are required part of the transaction) or be
522         modified to be fixed (in case one or both jobs are not a
523         required part of the transaction). In the latter case, the job
524         that is not the required will be removed, or in case both are
525         not required, the unit that conflicts will be started and the
526         unit that is conflicted is stopped.</para></listitem>
527       </varlistentry>
528
529       <varlistentry>
530         <term><varname>Before=</varname></term>
531         <term><varname>After=</varname></term>
532
533         <listitem><para>A space-separated list of unit names.
534         Configures ordering dependencies between units. If a unit
535         <filename>foo.service</filename> contains a setting
536         <option>Before=bar.service</option> and both units are being
537         started, <filename>bar.service</filename>'s start-up is
538         delayed until <filename>foo.service</filename> is started up.
539         Note that this setting is independent of and orthogonal to the
540         requirement dependencies as configured by
541         <varname>Requires=</varname>. It is a common pattern to
542         include a unit name in both the <varname>After=</varname> and
543         <varname>Requires=</varname> option, in which case the unit
544         listed will be started before the unit that is configured with
545         these options. This option may be specified more than once, in
546         which case ordering dependencies for all listed names are
547         created. <varname>After=</varname> is the inverse of
548         <varname>Before=</varname>, i.e. while
549         <varname>After=</varname> ensures that the configured unit is
550         started after the listed unit finished starting up,
551         <varname>Before=</varname> ensures the opposite, i.e. that the
552         configured unit is fully started up before the listed unit is
553         started. Note that when two units with an ordering dependency
554         between them are shut down, the inverse of the start-up order
555         is applied. i.e. if a unit is configured with
556         <varname>After=</varname> on another unit, the former is
557         stopped before the latter if both are shut down. If one unit
558         with an ordering dependency on another unit is shut down while
559         the latter is started up, the shut down is ordered before the
560         start-up regardless of whether the ordering dependency is
561         actually of type <varname>After=</varname> or
562         <varname>Before=</varname>. If two units have no ordering
563         dependencies between them, they are shut down or started up
564         simultaneously, and no ordering takes place.
565         </para></listitem>
566       </varlistentry>
567
568       <varlistentry>
569         <term><varname>OnFailure=</varname></term>
570
571         <listitem><para>A space-separated list of one or more units
572         that are activated when this unit enters the
573         <literal>failed</literal> state.</para></listitem>
574       </varlistentry>
575
576       <varlistentry>
577         <term><varname>PropagatesReloadTo=</varname></term>
578         <term><varname>ReloadPropagatedFrom=</varname></term>
579
580         <listitem><para>A space-separated list of one or more units
581         where reload requests on this unit will be propagated to, or
582         reload requests on the other unit will be propagated to this
583         unit, respectively. Issuing a reload request on a unit will
584         automatically also enqueue a reload request on all units that
585         the reload request shall be propagated to via these two
586         settings.</para></listitem>
587       </varlistentry>
588
589       <varlistentry>
590         <term><varname>JoinsNamespaceOf=</varname></term>
591
592         <listitem><para>For units that start processes (such as
593         service units), lists one or more other units whose network
594         and/or temporary file namespace to join. This only applies to
595         unit types which support the
596         <varname>PrivateNetwork=</varname> and
597         <varname>PrivateTmp=</varname> directives (see
598         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
599         for details). If a unit that has this setting set is started,
600         its processes will see the same <filename>/tmp</filename>,
601         <filename>/tmp/var</filename> and network namespace as one
602         listed unit that is started. If multiple listed units are
603         already started, it is not defined which namespace is joined.
604         Note that this setting only has an effect if
605         <varname>PrivateNetwork=</varname> and/or
606         <varname>PrivateTmp=</varname> is enabled for both the unit
607         that joins the namespace and the unit whose namespace is
608         joined.</para></listitem>
609       </varlistentry>
610
611       <varlistentry>
612         <term><varname>RequiresMountsFor=</varname></term>
613
614         <listitem><para>Takes a space-separated list of absolute
615         paths. Automatically adds dependencies of type
616         <varname>Requires=</varname> and <varname>After=</varname> for
617         all mount units required to access the specified path.</para>
618
619         <para>Mount points marked with <option>noauto</option> are not
620         mounted automatically and will be ignored for the purposes of
621         this option. If such a mount should be a requirement for this
622         unit, direct dependencies on the mount units may be added
623         (<varname>Requires=</varname> and <varname>After=</varname> or
624         some other combination). </para></listitem>
625       </varlistentry>
626
627       <varlistentry>
628         <term><varname>OnFailureJobMode=</varname></term>
629
630         <listitem><para>Takes a value of
631         <literal>fail</literal>,
632         <literal>replace</literal>,
633         <literal>replace-irreversibly</literal>,
634         <literal>isolate</literal>,
635         <literal>flush</literal>,
636         <literal>ignore-dependencies</literal> or
637         <literal>ignore-requirements</literal>. Defaults to
638         <literal>replace</literal>. Specifies how the units listed in
639         <varname>OnFailure=</varname> will be enqueued. See
640         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
641         <option>--job-mode=</option> option for details on the
642         possible values. If this is set to <literal>isolate</literal>,
643         only a single unit may be listed in
644         <varname>OnFailure=</varname>..</para></listitem>
645       </varlistentry>
646
647       <varlistentry>
648         <term><varname>IgnoreOnIsolate=</varname></term>
649
650         <listitem><para>Takes a boolean argument. If
651         <option>true</option>, this unit will not be stopped when
652         isolating another unit. Defaults to
653         <option>false</option>.</para></listitem>
654       </varlistentry>
655
656       <varlistentry>
657         <term><varname>IgnoreOnSnapshot=</varname></term>
658
659         <listitem><para>Takes a boolean argument. If
660         <option>true</option>, this unit will not be included in
661         snapshots. Defaults to <option>true</option> for device and
662         snapshot units, <option>false</option> for the
663         others.</para></listitem>
664       </varlistentry>
665
666       <varlistentry>
667         <term><varname>StopWhenUnneeded=</varname></term>
668
669         <listitem><para>Takes a boolean argument. If
670         <option>true</option>, this unit will be stopped when it is no
671         longer used. Note that in order to minimize the work to be
672         executed, systemd will not stop units by default unless they
673         are conflicting with other units, or the user explicitly
674         requested their shut down. If this option is set, a unit will
675         be automatically cleaned up if no other active unit requires
676         it. Defaults to <option>false</option>.</para></listitem>
677       </varlistentry>
678
679       <varlistentry>
680         <term><varname>RefuseManualStart=</varname></term>
681         <term><varname>RefuseManualStop=</varname></term>
682
683         <listitem><para>Takes a boolean argument. If
684         <option>true</option>, this unit can only be activated or
685         deactivated indirectly. In this case, explicit start-up or
686         termination requested by the user is denied, however if it is
687         started or stopped as a dependency of another unit, start-up
688         or termination will succeed. This is mostly a safety feature
689         to ensure that the user does not accidentally activate units
690         that are not intended to be activated explicitly, and not
691         accidentally deactivate units that are not intended to be
692         deactivated. These options default to
693         <option>false</option>.</para></listitem>
694       </varlistentry>
695
696       <varlistentry>
697         <term><varname>AllowIsolate=</varname></term>
698
699         <listitem><para>Takes a boolean argument. If
700         <option>true</option>, this unit may be used with the
701         <command>systemctl isolate</command> command. Otherwise, this
702         will be refused. It probably is a good idea to leave this
703         disabled except for target units that shall be used similar to
704         runlevels in SysV init systems, just as a precaution to avoid
705         unusable system states. This option defaults to
706         <option>false</option>.</para></listitem>
707       </varlistentry>
708
709       <varlistentry>
710         <term><varname>DefaultDependencies=</varname></term>
711
712         <listitem><para>Takes a boolean argument. If
713         <option>true</option>, (the default), a few default
714         dependencies will implicitly be created for the unit. The
715         actual dependencies created depend on the unit type. For
716         example, for service units, these dependencies ensure that the
717         service is started only after basic system initialization is
718         completed and is properly terminated on system shutdown. See
719         the respective man pages for details. Generally, only services
720         involved with early boot or late shutdown should set this
721         option to <option>false</option>. It is highly recommended to
722         leave this option enabled for the majority of common units. If
723         set to <option>false</option>, this option does not disable
724         all implicit dependencies, just non-essential
725         ones.</para></listitem>
726       </varlistentry>
727
728       <varlistentry>
729         <term><varname>JobTimeoutSec=</varname></term>
730         <term><varname>JobTimeoutAction=</varname></term>
731         <term><varname>JobTimeoutRebootArgument=</varname></term>
732
733         <listitem><para>When a job for this unit is queued a time-out
734         may be configured. If this time limit is reached, the job will
735         be cancelled, the unit however will not change state or even
736         enter the <literal>failed</literal> mode. This value defaults
737         to 0 (job timeouts disabled), except for device units. NB:
738         this timeout is independent from any unit-specific timeout
739         (for example, the timeout set with
740         <varname>StartTimeoutSec=</varname> in service units) as the
741         job timeout has no effect on the unit itself, only on the job
742         that might be pending for it. Or in other words: unit-specific
743         timeouts are useful to abort unit state changes, and revert
744         them. The job timeout set with this option however is useful
745         to abort only the job waiting for the unit state to
746         change.</para>
747
748         <para><varname>JobTimeoutAction=</varname>
749         optionally configures an additional
750         action to take when the time-out is
751         hit. It takes the same values as the
752         per-service
753         <varname>StartLimitAction=</varname>
754         setting, see
755         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
756         for details. Defaults to
757         <option>none</option>. <varname>JobTimeoutRebootArgument=</varname>
758         configures an optional reboot string
759         to pass to the
760         <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
761         system call.</para></listitem>
762       </varlistentry>
763
764       <varlistentry>
765         <term><varname>ConditionArchitecture=</varname></term>
766         <term><varname>ConditionVirtualization=</varname></term>
767         <term><varname>ConditionHost=</varname></term>
768         <term><varname>ConditionKernelCommandLine=</varname></term>
769         <term><varname>ConditionSecurity=</varname></term>
770         <term><varname>ConditionCapability=</varname></term>
771         <term><varname>ConditionACPower=</varname></term>
772         <term><varname>ConditionNeedsUpdate=</varname></term>
773         <term><varname>ConditionFirstBoot=</varname></term>
774         <term><varname>ConditionPathExists=</varname></term>
775         <term><varname>ConditionPathExistsGlob=</varname></term>
776         <term><varname>ConditionPathIsDirectory=</varname></term>
777         <term><varname>ConditionPathIsSymbolicLink=</varname></term>
778         <term><varname>ConditionPathIsMountPoint=</varname></term>
779         <term><varname>ConditionPathIsReadWrite=</varname></term>
780         <term><varname>ConditionDirectoryNotEmpty=</varname></term>
781         <term><varname>ConditionFileNotEmpty=</varname></term>
782         <term><varname>ConditionFileIsExecutable=</varname></term>
783
784         <!-- We don't document ConditionNull=
785              here as it is not particularly
786              useful and probably just
787              confusing. -->
788
789         <listitem><para>Before starting a unit verify that the
790         specified condition is true. If it is not true, the starting
791         of the unit will be skipped, however all ordering dependencies
792         of it are still respected. A failing condition will not result
793         in the unit being moved into a failure state. The condition is
794         checked at the time the queued start job is to be
795         executed.</para>
796
797         <para><varname>ConditionArchitecture=</varname> may be used to
798         check whether the system is running on a specific
799         architecture. Takes one of
800         <varname>x86</varname>,
801         <varname>x86-64</varname>,
802         <varname>ppc</varname>,
803         <varname>ppc-le</varname>,
804         <varname>ppc64</varname>,
805         <varname>ppc64-le</varname>,
806         <varname>ia64</varname>,
807         <varname>parisc</varname>,
808         <varname>parisc64</varname>,
809         <varname>s390</varname>,
810         <varname>s390x</varname>,
811         <varname>sparc</varname>,
812         <varname>sparc64</varname>,
813         <varname>mips</varname>,
814         <varname>mips-le</varname>,
815         <varname>mips64</varname>,
816         <varname>mips64-le</varname>,
817         <varname>alpha</varname>,
818         <varname>arm</varname>,
819         <varname>arm-be</varname>,
820         <varname>arm64</varname>,
821         <varname>arm64-be</varname>,
822         <varname>sh</varname>,
823         <varname>sh64</varname>,
824         <varname>m86k</varname>,
825         <varname>tilegx</varname>,
826         <varname>cris</varname> to test
827         against a specific architecture. The architecture is
828         determined from the information returned by
829         <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry>
830         and is thus subject to
831         <citerefentry><refentrytitle>personality</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
832         Note that a <varname>Personality=</varname> setting in the
833         same unit file has no effect on this condition. A special
834         architecture name <varname>native</varname> is mapped to the
835         architecture the system manager itself is compiled for. The
836         test may be negated by prepending an exclamation mark.</para>
837
838         <para><varname>ConditionVirtualization=</varname> may be used
839         to check whether the system is executed in a virtualized
840         environment and optionally test whether it is a specific
841         implementation. Takes either boolean value to check if being
842         executed in any virtualized environment, or one of
843         <varname>vm</varname> and
844         <varname>container</varname> to test against a generic type of
845         virtualization solution, or one of
846         <varname>qemu</varname>,
847         <varname>kvm</varname>,
848         <varname>zvm</varname>,
849         <varname>vmware</varname>,
850         <varname>microsoft</varname>,
851         <varname>oracle</varname>,
852         <varname>xen</varname>,
853         <varname>bochs</varname>,
854         <varname>uml</varname>,
855         <varname>openvz</varname>,
856         <varname>lxc</varname>,
857         <varname>lxc-libvirt</varname>,
858         <varname>systemd-nspawn</varname>,
859         <varname>docker</varname> to test
860         against a specific implementation. See
861         <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry>
862         for a full list of known virtualization technologies and their
863         identifiers. If multiple virtualization technologies are
864         nested, only the innermost is considered. The test may be
865         negated by prepending an exclamation mark.</para>
866
867         <para><varname>ConditionHost=</varname> may be used to match
868         against the hostname or machine ID of the host. This either
869         takes a hostname string (optionally with shell style globs)
870         which is tested against the locally set hostname as returned
871         by
872         <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
873         or a machine ID formatted as string (see
874         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
875         The test may be negated by prepending an exclamation
876         mark.</para>
877
878         <para><varname>ConditionKernelCommandLine=</varname> may be
879         used to check whether a specific kernel command line option is
880         set (or if prefixed with the exclamation mark unset). The
881         argument must either be a single word, or an assignment (i.e.
882         two words, separated <literal>=</literal>). In the former case
883         the kernel command line is searched for the word appearing as
884         is, or as left hand side of an assignment. In the latter case,
885         the exact assignment is looked for with right and left hand
886         side matching.</para>
887
888         <para><varname>ConditionSecurity=</varname> may be used to
889         check whether the given security module is enabled on the
890         system. Currently the recognized values values are
891         <varname>selinux</varname>,
892         <varname>apparmor</varname>,
893         <varname>ima</varname>,
894         <varname>smack</varname> and
895         <varname>audit</varname>. The test may be negated by
896         prepending an exclamation mark.</para>
897
898         <para><varname>ConditionCapability=</varname> may be used to
899         check whether the given capability exists in the capability
900         bounding set of the service manager (i.e. this does not check
901         whether capability is actually available in the permitted or
902         effective sets, see
903         <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
904         for details). Pass a capability name such as
905         <literal>CAP_MKNOD</literal>, possibly prefixed with an
906         exclamation mark to negate the check.</para>
907
908         <para><varname>ConditionACPower=</varname> may be used to
909         check whether the system has AC power, or is exclusively
910         battery powered at the time of activation of the unit. This
911         takes a boolean argument. If set to <varname>true</varname>,
912         the condition will hold only if at least one AC connector of
913         the system is connected to a power source, or if no AC
914         connectors are known. Conversely, if set to
915         <varname>false</varname>, the condition will hold only if
916         there is at least one AC connector known and all AC connectors
917         are disconnected from a power source.</para>
918
919         <para><varname>ConditionNeedsUpdate=</varname> takes one of
920         <filename>/var</filename> or <filename>/etc</filename> as
921         argument, possibly prefixed with a <literal>!</literal> (for
922         inverting the condition). This condition may be used to
923         conditionalize units on whether the specified directory
924         requires an update because <filename>/usr</filename>'s
925         modification time is newer than the stamp file
926         <filename>.updated</filename> in the specified directory. This
927         is useful to implement offline updates of the vendor operating
928         system resources in <filename>/usr</filename> that require
929         updating of <filename>/etc</filename> or
930         <filename>/var</filename> on the next following boot. Units
931         making use of this condition should order themselves before
932         <citerefentry><refentrytitle>systemd-update-done.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
933         to make sure they run before the stamp files's modification
934         time gets reset indicating a completed update.</para>
935
936         <para><varname>ConditionFirstBoot=</varname> takes a boolean
937         argument. This condition may be used to conditionalize units
938         on whether the system is booting up with an unpopulated
939         <filename>/etc</filename> directory. This may be used to
940         populate <filename>/etc</filename> on the first boot after
941         factory reset, or when a new system instances boots up for the
942         first time.</para>
943
944         <para>With <varname>ConditionPathExists=</varname> a file
945         existence condition is checked before a unit is started. If
946         the specified absolute path name does not exist, the condition
947         will fail. If the absolute path name passed to
948         <varname>ConditionPathExists=</varname> is prefixed with an
949         exclamation mark (<literal>!</literal>), the test is negated,
950         and the unit is only started if the path does not
951         exist.</para>
952
953         <para><varname>ConditionPathExistsGlob=</varname> is similar
954         to <varname>ConditionPathExists=</varname>, but checks for the
955         existence of at least one file or directory matching the
956         specified globbing pattern.</para>
957
958         <para><varname>ConditionPathIsDirectory=</varname> is similar
959         to <varname>ConditionPathExists=</varname> but verifies
960         whether a certain path exists and is a directory.</para>
961
962         <para><varname>ConditionPathIsSymbolicLink=</varname> is
963         similar to <varname>ConditionPathExists=</varname> but
964         verifies whether a certain path exists and is a symbolic
965         link.</para>
966
967         <para><varname>ConditionPathIsMountPoint=</varname> is similar
968         to <varname>ConditionPathExists=</varname> but verifies
969         whether a certain path exists and is a mount point.</para>
970
971         <para><varname>ConditionPathIsReadWrite=</varname> is similar
972         to <varname>ConditionPathExists=</varname> but verifies
973         whether the underlying file system is readable and writable
974         (i.e. not mounted read-only).</para>
975
976         <para><varname>ConditionDirectoryNotEmpty=</varname> is
977         similar to <varname>ConditionPathExists=</varname> but
978         verifies whether a certain path exists and is a non-empty
979         directory.</para>
980
981         <para><varname>ConditionFileNotEmpty=</varname> is similar to
982         <varname>ConditionPathExists=</varname> but verifies whether a
983         certain path exists and refers to a regular file with a
984         non-zero size.</para>
985
986         <para><varname>ConditionFileIsExecutable=</varname> is similar
987         to <varname>ConditionPathExists=</varname> but verifies
988         whether a certain path exists, is a regular file and marked
989         executable.</para>
990
991         <para>If multiple conditions are specified, the unit will be
992         executed if all of them apply (i.e. a logical AND is applied).
993         Condition checks can be prefixed with a pipe symbol (|) in
994         which case a condition becomes a triggering condition. If at
995         least one triggering condition is defined for a unit, then the
996         unit will be executed if at least one of the triggering
997         conditions apply and all of the non-triggering conditions. If
998         you prefix an argument with the pipe symbol and an exclamation
999         mark, the pipe symbol must be passed first, the exclamation
1000         second. Except for
1001         <varname>ConditionPathIsSymbolicLink=</varname>, all path
1002         checks follow symlinks. If any of these options is assigned
1003         the empty string, the list of conditions is reset completely,
1004         all previous condition settings (of any kind) will have no
1005         effect.</para></listitem>
1006       </varlistentry>
1007
1008       <varlistentry>
1009         <term><varname>AssertArchitecture=</varname></term>
1010         <term><varname>AssertVirtualization=</varname></term>
1011         <term><varname>AssertHost=</varname></term>
1012         <term><varname>AssertKernelCommandLine=</varname></term>
1013         <term><varname>AssertSecurity=</varname></term>
1014         <term><varname>AssertCapability=</varname></term>
1015         <term><varname>AssertACPower=</varname></term>
1016         <term><varname>AssertNeedsUpdate=</varname></term>
1017         <term><varname>AssertFirstBoot=</varname></term>
1018         <term><varname>AssertPathExists=</varname></term>
1019         <term><varname>AssertPathExistsGlob=</varname></term>
1020         <term><varname>AssertPathIsDirectory=</varname></term>
1021         <term><varname>AssertPathIsSymbolicLink=</varname></term>
1022         <term><varname>AssertPathIsMountPoint=</varname></term>
1023         <term><varname>AssertPathIsReadWrite=</varname></term>
1024         <term><varname>AssertDirectoryNotEmpty=</varname></term>
1025         <term><varname>AssertFileNotEmpty=</varname></term>
1026         <term><varname>AssertFileIsExecutable=</varname></term>
1027
1028         <listitem><para>Similar to the
1029         <varname>ConditionArchitecture=</varname>,
1030         <varname>ConditionVirtualization=</varname>, ... condition
1031         settings described above these settings add assertion checks
1032         to the start-up of the unit. However, unlike the conditions
1033         settings any assertion setting that is not met results in
1034         failure of the start job it was triggered
1035         by.</para></listitem>
1036       </varlistentry>
1037
1038       <varlistentry>
1039         <term><varname>SourcePath=</varname></term>
1040         <listitem><para>A path to a configuration file this unit has
1041         been generated from. This is primarily useful for
1042         implementation of generator tools that convert configuration
1043         from an external configuration file format into native unit
1044         files. This functionality should not be used in normal
1045         units.</para></listitem>
1046       </varlistentry>
1047     </variablelist>
1048
1049   </refsect1>
1050
1051   <refsect1>
1052     <title>[Install] Section Options</title>
1053
1054     <para>Unit file may include an <literal>[Install]</literal>
1055     section, which carries installation information for the unit. This
1056     section is not interpreted by
1057     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1058     during runtime. It is used exclusively by the
1059     <command>enable</command> and <command>disable</command> commands
1060     of the
1061     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1062     tool during installation of a unit:</para>
1063
1064     <variablelist class='unit-directives'>
1065       <varlistentry>
1066         <term><varname>Alias=</varname></term>
1067
1068         <listitem><para>A space-separated list of additional names
1069         this unit shall be installed under. The names listed here must
1070         have the same suffix (i.e. type) as the unit file name. This
1071         option may be specified more than once, in which case all
1072         listed names are used. At installation time,
1073         <command>systemctl enable</command> will create symlinks from
1074         these names to the unit filename.</para></listitem>
1075       </varlistentry>
1076
1077       <varlistentry>
1078         <term><varname>WantedBy=</varname></term>
1079         <term><varname>RequiredBy=</varname></term>
1080
1081         <listitem><para>This option may be used more than once, or a
1082         space-separated list of unit names may be given. A symbolic
1083         link is created in the <filename>.wants/</filename> or
1084         <filename>.requires/</filename> directory of each of the
1085         listed units when this unit is installed by <command>systemctl
1086         enable</command>. This has the effect that a dependency of
1087         type <varname>Wants=</varname> or <varname>Requires=</varname>
1088         is added from the listed unit to the current unit. The primary
1089         result is that the current unit will be started when the
1090         listed unit is started. See the description of
1091         <varname>Wants=</varname> and <varname>Requires=</varname> in
1092         the [Unit] section for details.</para>
1093
1094         <para><command>WantedBy=foo.service</command> in a service
1095         <filename>bar.service</filename> is mostly equivalent to
1096         <command>Alias=foo.service.wants/bar.service</command> in the
1097         same file. In case of template units, <command>systemctl
1098         enable</command> must be called with an instance name, and
1099         this instance will be added to the
1100         <filename>.wants/</filename> or
1101         <filename>.requires/</filename> list of the listed unit. E.g.
1102         <command>WantedBy=getty.target</command> in a service
1103         <filename>getty@.service</filename> will result in
1104         <command>systemctl enable getty@tty2.service</command>
1105         creating a
1106         <filename>getty.target.wants/getty@tty2.service</filename>
1107         link to <filename>getty@.service</filename>.
1108         </para></listitem>
1109       </varlistentry>
1110
1111       <varlistentry>
1112         <term><varname>Also=</varname></term>
1113
1114         <listitem><para>Additional units to install/deinstall when
1115         this unit is installed/deinstalled. If the user requests
1116         installation/deinstallation of a unit with this option
1117         configured, <command>systemctl enable</command> and
1118         <command>systemctl disable</command> will automatically
1119         install/uninstall units listed in this option as well.</para>
1120
1121         <para>This option may be used more than once, or a
1122         space-separated list of unit names may be
1123         given.</para></listitem>
1124       </varlistentry>
1125
1126       <varlistentry>
1127         <term><varname>DefaultInstance=</varname></term>
1128
1129         <listitem><para>In template unit files, this specifies for
1130         which instance the unit shall be enabled if the template is
1131         enabled without any explicitly set instance. This option has
1132         no effect in non-template unit files. The specified string
1133         must be usable as instance identifier.</para></listitem>
1134       </varlistentry>
1135     </variablelist>
1136
1137     <para>The following specifiers are interpreted in the Install
1138     section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning
1139     see the next section.
1140     </para>
1141   </refsect1>
1142
1143   <refsect1>
1144     <title>Specifiers</title>
1145
1146     <para>Many settings resolve specifiers which may be used to write
1147     generic unit files referring to runtime or unit parameters that
1148     are replaced when the unit files are loaded. The following
1149     specifiers are understood:</para>
1150
1151     <table>
1152       <title>Specifiers available in unit files</title>
1153       <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1154         <colspec colname="spec" />
1155         <colspec colname="mean" />
1156         <colspec colname="detail" />
1157         <thead>
1158           <row>
1159       <entry>Specifier</entry>
1160       <entry>Meaning</entry>
1161       <entry>Details</entry>
1162           </row>
1163         </thead>
1164         <tbody>
1165           <row>
1166       <entry><literal>%n</literal></entry>
1167       <entry>Full unit name</entry>
1168       <entry></entry>
1169           </row>
1170           <row>
1171       <entry><literal>%N</literal></entry>
1172       <entry>Unescaped full unit name</entry>
1173       <entry>Same as <literal>%n</literal>, but with escaping undone</entry>
1174           </row>
1175           <row>
1176       <entry><literal>%p</literal></entry>
1177       <entry>Prefix name</entry>
1178       <entry>For instantiated units, this refers to the string before the <literal>@</literal> character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed.</entry>
1179           </row>
1180           <row>
1181       <entry><literal>%P</literal></entry>
1182       <entry>Unescaped prefix name</entry>
1183       <entry>Same as <literal>%p</literal>, but with escaping undone</entry>
1184           </row>
1185           <row>
1186       <entry><literal>%i</literal></entry>
1187       <entry>Instance name</entry>
1188       <entry>For instantiated units: this is the string between the <literal>@</literal> character and the suffix of the unit name.</entry>
1189           </row>
1190           <row>
1191       <entry><literal>%I</literal></entry>
1192       <entry>Unescaped instance name</entry>
1193       <entry>Same as <literal>%i</literal>, but with escaping undone</entry>
1194           </row>
1195           <row>
1196       <entry><literal>%f</literal></entry>
1197       <entry>Unescaped filename</entry>
1198       <entry>This is either the unescaped instance name (if applicable) with <filename>/</filename> prepended (if applicable), or the prefix name prepended with <filename>/</filename>.</entry>
1199           </row>
1200           <row>
1201       <entry><literal>%c</literal></entry>
1202       <entry>Control group path of the unit</entry>
1203       <entry>This path does not include the <filename>/sys/fs/cgroup/systemd/</filename> prefix.</entry>
1204           </row>
1205           <row>
1206       <entry><literal>%r</literal></entry>
1207       <entry>Control group path of the slice the unit is placed in</entry>
1208       <entry>This usually maps to the parent cgroup path of <literal>%c</literal>.</entry>
1209           </row>
1210           <row>
1211       <entry><literal>%R</literal></entry>
1212       <entry>Root control group path below which slices and units are placed</entry>
1213       <entry>For system instances, this resolves to <filename>/</filename>, except in containers, where this maps to the container's root control group path.</entry>
1214           </row>
1215           <row>
1216       <entry><literal>%t</literal></entry>
1217       <entry>Runtime directory</entry>
1218       <entry>This is either <filename>/run</filename> (for the system manager) or the path <literal>$XDG_RUNTIME_DIR</literal> resolves to (for user managers).</entry>
1219           </row>
1220           <row>
1221       <entry><literal>%u</literal></entry>
1222       <entry>User name</entry>
1223       <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
1224           </row>
1225           <row>
1226       <entry><literal>%U</literal></entry>
1227       <entry>User UID</entry>
1228       <entry>This is the numeric UID of the configured user of the unit, or (if none is set) the user running the systemd user instance. Note that this specifier is not available for units run by the systemd system instance (as opposed to those run by a systemd user instance), unless the user has been configured as a numeric UID in the first place or the configured user is the root user.</entry>
1229           </row>
1230           <row>
1231       <entry><literal>%h</literal></entry>
1232       <entry>User home directory</entry>
1233       <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
1234           </row>
1235           <row>
1236       <entry><literal>%s</literal></entry>
1237       <entry>User shell</entry>
1238       <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd user instance. Similar to <literal>%U</literal>, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user.</entry>
1239           </row>
1240           <row>
1241       <entry><literal>%m</literal></entry>
1242       <entry>Machine ID</entry>
1243       <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
1244           </row>
1245           <row>
1246       <entry><literal>%b</literal></entry>
1247       <entry>Boot ID</entry>
1248       <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
1249           </row>
1250           <row>
1251       <entry><literal>%H</literal></entry>
1252       <entry>Host name</entry>
1253       <entry>The hostname of the running system at the point in time the unit configuation is loaded.</entry>
1254           </row>
1255           <row>
1256       <entry><literal>%v</literal></entry>
1257       <entry>Kernel release</entry>
1258       <entry>Identical to <command>uname -r</command> output</entry>
1259           </row>
1260           <row>
1261       <entry><literal>%%</literal></entry>
1262       <entry>Single percent sign</entry>
1263       <entry>Use <literal>%%</literal> in place of <literal>%</literal> to specify a single percent sign.</entry>
1264           </row>
1265         </tbody>
1266       </tgroup>
1267     </table>
1268
1269     <para>Please note that specifiers <literal>%U</literal>,
1270     <literal>%h</literal>, <literal>%s</literal> are mostly useless
1271     when systemd is running in system mode. PID 1 cannot query the
1272     user account database for information, so the specifiers only work
1273     as shortcuts for things which are already specified in a different
1274     way in the unit file. They are fully functional when systemd is
1275     running in <option>--user</option> mode.</para>
1276   </refsect1>
1277
1278   <refsect1>
1279     <title>Examples</title>
1280
1281     <example>
1282       <title>Allowing units to be enabled</title>
1283
1284       <para>The following snippet (highlighted) allows a unit (e.g.
1285       <filename>foo.service</filename>) to be enabled via
1286       <command>systemctl enable</command>:</para>
1287
1288       <programlisting>[Unit]
1289 Description=Foo
1290
1291 [Service]
1292 ExecStart=/usr/sbin/foo-daemon
1293
1294 <emphasis>[Install]</emphasis>
1295 <emphasis>WantedBy=multi-user.target</emphasis></programlisting>
1296
1297       <para>After running <command>systemctl enable</command>, a
1298       symlink
1299       <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename>
1300       linking to the actual unit will be created. It tells systemd to
1301       pull in the unit when starting
1302       <filename>multi-user.target</filename>. The inverse
1303       <command>systemctl disable</command> will remove that symlink
1304       again.</para>
1305     </example>
1306
1307     <example>
1308       <title>Overriding vendor settings</title>
1309
1310       <para>There are two methods of overriding vendor settings in
1311       unit files: copying the unit file from
1312       <filename>/usr/lib/systemd/system</filename> to
1313       <filename>/etc/systemd/system</filename> and modifying the
1314       chosen settings. Alternatively, one can create a directory named
1315       <filename><replaceable>unit</replaceable>.d/</filename> within
1316       <filename>/etc/systemd/system</filename> and place a drop-in
1317       file <filename><replaceable>name</replaceable>.conf</filename>
1318       there that only changes the specific settings one is interested
1319       in. Note that multiple such drop-in files are read if
1320       present.</para>
1321
1322       <para>The advantage of the first method is that one easily
1323       overrides the complete unit, the vendor unit is not parsed at
1324       all anymore. It has the disadvantage that improvements to the
1325       unit file by the vendor are not automatically incorporated on
1326       updates.</para>
1327
1328       <para>The advantage of the second method is that one only
1329       overrides the settings one specifically wants, where updates to
1330       the unit by the vendor automatically apply. This has the
1331       disadvantage that some future updates by the vendor might be
1332       incompatible with the local changes.</para>
1333
1334       <para>Note that for drop-in files, if one wants to remove
1335       entries from a setting that is parsed as a list (and is not a
1336       dependency), such as <varname>ConditionPathExists=</varname> (or
1337       e.g. <varname>ExecStart=</varname> in service units), one needs
1338       to first clear the list before re-adding all entries except the
1339       one that is to be removed. See below for an example.</para>
1340
1341       <para>This also applies for user instances of systemd, but with
1342       different locations for the unit files. See the section on unit
1343       load paths for further details.</para>
1344
1345       <para>Suppose there is a vendor-supplied unit
1346       <filename>/usr/lib/systemd/system/httpd.service</filename> with
1347       the following contents:</para>
1348
1349       <programlisting>[Unit]
1350 Description=Some HTTP server
1351 After=remote-fs.target sqldb.service
1352 Requires=sqldb.service
1353 AssertPathExists=/srv/webserver
1354
1355 [Service]
1356 Type=notify
1357 ExecStart=/usr/sbin/some-fancy-httpd-server
1358 Nice=5
1359
1360 [Install]
1361 WantedBy=multi-user.target</programlisting>
1362
1363       <para>Now one wants to change some settings as an administrator:
1364       firstly, in the local setup, <filename>/srv/webserver</filename>
1365       might not exist, because the HTTP server is configured to use
1366       <filename>/srv/www</filename> instead. Secondly, the local
1367       configuration makes the HTTP server also depend on a memory
1368       cache service, <filename>memcached.service</filename>, that
1369       should be pulled in (<varname>Requires=</varname>) and also be
1370       ordered appropriately (<varname>After=</varname>). Thirdly, in
1371       order to harden the service a bit more, the administrator would
1372       like to set the <varname>PrivateTmp=</varname> setting (see
1373       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1374       for details). And lastly, the administrator would like to reset
1375       the niceness of the service to its default value of 0.</para>
1376
1377       <para>The first possibility is to copy the unit file to
1378       <filename>/etc/systemd/system/httpd.service</filename> and
1379       change the chosen settings:</para>
1380
1381       <programlisting>[Unit]
1382 Description=Some HTTP server
1383 After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis>
1384 Requires=sqldb.service <emphasis>memcached.service</emphasis>
1385 AssertPathExists=<emphasis>/srv/www</emphasis>
1386
1387 [Service]
1388 Type=notify
1389 ExecStart=/usr/sbin/some-fancy-httpd-server
1390 <emphasis>Nice=0</emphasis>
1391 <emphasis>PrivateTmp=yes</emphasis>
1392
1393 [Install]
1394 WantedBy=multi-user.target</programlisting>
1395
1396       <para>Alternatively, the administrator could create a drop-in
1397       file
1398       <filename>/etc/systemd/system/httpd.service.d/local.conf</filename>
1399       with the following contents:</para>
1400
1401       <programlisting>[Unit]
1402 After=memcached.service
1403 Requires=memcached.service
1404 # Reset all assertions and then re-add the condition we want
1405 AssertPathExists=
1406 AssertPathExists=/srv/www
1407
1408 [Service]
1409 Nice=0
1410 PrivateTmp=yes</programlisting>
1411
1412       <para>Note that dependencies (<varname>After=</varname>, etc.)
1413       cannot be reset to an empty list, so dependencies can only be
1414       added in drop-ins. If you want to remove dependencies, you have
1415       to override the entire unit.</para>
1416     </example>
1417   </refsect1>
1418
1419   <refsect1>
1420     <title>See Also</title>
1421     <para>
1422       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1423       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1424       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1425       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1426       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1427       <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1428       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1429       <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1430       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1431       <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1432       <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1433       <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1434       <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1435       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1436       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1437       <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1438       <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1439       <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1440       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1441       <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>1</manvolnum></citerefentry>
1442     </para>
1443   </refsect1>
1444
1445 </refentry>