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