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=918bbc41198509cc9030ac8a83c5e8559dedf085;hb=d55192add75584f55932ad463ee6b4cc30370c63;hpb=15f2a3a9930eb42e8a858c601f198431979b0b60 diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 918bbc411..2e298ca04 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -70,9 +70,13 @@ ... - $HOME/.config/systemd/user/* + $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/* ... @@ -138,10 +142,12 @@ 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 , it is ignored completely by - systemd. Applications may use this to include - additional information in the unit files. + continue loading the unit. If an option or section name + is prefixed with , it is ignored + completely by systemd. Options within an ignored + section do not need the prefix. Applications may use + this to include additional information in the unit + files. Boolean arguments used in unit files can be written in various formats. For positive settings the @@ -175,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 @@ -198,13 +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. - If a line starts with - followed by a filename, 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. + Note that while systemd offers a flexible dependency system between units it is recommended to @@ -222,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. @@ -232,7 +241,7 @@ 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 + file system. 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 @@ -276,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. @@ -325,21 +336,37 @@ </row> </thead> <tbody> + <row> + <entry><filename>$XDG_CONFIG_HOME/systemd/user</filename></entry> + <entry>User configuration (only used when $XDG_CONFIG_HOME is set)</entry> + </row> <row> <entry><filename>$HOME/.config/systemd/user</filename></entry> - <entry>User configuration</entry> + <entry>User configuration (only used when $XDG_CONFIG_HOME is not set)</entry> </row> <row> <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> @@ -356,7 +383,7 @@ </refsect1> <refsect1> - <title>Options + [Unit] Section OptionsUnit file may include a [Unit] section, which carries generic information about the unit that is not @@ -395,7 +422,7 @@ man:. For more information about the syntax of these URIs, see - uri7. The + uri7. The URIs should be listed in order of relevance, starting with the most relevant. It is a good idea to first @@ -403,7 +430,7 @@ 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 + 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 @@ -492,7 +519,7 @@ Requires= and RequiresOverridable=, respectively. However, if the units - listed here are not started already + listed here are not started already, they will not be started and the transaction will fail immediately. @@ -506,7 +533,7 @@ listed in this option will be started if the configuring unit is. However, if the listed units fail to start - or cannot be added to the transaction + 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 @@ -519,7 +546,7 @@ symlinks to a .wants/ directory accompanying the unit file. For - details see above. + details, see above. @@ -528,7 +555,7 @@ Configures requirement dependencies, very similar in style to Requires=, however - in addition to this behavior it also + in addition to this behavior, it also declares that this unit is stopped when any of the units listed suddenly disappears. Units can suddenly, @@ -548,7 +575,7 @@ 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 — + Note that this is a one-way dependency — changes to this unit do not affect the listed units. @@ -577,9 +604,9 @@ 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 + case, the job that is not the required will be removed, or in case both are - not required the unit that conflicts + not required, the unit that conflicts will be started and the unit that is conflicted is stopped. @@ -606,7 +633,7 @@ a common pattern to include a unit name in both the After= and - Requires= option in + Requires= option, in which case the unit listed will be started before the unit that is configured with these options. This @@ -634,7 +661,7 @@ 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 + start-up regardless of whether the ordering dependency is actually of type After= or Before=. If two @@ -686,13 +713,13 @@ directives (see systemd.exec5 for details). If a unit that has this - setting set is started its processes + setting set is started, its processes will see the same /tmp, /tmp/var and network namespace as one listed unit that is started. If multiple listed - units are already started it is not + units are already started, it is not defined which namespace is joined. Note that this setting only has an effect if @@ -706,13 +733,26 @@ RequiresMountsFor= - Takes a space-separated - list of absolute paths. Automatically - adds dependencies of type - Requires= and - After= for all + Takes a + space-separated list of absolute + paths. Automatically adds dependencies + of type Requires= + and After= for all mount units required to access the - specified path. + specified path. + + Mount points marked with + are not + mounted automatically and will be + ignored for the purposes of this + option. If such a mount should be a + requirement for this unit, + direct dependencies on the mount + units may be added + (Requires= and + After= or + some other combination). + @@ -852,20 +892,22 @@ JobTimeoutSec= - - 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 failed - mode. This value defaults to 0 (job - timeouts disabled), except for device + JobTimeoutAction= + JobTimeoutRebootArgument= + + 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 + failed 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 - Timeout= in service + StartTimeoutSec= 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 @@ -875,10 +917,34 @@ timeout set with this option however is useful to abort only the job waiting for the unit state to - change. + change. + + JobTimeoutAction= + optionally configures an additional + action to take when the time-out is + hit. It takes the same values as the + per-service + StartLimitAction= + setting, see + systemd.service5 + for details. Defaults to + . JobTimeoutRebootArgument= + configures an optional reboot string + to pass to the + reboot2 + system call. + ConditionArchitecture= + ConditionVirtualization= + ConditionHost= + ConditionKernelCommandLine= + ConditionSecurity= + ConditionCapability= + ConditionACPower= + ConditionNeedsUpdate= + ConditionFirstBoot= ConditionPathExists= ConditionPathExistsGlob= ConditionPathIsDirectory= @@ -888,13 +954,11 @@ ConditionDirectoryNotEmpty= ConditionFileNotEmpty= ConditionFileIsExecutable= - ConditionKernelCommandLine= - ConditionVirtualization= - ConditionSecurity= - ConditionCapability= - ConditionHost= - ConditionACPower= - ConditionNull= + + Before starting a unit verify that the specified condition is @@ -908,6 +972,201 @@ queued start job is to be executed. + ConditionArchitecture= + may be used to check whether the + system is running on a specific + architecture. Takes one of + x86, + x86-64, + ppc, + ppc-le, + ppc64, + ppc64-le, + ia64, + parisc, + parisc64, + s390, + s390x, + sparc, + sparc64, + mips, + mips-le, + mips64, + mips64-le, + alpha, + arm, + arm-be, + arm64, + arm64-be, + sh, + sh64, + m86k, + tilegx, + cris to test + against a specific architecture. The + architecture is determined from the + information returned by + uname2 + and is thus subject to + personality2. Note + that a Personality= + setting in the same unit file has no + effect on this condition. A special + architecture name + native is mapped to + the architecture the system manager + itself is compiled for. The test may + be negated by prepending an + exclamation mark. + + ConditionVirtualization= + 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 + vm and + container to test + against a generic type of + virtualization solution, or one of + qemu, + kvm, + zvm, + vmware, + microsoft, + oracle, + xen, + bochs, + uml, + openvz, + lxc, + lxc-libvirt, + systemd-nspawn, + docker to test + against a specific implementation. See + systemd-detect-virt1 + 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. + + ConditionHost= + may be used to match against the + hostname or machine ID of the + host. This either takes a hostname + string (optionally with shell style + globs) which is tested against the + locally set hostname as returned by + gethostname2, + or a machine ID formatted as string + (see + machine-id5). + The test may be negated by prepending + an exclamation mark. + + ConditionKernelCommandLine= + 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. + + ConditionSecurity= + may be used to check whether the given + security module is enabled on the + system. Currently the recognized + values values are + selinux, + apparmor, + ima, + smack and + audit. The test may + be negated by prepending an + exclamation mark. + + ConditionCapability= + 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 + capabilities7 + for details). Pass a capability name + such as CAP_MKNOD, + possibly prefixed with an exclamation + mark to negate the check. + + ConditionACPower= + 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 + true, 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 false, the + condition will hold only if there is + at least one AC connector known and + all AC connectors are disconnected + from a power source. + + ConditionNeedsUpdate= + takes one of /var + or /etc as + argument, possibly prefixed with a + ! (for inverting + the condition). This condition may be + used to conditionalize units on + whether the specified directory + requires an update because + /usr's + modification time is newer than the + stamp file + .updated in the + specified directory. This is useful to + implement offline updates of the + vendor operating system resources in + /usr that require + updating of /etc + or /var on the + next following boot. Units making use + of this condition should order + themselves before + systemd-update-done.service8, + to make sure they run before the stamp + files's modification time gets reset + indicating a completed update. + + ConditionFirstBoot= + takes a boolean argument. This + condition may be used to + conditionalize units on whether the + system is booting up with an + unpopulated /etc + directory. This may be used to + populate /etc on + the first boot after factory reset, or + when a new system instances boots up + for the first time. + With ConditionPathExists= a file existence condition is @@ -979,120 +1238,6 @@ exists, is a regular file and marked executable. - Similar, - ConditionKernelCommandLine= - 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. - - ConditionVirtualization= - 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 - vm and - container to test - against a generic type of - virtualization solution, or one of - qemu, - kvm, - vmware, - microsoft, - oracle, - xen, - bochs, - chroot, - uml, - openvz, - lxc, - lxc-libvirt, - systemd-nspawn 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. - - ConditionSecurity= - may be used to check whether the given - security module is enabled on the - system. Currently the recognized values - values are selinux, - apparmor, - ima and - smack. - The test may be negated by prepending - an exclamation - mark. - - ConditionCapability= - 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 - capabilities7 - for details). Pass a capability name - such as CAP_MKNOD, - possibly prefixed with an exclamation - mark to negate the check. - - ConditionHost= - may be used to match against the - hostname or machine ID of the - host. This either takes a hostname - string (optionally with shell style - globs) which is tested against the - locally set hostname as returned by - gethostname2, - or a machine ID formatted as string - (see - machine-id5). - The test may be negated by prepending - an exclamation mark. - - ConditionACPower= - 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 - true, 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 false, the - condition will hold only if there is - at least one AC connector known and - all AC connectors are disconnected - from a power source. - - Finally, - ConditionNull= may - be used to add a constant condition - check value to the unit. It takes a - boolean argument. If set to - false, the condition - will always fail, otherwise - succeed. - If multiple conditions are specified, the unit will be executed if all of them apply (i.e. a logical AND @@ -1118,6 +1263,38 @@ have no effect. + + AssertArchitecture= + AssertVirtualization= + AssertHost= + AssertKernelCommandLine= + AssertSecurity= + AssertCapability= + AssertACPower= + AssertNeedsUpdate= + AssertFirstBoot= + AssertPathExists= + AssertPathExistsGlob= + AssertPathIsDirectory= + AssertPathIsSymbolicLink= + AssertPathIsMountPoint= + AssertPathIsReadWrite= + AssertDirectoryNotEmpty= + AssertFileNotEmpty= + AssertFileIsExecutable= + + Similar to the + ConditionArchitecture=, + ConditionVirtualization=, + ... 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. + + SourcePath= A path to a @@ -1126,15 +1303,21 @@ useful for implementation of generator tools that convert configuration from an external configuration file format - into native unit files. Thus + into native unit files. This functionality should not be used in normal units. - Unit file may include a [Install] section, which - carries installation information for the unit. This - section is not interpreted by + + + + [Install] Section Options + + 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 @@ -1146,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) @@ -1226,6 +1409,19 @@ of unit names may be given. + + + DefaultInstance= + + In template unit files, + this specifies for which instance the + unit shall be enabled if the template + is enabled without any explicitly set + instance. This option has no effect in + non-template unit files. The specified + string must be usable as instance + identifier. + The following specifiers are interpreted in the @@ -1270,7 +1466,7 @@ %p Prefix name - For instantiated units this refers to the string before the @ character of the unit name. For non-instantiated units this refers to the name of the unit with the type suffix removed. + For instantiated units, this refers to the string before the @ character of the unit name. For non-instantiated units, this refers to the name of the unit with the type suffix removed. %P @@ -1325,12 +1521,12 @@ %h User home directory - 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 %U this specifier is not available for units run by the systemd system instance, unless the configured user is the root user. + 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 %U, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user. %s User shell - 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 %U this specifier is not available for units run by the systemd system instance, unless the configured user is the root user. + 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 %U, this specifier is not available for units run by the systemd system instance, unless the configured user is the root user. %m @@ -1366,7 +1562,7 @@ See Also systemd1, - systemctl8, + systemctl1, systemd.special7, systemd.service5, systemd.socket5, @@ -1381,7 +1577,8 @@ systemd.scope5, systemd.slice5, systemd.time7, - capabilities7, + systemd-verify1, + capabilities7, systemd.directives7, uname1