X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=2196e73bb308f5649add04ec20d319b81811cbe0;hb=aa0bb9c2c4500696530957f715e097c00bd9e8c4;hp=35644d38a666c68dd1b7c0d37aeabbca1a624e33;hpb=7a529f63e60dfdccc23d61808c20ba40d9901e47;p=elogind.git diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 35644d38a..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 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. For details see systemd.time7. + 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,124 +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 - %m - Machine ID - The machine ID of the running system, formatted as string. See machine-id5 for more information. + /run/systemd/user + Volatile units - %b - Boot ID - The boot ID of the running system, formatted as string. See random4 for more information. + /tmp/systemd-generator.XXXXXX + Generated units - %H - Host name - The host name of the running system. + /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. + @@ -313,7 +395,7 @@ carries generic information about the unit that is not dependent on the type of unit: - + Description= @@ -345,8 +427,13 @@ reference documentation that explains what the unit's purpose is, followed by how it is configured, followed by - any other related - documentation. + 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. @@ -785,6 +872,7 @@ ConditionSecurity= ConditionCapability= ConditionHost= + ConditionACPower= ConditionNull= Before starting a unit @@ -954,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 @@ -980,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. @@ -1008,7 +1117,7 @@ systemctl1 tool during installation of a unit: - + Alias= @@ -1059,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. + + + +
@@ -1078,7 +1321,8 @@ systemd.timer5, systemd.snapshot5, systemd.time7, - capabilities7 + capabilities7, + systemd.directives7