X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.unit.xml;h=8d6acc7b02e092e135a6168574eb30e0e06a1892;hp=f924ef69dd3149e64f67c9451a62b270aed9ed8d;hb=6baf995c17a95ca0d6b5ad0b1f1667c956574816;hpb=0df2d38abfc787f40149072340d79b4f7b682a24 diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index f924ef69d..8d6acc7b0 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -60,7 +60,9 @@ target.target, path.path, timer.timer, - snapshot.snapshot + snapshot.snapshot, + slice.slice, + scope.scope /etc/systemd/system/* /run/systemd/system/* @@ -68,7 +70,8 @@ ... - /etc/systemd/user/* + $HOME/.config/systemd/user/* +/etc/systemd/user/* /run/systemd/user/* /usr/lib/systemd/user/* ... @@ -81,12 +84,15 @@ 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 - supervised by - systemd1. The - syntax is inspired by systemd1, + a temporary system state snapshot, a resource + management slice or a group of externally created + processes. The syntax is inspired by XDG - Desktop Entry Specification .desktop files, which are in turn + Desktop Entry Specification + .desktop files, which are in turn inspired by Microsoft Windows .ini files. @@ -110,17 +116,30 @@ systemd.path5, systemd.timer5, systemd.snapshot5. + systemd.slice5. + systemd.scope5. + Various settings are allowed to be specified + more than once, in which case the interpretation + depends on the setting. Often, multiple settings form + a list, and setting to an empty value "resets", which + means that previous assignments are ignored. When this + is allowed, it is mentioned in the description of the + setting. Note that using multiple assignments to the + same value makes the unit file incompatible with + parsers for the XDG .desktop file + format. + 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 - option it will write a warning log message but + option, it will write a warning log message but continue loading the unit. If an option is prefixed - with it is ignored completely by + with , it is ignored completely by systemd. Applications may use this to include additional information in the unit files. @@ -128,7 +147,7 @@ written in various formats. For positive settings the strings , , and are - equivalent. For negative settings the strings + equivalent. For negative settings, the strings , , and are equivalent. @@ -152,14 +171,14 @@ space character. This may be used to wrap long lines. Along with a unit file - foo.service the directory + foo.service, the directory 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 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 Wanted=, see below. The preferred way to create symlinks in the .wants/ directory of a unit file is with the enable command of the @@ -171,9 +190,9 @@ .requires/ in this case. Along with a unit file - foo.service a directory + foo.service, a directory foo.service.d/ may exist. All - files with the suffix .conf from + 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 @@ -182,7 +201,7 @@ directive. If a line starts with - followed by a file name, the specified file will be + 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. @@ -195,12 +214,12 @@ in a both simpler and more flexible system. Some unit names reflect paths existing in the - file system name space. Example: a device unit + file system namespace. Example: a device unit dev-sda.device refers to a device - with the device node /dev/sda in - the file system namespace. If this applies a special + with the device node /dev/sda in + the file system namespace. If this applies, a special way to escape the path name is used, so that the - result is usable as part of a file name. Basically, + 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 @@ -211,12 +230,12 @@ Optionally, units may be instantiated from a template file at runtime. This allows creation of multiple units from a single configuration file. If - systemd looks for a unit configuration file it will + 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 - name contains an @ character, systemd will look for a + 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 + instance string (i.e. the part between the @ character and the suffix) removed. Example: if a service getty@tty3.service is requested and no file by that name is found, systemd will look @@ -230,7 +249,7 @@ 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 + 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 @@ -249,10 +268,9 @@ 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. - + tables below. Unit files found in directories listed + earlier override files with the same name in + directories lower in the list. When systemd is running in user mode () and the variable @@ -276,33 +294,17 @@ - - /run/systemd/generator.early - Generated units (early) - /etc/systemd/system Local configuration - /run/systemd/systemd - Volatile units - - - /run/systemd/generator - Generated units (middle) - - - /usr/local/lib/systemd/system - Units for local packages + /run/systemd/system + Runtime units /usr/lib/systemd/system - Units for installed packages - - - /run/systemd/generator.late - Generated units (late) + Units of installed packages @@ -310,7 +312,7 @@ - Load path when running in session mode (<option>--user</option>). + Load path when running in user mode (<option>--user</option>). @@ -324,8 +326,8 @@ - /tmp/systemd-generator.early.XXXXXX - Generated units (early) + $HOME/.config/systemd/user + User configuration /etc/systemd/user @@ -333,23 +335,11 @@ /run/systemd/user - Volatile units - - - /tmp/systemd-generator.XXXXXX - Generated units (middle) - - - /usr/local/lib/systemd/user - Units for local packages + Runtime units /usr/lib/systemd/user - Units for installed packages - - - /tmp/systemd-generator.late.XXXXXX - Generated units (late) + Units of installed packages @@ -358,7 +348,10 @@ Additional units might be loaded into systemd ("linked") from directories not on the unit load path. See the link command for - systemctl1. + systemctl1. Also, + some units are dynamically created via generators + Generators. @@ -377,12 +370,20 @@ describing the unit. This is intended for use in UIs to show descriptive information along with the unit - name. + name. The description should contain a name + that means something to the end user. + Apache2 Web Server is a good + example. Bad examples are + high-performance light-weight HTTP + server (too generic) or + Apache2 (too specific and + meaningless for people who do not know + Apache). Documentation= - A space separated list + A space-separated list of URIs referencing documentation for this unit or its configuration. Accepted are only URIs @@ -393,7 +394,7 @@ info:, man:. For more information about the syntax of these - URIs see + URIs, see uri7. The URIs should be listed in order of relevance, starting with the most @@ -405,7 +406,7 @@ 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 + assigned to this option, the list is reset and all prior assignments will have no effect. @@ -420,10 +421,12 @@ of the other units gets deactivated or its activation fails, this unit will be deactivated. This option may be - specified more than once, in which - case requirement dependencies for all - listed names are created. Note that - requirement dependencies do not + specified more than once or multiple + space-separated units may be specified + in one option in which case + requirement dependencies for all + listed names will be created. Note + that requirement dependencies do not influence the order in which services are started or stopped. This has to be configured independently with the @@ -471,7 +474,7 @@ the start-up was pulled in indirectly by some dependency or automatic start-up of units that is not - requested by the user this dependency + requested by the user, this dependency must be fulfilled and otherwise the transaction fails. Hence, this option may be used to configure dependencies @@ -486,22 +489,23 @@ RequisiteOverridable=Similar to - Requires= - and RequiresOverridable=, respectively. However, - if a unit listed here is not started - already it will not be started and the - transaction fails - immediately. + Requires= and + RequiresOverridable=, + respectively. However, if the units + listed here are not started already + they will not be started and the + transaction will fail immediately. + Wants= A weaker version of - Requires=. A unit + Requires=. Units listed in this option will be started if the configuring unit is. However, - if the listed unit fails to start up + if the listed units fail to start or cannot be added to the transaction this has no impact on the validity of the transaction as a whole. This is @@ -511,8 +515,8 @@ Note that dependencies of this type may also be configured outside of - the unit configuration file by - adding a symlink to a + the unit configuration file by adding + symlinks to a .wants/ directory accompanying the unit file. For details see above. @@ -544,7 +548,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. @@ -553,12 +557,12 @@ Conflicts= - Configures negative + A space-separated list + of unit names. Configures negative requirement dependencies. If a unit - has a - Conflicts= setting - on another unit, starting the former - will stop the latter and vice + has a Conflicts= + setting on another unit, starting the + former will stop the latter and vice versa. Note that this setting is independent of and orthogonal to the After= and @@ -585,7 +589,8 @@ Before= After= - Configures ordering + A space-separated list + of unit names. Configures ordering dependencies between units. If a unit foo.service contains a setting @@ -634,19 +639,19 @@ type After= or Before=. If two units have no ordering dependencies - between them they are shut down - or started up simultaneously, and - no ordering takes + between them, they are shut down or + started up simultaneously, and no + ordering takes place. OnFailure= - Lists one or more - units that are activated when this - unit enters the - 'failed' + A space-separated list + of one or more units that are + activated when this unit enters the + failed state. @@ -654,23 +659,55 @@ PropagatesReloadTo= ReloadPropagatedFrom= - Lists one or more - units where reload requests on the - unit will be propagated to/on the - other unit will be propagated - from. Issuing a reload request on a - unit will automatically also enqueue a - reload request on all units that the - reload request shall be propagated to - via these two - settings. + A space-separated list + of one or more units where reload + requests on this unit will be + propagated to, or reload requests on + the other unit will be propagated to + this unit, respectively. Issuing a + reload request on a unit will + automatically also enqueue a reload + request on all units that the reload + request shall be propagated to via + these two settings. + + + + JoinsNamespaceOf= + + For units that start + processes (such as service units), + lists one or more other units whose + network and/or temporary file + namespace to join. This only applies + to unit types which support the + PrivateNetwork= and + PrivateTmp= + directives (see + systemd.exec5 + for details). If a unit that has this + 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 + defined which namespace is + joined. Note that this setting only + has an effect if + PrivateNetwork= + and/or PrivateTmp= + is enabled for both the unit that + joins the namespace and the unit whose + namespace is joined. RequiresMountsFor= - Takes a space - separated list of absolute paths. Automatically + Takes a space-separated + list of absolute paths. Automatically adds dependencies of type Requires= and After= for all @@ -679,26 +716,36 @@ - OnFailureIsolate= - - Takes a boolean - argument. If the - unit listed in + OnFailureJobMode= + + Takes a value of + fail, + replace, + replace-irreversibly, + isolate, + flush, + ignore-dependencies + or + ignore-requirements. Defaults + to + replace. Specifies + how the units listed in OnFailure= will be - enqueued in isolation mode, i.e. all - units that are not its dependency will - be stopped. If this is set only a + enqueued. See + systemctl1's + option + for details on the possible values. If + this is set to + isolate, only a single unit may be listed in - OnFailure=. Defaults - to - . + OnFailure=.. IgnoreOnIsolate= Takes a boolean - argument. If + argument. If , this unit will not be stopped when isolating another unit. Defaults to . @@ -708,7 +755,7 @@ IgnoreOnSnapshot= Takes a boolean - argument. If + argument. If , this unit will not be included in snapshots. Defaults to for device and @@ -720,7 +767,7 @@ StopWhenUnneeded= Takes a boolean - argument. If + argument. If , this unit will be stopped when it is no longer used. Note that in order to minimize the work to be executed, @@ -739,10 +786,10 @@ RefuseManualStop= Takes a boolean - argument. If + argument. If , this unit can only be activated or deactivated indirectly. In - this case explicit start-up + this case, explicit start-up or termination requested by the user is denied, however if it is started or stopped as a @@ -762,10 +809,10 @@ AllowIsolate= Takes a boolean - argument. If + argument. If , this unit may be used with the systemctl isolate - command. Otherwise this will be + command. Otherwise, this will be refused. It probably is a good idea to leave this disabled except for target units that shall be used similar to @@ -779,7 +826,7 @@ DefaultDependencies= Takes a boolean - argument. If + argument. If , (the default), a few default dependencies will implicitly be created for the unit. The actual @@ -797,7 +844,7 @@ highly recommended to leave this option enabled for the majority of common units. If set to - this option + , this option does not disable all implicit dependencies, just non-essential ones. @@ -809,10 +856,10 @@ When clients are waiting for a job of this unit to complete, time out after the specified - time. If this time limit is reached + time. If this time limit is reached, the job will be cancelled, the unit however will not change state or even - enter the 'failed' + enter the failed mode. This value defaults to 0 (job timeouts disabled), except for device units. NB: this timeout is independent @@ -851,7 +898,7 @@ Before starting a unit verify that the specified condition is - true. If it is not true the starting + true. If it is not true, the starting of the unit will be skipped, however all ordering dependencies of it are still respected. A failing condition @@ -866,12 +913,12 @@ a file existence condition is checked before a unit is started. If the specified absolute path name does - not exist the condition will + not exist, the condition will fail. If the absolute path name passed to ConditionPathExists= is prefixed with an exclamation mark - ('!'), the test is negated, and the unit + (!), the test is negated, and the unit is only started if the path does not exist. @@ -940,7 +987,7 @@ exclamation mark unset). The argument must either be a single word, or an assignment (i.e. two words, separated - '='). In the former + =). In the former case the kernel command line is searched for the word appearing as is, or as left hand side of an @@ -969,13 +1016,14 @@ xen, bochs, chroot, + uml, openvz, lxc, lxc-libvirt, systemd-nspawn to test against a specific implementation. If multiple - virtualization technologies are nested + virtualization technologies are nested, only the innermost is considered. The test may be negated by prepending an exclamation mark. @@ -983,8 +1031,11 @@ ConditionSecurity= may be used to check whether the given security module is enabled on the - system. Currently the only recognized - value is selinux. + system. Currently the recognized values + values are selinux, + apparmor, + ima and + smack. The test may be negated by prepending an exclamation mark. @@ -1004,11 +1055,11 @@ ConditionHost= may be used to match against the - host name or machine ID of the - host. This either takes a host name + 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 host name as returned by + locally set hostname as returned by gethostname2, or a machine ID formatted as string (see @@ -1022,12 +1073,12 @@ battery powered at the time of activation of the unit. This takes a boolean argument. If set to - true the condition + 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 + set to false, the condition will hold only if there is at least one AC connector known and all AC connectors are disconnected @@ -1038,30 +1089,30 @@ be used to add a constant condition check value to the unit. It takes a boolean argument. If set to - false the condition + false, the condition will always fail, otherwise succeed. If multiple conditions are - specified the unit will be executed if + specified, the unit will be executed if all of them apply (i.e. a logical AND is applied). Condition checks can be prefixed with a pipe symbol (|) in which case a condition becomes a triggering condition. If at least one triggering condition is defined for a - unit then the unit will be executed if + unit, then the unit will be executed if at least one of the triggering conditions apply and all of the non-triggering conditions. If you prefix an argument with the pipe - symbol and an exclamation mark the + symbol and an exclamation mark, the pipe symbol must be passed first, the exclamation second. Except for ConditionPathIsSymbolicLink=, all path checks follow symlinks. If any of these options is assigned the - empty string the list of conditions is + empty string, the list of conditions is reset completely, all previous condition settings (of any kind) will have no effect. @@ -1095,55 +1146,90 @@ Alias= - Additional names this - unit shall be installed under. The - names listed here must have the same - suffix (i.e. type) as the unit file - name. This option may be specified - more than once, in which case all - listed names are used. At installation - time, - systemctl enable - will create symlinks from these names - to the unit file name. + A space-seperated list + of additional names this unit shall be + installed under. The names listed here + must have the same suffix (i.e. type) + as the unit file name. This option may + be specified more than once, in which + case all listed names are used. At + installation time, systemctl + enable will create symlinks + from these names to the unit + filename. WantedBy= RequiredBy= - Installs a symlink in - the .wants/ - 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 - too. WantedBy=foo.service + This option may be + used more than once, or a + space-separated list of unit names may + be given. A symbolic link is created + in the .wants/ or + .requires/ + directory of each of the listed units + when this unit is installed by + systemctl enable. + This has the effect that a dependency + of type Wants= or + Requires= is added + from the listed unit to the current + unit. The primary result is that the + current unit will be started when the + listed unit is started. See the + description of + Wants= and + Requires= in the + [Unit] section for details. + + WantedBy=foo.service in a service bar.service is mostly equivalent to Alias=foo.service.wants/bar.service - in the same file. + in the same file. In case of template + units, systemctl enable + must be called with an instance name, and + this instance will be added to the + .wants/ or + .requires/ list + of the listed unit. + E.g. WantedBy=getty.target + in a service + getty@.service + will result in systemctl + enable getty@tty2.service + creating a + getty.target.wants/getty@tty2.service + link to getty@.service. + Also= Additional units to - install when this unit is - installed. If the user requests - installation of a unit with this - option configured, + install/deinstall when this unit is + installed/deinstalled. If the user + requests installation/deinstallation + of a unit with this option configured, systemctl enable - will automatically install units - listed in this option as - well. + and systemctl + disable will automatically + install/uninstall units listed in this option as + well. + + This option may be used more + than once, or a space-separated list + of unit names may be + given. The following specifiers are interpreted in the - Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b. + Install section: %n, %N, %p, %i, %U, %u, %m, %H, %b, %v. For their meaning see the next section. @@ -1194,7 +1280,7 @@ %i Instance name - For instantiated units: this is the string between the @ character and the suffix. + For instantiated units: this is the string between the @ character and the suffix. %I @@ -1203,7 +1289,7 @@ %f - Unescaped file name + Unescaped filename This is either the unescaped instance name (if applicable) with / prepended (if applicable), or the prefix name similarly prepended with /. @@ -1214,12 +1300,15 @@ %r Root control group path where units are placed. - For system instances this usually resolves to /system, except in containers, where the path might be prefixed with the container's root control group. + For system instances, this usually resolves to /system, except in containers, where the path might be prefixed with the container's root control group. %R Parent directory of the control group path where units are placed. - For system instances this usually resolves to /, except in containers, where this resolves to the container's root directory. This specifier is particularly useful in the ControlGroup= setting (see systemd.exec5). + For system instances, this usually + resolves to /, except in + containers, where this resolves to the + container's root directory. %t @@ -1259,7 +1348,12 @@ %H Host name - The host name of the running system. + The hostname of the running system. + + + %v + Kernel release + Identical to uname -r output. %% @@ -1287,9 +1381,12 @@ systemd.path5, systemd.timer5, systemd.snapshot5, + systemd.scope5, + systemd.slice5, systemd.time7, capabilities7, - systemd.directives7 + systemd.directives7, + uname1