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=5230a78337e34b9ca3a2e532b83283928c4b748d;hb=d2bbca6855b174fb7ea90b4767a886bb88bd2400;hpb=af62c704053b5d34672497eb5bdc4764ebbb5f4f diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 5230a7833..0454cf292 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -9,16 +9,16 @@ Copyright 2010 Lennart Poettering systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -44,169 +44,958 @@ systemd.service - systemd service configuration files + Service unit configuration - systemd.service + service.service Description - A configuration file ending in .service encodes - information about a process controlled and supervised - by systemd. + A unit configuration file whose name ends in + .service encodes information + about a process controlled and supervised by + systemd. This man page lists the configuration options specific to this unit type. See systemd.unit5 for the common options of all unit configuration - files. + files. The common configuration items are configured + in the generic [Unit] and + [Install] sections. The service + specific configuration options are configured in the + [Service] section. + + Additional options are listed in + systemd.exec5, + which define the execution environment the commands + are executed in, and in + systemd.kill5 + which define the way the processes of the service are + terminated. + + Unless DefaultDependencies= + is set to , service units will + implicitly have dependencies of type + Requires= and + After= on + basic.target as well as + dependencies of type Conflicts= and + Before= on + shutdown.target. These ensure + that normal service units pull in basic system + initialization, and are terminated cleanly prior to + system shutdown. Only services involved with early + boot or late system shutdown should disable this + option. + + If a service is requested under a certain name + but no unit configuration file is found, systemd looks + for a SysV init script by the same name (with the + .service suffix removed) and + dynamically creates a service unit from that + 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. + Options - + Service files must include a + [Service] section, which carries + information about the service and the process it + supervises. A number of options that may be used in + this section are shared with other unit types. These + options are documented in + systemd.exec5 + and + systemd.kill5. The + options specific to the [Service] + section of service units are the following: + + Type= - - One of - forking, - simple, - finish, - dbus. - - If set to - forking - (the default) it is expected - that the process configured - with - ExecStart= - will start up and call - fork(). The - parent process is expected to - finish when start-up is - complete and all communication - channels set up. The child - continues to run as the main - daemon process. This is the - behaviour of traditional UNIX - daemons. If this setting is - used, it is recommended to also - use the - 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 exits. - - If set to - simple (the - recommended value) it is - expected that the process - configured with - ExecStart= - is the main process of the - daemon. In this mode, - communication channels must be - available before the daemon is - started up (sockets set up by systemd), - as systemd will immediately proceed - starting follow-up units. - - Behaviour of - finish is - similar to - simple, - however it is expected that - the process has to exit before - systemd starts follow-up - units. ValidNoProcess= - is particularly useful for - this type of service. - - Behaviour of - dbus is - similar to - simple, - 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 - acquired. + + Configures the process + start-up type for this service + unit. One of , + , + , + , + or + . + + If set to + (the default + value if BusName= + 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 + should be installed before the daemon + is started up (e.g. sockets set up by + systemd, via socket activation), as + systemd will immediately proceed + starting follow-up units. + + If set to + 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 + to run as the main daemon + process. This is the behavior of + traditional UNIX daemons. If this + setting is used, it is recommended to + also use the + 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 + exits. + + Behavior of + 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. + + Behavior of + is similar to + , 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 + acquired. Service units with this + option configured implicitly gain + dependencies on the + dbus.socket + unit. This type is the default if + BusName= is + specified. + + Behavior of + is similar to + , 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 + starting follow-up units after this + notification message has been sent. If + 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 + . + + Behavior of + is very similar + to , however + actual execution of the service + binary is delayed until all jobs are + dispatched. This may be used to avoid + interleaving of output of shell + services with the status output on the + console. + + + + + RemainAfterExit= + + Takes a boolean value + that specifies whether the service + shall be considered active even when + all its processes exited. Defaults to + . + - ValidNoProcess= - - Takes a boolean value - that specifies whether the service - shall be considered active - even when all its processes - exited. Defaults to no. + GuessMainPID= + + Takes a boolean value + that specifies whether systemd should + try to guess the main PID of a service + if it cannot be determined + reliably. This option is ignored + unless + is set and + is unset because for the other types + or with an explicitly configured PID + 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 + the main PID cannot be determined + failure detection and automatic + restarting of a service will not work + reliably. Defaults to + . PIDFile= - - Takes an absolute file - name pointing to the PID file - of this daemon. Use of this - option is recommended for - services where - Type= is - set to - forking. + + Takes an absolute file + name pointing to the PID file of this + daemon. Use of this option is + recommended for services where + Type= is set to + . systemd will + read the PID of the main process of + the daemon after start-up of the + service. systemd will not write to the + file configured here. BusName= - - Takes a D-Bus bus name, - where this service is reachable - as. This option is mandatory - for services where - Type= is - set to - dbus, but - its use is otherwise - recommended as well if the - process takes a name on the - D-Bus bus. + + Takes a D-Bus bus + 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. ExecStart= - - Takes a command line - that is executed when this - service shall be started - up. The first word of the - command line must be an - absolute file name. It is - mandatory to set this option - for all services. + 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, 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 + described in + 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 + ${FOO} as part of a + 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 + whitespace it contains, resulting in a + single argument. Use + $FOO as a separate + 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 zero or + more arguments. 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. + + 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 or after + the command in + 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. + + + + + ExecReload= + Commands to execute to + trigger a configuration reload in the + service. This argument takes multiple + command lines, following the same + 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 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 + + + + + ExecStop= + Commands to execute to + stop the service started via + ExecStart=. This + argument takes multiple command lines, + 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 + terminated according to the + KillMode= setting + (see + systemd.kill5). If + this option is not specified the + process is terminated right-away when + service stop is requested. Specifier + and environment variable substitution + is supported (including + $MAINPID, see + above). + + + + ExecStopPost= + Additional commands + that are executed after the service + 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 described + for ExecStart. Use + of these settings is + optional. Specifier and environment + variable substitution is + supported. + + + + RestartSec= + Configures the time to + sleep before restarting a service (as + configured with + Restart=). Takes a + unit-less value in seconds, or a time + span value such as "5min + 20s". Defaults to + 100ms. + + + + TimeoutStartSec= + Configures the time to + wait for start-up. If a + daemon service does not signal + start-up completion within the + configured time, the service will be + considered failed and 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 90s, except when + Type=oneshot is + used in which case the timeout + is disabled by default. + + + + + TimeoutStopSec= + Configures the time to + 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 + another delay of this time 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 90s. + + + + + TimeoutSec= + A shorthand for configuring + both TimeoutStartSec= + and TimeoutStopSec= + to the specified value. + + + + + WatchdogSec= + Configures the + 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 + "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 + setting Restart= to + or + the service + will be automatically restarted. The + time configured here will be passed to + the executed service process in the + WATCHDOG_USEC= + environment variable. This allows + daemons to automatically enable the + keep-alive pinging logic if watchdog + support is enabled for the service. If + 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 + . Defaults to 0, + which disables this + feature. + + + + Restart= + Configures whether the + 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 + . 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=. + 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 regardless 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 + 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. + + + + PermissionsStartOnly= + Takes a boolean + argument. If true, the permission + related execution options as + configured with + User= and similar + options (see + systemd.exec5 + for more information) are only applied + to the process started with + ExecStart=, and not + to the various other + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, + ExecStopPost= + commands. If false, the setting is + applied to all configured commands the + same way. Defaults to + false. + + + + RootDirectoryStartOnly= + Takes a boolean + argument. If true, the root directory + as configured with the + RootDirectory= + option (see + systemd.exec5 + for more information) is only applied + to the process started with + ExecStart=, and not + to the various other + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, + ExecStopPost= + commands. If false, the setting is + applied to all configured commands the + same way. Defaults to + false. + + + + NonBlocking= + Set 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 + non-blocking mode. This option is only + useful in conjunction with a socket + unit, as described in + systemd.socket5. Defaults + to false. + + + + NotifyAccess= + Controls access to the + service status notification socket, as + accessible via the + sd_notify3 + call. Takes one of + (the default), + or + . If + no daemon status + updates are accepted from the service + processes, all status update messages + are ignored. If + only service updates sent from the + main process of the service are + accepted. If all + services updates from all members of + the service's control group are + accepted. This option should be set to + open access to the notification socket + when using + Type=notify or + WatchdogSec= (see + above). If those options are used but + NotifyAccess= not + configured it will be implicitly set + to + . + + + + Sockets= + Specifies the name of + the socket units this service shall + inherit the sockets from when the + service is started. Normally it + should not be necessary to use this + setting as all sockets whose unit + shares the same name as the service + (ignoring the different suffix of course) + are passed to the spawned + process. + + Note that the same socket may be + 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 + Service= setting of + .socket units + 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. + + + + StartLimitInterval= + StartLimitBurst= + + Configure service + 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 + may be modified. Use + StartLimitInterval= + to configure the checking interval + (defaults to 10s, 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 + configuration options are particularly + useful in conjunction with + Restart=, however + 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 + activated. Note that + systemctl + reset-failed will cause the + restart rate counter for a service to + be flushed, which is useful if the + administrator wants to manually start + a service and the start limit + interferes with + that. + + + + StartLimitAction= + + Configure the action + to take if the rate limit configured + with + StartLimitInterval= + and + StartLimitBurst= is + hit. Takes one of + , + , + 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 + (i.e. equivalent to systemctl + reboot -f) and + + causes immediate execution of the + reboot2 + system call, which might result in + data loss. Defaults to + . + + + + + Check + systemd.exec5 + and + systemd.kill5 + for more settings. + + + + + Compatibility Options + + The following options are also available in the + [Service] section, but exist purely + for compatibility reasons and should not be used in + newly written service files. + + + + SysVStartPriority= + Set the SysV start + priority to use to order this service + 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 + 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 + 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 + 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. + + See Also - systemd8, - systemctl8 - systemd.unit5 + systemd1, + systemctl8, + systemd.unit5, + systemd.exec5, + systemd.kill5, + systemd.directives7