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