diff options
Diffstat (limited to 'man/systemd.unit.xml')
| -rw-r--r-- | man/systemd.unit.xml | 216 |
1 files changed, 130 insertions, 86 deletions
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 7605c43375..7e1b3cb7eb 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > @@ -39,19 +39,26 @@ <filename><replaceable>slice</replaceable>.slice</filename>, <filename><replaceable>scope</replaceable>.scope</filename></para> - <para><literallayout><filename>/etc/systemd/system.control/*</filename> + <refsect2> + <title>System Unit Search Path</title> + + <para><literallayout><filename>/etc/systemd/system.control/*</filename> <filename>/run/systemd/system.control/*</filename> <filename>/run/systemd/transient/*</filename> <filename>/run/systemd/generator.early/*</filename> <filename>/etc/systemd/system/*</filename> +<filename>/etc/systemd/systemd.attached/*</filename> <filename>/run/systemd/system/*</filename> +<filename>/run/systemd/systemd.attached/*</filename> <filename>/run/systemd/generator/*</filename> <filename>…</filename> <filename>/usr/lib/systemd/system/*</filename> -<filename>/run/systemd/generator.late/*</filename> - </literallayout></para> +<filename>/run/systemd/generator.late/*</filename></literallayout></para> + </refsect2> - <para><literallayout><filename>~/.config/systemd/user.control/*</filename> + <refsect2> + <title>User Unit Search Path</title> + <para><literallayout><filename>~/.config/systemd/user.control/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/user.control/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/transient/*</filename> <filename>$XDG_RUNTIME_DIR/systemd/generator.early/*</filename> @@ -63,8 +70,9 @@ <filename>~/.local/share/systemd/user/*</filename> <filename>…</filename> <filename>/usr/lib/systemd/user/*</filename> -<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename> - </literallayout></para> +<filename>$XDG_RUNTIME_DIR/systemd/generator.late/*</filename></literallayout></para> + </refsect2> + </refsynopsisdiv> <refsect1> @@ -118,23 +126,6 @@ do not need the prefix. 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: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to - 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood: - <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>, - <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see - <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name in one of the unit search paths. For example, <filename>systemd-networkd.service</filename> has the alias @@ -334,7 +325,7 @@ <row> <entry><filename>/run/systemd/generator.early</filename></entry> <entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>/etc/systemd/system</filename></entry> @@ -347,7 +338,7 @@ <row> <entry><filename>/run/systemd/generator</filename></entry> <entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>/usr/local/lib/systemd/system</filename></entry> @@ -359,7 +350,7 @@ <row> <entry><filename>/run/systemd/generator.late</filename></entry> <entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> </tbody> </tgroup> @@ -395,7 +386,7 @@ <row> <entry><filename>/run/systemd/generator.early</filename></entry> <entry>Generated units with high priority (see <replaceable>early-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename> or <filename>$HOME/.config/systemd/user</filename></entry> @@ -416,7 +407,7 @@ <row> <entry><filename>$XDG_RUNTIME_DIR/systemd/generator</filename></entry> <entry>Generated units with medium priority (see <replaceable>normal-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> <row> <entry><filename>$XDG_DATA_HOME/systemd/user</filename> or <filename>$HOME/.local/share/systemd/user</filename></entry> @@ -436,7 +427,7 @@ <row> <entry><filename>$XDG_RUNTIME_DIR/systemd/generator.late</filename></entry> <entry>Generated units with low priority (see <replaceable>late-dir</replaceable> in <citerefentry - ><refentrytitle>system.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> + ><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>)</entry> </row> </tbody> </tgroup> @@ -511,15 +502,21 @@ <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. The description should contain a - name that means something to the end user. <literal>Apache2 - Web Server</literal> is a good example. Bad examples are - <literal>high-performance light-weight HTTP server</literal> - (too generic) or <literal>Apache2</literal> (too specific and - meaningless for people who do not know - Apache).</para></listitem> + <listitem><para>A human readable name for the unit. This is used by + <command>systemd</command> (and other UIs) as the label for the unit, so this string should + identify the unit rather than describe it, despite the name. <literal>Apache2 Web + Server</literal> is a good example. Bad examples are <literal>high-performance light-weight + HTTP server</literal> (too generic) or <literal>Apache2</literal> (too specific and + meaningless for people who do not know Apache). <command>systemd</command> will use this + string as a noun in status messages (<literal>Starting + <replaceable>description</replaceable>...</literal>, <literal>Started + <replaceable>description</replaceable>.</literal>, <literal>Reached target + <replaceable>description</replaceable>.</literal>, <literal>Failed to start + <replaceable>description</replaceable>.</literal>), so it should be capitalized, and should + not be a full sentence or a phrase with a continous verb. Bad examples include + <literal>exiting the container</literal> or <literal>updating the database once per + day.</literal>.</para> + </listitem> </varlistentry> <varlistentry> @@ -668,10 +665,10 @@ <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 + fail (in case both are required parts 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 + that is not 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> @@ -874,12 +871,49 @@ </varlistentry> <varlistentry> + <term><varname>FailureAction=</varname></term> + <term><varname>SuccessAction=</varname></term> + + <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive state. + Takes one of <option>none</option>, <option>reboot</option>, <option>reboot-force</option>, + <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option>, + <option>poweroff-immediate</option>, <option>exit</option>, and <option>exit-force</option>. In system mode, + all options are allowed. In user mode, only <option>none</option>, <option>exit</option>, and + <option>exit-force</option> are allowed. Both options default to <option>none</option>.</para> + + <para>If <option>none</option> is set, no action will be triggered. <option>reboot</option> causes a reboot + following the normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>). + <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should + cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and + <option>reboot-immediate</option> causes immediate execution of the + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which + might result in data loss (i.e. equivalent to <command>systemctl reboot -ff</command>). Similarly, + <option>poweroff</option>, <option>poweroff-force</option>, <option>poweroff-immediate</option> have the effect + of powering down the system with similar semantics. <option>exit</option> causes the manager to exit following + the normal shutdown procedure, and <option>exit-force</option> causes it terminate without shutting down + services. When <option>exit</option> or <option>exit-force</option> is used by default the exit status of the + main process of the unit (if this applies) is returned from the service manager. However, this may be overriden + with <varname>FailureActionExitStatus=</varname>/<varname>SuccessActionExitStatus=</varname>, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>FailureActionExitStatus=</varname></term> + <term><varname>SuccessActionExitStatus=</varname></term> + + <listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a + system service) or service manager (in case of a user manager) when the + <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> are set to <option>exit</option> or + <option>exit-force</option> and the action is triggered. By default the exit status of the main process of the + triggering unit (if this applies) is propagated. Takes a value in the range 0…255 or the empty string to + request default behaviour.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>JobTimeoutSec=</varname></term> <term><varname>JobRunningTimeoutSec=</varname></term> - <term><varname>JobTimeoutAction=</varname></term> - <term><varname>JobTimeoutRebootArgument=</varname></term> - <listitem><para>When a job for this unit is queued, a time-out <varname>JobTimeoutSec=</varname> may be + <listitem><para>When a job for this unit is queued, a timeout <varname>JobTimeoutSec=</varname> may be configured. Similarly, <varname>JobRunningTimeoutSec=</varname> starts counting when the queued job is actually started. If either 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 <literal>infinity</literal> (job timeouts @@ -889,12 +923,20 @@ 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> - <para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when the time-out - is hit. It takes the same values as <varname>StartLimitAction=</varname>. Defaults to <option>none</option>. + <varlistentry> + <term><varname>JobTimeoutAction=</varname></term> + <term><varname>JobTimeoutRebootArgument=</varname></term> + + <listitem><para><varname>JobTimeoutAction=</varname> optionally configures an additional action to take when + the timeout is hit, see description of <varname>JobTimeoutSec=</varname> and + <varname>JobRunningTimeoutSec=</varname> above. It takes the same values as + <varname>StartLimitAction=</varname>. Defaults to <option>none</option>. <varname>JobTimeoutRebootArgument=</varname> configures an optional reboot string to pass to the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> - system call.</para></listitem> + <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call. + </para></listitem> </varlistentry> <varlistentry> @@ -929,29 +971,13 @@ <varlistentry> <term><varname>StartLimitAction=</varname></term> - <listitem><para>Configure the action to take if the rate limit configured with - <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes one of - <option>none</option>, <option>reboot</option>, <option>reboot-force</option>, - <option>reboot-immediate</option>, <option>poweroff</option>, <option>poweroff-force</option> or - <option>poweroff-immediate</option>. If <option>none</option> is set, hitting the rate limit will trigger no - action besides that the start will not be permitted. <option>reboot</option> causes a reboot following the - normal shutdown procedure (i.e. equivalent to <command>systemctl reboot</command>). - <option>reboot-force</option> causes a forced reboot which will terminate all processes forcibly but should - cause no dirty file systems on reboot (i.e. equivalent to <command>systemctl reboot -f</command>) and - <option>reboot-immediate</option> causes immediate execution of the - <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> system call, which - might result in data loss. Similarly, <option>poweroff</option>, <option>poweroff-force</option>, - <option>poweroff-immediate</option> have the effect of powering down the system with similar - semantics. Defaults to <option>none</option>.</para></listitem> + <listitem><para>Configure an additional action to take if the rate limit configured with + <varname>StartLimitIntervalSec=</varname> and <varname>StartLimitBurst=</varname> is hit. Takes the same + values as the setting <varname>FailureAction=</varname>/<varname>SuccessAction=</varname> settings and executes + the same actions. If <option>none</option> is set, hitting the rate limit will trigger no action besides that + the start will not be permitted. Defaults to <option>none</option>.</para></listitem> </varlistentry> - <varlistentry> - <term><varname>FailureAction=</varname></term> - <term><varname>SuccessAction=</varname></term> - <listitem><para>Configure the action to take when the unit stops and enters a failed state or inactive - state. Takes the same values as the setting <varname>StartLimitAction=</varname> setting and executes the same - actions. Both options default to <option>none</option>.</para></listitem> - </varlistentry> <varlistentry> <term><varname>RebootArgument=</varname></term> @@ -992,12 +1018,13 @@ <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 (mostly silently) 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. Use condition expressions in order to silently skip - units that do not apply to the local running system, for example because the kernel or runtime environment - doesn't require its functionality. Use the various <varname>AssertArchitecture=</varname>, - <varname>AssertVirtualization=</varname>, … options for a similar mechanism that puts the unit in a failure - state and logs about the failed check (see below).</para> + respected. A failing condition will not result in the unit being moved into the <literal>failed</literal> + state. The condition is checked at the time the queued start job is to be executed. Use condition expressions + in order to silently skip units that do not apply to the local running system, for example because the kernel + or runtime environment doesn't require their functionality. Use the various + <varname>AssertArchitecture=</varname>, <varname>AssertVirtualization=</varname>, … options for a similar + mechanism that causes the job to fail (instead of being skipped) and results in logging about the failed check + (instead of being silently processed). For details about assertion conditions see below.</para> <para><varname>ConditionArchitecture=</varname> may be used to check whether the system is running on a specific @@ -1226,12 +1253,12 @@ cgroup controller name (eg. <option>cpu</option>), verifying that it is available for use on the system. For example, a particular controller may not be available if it was disabled on the kernel command line with - <literal>cgroup_disable=</literal><replaceable>controller</replaceable>. - Multiple controllers may be passed with a space separating them; in - this case the condition will only pass if all listed controllers are - available for use. Controllers unknown to systemd are ignored. Valid - controllers are <option>cpu</option>, <option>cpuacct</option>, - <option>io</option>, <option>blkio</option>, <option>memory</option>, + <varname>cgroup_disable=controller</varname>. Multiple controllers may + be passed with a space separating them; in this case the condition will + only pass if all listed controllers are available for use. Controllers + unknown to systemd are ignored. Valid controllers are + <option>cpu</option>, <option>cpuacct</option>, <option>io</option>, + <option>blkio</option>, <option>memory</option>, <option>devices</option>, and <option>pids</option>.</para> <para>If multiple conditions are specified, the unit will be @@ -1278,9 +1305,16 @@ <listitem><para>Similar to the <varname>ConditionArchitecture=</varname>, <varname>ConditionVirtualization=</varname>, …, condition settings described above, these settings add assertion checks to the start-up of the unit. However, unlike the conditions settings, any assertion setting - that is not met results in failure of the start job (which means this is logged loudly). Use assertion - expressions for units that cannot operate when specific requirements are not met, and when this is something - the administrator or user should look into.</para></listitem> + that is not met results in failure of the start job (which means this is logged loudly). Note that hitting a + configured assertion does not cause the unit to enter the <literal>failed</literal> state (or in fact result in + any state change of the unit), it affects only the job queued for it. Use assertion expressions for units that + cannot operate when specific requirements are not met, and when this is something the administrator or user + should look into.</para> + + <para>Note that neither assertion nor condition expressions result in unit state changes. Also note that both + are checked at the time the job is to be executed, i.e. long after depending jobs and it itself were + queued. Thus, neither condition nor assertion expressions are suitable for conditionalizing unit + dependencies.</para></listitem> </varlistentry> <varlistentry> @@ -1495,8 +1529,8 @@ </variablelist> <para>The following specifiers are interpreted in the Install - section: %n, %N, %p, %i, %j, %U, %u, %m, %H, %b, %v. For their meaning - see the next section. + section: %n, %N, %p, %i, %j, %g, %G, %U, %u, %m, %H, %b, %v. For their + meaning see the next section. </para> </refsect1> @@ -1624,6 +1658,16 @@ <entry>This is either <filename>/tmp</filename> or the path <literal>$TMPDIR</literal>, <literal>$TEMP</literal> or <literal>$TMP</literal> are set to.</entry> </row> <row> + <entry><literal>%g</literal></entry> + <entry>User group</entry> + <entry>This is the name of the group running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry> + </row> + <row> + <entry><literal>%G</literal></entry> + <entry>User GID</entry> + <entry>This is the numeric GID of the user running the service manager instance. In case of the system manager this resolves to <literal>0</literal>.</entry> + </row> + <row> <entry><literal>%u</literal></entry> <entry>User name</entry> <entry>This is the name of the user running the service manager instance. In case of the system manager this resolves to <literal>root</literal>.</entry> |