X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=0454cf292ef199c3a36bd94b995f5a1019e0bc01;hp=1946d85f483ea3e85a98a3c7eab67c100c92a1c3;hb=d2bbca6855b174fb7ea90b4767a886bb88bd2400;hpb=9ed63f16131637fc0e76bd40b5452cfc45bccfc7 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 1946d85f4..0454cf292 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -48,7 +48,7 @@ - systemd.service + service.service @@ -100,7 +100,7 @@ script. This is useful for compatibility with SysV. Note that this compatibility is quite comprehensive but not 100%. For details about the - incomptibilities see the Incompatibilities with SysV document. @@ -121,7 +121,7 @@ options specific to the [Service] section of service units are the following: - + Type= @@ -160,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 @@ -171,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 @@ -180,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 @@ -197,7 +197,7 @@ BusName= is specified. - Behaviour of + Behavior of is similar to , however it is expected that the daemon sends a @@ -216,10 +216,10 @@ not set, it will be implicitly set to . - Behaviour of + Behavior of is very similar to , however - actual execution of a the service + actual execution of the service binary is delayed until all jobs are dispatched. This may be used to avoid interleaving of output of shell @@ -245,7 +245,7 @@ Takes a boolean value that specifies whether systemd should try to guess the main PID of a service - should if it cannot be determined + if it cannot be determined reliably. This option is ignored unless is set and @@ -283,7 +283,7 @@ BusName= Takes a D-Bus bus - name, where this service is reachable + name, that this service is reachable as. This option is mandatory for services where Type= is set to @@ -296,52 +296,62 @@ ExecStart= - Takes a command line - that is executed when this service - shall be started up. The first token - of the command line must be an - absolute file name, then followed by - arguments for the process. It is - mandatory to set this option for all - services. This option may not be - specified more than once, except when + Commands with their + arguments that are executed when this + service is started. The first + argument must be an absolute path + name. + + When Type is + not , only one + command may be given. When Type=oneshot is - used in which case more than one - ExecStart= line is - accepted which are then invoked one by - one, sequentially in the order they - appear in the unit file. - - Optionally, if the absolute file - name is prefixed with - @, the second token - will be passed as - argv[0] to the - executed process, followed by the - further arguments specified. If the - first token 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 for the - same command the former must precede - the latter. Unless + 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. However, + the latter syntax is not recommended + for compatibility with parsers + suitable for XDG + .desktop files. + 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. + + 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. + + Unless Type=forking is set, the process started via this command line will be considered the - main process of the daemon. The - command line accepts % specifiers as + main process of the daemon. + + The command line accepts + '%' specifiers as described in - systemd.unit5. + 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 + Basic environment variable + substitution is supported. Use ${FOO} as part of a - word, or as 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 @@ -351,38 +361,66 @@ 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 + at whitespace, resulting in zero 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. + may not be a variable, since it must + be a literal and absolute path + name. + + Optionally, if the absolute file + name is prefixed with + '@', 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 + 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 + 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 + 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. + ExecStartPre= ExecStartPost= Additional commands - that are executed before (resp. after) + that are executed before or after the command in - ExecStart=. Multiple - command lines may be concatenated in a - single directive, by separating them - by semicolons (these semicolons must - be passed as separate words). In that - case, the commands are executed one - after the other, - serially. Alternatively, these - directives 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. - Use of these settings is - optional. Specifier and environment - variable substitution is - supported. + ExecStart=, respectively. + Syntax is the same as for + ExecStart=, except + 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. + @@ -391,20 +429,23 @@ trigger a configuration reload in the service. This argument takes multiple command lines, following the same - scheme as pointed out for - ExecStartPre= + scheme as described for + ExecStart= above. Use of this setting is optional. Specifier and environment variable substitution is supported here following the same scheme as for - ExecStart=. One - 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. + ExecStart=. + + One additional special + environment variables 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 + @@ -413,9 +454,8 @@ stop the service started via ExecStart=. This argument takes multiple command lines, - following the same scheme as pointed - out for - ExecStartPre= + following the same scheme as described + for ExecStart= above. Use of this setting is optional. All processes remaining for a service after the commands @@ -429,7 +469,7 @@ service stop is requested. Specifier and environment variable substitution is supported (including - $MAINPID, see + $MAINPID, see above). @@ -437,13 +477,15 @@ 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 doesn't have any + ExecStop= defined, or + where the service exited unexpectedly. This argument takes multiple command lines, - following the same scheme as pointed - out for - ExecStartPre. Use + following the same scheme as described + for ExecStart. Use of these settings is optional. Specifier and environment variable substitution is @@ -511,8 +553,8 @@ 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 @@ -546,37 +588,122 @@ 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 also one of the processes + specified with + ExecStartPre=, + ExecStartPost=, + ExecStopPre=, + 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 + service will not be restarted. 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 equalling 0, when - terminated by a signal (including on + 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 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 + 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 regardless whether it exited cleanly or not, got terminated abnormally by a signal or - hit a timeout. + 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). + + + + 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, + 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 + effect. + + + + 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. 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 + of this option will have no + effect. @@ -664,7 +791,7 @@ open access to the notification socket when using Type=notify or - WatchdogUsec= (see + WatchdogSec= (see above). If those options are used but NotifyAccess= not configured it will be implicitly set @@ -690,13 +817,22 @@ same time. Also note that a different service may be activated on incoming traffic than inherits the sockets. Or - in other words: The + in other words: the Service= setting of .socket units - doesn't have to match the inverse of the - Sockets= setting of - the .service it - refers to. + doesn't have to match the inverse of + the Sockets= + setting of the + .service it + refers to. + + 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 + this setting will have no + effect. @@ -797,7 +933,7 @@ for compatibility reasons and should not be used in newly written service files. - + SysVStartPriority= Set the SysV start @@ -858,7 +994,8 @@ systemctl8, systemd.unit5, systemd.exec5, - systemd.kill5 + systemd.kill5, + systemd.directives7