X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=a15dfb2cb69876dec403fb4fa9fea087bc578f1d;hp=891b3474aae66211b69e3bb73f40d84050a5f353;hb=44ded3abc28620279633f51a05f2416e5aa3e8e2;hpb=28137202027b07fec5c270c1b1ef12ebaf35d58d diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 891b3474a..a15dfb2cb 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -48,7 +48,7 @@ - systemd.service + service.service @@ -73,9 +73,12 @@ systemd.exec5, which define the execution environment the commands are executed in, and in - systemd.kill5 + systemd.kill5, which define the way the processes of the service are - terminated. + terminated, and in + systemd.cgroup5, + which configure control group settings for the + processes of the service. Unless DefaultDependencies= is set to , service units will @@ -121,7 +124,7 @@ options specific to the [Service] section of service units are the following: - + Type= @@ -214,7 +217,11 @@ systemd. If NotifyAccess= is not set, it will be implicitly set to - . + . Note that + currently + Type= + won't work if used in combination with + PrivateNetwork=. Behavior of is very similar @@ -298,10 +305,13 @@ ExecStart= Commands with their arguments that are executed when this - service is started. - + service is started. The first + argument must be an absolute path + name. - When + When Type is + not , only one + command may be given. When Type=oneshot is used, more than one command may be specified. Multiple command lines may @@ -315,19 +325,22 @@ for compatibility with parsers suitable for XDG .desktop files. - The commands are invoked one by one - sequentially in the order they appear - in the unit file. When - Type is not - , only one - command may be given. Lone semicolons - may be escaped as - '\;'. If the empty + 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 @@ -335,16 +348,15 @@ main process of the daemon. The command line accepts - '%' specifiers as + % specifiers as described in 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 a word of its own on the command line, in which case it will be @@ -356,28 +368,28 @@ 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 + 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 + @, 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 + absolute filename 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 + - and + @ are used they can appear in either order. Note that this setting does not @@ -385,13 +397,14 @@ 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' + 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 + $MANAGERPID is set to the PID of the systemd instance. @@ -409,6 +422,11 @@ 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. @@ -424,14 +442,17 @@ optional. Specifier and environment variable substitution is supported here following the same scheme as for - ExecStart=. One - additional special environment - variables is set: if known - $MAINPID is set to + 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. + following: + + /bin/kill -HUP $MAINPID + @@ -455,7 +476,7 @@ service stop is requested. Specifier and environment variable substitution is supported (including - $MAINPID, see + $MAINPID, see above). @@ -463,9 +484,12 @@ 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 does not have any + ExecStop= defined, or + where the service exited unexpectedly. This argument takes multiple command lines, following the same scheme as described for ExecStart. Use @@ -512,9 +536,9 @@ 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 + forcibly via SIGTERM, and after another delay of this time with - SIGKILL (See + SIGKILL (See KillMode= in systemd.kill5). Takes a unit-less value in seconds, or a @@ -536,8 +560,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 @@ -571,37 +595,66 @@ 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 equaling 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). @@ -611,15 +664,15 @@ 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 + 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 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 + signal SIGKILL are considered clean service terminations. This option may appear more than once in which case the list of successful exit statuses @@ -646,8 +699,8 @@ that by default no exit status is excluded from the configured restart logic. Example: - "RestartPreventExitStatus=1 6 - SIGABRT", ensures that exit + RestartPreventExitStatus=1 6 + SIGABRT, ensures that exit codes 1 and 6 and the termination signal SIGABRT will not result in automatic service restarting. This @@ -774,7 +827,7 @@ in other words: the Service= setting of .socket units - doesn't have to match the inverse of + does not have to match the inverse of the Sockets= setting of the .service it @@ -887,7 +940,7 @@ for compatibility reasons and should not be used in newly written service files. - + SysVStartPriority= Set the SysV start @@ -948,6 +1001,7 @@ systemctl8, systemd.unit5, systemd.exec5, + systemd.cgroup5, systemd.kill5, systemd.directives7