X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=f33e8df05697529c2012f09178cee6f546277fd9;hp=640318ba4412779ce9d8b2c750c2c369a124f52d;hb=320814811417146cfa1e416f69f1101eed630c36;hpb=6cfe2fde1cc919c2333a5749ea1cbc31fa757077 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 640318ba4..f33e8df05 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -139,9 +139,10 @@ If set to (the default - value if neither + if neither Type= nor - BusName= are + BusName=, but + ExecStart= are specified), it is expected that the process configured with ExecStart= is the @@ -177,13 +178,17 @@ exits. Behavior of - is similar - to ; however, - it is expected that the process has to + is similar to + ; however, it + is expected that the process has to exit before systemd starts follow-up units. RemainAfterExit= is particularly useful for this type - of service. + of service. This is the implied + default if neither + Type= or + ExecStart= are + specified. Behavior of is similar to @@ -296,9 +301,48 @@ as. This option is mandatory for services where Type= is set to - , but its use - is otherwise recommended if the process - takes a name on the D-Bus bus. + . + + + + + BusPolicy= + + If specified, a custom + kdbus + endpoint will be created and installed as the + default bus node for the service. Such a custom + endpoint can hold an own set of policy rules + that are enforced on top of the bus-wide ones. + The custom endpoint is named after the service + it was created for, and its node will be + bind-mounted over the default bus node + location, so the service can only access the + bus through its own endpoint. Note that custom + bus endpoints default to a 'deny all' policy. + Hence, if at least one + BusPolicy= directive is + given, you have to make sure to add explicit + rules for everything the service should be able + to do. + The value of this directive is comprised + of two parts; the bus name, and a verb to + specify to granted access, which is one of + , + , or + . + implies + , and + implies both and + . + If multiple access levels are specified for the + same bus name, the most powerful one takes + effect. + + Examples: + BusPolicy=org.freedesktop.systemd1 talk + BusPolicy=org.foo.bar see + This option is only available on kdbus enabled systems. @@ -306,67 +350,58 @@ ExecStart= Commands with their arguments that are executed when this - service is started. For each of the - specified commands, the first argument - must be an absolute and literal path - to an executable. + service is started. The value is split + into zero or more command lines is + according to the rules described below + (see section "Command Lines" below). + When Type is not , only one - command may be given. When + command may and must be given. When Type=oneshot is - used, more than one command may be - specified. Multiple command lines may - be concatenated in a single directive - by separating them with semicolons - (these semicolons must be passed as - separate words). Alternatively, this - directive may be specified more than - once with the same effect. - Lone semicolons may be escaped as - \;. If the empty - string is assigned to this option, the - list of commands to start is reset, - prior assignments of this option will - have no effect. - - Each command line is split on - whitespace, with the first item being - the command to execute, and the - subsequent items being the arguments. - Double quotes ("...") and single - quotes ('...') may be used, in which - case everything until the next - matching quote becomes part of the - same argument. Quotes themselves are - removed after parsing. In addition, a - trailing backslash - (\) may be used to - merge lines. This syntax is intended - to be very similar to shell syntax, - but only the meta-characters and - expansions described in the following - paragraphs are understood. - Specifically, redirection using - <, - <<, - >, and - >>, pipes - using |, and - running programs in the background - using & - and other elements of shell - syntax are not supported. - + used, zero or more commands may be + specified. This can be specified by + providing multiple command lines in + the same directive, or alternatively, + this directive may be specified more + than once with the same effect. If the + empty string is assigned to this + option, the list of commands to start + is reset, prior assignments of this + option will have no effect. If no + ExecStart= is + specified, then the service must have + RemainAfterExit=yes + set. + + For each of the specified + commands, the first argument must be + an absolute path to an executable. + Optionally, if this file name is + prefixed with @, + the second token will be passed as + argv[0] to the + executed process, followed by the + further arguments specified. If the + absolute filename is prefixed with + -, an exit code of + the command normally considered a + failure (i.e. non-zero exit status or + abnormal exit due to signal) is + ignored and considered success. If + both - and + @ are used, they + can appear in either order. If more than one command is specified, the commands are invoked sequentially in the order they appear in the unit file. If one of the commands fails (and is not prefixed - with -), other lines - are not executed, and the unit is - considered failed. + with -), other + lines are not executed, and the unit + is considered failed. Unless Type=forking is @@ -374,106 +409,6 @@ command line will be considered the main process of the daemon. - The command line accepts - % specifiers as - described in - systemd.unit5. - Note that the first argument of the - command line (i.e. the program to - execute) may not include - specifiers. - - Basic environment variable - substitution is supported. Use - ${FOO} as part of a - word, or as a word of its own, on the - command line, in which case it will be - replaced by the value of the - environment variable including all - whitespace it contains, resulting in a - single argument. Use - $FOO as a separate - word on the command line, in which - case it will be replaced by the value - of the environment variable split at - whitespace, resulting in zero or more - arguments. To pass a literal dollar - sign, use $$. - Variables whose value is not known at - expansion time are treated as empty - strings. Note that the first argument - (i.e. the program to execute) may not - be a variable. - - Variables to be used in this - fashion may be defined through - Environment= and - EnvironmentFile=. - In addition, variables listed in the - section "Environment variables in - spawned processes" in - systemd.exec5, - which are considered "static - configuration", may be used (this includes - e.g. $USER, but not - $TERM). - - Optionally, if the absolute file - name is prefixed with - @, the second token - will be passed as - argv[0] to the - executed process, followed by the - further arguments specified. If the - absolute filename is prefixed with - -, an exit code of - the command normally considered a - failure (i.e. non-zero exit status or - abnormal exit due to signal) is ignored - and considered success. If both - - and - @ are used, they - can appear in either order. - - Note that this setting does not - directly support shell command - lines. If shell command lines are to - be used, they need to be passed - explicitly to a shell implementation - of some kind. Example: - ExecStart=/bin/sh -c 'dmesg | tac' - Example: - ExecStart=/bin/echo one ; /bin/echo "two two" - This will execute - /bin/echo two - times, each time with one argument: - one and - two two, - respectively. Because two commands are - specified, - Type=oneshot must - be used. - - Example: - ExecStart=/bin/echo / >/dev/null & \; \ -/bin/ls - This will execute - /bin/echo with five - arguments: /, - >/dev/null, - &, - ;, and - /bin/ls. - - Example: - Environment="ONE=one" 'TWO=two two' -ExecStart=/bin/echo $ONE $TWO ${TWO} - This will execute - /bin/echo with four - arguments: one, - two, - two, and - two two. @@ -605,11 +540,12 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} time span value such as "5min 20s". Pass 0 to disable the timeout logic. Defaults to - TimeoutStartSec= from + DefaultTimeoutStartSec= from the manager configuration file, except when Type=oneshot is used, in which case the timeout - is disabled by default. + is disabled by default + (see systemd-system.conf5). @@ -628,8 +564,9 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} time span value such as "5min 20s". Pass 0 to disable the timeout logic. Defaults to - TimeoutStartSec= from the - manager configuration file. + DefaultTimeoutStopSec= from the + manager configuration file + (see systemd-system.conf5). @@ -653,8 +590,9 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} (i.e. the "keep-alive ping"). If the time between two such calls is larger than the configured time, then the service - is placed in a failed state. By - setting Restart= to + is placed in a failed state and it will + be terminated with SIGABRT. + By setting Restart= to or , the service will be automatically restarted. The @@ -825,10 +763,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} - In addition to the above settings, - the service will not be restarted if the - exit code or signal is specified in + As exceptions to the setting + above the service will not be + restarted if the exit code or signal + is specified in RestartPreventExitStatus= + (see below). Also, the services will + always be restarted if the exit code + or signal is specified in + RestartForceExitStatus= (see below). Setting this to @@ -838,8 +781,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} reliability by attempting automatic recovery from errors. For services that shall be able to terminate on - their own choice (and avoiding - immediate restart) + their own choice (and avoid + immediate restarting), is an alternative choice. @@ -857,7 +800,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} definitions can either be numeric exit codes or termination signal names, separated by spaces. For example: - SuccessExitStatus=1 2 8 SIGKILL + SuccessExitStatus=1 2 8 SIGKILL ensures that exit codes 1, 2, 8 and the termination signal SIGKILL are @@ -897,9 +840,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} spaces. Defaults to the empty list, so that, by default, no exit status is excluded from the configured restart - logic. Example: - RestartPreventExitStatus=1 6 - SIGABRT, ensures that exit + logic. For example: + RestartPreventExitStatus=1 6 SIGABRT ensures that exit codes 1 and 6 and the termination signal SIGABRT will not result in automatic service @@ -913,6 +855,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} effect. + + RestartForceExitStatus= + Takes a list of exit + status definitions that when returned + by the main service process will force + automatic service restarts, regardless + of the restart setting configured with + Restart=. The + argument format is similar to + RestartPreventExitStatus=. + + PermissionsStartOnly= Takes a boolean @@ -1012,21 +966,24 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} Sockets= Specifies the name of the socket units this service shall - inherit the sockets from when the - service is started. Normally it - should not be necessary to use this - setting as all sockets whose unit + inherit socket file descriptors + from when the service is + started. Normally it should not be + necessary to use this setting as all + socket file descriptors whose unit shares the same name as the service - (ignoring the different suffix of course) - are passed to the spawned - process. - - Note that the same socket may be - passed to multiple processes at the - same time. Also note that a different - service may be activated on incoming - traffic than that which inherits the - sockets. Or in other words: the + (subject to the different unit name + suffix of course) are passed to the + spawned process. + + Note that the same socket file + descriptors may be passed to multiple + processes simultaneously. Also note + that a different service may be + activated on incoming socket traffic + than the one which is ultimately + configured to inherit the socket file + descriptors. Or in other words: the Service= setting of .socket units does not have to match the inverse of @@ -1103,29 +1060,49 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} hit. Takes one of , , - , or - . If - is set, - hitting the rate limit will trigger no - action besides that the start will not - be permitted. + , + , + , + or + . If + is set, hitting + the rate limit will trigger no action + besides that the start will not be + permitted. causes a reboot following the normal shutdown procedure (i.e. equivalent to systemctl reboot). - causes - a forced reboot which will terminate - all processes forcibly but should - cause no dirty file systems on reboot + causes a + forced reboot which will terminate all + processes forcibly but should cause no + dirty file systems on reboot (i.e. equivalent to systemctl reboot -f) and causes immediate execution of the reboot2 system call, which might result in - data loss. Defaults to + data loss. Similar, + , + , + + have the effect of powering down the + system with similar + semantics. Defaults to . + + FailureAction= + Configure the action + to take when the service enters a failed + state. Takes the same values as + StartLimitAction= + and executes the same actions. + Defaults to . + + + RebootArgument= Configure the optional @@ -1133,6 +1110,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} reboot2 system call if StartLimitAction= + or FailureAction= is a reboot action. This works just like the optional argument to systemctl reboot @@ -1140,14 +1118,32 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} - FailureAction= - Configure the action - to take when the service enters a failed - state. Takes the same values as - StartLimitAction= - and executes the same actions. - Defaults to . - + FileDescriptorStoreMax= + Configure how many + file descriptors may be stored in the + service manager for the service using + sd_pid_notify_with_fds3's + FDSTORE=1 + messages. This is useful for + implementing service restart schemes + where the state is serialized to + /run and the file + descriptors passed to the service + manager, to allow restarts without + losing state. Defaults to 0, i.e. no + file descriptors may be stored in the + service manager by default. All file + descriptors passed to the service + manager from a specific service are + passed back to the service's main + process on the next service + restart. Any file descriptors passed + to the service manager are + automatically closed when POLLHUP or + POLLERR is seen on them, or when the + service is fully stopped and no job + queued or being executed for + it. @@ -1161,44 +1157,507 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} - Compatibility Options + Command lines + + This section describes command line parsing and + variable and specifier substitions for + ExecStart=, + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, and + ExecStopPost= options. + + Multiple command lines may be concatenated in a + single directive by separating them with semicolons + (these semicolons must be passed as separate words). + Lone semicolons may be escaped as + \;. + + Each command line is split on whitespace, with + the first item being the command to execute, and the + subsequent items being the arguments. Double quotes + ("...") and single quotes ('...') may be used, in + which case everything until the next matching quote + becomes part of the same argument. C-style escapes are + also supported, see table below. Quotes themselves are + removed after parsing and escape sequences + substituted. In addition, a trailing backslash + (\) may be used to merge lines. + - The following options are also available in the - [Service] section, but exist purely - for compatibility reasons and should not be used in - newly written service files. + This syntax is intended to be very similar to + shell syntax, but only the meta-characters and + expansions described in the following paragraphs are + understood. Specifically, redirection using + <, <<, + >, and + >>, pipes using + |, running programs in the + background using &, and + other elements of shell syntax are not + supported. + + The command to execute must an absolute path + name. It may contain spaces, but control characters + are not allowed. + + The command line accepts % + specifiers as described in + systemd.unit5. + Note that the first argument of the command line + (i.e. the program to execute) may not include + specifiers. + + Basic environment variable substitution is + supported. Use ${FOO} as part of a + word, or as a word of its own, on the command line, in + which case it will be replaced by the value of the + environment variable including all whitespace it + contains, resulting in a single argument. Use + $FOO as a separate word on the + command line, in which case it will be replaced by the + value of the environment variable split at whitespace + resulting in zero or more arguments. For this type of + expansion, quotes and respected when splitting into + words, and afterwards removed. + + Example: + + Environment="ONE=one" 'TWO=two two' +ExecStart=/bin/echo $ONE $TWO ${TWO} - - - SysVStartPriority= - Set the SysV start - priority to use to order this service - in relation to SysV services lacking - LSB headers. This option is only - necessary to fix ordering in relation - to legacy SysV services that have no - ordering information encoded in the - script headers. As such, it should only - be used as a temporary compatibility - option and should not be used in new unit - files. Almost always, it is a better - choice to add explicit ordering - directives via - After= or - Before=, - instead. For more details, see - systemd.unit5. - If used, pass an integer value in the - range 0-99. - - + This will execute /bin/echo + with four arguments: one, + two, two, and + two two. + + Example: + Environment=ONE='one' "TWO='two two' too" THREE= +ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} +ExecStart=/bin/echo $ONE $TWO $THREE + This results in echo being + called twice, the first time with arguments + 'one', + 'two two' too, , + and the second time with arguments + one, two two, + too. + + + To pass a literal dollar sign, use + $$. Variables whose value is not + known at expansion time are treated as empty + strings. Note that the first argument (i.e. the + program to execute) may not be a variable. + + Variables to be used in this fashion may be + defined through Environment= and + EnvironmentFile=. In addition, + variables listed in the section "Environment variables + in spawned processes" in + systemd.exec5, + which are considered "static configuration", may be + used (this includes e.g. $USER, but + not $TERM). + + Note that shell command lines are not directly + supported. If shell command lines are to be used, they + need to be passed explicitly to a shell implementation + of some kind. Example: + ExecStart=/bin/sh -c 'dmesg | tac' + + Example: + + ExecStart=/bin/echo one ; /bin/echo "two two" + + This will execute /bin/echo + two times, each time with one argument: + one and two two, + respectively. Because two commands are specified, + Type=oneshot must be used. + + Example: + + ExecStart=/bin/echo / >/dev/null & \; \ +/bin/ls + + This will execute /bin/echo + with five arguments: /, + >/dev/null, + &, ;, and + /bin/ls. + + + C escapes supported in command lines and environment variables + + + + + + Literal + Actual value + + + + + \a + bell + + + \b + backspace + + + \f + form feed + + + \n + newline + + + \r + carriage return + + + \t + tab + + + \v + vertical tab + + + \\ + backslash + + + \" + double quotation mark + + + \' + single quotation mark + + + \s + space + + + \xxx + character number xx in hexadecimal encoding + + + \nnn + character number nnn in octal encoding + + + +
+ + + + Examples + + + Simple service + + The following unit file creates a service + that will execute + /usr/sbin/foo-daemon. + Since no Type= is specified, + the default + Type= + will be assumed. systemd will assume the unit + to be started immediately after the program has + begun executing. + + [Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo-daemon + +[Install] +WantedBy=multi-user.target + + Note that systemd assumes here that the + process started by systemd will continue + running until the service terminates. If the + program daemonizes itself (i.e. forks), please + use + Type= + instead. + + Since no ExecStop= was + specified, systemd will send SIGTERM to all + processes started from this service, and after + a timeout also SIGKILL. This behavior can be + modified, see + systemd.kill5 + for details. + + Note that this unit type does not include + any type of notification when a service has + completed initialization. For this, you should + use other unit types, such as + Type= + if the service understands systemd's + notification protocol, + Type= + if the service can background itself or + Type= + if the unit acquires a DBus name once + initialization is complete. See below. + + + + Oneshot service + + Sometimes units should just execute an + action without keeping active processes, such + as a filesystem check or a cleanup action on + boot. For this, + Type= + exists. Units of this type will wait until the + process specified terminates and then fall back + to being inactive. The following unit will + perform a clenaup action: + + [Unit] +Description=Cleanup old Foo data + +[Service] +Type=oneshot +ExecStart=/usr/sbin/foo-cleanup + +[Install] +WantedBy=multi-user.target + + Note that systemd will consider the unit + to be in the state 'starting' until the program + has terminated, so ordered dependencies will + wait for the program to finish before starting + themselves. The unit will revert to the + 'inactive' state after the execution is + done, never reaching the 'active' state. That + means another request to start the unit will + perform the action again. + + Type= + are the only service units that may have more + than one ExecStart= + specified. They will be executed in order until + either they are all successful or one of them + fails. + + + + Stoppable oneshot service + + Similarly to the oneshot services, there + are sometimes units that need to execute a + program to set up something and then execute + another to shut it down, but no process remains + active while they are considered + 'started'. Network configuration can sometimes + fall into this category. Another use case is if + a oneshot service shall not be executed a + each time when they are pulled in as a + dependency, but only the first time. + + For this, systemd knows the setting + RemainAfterExit=, + which causes systemd to consider the unit to be + active if the start action exited successfully. + This directive can be used with all types, but + is most useful with + Type= + and + Type=. + With + Type= + systemd waits until the start action has + completed before it considers the unit to be + active, so dependencies start only after the + start action has succeeded. With + Type= + dependencies will start immediately after the + start action has been dispatched. The following + unit provides an example for a simple static + firewall. + + [Unit] +Description=Simple firewall + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/local/sbin/simple-firewall-start +ExecStop=/usr/local/sbin/simple-firewall-stop + +[Install] +WantedBy=multi-user.target + + Since the unit is considered to be + running after the start action has exited, + invoking systemctl start on + that unit again will cause no action to be + taken. + + + + Traditional forking services + + Many traditional daemons/services + background (i.e. fork, daemonize) themselves + when starting. Set + Type= + in the service's unit file to support this mode + of operation. systemd will consider the service + to be in the process of initialization while + the original program is still running. Once + it exits successfully and at least a process + remains (and + RemainAfterExit=), + the service is considered started. + + Often a traditional daemon only consists + of one process. Therefore, if only one process + is left after the original process terminates, + systemd will consider that process the main + process of the service. In that case, the + $MAINPID variable will be + available in ExecReload=, + ExecStop=, etc. + + In case more than one process remains, + systemd will be unable to determine the main + process, so it will not assume there is one. + In that case, $MAINPID will + not expand to anything. However, if the process + decides to write a traditional PID file, + systemd will be able to read the main PID from + there. Please set PIDFile= + accordingly. Note that the daemon should write + that file before finishing with its + initialization, otherwise systemd might try to + read the file before it exists. + + The following example shows a simple + daemon that forks and just starts one process + in the background: + + [Unit] +Description=Some simple daemon + +[Service] +Type=forking +ExecStart=/usr/sbin/my-simple-daemon -d + +[Install] +WantedBy=multi-user.target + + Please see + systemd.kill5 + for details on how you can influence the way + systemd terminates the service. + + + + DBus services + + For services that acquire a name on the + DBus system bus, use + Type= + and set BusName= + accordingly. The service should not fork + (daemonize). systemd will consider the service + to be initialized once the name has been + acquired on the system bus. The following + example shows a typical DBus service: + + [Unit] +Description=Simple DBus service + +[Service] +Type=dbus +BusName=org.example.simple-dbus-service +ExecStart=/usr/sbin/simple-dbus-service + +[Install] +WantedBy=multi-user.target + + For bus-activatable + services, don't include a + [Install] section in the + systemd service file, but use the + SystemdService= option in + the corresponding DBus service file, for + example + (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service): + + [D-BUS Service] +Name=org.example.simple-dbus-service +Exec=/usr/sbin/simple-dbus-service +User=root +SystemdService=simple-dbus-service.service + + Please see + systemd.kill5 + for details on how you can influence the way + systemd terminates the service. + + + + Services that notify systemd about their initialization + + Type= + services are really easy to write, but have the + major disadvantage of systemd not being able to + tell when initialization of the given service + is complete. For this reason, systemd supports + a simple notification protocol that allows + daemons to make systemd aware that they are + done initializing. Use + Type= + for this. A typical service file for such a + daemon would look like this: + + [Unit] +Description=Simple notifying service + +[Service] +Type=notify +ExecStart=/usr/sbin/simple-notifying-service + +[Install] +WantedBy=multi-user.target + + Note that the daemon has to support + systemd's notification protocol, else systemd + will think the service hasn't started yet and + kill it after a timeout. For an example of how + to update daemons to support this protocol + transparently, take a look at + sd_notify3. + systemd will consider the unit to be in the + 'starting' state until a readiness notification + has arrived. + + Please see + systemd.kill5 + for details on how you can influence the way + systemd terminates the service. + See Also systemd1, - systemctl8, + systemctl1, systemd.unit5, systemd.exec5, systemd.resource-control5,