X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=b9a2f8d82f952532ad8901827b8c10e1620bfdd8;hp=454cde4b4992eb25feda0b949dac12fb17ec8896;hb=edf2573743b25273bee020230a60f1a054b8ec60;hpb=6db2742802b70938f0f2d373110ed734d4fb9813 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 454cde4b4..b9a2f8d82 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 @@ -302,6 +307,47 @@ + + 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. + + + ExecStart= Commands with their @@ -313,22 +359,27 @@ 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 + used, none or 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. + have no effect. If no + ExecStart= is + specified, then the service must have + RemainAfterExit=yes + set. Each command line is split on whitespace, with the first item being @@ -519,6 +570,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 not only triggers a + configuration reload of the daemon, + but also synchronously waits for it to + complete. @@ -591,11 +656,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-systemd.conf5). @@ -614,8 +680,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-systemd.conf5). @@ -674,7 +741,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} processes specified with ExecStartPre=, ExecStartPost=, - ExecStopPre=, + ExecStop=, ExecStopPost=, or ExecReload=. When the death of the process is a @@ -689,51 +756,151 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} , , , + , , , or . If set to (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 + 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=. + 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, 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 + process exits with a non-zero exit + code, is terminated by a signal + (including on core dump, but excluding + the aforementiond four signals), when + an operation (such as service reload) + times out, and when the configured + watchdog timeout is triggered. If set + to , the + service will be restarted when the + process is terminated by a signal + (including on core dump, excluding the + aforementioned four signals), when an + operation times out, or when the + 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 + will be restarted regardless of + whether it exited cleanly or not, got 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 + + Exit causes and the effect of the <varname>Restart=</varname> settings on them + + + + + + + Restart settings/Exit causes + + + + + + + + + + + + Clean exit code or signal + + X + X + + + + + + + Unclean exit code + + X + + X + + + + + + Unclean signal + + X + + X + X + X + + + + Timeout + + X + + X + X + + + + + Watchdog + + X + + X + X + + X + + + +
+ + As exceptions to the setting + above the service will not be + restarted if the exit code or signal + is specified in RestartPreventExitStatus= - (see below). + (see below). Also, the services will + always be restarted if the exit code + or signal is specified in + RestartForceExitStatus= + (see below). + + Setting this to + is the + recommended choice for long-running + services, in order to increase + reliability by attempting automatic + recovery from errors. For services + that shall be able to terminate on + their own choice (and avoid + immediate restarting), + is an + alternative choice. + @@ -747,33 +914,30 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} SIGTERM, and SIGPIPE. Exit status definitions can either be numeric exit codes or termination signal names, - separated by spaces. Signals will only - be considered if the service does not implement - a signal handler and exits as a direct result - of receiving the signal. 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. + 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. @@ -791,9 +955,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 @@ -807,6 +970,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 @@ -997,29 +1172,63 @@ 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 + argument for the + reboot2 + system call if + StartLimitAction= + or FailureAction= + is a reboot action. This works just + like the optional argument to + systemctl reboot + command. + + Check @@ -1068,7 +1277,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} See Also systemd1, - systemctl8, + systemctl1, systemd.unit5, systemd.exec5, systemd.resource-control5,