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