man/systemd.service.xml

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