man/systemd.service.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  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.
  14
  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.
  19
  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/>.
  22 -->
  23
  24 <refentry id="systemd.service">
  25   <refentryinfo>
  26     <title>systemd.service</title>
  27     <productname>systemd</productname>
  28
  29     <authorgroup>
  30       <author>
  31         <contrib>Developer</contrib>
  32         <firstname>Lennart</firstname>
  33         <surname>Poettering</surname>
  34         <email>lennart@poettering.net</email>
  35       </author>
  36     </authorgroup>
  37   </refentryinfo>
  38
  39   <refmeta>
  40     <refentrytitle>systemd.service</refentrytitle>
  41     <manvolnum>5</manvolnum>
  42   </refmeta>
  43
  44   <refnamediv>
  45     <refname>systemd.service</refname>
  46     <refpurpose>Service unit configuration</refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <para><filename><replaceable>service</replaceable>.service</filename></para>
  51   </refsynopsisdiv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  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>
  59
  60     <para>This man page lists the configuration options specific to
  61     this unit type. See
  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>
  68
  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
  72     in, and in
  73     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  74     which define the way the processes of the service are terminated,
  75     and in
  76     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  77     which configure resource control settings for the processes of the
  78     service.</para>
  79
  80     <para>Unless <varname>DefaultDependencies=</varname> is set to
  81     <option>false</option>, service units will implicitly have
  82     dependencies of type <varname>Requires=</varname> and
  83     <varname>After=</varname> on <filename>basic.target</filename> as
  84     well as dependencies of type <varname>Conflicts=</varname> and
  85     <varname>Before=</varname> on
  86     <filename>shutdown.target</filename>. These ensure that normal
  87     service units pull in basic system initialization, and are
  88     terminated cleanly prior to system shutdown. Only services
  89     involved with early boot or late system shutdown should disable
  90     this option.</para>
  91
  92     <para>If a service is requested under a certain name but no unit
  93     configuration file is found, systemd looks for a SysV init script
  94     by the same name (with the <filename>.service</filename> suffix
  95     removed) and dynamically creates a service unit from that script.
  96     This is useful for compatibility with SysV. Note that this
  97     compatibility is quite comprehensive but not 100%. For details
  98     about the incompatibilities, see the <ulink
  99     url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
 100     with SysV</ulink> document.
 101     </para>
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>Options</title>
 106
 107     <para>Service files must include a <literal>[Service]</literal>
 108     section, which carries information about the service and the
 109     process it supervises. A number of options that may be used in
 110     this section are shared with other unit types. These options are
 111     documented in
 112     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 113     and
 114     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 115     The options specific to the <literal>[Service]</literal> section
 116     of service units are the following:</para>
 117
 118     <variablelist class='unit-directives'>
 119       <varlistentry>
 120         <term><varname>Type=</varname></term>
 121
 122         <listitem><para>Configures the process start-up type for this
 123         service unit. One of
 124         <option>simple</option>,
 125         <option>forking</option>,
 126         <option>oneshot</option>,
 127         <option>dbus</option>,
 128         <option>notify</option> or
 129         <option>idle</option>.</para>
 130
 131         <para>If set to <option>simple</option> (the default if
 132         neither <varname>Type=</varname> nor
 133         <varname>BusName=</varname>, but <varname>ExecStart=</varname>
 134         are specified), it is expected that the process configured
 135         with <varname>ExecStart=</varname> is the main process of the
 136         service. In this mode, if the process offers functionality to
 137         other processes on the system, its communication channels
 138         should be installed before the daemon is started up (e.g.
 139         sockets set up by systemd, via socket activation), as systemd
 140         will immediately proceed starting follow-up units.</para>
 141
 142         <para>If set to <option>forking</option>, it is expected that
 143         the process configured with <varname>ExecStart=</varname> will
 144         call <function>fork()</function> as part of its start-up. The
 145         parent process is expected to exit when start-up is complete
 146         and all communication channels are set up. The child continues
 147         to run as the main daemon process. This is the behavior of
 148         traditional UNIX daemons. If this setting is used, it is
 149         recommended to also use the <varname>PIDFile=</varname>
 150         option, so that systemd can identify the main process of the
 151         daemon. systemd will proceed with starting follow-up units as
 152         soon as the parent process exits.</para>
 153
 154         <para>Behavior of <option>oneshot</option> is similar to
 155         <option>simple</option>; however, it is expected that the
 156         process has to exit before systemd starts follow-up units.
 157         <varname>RemainAfterExit=</varname> is particularly useful for
 158         this type of service. This is the implied default if neither
 159         <varname>Type=</varname> or <varname>ExecStart=</varname> are
 160         specified.</para>
 161
 162         <para>Behavior of <option>dbus</option> is similar to
 163         <option>simple</option>; however, it is expected that the
 164         daemon acquires a name on the D-Bus bus, as configured by
 165         <varname>BusName=</varname>. systemd will proceed with
 166         starting follow-up units after the D-Bus bus name has been
 167         acquired. Service units with this option configured implicitly
 168         gain dependencies on the <filename>dbus.socket</filename>
 169         unit. This type is the default if <varname>BusName=</varname>
 170         is specified.</para>
 171
 172         <para>Behavior of <option>notify</option> is similar to
 173         <option>simple</option>; however, it is expected that the
 174         daemon sends a notification message via
 175         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 176         or an equivalent call when it has finished starting up.
 177         systemd will proceed with starting follow-up units after this
 178         notification message has been sent. If this option is used,
 179         <varname>NotifyAccess=</varname> (see below) should be set to
 180         open access to the notification socket provided by systemd. If
 181         <varname>NotifyAccess=</varname> is not set, it will be
 182         implicitly set to <option>main</option>. Note that currently
 183         <varname>Type=</varname><option>notify</option> will not work
 184         if used in combination with
 185         <varname>PrivateNetwork=</varname><option>yes</option>.</para>
 186
 187         <para>Behavior of <option>idle</option> is very similar to
 188         <option>simple</option>; however, actual execution of the
 189         service binary is delayed until all jobs are dispatched. This
 190         may be used to avoid interleaving of output of shell services
 191         with the status output on the console.</para>
 192         </listitem>
 193       </varlistentry>
 194
 195       <varlistentry>
 196         <term><varname>RemainAfterExit=</varname></term>
 197
 198         <listitem><para>Takes a boolean value that specifies whether
 199         the service shall be considered active even when all its
 200         processes exited. Defaults to <option>no</option>.</para>
 201         </listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><varname>GuessMainPID=</varname></term>
 206
 207         <listitem><para>Takes a boolean value that specifies whether
 208         systemd should try to guess the main PID of a service if it
 209         cannot be determined reliably. This option is ignored unless
 210         <option>Type=forking</option> is set and
 211         <option>PIDFile=</option> is unset because for the other types
 212         or with an explicitly configured PID file, the main PID is
 213         always known. The guessing algorithm might come to incorrect
 214         conclusions if a daemon consists of more than one process. If
 215         the main PID cannot be determined, failure detection and
 216         automatic restarting of a service will not work reliably.
 217         Defaults to <option>yes</option>.</para>
 218         </listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><varname>PIDFile=</varname></term>
 223
 224         <listitem><para>Takes an absolute file name pointing to the
 225         PID file of this daemon. Use of this option is recommended for
 226         services where <varname>Type=</varname> is set to
 227         <option>forking</option>. systemd will read the PID of the
 228         main process of the daemon after start-up of the service.
 229         systemd will not write to the file configured here.</para>
 230         </listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term><varname>BusName=</varname></term>
 235
 236         <listitem><para>Takes a D-Bus bus name that this service is
 237         reachable as. This option is mandatory for services where
 238         <varname>Type=</varname> is set to
 239         <option>dbus</option>.</para>
 240         </listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><varname>BusPolicy=</varname></term>
 245
 246         <listitem><para>If specified, a custom kdbus
 247         endpoint will be created and installed as the default bus node
 248         for the service. Such a custom endpoint can hold an own set of
 249         policy rules that are enforced on top of the bus-wide ones.
 250         The custom endpoint is named after the service it was created
 251         for, and its node will be bind-mounted over the default bus
 252         node location, so the service can only access the bus through
 253         its own endpoint. Note that custom bus endpoints default to a
 254         'deny all' policy. Hence, if at least one
 255         <varname>BusPolicy=</varname> directive is given, you have to
 256         make sure to add explicit rules for everything the service
 257         should be able to do.</para>
 258         <para>The value of this directive is comprised
 259         of two parts; the bus name, and a verb to
 260         specify to granted access, which is one of
 261         <option>see</option>,
 262         <option>talk</option>, or
 263         <option>own</option>.
 264         <option>talk</option> implies
 265         <option>see</option>, and <option>own</option>
 266         implies both <option>talk</option> and
 267         <option>see</option>.
 268         If multiple access levels are specified for the
 269         same bus name, the most powerful one takes
 270         effect.
 271         </para>
 272         <para>Examples:</para>
 273         <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
 274         <programlisting>BusPolicy=org.foo.bar see</programlisting>
 275         <para>This option is only available on kdbus enabled systems.</para>
 276         </listitem>
 277       </varlistentry>
 278
 279       <varlistentry>
 280         <term><varname>ExecStart=</varname></term>
 281         <listitem><para>Commands with their arguments that are
 282         executed when this service is started. The value is split into
 283         zero or more command lines is according to the rules described
 284         below (see section "Command Lines" below).
 285         </para>
 286
 287         <para>When <varname>Type</varname> is not
 288         <option>oneshot</option>, only one command may and must be
 289         given. When <varname>Type=oneshot</varname> is used, zero or
 290         more commands may be specified. This can be specified by
 291         providing multiple command lines in the same directive, or
 292         alternatively, this directive may be specified more than once
 293         with the same effect. If the empty string is assigned to this
 294         option, the list of commands to start is reset, prior
 295         assignments of this option will have no effect. If no
 296         <varname>ExecStart=</varname> is specified, then the service
 297         must have <varname>RemainAfterExit=yes</varname> set.</para>
 298
 299         <para>For each of the specified commands, the first argument
 300         must be an absolute path to an executable. Optionally, if this
 301         file name is prefixed with <literal>@</literal>, the second
 302         token will be passed as <literal>argv[0]</literal> to the
 303         executed process, followed by the further arguments specified.
 304         If the absolute filename is prefixed with
 305         <literal>-</literal>, an exit code of the command normally
 306         considered a failure (i.e. non-zero exit status or abnormal
 307         exit due to signal) is ignored and considered success. If both
 308         <literal>-</literal> and <literal>@</literal> are used, they
 309         can appear in either order.</para>
 310
 311         <para>If more than one command is specified, the commands are
 312         invoked sequentially in the order they appear in the unit
 313         file. If one of the commands fails (and is not prefixed with
 314         <literal>-</literal>), other lines are not executed, and the
 315         unit is considered failed.</para>
 316
 317         <para>Unless <varname>Type=forking</varname> is set, the
 318         process started via this command line will be considered the
 319         main process of the daemon.</para>
 320         </listitem>
 321       </varlistentry>
 322
 323       <varlistentry>
 324         <term><varname>ExecStartPre=</varname></term>
 325         <term><varname>ExecStartPost=</varname></term>
 326         <listitem><para>Additional commands that are executed before
 327         or after the command in <varname>ExecStart=</varname>,
 328         respectively. Syntax is the same as for
 329         <varname>ExecStart=</varname>, except that multiple command
 330         lines are allowed and the commands are executed one after the
 331         other, serially.</para>
 332
 333         <para>If any of those commands (not prefixed with
 334         <literal>-</literal>) fail, the rest are not executed and the
 335         unit is considered failed.</para>
 336
 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>
 341         </listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <term><varname>ExecReload=</varname></term>
 346         <listitem><para>Commands to execute to trigger a configuration
 347         reload in the service. This argument takes multiple command
 348         lines, following the same scheme as described for
 349         <varname>ExecStart=</varname> above. Use of this setting is
 350         optional. Specifier and environment variable substitution is
 351         supported here following the same scheme as for
 352         <varname>ExecStart=</varname>.</para>
 353
 354         <para>One additional, special environment variable is set: if
 355         known, <varname>$MAINPID</varname> is set to the main process
 356         of the daemon, and may be used for command lines like the
 357         following:</para>
 358
 359         <programlisting>/bin/kill -HUP $MAINPID</programlisting>
 360
 361         <para>Note however that reloading a daemon by sending a signal
 362         (as with the example line above) is usually not a good choice,
 363         because this is an asynchronous operation and hence not
 364         suitable to order reloads of multiple services against each
 365         other. It is strongly recommended to set
 366         <varname>ExecReload=</varname> to a command that not only
 367         triggers a configuration reload of the daemon, but also
 368         synchronously waits for it to complete.</para>
 369         </listitem>
 370       </varlistentry>
 371
 372       <varlistentry>
 373         <term><varname>ExecStop=</varname></term>
 374         <listitem><para>Commands to execute to stop the service
 375         started via <varname>ExecStart=</varname>. This argument takes
 376         multiple command lines, following the same scheme as described
 377         for <varname>ExecStart=</varname> above. Use of this setting
 378         is optional. After the commands configured in this option are
 379         run, all processes remaining for a service are terminated
 380         according to the <varname>KillMode=</varname> setting (see
 381         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 382         If this option is not specified, the process is terminated by
 383         sending the signal specified in <varname>KillSignal=</varname>
 384         when service stop is requested. Specifier and environment
 385         variable substitution is supported (including
 386         <varname>$MAINPID</varname>, see above).</para>
 387
 388         <para>Note that it is usually not sufficient to specify a
 389         command for this setting that only asks the service to
 390         terminate (for example by queuing some form of termination
 391         signal for it), but does not wait for it to do so. Since the
 392         remaining processes of the services are killed using
 393         <constant>SIGKILL</constant> immediately after the command
 394         exited this would not result in a clean stop. The specified
 395         command should hence be a synchronous operation, not an
 396         asynchronous one.</para></listitem>
 397       </varlistentry>
 398
 399       <varlistentry>
 400         <term><varname>ExecStopPost=</varname></term>
 401         <listitem><para>Additional commands that are executed after
 402         the service was stopped. This includes cases where the
 403         commands configured in <varname>ExecStop=</varname> were used,
 404         where the service does not have any
 405         <varname>ExecStop=</varname> defined, or where the service
 406         exited unexpectedly. This argument takes multiple command
 407         lines, following the same scheme as described for
 408         <varname>ExecStart</varname>. Use of these settings is
 409         optional. Specifier and environment variable substitution is
 410         supported.</para></listitem>
 411       </varlistentry>
 412
 413       <varlistentry>
 414         <term><varname>RestartSec=</varname></term>
 415         <listitem><para>Configures the time to sleep before restarting
 416         a service (as configured with <varname>Restart=</varname>).
 417         Takes a unit-less value in seconds, or a time span value such
 418         as "5min 20s". Defaults to 100ms.</para></listitem>
 419       </varlistentry>
 420
 421       <varlistentry>
 422         <term><varname>TimeoutStartSec=</varname></term>
 423         <listitem><para>Configures the time to wait for start-up. If a
 424         daemon service does not signal start-up completion within the
 425         configured time, the service will be considered failed and
 426         will be shut down again. Takes a unit-less value in seconds,
 427         or a time span value such as "5min 20s". Pass
 428         <literal>0</literal> to disable the timeout logic. Defaults to
 429         <varname>DefaultTimeoutStartSec=</varname> from the manager
 430         configuration file, except when
 431         <varname>Type=oneshot</varname> is used, in which case the
 432         timeout is disabled by default (see
 433         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 434         </para></listitem>
 435       </varlistentry>
 436
 437       <varlistentry>
 438         <term><varname>TimeoutStopSec=</varname></term>
 439         <listitem><para>Configures the time to wait for stop. If a
 440         service is asked to stop, but does not terminate in the
 441         specified time, it will be terminated forcibly via
 442         <constant>SIGTERM</constant>, and after another timeout of
 443         equal duration with <constant>SIGKILL</constant> (see
 444         <varname>KillMode=</varname> in
 445         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 446         Takes a unit-less value in seconds, or a time span value such
 447         as "5min 20s". Pass <literal>0</literal> to disable the
 448         timeout logic. Defaults to
 449         <varname>DefaultTimeoutStopSec=</varname> from the manager
 450         configuration file (see
 451         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 452         </para></listitem>
 453       </varlistentry>
 454
 455       <varlistentry>
 456         <term><varname>TimeoutSec=</varname></term>
 457         <listitem><para>A shorthand for configuring both
 458         <varname>TimeoutStartSec=</varname> and
 459         <varname>TimeoutStopSec=</varname> to the specified value.
 460         </para></listitem>
 461       </varlistentry>
 462
 463       <varlistentry>
 464         <term><varname>WatchdogSec=</varname></term>
 465         <listitem><para>Configures the watchdog timeout for a service.
 466         The watchdog is activated when the start-up is completed. The
 467         service must call
 468         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 469         regularly with <literal>WATCHDOG=1</literal> (i.e. the
 470         "keep-alive ping"). If the time between two such calls is
 471         larger than the configured time, then the service is placed in
 472         a failed state and it will be terminated with
 473         <varname>SIGABRT</varname>. By setting
 474         <varname>Restart=</varname> to <option>on-failure</option> or
 475         <option>always</option>, the service will be automatically
 476         restarted. The time configured here will be passed to the
 477         executed service process in the
 478         <varname>WATCHDOG_USEC=</varname> environment variable. This
 479         allows daemons to automatically enable the keep-alive pinging
 480         logic if watchdog support is enabled for the service. If this
 481         option is used, <varname>NotifyAccess=</varname> (see below)
 482         should be set to open access to the notification socket
 483         provided by systemd. If <varname>NotifyAccess=</varname> is
 484         not set, it will be implicitly set to <option>main</option>.
 485         Defaults to 0, which disables this feature.</para></listitem>
 486       </varlistentry>
 487
 488       <varlistentry>
 489         <term><varname>Restart=</varname></term>
 490         <listitem><para>Configures whether the service shall be
 491         restarted when the service process exits, is killed, or a
 492         timeout is reached. The service process may be the main
 493         service process, but it may also be one of the processes
 494         specified with <varname>ExecStartPre=</varname>,
 495         <varname>ExecStartPost=</varname>,
 496         <varname>ExecStop=</varname>,
 497         <varname>ExecStopPost=</varname>, or
 498         <varname>ExecReload=</varname>. When the death of the process
 499         is a result of systemd operation (e.g. service stop or
 500         restart), the service will not be restarted. Timeouts include
 501         missing the watchdog "keep-alive ping" deadline and a service
 502         start, reload, and stop operation timeouts.</para>
 503
 504         <para>Takes one of
 505         <option>no</option>,
 506         <option>on-success</option>,
 507         <option>on-failure</option>,
 508         <option>on-abnormal</option>,
 509         <option>on-watchdog</option>,
 510         <option>on-abort</option>, or
 511         <option>always</option>.
 512         If set to <option>no</option> (the default), the service will
 513         not be restarted. If set to <option>on-success</option>, it
 514         will be restarted only when the service process exits cleanly.
 515         In this context, a clean exit means an exit code of 0, or one
 516         of the signals
 517         <constant>SIGHUP</constant>,
 518         <constant>SIGINT</constant>,
 519         <constant>SIGTERM</constant> or
 520         <constant>SIGPIPE</constant>, and
 521         additionally, exit statuses and signals specified in
 522         <varname>SuccessExitStatus=</varname>. If set to
 523         <option>on-failure</option>, the service will be restarted
 524         when the process exits with a non-zero exit code, is
 525         terminated by a signal (including on core dump, but excluding
 526         the aforementioned four signals), when an operation (such as
 527         service reload) times out, and when the configured watchdog
 528         timeout is triggered. If set to <option>on-abnormal</option>,
 529         the service will be restarted when the process is terminated
 530         by a signal (including on core dump, excluding the
 531         aforementioned four signals), when an operation times out, or
 532         when the watchdog timeout is triggered. If set to
 533         <option>on-abort</option>, the service will be restarted only
 534         if the service process exits due to an uncaught signal not
 535         specified as a clean exit status. If set to
 536         <option>on-watchdog</option>, the service will be restarted
 537         only if the watchdog timeout for the service expires. If set
 538         to <option>always</option>, the service will be restarted
 539         regardless of whether it exited cleanly or not, got terminated
 540         abnormally by a signal, or hit a timeout.</para>
 541
 542         <table>
 543           <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>
 544
 545           <tgroup cols='2'>
 546             <colspec colname='path' />
 547             <colspec colname='expl' />
 548             <thead>
 549               <row>
 550                 <entry>Restart settings/Exit causes</entry>
 551                 <entry><option>no</option></entry>
 552                 <entry><option>always</option></entry>
 553                 <entry><option>on-success</option></entry>
 554                 <entry><option>on-failure</option></entry>
 555                 <entry><option>on-abnormal</option></entry>
 556                 <entry><option>on-abort</option></entry>
 557                 <entry><option>on-watchdog</option></entry>
 558               </row>
 559             </thead>
 560             <tbody>
 561               <row>
 562                 <entry>Clean exit code or signal</entry>
 563                 <entry/>
 564                 <entry>X</entry>
 565                 <entry>X</entry>
 566                 <entry/>
 567                 <entry/>
 568                 <entry/>
 569                 <entry/>
 570               </row>
 571               <row>
 572                 <entry>Unclean exit code</entry>
 573                 <entry/>
 574                 <entry>X</entry>
 575                 <entry/>
 576                 <entry>X</entry>
 577                 <entry/>
 578                 <entry/>
 579                 <entry/>
 580               </row>
 581               <row>
 582                 <entry>Unclean signal</entry>
 583                 <entry/>
 584                 <entry>X</entry>
 585                 <entry/>
 586                 <entry>X</entry>
 587                 <entry>X</entry>
 588                 <entry>X</entry>
 589                 <entry/>
 590               </row>
 591               <row>
 592                 <entry>Timeout</entry>
 593                 <entry/>
 594                 <entry>X</entry>
 595                 <entry/>
 596                 <entry>X</entry>
 597                 <entry>X</entry>
 598                 <entry/>
 599                 <entry/>
 600               </row>
 601               <row>
 602                 <entry>Watchdog</entry>
 603                 <entry/>
 604                 <entry>X</entry>
 605                 <entry/>
 606                 <entry>X</entry>
 607                 <entry>X</entry>
 608                 <entry/>
 609                 <entry>X</entry>
 610               </row>
 611             </tbody>
 612           </tgroup>
 613         </table>
 614
 615         <para>As exceptions to the setting above the service will not
 616         be restarted if the exit code or signal is specified in
 617         <varname>RestartPreventExitStatus=</varname> (see below).
 618         Also, the services will always be restarted if the exit code
 619         or signal is specified in
 620         <varname>RestartForceExitStatus=</varname> (see below).</para>
 621
 622         <para>Setting this to <option>on-failure</option> is the
 623         recommended choice for long-running services, in order to
 624         increase reliability by attempting automatic recovery from
 625         errors. For services that shall be able to terminate on their
 626         own choice (and avoid immediate restarting),
 627         <option>on-abnormal</option> is an alternative choice.</para>
 628         </listitem>
 629       </varlistentry>
 630
 631       <varlistentry>
 632         <term><varname>SuccessExitStatus=</varname></term>
 633         <listitem><para>Takes a list of exit status definitions that
 634         when returned by the main service process will be considered
 635         successful termination, in addition to the normal successful
 636         exit code 0 and the signals <constant>SIGHUP</constant>,
 637         <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and
 638         <constant>SIGPIPE</constant>. Exit status definitions can
 639         either be numeric exit codes or termination signal names,
 640         separated by spaces. For example:
 641         <programlisting>SuccessExitStatus=1 2 8
 642         SIGKILL</programlisting> ensures that exit codes 1, 2, 8 and
 643         the termination signal <constant>SIGKILL</constant> are
 644         considered clean service terminations.
 645         </para>
 646
 647         <para>Note that if a process has a signal handler installed
 648         and exits by calling
 649         <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 650         in response to a signal, the information about the signal is
 651         lost. Programs should instead perform cleanup and kill
 652         themselves with the same signal instead. See
 653         <ulink url="http://www.cons.org/cracauer/sigint.html">Proper
 654         handling of SIGINT/SIGQUIT — How to be a proper
 655         program</ulink>.</para>
 656
 657         <para>This option may appear more than once, in which case the
 658         list of successful exit statuses is merged. If the empty
 659         string is assigned to this option, the list is reset, all
 660         prior assignments of this option will have no
 661         effect.</para></listitem>
 662       </varlistentry>
 663
 664       <varlistentry>
 665         <term><varname>RestartPreventExitStatus=</varname></term>
 666         <listitem><para>Takes a list of exit status definitions that
 667         when returned by the main service process will prevent
 668         automatic service restarts, regardless of the restart setting
 669         configured with <varname>Restart=</varname>. Exit status
 670         definitions can either be numeric exit codes or termination
 671         signal names, and are separated by spaces. Defaults to the
 672         empty list, so that, by default, no exit status is excluded
 673         from the configured restart logic. For example:
 674         <programlisting>RestartPreventExitStatus=1 6
 675         SIGABRT</programlisting> ensures that exit codes 1 and 6 and
 676         the termination signal <constant>SIGABRT</constant> will not
 677         result in automatic service restarting. This option may appear
 678         more than once, in which case the list of restart-preventing
 679         statuses is merged. If the empty string is assigned to this
 680         option, the list is reset and all prior assignments of this
 681         option will have no effect.</para></listitem>
 682       </varlistentry>
 683
 684       <varlistentry>
 685         <term><varname>RestartForceExitStatus=</varname></term>
 686         <listitem><para>Takes a list of exit status definitions that
 687         when returned by the main service process will force automatic
 688         service restarts, regardless of the restart setting configured
 689         with <varname>Restart=</varname>. The argument format is
 690         similar to
 691         <varname>RestartPreventExitStatus=</varname>.</para></listitem>
 692       </varlistentry>
 693
 694       <varlistentry>
 695         <term><varname>PermissionsStartOnly=</varname></term>
 696         <listitem><para>Takes a boolean argument. If true, the
 697         permission-related execution options, as configured with
 698         <varname>User=</varname> and similar options (see
 699         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 700         for more information), are only applied to the process started
 701         with
 702         <varname>ExecStart=</varname>, and not to the various other
 703         <varname>ExecStartPre=</varname>,
 704         <varname>ExecStartPost=</varname>,
 705         <varname>ExecReload=</varname>,
 706         <varname>ExecStop=</varname>, and
 707         <varname>ExecStopPost=</varname>
 708         commands. If false, the setting is applied to all configured
 709         commands the same way. Defaults to false.</para></listitem>
 710       </varlistentry>
 711
 712       <varlistentry>
 713         <term><varname>RootDirectoryStartOnly=</varname></term>
 714         <listitem><para>Takes a boolean argument. If true, the root
 715         directory, as configured with the
 716         <varname>RootDirectory=</varname> option (see
 717         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 718         for more information), is only applied to the process started
 719         with <varname>ExecStart=</varname>, and not to the various
 720         other <varname>ExecStartPre=</varname>,
 721         <varname>ExecStartPost=</varname>,
 722         <varname>ExecReload=</varname>, <varname>ExecStop=</varname>,
 723         and <varname>ExecStopPost=</varname> commands. If false, the
 724         setting is applied to all configured commands the same way.
 725         Defaults to false.</para></listitem>
 726       </varlistentry>
 727
 728       <varlistentry>
 729         <term><varname>NonBlocking=</varname></term>
 730         <listitem><para>Set the <constant>O_NONBLOCK</constant> flag
 731         for all file descriptors passed via socket-based activation.
 732         If true, all file descriptors >= 3 (i.e. all except stdin,
 733         stdout, and stderr) will have the
 734         <constant>O_NONBLOCK</constant> flag set and hence are in
 735         non-blocking mode. This option is only useful in conjunction
 736         with a socket unit, as described in
 737         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 738         Defaults to false.</para></listitem>
 739       </varlistentry>
 740
 741       <varlistentry>
 742         <term><varname>NotifyAccess=</varname></term>
 743         <listitem><para>Controls access to the service status
 744         notification socket, as accessible via the
 745         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 746         call. Takes one of <option>none</option> (the default),
 747         <option>main</option> or <option>all</option>. If
 748         <option>none</option>, no daemon status updates are accepted
 749         from the service processes, all status update messages are
 750         ignored. If <option>main</option>, only service updates sent
 751         from the main process of the service are accepted. If
 752         <option>all</option>, all services updates from all members of
 753         the service's control group are accepted. This option should
 754         be set to open access to the notification socket when using
 755         <varname>Type=notify</varname> or
 756         <varname>WatchdogSec=</varname> (see above). If those options
 757         are used but <varname>NotifyAccess=</varname> is not
 758         configured, it will be implicitly set to
 759         <option>main</option>.</para></listitem>
 760       </varlistentry>
 761
 762       <varlistentry>
 763         <term><varname>Sockets=</varname></term>
 764         <listitem><para>Specifies the name of the socket units this
 765         service shall inherit socket file descriptors from when the
 766         service is started. Normally it should not be necessary to use
 767         this setting as all socket file descriptors whose unit shares
 768         the same name as the service (subject to the different unit
 769         name suffix of course) are passed to the spawned
 770         process.</para>
 771
 772         <para>Note that the same socket file descriptors may be passed
 773         to multiple processes simultaneously. Also note that a
 774         different service may be activated on incoming socket traffic
 775         than the one which is ultimately configured to inherit the
 776         socket file descriptors. Or in other words: the
 777         <varname>Service=</varname> setting of
 778         <filename>.socket</filename> units does not have to match the
 779         inverse of the <varname>Sockets=</varname> setting of the
 780         <filename>.service</filename> it refers to.</para>
 781
 782         <para>This option may appear more than once, in which case the
 783         list of socket units is merged. If the empty string is
 784         assigned to this option, the list of sockets is reset, and all
 785         prior uses of this setting will have no
 786         effect.</para></listitem>
 787       </varlistentry>
 788
 789       <varlistentry>
 790         <term><varname>StartLimitInterval=</varname></term>
 791         <term><varname>StartLimitBurst=</varname></term>
 792
 793         <listitem><para>Configure service start rate limiting. By
 794         default, services which are started more than 5 times within
 795         10 seconds are not permitted to start any more times until the
 796         10 second interval ends. With these two options, this rate
 797         limiting may be modified. Use
 798         <varname>StartLimitInterval=</varname> to configure the
 799         checking interval (defaults to
 800         <varname>DefaultStartLimitInterval=</varname> in manager
 801         configuration file, set to 0 to disable any kind of rate
 802         limiting). Use <varname>StartLimitBurst=</varname> to
 803         configure how many starts per interval are allowed (defaults
 804         to <varname>DefaultStartLimitBurst=</varname> in manager
 805         configuration file). These configuration options are
 806         particularly useful in conjunction with
 807         <varname>Restart=</varname>; however, they apply to all kinds
 808         of starts (including manual), not just those triggered by the
 809         <varname>Restart=</varname> logic. Note that units which are
 810         configured for <varname>Restart=</varname> and which reach the
 811         start limit are not attempted to be restarted anymore;
 812         however, they may still be restarted manually at a later
 813         point, from which point on, the restart logic is again
 814         activated. Note that <command>systemctl reset-failed</command>
 815         will cause the restart rate counter for a service to be
 816         flushed, which is useful if the administrator wants to
 817         manually start a service and the start limit interferes with
 818         that.</para></listitem>
 819       </varlistentry>
 820
 821       <varlistentry>
 822         <term><varname>StartLimitAction=</varname></term>
 823
 824         <listitem><para>Configure the action to take if the rate limit
 825         configured with <varname>StartLimitInterval=</varname> and
 826         <varname>StartLimitBurst=</varname> is hit. Takes one of
 827         <option>none</option>,
 828         <option>reboot</option>,
 829         <option>reboot-force</option>,
 830         <option>reboot-immediate</option>,
 831         <option>poweroff</option>,
 832         <option>poweroff-force</option> or
 833         <option>poweroff-immediate</option>. If
 834         <option>none</option> is set, hitting the rate limit will
 835         trigger no action besides that the start will not be
 836         permitted. <option>reboot</option> causes a reboot following
 837         the normal shutdown procedure (i.e. equivalent to
 838         <command>systemctl reboot</command>).
 839         <option>reboot-force</option> causes a forced reboot which
 840         will terminate all processes forcibly but should cause no
 841         dirty file systems on reboot (i.e. equivalent to
 842         <command>systemctl reboot -f</command>) and
 843         <option>reboot-immediate</option> causes immediate execution
 844         of the
 845         <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 846         system call, which might result in data loss. Similar,
 847         <option>poweroff</option>, <option>poweroff-force</option>,
 848         <option>poweroff-immediate</option> have the effect of
 849         powering down the system with similar semantics. Defaults to
 850         <option>none</option>.</para></listitem>
 851       </varlistentry>
 852
 853       <varlistentry>
 854         <term><varname>FailureAction=</varname></term>
 855         <listitem><para>Configure the action to take when the service
 856         enters a failed state. Takes the same values as
 857         <varname>StartLimitAction=</varname> and executes the same
 858         actions. Defaults to <option>none</option>. </para></listitem>
 859       </varlistentry>
 860
 861       <varlistentry>
 862         <term><varname>RebootArgument=</varname></term>
 863         <listitem><para>Configure the optional argument for the
 864         <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 865         system call if <varname>StartLimitAction=</varname> or
 866         <varname>FailureAction=</varname> is a reboot action. This
 867         works just like the optional argument to <command>systemctl
 868         reboot</command> command.</para></listitem>
 869       </varlistentry>
 870
 871       <varlistentry>
 872         <term><varname>FileDescriptorStoreMax=</varname></term>
 873         <listitem><para>Configure how many file descriptors may be
 874         stored in the service manager for the service using
 875         <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
 876         <literal>FDSTORE=1</literal> messages. This is useful for
 877         implementing service restart schemes where the state is
 878         serialized to <filename>/run</filename> and the file
 879         descriptors passed to the service manager, to allow restarts
 880         without losing state. Defaults to 0, i.e. no file descriptors
 881         may be stored in the service manager by default. All file
 882         descriptors passed to the service manager from a specific
 883         service are passed back to the service's main process on the
 884         next service restart. Any file descriptors passed to the
 885         service manager are automatically closed when POLLHUP or
 886         POLLERR is seen on them, or when the service is fully stopped
 887         and no job queued or being executed for it.</para></listitem>
 888       </varlistentry>
 889
 890     </variablelist>
 891
 892     <para>Check
 893     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 894     and
 895     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 896     for more settings.</para>
 897
 898   </refsect1>
 899
 900   <refsect1>
 901     <title>Command lines</title>
 902
 903     <para>This section describes command line parsing and
 904     variable and specifier substitutions for
 905     <varname>ExecStart=</varname>,
 906     <varname>ExecStartPre=</varname>,
 907     <varname>ExecStartPost=</varname>,
 908     <varname>ExecReload=</varname>,
 909     <varname>ExecStop=</varname>, and
 910     <varname>ExecStopPost=</varname> options.</para>
 911
 912     <para>Multiple command lines may be concatenated in a single
 913     directive by separating them with semicolons (these semicolons
 914     must be passed as separate words). Lone semicolons may be escaped
 915     as <literal>\;</literal>.</para>
 916
 917     <para>Each command line is split on whitespace, with the first
 918     item being the command to execute, and the subsequent items being
 919     the arguments. Double quotes ("...") and single quotes ('...') may
 920     be used, in which case everything until the next matching quote
 921     becomes part of the same argument. C-style escapes are also
 922     supported, see table below. Quotes themselves are removed after
 923     parsing and escape sequences substituted. In addition, a trailing
 924     backslash (<literal>\</literal>) may be used to merge lines.
 925     </para>
 926
 927     <para>This syntax is intended to be very similar to shell syntax,
 928     but only the meta-characters and expansions described in the
 929     following paragraphs are understood. Specifically, redirection
 930     using
 931     <literal>&lt;</literal>,
 932     <literal>&lt;&lt;</literal>,
 933     <literal>&gt;</literal>, and
 934     <literal>&gt;&gt;</literal>, pipes using
 935     <literal>|</literal>, running programs in the background using
 936     <literal>&amp;</literal>, and <emphasis>other elements of shell
 937     syntax are not supported</emphasis>.</para>
 938
 939     <para>The command to execute must an absolute path name. It may
 940     contain spaces, but control characters are not allowed.</para>
 941
 942     <para>The command line accepts <literal>%</literal> specifiers as
 943     described in
 944     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 945     Note that the first argument of the command line (i.e. the program
 946     to execute) may not include specifiers.</para>
 947
 948     <para>Basic environment variable substitution is supported. Use
 949     <literal>${FOO}</literal> as part of a word, or as a word of its
 950     own, on the command line, in which case it will be replaced by the
 951     value of the environment variable including all whitespace it
 952     contains, resulting in a single argument. Use
 953     <literal>$FOO</literal> as a separate word on the command line, in
 954     which case it will be replaced by the value of the environment
 955     variable split at whitespace resulting in zero or more arguments.
 956     For this type of expansion, quotes and respected when splitting
 957     into words, and afterwards removed.</para>
 958
 959     <para>Example:</para>
 960
 961     <programlisting>Environment="ONE=one" 'TWO=two two'
 962 ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
 963
 964     <para>This will execute <command>/bin/echo</command> with four
 965     arguments: <literal>one</literal>, <literal>two</literal>,
 966     <literal>two</literal>, and <literal>two two</literal>.</para>
 967
 968     <para>Example:</para>
 969     <programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
 970 ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
 971 ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
 972     <para>This results in <filename>echo</filename> being
 973     called twice, the first time with arguments
 974     <literal>'one'</literal>,
 975     <literal>'two two' too</literal>, <literal></literal>,
 976     and the second time with arguments
 977     <literal>one</literal>, <literal>two two</literal>,
 978     <literal>too</literal>.
 979     </para>
 980
 981     <para>To pass a literal dollar sign, use <literal>$$</literal>.
 982     Variables whose value is not known at expansion time are treated
 983     as empty strings. Note that the first argument (i.e. the program
 984     to execute) may not be a variable.</para>
 985
 986     <para>Variables to be used in this fashion may be defined through
 987     <varname>Environment=</varname> and
 988     <varname>EnvironmentFile=</varname>. In addition, variables listed
 989     in the section "Environment variables in spawned processes" in
 990     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 991     which are considered "static configuration", may be used (this
 992     includes e.g. <varname>$USER</varname>, but not
 993     <varname>$TERM</varname>).</para>
 994
 995     <para>Note that shell command lines are not directly supported. If
 996     shell command lines are to be used, they need to be passed
 997     explicitly to a shell implementation of some kind. Example:</para>
 998     <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
 999
1000     <para>Example:</para>
1001
1002     <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
1003
1004     <para>This will execute <command>/bin/echo</command> two times,
1005     each time with one argument: <literal>one</literal> and
1006     <literal>two two</literal>, respectively. Because two commands are
1007     specified, <varname>Type=oneshot</varname> must be used.</para>
1008
1009     <para>Example:</para>
1010
1011     <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
1012 /bin/ls</programlisting>
1013
1014     <para>This will execute <command>/bin/echo</command>
1015     with five arguments: <literal>/</literal>,
1016     <literal>&gt;/dev/null</literal>,
1017     <literal>&amp;</literal>, <literal>;</literal>, and
1018     <literal>/bin/ls</literal>.</para>
1019
1020     <table>
1021       <title>C escapes supported in command lines and environment variables</title>
1022       <tgroup cols='2'>
1023         <colspec colname='escape' />
1024         <colspec colname='meaning' />
1025         <thead>
1026           <row>
1027             <entry>Literal</entry>
1028             <entry>Actual value</entry>
1029           </row>
1030         </thead>
1031         <tbody>
1032           <row>
1033             <entry><literal>\a</literal></entry>
1034             <entry>bell</entry>
1035           </row>
1036           <row>
1037             <entry><literal>\b</literal></entry>
1038             <entry>backspace</entry>
1039           </row>
1040           <row>
1041             <entry><literal>\f</literal></entry>
1042             <entry>form feed</entry>
1043           </row>
1044           <row>
1045             <entry><literal>\n</literal></entry>
1046             <entry>newline</entry>
1047           </row>
1048           <row>
1049             <entry><literal>\r</literal></entry>
1050             <entry>carriage return</entry>
1051           </row>
1052           <row>
1053             <entry><literal>\t</literal></entry>
1054             <entry>tab</entry>
1055           </row>
1056           <row>
1057             <entry><literal>\v</literal></entry>
1058             <entry>vertical tab</entry>
1059           </row>
1060           <row>
1061             <entry><literal>\\</literal></entry>
1062             <entry>backslash</entry>
1063           </row>
1064           <row>
1065             <entry><literal>\"</literal></entry>
1066             <entry>double quotation mark</entry>
1067           </row>
1068           <row>
1069             <entry><literal>\'</literal></entry>
1070             <entry>single quotation mark</entry>
1071           </row>
1072           <row>
1073             <entry><literal>\s</literal></entry>
1074             <entry>space</entry>
1075           </row>
1076           <row>
1077             <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
1078             <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
1079           </row>
1080           <row>
1081             <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
1082             <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
1083           </row>
1084         </tbody>
1085       </tgroup>
1086     </table>
1087   </refsect1>
1088
1089   <refsect1>
1090     <title>Examples</title>
1091
1092     <example>
1093       <title>Simple service</title>
1094
1095       <para>The following unit file creates a service that will
1096       execute <filename>/usr/sbin/foo-daemon</filename>. Since no
1097       <varname>Type=</varname> is specified, the default
1098       <varname>Type=</varname><option>simple</option> will be assumed.
1099       systemd will assume the unit to be started immediately after the
1100       program has begun executing.</para>
1101
1102       <programlisting>[Unit]
1103 Description=Foo
1104
1105 [Service]
1106 ExecStart=/usr/sbin/foo-daemon
1107
1108 [Install]
1109 WantedBy=multi-user.target</programlisting>
1110
1111       <para>Note that systemd assumes here that the process started by
1112       systemd will continue running until the service terminates. If
1113       the program daemonizes itself (i.e. forks), please use
1114       <varname>Type=</varname><option>forking</option> instead.</para>
1115
1116       <para>Since no <varname>ExecStop=</varname> was specified,
1117       systemd will send SIGTERM to all processes started from this
1118       service, and after a timeout also SIGKILL. This behavior can be
1119       modified, see
1120       <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1121       for details.</para>
1122
1123       <para>Note that this unit type does not include any type of
1124       notification when a service has completed initialization. For
1125       this, you should use other unit types, such as
1126       <varname>Type=</varname><option>notify</option> if the service
1127       understands systemd's notification protocol,
1128       <varname>Type=</varname><option>forking</option> if the service
1129       can background itself or
1130       <varname>Type=</varname><option>dbus</option> if the unit
1131       acquires a DBus name once initialization is complete. See
1132       below.</para>
1133     </example>
1134
1135     <example>
1136       <title>Oneshot service</title>
1137
1138       <para>Sometimes units should just execute an action without
1139       keeping active processes, such as a filesystem check or a
1140       cleanup action on boot. For this,
1141       <varname>Type=</varname><option>oneshot</option> exists. Units
1142       of this type will wait until the process specified terminates
1143       and then fall back to being inactive. The following unit will
1144       perform a cleanup action:</para>
1145
1146       <programlisting>[Unit]
1147 Description=Cleanup old Foo data
1148
1149 [Service]
1150 Type=oneshot
1151 ExecStart=/usr/sbin/foo-cleanup
1152
1153 [Install]
1154 WantedBy=multi-user.target</programlisting>
1155
1156       <para>Note that systemd will consider the unit to be in the
1157       state 'starting' until the program has terminated, so ordered
1158       dependencies will wait for the program to finish before starting
1159       themselves. The unit will revert to the 'inactive' state after
1160       the execution is done, never reaching the 'active' state. That
1161       means another request to start the unit will perform the action
1162       again.</para>
1163
1164       <para><varname>Type=</varname><option>oneshot</option> are the
1165       only service units that may have more than one
1166       <varname>ExecStart=</varname> specified. They will be executed
1167       in order until either they are all successful or one of them
1168       fails.</para>
1169     </example>
1170
1171     <example>
1172       <title>Stoppable oneshot service</title>
1173
1174       <para>Similarly to the oneshot services, there are sometimes
1175       units that need to execute a program to set up something and
1176       then execute another to shut it down, but no process remains
1177       active while they are considered 'started'. Network
1178       configuration can sometimes fall into this category. Another use
1179       case is if a oneshot service shall not be executed a each time
1180       when they are pulled in as a dependency, but only the first
1181       time.</para>
1182
1183       <para>For this, systemd knows the setting
1184       <varname>RemainAfterExit=</varname><option>yes</option>, which
1185       causes systemd to consider the unit to be active if the start
1186       action exited successfully. This directive can be used with all
1187       types, but is most useful with
1188       <varname>Type=</varname><option>oneshot</option> and
1189       <varname>Type=</varname><option>simple</option>. With
1190       <varname>Type=</varname><option>oneshot</option> systemd waits
1191       until the start action has completed before it considers the
1192       unit to be active, so dependencies start only after the start
1193       action has succeeded. With
1194       <varname>Type=</varname><option>simple</option> dependencies
1195       will start immediately after the start action has been
1196       dispatched. The following unit provides an example for a simple
1197       static firewall.</para>
1198
1199       <programlisting>[Unit]
1200 Description=Simple firewall
1201
1202 [Service]
1203 Type=oneshot
1204 RemainAfterExit=yes
1205 ExecStart=/usr/local/sbin/simple-firewall-start
1206 ExecStop=/usr/local/sbin/simple-firewall-stop
1207
1208 [Install]
1209 WantedBy=multi-user.target</programlisting>
1210
1211       <para>Since the unit is considered to be running after the start
1212       action has exited, invoking <command>systemctl start</command>
1213       on that unit again will cause no action to be taken.</para>
1214     </example>
1215
1216     <example>
1217       <title>Traditional forking services</title>
1218
1219       <para>Many traditional daemons/services background (i.e. fork,
1220       daemonize) themselves when starting. Set
1221       <varname>Type=</varname><option>forking</option> in the
1222       service's unit file to support this mode of operation. systemd
1223       will consider the service to be in the process of initialization
1224       while the original program is still running. Once it exits
1225       successfully and at least a process remains (and
1226       <varname>RemainAfterExit=</varname><option>no</option>), the
1227       service is considered started.</para>
1228
1229       <para>Often a traditional daemon only consists of one process.
1230       Therefore, if only one process is left after the original
1231       process terminates, systemd will consider that process the main
1232       process of the service. In that case, the
1233       <varname>$MAINPID</varname> variable will be available in
1234       <varname>ExecReload=</varname>, <varname>ExecStop=</varname>,
1235       etc.</para>
1236
1237       <para>In case more than one process remains, systemd will be
1238       unable to determine the main process, so it will not assume
1239       there is one. In that case, <varname>$MAINPID</varname> will not
1240       expand to anything. However, if the process decides to write a
1241       traditional PID file, systemd will be able to read the main PID
1242       from there. Please set <varname>PIDFile=</varname> accordingly.
1243       Note that the daemon should write that file before finishing
1244       with its initialization, otherwise systemd might try to read the
1245       file before it exists.</para>
1246
1247       <para>The following example shows a simple daemon that forks and
1248       just starts one process in the background:</para>
1249
1250       <programlisting>[Unit]
1251 Description=Some simple daemon
1252
1253 [Service]
1254 Type=forking
1255 ExecStart=/usr/sbin/my-simple-daemon -d
1256
1257 [Install]
1258 WantedBy=multi-user.target</programlisting>
1259
1260       <para>Please see
1261       <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1262       for details on how you can influence the way systemd terminates
1263       the service.</para>
1264     </example>
1265
1266     <example>
1267       <title>DBus services</title>
1268
1269       <para>For services that acquire a name on the DBus system bus,
1270       use <varname>Type=</varname><option>dbus</option> and set
1271       <varname>BusName=</varname> accordingly. The service should not
1272       fork (daemonize). systemd will consider the service to be
1273       initialized once the name has been acquired on the system bus.
1274       The following example shows a typical DBus service:</para>
1275
1276       <programlisting>[Unit]
1277 Description=Simple DBus service
1278
1279 [Service]
1280 Type=dbus
1281 BusName=org.example.simple-dbus-service
1282 ExecStart=/usr/sbin/simple-dbus-service
1283
1284 [Install]
1285 WantedBy=multi-user.target</programlisting>
1286
1287       <para>For <emphasis>bus-activatable</emphasis> services, don't
1288       include a <literal>[Install]</literal> section in the systemd
1289       service file, but use the <varname>SystemdService=</varname>
1290       option in the corresponding DBus service file, for example
1291       (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>
1292
1293       <programlisting>[D-BUS Service]
1294 Name=org.example.simple-dbus-service
1295 Exec=/usr/sbin/simple-dbus-service
1296 User=root
1297 SystemdService=simple-dbus-service.service</programlisting>
1298
1299       <para>Please see
1300       <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1301       for details on how you can influence the way systemd terminates
1302       the service.</para>
1303     </example>
1304
1305     <example>
1306       <title>Services that notify systemd about their initialization</title>
1307
1308       <para><varname>Type=</varname><option>simple</option> services
1309       are really easy to write, but have the major disadvantage of
1310       systemd not being able to tell when initialization of the given
1311       service is complete. For this reason, systemd supports a simple
1312       notification protocol that allows daemons to make systemd aware
1313       that they are done initializing. Use
1314       <varname>Type=</varname><option>notify</option> for this. A
1315       typical service file for such a daemon would look like
1316       this:</para>
1317
1318       <programlisting>[Unit]
1319 Description=Simple notifying service
1320
1321 [Service]
1322 Type=notify
1323 ExecStart=/usr/sbin/simple-notifying-service
1324
1325 [Install]
1326 WantedBy=multi-user.target</programlisting>
1327
1328       <para>Note that the daemon has to support systemd's notification
1329       protocol, else systemd will think the service hasn't started yet
1330       and kill it after a timeout. For an example of how to update
1331       daemons to support this protocol transparently, take a look at
1332       <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
1333       systemd will consider the unit to be in the 'starting' state
1334       until a readiness notification has arrived.</para>
1335
1336       <para>Please see
1337       <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1338       for details on how you can influence the way systemd terminates
1339       the service.</para>
1340     </example>
1341   </refsect1>
1342
1343   <refsect1>
1344       <title>See Also</title>
1345       <para>
1346         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1347         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1348         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1349         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1350         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1351         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1352         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1353       </para>
1354   </refsect1>
1355
1356 </refentry>