diff options
Diffstat (limited to 'man/systemd.unit.xml')
| -rw-r--r-- | man/systemd.unit.xml | 1329 |
1 files changed, 1329 insertions, 0 deletions
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml new file mode 100644 index 0000000000..2196e73bb3 --- /dev/null +++ b/man/systemd.unit.xml @@ -0,0 +1,1329 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="systemd.unit"> + + <refentryinfo> + <title>systemd.unit</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.unit</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.unit</refname> + <refpurpose>Unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>service</replaceable>.service</filename>, + <filename><replaceable>socket</replaceable>.socket</filename>, + <filename><replaceable>device</replaceable>.device</filename>, + <filename><replaceable>mount</replaceable>.mount</filename>, + <filename><replaceable>automount</replaceable>.automount</filename>, + <filename><replaceable>swap</replaceable>.swap</filename>, + <filename><replaceable>target</replaceable>.target</filename>, + <filename><replaceable>path</replaceable>.path</filename>, + <filename><replaceable>timer</replaceable>.timer</filename>, + <filename><replaceable>snapshot</replaceable>.snapshot</filename></para> + + <para><literallayout><filename>/etc/systemd/system/*</filename> +<filename>/run/systemd/system/*</filename> +<filename>/usr/lib/systemd/system/*</filename> +<filename>...</filename> + </literallayout></para> + + <para><literallayout><filename>/etc/systemd/user/*</filename> +<filename>/run/systemd/user/*</filename> +<filename>/usr/lib/systemd/user/*</filename> +<filename>...</filename> + </literallayout></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file encodes information + about a service, a socket, a device, a mount point, an + automount point, a swap file or partition, a start-up + target, a file system path, or a timer controlled and + supervised by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. The + syntax is inspired by <ulink + url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG + Desktop Entry Specification</ulink> <filename>.desktop</filename> files, which are in turn + inspired by Microsoft Windows + <filename>.ini</filename> files.</para> + + <para>This man page lists the common configuration + options of all the unit types. These options need to + be configured in the [Unit] or [Install] + sections of the unit files.</para> + + <para>In addition to the generic [Unit] and [Install] + sections described here, each unit may have a + type-specific section, e.g. [Service] for a service + unit. See the respective man pages for more + information: + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>Unit files are loaded from a set of paths + determined during compilation, described in the next section. + </para> + + <para>Unit files may contain additional options on top + of those listed here. If systemd encounters an unknown + option it will write a warning log message but + continue loading the unit. If an option is prefixed + with <option>X-</option> it is ignored completely by + systemd. Applications may use this to include + additional information in the unit files.</para> + + <para>Boolean arguments used in unit files can be + written in various formats. For positive settings the + strings <option>1</option>, <option>yes</option>, + <option>true</option> and <option>on</option> are + equivalent. For negative settings the strings + <option>0</option>, <option>no</option>, + <option>false</option> and <option>off</option> are + equivalent.</para> + + <para>Time span values encoded in unit files can be + written in various formats. A stand-alone number + specifies a time in seconds. If suffixed with a time + unit, the unit is honored. A concatenation of multiple + values with units is supported, in which case the + values are added up. Example: "50" refers to 50 + seconds; "2min 200ms" refers to 2 minutes plus 200 + milliseconds, i.e. 120200ms. The following time units + are understood: s, min, h, d, w, ms, us. For details + see + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>Empty lines and lines starting with # or ; are + ignored. This may be used for commenting. Lines ending + in a backslash are concatenated with the following + line while reading and the backslash is replaced by a + space character. This may be used to wrap long lines.</para> + + <para>Along with a unit file + <filename>foo.service</filename> the directory + <filename>foo.service.wants/</filename> may exist. All + unit files symlinked from such a directory are + implicitly added as dependencies of type + <varname>Wanted=</varname> to the unit. This is useful + to hook units into the start-up of other units, + without having to modify their unit files. For details + about the semantics of <varname>Wanted=</varname> see + below. The preferred way to create symlinks in the + <filename>.wants/</filename> directory of a unit file + is with the <command>enable</command> command of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool which reads information from the [Install] + section of unit files (see below). A similar + functionality exists for <varname>Requires=</varname> + type dependencies as well, the directory suffix is + <filename>.requires/</filename> in this case.</para> + + <para>Along with a unit file + <filename>foo.service</filename> a directory + <filename>foo.service.d/</filename> may exist. All + files with the suffix <filename>.conf</filename> from + this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration + settings to a unit, without having to modify their + unit files. Make sure that the file that is included + has the appropriate section headers before any + directive.</para> + + <para>If a line starts with <option>.include</option> + followed by a file name, the specified file will be + parsed at this point. Make sure that the file that is + included has the appropriate section headers before + any directives.</para> + + <para>Note that while systemd offers a flexible + dependency system between units it is recommended to + use this functionality only sparingly and instead rely + on techniques such as bus-based or socket-based + activation which make dependencies implicit, resulting + in a both simpler and more flexible system.</para> + + <para>Some unit names reflect paths existing in the + file system name space. Example: a device unit + <filename>dev-sda.device</filename> refers to a device + with the device node <filename>/dev/sda</filename> in + the file system namespace. If this applies a special + way to escape the path name is used, so that the + result is usable as part of a file name. Basically, + given a path, "/" is replaced by "-", and all + unprintable characters and the "-" are replaced by + C-style "\x20" escapes. The root directory "/" is + encoded as single dash, while otherwise the initial + and ending "/" is removed from all paths during + transformation. This escaping is reversible.</para> + + <para>Optionally, units may be instantiated from a + template file at runtime. This allows creation of + multiple units from a single configuration file. If + systemd looks for a unit configuration file it will + first search for the literal unit name in the + filesystem. If that yields no success and the unit + name contains an @ character, systemd will look for a + unit template that shares the same name but with the + instance string (i.e. the part between the @ character + and the suffix) removed. Example: if a service + <filename>getty@tty3.service</filename> is requested + and no file by that name is found, systemd will look + for <filename>getty@.service</filename> and + instantiate a service from that configuration file if + it is found.</para> + + <para>To refer to the instance string from + within the configuration file you may use the special + <literal>%i</literal> specifier in many of the + configuration options. See below for details.</para> + + <para>If a unit file is empty (i.e. has the file size + 0) or is symlinked to <filename>/dev/null</filename> + its configuration will not be loaded and it appears + with a load state of <literal>masked</literal>, and + cannot be activated. Use this as an effective way to + fully disable a unit, making it impossible to start it + even manually.</para> + + <para>The unit file format is covered by the + <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + + </refsect1> + + <refsect1> + <title>Unit load path</title> + + <para>Unit files are loaded from a set of paths + determined during compilation, described in the two + tables below. Unit files found in directories higher + in the hierarchy override files with the same name + lower in the hierarchy, thus allowing overrides. + </para> + + <para>When systemd is running in session mode + (<option>--user</option>) and the variable + <varname>$SYSTEMD_UNIT_PATH</varname> is set, this + contents of this variable overrides the unit load + path. + </para> + + <table> + <title> + Load path when running in system mode (<option>--system</option>). + </title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Path</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/run/systemd/generator.early</filename></entry> + <entry>Generated units</entry> + </row> + <row> + <entry><filename>@SYSTEM_CONFIG_UNIT_PATH@</filename></entry> + <entry morerows='1'>Local configuration</entry> + </row> + <row> + <entry><filename>/etc/systemd/system</filename></entry> + </row> + <row> + <entry><filename>/run/systemd/systemd</filename></entry> + <entry>Volatile units</entry> + </row> + <row> + <entry><filename>/run/systemd/generator</filename></entry> + <entry>Generated units</entry> + </row> + <row> + <entry><filename>/usr/local/lib/systemd/system</filename></entry> + <entry>Units for local packages</entry> + </row> + <row> + <entry><filename>@systemunitdir@</filename></entry> + <entry>Systemd package configuration</entry> + </row> + <row> + <entry><filename>/usr/lib/systemd/system</filename></entry> + <entry morerows='1'>Units for installed packages</entry> + </row> + <row> + <entry><filename>/lib/systemd/system</filename></entry> + </row> + <row> + <entry><filename>/run/systemd/generator.late</filename></entry> + <entry>Generated units</entry> + </row> + </tbody> + </tgroup> + </table> + + <table> + <title> + Load path when running in session mode (<option>--user</option>). + </title> + + <tgroup cols='2'> + <colspec colname='path' /> + <colspec colname='expl' /> + <thead> + <row> + <entry>Path</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><filename>/tmp/systemd-generator.early.<replaceable>XXXXXX</replaceable></filename></entry> + <entry>Generated units</entry> + </row> + <row> + <entry><filename>@USER_CONFIG_UNIT_PATH@</filename></entry> + <entry morerows='1'>Local configuration</entry> + </row> + <row> + <entry><filename>/etc/systemd/user</filename></entry> + </row> + <row> + <entry><filename>/run/systemd/user</filename></entry> + <entry>Volatile units</entry> + </row> + <row> + <entry><filename>/tmp/systemd-generator.<replaceable>XXXXXX</replaceable></filename></entry> + <entry>Generated units</entry> + </row> + <row> + <entry><filename>/usr/local/lib/systemd/user</filename></entry> + <entry morerows='1'>Units for local packages</entry> + </row> + <row> + <entry><filename>/usr/local/share/systemd/user</filename></entry> + </row> + <row> + <entry><filename>@userunitdir@</filename></entry> + <entry>Systemd package configuration</entry> + </row> + <row> + <entry><filename>/usr/lib/systemd/user</filename></entry> + <entry morerows='1'>Units for installed packages</entry> + </row> + <row> + <entry><filename>/usr/share/systemd/user</filename></entry> + </row> + <row> + <entry><filename>/tmp/systemd-generator.late.<replaceable>XXXXXX</replaceable></filename></entry> + <entry>Generated units</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Note: the paths listed above are set at + compilation time and differ between distributions. The + "authorative" list is printed by + <command>systemd</command> at during start and daemon + reconfiguration.</para> + + <para>Additional units might be loaded into systemd + ("linked") from directories not on the unit load + path. See the <command>link</command> command for + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Unit file may include a [Unit] section, which + carries generic information about the unit that is not + dependent on the type of unit:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>Description=</varname></term> + <listitem><para>A free-form string + describing the unit. This is intended + for use in UIs to show descriptive + information along with the unit + name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Documentation=</varname></term> + <listitem><para>A space separated list + of URIs referencing documentation for + this unit or its + configuration. Accepted are only URIs + of the types + <literal>http://</literal>, + <literal>https://</literal>, + <literal>file:</literal>, + <literal>info:</literal>, + <literal>man:</literal>. For more + information about the syntax of these + URIs see + <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + URIs should be listed in order of + relevance, starting with the most + relevant. It is a good idea to first + reference documentation that explains + what the unit's purpose is, followed + by how it is configured, followed by + any other related documentation. This + option may be specified more than once + in which case the specified list of + URIs is merged. If the empty string is + assigned to this option the list is + reset and all prior assignments will + have no effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Requires=</varname></term> + + <listitem><para>Configures requirement + dependencies on other units. If this + unit gets activated, the units listed + here will be activated as well. If one + of the other units gets deactivated or + its activation fails, this unit will + be deactivated. This option may be + specified more than once, in which + case requirement dependencies for all + listed names are created. Note that + requirement dependencies do not + influence the order in which services + are started or stopped. This has to be + configured independently with the + <varname>After=</varname> or + <varname>Before=</varname> options. If + a unit + <filename>foo.service</filename> + requires a unit + <filename>bar.service</filename> as + configured with + <varname>Requires=</varname> and no + ordering is configured with + <varname>After=</varname> or + <varname>Before=</varname>, then both + units will be started simultaneously + and without any delay between them if + <filename>foo.service</filename> is + activated. Often it is a better choice + to use <varname>Wants=</varname> + instead of + <varname>Requires=</varname> in order + to achieve a system that is more + robust when dealing with failing + services.</para> + + <para>Note that dependencies of this + type may also be configured outside of + the unit configuration file by + adding a symlink to a + <filename>.requires/</filename> directory + accompanying the unit file. For + details see above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RequiresOverridable=</varname></term> + + <listitem><para>Similar to + <varname>Requires=</varname>. + Dependencies listed in + <varname>RequiresOverridable=</varname> + which cannot be fulfilled or fail to + start are ignored if the startup was + explicitly requested by the user. If + the start-up was pulled in indirectly + by some dependency or automatic + start-up of units that is not + requested by the user this dependency + must be fulfilled and otherwise the + transaction fails. Hence, this option + may be used to configure dependencies + that are normally honored unless the + user explicitly starts up the unit, in + which case whether they failed or not + is irrelevant.</para></listitem> + + </varlistentry> + <varlistentry> + <term><varname>Requisite=</varname></term> + <term><varname>RequisiteOverridable=</varname></term> + + <listitem><para>Similar to + <varname>Requires=</varname> + and <varname>RequiresOverridable=</varname>, respectively. However, + if a unit listed here is not started + already it will not be started and the + transaction fails + immediately.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Wants=</varname></term> + + <listitem><para>A weaker version of + <varname>Requires=</varname>. A unit + listed in this option will be started + if the configuring unit is. However, + if the listed unit fails to start up + or cannot be added to the transaction + this has no impact on the validity of + the transaction as a whole. This is + the recommended way to hook start-up + of one unit to the start-up of another + unit.</para> + + <para>Note that dependencies of this + type may also be configured outside of + the unit configuration file by + adding a symlink to a + <filename>.wants/</filename> directory + accompanying the unit file. For + details see above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BindsTo=</varname></term> + + <listitem><para>Configures requirement + dependencies, very similar in style to + <varname>Requires=</varname>, however + in addition to this behavior it also + declares that this unit is stopped + when any of the units listed suddenly + disappears. Units can suddenly, + unexpectedly disappear if a service + terminates on its own choice, a device + is unplugged or a mount point + unmounted without involvement of + systemd.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PartOf=</varname></term> + + <listitem><para>Configures dependencies + similar to <varname>Requires=</varname>, + but limited to stopping and restarting + of units. When systemd stops or restarts + the units listed here, the action is + propagated to this unit. + Note that this is a one way dependency - + changes to this unit do not affect the + listed units. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Conflicts=</varname></term> + + <listitem><para>Configures negative + requirement dependencies. If a unit + has a + <varname>Conflicts=</varname> setting + on another unit, starting the former + will stop the latter and vice + versa. Note that this setting is + independent of and orthogonal to the + <varname>After=</varname> and + <varname>Before=</varname> ordering + dependencies.</para> + + <para>If a unit A that conflicts with + a unit B is scheduled to be started at + the same time as B, the transaction + will either fail (in case both are + required part of the transaction) or + be modified to be fixed (in case one + or both jobs are not a required part + of the transaction). In the latter + case the job that is not the required + will be removed, or in case both are + not required the unit that conflicts + will be started and the unit that is + conflicted is + stopped.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Before=</varname></term> + <term><varname>After=</varname></term> + + <listitem><para>Configures ordering + dependencies between units. If a unit + <filename>foo.service</filename> + contains a setting + <option>Before=bar.service</option> + and both units are being started, + <filename>bar.service</filename>'s + start-up is delayed until + <filename>foo.service</filename> is + started up. Note that this setting is + independent of and orthogonal to the + requirement dependencies as configured + by <varname>Requires=</varname>. It is + a common pattern to include a unit + name in both the + <varname>After=</varname> and + <varname>Requires=</varname> option in + which case the unit listed will be + started before the unit that is + configured with these options. This + option may be specified more than + once, in which case ordering + dependencies for all listed names are + created. <varname>After=</varname> is + the inverse of + <varname>Before=</varname>, i.e. while + <varname>After=</varname> ensures that + the configured unit is started after + the listed unit finished starting up, + <varname>Before=</varname> ensures the + opposite, i.e. that the configured + unit is fully started up before the + listed unit is started. Note that when + two units with an ordering dependency + between them are shut down, the + inverse of the start-up order is + applied. i.e. if a unit is configured + with <varname>After=</varname> on + another unit, the former is stopped + before the latter if both are shut + down. If one unit with an ordering + dependency on another unit is shut + down while the latter is started up, + the shut down is ordered before the + start-up regardless whether the + ordering dependency is actually of + type <varname>After=</varname> or + <varname>Before=</varname>. If two + units have no ordering dependencies + between them they are shut down + or started up simultaneously, and + no ordering takes + place. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailure=</varname></term> + + <listitem><para>Lists one or more + units that are activated when this + unit enters the + '<literal>failed</literal>' + state.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PropagatesReloadTo=</varname></term> + <term><varname>ReloadPropagatedFrom=</varname></term> + + <listitem><para>Lists one or more + units where reload requests on the + unit will be propagated to/on the + other unit will be propagated + from. Issuing a reload request on a + unit will automatically also enqueue a + reload request on all units that the + reload request shall be propagated to + via these two + settings.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RequiresMountsFor=</varname></term> + + <listitem><para>Takes a space + separated list of absolute paths. Automatically + adds dependencies of type + <varname>Requires=</varname> and + <varname>After=</varname> for all + mount units required to access the + specified path.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>OnFailureIsolate=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> the + unit listed in + <varname>OnFailure=</varname> will be + enqueued in isolation mode, i.e. all + units that are not its dependency will + be stopped. If this is set only a + single unit may be listed in + <varname>OnFailure=</varname>. Defaults + to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreOnIsolate=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit will not be stopped when + isolating another unit. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>IgnoreOnSnapshot=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit will not be included in + snapshots. Defaults to + <option>true</option> for device and + snapshot units, <option>false</option> + for the others.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>StopWhenUnneeded=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit will be stopped when it is + no longer used. Note that in order to + minimize the work to be executed, + systemd will not stop units by default + unless they are conflicting with other + units, or the user explicitly + requested their shut down. If this + option is set, a unit will be + automatically cleaned up if no other + active unit requires it. Defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>RefuseManualStart=</varname></term> + <term><varname>RefuseManualStop=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit can only be activated + or deactivated indirectly. In + this case explicit start-up + or termination requested by the + user is denied, however if it is + started or stopped as a + dependency of another unit, start-up + or termination will succeed. This + is mostly a safety feature to ensure + that the user does not accidentally + activate units that are not intended + to be activated explicitly, and not + accidentally deactivate units that are + not intended to be deactivated. + These options default to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>AllowIsolate=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + this unit may be used with the + <command>systemctl isolate</command> + command. Otherwise this will be + refused. It probably is a good idea to + leave this disabled except for target + units that shall be used similar to + runlevels in SysV init systems, just + as a precaution to avoid unusable + system states. This option defaults to + <option>false</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DefaultDependencies=</varname></term> + + <listitem><para>Takes a boolean + argument. If <option>true</option> + (the default), a few default + dependencies will implicitly be + created for the unit. The actual + dependencies created depend on the + unit type. For example, for service + units, these dependencies ensure that + the service is started only after + basic system initialization is + completed and is properly terminated on + system shutdown. See the respective + man pages for details. Generally, only + services involved with early boot or + late shutdown should set this option + to <option>false</option>. It is + highly recommended to leave this + option enabled for the majority of + common units. If set to + <option>false</option> this option + does not disable all implicit + dependencies, just non-essential + ones.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>JobTimeoutSec=</varname></term> + + <listitem><para>When clients are + waiting for a job of this unit to + complete, time out after the specified + time. If this time limit is reached + the job will be cancelled, the unit + however will not change state or even + enter the '<literal>failed</literal>' + mode. This value defaults to 0 (job + timeouts disabled), except for device + units. NB: this timeout is independent + from any unit-specific timeout (for + example, the timeout set with + <varname>Timeout=</varname> in service + units) as the job timeout has no + effect on the unit itself, only on the + job that might be pending for it. Or + in other words: unit-specific timeouts + are useful to abort unit state + changes, and revert them. The job + timeout set with this option however + is useful to abort only the job + waiting for the unit state to + change.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ConditionPathExists=</varname></term> + <term><varname>ConditionPathExistsGlob=</varname></term> + <term><varname>ConditionPathIsDirectory=</varname></term> + <term><varname>ConditionPathIsSymbolicLink=</varname></term> + <term><varname>ConditionPathIsMountPoint=</varname></term> + <term><varname>ConditionPathIsReadWrite=</varname></term> + <term><varname>ConditionDirectoryNotEmpty=</varname></term> + <term><varname>ConditionFileNotEmpty=</varname></term> + <term><varname>ConditionFileIsExecutable=</varname></term> + <term><varname>ConditionKernelCommandLine=</varname></term> + <term><varname>ConditionVirtualization=</varname></term> + <term><varname>ConditionSecurity=</varname></term> + <term><varname>ConditionCapability=</varname></term> + <term><varname>ConditionHost=</varname></term> + <term><varname>ConditionACPower=</varname></term> + <term><varname>ConditionNull=</varname></term> + + <listitem><para>Before starting a unit + verify that the specified condition is + true. If it is not true the starting + of the unit will be skipped, however + all ordering dependencies of it are + still respected. A failing condition + will not result in the unit being + moved into a failure state. The + condition is checked at the time the + queued start job is to be + executed.</para> + + <para>With + <varname>ConditionPathExists=</varname> + a file existence condition is + checked before a unit is started. If + the specified absolute path name does + not exist the condition will + fail. If the absolute path name passed + to + <varname>ConditionPathExists=</varname> + is prefixed with an exclamation mark + ('!'), the test is negated, and the unit + is only started if the path does not + exist.</para> + + <para><varname>ConditionPathExistsGlob=</varname> + is similar to + <varname>ConditionPathExists=</varname>, + but checks for the existence of at + least one file or directory matching + the specified globbing pattern.</para> + + <para><varname>ConditionPathIsDirectory=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a + directory.</para> + + <para><varname>ConditionPathIsSymbolicLink=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a symbolic + link.</para> + + <para><varname>ConditionPathIsMountPoint=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a mount + point.</para> + + <para><varname>ConditionPathIsReadWrite=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether the underlying + file system is readable and writable + (i.e. not mounted + read-only).</para> + + <para><varname>ConditionDirectoryNotEmpty=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and is a non-empty + directory.</para> + + <para><varname>ConditionFileNotEmpty=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists and refers to a regular file + with a non-zero size.</para> + + <para><varname>ConditionFileIsExecutable=</varname> + is similar to + <varname>ConditionPathExists=</varname> + but verifies whether a certain path + exists, is a regular file and marked + executable.</para> + + <para>Similar, + <varname>ConditionKernelCommandLine=</varname> + may be used to check whether a + specific kernel command line option is + set (or if prefixed with the + exclamation mark unset). The argument + must either be a single word, or an + assignment (i.e. two words, separated + '='). In the former + case the kernel command line is + searched for the word appearing as is, + or as left hand side of an + assignment. In the latter case the + exact assignment is looked for with + right and left hand side + matching.</para> + + <para><varname>ConditionVirtualization=</varname> + may be used to check whether the + system is executed in a virtualized + environment and optionally test + whether it is a specific + implementation. Takes either boolean + value to check if being executed in + any virtualized environment, or one of + <varname>vm</varname> and + <varname>container</varname> to test + against a generic type of + virtualization solution, or one of + <varname>qemu</varname>, + <varname>kvm</varname>, + <varname>vmware</varname>, + <varname>microsoft</varname>, + <varname>oracle</varname>, + <varname>xen</varname>, + <varname>bochs</varname>, + <varname>chroot</varname>, + <varname>openvz</varname>, + <varname>lxc</varname>, + <varname>lxc-libvirt</varname>, + <varname>systemd-nspawn</varname> to + test against a specific + implementation. If multiple + virtualization technologies are nested + only the innermost is considered. The + test may be negated by prepending an + exclamation mark.</para> + + <para><varname>ConditionSecurity=</varname> + may be used to check whether the given + security module is enabled on the + system. Currently the only recognized + value is <varname>selinux</varname>. + The test may be negated by prepending + an exclamation + mark.</para> + + <para><varname>ConditionCapability=</varname> + may be used to check whether the given + capability exists in the capability + bounding set of the service manager + (i.e. this does not check whether + capability is actually available in + the permitted or effective sets, see + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details). Pass a capability name + such as <literal>CAP_MKNOD</literal>, + possibly prefixed with an exclamation + mark to negate the check.</para> + + <para><varname>ConditionHost=</varname> + may be used to match against the + host name or machine ID of the + host. This either takes a host name + string (optionally with shell style + globs) which is tested against the + locally set host name as returned by + <citerefentry><refentrytitle>gethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + or a machine ID formatted as string + (see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + The test may be negated by prepending + an exclamation mark.</para> + + <para><varname>ConditionACPower=</varname> + may be used to check whether the + system has AC power, or is exclusively + battery powered at the time of + activation of the unit. This takes a + boolean argument. If set to + <varname>true</varname> the condition + will hold only if at least one AC + connector of the system is connected + to a power source, or if no AC + connectors are known. Conversely, if + set to <varname>false</varname> the + condition will hold only if there is + at least one AC connector known and + all AC connectors are disconnected + from a power source.</para> + + <para>Finally, + <varname>ConditionNull=</varname> may + be used to add a constant condition + check value to the unit. It takes a + boolean argument. If set to + <varname>false</varname> the condition + will always fail, otherwise + succeed.</para> + + <para>If multiple conditions are + specified the unit will be executed if + all of them apply (i.e. a logical AND + is applied). Condition checks can be + prefixed with a pipe symbol (|) in + which case a condition becomes a + triggering condition. If at least one + triggering condition is defined for a + unit then the unit will be executed if + at least one of the triggering + conditions apply and all of the + non-triggering conditions. If you + prefix an argument with the pipe + symbol and an exclamation mark the + pipe symbol must be passed first, the + exclamation second. Except for + <varname>ConditionPathIsSymbolicLink=</varname>, + all path checks follow symlinks. If + any of these options is assigned the + empty string the list of conditions is + reset completely, all previous + condition settings (of any kind) will + have no effect.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SourcePath=</varname></term> + <listitem><para>A path to a + configuration file this unit has been + generated from. This is primarily + useful for implementation of generator + tools that convert configuration from + an external configuration file format + into native unit files. Thus + functionality should not be used in + normal units.</para></listitem> + </varlistentry> + </variablelist> + + <para>Unit file may include a [Install] section, which + carries installation information for the unit. This + section is not interpreted by + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + during runtime. It is used exclusively by the + <command>enable</command> and + <command>disable</command> commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool during installation of a unit:</para> + + <variablelist class='unit-directives'> + <varlistentry> + <term><varname>Alias=</varname></term> + + <listitem><para>Additional names this + unit shall be installed under. The + names listed here must have the same + suffix (i.e. type) as the unit file + name. This option may be specified + more than once, in which case all + listed names are used. At installation + time, + <command>systemctl enable</command> + will create symlinks from these names + to the unit file name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>WantedBy=</varname></term> + <term><varname>RequiredBy=</varname></term> + + <listitem><para>Installs a symlink in + the <filename>.wants/</filename> + or <filename>.requires/</filename> + subdirectory for a unit, respectively. This has the + effect that when the listed unit name + is activated the unit listing it is + activated + too. <command>WantedBy=foo.service</command> + in a service + <filename>bar.service</filename> is + mostly equivalent to + <command>Alias=foo.service.wants/bar.service</command> + in the same file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Also=</varname></term> + + <listitem><para>Additional units to + install when this unit is + installed. If the user requests + installation of a unit with this + option configured, + <command>systemctl enable</command> + will automatically install units + listed in this option as + well.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following specifiers are interpreted in the + Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b. + For their meaning see the next section. + </para> + </refsect1> + + <refsect1> + <title>Specifiers</title> + + <para>Many settings resolve specifiers which may be + used to write generic unit files referring to runtime + or unit parameters that are replaced when the unit + files are loaded. The following specifiers are + understood:</para> + + <table> + <title>Specifiers available in unit files</title> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname="spec" /> + <colspec colname="mean" /> + <colspec colname="detail" /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Meaning</entry> + <entry>Details</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>%n</literal></entry> + <entry>Full unit name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%N</literal></entry> + <entry>Unescaped full unit name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%p</literal></entry> + <entry>Prefix name</entry> + <entry>For instantiated units this refers to the string before the @. For non-instantiated units this refers to to the name of the unit with the type suffix removed.</entry> + </row> + <row> + <entry><literal>%P</literal></entry> + <entry>Unescaped prefix name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%i</literal></entry> + <entry>Instance name</entry> + <entry>For instantiated units: this is the string between the @ character and the suffix.</entry> + </row> + <row> + <entry><literal>%I</literal></entry> + <entry>Unescaped instance name</entry> + <entry></entry> + </row> + <row> + <entry><literal>%f</literal></entry> + <entry>Unescaped file name</entry> + <entry>This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /.</entry> + </row> + <row> + <entry><literal>%c</literal></entry> + <entry>Control group path of the unit</entry> + <entry></entry> + </row> + <row> + <entry><literal>%r</literal></entry> + <entry>Root control group path of systemd</entry> + <entry></entry> + </row> + <row> + <entry><literal>%R</literal></entry> + <entry>Parent directory of the root control group path of systemd</entry> + <entry></entry> + </row> + <row> + <entry><literal>%t</literal></entry> + <entry>Runtime socket dir</entry> + <entry>This is either <filename>/run</filename> (for the system manager) or <literal>$XDG_RUNTIME_DIR</literal> (for user managers).</entry> + </row> + <row> + <entry><literal>%u</literal></entry> + <entry>User name</entry> + <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> + </row> + <row> + <entry><literal>%U</literal></entry> + <entry>User UID</entry> + <entry>This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> + </row> + <row> + <entry><literal>%h</literal></entry> + <entry>User home directory</entry> + <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry> + </row> + <row> + <entry><literal>%s</literal></entry> + <entry>User shell</entry> + <entry>This is the shell of the configured + user of the unit, or (if none is set) the user + running the systemd instance. If the user is + <literal>root</literal> (UID equal to 0), the + shell configured in account database is + ignored and <filename>/bin/sh</filename> is + always used. + </entry> + </row> + <row> + <entry><literal>%m</literal></entry> + <entry>Machine ID</entry> + <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> + </row> + <row> + <entry><literal>%b</literal></entry> + <entry>Boot ID</entry> + <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry> + </row> + <row> + <entry><literal>%H</literal></entry> + <entry>Host name</entry> + <entry>The host name of the running system.</entry> + </row> + <row> + <entry><literal>%%</literal></entry> + <entry>Escaped %</entry> + <entry>Single percent sign.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |