X-Git-Url: http://git.ipfire.org/?p=thirdparty%2Fsystemd.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=fbb2987d0bec705a8c45255d1c04903b3ffb7d67;hp=398fd69b46979c39624df559cf319e887e01e677;hb=c53da7ed02a5d732c9449f79c19675b90a6032e3;hpb=a9ab5cdb505d7d368c44fc02cc0183e75db1f657 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 398fd69b469..fbb2987d0be 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -35,9 +35,9 @@ systemd.unit5 for the common options of all unit configuration files. The common configuration items are configured in the generic - [Unit] and [Install] + [Unit] and [Install] sections. The service specific configuration options are - configured in the [Service] section. + configured in the [Service] section. Additional options are listed in systemd.exec5, @@ -138,7 +138,7 @@ Options - Service files must include a [Service] + Service files must include a [Service] section, which carries information about the service and the process it supervises. A number of options that may be used in this section are shared with other unit types. These options are @@ -147,7 +147,7 @@ systemd.kill5 and systemd.resource-control5. - The options specific to the [Service] section + The options specific to the [Service] section of service units are the following: @@ -217,7 +217,7 @@ this notification message has been sent. If this option is used, NotifyAccess= (see below) should be set to open access to the notification socket provided by systemd. If NotifyAccess= is missing or set to , it will be forcibly set to - . + . Behavior of is very similar to ; however, actual execution of the service program is delayed until all active jobs are dispatched. This may be used @@ -464,7 +464,7 @@ of the daemon, and may be used for command lines like the following: - /bin/kill -HUP $MAINPID + ExecReload=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, @@ -473,7 +473,14 @@ other. It is strongly recommended to set ExecReload= to a command that not only triggers a configuration reload of the daemon, but also - synchronously waits for it to complete. + synchronously waits for it to complete. For example, + dbus-broker1 + uses the following: + + ExecReload=busctl call org.freedesktop.DBus \ + /org/freedesktop/DBus org.freedesktop.DBus \ + ReloadConfig + @@ -553,16 +560,12 @@ TimeoutStartSec= - Configures the time to wait for start-up. If a - daemon service does not signal start-up completion within the - configured time, the service will be 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 - infinity to disable the timeout logic. Defaults to - DefaultTimeoutStartSec= from the manager - configuration file, except when - Type=oneshot is used, in which case the - timeout is disabled by default (see + Configures the time to wait for start-up. If a daemon service does not signal start-up + completion within the configured time, the service will be considered failed and will be shut down again. The + precise action depends on the TimeoutStartFailureMode= option. Takes a unit-less value in + seconds, or a time span value such as "5min 20s". Pass infinity to disable the timeout logic. + Defaults to DefaultTimeoutStartSec= from the manager configuration file, except when + Type=oneshot is used, in which case the timeout is disabled by default (see systemd-system.conf5). @@ -581,7 +584,8 @@ This option serves two purposes. First, it configures the time to wait for each ExecStop= command. If any of them times out, subsequent ExecStop= commands are skipped and the service will be terminated by SIGTERM. If no ExecStop= - commands are specified, the service gets the SIGTERM immediately. Second, it configures the time + commands are specified, the service gets the SIGTERM immediately. This default behavior + can be changed by the TimeoutStopFailureMode= option. Second, it configures the time to wait for the service itself to stop. If it doesn't terminate in the specified time, it will be forcibly terminated by SIGKILL (see KillMode= in systemd.kill5). @@ -639,6 +643,28 @@ + + TimeoutStartFailureMode= + TimeoutStopFailureMode= + + These options configure the action that is taken in case a daemon service does not signal + start-up within its configured TimeoutStartSec=, respectively if it does not stop within + TimeoutStopSec=. Takes one of , and + . Both options default to . + + If is set the service will be gracefully terminated by sending the signal + specified in KillSignal= (defaults to SIGTERM, see + systemd.kill5). If the + service does not terminate the FinalKillSignal= is sent after + TimeoutStopSec=. If is set, WatchdogSignal= is sent + instead and TimeoutAbortSec= applies before sending FinalKillSignal=. + This setting may be used to analyze services that fail to start-up or shut-down intermittently. + By using the service is immediately terminated by sending + FinalKillSignal= without any further timeout. This setting can be used to expedite the + shutdown of failing services. + + + RuntimeMaxSec= @@ -845,35 +871,41 @@ 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, + process, will be considered successful termination, in addition to the normal successful exit status + 0 and the signals SIGHUP, SIGINT, SIGTERM, and SIGPIPE. Exit status definitions can be - numeric exit codes, termination code names, or termination signal names, separated by spaces. See the - Process Exit Codes section in + numeric termination statuses, termination status names, or termination signal names, separated by + spaces. See the Process Exit Codes section in systemd.exec5 for - a list of termination codes names (for this setting only the part without the - EXIT_ or EX_ prefix should be used). See - signal7 for + a list of termination status names (for this setting only the part without the + EXIT_ or EX_ prefix should be used). See signal7 for a list of signal names. - 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. + Note that this setting does not change the mapping between numeric exit statuses and their + names, i.e. regardless how this setting is used 0 will still be mapped to SUCCESS + (and thus typically shown as 0/SUCCESS in tool outputs) and 1 to + FAILURE (and thus typically shown as 1/FAILURE), and so on. It + only controls what happens as effect of these exit statuses, and how it propagates to the state of + the service as a whole. + + 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. - A service with with the <varname>SuccessExitStatus=</varname> setting + A service with the <varname>SuccessExitStatus=</varname> setting SuccessExitStatus=TEMPFAIL 250 SIGUSR1 - Exit codes 75 (TEMPFAIL), 250, and the termination signal - SIGKILL are considered clean service terminations. + Exit status 75 (TEMPFAIL), 250, and the termination signal + SIGUSR1 are considered clean service terminations. - Note: systemd-analyze exit-codes may be used to list exit - codes and translate between numerical code values and names. + Note: systemd-analyze exit-status may be used to list exit statuses and + translate between numerical status values and names. @@ -959,7 +991,14 @@ . Conversely, if an auxiliary process of the unit sends an sd_notify() message and immediately exits, the service manager might not be able to properly attribute the message to the unit, and thus will ignore it, even if - NotifyAccess= is set for it. + NotifyAccess= is set for it. + + Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications + to units correctly, sd_notify_barrier() may be used. This call acts as a synchronization point + and ensures all notifications sent before this call have been picked up by the service manager when it returns + successfully. Use of sd_notify_barrier() is needed for clients which are not invoked by the + service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the + unit. @@ -1039,8 +1078,8 @@ manager. If set to kill and one of the service's processes is killed by the OOM killer the kernel is instructed to kill all remaining processes of the service, too. Defaults to the setting DefaultOOMPolicy= in - system.conf5 is - set to, except for services where Delegate= is turned on, where it defaults to + systemd-system.conf5 + is set to, except for services where Delegate= is turned on, where it defaults to continue. Use the OOMScoreAdjust= setting to configure whether processes of the unit @@ -1456,7 +1495,7 @@ ExecStart=/usr/sbin/simple-dbus-service WantedBy=multi-user.target For bus-activatable services, do not - include a [Install] section in the systemd + 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):