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
  59                 about a process controlled and supervised by
  60                 systemd.</para>
  61
  62                 <para>This man page lists the configuration options
  63                 specific to this unit type. See
  64                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  65                 for the common options of all unit configuration
  66                 files. The common configuration items are configured
  67                 in the generic <literal>[Unit]</literal> and
  68                 <literal>[Install]</literal> sections. The service
  69                 specific configuration options are configured in the
  70                 <literal>[Service]</literal> section.</para>
  71
  72                 <para>Additional options are listed in
  73                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  74                 which define the execution environment the commands
  75                 are executed in, and in
  76                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  77                 which define the way the processes of the service are
  78                 terminated, and in
  79                 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  80                 which configure resource control settings for the
  81                 processes of the service.</para>
  82
  83                 <para>Unless <varname>DefaultDependencies=</varname>
  84                 is set to <option>false</option>, service units will
  85                 implicitly have dependencies of type
  86                 <varname>Requires=</varname> and
  87                 <varname>After=</varname> on
  88                 <filename>basic.target</filename> as well as
  89                 dependencies of type <varname>Conflicts=</varname> and
  90                 <varname>Before=</varname> on
  91                 <filename>shutdown.target</filename>. These ensure
  92                 that normal service units pull in basic system
  93                 initialization, and are terminated cleanly prior to
  94                 system shutdown. Only services involved with early
  95                 boot or late system shutdown should disable this
  96                 option.</para>
  97
  98                 <para>If a service is requested under a certain name
  99                 but no unit configuration file is found, systemd looks
 100                 for a SysV init script by the same name (with the
 101                 <filename>.service</filename> suffix removed) and
 102                 dynamically creates a service unit from that
 103                 script. This is useful for compatibility with
 104                 SysV. Note that this compatibility is quite
 105                 comprehensive but not 100%. For details about the
 106                 incompatibilities see the <ulink
 107                 url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
 108                 with SysV</ulink> document.
 109                 </para>
 110         </refsect1>
 111
 112         <refsect1>
 113                 <title>Options</title>
 114
 115                 <para>Service files must include a
 116                 <literal>[Service]</literal> section, which carries
 117                 information about the service and the process it
 118                 supervises. A number of options that may be used in
 119                 this section are shared with other unit types. These
 120                 options are documented in
 121                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 122                 and
 123                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 124                 options specific to the <literal>[Service]</literal>
 125                 section of service units are the following:</para>
 126
 127                 <variablelist class='unit-directives'>
 128                         <varlistentry>
 129                                 <term><varname>Type=</varname></term>
 130
 131                                 <listitem><para>Configures the process
 132                                 start-up type for this service
 133                                 unit. One of <option>simple</option>,
 134                                 <option>forking</option>,
 135                                 <option>oneshot</option>,
 136                                 <option>dbus</option>,
 137                                 <option>notify</option> or
 138                                 <option>idle</option>.</para>
 139
 140                                 <para>If set to
 141                                 <option>simple</option> (the default
 142                                 value if <varname>BusName=</varname>
 143                                 is not specified), it is expected that
 144                                 the process configured with
 145                                 <varname>ExecStart=</varname> is the
 146                                 main process of the service. In this
 147                                 mode, if the process offers
 148                                 functionality to other processes on
 149                                 the system, its communication channels
 150                                 should be installed before the daemon
 151                                 is started up (e.g. sockets set up by
 152                                 systemd, via socket activation), as
 153                                 systemd will immediately proceed
 154                                 starting follow-up units.</para>
 155
 156                                 <para>If set to
 157                                 <option>forking</option>, it is
 158                                 expected that the process configured
 159                                 with <varname>ExecStart=</varname>
 160                                 will call <function>fork()</function>
 161                                 as part of its start-up. The parent process is
 162                                 expected to exit when start-up is
 163                                 complete and all communication
 164                                 channels are set up. The child continues
 165                                 to run as the main daemon
 166                                 process. This is the behavior of
 167                                 traditional UNIX daemons. If this
 168                                 setting is used, it is recommended to
 169                                 also use the
 170                                 <varname>PIDFile=</varname> option, so
 171                                 that systemd can identify the main
 172                                 process of the daemon. systemd will
 173                                 proceed starting follow-up units as
 174                                 soon as the parent process
 175                                 exits.</para>
 176
 177                                 <para>Behavior of
 178                                 <option>oneshot</option> is similar
 179                                 to <option>simple</option>, however
 180                                 it is expected that the process has to
 181                                 exit before systemd starts follow-up
 182                                 units. <varname>RemainAfterExit=</varname>
 183                                 is particularly useful for this type
 184                                 of service.</para>
 185
 186                                 <para>Behavior of
 187                                 <option>dbus</option> is similar to
 188                                 <option>simple</option>, however it is
 189                                 expected that the daemon acquires a
 190                                 name on the D-Bus bus, as configured
 191                                 by
 192                                 <varname>BusName=</varname>. systemd
 193                                 will proceed starting follow-up units
 194                                 after the D-Bus bus name has been
 195                                 acquired. Service units with this
 196                                 option configured implicitly gain
 197                                 dependencies on the
 198                                 <filename>dbus.socket</filename>
 199                                 unit. This type is the default if
 200                                 <varname>BusName=</varname> is
 201                                 specified.</para>
 202
 203                                 <para>Behavior of
 204                                 <option>notify</option> is similar to
 205                                 <option>simple</option>, however it is
 206                                 expected that the daemon sends a
 207                                 notification message via
 208                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 209                                 or an equivalent call when it finished
 210                                 starting up. systemd will proceed
 211                                 starting follow-up units after this
 212                                 notification message has been sent. If
 213                                 this option is used,
 214                                 <varname>NotifyAccess=</varname> (see
 215                                 below) should be set to open access to
 216                                 the notification socket provided by
 217                                 systemd. If
 218                                 <varname>NotifyAccess=</varname> is
 219                                 not set, it will be implicitly set to
 220                                 <option>main</option>. Note that
 221                                 currently
 222                                 <varname>Type=</varname><option>notify</option>
 223                                 will not work if used in combination with
 224                                 <varname>PrivateNetwork=</varname><option>yes</option>.</para>
 225
 226                                 <para>Behavior of
 227                                 <option>idle</option> is very similar
 228                                 to <option>simple</option>, however
 229                                 actual execution of the service
 230                                 binary is delayed until all jobs are
 231                                 dispatched. This may be used to avoid
 232                                 interleaving of output of shell
 233                                 services with the status output on the
 234                                 console.</para>
 235                                 </listitem>
 236                         </varlistentry>
 237
 238                         <varlistentry>
 239                                 <term><varname>RemainAfterExit=</varname></term>
 240
 241                                 <listitem><para>Takes a boolean value
 242                                 that specifies whether the service
 243                                 shall be considered active even when
 244                                 all its processes exited. Defaults to
 245                                 <option>no</option>.</para>
 246                                 </listitem>
 247                         </varlistentry>
 248
 249                         <varlistentry>
 250                                 <term><varname>GuessMainPID=</varname></term>
 251
 252                                 <listitem><para>Takes a boolean value
 253                                 that specifies whether systemd should
 254                                 try to guess the main PID of a service
 255                                 if it cannot be determined
 256                                 reliably. This option is ignored
 257                                 unless <option>Type=forking</option>
 258                                 is set and <option>PIDFile=</option>
 259                                 is unset because for the other types
 260                                 or with an explicitly configured PID
 261                                 file the main PID is always known. The
 262                                 guessing algorithm might come to
 263                                 incorrect conclusions if a daemon
 264                                 consists of more than one process. If
 265                                 the main PID cannot be determined,
 266                                 failure detection and automatic
 267                                 restarting of a service will not work
 268                                 reliably. Defaults to
 269                                 <option>yes</option>.</para>
 270                                 </listitem>
 271                         </varlistentry>
 272
 273                         <varlistentry>
 274                                 <term><varname>PIDFile=</varname></term>
 275
 276                                 <listitem><para>Takes an absolute file
 277                                 name pointing to the PID file of this
 278                                 daemon. Use of this option is
 279                                 recommended for services where
 280                                 <varname>Type=</varname> is set to
 281                                 <option>forking</option>. systemd will
 282                                 read the PID of the main process of
 283                                 the daemon after start-up of the
 284                                 service. systemd will not write to the
 285                                 file configured here.</para>
 286                                 </listitem>
 287                         </varlistentry>
 288
 289                         <varlistentry>
 290                                 <term><varname>BusName=</varname></term>
 291
 292                                 <listitem><para>Takes a D-Bus bus
 293                                 name, that this service is reachable
 294                                 as. This option is mandatory for
 295                                 services where
 296                                 <varname>Type=</varname> is set to
 297                                 <option>dbus</option>, but its use
 298                                 is otherwise recommended as well if
 299                                 the process takes a name on the D-Bus
 300                                 bus.</para>
 301                                 </listitem>
 302                         </varlistentry>
 303
 304                         <varlistentry>
 305                                 <term><varname>ExecStart=</varname></term>
 306                                 <listitem><para>Commands with their
 307                                 arguments that are executed when this
 308                                 service is started. For each of the
 309                                 specified commands, the first argument
 310                                 must be an absolute and literal path
 311                                 to an executable.</para>
 312
 313                                 <para>When <varname>Type</varname> is
 314                                 not <option>oneshot</option>, only one
 315                                 command may be given. When
 316                                 <varname>Type=oneshot</varname> is
 317                                 used, more than one command may be
 318                                 specified. Multiple command lines may
 319                                 be concatenated in a single directive,
 320                                 by separating them with semicolons
 321                                 (these semicolons must be passed as
 322                                 separate words). Alternatively, this
 323                                 directive may be specified more than
 324                                 once with the same effect. However,
 325                                 the latter syntax is not recommended
 326                                 for compatibility with parsers
 327                                 suitable for XDG
 328                                 <filename>.desktop</filename> files.
 329                                 Lone semicolons may be escaped as
 330                                 <literal>\;</literal>. If the empty
 331                                 string is assigned to this option, the
 332                                 list of commands to start is reset,
 333                                 prior assignments of this option will
 334                                 have no effect.</para>
 335
 336                                 <para>Each command line is split on
 337                                 whitespace, with the first item being
 338                                 the command to execute, and the
 339                                 subsequent items being the arguments.
 340                                 Double quotes ("...") and single
 341                                 quotes ('...') may be used, in which
 342                                 case everything until the next
 343                                 matching quote becomes part of the
 344                                 same argument. Quotes themselves are
 345                                 removed after parsing. In addition, a
 346                                 trailing backslash
 347                                 (<literal>\</literal>) may be used to
 348                                 merge lines. This syntax is intended
 349                                 to be very similar to shell syntax,
 350                                 but only the meta-characters and
 351                                 expansions described in the following
 352                                 paragraphs are understood.
 353                                 Specifically, redirection using
 354                                 <literal>&lt;</literal>,
 355                                 <literal>&lt;&lt;</literal>,
 356                                 <literal>&gt;</literal>, and
 357                                 <literal>&gt;&gt;</literal>, pipes
 358                                 using <literal>|</literal>, and
 359                                 running programs in the background
 360                                 using <literal>&amp;</literal>
 361                                 and <emphasis>other elements of shell
 362                                 syntax are not supported</emphasis>.
 363                                 </para>
 364
 365                                 <para>If more than one command is
 366                                 specified, the commands are invoked
 367                                 one by one sequentially in the order
 368                                 they appear in the unit file. If one
 369                                 of the commands fails (and is not
 370                                 prefixed with <literal>-</literal>),
 371                                 other lines are not executed and the
 372                                 unit is considered failed.</para>
 373
 374                                 <para>Unless
 375                                 <varname>Type=forking</varname> is
 376                                 set, the process started via this
 377                                 command line will be considered the
 378                                 main process of the daemon.</para>
 379
 380                                 <para>The command line accepts
 381                                 <literal>%</literal> specifiers as
 382                                 described in
 383                                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 384                                 Note that the first argument of the
 385                                 command line (i.e. the program to
 386                                 execute) may not include
 387                                 specifiers.</para>
 388
 389                                 <para>Basic environment variable
 390                                 substitution is supported. Use
 391                                 <literal>${FOO}</literal> as part of a
 392                                 word, or as a word of its own on the
 393                                 command line, in which case it will be
 394                                 replaced by the value of the
 395                                 environment variable including all
 396                                 whitespace it contains, resulting in a
 397                                 single argument.  Use
 398                                 <literal>$FOO</literal> as a separate
 399                                 word on the command line, in which
 400                                 case it will be replaced by the value
 401                                 of the environment variable split up
 402                                 at whitespace, resulting in zero or
 403                                 more arguments. To pass a literal dollar sign,
 404                                 use <literal>$$</literal>. Note that the first
 405                                 argument (i.e. the program to execute)
 406                                 may not be a variable.</para>
 407
 408                                 <para>Optionally, if the absolute file
 409                                 name is prefixed with
 410                                 <literal>@</literal>, the second token
 411                                 will be passed as
 412                                 <literal>argv[0]</literal> to the
 413                                 executed process, followed by the
 414                                 further arguments specified. If the
 415                                 absolute filename is prefixed with
 416                                 <literal>-</literal>, an exit code of
 417                                 the command normally considered a
 418                                 failure (i.e. non-zero exit status or
 419                                 abnormal exit due to signal) is ignored
 420                                 and considered success. If both
 421                                 <literal>-</literal> and
 422                                 <literal>@</literal> are used, they
 423                                 can appear in either order.</para>
 424
 425                                 <para>Note that this setting does not
 426                                 directly support shell command
 427                                 lines. If shell command lines are to
 428                                 be used, they need to be passed
 429                                 explicitly to a shell implementation
 430                                 of some kind. Example:</para>
 431                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
 432                                 </programlisting>
 433
 434                                 <para>Only select environment variables
 435                                 are set for executed commands. See
 436                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 437                                 </para>
 438
 439                                 <para>Example:</para>
 440                                 <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"
 441                                 </programlisting>
 442                                 <para>This will execute
 443                                 <command>/bin/echo</command> two
 444                                 times, each time with one argument,
 445                                 <literal>one</literal> and
 446                                 <literal>two two</literal>,
 447                                 respectively. Since two commands are
 448                                 specified
 449                                 <varname>Type=oneshot</varname> must
 450                                 be used.</para>
 451
 452                                 <para>Example:</para>
 453                                 <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
 454 /bin/ls
 455                                 </programlisting>
 456                                 <para>This will execute
 457                                 <command>/bin/echo</command> with five
 458                                 arguments: <literal>/</literal>,
 459                                 <literal>&gt;/dev/null</literal>,
 460                                 <literal>&amp;</literal>,
 461                                 <literal>;</literal>, and
 462                                 <literal>/bin/ls</literal>.</para>
 463
 464                                 <para>Example:</para>
 465                                 <programlisting>Environment="ONE=one" 'TWO=two two'
 466 ExecStart=/bin/echo $ONE $TWO ${TWO}
 467                                 </programlisting>
 468                                 <para>This will execute
 469                                 <command>/bin/echo</command> with four
 470                                 arguments: <literal>one</literal>,
 471                                 <literal>two</literal>,
 472                                 <literal>two</literal>, and
 473                                 <literal>two two</literal>.</para>
 474                               </listitem>
 475                         </varlistentry>
 476
 477                         <varlistentry>
 478                                 <term><varname>ExecStartPre=</varname></term>
 479                                 <term><varname>ExecStartPost=</varname></term>
 480                                 <listitem><para>Additional commands
 481                                 that are executed before or after
 482                                 the command in
 483                                 <varname>ExecStart=</varname>, respectively.
 484                                 Syntax is the same as for
 485                                 <varname>ExecStart=</varname>, except
 486                                 that multiple command lines are allowed
 487                                 and the commands are executed one
 488                                 after the other, serially.</para>
 489
 490                                 <para>If any of those commands (not
 491                                 prefixed with <literal>-</literal>)
 492                                 fail, the rest are not executed and
 493                                 the unit is considered failed.</para>
 494                                 </listitem>
 495                         </varlistentry>
 496
 497                         <varlistentry>
 498                                 <term><varname>ExecReload=</varname></term>
 499                                 <listitem><para>Commands to execute to
 500                                 trigger a configuration reload in the
 501                                 service. This argument takes multiple
 502                                 command lines, following the same
 503                                 scheme as described for
 504                                 <varname>ExecStart=</varname>
 505                                 above. Use of this setting is
 506                                 optional. Specifier and environment
 507                                 variable substitution is supported
 508                                 here following the same scheme as for
 509                                 <varname>ExecStart=</varname>.</para>
 510
 511                                 <para>One additional special
 512                                 environment variables is set: if known
 513                                 <varname>$MAINPID</varname> is set to
 514                                 the main process of the daemon, and
 515                                 may be used for command lines like the
 516                                 following:</para>
 517
 518                                 <programlisting>/bin/kill -HUP $MAINPID</programlisting>
 519                                 </listitem>
 520                         </varlistentry>
 521
 522                         <varlistentry>
 523                                 <term><varname>ExecStop=</varname></term>
 524                                 <listitem><para>Commands to execute to
 525                                 stop the service started via
 526                                 <varname>ExecStart=</varname>. This
 527                                 argument takes multiple command lines,
 528                                 following the same scheme as described
 529                                 for <varname>ExecStart=</varname>
 530                                 above. Use of this setting is
 531                                 optional. All processes remaining for
 532                                 a service after the commands
 533                                 configured in this option are run are
 534                                 terminated according to the
 535                                 <varname>KillMode=</varname> setting
 536                                 (see
 537                                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
 538                                 this option is not specified, the
 539                                 process is terminated right-away when
 540                                 service stop is requested. Specifier
 541                                 and environment variable substitution
 542                                 is supported (including
 543                                 <varname>$MAINPID</varname>, see
 544                                 above).</para></listitem>
 545                         </varlistentry>
 546
 547                         <varlistentry>
 548                                 <term><varname>ExecStopPost=</varname></term>
 549                                 <listitem><para>Additional commands
 550                                 that are executed after the service
 551                                 was stopped. This includes cases where
 552                                 the commands configured in
 553                                 <varname>ExecStop=</varname> were used,
 554                                 where the service does not have any
 555                                 <varname>ExecStop=</varname> defined, or
 556                                 where the service exited unexpectedly. This
 557                                 argument takes multiple command lines,
 558                                 following the same scheme as described
 559                                 for <varname>ExecStart</varname>. Use
 560                                 of these settings is
 561                                 optional. Specifier and environment
 562                                 variable substitution is
 563                                 supported.</para></listitem>
 564                         </varlistentry>
 565
 566                         <varlistentry>
 567                                 <term><varname>RestartSec=</varname></term>
 568                                 <listitem><para>Configures the time to
 569                                 sleep before restarting a service (as
 570                                 configured with
 571                                 <varname>Restart=</varname>). Takes a
 572                                 unit-less value in seconds, or a time
 573                                 span value such as "5min
 574                                 20s". Defaults to
 575                                 100ms.</para></listitem>
 576                         </varlistentry>
 577
 578                         <varlistentry>
 579                                 <term><varname>TimeoutStartSec=</varname></term>
 580                                 <listitem><para>Configures the time to
 581                                 wait for start-up. If a
 582                                 daemon service does not signal
 583                                 start-up completion within the
 584                                 configured time, the service will be
 585                                 considered failed and be shut down
 586                                 again.
 587                                 Takes a unit-less value in seconds, or a
 588                                 time span value such as "5min
 589                                 20s". Pass 0 to disable the timeout
 590                                 logic. Defaults to <varname>TimeoutStartSec=</varname> from the
 591                                 manager configuration file, except when
 592                                 <varname>Type=oneshot</varname> is
 593                                 used, in which case the timeout
 594                                 is disabled by default.
 595                                 </para></listitem>
 596                         </varlistentry>
 597
 598                         <varlistentry>
 599                                 <term><varname>TimeoutStopSec=</varname></term>
 600                                 <listitem><para>Configures the time to
 601                                 wait for stop. If a service is asked
 602                                 to stop but does not terminate in the
 603                                 specified time, it will be terminated
 604                                 forcibly via <constant>SIGTERM</constant>, and after
 605                                 another delay of this time with
 606                                 <constant>SIGKILL</constant> (See
 607                                 <varname>KillMode=</varname>
 608                                 in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 609                                 Takes a unit-less value in seconds, or a
 610                                 time span value such as "5min
 611                                 20s". Pass 0 to disable the timeout
 612                                 logic. Defaults to <varname>TimeoutStartSec=</varname> from the
 613                                 manager configuration file.
 614                                 </para></listitem>
 615                         </varlistentry>
 616
 617                         <varlistentry>
 618                                 <term><varname>TimeoutSec=</varname></term>
 619                                 <listitem><para>A shorthand for configuring
 620                                 both <varname>TimeoutStartSec=</varname>
 621                                 and <varname>TimeoutStopSec=</varname>
 622                                 to the specified value.
 623                                 </para></listitem>
 624                         </varlistentry>
 625
 626                         <varlistentry>
 627                                 <term><varname>WatchdogSec=</varname></term>
 628                                 <listitem><para>Configures the
 629                                 watchdog timeout for a service. The
 630                                 watchdog is activated when the start-up is
 631                                 completed. The service must call
 632                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 633                                 regularly with "WATCHDOG=1" (i.e. the
 634                                 "keep-alive ping"). If the time
 635                                 between two such calls is larger than
 636                                 the configured time, then the service
 637                                 is placed in a failure state. By
 638                                 setting <varname>Restart=</varname> to
 639                                 <option>on-failure</option> or
 640                                 <option>always</option>, the service
 641                                 will be automatically restarted. The
 642                                 time configured here will be passed to
 643                                 the executed service process in the
 644                                 <varname>WATCHDOG_USEC=</varname>
 645                                 environment variable. This allows
 646                                 daemons to automatically enable the
 647                                 keep-alive pinging logic if watchdog
 648                                 support is enabled for the service. If
 649                                 this option is used,
 650                                 <varname>NotifyAccess=</varname> (see
 651                                 below) should be set to open access to
 652                                 the notification socket provided by
 653                                 systemd. If
 654                                 <varname>NotifyAccess=</varname> is
 655                                 not set, it will be implicitly set to
 656                                 <option>main</option>. Defaults to 0,
 657                                 which disables this
 658                                 feature.</para></listitem>
 659                         </varlistentry>
 660
 661                         <varlistentry>
 662                                 <term><varname>Restart=</varname></term>
 663                                 <listitem><para>Configures whether the
 664                                 service shall be restarted when the
 665                                 service process exits, is killed,
 666                                 or a timeout is reached. The service
 667                                 process may be the main service
 668                                 process, but also one of the processes
 669                                 specified with
 670                                 <varname>ExecStartPre=</varname>,
 671                                 <varname>ExecStartPost=</varname>,
 672                                 <varname>ExecStopPre=</varname>,
 673                                 <varname>ExecStopPost=</varname>, or
 674                                 <varname>ExecReload=</varname>.
 675                                 When the death of the process is a
 676                                 result of systemd operation (e.g. service
 677                                 stop or restart), the service will not be
 678                                 restarted. Timeouts include missing
 679                                 the watchdog "keep-alive ping"
 680                                 deadline and a service start, reload,
 681                                 and stop operation timeouts.</para>
 682
 683                                 <para>Takes one of
 684                                 <option>no</option>,
 685                                 <option>on-success</option>,
 686                                 <option>on-failure</option>,
 687                                 <option>on-watchdog</option>,
 688                                 <option>on-abort</option>, or
 689                                 <option>always</option>. If set to
 690                                 <option>no</option> (the default), the
 691                                 service will not be restarted. If set to
 692                                 <option>on-success</option>, it will be
 693                                 restarted only when the service process
 694                                 exits cleanly.
 695                                 In this context, a clean exit means
 696                                 an exit code of 0, or one of the signals
 697                                 <constant>SIGHUP</constant>, <constant>SIGINT</constant>, <constant>SIGTERM</constant>, or <constant>SIGPIPE</constant>, and
 698                                 additionally, exit statuses and signals
 699                                 specified in <varname>SuccessExitStatus=</varname>.
 700                                 If set to <option>on-failure</option>,
 701                                 the service will be restarted when the
 702                                 process exits with an nonzero exit code,
 703                                 is terminated by a signal (including on
 704                                 core dump), when an operation (such as
 705                                 service reload) times out, and when the
 706                                 configured watchdog timeout is triggered.
 707                                 If set to
 708                                 <option>on-abort</option>, the service
 709                                 will be restarted only if the service
 710                                 process exits due to an uncaught
 711                                 signal not specified as a clean exit
 712                                 status.
 713                                 If set to
 714                                 <option>on-watchdog</option>, the service
 715                                 will be restarted only if the watchdog
 716                                 timeout for the service expires.
 717                                 If set to
 718                                 <option>always</option>, the service
 719                                 will be restarted regardless whether
 720                                 it exited cleanly or not, got
 721                                 terminated abnormally by a signal or
 722                                 hit a timeout.</para>
 723
 724                                 <para>In addition to the above settings,
 725                                 the service will not be restarted if the
 726                                 exit code or signal is specified in
 727                                 <varname>RestartPreventExitStatus=</varname>
 728                                 (see below).</para></listitem>
 729                         </varlistentry>
 730
 731                         <varlistentry>
 732                                 <term><varname>SuccessExitStatus=</varname></term>
 733                                 <listitem><para>Takes a list of exit
 734                                 status definitions that when returned
 735                                 by the main service process will be
 736                                 considered successful termination, in
 737                                 addition to the normal successful exit
 738                                 code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
 739                                 <constant>SIGTERM</constant> and <constant>SIGPIPE</constant>. Exit status
 740                                 definitions can either be numeric exit
 741                                 codes or termination signal names,
 742                                 separated by spaces. Example:
 743                                 <literal>SuccessExitStatus=1 2 8
 744                                 <constant>SIGKILL</constant></literal>, ensures that exit
 745                                 codes 1, 2, 8 and the termination
 746                                 signal <constant>SIGKILL</constant> are considered clean
 747                                 service terminations. This option may
 748                                 appear more than once in which case
 749                                 the list of successful exit statuses
 750                                 is merged. If the empty string is
 751                                 assigned to this option, the list is
 752                                 reset, all prior assignments of this
 753                                 option will have no
 754                                 effect.</para></listitem>
 755                         </varlistentry>
 756
 757                         <varlistentry>
 758                                 <term><varname>RestartPreventExitStatus=</varname></term>
 759                                 <listitem><para>Takes a list of exit
 760                                 status definitions that when returned
 761                                 by the main service process will
 762                                 prevent automatic service restarts
 763                                 regardless of the restart setting
 764                                 configured with
 765                                 <varname>Restart=</varname>. Exit
 766                                 status definitions can either be
 767                                 numeric exit codes or termination
 768                                 signal names, and are separated by
 769                                 spaces. Defaults to the empty list, so
 770                                 that by default no exit status is
 771                                 excluded from the configured restart
 772                                 logic. Example:
 773                                 <literal>RestartPreventExitStatus=1 6
 774                                 SIGABRT</literal>, ensures that exit
 775                                 codes 1 and 6 and the termination
 776                                 signal SIGABRT will not result in
 777                                 automatic service restarting. This
 778                                 option may appear more than once in
 779                                 which case the list of restart preventing
 780                                 statuses is merged. If the empty
 781                                 string is assigned to this option, the
 782                                 list is reset, all prior assignments
 783                                 of this option will have no
 784                                 effect.</para></listitem>
 785                         </varlistentry>
 786
 787                         <varlistentry>
 788                                 <term><varname>PermissionsStartOnly=</varname></term>
 789                                 <listitem><para>Takes a boolean
 790                                 argument. If true, the permission
 791                                 related execution options as
 792                                 configured with
 793                                 <varname>User=</varname> and similar
 794                                 options (see
 795                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 796                                 for more information) are only applied
 797                                 to the process started with
 798                                 <varname>ExecStart=</varname>, and not
 799                                 to the various other
 800                                 <varname>ExecStartPre=</varname>,
 801                                 <varname>ExecStartPost=</varname>,
 802                                 <varname>ExecReload=</varname>,
 803                                 <varname>ExecStop=</varname>,
 804                                 <varname>ExecStopPost=</varname>
 805                                 commands. If false, the setting is
 806                                 applied to all configured commands the
 807                                 same way. Defaults to
 808                                 false.</para></listitem>
 809                         </varlistentry>
 810
 811                         <varlistentry>
 812                                 <term><varname>RootDirectoryStartOnly=</varname></term>
 813                                 <listitem><para>Takes a boolean
 814                                 argument. If true, the root directory
 815                                 as configured with the
 816                                 <varname>RootDirectory=</varname>
 817                                 option (see
 818                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 819                                 for more information) is only applied
 820                                 to the process started with
 821                                 <varname>ExecStart=</varname>, and not
 822                                 to the various other
 823                                 <varname>ExecStartPre=</varname>,
 824                                 <varname>ExecStartPost=</varname>,
 825                                 <varname>ExecReload=</varname>,
 826                                 <varname>ExecStop=</varname>,
 827                                 <varname>ExecStopPost=</varname>
 828                                 commands. If false, the setting is
 829                                 applied to all configured commands the
 830                                 same way. Defaults to
 831                                 false.</para></listitem>
 832                         </varlistentry>
 833
 834                         <varlistentry>
 835                                 <term><varname>NonBlocking=</varname></term>
 836                                 <listitem><para>Set O_NONBLOCK flag
 837                                 for all file descriptors passed via
 838                                 socket-based activation. If true, all
 839                                 file descriptors >= 3 (i.e. all except
 840                                 STDIN/STDOUT/STDERR) will have
 841                                 the O_NONBLOCK flag set and hence are in
 842                                 non-blocking mode. This option is only
 843                                 useful in conjunction with a socket
 844                                 unit, as described in
 845                                 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
 846                                 to false.</para></listitem>
 847                         </varlistentry>
 848
 849                         <varlistentry>
 850                                 <term><varname>NotifyAccess=</varname></term>
 851                                 <listitem><para>Controls access to the
 852                                 service status notification socket, as
 853                                 accessible via the
 854                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 855                                 call. Takes one of
 856                                 <option>none</option> (the default),
 857                                 <option>main</option> or
 858                                 <option>all</option>. If
 859                                 <option>none</option>, no daemon status
 860                                 updates are accepted from the service
 861                                 processes, all status update messages
 862                                 are ignored. If <option>main</option>,
 863                                 only service updates sent from the
 864                                 main process of the service are
 865                                 accepted. If <option>all</option>, all
 866                                 services updates from all members of
 867                                 the service's control group are
 868                                 accepted. This option should be set to
 869                                 open access to the notification socket
 870                                 when using
 871                                 <varname>Type=notify</varname> or
 872                                 <varname>WatchdogSec=</varname> (see
 873                                 above). If those options are used but
 874                                 <varname>NotifyAccess=</varname> is not
 875                                 configured, it will be implicitly set
 876                                 to
 877                                 <option>main</option>.</para></listitem>
 878                         </varlistentry>
 879
 880                         <varlistentry>
 881                                 <term><varname>Sockets=</varname></term>
 882                                 <listitem><para>Specifies the name of
 883                                 the socket units this service shall
 884                                 inherit the sockets from when the
 885                                 service is started. Normally it
 886                                 should not be necessary to use this
 887                                 setting as all sockets whose unit
 888                                 shares the same name as the service
 889                                 (ignoring the different suffix of course)
 890                                 are passed to the spawned
 891                                 process.</para>
 892
 893                                 <para>Note that the same socket may be
 894                                 passed to multiple processes at the
 895                                 same time. Also note that a different
 896                                 service may be activated on incoming
 897                                 traffic than inherits the sockets. Or
 898                                 in other words: the
 899                                 <varname>Service=</varname> setting of
 900                                 <filename>.socket</filename> units
 901                                 does not have to match the inverse of
 902                                 the <varname>Sockets=</varname>
 903                                 setting of the
 904                                 <filename>.service</filename> it
 905                                 refers to.</para>
 906
 907                                 <para>This option may appear more than
 908                                 once, in which case the list of socket
 909                                 units is merged. If the empty string
 910                                 is assigned to this option, the list of
 911                                 sockets is reset, all prior uses of
 912                                 this setting will have no
 913                                 effect.</para></listitem>
 914                         </varlistentry>
 915
 916                         <varlistentry>
 917                                 <term><varname>StartLimitInterval=</varname></term>
 918                                 <term><varname>StartLimitBurst=</varname></term>
 919
 920                                 <listitem><para>Configure service
 921                                 start rate limiting. By default,
 922                                 services which are started more often
 923                                 than 5 times within 10s are not
 924                                 permitted to start any more times
 925                                 until the 10s interval ends. With
 926                                 these two options, this rate limiting
 927                                 may be modified. Use
 928                                 <varname>StartLimitInterval=</varname>
 929                                 to configure the checking interval (defaults to
 930                                 <varname>DefaultStartLimitInterval=</varname> in
 931                                 manager configuration file, set to 0 to disable
 932                                 any kind of rate limiting). Use
 933                                 <varname>StartLimitBurst=</varname> to
 934                                 configure how many starts per interval
 935                                 are allowed (defaults to
 936                                 <varname>DefaultStartLimitBurst=</varname> in
 937                                 manager configuration file). These
 938                                 configuration options are particularly
 939                                 useful in conjunction with
 940                                 <varname>Restart=</varname>, however
 941                                 apply to all kinds of starts
 942                                 (including manual), not just those
 943                                 triggered by the
 944                                 <varname>Restart=</varname> logic.
 945                                 Note that units which are configured
 946                                 for <varname>Restart=</varname> and
 947                                 which reach the start limit are not
 948                                 attempted to be restarted anymore,
 949                                 however they may still be restarted
 950                                 manually at a later point from which
 951                                 point on the restart logic is again
 952                                 activated. Note that
 953                                 <command>systemctl
 954                                 reset-failed</command> will cause the
 955                                 restart rate counter for a service to
 956                                 be flushed, which is useful if the
 957                                 administrator wants to manually start
 958                                 a service and the start limit
 959                                 interferes with
 960                                 that.</para></listitem>
 961                         </varlistentry>
 962
 963                         <varlistentry>
 964                                 <term><varname>StartLimitAction=</varname></term>
 965
 966                                 <listitem><para>Configure the action
 967                                 to take if the rate limit configured
 968                                 with
 969                                 <varname>StartLimitInterval=</varname>
 970                                 and
 971                                 <varname>StartLimitBurst=</varname> is
 972                                 hit. Takes one of
 973                                 <option>none</option>,
 974                                 <option>reboot</option>,
 975                                 <option>reboot-force</option> or
 976                                 <option>reboot-immediate</option>. If
 977                                 <option>none</option> is set,
 978                                 hitting the rate limit will trigger no
 979                                 action besides that the start will not
 980                                 be
 981                                 permitted. <option>reboot</option>
 982                                 causes a reboot following the normal
 983                                 shutdown procedure (i.e. equivalent to
 984                                 <command>systemctl reboot</command>),
 985                                 <option>reboot-force</option> causes
 986                                 an forced reboot which will terminate
 987                                 all processes forcibly but should
 988                                 cause no dirty file systems on reboot
 989                                 (i.e. equivalent to <command>systemctl
 990                                 reboot -f</command>) and
 991                                 <option>reboot-immediate</option>
 992                                 causes immediate execution of the
 993                                 <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 994                                 system call, which might result in
 995                                 data loss.  Defaults to
 996                                 <option>none</option>.</para></listitem>
 997                         </varlistentry>
 998
 999                 </variablelist>
1000
1001                 <para>Check
1002                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1003                 and
1004                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1005                 for more settings.</para>
1006
1007         </refsect1>
1008
1009         <refsect1>
1010                 <title>Compatibility Options</title>
1011
1012                 <para>The following options are also available in the
1013                 <literal>[Service]</literal> section, but exist purely
1014                 for compatibility reasons and should not be used in
1015                 newly written service files.</para>
1016
1017                 <variablelist class='unit-directives'>
1018                         <varlistentry>
1019                                 <term><varname>SysVStartPriority=</varname></term>
1020                                 <listitem><para>Set the SysV start
1021                                 priority to use to order this service
1022                                 in relation to SysV services lacking
1023                                 LSB headers. This option is only
1024                                 necessary to fix ordering in relation
1025                                 to legacy SysV services, that have no
1026                                 ordering information encoded in the
1027                                 script headers. As such it should only
1028                                 be used as temporary compatibility
1029                                 option, and not be used in new unit
1030                                 files. Almost always it is a better
1031                                 choice to add explicit ordering
1032                                 directives via
1033                                 <varname>After=</varname> or
1034                                 <varname>Before=</varname>,
1035                                 instead. For more details see
1036                                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
1037                                 used, pass an integer value in the
1038                                 range 0-99.</para></listitem>
1039                         </varlistentry>
1040
1041                 </variablelist>
1042         </refsect1>
1043
1044         <refsect1>
1045                   <title>See Also</title>
1046                   <para>
1047                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1048                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1049                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1050                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1051                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1052                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1053                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1054                   </para>
1055         </refsect1>
1056
1057 </refentry>