X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=f33e8df05697529c2012f09178cee6f546277fd9;hb=320814811417146cfa1e416f69f1101eed630c36;hp=5230a78337e34b9ca3a2e532b83283928c4b748d;hpb=af62c704053b5d34672497eb5bdc4764ebbb5f4f;p=elogind.git diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 5230a7833..f33e8df05 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -9,16 +9,16 @@ Copyright 2010 Lennart Poettering systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -44,169 +44,1625 @@ systemd.service - systemd service configuration files + Service unit configuration - systemd.service + service.service Description - A configuration file ending in .service encodes - information about a process controlled and supervised - by systemd. + A unit configuration file whose name ends in + .service encodes information + about a process controlled and supervised by + systemd. This man page lists the configuration options specific to this unit type. See systemd.unit5 for the common options of all unit configuration - files. + files. The common configuration items are configured + in the generic [Unit] and + [Install] sections. The service + specific configuration options are configured in the + [Service] section. + + Additional options are listed in + systemd.exec5, + which define the execution environment the commands + are executed in, and in + systemd.kill5, + which define the way the processes of the service are + terminated, 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= - - One of - forking, - simple, - finish, - dbus. - - If set to - forking - (the default) it is expected - that the process configured - with - ExecStart= - will start up and call - fork(). The - parent process is expected to - finish when start-up is - complete and all communication - channels set up. The child - continues to run as the main - daemon process. This is the - behaviour of traditional UNIX - daemons. If this setting is - used, it is recommended to also - use the - PIDFile= - option, so that systemd can - identify the main process of - the daemon. systemd will proceed - starting follow-up units as soon - as the parent process exits. - - If set to - simple (the - recommended value) it is - expected that the process - configured with - ExecStart= - is the main process of the - daemon. In this mode, - communication channels must be - available before the daemon is - started up (sockets set up by systemd), - as systemd will immediately proceed - starting follow-up units. - - Behaviour of - finish is - similar to - simple, - however it is expected that - the process has to exit before - systemd starts follow-up - units. ValidNoProcess= - is particularly useful for - this type of service. - - Behaviour of - dbus is - similar to - simple, - however it is expected that - the daemon acquires a name on - the D-Bus bus, as configured - by - BusName=. Systemd will - proceed starting follow-up - units after the D-Bus bus name has been - acquired. + + Configures the process + start-up type for this service + unit. One of , + , + , + , + or + . + + If set to + (the default + 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 + . + - ValidNoProcess= - - Takes a boolean value - that specifies whether the service - shall be considered active - even when all its processes - exited. Defaults to no. + GuessMainPID= + + Takes a boolean value + that specifies whether systemd should + try to guess the main PID of a service + if it cannot be determined + reliably. This option is ignored + unless + is set and + is unset because for the other types + or with an explicitly configured PID + file, the main PID is always known. The + guessing algorithm might come to + incorrect conclusions if a daemon + consists of more than one process. If + the main PID cannot be determined, + failure detection and automatic + restarting of a service will not work + reliably. Defaults to + . PIDFile= - - Takes an absolute file - name pointing to the PID file - of this daemon. Use of this - option is recommended for - services where - Type= is - set to - forking. + + Takes an absolute file + name pointing to the PID file of this + daemon. Use of this option is + recommended for services where + Type= is set to + . systemd will + read the PID of the main process of + the daemon after start-up of the + service. systemd will not write to the + file configured here. BusName= - - Takes a D-Bus bus name, - where this service is reachable - as. This option is mandatory - for services where - Type= is - set to - dbus, but - its use is otherwise - recommended as well if the - process takes a name on the - D-Bus bus. + + Takes a D-Bus bus + name that this service is reachable + as. This option is mandatory for + services where + Type= is set to + . + + + + + 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= - - Takes a command line - that is executed when this - service shall be started - up. The first word of the - command line must be an - absolute file name. It is - mandatory to set this option - for all services. + Commands with their + arguments that are executed when this + service is started. The 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 - systemd8, - systemctl8 - systemd.unit5 + systemd1, + systemctl1, + systemd.unit5, + systemd.exec5, + systemd.resource-control5, + systemd.kill5, + systemd.directives7