X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=c03b4e8a540517a9a33df8cd9e98a9492795e5b3;hp=12d0b8a12b98a91d7e388c32ecc47e5d7722dcd5;hb=0a6f50c0afdfc434b492493bd9efab20cbee8623;hpb=c485d3ba094a0bf8d0165a4ba3eb5602cc21812a diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 12d0b8a12..c03b4e8a5 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1,7 +1,6 @@ - + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - systemd.service - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - systemd.service - 5 - - - - systemd.service - systemd service configuration files - - - - systemd.service - - - - Description - - 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. 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. - - 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. - - - - 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. The - options specific to the [Service] - section of service units are the following: - - - - Type= - - 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 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. - - Behaviour 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. - - Behaviour 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. - - Behaviour 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 - . - - Behaviour of - is very similar - to , however - actual execution of a 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 - . - - - - - GuessMainPID= - - Takes a boolean value - that specifies whether systemd should - try to guess the main PID of a service - should 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 - . 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 - , 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 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 - 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 - 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. - - On top of that basic environment - variable substitution is - supported. Use - ${FOO} as part of a - word, or as 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 no 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. - - - - ExecStartPre= - ExecStartPost= - Additional commands - that are executed before (resp. 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. - - - - ExecReload= - Commands to execute to - trigger a configuration reload in the - service. This argument takes multiple - command lines, following the same - scheme as pointed out for - ExecStartPre= - 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. - - - - ExecStop= - Commands to execute to - stop the service started via - ExecStart=. This - argument takes multiple command lines, - following the same scheme as pointed - out for - ExecStartPre= - 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 below). 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 using the commands - configured in - ExecStop=. This - argument takes multiple command lines, - following the same scheme as pointed - out for - ExecStartPre. 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. - - - - TimeoutSec= - Configures the time to - wait for start-up and stop. 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. 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= - below.) 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. - - - - WatchdogSec= - Configures the - watchdog timeout for a service. This - is activated when the start-up is - completed. The service must call - sd_notify3 - regularly with "WATCHDOG=1". 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. 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 - main service process shall be - restarted when it exits. Takes one of - , - , - , - or - . If set to - (the default) the - service will not be restarted when it - exits. 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, when an - operation 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. 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. - - - - 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. - - - - KillMode= - Specifies how - processes of this service shall be - killed. One of - , - , - . - - If set to - all - remaining processes in the control - group of this service will be - terminated on service stop, after the - stop command (as configured with - ExecStop=) is - executed. If set to - only the main - process itself is killed. If set to - no process is - killed. In this case only the stop - command will be executed on service - stop, but no process be killed - otherwise. Processes remaining alive - after stop are left in their control - group and the control group continues - to exist after stop unless it is - empty. Defaults to - . - - Processes will first be - terminated via SIGTERM (unless the - signal to send is changed via - KillSignal=). If - then after a delay (configured via the - TimeoutSec= option) - processes still remain, the - termination request is repeated with - the SIGKILL signal (unless this is - disabled via the - SendSIGKILL= - option). See - kill2 - for more - information. - - - - KillSignal= - Specifies which signal - to use when killing a - service. Defaults to SIGTERM. - - - - - SendSIGKILL= - Specifies whether to - send SIGKILL to remaining processes - after a timeout, if the normal - shutdown procedure left processes of - the service around. Takes a boolean - value. Defaults to "yes". - - - - - 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 - WatchdogUsec= (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. - - - - 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=. - - - - 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 - . - - - - - - - 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 - - systemd1, - systemctl8, - systemd.unit5, - systemd.exec5 - - + + systemd.service + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.service + 5 + + + + systemd.service + Service unit configuration + + + + service.service + + + + Description + + 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. 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, + and in + systemd.resource-control5, + which configure resource control settings for the processes of the + service. + + 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= + + Configures the process start-up type for this + service unit. One of + , + , + , + , + or + . + + If set to (the default if + neither Type= nor + BusName=, but ExecStart= + are 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 are 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 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 exit before systemd starts follow-up units. + RemainAfterExit= is particularly useful for + this type of service. This is the implied default if neither + Type= or ExecStart= are + specified. + + 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 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 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 has finished starting up. + systemd will proceed with 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 . Note that currently + Type= will not work + if used in combination with + PrivateNetwork=. + + 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 . + + + + + 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 + . 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 that this service is + reachable as. This option is mandatory for services where + Type= is set to + . + + + + + BusPolicy= + + If specified, 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. + + + + + ExecStart= + Commands with their arguments that are + executed when this service is started. The value is split into + zero or more command lines is according to the rules described + below (see section "Command Lines" below). + + + When Type is not + , only one command may and must be + given. When Type=oneshot is used, zero or + more commands may be specified. This can be specified by + providing multiple command lines in the same directive, or + alternatively, this directive may be specified more than once + with the same effect. 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 no + ExecStart= is specified, then the service + must have RemainAfterExit=yes set. + + For each of the specified commands, the first argument + must be an absolute path to an executable. Optionally, if this + 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 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 + can appear in either order. + + If more than one command is specified, the commands are + invoked 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. + + + + + 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 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. + + + + + 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. 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 + immediately 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 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 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 + 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 + DefaultTimeoutStartSec= from the manager + configuration file, except when + Type=oneshot is used, in which case the + timeout is disabled by default (see + systemd-system.conf5). + + + + + 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 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 + DefaultTimeoutStopSec= from the manager + configuration file (see + systemd-system.conf5). + + + + + 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 failed state and it will be terminated with + SIGABRT. 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 it may also be one of the processes + specified with ExecStartPre=, + ExecStartPost=, + ExecStop=, + 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 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 hit a timeout. + + + 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). + 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. + + + + + 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. 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. + + + + 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. 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 + statuses is merged. If the empty string is assigned to this + option, the 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 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=, and + 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=, + and ExecStopPost= commands. If false, the + setting is applied to all configured commands the same way. + Defaults to false. + + + + NonBlocking= + 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, 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 + 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= is not + configured, it will be implicitly set to + . + + + + Sockets= + Specifies the name of the socket units this + service shall inherit socket file descriptors from when the + service is started. Normally it should not be necessary to use + this setting as all socket file descriptors whose unit shares + the same name as the service (subject to the different unit + name suffix of course) are passed to the spawned + process. + + Note that the same socket file descriptors may be passed + to multiple processes simultaneously. Also note that a + different service may be activated on incoming socket traffic + than the one which is ultimately configured to inherit the + socket file descriptors. Or in other words: the + Service= setting of + .socket units does not 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, and all + prior uses of this setting will have no + effect. + + + + StartLimitInterval= + StartLimitBurst= + + Configure service start rate limiting. By + default, services which are started more than 5 times within + 10 seconds are not permitted to start any more times until the + 10 second interval ends. With these two options, this rate + limiting may be modified. Use + StartLimitInterval= 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 DefaultStartLimitBurst= in manager + configuration file). These configuration options are + particularly useful in conjunction with + 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 + 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 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. 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. + + + + FileDescriptorStoreMax= + Configure how many file descriptors may be + stored in the service manager for the service using + sd_pid_notify_with_fds3's + FDSTORE=1 messages. This is useful for + implementing service restart schemes where the state is + serialized to /run and the file + descriptors passed to the service manager, to allow restarts + without losing state. Defaults to 0, i.e. no file descriptors + may be stored in the service manager by default. All file + descriptors passed to the service manager from a specific + service are passed back to the service's main process on the + next service restart. Any file descriptors passed to the + service manager are automatically closed when POLLHUP or + POLLERR is seen on them, or when the service is fully stopped + and no job queued or being executed for it. + + + + + Check + systemd.exec5 + and + systemd.kill5 + for more settings. + + + + + Command lines + + This section describes command line parsing and + variable and specifier substitions for + ExecStart=, + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, and + ExecStopPost= options. + + Multiple command lines may be concatenated in a single + directive by separating them with semicolons (these semicolons + must be passed as separate words). Lone semicolons may be escaped + as \;. + + 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. C-style escapes are also + supported, see table below. Quotes themselves are removed after + parsing and escape sequences substituted. 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 + |, running programs in the background using + &, and other elements of shell + syntax are not supported. + + The command to execute must an absolute path name. It may + contain spaces, but control characters are not allowed. + + 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 at whitespace resulting in zero or more arguments. + For this type of expansion, quotes and respected when splitting + into words, and afterwards removed. + + 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. + + Example: + Environment=ONE='one' "TWO='two two' too" THREE= +ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} +ExecStart=/bin/echo $ONE $TWO $THREE + This results in echo being + called twice, the first time with arguments + 'one', + 'two two' too, , + and the second time with arguments + one, two two, + too. + + + To pass a literal dollar sign, use $$. + Variables whose value is not known at expansion time are treated + as empty strings. Note that the first argument (i.e. the program + to execute) may not be a variable. + + Variables to be used in this fashion may be defined through + Environment= and + EnvironmentFile=. In addition, variables listed + in the section "Environment variables in spawned processes" in + systemd.exec5, + which are considered "static configuration", may be used (this + includes e.g. $USER, but not + $TERM). + + Note that shell command lines are not directly supported. 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' + + 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. Because 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. + + + C escapes supported in command lines and environment variables + + + + + + Literal + Actual value + + + + + \a + bell + + + \b + backspace + + + \f + form feed + + + \n + newline + + + \r + carriage return + + + \t + tab + + + \v + vertical tab + + + \\ + backslash + + + \" + double quotation mark + + + \' + single quotation mark + + + \s + space + + + \xxx + character number xx in hexadecimal encoding + + + \nnn + character number nnn in octal encoding + + + +
+ + + + Examples + + + Simple service + + The following unit file creates a service that will + execute /usr/sbin/foo-daemon. Since no + Type= is specified, the default + Type= will be assumed. + systemd will assume the unit to be started immediately after the + program has begun executing. + + [Unit] +Description=Foo + +[Service] +ExecStart=/usr/sbin/foo-daemon + +[Install] +WantedBy=multi-user.target + + Note that systemd assumes here that the process started by + systemd will continue running until the service terminates. If + the program daemonizes itself (i.e. forks), please use + Type= instead. + + Since no ExecStop= was specified, + systemd will send SIGTERM to all processes started from this + service, and after a timeout also SIGKILL. This behavior can be + modified, see + systemd.kill5 + for details. + + Note that this unit type does not include any type of + notification when a service has completed initialization. For + this, you should use other unit types, such as + Type= if the service + understands systemd's notification protocol, + Type= if the service + can background itself or + Type= if the unit + acquires a DBus name once initialization is complete. See + below. + + + + Oneshot service + + Sometimes units should just execute an action without + keeping active processes, such as a filesystem check or a + cleanup action on boot. For this, + Type= exists. Units + of this type will wait until the process specified terminates + and then fall back to being inactive. The following unit will + perform a clenaup action: + + [Unit] +Description=Cleanup old Foo data + +[Service] +Type=oneshot +ExecStart=/usr/sbin/foo-cleanup + +[Install] +WantedBy=multi-user.target + + Note that systemd will consider the unit to be in the + state 'starting' until the program has terminated, so ordered + dependencies will wait for the program to finish before starting + themselves. The unit will revert to the 'inactive' state after + the execution is done, never reaching the 'active' state. That + means another request to start the unit will perform the action + again. + + Type= are the + only service units that may have more than one + ExecStart= specified. They will be executed + in order until either they are all successful or one of them + fails. + + + + Stoppable oneshot service + + Similarly to the oneshot services, there are sometimes + units that need to execute a program to set up something and + then execute another to shut it down, but no process remains + active while they are considered 'started'. Network + configuration can sometimes fall into this category. Another use + case is if a oneshot service shall not be executed a each time + when they are pulled in as a dependency, but only the first + time. + + For this, systemd knows the setting + RemainAfterExit=, which + causes systemd to consider the unit to be active if the start + action exited successfully. This directive can be used with all + types, but is most useful with + Type= and + Type=. With + Type= systemd waits + until the start action has completed before it considers the + unit to be active, so dependencies start only after the start + action has succeeded. With + Type= dependencies + will start immediately after the start action has been + dispatched. The following unit provides an example for a simple + static firewall. + + [Unit] +Description=Simple firewall + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/local/sbin/simple-firewall-start +ExecStop=/usr/local/sbin/simple-firewall-stop + +[Install] +WantedBy=multi-user.target + + Since the unit is considered to be running after the start + action has exited, invoking systemctl start + on that unit again will cause no action to be taken. + + + + Traditional forking services + + Many traditional daemons/services background (i.e. fork, + daemonize) themselves when starting. Set + Type= in the + service's unit file to support this mode of operation. systemd + will consider the service to be in the process of initialization + while the original program is still running. Once it exits + successfully and at least a process remains (and + RemainAfterExit=), the + service is considered started. + + Often a traditional daemon only consists of one process. + Therefore, if only one process is left after the original + process terminates, systemd will consider that process the main + process of the service. In that case, the + $MAINPID variable will be available in + ExecReload=, ExecStop=, + etc. + + In case more than one process remains, systemd will be + unable to determine the main process, so it will not assume + there is one. In that case, $MAINPID will not + expand to anything. However, if the process decides to write a + traditional PID file, systemd will be able to read the main PID + from there. Please set PIDFile= accordingly. + Note that the daemon should write that file before finishing + with its initialization, otherwise systemd might try to read the + file before it exists. + + The following example shows a simple daemon that forks and + just starts one process in the background: + + [Unit] +Description=Some simple daemon + +[Service] +Type=forking +ExecStart=/usr/sbin/my-simple-daemon -d + +[Install] +WantedBy=multi-user.target + + Please see + systemd.kill5 + for details on how you can influence the way systemd terminates + the service. + + + + DBus services + + For services that acquire a name on the DBus system bus, + use Type= and set + BusName= accordingly. The service should not + fork (daemonize). systemd will consider the service to be + initialized once the name has been acquired on the system bus. + The following example shows a typical DBus service: + + [Unit] +Description=Simple DBus service + +[Service] +Type=dbus +BusName=org.example.simple-dbus-service +ExecStart=/usr/sbin/simple-dbus-service + +[Install] +WantedBy=multi-user.target + + For bus-activatable services, don't + include a [Install] section in the systemd + service file, but use the SystemdService= + option in the corresponding DBus service file, for example + (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service): + + [D-BUS Service] +Name=org.example.simple-dbus-service +Exec=/usr/sbin/simple-dbus-service +User=root +SystemdService=simple-dbus-service.service + + Please see + systemd.kill5 + for details on how you can influence the way systemd terminates + the service. + + + + Services that notify systemd about their initialization + + Type= services + are really easy to write, but have the major disadvantage of + systemd not being able to tell when initialization of the given + service is complete. For this reason, systemd supports a simple + notification protocol that allows daemons to make systemd aware + that they are done initializing. Use + Type= for this. A + typical service file for such a daemon would look like + this: + + [Unit] +Description=Simple notifying service + +[Service] +Type=notify +ExecStart=/usr/sbin/simple-notifying-service + +[Install] +WantedBy=multi-user.target + + Note that the daemon has to support systemd's notification + protocol, else systemd will think the service hasn't started yet + and kill it after a timeout. For an example of how to update + daemons to support this protocol transparently, take a look at + sd_notify3. + systemd will consider the unit to be in the 'starting' state + until a readiness notification has arrived. + + Please see + systemd.kill5 + for details on how you can influence the way systemd terminates + the service. + + + + + See Also + + systemd1, + systemctl1, + systemd.unit5, + systemd.exec5, + systemd.resource-control5, + systemd.kill5, + systemd.directives7 + +