man/systemd.unit.xml

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