systemd.service(5)

Takes a boolean argument, or a list of resources defined in systemd.exec(5). Possible values are extensions and credentials, separated by space. Prepending the list with a single tilde character (~) inverts the effect. Defaults to extensions. An empty assignment resets the list to default. If enabled, the corresponding resources (ExtensionImages=/ExtensionDirectories= for extensions and LoadCredential=/ImportCredential=/ SetCredential= (along with their Encrypted counterparts) for credentials) will be refreshed on service reload. If yes, all resources listed above that are used by the service shall be refreshed.

Specially, if this option is set explicitly, and the respective resources are in use, the service may be reloaded without any actual reload mechanism (ExecReload= or Type=notify-reload) for notifying the main process, in which case the reload is considered complete immediately after refreshing.

Added in version 260.

.RE

.PP Check systemd.unit(5), systemd.exec(5), and systemd.kill(5) for more settings.

.SH "COMMAND LINES"

.PP This section describes command line parsing and variable and specifier substitutions for ExecStart=, ExecStartPre=, ExecStartPost=, ExecReload=, ExecStop=, ExecStopPost=, and ExecCondition= options.

.PP Multiple command lines may be specified by using the relevant setting multiple times.

.PP Each command line is unquoted using the rules described in "Quoting" section in systemd.syntax(7). The first item becomes the command to execute, and the subsequent items the arguments.

.PP This syntax is inspired by shell syntax, but only the meta-characters and expansions described in the following paragraphs are understood, and the expansion of variables is different. Specifically, redirection using <, <<, >, and >>, pipes using |, running programs in the background using &, and other elements of shell syntax are not supported.

.PP The command to execute may contain spaces, but control characters are not allowed.

.PP Each command may be prefixed with a number of special characters:

.sp
Table 2. Special executable prefixes

.PP @, |, -, :, and one of +/! may be used together and they can appear in any order. However, + and ! may not be specified at the same time.

.PP For each command, the first argument must be either an absolute path to an executable or a simple file name without any slashes. If the command is not a full (absolute) path, it will be resolved to a full path using a fixed search path determined at compilation time. Searched directories include /usr/local/bin/, /usr/bin/, and their sbin/ counterparts (only on systems using split bin/ and sbin/). It is thus safe to use just the executable name in case of executables located in any of the "standard" directories, and an absolute path must be used in other cases. Hint: this search path may be queried using systemd-path search-binaries-default.

.PP The command line accepts % specifiers as described in systemd.unit(5).

.PP An argument solely consisting of ; must be escaped, i.e. specified as \;.

.PP 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 erased and replaced by the exact value of the environment variable (if any) including all whitespace it contains, always resulting in exactly 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 are respected when splitting into words, and afterwards removed.

.PP Example:

Environment="ONE=one" 'TWO=two two'
ExecStart=echo $ONE $TWO ${TWO}

.PP This will execute /bin/echo with four arguments: one, two, two, and two two.

.PP Example:

Environment=ONE='one' "TWO='two two' too" THREE=
ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
ExecStart=/bin/echo $ONE $TWO $THREE

.PP This results in /bin/echo being called twice, the first time with arguments one, 'two two' too, , and the second time with arguments one, two two, too.

.PP Unless for commands with the special executable prefix :, 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.

.PP 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.exec(5), which are considered "static configuration", may be used (this includes e.g. $USER, but not $TERM).

.PP Note that shell command lines are not directly supported, and | invokes the user's default shell which isn't deterministic. It's recommended to specify a shell implementation explicitly if portability is desired. Example:

ExecStart=sh -c 'dmesg | tac'

.PP Example:

ExecStart=echo one
ExecStart=echo "two two"

.PP This will execute echo two times, each time with one argument: one and two two, respectively. Because two commands are specified, Type=oneshot must be used.

.PP Example:

Type=oneshot
ExecStart=:echo $USER
ExecStart=-false
ExecStart=+:@true $TEST

.PP This will execute /usr/bin/echo with the literal argument $USER (: suppresses variable expansion), and then /usr/bin/false (the return value will be ignored because - suppresses checking of the return value), and /usr/bin/true (with elevated privileges, with $TEST as argv[0]).

.PP Example:

ExecStart=echo / >/dev/null & \; \
ls

.PP This will execute echo with five arguments: /, >/dev/null, &, ;, and ls.

.SH "EXAMPLES"

.PP Example 3. Simple service

.PP The following unit file creates a service that will execute /usr/sbin/foo-daemon. Since no Type= is specified, the default Type=simple 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

.PP 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=forking instead.

.PP 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.kill(5) for details.

.PP 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=notify/Type=notify-reload if the service understands systemd's notification protocol, Type=forking if the service can background itself or Type=dbus if the unit acquires a DBus name once initialization is complete. See below.

.PP Example 4. Oneshot service

.PP 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=oneshot 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 cleanup action:

[Unit]
Description=Cleanup old Foo data
[Service]
Type=oneshot
ExecStart=/usr/sbin/foo-cleanup
[Install]
WantedBy=multi-user.target

.PP 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.

.PP Type=oneshot are the only service units that may have more than one ExecStart= specified. For units with multiple commands (Type=oneshot), all commands will be run again.

.PP For Type=oneshot, Restart=always and Restart=on-success are not allowed.

.PP Example 5. Stoppable oneshot service

.PP 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 each time when they are pulled in as a dependency, but only the first time.

.PP For this, systemd knows the setting RemainAfterExit=yes, 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=oneshot and Type=simple. With Type=oneshot, 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=simple, 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

.PP 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.

.PP Example 6. Traditional forking services

.PP Many traditional daemons/services background (i.e. fork, daemonize) themselves when starting. Set Type=forking 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=no), the service is considered started.

.PP 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.

.PP 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.

.PP The following example shows a simple daemon that forks and just starts one process in the background:

[Unit]
Description=My Simple Daemon
[Service]
Type=forking
ExecStart=/usr/sbin/my-simple-daemon -d
[Install]
WantedBy=multi-user.target

.PP Please see systemd.kill(5) for details on how you can influence the way systemd terminates the service.

.PP Example 7. DBus services

.PP For services that acquire a name on the DBus system bus, use Type=dbus 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

.PP For bus-activatable services, do not 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

.PP Please see systemd.kill(5) for details on how you can influence the way systemd terminates the service.

.PP Example 8. Services that notify systemd about their initialization

.PP Type=simple 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=notify or Type=notify-reload for this. A typical service file for such a daemon would look like this:

[Unit]
Description=Simple Notifying Service
[Service]
Type=notify-reload
ExecStart=/usr/sbin/simple-notifying-service
[Install]
WantedBy=multi-user.target

.PP Note that the daemon has to support systemd's notification protocol, else systemd will think the service has not 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_notify(3). systemd will consider the unit to be in the 'starting' state until a readiness notification has arrived.

.PP Please see systemd.kill(5) for details on how you can influence the way systemd terminates the service.

.PP To avoid code duplication, it is preferable to use sd_notify(3) when possible, especially when other APIs provided by libsystemd(3) are also used, but note that the notification protocol is very simple and guaranteed to be stable as per the Interface Portability and Stability Promise[5], so it can be reimplemented by services with no external dependencies. For a self-contained example, see sd_notify(3).

.SH "SEE ALSO"

.PP systemd(1), systemctl(1), systemd-system.conf(5), systemd.unit(5), systemd.exec(5), systemd.resource-control(5), systemd.kill(5), systemd.directives(7), systemd-run(1)