X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=a82dfb2c86496c11eb14f702ec0ece5c7f16b62a;hp=72b872beced11be7146da478c10c6dd3913b548e;hb=501996231293506a85bf4d610938a655ddc8cb92;hpb=29e254f7f093c07a1ec7e845e60203357f585235 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 72b872bec..a82dfb2c8 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -103,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. @@ -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 @@ -172,28 +173,32 @@ 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 - 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 - , 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 @@ -204,12 +209,12 @@ 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, @@ -227,7 +232,7 @@ 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 @@ -260,7 +265,7 @@ 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 @@ -292,14 +297,53 @@ 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. + + + + + BusPolicy= + + If specfied, 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. @@ -314,22 +358,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 @@ -362,12 +411,12 @@ If more than one command is specified, the commands are invoked - one by one 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. + 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 @@ -387,7 +436,7 @@ 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 @@ -410,12 +459,12 @@ fashion may be defined through Environment= and EnvironmentFile=. - In addition, variables listed in + In addition, variables listed in the section "Environment variables in spawned processes" in - systemd.exec5 + systemd.exec5, which are considered "static - configuration" may used (this includes + configuration", may be used (this includes e.g. $USER, but not $TERM). @@ -442,26 +491,22 @@ be used, they need to be passed explicitly to a shell implementation of some kind. Example: - ExecStart=/bin/sh -c 'dmesg | tac' - - + ExecStart=/bin/sh -c 'dmesg | tac' Example: - ExecStart=/bin/echo one ; /bin/echo "two two" - + ExecStart=/bin/echo one ; /bin/echo "two two" This will execute /bin/echo two - times, each time with one argument, + times, each time with one argument: one and two two, - respectively. Since two commands are + respectively. Because two commands are specified, Type=oneshot must be used. Example: ExecStart=/bin/echo / >/dev/null & \; \ -/bin/ls - +/bin/ls This will execute /bin/echo with five arguments: /, @@ -472,8 +517,7 @@ Example: Environment="ONE=one" 'TWO=two two' -ExecStart=/bin/echo $ONE $TWO ${TWO} - +ExecStart=/bin/echo $ONE $TWO ${TWO} This will execute /bin/echo with four arguments: one, @@ -517,14 +561,28 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} here following the same scheme as for ExecStart=. - One additional special - environment variables is set: if known + 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 + + 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. @@ -537,15 +595,15 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 + process is terminated immediately when service stop is requested. Specifier and environment variable substitution is supported (including @@ -591,16 +649,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 TimeoutStartSec= from the - manager configuration file, except when - Type=oneshot is + 20s". Pass 0 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. + is disabled by default + (see systemd-systemd.conf5). @@ -608,18 +668,20 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 TimeoutStartSec= from the - manager configuration file. + 20s". Pass 0 to disable + the timeout logic. Defaults to + DefaultTimeoutStopSec= from the + manager configuration file + (see systemd-systemd.conf5). @@ -639,11 +701,11 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 + is placed in a failed state. By setting Restart= to or , the service @@ -674,11 +736,11 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} service process exits, is killed, or a timeout is reached. The service process may be the main service - process, but also one of the processes - specified with + process, but it may also be one of the + processes specified with ExecStartPre=, ExecStartPost=, - ExecStopPre=, + ExecStop=, ExecStopPost=, or ExecReload=. When the death of the process is a @@ -693,48 +755,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 - SIGHUP, SIGINT, SIGTERM, or SIGPIPE, and - additionally, exit statuses and signals - specified in SuccessExitStatus=. + 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 an nonzero 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 - terminated abnormally by a signal or + 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. + @@ -748,33 +913,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. @@ -782,7 +944,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 @@ -790,40 +952,52 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 + 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 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 + list is reset and all prior assignments of this option will have no 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 - 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 @@ -834,19 +1008,19 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 @@ -856,12 +1030,14 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 @@ -917,8 +1093,8 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 does not have to match the inverse of @@ -931,7 +1107,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 + sockets is reset, and all prior uses of this setting will have no effect. @@ -942,10 +1118,10 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} Configure service start rate limiting. By default, - services which are started more often - than 5 times within 10s are not + 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 + until the 10 second interval ends. With these two options, this rate limiting may be modified. Use StartLimitInterval= @@ -960,18 +1136,18 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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 @@ -995,30 +1171,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 + , + , + , + 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 - an forced reboot which will terminate - all processes forcibly but should - cause no dirty file systems on reboot + systemctl 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 @@ -1045,22 +1254,21 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} 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. - @@ -1068,7 +1276,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} See Also systemd1, - systemctl8, + systemctl1, systemd.unit5, systemd.exec5, systemd.resource-control5,