X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=2e298ca04f06caaa6318735a288c1bb4512eca9e;hp=b1f8108984377dd76e45e62b2dcab985d819efb3;hb=d55192add75584f55932ad463ee6b4cc30370c63;hpb=e26807239bd65bc17535a53cd540f38600e7ef24 diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index b1f810898..2e298ca04 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -73,7 +73,10 @@ $XDG_CONFIG_HOME/systemd/user/* $HOME/.config/systemd/user/* /etc/systemd/user/* +$XDG_RUNTIME_DIR/systemd/user/* /run/systemd/user/* +$XDG_DATA_HOME/systemd/user/* +$HOME/.local/share/systemd/user/* /usr/lib/systemd/user/* ... @@ -178,10 +181,10 @@ foo.service.wants/ may exist. All unit files symlinked from such a directory are implicitly added as dependencies of type - Wanted= to the unit. This is useful + Wants= 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 Wanted=, see + about the semantics of Wants=, see below. The preferred way to create symlinks in the .wants/ directory of a unit file is with the enable command of the @@ -201,7 +204,16 @@ 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. + directive. Note that for instanced units this logic + will first look for the instance + .d/ subdirectory and read its + .conf files, followed by the + template .d/ subdirectory and reads + its .conf files. + + Note that while systemd offers a flexible dependency system between units it is recommended to @@ -219,7 +231,7 @@ result is usable as part of a filename. Basically, given a path, "/" is replaced by "-", and all unprintable characters and the "-" are replaced by - C-style "\x20" escapes. The root directory "/" is + C-style "\x2d" 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. @@ -273,8 +285,10 @@ () and the variable $SYSTEMD_UNIT_PATH is set, this contents of this variable overrides the unit load - path. - + path. If $SYSTEMD_UNIT_PATH ends + with an empty component (:), the + usual unit load path will be appended to the contents + of the variable. @@ -334,13 +348,25 @@ <entry><filename>/etc/systemd/user</filename></entry> <entry>Local configuration</entry> </row> + <row> + <entry><filename>$XDG_RUNTIME_DIR/systemd/user</filename></entry> + <entry>Runtime units (only used when $XDG_RUNTIME_DIR is set)</entry> + </row> <row> <entry><filename>/run/systemd/user</filename></entry> <entry>Runtime units</entry> </row> + <row> + <entry><filename>$XDG_DATA_HOME/systemd/user</filename></entry> + <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)</entry> + </row> + <row> + <entry><filename>$HOME/.local/share/systemd/user</filename></entry> + <entry>Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)</entry> + </row> <row> <entry><filename>/usr/lib/systemd/user</filename></entry> - <entry>Units of installed packages</entry> + <entry>Units of packages that have been installed system-wide</entry> </row> </tbody> </tgroup> @@ -396,7 +422,7 @@ <literal>man:</literal>. For more information about the syntax of these URIs, see - <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + <citerefentry project='man-pages'><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 @@ -866,20 +892,22 @@ <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 + <term><varname>JobTimeoutAction=</varname></term> + <term><varname>JobTimeoutRebootArgument=</varname></term> + + <listitem><para>When a job for this + unit is queued a time-out may be + configured. 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 + <varname>StartTimeoutSec=</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 @@ -889,7 +917,22 @@ timeout set with this option however is useful to abort only the job waiting for the unit state to - change.</para></listitem> + change.</para> + + <para><varname>JobTimeoutAction=</varname> + optionally configures an additional + action to take when the time-out is + hit. It takes the same values as the + per-service + <varname>StartLimitAction=</varname> + setting, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. 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> </varlistentry> <varlistentry> @@ -911,7 +954,11 @@ <term><varname>ConditionDirectoryNotEmpty=</varname></term> <term><varname>ConditionFileNotEmpty=</varname></term> <term><varname>ConditionFileIsExecutable=</varname></term> - <term><varname>ConditionNull=</varname></term> + + <!-- We don't document ConditionNull= + here as it is not particularly + useful and probably just + confusing. --> <listitem><para>Before starting a unit verify that the specified condition is @@ -986,6 +1033,7 @@ virtualization solution, or one of <varname>qemu</varname>, <varname>kvm</varname>, + <varname>zvm</varname>, <varname>vmware</varname>, <varname>microsoft</varname>, <varname>oracle</varname>, @@ -995,13 +1043,17 @@ <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> + <varname>systemd-nspawn</varname>, + <varname>docker</varname> to test + against a specific implementation. See + <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for a full list of known + virtualization technologies and their + identifiers. If multiple + virtualization technologies are + nested, only the innermost is + considered. The test may be negated by + prepending an exclamation mark.</para> <para><varname>ConditionHost=</varname> may be used to match against the @@ -1036,14 +1088,15 @@ <para><varname>ConditionSecurity=</varname> may be used to check whether the given security module is enabled on the - system. Currently the recognized values - values are <varname>selinux</varname>, + system. Currently the recognized + values values are + <varname>selinux</varname>, <varname>apparmor</varname>, - <varname>ima</varname> and - <varname>smack</varname>. - The test may be negated by prepending - an exclamation - mark.</para> + <varname>ima</varname>, + <varname>smack</varname> and + <varname>audit</varname>. The test may + be negated by prepending an + exclamation mark.</para> <para><varname>ConditionCapability=</varname> may be used to check whether the given @@ -1052,7 +1105,7 @@ (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> + <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details). Pass a capability name such as <literal>CAP_MKNOD</literal>, possibly prefixed with an exclamation @@ -1185,15 +1238,6 @@ exists, is a regular file and marked executable.</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 @@ -1219,6 +1263,38 @@ have no effect.</para></listitem> </varlistentry> + <varlistentry> + <term><varname>AssertArchitecture=</varname></term> + <term><varname>AssertVirtualization=</varname></term> + <term><varname>AssertHost=</varname></term> + <term><varname>AssertKernelCommandLine=</varname></term> + <term><varname>AssertSecurity=</varname></term> + <term><varname>AssertCapability=</varname></term> + <term><varname>AssertACPower=</varname></term> + <term><varname>AssertNeedsUpdate=</varname></term> + <term><varname>AssertFirstBoot=</varname></term> + <term><varname>AssertPathExists=</varname></term> + <term><varname>AssertPathExistsGlob=</varname></term> + <term><varname>AssertPathIsDirectory=</varname></term> + <term><varname>AssertPathIsSymbolicLink=</varname></term> + <term><varname>AssertPathIsMountPoint=</varname></term> + <term><varname>AssertPathIsReadWrite=</varname></term> + <term><varname>AssertDirectoryNotEmpty=</varname></term> + <term><varname>AssertFileNotEmpty=</varname></term> + <term><varname>AssertFileIsExecutable=</varname></term> + + <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 it was triggered by.</para></listitem> + </varlistentry> + <varlistentry> <term><varname>SourcePath=</varname></term> <listitem><para>A path to a @@ -1238,9 +1314,10 @@ <refsect1> <title>[Install] Section Options - Unit file may include a [Install] section, which - carries installation information for the unit. This - section is not interpreted by + Unit file may include an + [Install] section, which carries + installation information for the unit. This section is + not interpreted by systemd1 during runtime. It is used exclusively by the enable and @@ -1252,7 +1329,7 @@ Alias= - A space-seperated list + A space-separated list of additional names this unit shall be installed under. The names listed here must have the same suffix (i.e. type) @@ -1485,7 +1562,7 @@ See Also systemd1, - systemctl8, + systemctl1, systemd.special7, systemd.service5, systemd.socket5, @@ -1500,7 +1577,8 @@ systemd.scope5, systemd.slice5, systemd.time7, - capabilities7, + systemd-verify1, + capabilities7, systemd.directives7, uname1