1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id=
"systemd.service">
26 <title>systemd.service
</title>
27 <productname>systemd
</productname>
31 <contrib>Developer
</contrib>
32 <firstname>Lennart
</firstname>
33 <surname>Poettering
</surname>
34 <email>lennart@poettering.net
</email>
40 <refentrytitle>systemd.service
</refentrytitle>
41 <manvolnum>5</manvolnum>
45 <refname>systemd.service
</refname>
46 <refpurpose>Service unit configuration
</refpurpose>
50 <para><filename><replaceable>service
</replaceable>.service
</filename></para>
54 <title>Description
</title>
56 <para>A unit configuration file whose name ends in
57 <filename>.service
</filename> encodes information about a process
58 controlled and supervised by systemd.
</para>
60 <para>This man page lists the configuration options specific to
62 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
63 for the common options of all unit configuration files. The common
64 configuration items are configured in the generic
65 <literal>[Unit]
</literal> and
<literal>[Install]
</literal>
66 sections. The service specific configuration options are
67 configured in the
<literal>[Service]
</literal> section.
</para>
69 <para>Additional options are listed in
70 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
71 which define the execution environment the commands are executed
73 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
74 which define the way the processes of the service are terminated,
76 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
77 which configure resource control settings for the processes of the
80 <para>If a service is requested under a certain name but no unit
81 configuration file is found, systemd looks for a SysV init script
82 by the same name (with the
<filename>.service
</filename> suffix
83 removed) and dynamically creates a service unit from that script.
84 This is useful for compatibility with SysV. Note that this
85 compatibility is quite comprehensive but not
100%. For details
86 about the incompatibilities, see the
<ulink
87 url=
"http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
88 with SysV
</ulink> document.
</para>
92 <title>Automatic Dependencies
</title>
94 <para>Services with
<varname>Type=dbus
</varname> set automatically
95 acquire dependencies of type
<varname>Requires=
</varname> and
96 <varname>After=
</varname> on
97 <filename>dbus.socket
</filename>.
</para>
99 <para>Socket activated services are automatically ordered after
100 their activating
<filename>.socket
</filename> units via an
101 automatic
<varname>After=
</varname> dependency.
102 Services also pull in all
<filename>.socket
</filename> units
103 listed in
<varname>Sockets=
</varname> via automatic
104 <varname>Wants=
</varname> and
<varname>After=
</varname> dependencies.
</para>
106 <para>Unless
<varname>DefaultDependencies=
</varname> in the
<literal>[Unit]
</literal> is set to
107 <option>false
</option>, service units will implicitly have dependencies of type
<varname>Requires=
</varname> and
108 <varname>After=
</varname> on
<filename>sysinit.target
</filename>, a dependency of type
<varname>After=
</varname> on
109 <filename>basic.target
</filename> as well as dependencies of type
<varname>Conflicts=
</varname> and
110 <varname>Before=
</varname> on
<filename>shutdown.target
</filename>. These ensure that normal service units pull in
111 basic system initialization, and are terminated cleanly prior to system shutdown. Only services involved with early
112 boot or late system shutdown should disable this option.
</para>
114 <para>Instanced service units (i.e. service units with an
<literal>@
</literal> in their name) are assigned by
115 default a per-template slice unit (see
116 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the
117 template unit, containing all instances of the specific template. This slice is normally stopped at shutdown,
118 together with all template instances. If that is not desired, set
<varname>DefaultDependencies=no
</varname> in the
119 template unit, and either define your own per-template slice unit file that also sets
120 <varname>DefaultDependencies=no
</varname>, or set
<varname>Slice=system.slice
</varname> (or another suitable slice)
121 in the template unit. Also see
122 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
124 <para>Additional implicit dependencies may be added as result of
125 execution and resource control parameters as documented in
126 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
128 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
132 <title>Options
</title>
134 <para>Service files must include a
<literal>[Service]
</literal>
135 section, which carries information about the service and the
136 process it supervises. A number of options that may be used in
137 this section are shared with other unit types. These options are
139 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
141 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
142 The options specific to the
<literal>[Service]
</literal> section
143 of service units are the following:
</para>
145 <variablelist class='unit-directives'
>
147 <term><varname>Type=
</varname></term>
149 <listitem><para>Configures the process start-up type for this
151 <option>simple
</option>,
152 <option>forking
</option>,
153 <option>oneshot
</option>,
154 <option>dbus
</option>,
155 <option>notify
</option> or
156 <option>idle
</option>.
</para>
158 <para>If set to
<option>simple
</option> (the default if
159 neither
<varname>Type=
</varname> nor
160 <varname>BusName=
</varname>, but
<varname>ExecStart=
</varname>
161 are specified), it is expected that the process configured
162 with
<varname>ExecStart=
</varname> is the main process of the
163 service. In this mode, if the process offers functionality to
164 other processes on the system, its communication channels
165 should be installed before the daemon is started up (e.g.
166 sockets set up by systemd, via socket activation), as systemd
167 will immediately proceed starting follow-up units.
</para>
169 <para>If set to
<option>forking
</option>, it is expected that
170 the process configured with
<varname>ExecStart=
</varname> will
171 call
<function>fork()
</function> as part of its start-up. The
172 parent process is expected to exit when start-up is complete
173 and all communication channels are set up. The child continues
174 to run as the main daemon process. This is the behavior of
175 traditional UNIX daemons. If this setting is used, it is
176 recommended to also use the
<varname>PIDFile=
</varname>
177 option, so that systemd can identify the main process of the
178 daemon. systemd will proceed with starting follow-up units as
179 soon as the parent process exits.
</para>
181 <para>Behavior of
<option>oneshot
</option> is similar to
182 <option>simple
</option>; however, it is expected that the
183 process has to exit before systemd starts follow-up units.
184 <varname>RemainAfterExit=
</varname> is particularly useful for
185 this type of service. This is the implied default if neither
186 <varname>Type=
</varname> or
<varname>ExecStart=
</varname> are
189 <para>Behavior of
<option>dbus
</option> is similar to
190 <option>simple
</option>; however, it is expected that the
191 daemon acquires a name on the D-Bus bus, as configured by
192 <varname>BusName=
</varname>. systemd will proceed with
193 starting follow-up units after the D-Bus bus name has been
194 acquired. Service units with this option configured implicitly
195 gain dependencies on the
<filename>dbus.socket
</filename>
196 unit. This type is the default if
<varname>BusName=
</varname>
199 <para>Behavior of
<option>notify
</option> is similar to
200 <option>simple
</option>; however, it is expected that the
201 daemon sends a notification message via
202 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
203 or an equivalent call when it has finished starting up.
204 systemd will proceed with starting follow-up units after this
205 notification message has been sent. If this option is used,
206 <varname>NotifyAccess=
</varname> (see below) should be set to
207 open access to the notification socket provided by systemd. If
208 <varname>NotifyAccess=
</varname> is missing or set to
209 <option>none
</option>, it will be forcibly set to
210 <option>main
</option>. Note that currently
211 <varname>Type=
</varname><option>notify
</option> will not work
212 if used in combination with
213 <varname>PrivateNetwork=
</varname><option>yes
</option>.
</para>
215 <para>Behavior of
<option>idle
</option> is very similar to
<option>simple
</option>; however, actual execution
216 of the service binary is delayed until all active jobs are dispatched. This may be used to avoid interleaving
217 of output of shell services with the status output on the console. Note that this type is useful only to
218 improve console output, it is not useful as a general unit ordering tool, and the effect of this service type
219 is subject to a
5s time-out, after which the service binary is invoked anyway.
</para>
224 <term><varname>RemainAfterExit=
</varname></term>
226 <listitem><para>Takes a boolean value that specifies whether
227 the service shall be considered active even when all its
228 processes exited. Defaults to
<option>no
</option>.
</para>
233 <term><varname>GuessMainPID=
</varname></term>
235 <listitem><para>Takes a boolean value that specifies whether
236 systemd should try to guess the main PID of a service if it
237 cannot be determined reliably. This option is ignored unless
238 <option>Type=forking
</option> is set and
239 <option>PIDFile=
</option> is unset because for the other types
240 or with an explicitly configured PID file, the main PID is
241 always known. The guessing algorithm might come to incorrect
242 conclusions if a daemon consists of more than one process. If
243 the main PID cannot be determined, failure detection and
244 automatic restarting of a service will not work reliably.
245 Defaults to
<option>yes
</option>.
</para>
250 <term><varname>PIDFile=
</varname></term>
252 <listitem><para>Takes an absolute file name pointing to the
253 PID file of this daemon. Use of this option is recommended for
254 services where
<varname>Type=
</varname> is set to
255 <option>forking
</option>. systemd will read the PID of the
256 main process of the daemon after start-up of the service.
257 systemd will not write to the file configured here, although
258 it will remove the file after the service has shut down if it
265 <term><varname>BusName=
</varname></term>
267 <listitem><para>Takes a D-Bus bus name that this service is
268 reachable as. This option is mandatory for services where
269 <varname>Type=
</varname> is set to
270 <option>dbus
</option>.
</para>
275 <term><varname>ExecStart=
</varname></term>
276 <listitem><para>Commands with their arguments that are
277 executed when this service is started. The value is split into
278 zero or more command lines according to the rules described
279 below (see section
"Command Lines" below).
282 <para>Unless
<varname>Type=
</varname> is
<option>oneshot
</option>, exactly one command must be given. When
283 <varname>Type=oneshot
</varname> is used, zero or more commands may be specified. Commands may be specified by
284 providing multiple command lines in the same directive, or alternatively, this directive may be specified more
285 than once with the same effect. If the empty string is assigned to this option, the list of commands to start
286 is reset, prior assignments of this option will have no effect. If no
<varname>ExecStart=
</varname> is
287 specified, then the service must have
<varname>RemainAfterExit=yes
</varname> set.
</para>
289 <para>For each of the specified commands, the first argument must be an absolute path to an
290 executable. Optionally, if this file name is prefixed with
<literal>@
</literal>, the second token will be
291 passed as
<literal>argv[
0]
</literal> to the executed process, followed by the further arguments specified. If
292 the absolute filename is prefixed with
<literal>-
</literal>, an exit code of the command normally considered a
293 failure (i.e. non-zero exit status or abnormal exit due to signal) is ignored and considered success. If the
294 absolute path is prefixed with
<literal>+
</literal> then it is executed with full
295 privileges.
<literal>@
</literal>,
<literal>-
</literal>, and
<literal>+
</literal> may be used together and they
296 can appear in any order.
</para>
298 <para>If more than one command is specified, the commands are
299 invoked sequentially in the order they appear in the unit
300 file. If one of the commands fails (and is not prefixed with
301 <literal>-
</literal>), other lines are not executed, and the
302 unit is considered failed.
</para>
304 <para>Unless
<varname>Type=forking
</varname> is set, the
305 process started via this command line will be considered the
306 main process of the daemon.
</para>
311 <term><varname>ExecStartPre=
</varname></term>
312 <term><varname>ExecStartPost=
</varname></term>
313 <listitem><para>Additional commands that are executed before
314 or after the command in
<varname>ExecStart=
</varname>,
315 respectively. Syntax is the same as for
316 <varname>ExecStart=
</varname>, except that multiple command
317 lines are allowed and the commands are executed one after the
318 other, serially.
</para>
320 <para>If any of those commands (not prefixed with
321 <literal>-
</literal>) fail, the rest are not executed and the
322 unit is considered failed.
</para>
324 <para><varname>ExecStart=
</varname> commands are only run after
325 all
<varname>ExecStartPre=
</varname> commands that were not prefixed
326 with a
<literal>-
</literal> exit successfully.
</para>
328 <para><varname>ExecStartPost=
</varname> commands are only run after
329 the service has started successfully, as determined by
<varname>Type=
</varname>
330 (i.e. the process has been started for
<varname>Type=simple
</varname>
331 or
<varname>Type=idle
</varname>, the process exits successfully for
332 <varname>Type=oneshot
</varname>, the initial process exits successfully
333 for
<varname>Type=forking
</varname>,
<literal>READY=
1</literal> is sent
334 for
<varname>Type=notify
</varname>, or the
<varname>BusName=
</varname>
335 has been taken for
<varname>Type=dbus
</varname>).
</para>
337 <para>Note that
<varname>ExecStartPre=
</varname> may not be
338 used to start long-running processes. All processes forked
339 off by processes invoked via
<varname>ExecStartPre=
</varname> will
340 be killed before the next service process is run.
</para>
342 <para>Note that if any of the commands specified in
<varname>ExecStartPre=
</varname>,
343 <varname>ExecStart=
</varname>, or
<varname>ExecStartPost=
</varname> fail (and are not prefixed with
344 <literal>-
</literal>, see above) or time out before the service is fully up, execution continues with commands
345 specified in
<varname>ExecStopPost=
</varname>, the commands in
<varname>ExecStop=
</varname> are skipped.
</para>
350 <term><varname>ExecReload=
</varname></term>
351 <listitem><para>Commands to execute to trigger a configuration
352 reload in the service. This argument takes multiple command
353 lines, following the same scheme as described for
354 <varname>ExecStart=
</varname> above. Use of this setting is
355 optional. Specifier and environment variable substitution is
356 supported here following the same scheme as for
357 <varname>ExecStart=
</varname>.
</para>
359 <para>One additional, special environment variable is set: if
360 known,
<varname>$MAINPID
</varname> is set to the main process
361 of the daemon, and may be used for command lines like the
364 <programlisting>/bin/kill -HUP $MAINPID
</programlisting>
366 <para>Note however that reloading a daemon by sending a signal
367 (as with the example line above) is usually not a good choice,
368 because this is an asynchronous operation and hence not
369 suitable to order reloads of multiple services against each
370 other. It is strongly recommended to set
371 <varname>ExecReload=
</varname> to a command that not only
372 triggers a configuration reload of the daemon, but also
373 synchronously waits for it to complete.
</para>
378 <term><varname>ExecStop=
</varname></term>
379 <listitem><para>Commands to execute to stop the service
380 started via
<varname>ExecStart=
</varname>. This argument takes
381 multiple command lines, following the same scheme as described
382 for
<varname>ExecStart=
</varname> above. Use of this setting
383 is optional. After the commands configured in this option are
384 run, all processes remaining for a service are terminated
385 according to the
<varname>KillMode=
</varname> setting (see
386 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
387 If this option is not specified, the process is terminated by
388 sending the signal specified in
<varname>KillSignal=
</varname>
389 when service stop is requested. Specifier and environment
390 variable substitution is supported (including
391 <varname>$MAINPID
</varname>, see above).
</para>
393 <para>Note that it is usually not sufficient to specify a
394 command for this setting that only asks the service to
395 terminate (for example, by queuing some form of termination
396 signal for it), but does not wait for it to do so. Since the
397 remaining processes of the services are killed using
398 <constant>SIGKILL
</constant> immediately after the command
399 exited, this would not result in a clean stop. The specified
400 command should hence be a synchronous operation, not an
401 asynchronous one.
</para>
403 <para>Note that the commands specified in
<varname>ExecStop=
</varname> are only executed when the service
404 started successfully first. They are not invoked if the service was never started at all, or in case its
405 start-up failed, for example because any of the commands specified in
<varname>ExecStart=
</varname>,
406 <varname>ExecStartPre=
</varname> or
<varname>ExecStartPost=
</varname> failed (and weren't prefixed with
407 <literal>-
</literal>, see above) or timed out. Use
<varname>ExecStopPost=
</varname> to invoke commands when a
408 service failed to start up correctly and is shut down again.
</para>
410 <para>It is recommended to use this setting for commands that communicate with the service requesting clean
411 termination. When the commands specified with this option are executed it should be assumed that the service is
412 still fully up and is able to react correctly to all commands. For post-mortem clean-up steps use
413 <varname>ExecStopPost=
</varname> instead.
</para></listitem>
417 <term><varname>ExecStopPost=
</varname></term>
418 <listitem><para>Additional commands that are executed after the service is stopped. This includes cases where
419 the commands configured in
<varname>ExecStop=
</varname> were used, where the service does not have any
420 <varname>ExecStop=
</varname> defined, or where the service exited unexpectedly. This argument takes multiple
421 command lines, following the same scheme as described for
<varname>ExecStart=
</varname>. Use of these settings
422 is optional. Specifier and environment variable substitution is supported. Note that – unlike
423 <varname>ExecStop=
</varname> – commands specified with this setting are invoked when a service failed to start
424 up correctly and is shut down again.
</para>
426 <para>It is recommended to use this setting for clean-up operations that shall be executed even when the
427 service failed to start up correctly. Commands configured with this setting need to be able to operate even if
428 the service failed starting up half-way and left incompletely initialized data around. As the service's
429 processes have been terminated already when the commands specified with this setting are executed they should
430 not attempt to communicate with them.
</para>
432 <para>Note that all commands that are configured with this setting are invoked with the result code of the
433 service, as well as the main process' exit code and status, set in the
<varname>$SERVICE_RESULT
</varname>,
434 <varname>$EXIT_CODE
</varname> and
<varname>$EXIT_STATUS
</varname> environment variables, see
435 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
436 details.
</para></listitem>
440 <term><varname>RestartSec=
</varname></term>
441 <listitem><para>Configures the time to sleep before restarting
442 a service (as configured with
<varname>Restart=
</varname>).
443 Takes a unit-less value in seconds, or a time span value such
444 as
"5min 20s". Defaults to
100ms.
</para></listitem>
448 <term><varname>TimeoutStartSec=
</varname></term>
449 <listitem><para>Configures the time to wait for start-up. If a
450 daemon service does not signal start-up completion within the
451 configured time, the service will be considered failed and
452 will be shut down again. Takes a unit-less value in seconds,
453 or a time span value such as
"5min 20s". Pass
454 <literal>infinity
</literal> to disable the timeout logic. Defaults to
455 <varname>DefaultTimeoutStartSec=
</varname> from the manager
456 configuration file, except when
457 <varname>Type=oneshot
</varname> is used, in which case the
458 timeout is disabled by default (see
459 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
464 <term><varname>TimeoutStopSec=
</varname></term>
465 <listitem><para>Configures the time to wait for stop. If a
466 service is asked to stop, but does not terminate in the
467 specified time, it will be terminated forcibly via
468 <constant>SIGTERM
</constant>, and after another timeout of
469 equal duration with
<constant>SIGKILL
</constant> (see
470 <varname>KillMode=
</varname> in
471 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
472 Takes a unit-less value in seconds, or a time span value such
473 as
"5min 20s". Pass
<literal>infinity
</literal> to disable the
474 timeout logic. Defaults to
475 <varname>DefaultTimeoutStopSec=
</varname> from the manager
476 configuration file (see
477 <citerefentry><refentrytitle>systemd-system.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
482 <term><varname>TimeoutSec=
</varname></term>
483 <listitem><para>A shorthand for configuring both
484 <varname>TimeoutStartSec=
</varname> and
485 <varname>TimeoutStopSec=
</varname> to the specified value.
490 <term><varname>RuntimeMaxSec=
</varname></term>
492 <listitem><para>Configures a maximum time for the service to run. If this is used and the service has been
493 active for longer than the specified time it is terminated and put into a failure state. Note that this setting
494 does not have any effect on
<varname>Type=oneshot
</varname> services, as they terminate immediately after
495 activation completed. Pass
<literal>infinity
</literal> (the default) to configure no runtime
496 limit.
</para></listitem>
500 <term><varname>WatchdogSec=
</varname></term>
501 <listitem><para>Configures the watchdog timeout for a service.
502 The watchdog is activated when the start-up is completed. The
504 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
505 regularly with
<literal>WATCHDOG=
1</literal> (i.e. the
506 "keep-alive ping"). If the time between two such calls is
507 larger than the configured time, then the service is placed in
508 a failed state and it will be terminated with
509 <constant>SIGABRT
</constant>. By setting
510 <varname>Restart=
</varname> to
<option>on-failure
</option>,
511 <option>on-watchdog
</option>,
<option>on-abnormal
</option> or
512 <option>always
</option>, the service will be automatically
513 restarted. The time configured here will be passed to the
514 executed service process in the
515 <varname>WATCHDOG_USEC=
</varname> environment variable. This
516 allows daemons to automatically enable the keep-alive pinging
517 logic if watchdog support is enabled for the service. If this
518 option is used,
<varname>NotifyAccess=
</varname> (see below)
519 should be set to open access to the notification socket
520 provided by systemd. If
<varname>NotifyAccess=
</varname> is
521 not set, it will be implicitly set to
<option>main
</option>.
522 Defaults to
0, which disables this feature. The service can
523 check whether the service manager expects watchdog keep-alive
525 <citerefentry><refentrytitle>sd_watchdog_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
527 <citerefentry><refentrytitle>sd_event_set_watchdog
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
528 may be used to enable automatic watchdog notification support.
533 <term><varname>Restart=
</varname></term>
534 <listitem><para>Configures whether the service shall be
535 restarted when the service process exits, is killed, or a
536 timeout is reached. The service process may be the main
537 service process, but it may also be one of the processes
538 specified with
<varname>ExecStartPre=
</varname>,
539 <varname>ExecStartPost=
</varname>,
540 <varname>ExecStop=
</varname>,
541 <varname>ExecStopPost=
</varname>, or
542 <varname>ExecReload=
</varname>. When the death of the process
543 is a result of systemd operation (e.g. service stop or
544 restart), the service will not be restarted. Timeouts include
545 missing the watchdog
"keep-alive ping" deadline and a service
546 start, reload, and stop operation timeouts.
</para>
550 <option>on-success
</option>,
551 <option>on-failure
</option>,
552 <option>on-abnormal
</option>,
553 <option>on-watchdog
</option>,
554 <option>on-abort
</option>, or
555 <option>always
</option>.
556 If set to
<option>no
</option> (the default), the service will
557 not be restarted. If set to
<option>on-success
</option>, it
558 will be restarted only when the service process exits cleanly.
559 In this context, a clean exit means an exit code of
0, or one
561 <constant>SIGHUP
</constant>,
562 <constant>SIGINT
</constant>,
563 <constant>SIGTERM
</constant> or
564 <constant>SIGPIPE
</constant>, and
565 additionally, exit statuses and signals specified in
566 <varname>SuccessExitStatus=
</varname>. If set to
567 <option>on-failure
</option>, the service will be restarted
568 when the process exits with a non-zero exit code, is
569 terminated by a signal (including on core dump, but excluding
570 the aforementioned four signals), when an operation (such as
571 service reload) times out, and when the configured watchdog
572 timeout is triggered. If set to
<option>on-abnormal
</option>,
573 the service will be restarted when the process is terminated
574 by a signal (including on core dump, excluding the
575 aforementioned four signals), when an operation times out, or
576 when the watchdog timeout is triggered. If set to
577 <option>on-abort
</option>, the service will be restarted only
578 if the service process exits due to an uncaught signal not
579 specified as a clean exit status. If set to
580 <option>on-watchdog
</option>, the service will be restarted
581 only if the watchdog timeout for the service expires. If set
582 to
<option>always
</option>, the service will be restarted
583 regardless of whether it exited cleanly or not, got terminated
584 abnormally by a signal, or hit a timeout.
</para>
587 <title>Exit causes and the effect of the
<varname>Restart=
</varname> settings on them
</title>
590 <colspec colname='path'
/>
591 <colspec colname='expl'
/>
594 <entry>Restart settings/Exit causes
</entry>
595 <entry><option>no
</option></entry>
596 <entry><option>always
</option></entry>
597 <entry><option>on-success
</option></entry>
598 <entry><option>on-failure
</option></entry>
599 <entry><option>on-abnormal
</option></entry>
600 <entry><option>on-abort
</option></entry>
601 <entry><option>on-watchdog
</option></entry>
606 <entry>Clean exit code or signal
</entry>
616 <entry>Unclean exit code
</entry>
626 <entry>Unclean signal
</entry>
636 <entry>Timeout
</entry>
646 <entry>Watchdog
</entry>
659 <para>As exceptions to the setting above, the service will not
660 be restarted if the exit code or signal is specified in
661 <varname>RestartPreventExitStatus=
</varname> (see below).
662 Also, the services will always be restarted if the exit code
663 or signal is specified in
664 <varname>RestartForceExitStatus=
</varname> (see below).
</para>
666 <para>Note that service restart is subject to unit start rate
667 limiting configured with
<varname>StartLimitIntervalSec=
</varname>
668 and
<varname>StartLimitBurst=
</varname>, see
669 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
672 <para>Setting this to
<option>on-failure
</option> is the
673 recommended choice for long-running services, in order to
674 increase reliability by attempting automatic recovery from
675 errors. For services that shall be able to terminate on their
676 own choice (and avoid immediate restarting),
677 <option>on-abnormal
</option> is an alternative choice.
</para>
682 <term><varname>SuccessExitStatus=
</varname></term>
683 <listitem><para>Takes a list of exit status definitions that,
684 when returned by the main service process, will be considered
685 successful termination, in addition to the normal successful
686 exit code
0 and the signals
<constant>SIGHUP
</constant>,
687 <constant>SIGINT
</constant>,
<constant>SIGTERM
</constant>, and
688 <constant>SIGPIPE
</constant>. Exit status definitions can
689 either be numeric exit codes or termination signal names,
690 separated by spaces. For example:
692 <programlisting>SuccessExitStatus=
1 2 8 SIGKILL
</programlisting>
694 ensures that exit codes
1,
2,
8 and
695 the termination signal
<constant>SIGKILL
</constant> are
696 considered clean service terminations.
699 <para>Note that if a process has a signal handler installed
701 <citerefentry><refentrytitle>_exit
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
702 in response to a signal, the information about the signal is
703 lost. Programs should instead perform cleanup and kill
704 themselves with the same signal instead. See
705 <ulink url=
"http://www.cons.org/cracauer/sigint.html">Proper
706 handling of SIGINT/SIGQUIT — How to be a proper
707 program
</ulink>.
</para>
709 <para>This option may appear more than once, in which case the
710 list of successful exit statuses is merged. If the empty
711 string is assigned to this option, the list is reset, all
712 prior assignments of this option will have no
713 effect.
</para></listitem>
717 <term><varname>RestartPreventExitStatus=
</varname></term>
718 <listitem><para>Takes a list of exit status definitions that,
719 when returned by the main service process, will prevent
720 automatic service restarts, regardless of the restart setting
721 configured with
<varname>Restart=
</varname>. Exit status
722 definitions can either be numeric exit codes or termination
723 signal names, and are separated by spaces. Defaults to the
724 empty list, so that, by default, no exit status is excluded
725 from the configured restart logic. For example:
727 <programlisting>RestartPreventExitStatus=
1 6 SIGABRT
</programlisting>
729 ensures that exit codes
1 and
6 and the termination signal
730 <constant>SIGABRT
</constant> will not result in automatic
731 service restarting. This option may appear more than once, in
732 which case the list of restart-preventing statuses is
733 merged. If the empty string is assigned to this option, the
734 list is reset and all prior assignments of this option will
735 have no effect.
</para></listitem>
739 <term><varname>RestartForceExitStatus=
</varname></term>
740 <listitem><para>Takes a list of exit status definitions that,
741 when returned by the main service process, will force automatic
742 service restarts, regardless of the restart setting configured
743 with
<varname>Restart=
</varname>. The argument format is
745 <varname>RestartPreventExitStatus=
</varname>.
</para></listitem>
749 <term><varname>PermissionsStartOnly=
</varname></term>
750 <listitem><para>Takes a boolean argument. If true, the
751 permission-related execution options, as configured with
752 <varname>User=
</varname> and similar options (see
753 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
754 for more information), are only applied to the process started
756 <varname>ExecStart=
</varname>, and not to the various other
757 <varname>ExecStartPre=
</varname>,
758 <varname>ExecStartPost=
</varname>,
759 <varname>ExecReload=
</varname>,
760 <varname>ExecStop=
</varname>, and
761 <varname>ExecStopPost=
</varname>
762 commands. If false, the setting is applied to all configured
763 commands the same way. Defaults to false.
</para></listitem>
767 <term><varname>RootDirectoryStartOnly=
</varname></term>
768 <listitem><para>Takes a boolean argument. If true, the root
769 directory, as configured with the
770 <varname>RootDirectory=
</varname> option (see
771 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
772 for more information), is only applied to the process started
773 with
<varname>ExecStart=
</varname>, and not to the various
774 other
<varname>ExecStartPre=
</varname>,
775 <varname>ExecStartPost=
</varname>,
776 <varname>ExecReload=
</varname>,
<varname>ExecStop=
</varname>,
777 and
<varname>ExecStopPost=
</varname> commands. If false, the
778 setting is applied to all configured commands the same way.
779 Defaults to false.
</para></listitem>
783 <term><varname>NonBlocking=
</varname></term>
784 <listitem><para>Set the
<constant>O_NONBLOCK
</constant> flag
785 for all file descriptors passed via socket-based activation.
786 If true, all file descriptors
>=
3 (i.e. all except stdin,
787 stdout, and stderr) will have the
788 <constant>O_NONBLOCK
</constant> flag set and hence are in
789 non-blocking mode. This option is only useful in conjunction
790 with a socket unit, as described in
791 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
792 Defaults to false.
</para></listitem>
796 <term><varname>NotifyAccess=
</varname></term>
797 <listitem><para>Controls access to the service status
798 notification socket, as accessible via the
799 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
800 call. Takes one of
<option>none
</option> (the default),
801 <option>main
</option> or
<option>all
</option>. If
802 <option>none
</option>, no daemon status updates are accepted
803 from the service processes, all status update messages are
804 ignored. If
<option>main
</option>, only service updates sent
805 from the main process of the service are accepted. If
806 <option>all
</option>, all services updates from all members of
807 the service's control group are accepted. This option should
808 be set to open access to the notification socket when using
809 <varname>Type=notify
</varname> or
810 <varname>WatchdogSec=
</varname> (see above). If those options
811 are used but
<varname>NotifyAccess=
</varname> is not
812 configured, it will be implicitly set to
813 <option>main
</option>.
</para></listitem>
817 <term><varname>Sockets=
</varname></term>
818 <listitem><para>Specifies the name of the socket units this
819 service shall inherit socket file descriptors from when the
820 service is started. Normally, it should not be necessary to use
821 this setting, as all socket file descriptors whose unit shares
822 the same name as the service (subject to the different unit
823 name suffix of course) are passed to the spawned
826 <para>Note that the same socket file descriptors may be passed
827 to multiple processes simultaneously. Also note that a
828 different service may be activated on incoming socket traffic
829 than the one which is ultimately configured to inherit the
830 socket file descriptors. Or, in other words: the
831 <varname>Service=
</varname> setting of
832 <filename>.socket
</filename> units does not have to match the
833 inverse of the
<varname>Sockets=
</varname> setting of the
834 <filename>.service
</filename> it refers to.
</para>
836 <para>This option may appear more than once, in which case the
837 list of socket units is merged. If the empty string is
838 assigned to this option, the list of sockets is reset, and all
839 prior uses of this setting will have no
840 effect.
</para></listitem>
844 <term><varname>FailureAction=
</varname></term>
845 <listitem><para>Configure the action to take when the service enters a failed state. Takes the same values as
846 the unit setting
<varname>StartLimitAction=
</varname> and executes the same actions (see
847 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>). Defaults to
848 <option>none
</option>.
</para></listitem>
852 <term><varname>FileDescriptorStoreMax=
</varname></term>
853 <listitem><para>Configure how many file descriptors may be
854 stored in the service manager for the service using
855 <citerefentry><refentrytitle>sd_pid_notify_with_fds
</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
856 <literal>FDSTORE=
1</literal> messages. This is useful for
857 implementing service restart schemes where the state is
858 serialized to
<filename>/run
</filename> and the file
859 descriptors passed to the service manager, to allow restarts
860 without losing state. Defaults to
0, i.e. no file descriptors
861 may be stored in the service manager. All file
862 descriptors passed to the service manager from a specific
863 service are passed back to the service's main process on the
864 next service restart. Any file descriptors passed to the
865 service manager are automatically closed when POLLHUP or
866 POLLERR is seen on them, or when the service is fully stopped
867 and no job is queued or being executed for it.
</para></listitem>
871 <term><varname>USBFunctionDescriptors=
</varname></term>
872 <listitem><para>Configure the location of a file containing
874 url=
"https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB
875 FunctionFS
</ulink> descriptors, for implementation of USB
876 gadget functions. This is used only in conjunction with a
877 socket unit with
<varname>ListenUSBFunction=
</varname>
878 configured. The contents of this file are written to the
879 <filename>ep0
</filename> file after it is
880 opened.
</para></listitem>
884 <term><varname>USBFunctionStrings=
</varname></term>
885 <listitem><para>Configure the location of a file containing
886 USB FunctionFS strings. Behavior is similar to
887 <varname>USBFunctionDescriptors=
</varname>
888 above.
</para></listitem>
894 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
896 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
897 for more settings.
</para>
902 <title>Command lines
</title>
904 <para>This section describes command line parsing and
905 variable and specifier substitutions for
906 <varname>ExecStart=
</varname>,
907 <varname>ExecStartPre=
</varname>,
908 <varname>ExecStartPost=
</varname>,
909 <varname>ExecReload=
</varname>,
910 <varname>ExecStop=
</varname>, and
911 <varname>ExecStopPost=
</varname> options.
</para>
913 <para>Multiple command lines may be concatenated in a single
914 directive by separating them with semicolons (these semicolons
915 must be passed as separate words). Lone semicolons may be escaped
916 as
<literal>\;
</literal>.
</para>
918 <para>Each command line is split on whitespace, with the first
919 item being the command to execute, and the subsequent items being
920 the arguments. Double quotes (
"...") and single quotes ('...') may
921 be used, in which case everything until the next matching quote
922 becomes part of the same argument. C-style escapes are also
923 supported. The table below contains the list of allowed escape
924 patterns. Only patterns which match the syntax in the table are
925 allowed; others will result in an error, and must be escaped by
926 doubling the backslash. Quotes themselves are removed after
927 parsing and escape sequences substituted. In addition, a trailing
928 backslash (
<literal>\
</literal>) may be used to merge lines.
931 <para>This syntax is intended to be very similar to shell syntax,
932 but only the meta-characters and expansions described in the
933 following paragraphs are understood. Specifically, redirection
935 <literal><</literal>,
936 <literal><<</literal>,
937 <literal>></literal>, and
938 <literal>>></literal>, pipes using
939 <literal>|
</literal>, running programs in the background using
940 <literal>&</literal>, and
<emphasis>other elements of shell
941 syntax are not supported
</emphasis>.
</para>
943 <para>The command to execute must be an absolute path name. It may
944 contain spaces, but control characters are not allowed.
</para>
946 <para>The command line accepts
<literal>%
</literal> specifiers as
948 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
949 Note that the first argument of the command line (i.e. the program
950 to execute) may not include specifiers.
</para>
952 <para>Basic environment variable substitution is supported. Use
953 <literal>${FOO}
</literal> as part of a word, or as a word of its
954 own, on the command line, in which case it will be replaced by the
955 value of the environment variable including all whitespace it
956 contains, resulting in a single argument. Use
957 <literal>$FOO
</literal> as a separate word on the command line, in
958 which case it will be replaced by the value of the environment
959 variable split at whitespace, resulting in zero or more arguments.
960 For this type of expansion, quotes are respected when splitting
961 into words, and afterwards removed.
</para>
963 <para>Example:
</para>
965 <programlisting>Environment=
"ONE=one" 'TWO=two two'
966 ExecStart=/bin/echo $ONE $TWO ${TWO}
</programlisting>
968 <para>This will execute
<command>/bin/echo
</command> with four
969 arguments:
<literal>one
</literal>,
<literal>two
</literal>,
970 <literal>two
</literal>, and
<literal>two two
</literal>.
</para>
972 <para>Example:
</para>
973 <programlisting>Environment=ONE='one'
"TWO='two two' too" THREE=
974 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
975 ExecStart=/bin/echo $ONE $TWO $THREE
</programlisting>
976 <para>This results in
<filename>echo
</filename> being
977 called twice, the first time with arguments
978 <literal>'one'
</literal>,
979 <literal>'two two' too
</literal>,
<literal></literal>,
980 and the second time with arguments
981 <literal>one
</literal>,
<literal>two two
</literal>,
982 <literal>too
</literal>.
985 <para>To pass a literal dollar sign, use
<literal>$$
</literal>.
986 Variables whose value is not known at expansion time are treated
987 as empty strings. Note that the first argument (i.e. the program
988 to execute) may not be a variable.
</para>
990 <para>Variables to be used in this fashion may be defined through
991 <varname>Environment=
</varname> and
992 <varname>EnvironmentFile=
</varname>. In addition, variables listed
993 in the section
"Environment variables in spawned processes" in
994 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
995 which are considered
"static configuration", may be used (this
996 includes e.g.
<varname>$USER
</varname>, but not
997 <varname>$TERM
</varname>).
</para>
999 <para>Note that shell command lines are not directly supported. If
1000 shell command lines are to be used, they need to be passed
1001 explicitly to a shell implementation of some kind. Example:
</para>
1002 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
</programlisting>
1004 <para>Example:
</para>
1006 <programlisting>ExecStart=/bin/echo one ; /bin/echo
"two two"</programlisting>
1008 <para>This will execute
<command>/bin/echo
</command> two times,
1009 each time with one argument:
<literal>one
</literal> and
1010 <literal>two two
</literal>, respectively. Because two commands are
1011 specified,
<varname>Type=oneshot
</varname> must be used.
</para>
1013 <para>Example:
</para>
1015 <programlisting>ExecStart=/bin/echo /
>/dev/null
& \; \
1016 /bin/ls
</programlisting>
1018 <para>This will execute
<command>/bin/echo
</command>
1019 with five arguments:
<literal>/
</literal>,
1020 <literal>>/dev/null
</literal>,
1021 <literal>&</literal>,
<literal>;
</literal>, and
1022 <literal>/bin/ls
</literal>.
</para>
1025 <title>C escapes supported in command lines and environment variables
</title>
1027 <colspec colname='escape'
/>
1028 <colspec colname='meaning'
/>
1031 <entry>Literal
</entry>
1032 <entry>Actual value
</entry>
1037 <entry><literal>\a
</literal></entry>
1041 <entry><literal>\b
</literal></entry>
1042 <entry>backspace
</entry>
1045 <entry><literal>\f
</literal></entry>
1046 <entry>form feed
</entry>
1049 <entry><literal>\n
</literal></entry>
1050 <entry>newline
</entry>
1053 <entry><literal>\r
</literal></entry>
1054 <entry>carriage return
</entry>
1057 <entry><literal>\t
</literal></entry>
1061 <entry><literal>\v
</literal></entry>
1062 <entry>vertical tab
</entry>
1065 <entry><literal>\\
</literal></entry>
1066 <entry>backslash
</entry>
1069 <entry><literal>\
"</literal></entry>
1070 <entry>double quotation mark</entry>
1073 <entry><literal>\'</literal></entry>
1074 <entry>single quotation mark</entry>
1077 <entry><literal>\s</literal></entry>
1078 <entry>space</entry>
1081 <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
1082 <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
1085 <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
1086 <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
1094 <title>Examples</title>
1097 <title>Simple service</title>
1099 <para>The following unit file creates a service that will
1100 execute <filename>/usr/sbin/foo-daemon</filename>. Since no
1101 <varname>Type=</varname> is specified, the default
1102 <varname>Type=</varname><option>simple</option> will be assumed.
1103 systemd will assume the unit to be started immediately after the
1104 program has begun executing.</para>
1106 <programlisting>[Unit]
1110 ExecStart=/usr/sbin/foo-daemon
1113 WantedBy=multi-user.target</programlisting>
1115 <para>Note that systemd assumes here that the process started by
1116 systemd will continue running until the service terminates. If
1117 the program daemonizes itself (i.e. forks), please use
1118 <varname>Type=</varname><option>forking</option> instead.</para>
1120 <para>Since no <varname>ExecStop=</varname> was specified,
1121 systemd will send SIGTERM to all processes started from this
1122 service, and after a timeout also SIGKILL. This behavior can be
1124 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1127 <para>Note that this unit type does not include any type of
1128 notification when a service has completed initialization. For
1129 this, you should use other unit types, such as
1130 <varname>Type=</varname><option>notify</option> if the service
1131 understands systemd's notification protocol,
1132 <varname>Type=</varname><option>forking</option> if the service
1133 can background itself or
1134 <varname>Type=</varname><option>dbus</option> if the unit
1135 acquires a DBus name once initialization is complete. See
1140 <title>Oneshot service</title>
1142 <para>Sometimes, units should just execute an action without
1143 keeping active processes, such as a filesystem check or a
1144 cleanup action on boot. For this,
1145 <varname>Type=</varname><option>oneshot</option> exists. Units
1146 of this type will wait until the process specified terminates
1147 and then fall back to being inactive. The following unit will
1148 perform a cleanup action:</para>
1150 <programlisting>[Unit]
1151 Description=Cleanup old Foo data
1155 ExecStart=/usr/sbin/foo-cleanup
1158 WantedBy=multi-user.target</programlisting>
1160 <para>Note that systemd will consider the unit to be in the
1161 state "starting
" until the program has terminated, so ordered
1162 dependencies will wait for the program to finish before starting
1163 themselves. The unit will revert to the "inactive
" state after
1164 the execution is done, never reaching the "active
" state. That
1165 means another request to start the unit will perform the action
1168 <para><varname>Type=</varname><option>oneshot</option> are the
1169 only service units that may have more than one
1170 <varname>ExecStart=</varname> specified. They will be executed
1171 in order until either they are all successful or one of them
1176 <title>Stoppable oneshot service</title>
1178 <para>Similarly to the oneshot services, there are sometimes
1179 units that need to execute a program to set up something and
1180 then execute another to shut it down, but no process remains
1181 active while they are considered "started
". Network
1182 configuration can sometimes fall into this category. Another use
1183 case is if a oneshot service shall not be executed each time
1184 when they are pulled in as a dependency, but only the first
1187 <para>For this, systemd knows the setting
1188 <varname>RemainAfterExit=</varname><option>yes</option>, which
1189 causes systemd to consider the unit to be active if the start
1190 action exited successfully. This directive can be used with all
1191 types, but is most useful with
1192 <varname>Type=</varname><option>oneshot</option> and
1193 <varname>Type=</varname><option>simple</option>. With
1194 <varname>Type=</varname><option>oneshot</option>, systemd waits
1195 until the start action has completed before it considers the
1196 unit to be active, so dependencies start only after the start
1197 action has succeeded. With
1198 <varname>Type=</varname><option>simple</option>, dependencies
1199 will start immediately after the start action has been
1200 dispatched. The following unit provides an example for a simple
1201 static firewall.</para>
1203 <programlisting>[Unit]
1204 Description=Simple firewall
1209 ExecStart=/usr/local/sbin/simple-firewall-start
1210 ExecStop=/usr/local/sbin/simple-firewall-stop
1213 WantedBy=multi-user.target</programlisting>
1215 <para>Since the unit is considered to be running after the start
1216 action has exited, invoking <command>systemctl start</command>
1217 on that unit again will cause no action to be taken.</para>
1221 <title>Traditional forking services</title>
1223 <para>Many traditional daemons/services background (i.e. fork,
1224 daemonize) themselves when starting. Set
1225 <varname>Type=</varname><option>forking</option> in the
1226 service's unit file to support this mode of operation. systemd
1227 will consider the service to be in the process of initialization
1228 while the original program is still running. Once it exits
1229 successfully and at least a process remains (and
1230 <varname>RemainAfterExit=</varname><option>no</option>), the
1231 service is considered started.</para>
1233 <para>Often, a traditional daemon only consists of one process.
1234 Therefore, if only one process is left after the original
1235 process terminates, systemd will consider that process the main
1236 process of the service. In that case, the
1237 <varname>$MAINPID</varname> variable will be available in
1238 <varname>ExecReload=</varname>, <varname>ExecStop=</varname>,
1241 <para>In case more than one process remains, systemd will be
1242 unable to determine the main process, so it will not assume
1243 there is one. In that case, <varname>$MAINPID</varname> will not
1244 expand to anything. However, if the process decides to write a
1245 traditional PID file, systemd will be able to read the main PID
1246 from there. Please set <varname>PIDFile=</varname> accordingly.
1247 Note that the daemon should write that file before finishing
1248 with its initialization. Otherwise, systemd might try to read the
1249 file before it exists.</para>
1251 <para>The following example shows a simple daemon that forks and
1252 just starts one process in the background:</para>
1254 <programlisting>[Unit]
1255 Description=Some simple daemon
1259 ExecStart=/usr/sbin/my-simple-daemon -d
1262 WantedBy=multi-user.target</programlisting>
1265 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1266 for details on how you can influence the way systemd terminates
1271 <title>DBus services</title>
1273 <para>For services that acquire a name on the DBus system bus,
1274 use <varname>Type=</varname><option>dbus</option> and set
1275 <varname>BusName=</varname> accordingly. The service should not
1276 fork (daemonize). systemd will consider the service to be
1277 initialized once the name has been acquired on the system bus.
1278 The following example shows a typical DBus service:</para>
1280 <programlisting>[Unit]
1281 Description=Simple DBus service
1285 BusName=org.example.simple-dbus-service
1286 ExecStart=/usr/sbin/simple-dbus-service
1289 WantedBy=multi-user.target</programlisting>
1291 <para>For <emphasis>bus-activatable</emphasis> services, do not
1292 include a <literal>[Install]</literal> section in the systemd
1293 service file, but use the <varname>SystemdService=</varname>
1294 option in the corresponding DBus service file, for example
1295 (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>
1297 <programlisting>[D-BUS Service]
1298 Name=org.example.simple-dbus-service
1299 Exec=/usr/sbin/simple-dbus-service
1301 SystemdService=simple-dbus-service.service</programlisting>
1304 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1305 for details on how you can influence the way systemd terminates
1310 <title>Services that notify systemd about their initialization</title>
1312 <para><varname>Type=</varname><option>simple</option> services
1313 are really easy to write, but have the major disadvantage of
1314 systemd not being able to tell when initialization of the given
1315 service is complete. For this reason, systemd supports a simple
1316 notification protocol that allows daemons to make systemd aware
1317 that they are done initializing. Use
1318 <varname>Type=</varname><option>notify</option> for this. A
1319 typical service file for such a daemon would look like
1322 <programlisting>[Unit]
1323 Description=Simple notifying service
1327 ExecStart=/usr/sbin/simple-notifying-service
1330 WantedBy=multi-user.target</programlisting>
1332 <para>Note that the daemon has to support systemd's notification
1333 protocol, else systemd will think the service has not started yet
1334 and kill it after a timeout. For an example of how to update
1335 daemons to support this protocol transparently, take a look at
1336 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
1337 systemd will consider the unit to be in the 'starting' state
1338 until a readiness notification has arrived.</para>
1341 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1342 for details on how you can influence the way systemd terminates
1348 <title>See Also</title>
1350 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1351 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1352 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1353 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1354 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1355 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1356 <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>