X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=339dea9aa503d8ab3787a3ea68edb8f38b7f4dc5;hp=11f98c34d6537b5ae08277fb7805f37ae48b909e;hb=c6511e859c35b12de4e6fb5f58d7258d9de3b8f2;hpb=66b1a24790ccc3c60509e6f94890ed8c20a2fe9e diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 11f98c34d..339dea9aa 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -44,7 +44,7 @@ systemd.service - systemd service configuration files + Service unit configuration @@ -72,7 +72,10 @@ Additional options are listed in systemd.exec5, which define the execution environment the commands - are executed in. + are executed in, and in + systemd.kill5 + which define the way the processes of the service are + terminated. Unless DefaultDependencies= is set to , service units will @@ -95,7 +98,12 @@ .service suffix removed) and dynamically creates a service unit from that script. This is useful for compatibility with - SysV. + SysV. Note that this compatibility is quite + comprehensive but not 100%. For details about the + incomptibilities see the Incompatibilities + with SysV document. + @@ -107,7 +115,9 @@ supervises. A number of options that may be used in this section are shared with other unit types. These options are documented in - systemd.exec5. The + systemd.exec5 + and + systemd.kill5. The options specific to the [Service] section of service units are the following: @@ -150,7 +160,7 @@ complete and all communication channels set up. The child continues to run as the main daemon - process. This is the behaviour of + process. This is the behavior of traditional UNIX daemons. If this setting is used, it is recommended to also use the @@ -161,7 +171,7 @@ soon as the parent process exits. - Behaviour of + Behavior of is similar to , however it is expected that the process has to @@ -170,7 +180,7 @@ is particularly useful for this type of service. - Behaviour of + Behavior of is similar to , however it is expected that the daemon acquires a @@ -187,7 +197,7 @@ BusName= is specified. - Behaviour of + Behavior of is similar to , however it is expected that the daemon sends a @@ -206,7 +216,7 @@ not set, it will be implicitly set to . - Behaviour of + Behavior of is very similar to , however actual execution of a the service @@ -346,7 +356,16 @@ argument (i.e. the program to execute) may not be a variable, and must be a literal and absolute path - name. + name. + + 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' + @@ -412,12 +431,13 @@ configured in this option are run are terminated according to the KillMode= setting - (see below). If this option is not - specified the process is terminated - right-away when service stop is - requested. Specifier and environment - variable substitution is supported - (including + (see + systemd.kill5). If + this option is not specified the + process is terminated right-away when + service stop is requested. Specifier + and environment variable substitution + is supported (including $MAINPID, see above). @@ -452,25 +472,49 @@ - TimeoutSec= + TimeoutStartSec= Configures the time to - wait for start-up and stop. If a + wait for start-up. If a daemon service does not signal start-up completion within the - configured time the service will be + configured time, the service will be considered failed and be shut down - again. If a service is asked to stop - but does not terminate in the - specified time it will be terminated + 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 + is disabled by default. + + + + + TimeoutStopSec= + Configures the time to + wait for stop. If a service is asked + 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 + SIGKILL (See KillMode= - below.) Takes a unit-less value in seconds, or a + 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. + logic. Defaults to 90s. + + + + + TimeoutSec= + A shorthand for configuring + both TimeoutStartSec= + and TimeoutStopSec= + to the specified value. + @@ -480,26 +524,29 @@ is activated when the start-up is completed. The service must call sd_notify3 - regularly with "WATCHDOG=1". If the - time between two such calls is larger - than the configured time then the - service is placed in a failure - state. By setting - Restart= - to or + 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 + setting Restart= to + or the service will be automatically restarted. The time configured here will be passed to the executed service process in the WATCHDOG_USEC= - environment variable. If + environment variable. This allows + daemons to automatically enable the + keep-alive pinging logic if watchdog + support is enabled for the service. If 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 + NotifyAccess= is + not set, it will be implicitly set to . Defaults to 0, which disables this feature. @@ -525,18 +572,63 @@ it will be restarted only when it exited with an exit code not equalling 0, when - terminated by a signal, when an - operation times out or when the + 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. If - set to the - service will be restarted regardless - whether it exited cleanly or not, - got terminated abnormally by a - signal or hit a timeout. + reception of an uncaught signal + (including on core dump). If set to + the service + will be restarted regardless whether + it exited cleanly or not, got + terminated abnormally by a signal or + hit a timeout. + + + + SuccessExitStatus= + Takes a list of exit + status definitions that when returned + 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 + 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. + + + + RestartPreventExitStatus= + Takes a list of exit + status definitions that when returned + by the main service process will + prevent automatic service restarts + regardless of the restart setting + configured with + Restart=. Exit + status definitions can either be + 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 + excluded from the configured restart + logic. Example: + "RestartPreventExitStatus=1 6 + SIGABRT", ensures that exit + codes 1 and 6 and the termination signal + SIGABRT will not result in automatic + service restarting. @@ -586,95 +678,6 @@ false. - - 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 temporary compatibility - option, and 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. - - - - KillMode= - Specifies how - processes of this service shall be - killed. One of - , - , - . - - If set to - all - remaining processes in the control - group of this service will be - terminated on service stop, after the - stop command (as configured with - ExecStop=) is - executed. If set to - only the main - process itself is killed. If set to - no process is - killed. In this case only the stop - command will be executed on service - stop, but no process be killed - otherwise. Processes remaining alive - after stop are left in their control - group and the control group continues - to exist after stop unless it is - empty. Defaults to - . - - Processes will first be - terminated via SIGTERM (unless the - signal to send is changed via - KillSignal=). If - then after a delay (configured via the - TimeoutSec= option) - processes still remain, the - termination request is repeated with - the SIGKILL signal (unless this is - disabled via the - SendSIGKILL= - option). See - kill2 - for more - information. - - - - KillSignal= - Specifies which signal - to use when killing a - service. Defaults to SIGTERM. - - - - - SendSIGKILL= - Specifies whether to - send SIGKILL to remaining processes - after a timeout, if the normal - shutdown procedure left processes of - the service around. Takes a boolean - value. Defaults to "yes". - - - NonBlocking= Set O_NONBLOCK flag @@ -748,33 +751,6 @@ refers to. - - 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. - - StartLimitInterval= StartLimitBurst= @@ -796,7 +772,27 @@ are allowed (defaults to 5). These configuration options are particularly useful in conjunction with - Restart=. + Restart=, however + 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 + activated. Note that + systemctl + reset-failed will cause the + restart rate counter for a service to + be flushed, which is useful if the + administrator wants to manually start + a service and the start limit + interferes with + that. @@ -836,6 +832,75 @@ + + Check + systemd.exec5 + and + systemd.kill5 + for more settings. + + + + + Compatibility Options + + 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. + + + + 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 temporary compatibility + option, and 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. + + + + 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. + + + @@ -844,7 +909,8 @@ systemd1, systemctl8, systemd.unit5, - systemd.exec5 + systemd.exec5, + systemd.kill5