X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=364ad7d0c8a5b8ce1dcb4bd0066f94270ac5cafe;hp=891b3474aae66211b69e3bb73f40d84050a5f353;hb=33169701b0640d3629d4c36cf8c71dc26d2cb7e1;hpb=28137202027b07fec5c270c1b1ef12ebaf35d58d diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 891b3474a..364ad7d0c 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -48,7 +48,7 @@ - systemd.service + service.service @@ -73,9 +73,12 @@ systemd.exec5, which define the execution environment the commands are executed in, and in - systemd.kill5 + systemd.kill5, which define the way the processes of the service are - terminated. + terminated, and in + systemd.resource-control5, + which configure resource control settings for the + processes of the service. Unless DefaultDependencies= is set to , service units will @@ -100,7 +103,7 @@ script. This is useful for compatibility with SysV. Note that this compatibility is quite comprehensive but not 100%. For details about the - incompatibilities see the Incompatibilities with SysV document. @@ -121,7 +124,7 @@ options specific to the [Service] section of service units are the following: - + Type= @@ -136,14 +139,16 @@ If set to (the default - value if BusName= - is not specified) it is expected that - the process configured with + value if neither + Type= nor + BusName= are + specified), it is expected that the + process configured with ExecStart= is the main process of the service. In this mode, if the process offers functionality to other processes on - the system its communication channels + the system, its communication channels should be installed before the daemon is started up (e.g. sockets set up by systemd, via socket activation), as @@ -151,14 +156,14 @@ starting follow-up units. If set to - it is + , it is expected that the process configured with ExecStart= will call fork() as part of its start-up. The parent process is expected to exit when start-up is complete and all communication - channels set up. The child continues + channels are set up. The child continues to run as the main daemon process. This is the behavior of traditional UNIX daemons. If this @@ -167,13 +172,13 @@ PIDFile= option, so that systemd can identify the main process of the daemon. systemd will - proceed starting follow-up units as - soon as the parent process + proceed with starting follow-up units + as soon as the parent process exits. Behavior of is similar - to , however + to ; however, it is expected that the process has to exit before systemd starts follow-up units. RemainAfterExit= @@ -182,13 +187,13 @@ Behavior of is similar to - , however it is + ; however, it is expected that the daemon acquires a name on the D-Bus bus, as configured by BusName=. systemd - will proceed starting follow-up units - after the D-Bus bus name has been + will proceed with starting follow-up + units after the D-Bus bus name has been acquired. Service units with this option configured implicitly gain dependencies on the @@ -199,26 +204,30 @@ Behavior of is similar to - , however it is + ; however, it is expected that the daemon sends a notification message via sd_notify3 - or an equivalent call when it finished - starting up. systemd will proceed + or an equivalent call when it has finished + starting up. systemd will proceed with starting follow-up units after this notification message has been sent. If - this option is used + this option is used, NotifyAccess= (see below) should be set to open access to the notification socket provided by systemd. If NotifyAccess= is not set, it will be implicitly set to - . + . Note that + currently + Type= + will not work if used in combination with + PrivateNetwork=. Behavior of is very similar - to , however + to ; however, actual execution of the service binary is delayed until all jobs are dispatched. This may be used to avoid @@ -251,11 +260,11 @@ is set and is unset because for the other types or with an explicitly configured PID - file the main PID is always known. The + file, the main PID is always known. The guessing algorithm might come to incorrect conclusions if a daemon consists of more than one process. If - the main PID cannot be determined + the main PID cannot be determined, failure detection and automatic restarting of a service will not work reliably. Defaults to @@ -283,14 +292,13 @@ BusName= Takes a D-Bus bus - name, that this service is reachable + name that this service is reachable as. This option is mandatory for services where Type= is set to , but its use - is otherwise recommended as well if - the process takes a name on the D-Bus - bus. + is otherwise recommended if the process + takes a name on the D-Bus bus. @@ -298,36 +306,68 @@ ExecStart= Commands with their arguments that are executed when this - service is started. - - - When + service is started. For each of the + specified commands, the first argument + must be an absolute and literal path + to an executable. + + When Type is + not , only one + command may be given. When Type=oneshot is used, more than one command may be specified. Multiple command lines may - be concatenated in a single directive, + 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. However, - the latter syntax is not recommended - for compatibility with parsers - suitable for XDG - .desktop files. - The commands are invoked one by one - sequentially in the order they appear - in the unit file. When - Type is not - , only one - command may be given. Lone semicolons - may be escaped as - '\;'. If the empty - string is assigned to this option the + 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. + + + 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. + Unless Type=forking is set, the process started via this @@ -335,66 +375,106 @@ main process of the daemon. The command line accepts - '%' specifiers as + % 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. - - On top of that basic environment - variable substitution is - supported. Use + 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 + 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 + 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 up - at whitespace, resulting in no or more - arguments. Note that the first - argument (i.e. the program to execute) - may not be a variable, and must be a - literal and absolute path - name. + 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 + @, the second token will be passed as argv[0] to the executed process, followed by the further arguments specified. If the - absolute file name is prefixed with - '-' an exit code of + 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 + - 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 + be used, they need to be passed explicitly to a shell implementation - of some kind. Example: - ExecStart=/bin/sh -c 'dmesg | tac' - - For services run by a user - instance of systemd the special - environment variable - MANAGERPID is set - to the PID of the systemd - instance. - + 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. + @@ -409,6 +489,11 @@ that multiple command lines are allowed and the commands are executed one after the other, serially. + + If any of those commands (not + prefixed with -) + fail, the rest are not executed and + the unit is considered failed. @@ -424,14 +509,31 @@ optional. Specifier and environment variable substitution is supported here following the same scheme as for - ExecStart=. One - additional special environment - variables is set: if known - $MAINPID is set to + ExecStart=. + + One additional, special + environment variable is set: if known, + $MAINPID is set to the main process of the daemon, and may be used for command lines like the - following: /bin/kill -HUP - $MAINPID. + following: + + /bin/kill -HUP $MAINPID + + Note however that reloading a + daemon by sending a signal (as with + the example line above) is usually not + a good choice, because this is an + asynchronous operation and hence not + suitable to order reloads of multiple + services against each other. It is + strongly recommended to set + ExecReload= to a + command that no only triggers a + configuration reload of the daemon, + but also synchronously waits for it + complete. + @@ -443,19 +545,19 @@ following the same scheme as described for ExecStart= above. Use of this setting is - optional. All processes remaining for - a service after the commands - configured in this option are run are + optional. After the commands configured + in this option are run, all processes + remaining for a service are terminated according to the KillMode= setting (see systemd.kill5). If - this option is not specified the - process is terminated right-away when + this option is not specified, the + process is terminated immediately when service stop is requested. Specifier and environment variable substitution is supported (including - $MAINPID, see + $MAINPID, see above). @@ -463,9 +565,12 @@ ExecStopPost= Additional commands that are executed after the service - was stopped using the commands - configured in - ExecStop=. This + was stopped. This includes cases where + the commands configured in + ExecStop= were used, + where the service does not have any + ExecStop= defined, or + where the service exited unexpectedly. This argument takes multiple command lines, following the same scheme as described for ExecStart. Use @@ -494,14 +599,16 @@ daemon service does not signal start-up completion within the configured time, the service will be - considered failed and be shut down - again. + considered failed and will be shut + down again. Takes a unit-less value in seconds, or a time span value such as "5min - 20s". Pass 0 to disable the timeout - logic. Defaults to 90s, except when - Type=oneshot is - used in which case the timeout + 20s". Pass 0 to + disable the timeout logic. Defaults to + TimeoutStartSec= from + the manager configuration file, except + when Type=oneshot is + used, in which case the timeout is disabled by default. @@ -510,17 +617,19 @@ TimeoutStopSec= Configures the time to wait for stop. If a service is asked - to stop but does not terminate in the + to stop, but does not terminate in the specified time, it will be terminated - forcibly via SIGTERM, and after - another delay of this time with - SIGKILL (See + forcibly via SIGTERM, + and after another timeout of equal duration + with SIGKILL (see KillMode= in systemd.kill5). Takes a unit-less value in seconds, or a time span value such as "5min - 20s". Pass 0 to disable the timeout - logic. Defaults to 90s. + 20s". Pass 0 to disable + the timeout logic. Defaults to + TimeoutStartSec= from the + manager configuration file. @@ -536,18 +645,18 @@ WatchdogSec= Configures the - watchdog timeout for a service. This - is activated when the start-up is + watchdog timeout for a service. The + watchdog is activated when the start-up is completed. The service must call sd_notify3 - regularly with "WATCHDOG=1" (i.e. the - "keep-alive ping"). If the time + regularly with WATCHDOG=1 + (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 failure state. By + the configured time, then the service + is placed in a failed state. By setting Restart= to or - the service + , the service will be automatically restarted. The time configured here will be passed to the executed service process in the @@ -556,7 +665,7 @@ daemons to automatically enable the keep-alive pinging logic if watchdog support is enabled for the service. If - this option is used + this option is used, NotifyAccess= (see below) should be set to open access to the notification socket provided by @@ -571,37 +680,74 @@ Restart= Configures whether the - main service process shall be - restarted when it exits. Takes one of + service shall be restarted when the + service process exits, is killed, + or a timeout is reached. The service + process may be the main service + process, but it may also be one of the + processes specified with + ExecStartPre=, + ExecStartPost=, + ExecStop=, + ExecStopPost=, or + ExecReload=. + When the death of the process is a + result of systemd operation (e.g. service + stop or restart), the service will not be + restarted. Timeouts include missing + the watchdog "keep-alive ping" + deadline and a service start, reload, + and stop operation timeouts. + + Takes one of , , , - or + , + , or . If set to - (the default) the - service will not be restarted when it - exits. If set to - it will be - restarted only when it exited cleanly, - i.e. terminated with an exit code of - 0. If set to - it will be - restarted only when it exited with an - exit code not equaling 0, when - terminated by a signal (including on + (the default), the + service will not be restarted. If set to + , it will be + restarted only when the service process + exits cleanly. + In this context, a clean exit means + an exit code of 0, or one of the signals + SIGHUP, + SIGINT, + SIGTERM, + or SIGPIPE, and + additionally, exit statuses and signals + specified in SuccessExitStatus=. + If set to , + the service will be restarted when the + process exits with a non-zero exit code, + is terminated by a signal (including on core dump), when an operation (such as - service reload) times out or when the - configured watchdog timeout is - triggered. If set to - it will be - restarted only if it exits due to - reception of an uncaught signal - (including on core dump). If set to - the service - will be restarted regardless whether + service reload) times out, and when the + configured watchdog timeout is triggered. + If set to + , the service + will be restarted only if the service + process exits due to an uncaught + signal not specified as a clean exit + status. + If set to + , the service + will be restarted only if the watchdog + timeout for the service expires. + If set to + , the service + will be restarted regardless of whether it exited cleanly or not, got - terminated abnormally by a signal or - hit a timeout. + terminated abnormally by a signal, or + hit a timeout. + + In addition to the above settings, + the service will not be restarted if the + exit code or signal is specified in + RestartPreventExitStatus= + (see below). @@ -611,22 +757,33 @@ by the main service process will be considered successful termination, in addition to the normal successful exit - code 0 and the signals SIGHUP, SIGINT, - SIGTERM and SIGPIPE. Exit status + code 0 and the signals SIGHUP, SIGINT, + SIGTERM, and SIGPIPE. Exit status definitions can either be numeric exit - codes or termination signal names, and - are separated by spaces. Example: - "SuccessExitStatus=1 2 8 - SIGKILL", ensures that exit - codes 1, 2, 8 and the termination - signal SIGKILL are considered clean - service terminations. This option may - appear more than once in which case - the list of successful exit statuses - is merged. If the empty string is - assigned to this option the list is - reset, all prior assignments of this - option will have no + codes or termination signal names, + separated by spaces. For example: + SuccessExitStatus=1 2 8 SIGKILL + ensures that exit codes 1, 2, 8 and + the termination signal + SIGKILL are + considered clean service terminations. + + + Note that if a process has a + signal handler installed and exits by + calling + _exit2 + in response to a signal, the + information about the signal is lost. + Programs should instead perform cleanup and kill themselves with the same signal instead. See + Proper handling of SIGINT/SIGQUIT — How to be a proper program. + + This option may appear more than once, + in which case the list of successful + exit statuses is merged. If the empty + string is assigned to this option, the + list is reset, all prior assignments + of this option will have no effect. @@ -635,7 +792,7 @@ Takes a list of exit status definitions that when returned by the main service process will - prevent automatic service restarts + prevent automatic service restarts, regardless of the restart setting configured with Restart=. Exit @@ -643,19 +800,20 @@ numeric exit codes or termination signal names, and are separated by spaces. Defaults to the empty list, so - that by default no exit status is + that, by default, no exit status is excluded from the configured restart logic. Example: - "RestartPreventExitStatus=1 6 - SIGABRT", ensures that exit + RestartPreventExitStatus=1 6 + SIGABRT, ensures that exit codes 1 and 6 and the termination - signal SIGABRT will not result in - automatic service restarting. This - option may appear more than once in - which case the list of restart preventing + signal SIGABRT will + not result in automatic service + restarting. This + option may appear more than once, in + which case the list of restart-preventing statuses is merged. If the empty - string is assigned to this option the - list is reset, all prior assignments + string is assigned to this option, the + list is reset and all prior assignments of this option will have no effect. @@ -663,20 +821,20 @@ PermissionsStartOnly= Takes a boolean - argument. If true, the permission - related execution options as + argument. If true, the permission-related + execution options, as configured with User= and similar options (see systemd.exec5 - for more information) are only applied + for more information), are only applied to the process started with ExecStart=, and not to the various other ExecStartPre=, ExecStartPost=, ExecReload=, - ExecStop=, + ExecStop=, and ExecStopPost= commands. If false, the setting is applied to all configured commands the @@ -687,19 +845,19 @@ RootDirectoryStartOnly= Takes a boolean - argument. If true, the root directory + argument. If true, the root directory, as configured with the RootDirectory= option (see systemd.exec5 - for more information) is only applied + for more information), is only applied to the process started with ExecStart=, and not to the various other ExecStartPre=, ExecStartPost=, ExecReload=, - ExecStop=, + ExecStop=, and ExecStopPost= commands. If false, the setting is applied to all configured commands the @@ -709,12 +867,14 @@ NonBlocking= - Set O_NONBLOCK flag + Set the + O_NONBLOCK flag for all file descriptors passed via socket-based activation. If true, all file descriptors >= 3 (i.e. all except - STDIN/STDOUT/STDERR) will have - the O_NONBLOCK flag set and hence are in + stdin, stdout, and stderr) will have + the O_NONBLOCK flag + set and hence are in non-blocking mode. This option is only useful in conjunction with a socket unit, as described in @@ -732,13 +892,13 @@ (the default), or . If - no daemon status + , no daemon status updates are accepted from the service processes, all status update messages - are ignored. If + are ignored. If , only service updates sent from the main process of the service are - accepted. If all + accepted. If , all services updates from all members of the service's control group are accepted. This option should be set to @@ -747,8 +907,8 @@ Type=notify or WatchdogSec= (see above). If those options are used but - NotifyAccess= not - configured it will be implicitly set + NotifyAccess= is not + configured, it will be implicitly set to . @@ -770,11 +930,11 @@ passed to multiple processes at the same time. Also note that a different service may be activated on incoming - traffic than inherits the sockets. Or - in other words: the + traffic than that which inherits the + sockets. Or in other words: the Service= setting of .socket units - doesn't have to match the inverse of + does not have to match the inverse of the Sockets= setting of the .service it @@ -783,8 +943,8 @@ This option may appear more than once, in which case the list of socket units is merged. If the empty string - is assigned to this option the list of - sockets is reset, all prior uses of + is assigned to this option, the list of + sockets is reset, and all prior uses of this setting will have no effect. @@ -794,34 +954,37 @@ StartLimitBurst= Configure service - start rate limiting. By default - services which are started more often - than 5 times within 10s are not + start rate limiting. By default, + services which are started more + than 5 times within 10 seconds are not permitted to start any more times - until the 10s interval ends. With - these two options this rate limiting + until the 10 second interval ends. With + these two options, this rate limiting may be modified. Use StartLimitInterval= - to configure the checking interval - (defaults to 10s, set to 0 to disable + to configure the checking interval (defaults to + DefaultStartLimitInterval= in + manager configuration file, set to 0 to disable any kind of rate limiting). Use StartLimitBurst= to configure how many starts per interval - are allowed (defaults to 5). These + are allowed (defaults to + DefaultStartLimitBurst= in + manager configuration file). These configuration options are particularly useful in conjunction with - Restart=, however - apply to all kinds of starts + Restart=; however, + they apply to all kinds of starts (including manual), not just those triggered by the Restart= logic. Note that units which are configured for Restart= and which reach the start limit are not - attempted to be restarted anymore, - however they may still be restarted - manually at a later point from which - point on the restart logic is again + attempted to be restarted anymore; + however, they may still be restarted + manually at a later point, from which + point on, the restart logic is again activated. Note that systemctl reset-failed will cause the @@ -845,18 +1008,17 @@ hit. Takes one of , , - or + , or . If is set, hitting the rate limit will trigger no action besides that the start will not - be - permitted. + be permitted. causes a reboot following the normal shutdown procedure (i.e. equivalent to - systemctl reboot), + systemctl reboot). causes - an forced reboot which will terminate + a forced reboot which will terminate all processes forcibly but should cause no dirty file systems on reboot (i.e. equivalent to systemctl @@ -865,10 +1027,34 @@ causes immediate execution of the reboot2 system call, which might result in - data loss. Defaults to + data loss. Defaults to . + + RebootArgument= + Configure the optional + argument for the + reboot2 + system call if + StartLimitAction= + is a reboot action. This works just + like the optional argument to + systemctl reboot + command. + + + + 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 . + + + Check @@ -887,7 +1073,7 @@ for compatibility reasons and should not be used in newly written service files. - + SysVStartPriority= Set the SysV start @@ -895,49 +1081,21 @@ 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 + to legacy SysV services that have no ordering information encoded in the - script headers. As such it should only - be used as temporary compatibility - option, and not be used in new unit - files. Almost always it is a better + 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 + instead. For more details, see + systemd.unit5. + If used, pass an integer value in the range 0-99. - - - FsckPassNo= - Set the fsck passno - priority to use to order this service - in relation to other file system - checking services. This option is only - necessary to fix ordering in relation - to fsck jobs automatically created for - all /etc/fstab - entries with a value in the fs_passno - column > 0. As such it should only be - used as option for fsck - services. 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 - same range as - /etc/fstab's - fs_passno column. See - fstab5 - for details. - - @@ -948,6 +1106,7 @@ systemctl8, systemd.unit5, systemd.exec5, + systemd.resource-control5, systemd.kill5, systemd.directives7