From 798d3a524ea57aaf40cb53858aaa45ec702f012d Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Tue, 3 Feb 2015 21:14:13 -0500 Subject: Reindent man pages to 2ch --- man/systemd.service.xml | 2821 +++++++++++++++++++++-------------------------- 1 file changed, 1247 insertions(+), 1574 deletions(-) (limited to 'man/systemd.service.xml') diff --git a/man/systemd.service.xml b/man/systemd.service.xml index f33e8df056..37d9e98219 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1,7 +1,7 @@ + "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 - 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' + + 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. + This will execute /bin/echo with four + arguments: one, two, + two, and two two. - Example: - Environment=ONE='one' "TWO='two two' too" THREE= + 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 & \; \ + 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] + 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] @@ -1382,50 +1094,42 @@ 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] + 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] @@ -1435,60 +1139,50 @@ 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] + 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] @@ -1500,56 +1194,46 @@ 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] + 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] @@ -1559,26 +1243,23 @@ 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] + 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] @@ -1589,43 +1270,38 @@ 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): + 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] + [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] + 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] @@ -1635,35 +1311,32 @@ 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 - - + 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 + + -- cgit v1.2.3