X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=94e72df9b47a48cbc09ceb18e78317b311e79bd4;hp=dcf57c30bbaebd4c4b76b7e72a6fa081c9ffec93;hb=494a66821815e8109afa136bd42818b85da38c09;hpb=909f413d3c572baadf9b13e36e1e90beba42af86 diff --git a/man/systemd.service.xml b/man/systemd.service.xml index dcf57c30b..94e72df9b 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -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.resource-control5, + which configure resource control settings for the + processes of the service. Unless DefaultDependencies= is set to , service units will @@ -137,13 +140,13 @@ If set to (the default value if BusName= - is not specified) it is expected that + is not specified), it is expected that the process configured with ExecStart= is the main process of the service. In this mode, if the process offers functionality to other processes on - the system its communication channels + the system, its communication channels should be installed before the daemon is started up (e.g. sockets set up by systemd, via socket activation), as @@ -151,14 +154,14 @@ starting follow-up units. If set to - it is + , it is expected that the process configured with ExecStart= will call fork() as part of its start-up. The parent process is expected to exit when start-up is complete and all communication - channels set up. The child continues + channels are set up. The child continues to run as the main daemon process. This is the behavior of traditional UNIX daemons. If this @@ -207,14 +210,18 @@ starting up. systemd will proceed starting follow-up units after this notification message has been sent. If - this option is used + this option is used, NotifyAccess= (see below) should be set to open access to the notification socket provided by systemd. If NotifyAccess= is not set, it will be implicitly set to - . + . Note that + currently + Type= + will not work if used in combination with + PrivateNetwork=. Behavior of is very similar @@ -255,7 +262,7 @@ guessing algorithm might come to incorrect conclusions if a daemon consists of more than one process. If - the main PID cannot be determined + the main PID cannot be determined, failure detection and automatic restarting of a service will not work reliably. Defaults to @@ -298,9 +305,10 @@ ExecStart= Commands with their arguments that are executed when this - service is started. The first - argument must be an absolute path - name. + service is started. For each of the + specified commands, the first argument + must be an absolute and literal path + to an executable. When Type is not , only one @@ -313,18 +321,43 @@ (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. + once with the same effect. Lone semicolons may be escaped as \;. If the empty - string is assigned to this option the + string is assigned to this option, the list of commands to start is reset, prior assignments of this option will have no effect. + Each command line is split on + whitespace, with the first item being + the command to execute, and the + subsequent items being the arguments. + Double quotes ("...") and single + quotes ('...') may be used, in which + case everything until the next + matching quote becomes part of the + same argument. Quotes themselves are + removed after parsing. In addition, a + trailing backslash + (\) may be used to + merge lines. This syntax is intended + to be very similar to shell syntax, + but only the meta-characters and + expansions described in the following + paragraphs are understood. + Specifically, redirection using + <, + <<, + >, and + >>, pipes + using |, and + running programs in the background + using & + and other elements of shell + syntax are not supported. + + If more than one command is specified, the commands are invoked one by one sequentially in the order @@ -343,10 +376,11 @@ The command line accepts % 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. + systemd.unit5. + Note that the first argument of the + command line (i.e. the program to + execute) may not include + specifiers. Basic environment variable substitution is supported. Use @@ -362,11 +396,10 @@ case it will be replaced by the value of the environment variable split up at whitespace, resulting in zero or - more arguments. Note that the first + more arguments. To pass a literal dollar sign, + use $$. Note that the first argument (i.e. the program to execute) - may not be a variable, since it must - be a literal and absolute path - name. + may not be a variable. Optionally, if the absolute file name is prefixed with @@ -375,32 +408,66 @@ 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 + @ 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 + 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. - + Only select environment variables + are set for executed commands. See + systemd.exec5. + + + Example: + ExecStart=/bin/echo one ; /bin/echo "two two" + + This will execute + /bin/echo two + times, each time with one argument, + one and + two two, + respectively. Since two commands are + specified + Type=oneshot must + be used. + + Example: + ExecStart=/bin/echo / >/dev/null & \; \ +/bin/ls + + This will execute + /bin/echo with five + arguments: /, + >/dev/null, + &, + ;, and + /bin/ls. + + Example: + Environment="ONE=one" 'TWO=two two' +ExecStart=/bin/echo $ONE $TWO ${TWO} + + This will execute + /bin/echo with four + arguments: one, + two, + two, and + two two. + @@ -464,7 +531,7 @@ KillMode= setting (see systemd.kill5). If - this option is not specified the + this option is not specified, the process is terminated right-away when service stop is requested. Specifier and environment variable substitution @@ -480,7 +547,7 @@ was stopped. This includes cases where the commands configured in ExecStop= were used, - where the service doesn't have any + where the service does not have any ExecStop= defined, or where the service exited unexpectedly. This argument takes multiple command lines, @@ -516,9 +583,10 @@ 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 90s, except when + logic. Defaults to TimeoutStartSec= from the + manager configuration file, except when Type=oneshot is - used in which case the timeout + used, in which case the timeout is disabled by default. @@ -529,15 +597,16 @@ 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 time span value such as "5min 20s". Pass 0 to disable the timeout - logic. Defaults to 90s. + logic. Defaults to TimeoutStartSec= from the + manager configuration file. @@ -560,11 +629,11 @@ 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 + the configured time, then the service is placed in a failure state. By setting Restart= to or - the service + , the service will be automatically restarted. The time configured here will be passed to the executed service process in the @@ -573,7 +642,7 @@ daemons to automatically enable the keep-alive pinging logic if watchdog support is enabled for the service. If - this option is used + this option is used, NotifyAccess= (see below) should be set to open access to the notification socket provided by @@ -611,19 +680,20 @@ , , , + , , or . If set to - (the default) the + (the default), the service will not be restarted. If set to - it will be + , 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 + SIGHUP, SIGINT, SIGTERM, or SIGPIPE, and additionally, exit statuses and signals specified in SuccessExitStatus=. - If set to + If set to , the service will be restarted when the process exits with an nonzero exit code, is terminated by a signal (including on @@ -631,14 +701,18 @@ service reload) times out, and when the configured watchdog timeout is triggered. If set to - the service + , 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 + , 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 hit a timeout. @@ -657,20 +731,20 @@ 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, separated by spaces. Example: SuccessExitStatus=1 2 8 - SIGKILL, ensures that exit + 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 is merged. If the empty string is - assigned to this option the list is + assigned to this option, the list is reset, all prior assignments of this option will have no effect. @@ -700,7 +774,7 @@ 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 + string is assigned to this option, the list is reset, all prior assignments of this option will have no effect. @@ -778,13 +852,13 @@ (the default), or . If - no daemon status + , no daemon status updates are accepted from the service processes, all status update messages - are ignored. If + are ignored. If , only service updates sent from the main process of the service are - accepted. If all + accepted. If , all services updates from all members of the service's control group are accepted. This option should be set to @@ -793,8 +867,8 @@ Type=notify or WatchdogSec= (see above). If those options are used but - NotifyAccess= not - configured it will be implicitly set + NotifyAccess= is not + configured, it will be implicitly set to . @@ -820,7 +894,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 @@ -829,7 +903,7 @@ 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 + is assigned to this option, the list of sockets is reset, all prior uses of this setting will have no effect. @@ -840,20 +914,23 @@ StartLimitBurst= Configure service - start rate limiting. By default + start rate limiting. By default, services which are started more often than 5 times within 10s are not permitted to start any more times until the 10s interval ends. With - these two options this rate limiting + these two options, this rate limiting may be modified. Use StartLimitInterval= - to configure the checking interval - (defaults to 10s, set to 0 to disable + to configure the checking interval (defaults to + DefaultStartLimitInterval= in + manager configuration file, set to 0 to disable any kind of rate limiting). Use StartLimitBurst= to configure how many starts per interval - are allowed (defaults to 5). These + are allowed (defaults to + DefaultStartLimitBurst= in + manager configuration file). These configuration options are particularly useful in conjunction with Restart=, however @@ -957,33 +1034,6 @@ range 0-99. - - FsckPassNo= - Set the fsck passno - priority to use to order this service - in relation to other file system - checking services. This option is only - necessary to fix ordering in relation - to fsck jobs automatically created for - all /etc/fstab - entries with a value in the fs_passno - column > 0. As such it should only be - used as option for fsck - services. 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 - same range as - /etc/fstab's - fs_passno column. See - fstab5 - for details. - - @@ -994,6 +1044,7 @@ systemctl8, systemd.unit5, systemd.exec5, + systemd.resource-control5, systemd.kill5, systemd.directives7