X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=2196e73bb308f5649add04ec20d319b81811cbe0;hb=aa0bb9c2c4500696530957f715e097c00bd9e8c4;hp=e0aadf4cd30313236727136c09b7446a1ea70219;hpb=c53158818d8cdaf46b3f1b5299b9bda118a1043f;p=elogind.git diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index e0aadf4cd..2196e73bb 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -48,16 +48,28 @@ - systemd.service, - systemd.socket, - systemd.device, - systemd.mount, - systemd.automount, - systemd.swap, - systemd.target, - systemd.path, - systemd.timer, - systemd.snapshot + service.service, + socket.socket, + device.device, + mount.mount, + automount.automount, + swap.swap, + target.target, + path.path, + timer.timer, + snapshot.snapshot + + /etc/systemd/system/* +/run/systemd/system/* +/usr/lib/systemd/system/* +... + + + /etc/systemd/user/* +/run/systemd/user/* +/usr/lib/systemd/user/* +... + @@ -66,7 +78,7 @@ 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 + target, a file system path, or a timer controlled and supervised by systemd1. The syntax is inspired by .ini files. - This man pages lists the common configuration + This man page lists the common configuration options of all the unit types. These options need to - be configured in the [Unit] resp. [Install] - section of the unit files. + be configured in the [Unit] or [Install] + sections of the unit files. In addition to the generic [Unit] and [Install] - sections described here, each unit should have a + 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. + information: + systemd.service5, + systemd.socket5, + systemd.device5, + systemd.mount5, + systemd.automount5, + systemd.swap5, + systemd.target5, + systemd.path5, + systemd.timer5, + systemd.snapshot5. + + + Unit files are loaded from a set of paths + determined during compilation, described in the next section. + Unit files may contain additional options on top of those listed here. If systemd encounters an unknown @@ -106,12 +133,14 @@ 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 + 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. + are understood: s, min, h, d, w, ms, us. For details + see + systemd.time7. Empty lines and lines starting with # or ; are ignored. This may be used for commenting. Lines ending @@ -119,39 +148,48 @@ line while reading and the backslash is replaced by a space character. This may be used to wrap long lines. - If a line starts with - 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. - Along with a unit file - foo.service a directory + foo.service the directory foo.service.wants/ may exist. All - units symlinked from such a directory are implicitly - added as dependencies of type + unit files symlinked from such a directory are + implicitly added as dependencies of type Wanted= to the unit. This is useful to hook units into the start-up of other units, - without having to modify their unit configuration - files. For details about the semantics of - Wanted= see below. The preferred - way to create symlinks in the - .wants/ directory of a service is - with the enable command of the + without having to modify their unit files. For details + about the semantics of Wanted= see + below. The preferred way to create symlinks in the + .wants/ directory of a unit file + is with the enable command of the systemctl1 tool which reads information from the [Install] - section of unit files. (See below.) A similar + section of unit files (see below). A similar functionality exists for Requires= type dependencies as well, the directory suffix is .requires/ in this case. + Along with a unit file + foo.service a directory + foo.service.d/ may exist. All + files with the suffix .conf 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. + + If a line starts with + 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. + Note that while systemd offers a flexible dependency system between units it is recommended to - use this functionality only sparsely and instead rely + use this functionality only sparingly and instead rely on techniques such as bus-based or socket-based - activation which makes dependencies implicit, which - both results in a simpler and more flexible - system. + activation which make dependencies implicit, resulting + in a both simpler and more flexible system. Some unit names reflect paths existing in the file system name space. Example: a device unit @@ -186,109 +224,168 @@ To refer to the instance string from within the configuration file you may use the special %i specifier in many of the - configuration options. Other specifiers exist, the - full list is: + configuration options. See below for details. + + If a unit file is empty (i.e. has the file size + 0) or is symlinked to /dev/null + its configuration will not be loaded and it appears + with a load state of masked, and + cannot be activated. Use this as an effective way to + fully disable a unit, making it impossible to start it + even manually. + + The unit file format is covered by the + Interface + Stability Promise. + + + + + Unit load path + + 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. + + + When systemd is running in session mode + () and the variable + $SYSTEMD_UNIT_PATH is set, this + contents of this variable overrides the unit load + path. + - Specifiers available in unit files - - - - + + Load path when running in system mode (<option>--system</option>). + + + + + - Specifier - Meaning - Details + Path + Description - %n - Full unit name - + /run/systemd/generator.early + Generated units - %N - Unescaped full unit name - + @SYSTEM_CONFIG_UNIT_PATH@ + Local configuration - %p - Prefix name - This refers to the string before the @, i.e. "getty" in the example above, where "tty3" is the instance name. + /etc/systemd/system - %P - Unescaped prefix name - + /run/systemd/systemd + Volatile units - %i - Instance name - This is the string between the @ character and the suffix. + /run/systemd/generator + Generated units - %I - Unescaped instance name - + /usr/local/lib/systemd/system + Units for local packages - %f - Unescaped file name - This is either the unescaped instance name (if set) with / prepended (if necessary), or the prefix name similarly prepended with /. + @systemunitdir@ + Systemd package configuration - %c - Control group path of the unit - + /usr/lib/systemd/system + Units for installed packages - %r - Root control group path of systemd - + /lib/systemd/system - %R - Parent directory of the root control group path of systemd - + /run/systemd/generator.late + Generated units + + +
+ + + + Load path when running in session mode (<option>--user</option>). + + + + + + - %t - Runtime socket dir - This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers). + Path + Description + + - %u - User name - This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance. + /tmp/systemd-generator.early.XXXXXX + Generated units - %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 instance. + @USER_CONFIG_UNIT_PATH@ + Local configuration - %s - User shell - This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance. + /etc/systemd/user + + + /run/systemd/user + Volatile units + + + /tmp/systemd-generator.XXXXXX + Generated units + + + /usr/local/lib/systemd/user + Units for local packages + + + /usr/local/share/systemd/user + + + @userunitdir@ + Systemd package configuration + + + /usr/lib/systemd/user + Units for installed packages + + + /usr/share/systemd/user + + + /tmp/systemd-generator.late.XXXXXX + Generated units
- If a unit file is empty (i.e. has the file size - 0) or is symlinked to /dev/null - its configuration will not be loaded and it appears - with a load state of masked, and - cannot be activated. Use this as an effective way to - fully disable a unit, making it impossible to start it - even manually. + Note: the paths listed above are set at + compilation time and differ between distributions. The + "authorative" list is printed by + systemd at during start and daemon + reconfiguration. - The unit file format is covered by the - Interface - Stability Promise. + Additional units might be loaded into systemd + ("linked") from directories not on the unit load + path. See the link command for + systemctl1. + @@ -298,7 +395,7 @@ carries generic information about the unit that is not dependent on the type of unit: - + Description= @@ -323,7 +420,20 @@ man:. For more information about the syntax of these URIs see - uri7. + uri7. 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. @@ -403,7 +513,7 @@ Similar to Requires= - resp. RequiresOverridable=. However, + and RequiresOverridable=, respectively. However, if a unit listed here is not started already it will not be started and the transaction fails @@ -551,7 +661,7 @@ Before=. If two units have no ordering dependencies between them they are shut down - resp. started up simultaneously, and + or started up simultaneously, and no ordering takes place. @@ -657,13 +767,13 @@ Takes a boolean argument. If this unit can only be activated - (resp. deactivated) indirectly. In + or deactivated indirectly. In this case explicit start-up - (resp. termination) requested by the + or termination requested by the user is denied, however if it is - started (resp. stopped) as a + started or stopped as a dependency of another unit, start-up - (resp. termination) will succeed. This + or termination will succeed. This is mostly a safety feature to ensure that the user does not accidentally activate units that are not intended @@ -762,6 +872,7 @@ ConditionSecurity= ConditionCapability= ConditionHost= + ConditionACPower= ConditionNull= Before starting a unit @@ -931,6 +1042,23 @@ 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 @@ -957,8 +1085,12 @@ pipe symbol must be passed first, the exclamation second. Except for ConditionPathIsSymbolicLink=, - all path checks follow - symlinks. + 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. @@ -985,7 +1117,7 @@ systemctl1 tool during installation of a unit: - + Alias= @@ -1008,8 +1140,8 @@ Installs a symlink in the .wants/ - resp. .requires/ - subdirectory for a unit. This has the + or .requires/ + subdirectory for a unit, respectively. This has the effect that when the listed unit name is activated the unit listing it is activated @@ -1036,6 +1168,140 @@ + 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. + + + + + Specifiers + + 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: + + + Specifiers available in unit files + + + + + + + Specifier + Meaning + Details + + + + + %n + Full unit name + + + + %N + Unescaped full unit name + + + + %p + Prefix name + 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. + + + %P + Unescaped prefix name + + + + %i + Instance name + For instantiated units: this is the string between the @ character and the suffix. + + + %I + Unescaped instance name + + + + %f + Unescaped file name + This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /. + + + %c + Control group path of the unit + + + + %r + Root control group path of systemd + + + + %R + Parent directory of the root control group path of systemd + + + + %t + Runtime socket dir + This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers). + + + %u + User name + This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance. + + + %U + User UID + This is the UID of the configured user of the unit, or (if none is set) the user running the systemd instance. + + + %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 instance. + + + %s + User shell + 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 + root (UID equal to 0), the + shell configured in account database is + ignored and /bin/sh is + always used. + + + + %m + Machine ID + The machine ID of the running system, formatted as string. See machine-id5 for more information. + + + %b + Boot ID + The boot ID of the running system, formatted as string. See random4 for more information. + + + %H + Host name + The host name of the running system. + + + %% + Escaped % + Single percent sign. + + + +
@@ -1054,7 +1320,9 @@ systemd.path5, systemd.timer5, systemd.snapshot5, - capabilities7 + systemd.time7, + capabilities7, + systemd.directives7