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