systemd.service.xml 48.7 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
<?xml version='1.0'?> <!--*-nxml-*-->
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
12 13
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
14 15 16 17 18
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  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 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd.service">
        <refentryinfo>
                <title>systemd.service</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd.service</refentrytitle>
                <manvolnum>5</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd.service</refname>
                <refpurpose>systemd service configuration files</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <para><filename>systemd.service</filename></para>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

57
                <para>A unit configuration file whose name ends in
58 59 60
                <filename>.service</filename> encodes information
                about a process controlled and supervised by
                systemd.</para>
61 62 63 64 65

                <para>This man page lists the configuration options
                specific to this unit type. See
                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for the common options of all unit configuration
66
                files. The common configuration items are configured
67 68 69 70
                in the generic <literal>[Unit]</literal> and
                <literal>[Install]</literal> sections. The service
                specific configuration options are configured in the
                <literal>[Service]</literal> section.</para>
71

72 73 74 75
                <para>Additional options are listed in
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which define the execution environment the commands
                are executed in.</para>
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90

                <para>Unless <varname>DefaultDependencies=</varname>
                is set to <option>false</option>, service units will
                implicitly have dependencies of type
                <varname>Requires=</varname> and
                <varname>After=</varname> on
                <filename>basic.target</filename> as well as
                dependencies of type <varname>Conflicts=</varname> and
                <varname>Before=</varname> on
                <filename>shutdown.target</filename>. These ensure
                that normal service units pull in basic system
                initialization, and are terminated cleanly prior to
                system shutdown. Only services involved with early
                boot or late system shutdown should disable this
                option.</para>
Lennart Poettering's avatar
Lennart Poettering committed
91 92 93 94 95 96 97 98

                <para>If a service is requested under a certain name
                but no unit configuration file is found, systemd looks
                for a SysV init script by the same name (with the
                <filename>.service</filename> suffix removed) and
                dynamically creates a service unit from that
                script. This is useful for compatibility with
                SysV.</para>
99 100 101 102 103
        </refsect1>

        <refsect1>
                <title>Options</title>

104 105 106 107 108 109
                <para>Service files must include a
                <literal>[Service]</literal> section, which carries
                information about the service and the process it
                supervises. A number of options that may be used in
                this section are shared with other unit types. These
                options are documented in
110
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
111 112
                options specific to the <literal>[Service]</literal>
                section of service units are the following:</para>
113

114 115 116
                <variablelist>
                        <varlistentry>
                                <term><varname>Type=</varname></term>
117 118 119 120 121

                                <listitem><para>Configures the process
                                start-up type for this service
                                unit. One of <option>simple</option>,
                                <option>forking</option>,
122
                                <option>oneshot</option>,
123
                                <option>dbus</option>,
124 125
                                <option>notify</option> or
                                <option>idle</option>.</para>
126 127 128

                                <para>If set to
                                <option>simple</option> (the default
129 130 131
                                value if <varname>BusName=</varname>
                                is not specified) it is expected that
                                the process configured with
132 133
                                <varname>ExecStart=</varname> is the
                                main process of the service. In this
134 135 136 137 138 139 140 141
                                mode, if the process offers
                                functionality to other processes on
                                the system its communication channels
                                should be installed before the daemon
                                is started up (e.g. sockets set up by
                                systemd, via socket activation), as
                                systemd will immediately proceed
                                starting follow-up units.</para>
142 143 144 145 146

                                <para>If set to
                                <option>forking</option> it is
                                expected that the process configured
                                with <varname>ExecStart=</varname>
147 148 149 150 151 152 153 154
                                will call <function>fork()</function>
                                as part of its start-up. The parent process is
                                expected to exit when start-up is
                                complete and all communication
                                channels set up. The child continues
                                to run as the main daemon
                                process. This is the behaviour of
                                traditional UNIX daemons. If this
155 156 157 158 159 160 161 162 163 164
                                setting is used, it is recommended to
                                also use the
                                <varname>PIDFile=</varname> option, so
                                that systemd can identify the main
                                process of the daemon. systemd will
                                proceed starting follow-up units as
                                soon as the parent process
                                exits.</para>

                                <para>Behaviour of
165
                                <option>oneshot</option> is similar
166 167 168
                                to <option>simple</option>, however
                                it is expected that the process has to
                                exit before systemd starts follow-up
169
                                units. <varname>RemainAfterExit=</varname>
170 171 172 173 174
                                is particularly useful for this type
                                of service.</para>

                                <para>Behaviour of
                                <option>dbus</option> is similar to
175 176
                                <option>simple</option>, however it is
                                expected that the daemon acquires a
177 178 179 180 181
                                name on the D-Bus bus, as configured
                                by
                                <varname>BusName=</varname>. systemd
                                will proceed starting follow-up units
                                after the D-Bus bus name has been
182
                                acquired. Service units with this
183
                                option configured implicitly gain
184
                                dependencies on the
185
                                <filename>dbus.socket</filename>
186 187 188
                                unit. This type is the default if
                                <varname>BusName=</varname> is
                                specified.</para>
189 190 191 192 193 194 195 196 197 198 199 200

                                <para>Behaviour of
                                <option>notify</option> is similar to
                                <option>simple</option>, however it is
                                expected that the daemon sends a
                                notification message via
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                or an equivalent call when it finished
                                starting up. systemd will proceed
                                starting follow-up units after this
                                notification message has been sent. If
                                this option is used
201
                                <varname>NotifyAccess=</varname> (see
202
                                below) should be set to open access to
203
                                the notification socket provided by
204
                                systemd. If
205 206
                                <varname>NotifyAccess=</varname> is
                                not set, it will be implicitly set to
207
                                <option>main</option>.</para>
208 209 210

                                <para>Behaviour of
                                <option>idle</option> is very similar
Kay Sievers's avatar
Kay Sievers committed
211
                                to <option>simple</option>, however
212 213 214 215 216 217
                                actual execution of a the service
                                binary is delayed until all jobs are
                                dispatched. This may be used to avoid
                                interleaving of output of shell
                                services with the status output on the
                                console.</para>
218 219
                                </listitem>
                        </varlistentry>
220

221
                        <varlistentry>
222
                                <term><varname>RemainAfterExit=</varname></term>
223 224 225 226 227 228

                                <listitem><para>Takes a boolean value
                                that specifies whether the service
                                shall be considered active even when
                                all its processes exited. Defaults to
                                <option>no</option>.</para>
229
                                </listitem>
230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
                        </varlistentry>

                        <varlistentry>
                                <term><varname>GuessMainPID=</varname></term>

                                <listitem><para>Takes a boolean value
                                that specifies whether systemd should
                                try to guess the main PID of a service
                                should if it cannot be determined
                                reliably. This option is ignored
                                unless <option>Type=forking</option>
                                is set and <option>PIDFile=</option>
                                is unset because for the other types
                                or with an explicitly configured PID
                                file the main PID is always known. The
                                guessing algorithm might come to
                                incorrect conclusions if a daemon
                                consists of more than one process. If
                                the main PID cannot be determined
                                failure detection and automatic
                                restarting of a service will not work
                                reliably. Defaults to
                                <option>yes</option>.</para>
                                </listitem>
254 255 256 257
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PIDFile=</varname></term>
258 259 260 261 262 263

                                <listitem><para>Takes an absolute file
                                name pointing to the PID file of this
                                daemon. Use of this option is
                                recommended for services where
                                <varname>Type=</varname> is set to
264 265 266 267 268
                                <option>forking</option>. systemd will
                                read the PID of the main process of
                                the daemon after start-up of the
                                service. systemd will not write to the
                                file configured here.</para>
269 270 271 272 273
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>BusName=</varname></term>
274 275 276 277 278 279 280 281 282 283

                                <listitem><para>Takes a D-Bus bus
                                name, where this service is reachable
                                as. This option is mandatory for
                                services where
                                <varname>Type=</varname> is set to
                                <option>dbus</option>, but its use
                                is otherwise recommended as well if
                                the process takes a name on the D-Bus
                                bus.</para>
284 285 286 287 288
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStart=</varname></term>
289 290 291 292 293 294 295 296
                                <listitem><para>Takes a command line
                                that is executed when this service
                                shall be started up. The first token
                                of the command line must be an
                                absolute file name, then followed by
                                arguments for the process. It is
                                mandatory to set this option for all
                                services. This option may not be
297 298 299 300 301 302 303 304 305 306 307 308
                                specified more than once, except when
                                <varname>Type=oneshot</varname> is
                                used in which case more than one
                                <varname>ExecStart=</varname> line is
                                accepted which are then invoked one by
                                one, sequentially in the order they
                                appear in the unit file.</para>

                                <para>Optionally, if the absolute file
                                name is prefixed with
                                <literal>@</literal>, the second token
                                will be passed as
309 310
                                <literal>argv[0]</literal> to the
                                executed process, followed by the
311 312
                                further arguments specified. If the
                                first token is prefixed with
313
                                <literal>-</literal> an exit code of
314
                                the command normally considered a
315
                                failure (i.e. non-zero exit status or
316
                                abnormal exit due to signal) is ignored
317 318 319
                                and considered success. If both
                                <literal>-</literal> and
                                <literal>@</literal> are used for the
320
                                same command the former must precede
321
                                the latter. Unless
322 323 324 325 326 327
                                <varname>Type=forking</varname> is
                                set, the process started via this
                                command line will be considered the
                                main process of the daemon. The
                                command line accepts % specifiers as
                                described in
328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>

                                <para>On top of that basic environment
                                variable substitution is
                                supported. Use
                                <literal>${FOO}</literal> as part of a
                                word, or as word of its own on the
                                command line, in which case it will be
                                replaced by the value of the
                                environment variable including all
                                whitespace it contains, resulting in a
                                single argument.  Use
                                <literal>$FOO</literal> as a separate
                                word on the command line, in which
                                case it will be replaced by the value
                                of the environment variable split up
                                at whitespace, resulting in no or more
                                arguments. Note that the first
                                argument (i.e. the program to execute)
                                may not be a variable, and must be a
                                literal and absolute path
                                name.</para></listitem>
350 351 352 353 354 355 356 357
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStartPre=</varname></term>
                                <term><varname>ExecStartPost=</varname></term>
                                <listitem><para>Additional commands
                                that are executed before (resp. after)
                                the command in
358 359
                                <varname>ExecStart=</varname>. Multiple
                                command lines may be concatenated in a
360
                                single directive, by separating them
361
                                by semicolons (these semicolons must
362
                                be passed as separate words). In that
363 364 365 366
                                case, the commands are executed one
                                after the other,
                                serially. Alternatively, these
                                directives may be specified more than
367
                                once with the same effect. However,
368 369 370 371 372
                                the latter syntax is not recommended
                                for compatibility with parsers
                                suitable for XDG
                                <filename>.desktop</filename> files.
                                Use of these settings is
373 374 375
                                optional. Specifier and environment
                                variable substitution is
                                supported.</para></listitem>
376 377 378 379 380 381
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecReload=</varname></term>
                                <listitem><para>Commands to execute to
                                trigger a configuration reload in the
382 383 384 385 386
                                service. This argument takes multiple
                                command lines, following the same
                                scheme as pointed out for
                                <varname>ExecStartPre=</varname>
                                above. Use of this setting is
387 388 389 390 391 392 393 394 395 396
                                optional. Specifier and environment
                                variable substitution is supported
                                here following the same scheme as for
                                <varname>ExecStart=</varname>. One
                                special environment variable is set:
                                if known <literal>$MAINPID</literal> is
                                set to the main process of the
                                daemon, and may be used for command
                                lines like the following:
                                <command>/bin/kill -HUP
397
                                $MAINPID</command>.</para></listitem>
398 399 400 401 402 403
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStop=</varname></term>
                                <listitem><para>Commands to execute to
                                stop the service started via
404 405 406 407 408 409
                                <varname>ExecStart=</varname>. This
                                argument takes multiple command lines,
                                following the same scheme as pointed
                                out for
                                <varname>ExecStartPre=</varname>
                                above. Use of this setting is
410 411 412 413 414 415 416 417
                                optional. All processes remaining for
                                a service after the commands
                                configured in this option are run are
                                terminated according to the
                                <varname>KillMode=</varname> setting
                                (see below). If this option is not
                                specified the process is terminated
                                right-away when service stop is
418 419 420
                                requested. Specifier and environment
                                variable substitution is supported
                                (including
421
                                <literal>$MAINPID</literal>, see
422
                                above).</para></listitem>
423 424 425 426 427 428 429 430
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStopPost=</varname></term>
                                <listitem><para>Additional commands
                                that are executed after the service
                                was stopped using the commands
                                configured in
431 432 433 434 435 436
                                <varname>ExecStop=</varname>. This
                                argument takes multiple command lines,
                                following the same scheme as pointed
                                out for
                                <varname>ExecStartPre</varname>. Use
                                of these settings is
437 438 439
                                optional. Specifier and environment
                                variable substitution is
                                supported.</para></listitem>
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RestartSec=</varname></term>
                                <listitem><para>Configures the time to
                                sleep before restarting a service (as
                                configured with
                                <varname>Restart=</varname>). Takes a
                                unit-less value in seconds, or a time
                                span value such as "5min
                                20s". Defaults to
                                100ms.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TimeoutSec=</varname></term>
                                <listitem><para>Configures the time to
                                wait for start-up and stop. If a
                                daemon service does not signal
                                start-up completion within the
                                configured time the service will be
                                considered failed and be shut down
                                again. If a service is asked to stop
                                but does not terminate in the
                                specified time it will be terminated
                                forcibly via SIGTERM, and after
                                another delay of this time with
                                SIGKILL. (See
468
                                <varname>KillMode=</varname>
469 470 471 472
                                below.) Takes a unit-less value in seconds, or a
                                time span value such as "5min
                                20s". Pass 0 to disable the timeout
                                logic. Defaults to
473 474 475
                                90s, except when <varname>Type=oneshot</varname> is
                                used in which case the timeout
                                is disabled by default.</para></listitem>
476 477
                        </varlistentry>

478 479
                        <varlistentry>
                                <term><varname>WatchdogSec=</varname></term>
480 481 482 483
                                <listitem><para>Configures the
                                watchdog timeout for a service. This
                                is activated when the start-up is
                                completed. The service must call
484
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
485 486 487 488 489
                                regularly with "WATCHDOG=1". If the
                                time between two such calls is larger
                                than the configured time then the
                                service is placed in a failure
                                state. By setting
Lennart Poettering's avatar
Lennart Poettering committed
490
                                <varname>Restart=</varname>
491
                                to <option>on-failure</option> or
492 493 494 495 496
                                <option>always</option> the service
                                will be automatically restarted. The
                                time configured here will be passed to
                                the executed service process in the
                                <varname>WATCHDOG_USEC=</varname>
497 498 499 500 501 502 503 504 505
                                environment variable. If
                                this option is used
                                <varname>NotifyAccess=</varname> (see
                                below) should be set to open access to
                                the notification socket provided by
                                systemd. If
                                <varname>NotifyAccess=</varname> is not
                                set, it will be implicitly set to
                                <option>main</option>. Defaults to 0,
506 507
                                which disables this
                                feature.</para></listitem>
508 509
                        </varlistentry>

510 511 512
                        <varlistentry>
                                <term><varname>Restart=</varname></term>
                                <listitem><para>Configures whether the
513
                                main service process shall be
Andrew Edmunds's avatar
Andrew Edmunds committed
514
                                restarted when it exits. Takes one of
515
                                <option>no</option>,
516 517 518 519 520 521 522 523 524 525 526 527
                                <option>on-success</option>,
                                <option>on-failure</option>,
                                <option>on-abort</option> or
                                <option>always</option>. If set to
                                <option>no</option> (the default) the
                                service will not be restarted when it
                                exits. If set to
                                <option>on-success</option> it will be
                                restarted only when it exited cleanly,
                                i.e. terminated with an exit code of
                                0. If set to
                                <option>on-failure</option> it will be
528
                                restarted only when it exited with an
529 530 531 532 533
                                exit code not equalling 0, when
                                terminated by a signal, when an
                                operation times out or when the
                                configured watchdog timeout is
                                triggered. If set to
534 535 536 537
                                <option>on-abort</option> it will be
                                restarted only if it exits due to
                                reception of an uncaught signal. If
                                set to <option>always</option> the
538
                                service will be restarted regardless
539
                                whether it exited cleanly or not,
540
                                got terminated abnormally by a
541
                                signal or hit a timeout.</para></listitem>
542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PermissionsStartOnly=</varname></term>
                                <listitem><para>Takes a boolean
                                argument. If true, the permission
                                related execution options as
                                configured with
                                <varname>User=</varname> and similar
                                options (see
                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for more information) are only applied
                                to the process started with
                                <varname>ExecStart=</varname>, and not
                                to the various other
                                <varname>ExecStartPre=</varname>,
                                <varname>ExecStartPost=</varname>,
                                <varname>ExecReload=</varname>,
                                <varname>ExecStop=</varname>,
                                <varname>ExecStopPost=</varname>
                                commands. If false, the setting is
                                applied to all configured commands the
                                same way. Defaults to
                                false.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RootDirectoryStartOnly=</varname></term>
                                <listitem><para>Takes a boolean
                                argument. If true, the root directory
                                as configured with the
                                <varname>RootDirectory=</varname>
                                option (see
                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for more information) is only applied
                                to the process started with
                                <varname>ExecStart=</varname>, and not
                                to the various other
                                <varname>ExecStartPre=</varname>,
                                <varname>ExecStartPost=</varname>,
                                <varname>ExecReload=</varname>,
                                <varname>ExecStop=</varname>,
                                <varname>ExecStopPost=</varname>
                                commands. If false, the setting is
                                applied to all configured commands the
                                same way. Defaults to
                                false.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>KillMode=</varname></term>
                                <listitem><para>Specifies how
                                processes of this service shall be
                                killed. One of
                                <option>control-group</option>,
                                <option>process</option>,
                                <option>none</option>.</para>

                                <para>If set to
                                <option>control-group</option> all
                                remaining processes in the control
                                group of this service will be
                                terminated on service stop, after the
                                stop command (as configured with
                                <varname>ExecStop=</varname>) is
                                executed. If set to
                                <option>process</option> only the main
                                process itself is killed. If set to
                                <option>none</option> no process is
                                killed. In this case only the stop
                                command will be executed on service
                                stop, but no process be killed
                                otherwise. Processes remaining alive
                                after stop are left in their control
                                group and the control group continues
                                to exist after stop unless it is
                                empty. Defaults to
Andrew Edmunds's avatar
Andrew Edmunds committed
619
                                <option>control-group</option>.</para>
620 621

                                <para>Processes will first be
622 623
                                terminated via SIGTERM (unless the
                                signal to send is changed via
624 625
                                <varname>KillSignal=</varname>). If
                                then after a delay (configured via the
626
                                <varname>TimeoutSec=</varname> option)
627 628
                                processes still remain, the
                                termination request is repeated with
629 630 631 632
                                the SIGKILL signal (unless this is
                                disabled via the
                                <varname>SendSIGKILL=</varname>
                                option). See
633 634 635 636 637
                                <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                for more
                                information.</para></listitem>
                        </varlistentry>

638 639 640 641 642 643 644 645
                        <varlistentry>
                                <term><varname>KillSignal=</varname></term>
                                <listitem><para>Specifies which signal
                                to use when killing a
                                service. Defaults to SIGTERM.
                                </para></listitem>
                        </varlistentry>

646 647 648 649 650 651 652 653 654 655 656
                        <varlistentry>
                                <term><varname>SendSIGKILL=</varname></term>
                                <listitem><para>Specifies whether to
                                send SIGKILL to remaining processes
                                after a timeout, if the normal
                                shutdown procedure left processes of
                                the service around. Takes a boolean
                                value. Defaults to "yes".
                                </para></listitem>
                        </varlistentry>

657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682
                        <varlistentry>
                                <term><varname>NonBlocking=</varname></term>
                                <listitem><para>Set O_NONBLOCK flag
                                for all file descriptors passed via
                                socket-based activation. If true, all
                                file descriptors >= 3 (i.e. all except
                                STDIN/STDOUT/STDERR) will have
                                the O_NONBLOCK flag set and hence are in
                                non-blocking mode. This option is only
                                useful in conjunction with a socket
                                unit, as described in
                                <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
                                to false.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>NotifyAccess=</varname></term>
                                <listitem><para>Controls access to the
                                service status notification socket, as
                                accessible via the
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                call. Takes one of
                                <option>none</option> (the default),
                                <option>main</option> or
                                <option>all</option>. If
                                <option>none</option> no daemon status
Andrew Edmunds's avatar
Andrew Edmunds committed
683
                                updates are accepted from the service
684 685 686 687 688 689 690
                                processes, all status update messages
                                are ignored. If <option>main</option>
                                only service updates sent from the
                                main process of the service are
                                accepted. If <option>all</option> all
                                services updates from all members of
                                the service's control group are
691
                                accepted. This option should be set to
692 693
                                open access to the notification socket
                                when using
694 695 696 697 698 699 700
                                <varname>Type=notify</varname> or
                                <varname>WatchdogUsec=</varname> (see
                                above). If those options are used but
                                <varname>NotifyAccess=</varname> not
                                configured it will be implicitly set
                                to
                                <option>main</option>.</para></listitem>
701 702
                        </varlistentry>

703 704 705 706 707
                        <varlistentry>
                                <term><varname>Sockets=</varname></term>
                                <listitem><para>Specifies the name of
                                the socket units this service shall
                                inherit the sockets from when the
708
                                service is started. Normally it
709 710 711
                                should not be necessary to use this
                                setting as all sockets whose unit
                                shares the same name as the service
712
                                (ignoring the different suffix of course)
713 714 715 716 717 718 719 720 721 722 723 724
                                are passed to the spawned
                                process.</para>

                                <para>Note that the same socket may be
                                passed to multiple processes at the
                                same time. Also note that a different
                                service may be activated on incoming
                                traffic than inherits the sockets. Or
                                in other words: The
                                <varname>Service=</varname> setting of
                                <filename>.socket</filename> units
                                doesn't have to match the inverse of the
Lennart Poettering's avatar
Lennart Poettering committed
725
                                <varname>Sockets=</varname> setting of
726 727 728 729
                                the <filename>.service</filename> it
                                refers to.</para></listitem>
                        </varlistentry>

730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789
                        <varlistentry>
                                <term><varname>StartLimitInterval=</varname></term>
                                <term><varname>StartLimitBurst=</varname></term>

                                <listitem><para>Configure service
                                start rate limiting. By default
                                services which are started more often
                                than 5 times within 10s are not
                                permitted to start any more times
                                until the 10s interval ends. With
                                these two options this rate limiting
                                may be modified. Use
                                <varname>StartLimitInterval=</varname>
                                to configure the checking interval
                                (defaults to 10s, set to 0 to disable
                                any kind of rate limiting). Use
                                <varname>StartLimitBurst=</varname> to
                                configure how many starts per interval
                                are allowed (defaults to 5). These
                                configuration options are particularly
                                useful in conjunction with
                                <varname>Restart=</varname>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>StartLimitAction=</varname></term>

                                <listitem><para>Configure the action
                                to take if the rate limit configured
                                with
                                <varname>StartLimitInterval=</varname>
                                and
                                <varname>StartLimitBurst=</varname> is
                                hit. Takes one of
                                <option>none</option>,
                                <option>reboot</option>,
                                <option>reboot-force</option> or
                                <option>reboot-immediate</option>. If
                                <option>none</option> is set,
                                hitting the rate limit will trigger no
                                action besides that the start will not
                                be
                                permitted. <option>reboot</option>
                                causes a reboot following the normal
                                shutdown procedure (i.e. equivalent to
                                <command>systemctl reboot</command>),
                                <option>reboot-force</option> causes
                                an forced reboot which will terminate
                                all processes forcibly but should
                                cause no dirty file systems on reboot
                                (i.e. equivalent to <command>systemctl
                                reboot -f</command>) and
                                <option>reboot-immediate</option>
                                causes immediate execution of the
                                <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                system call, which might result in
                                data loss.  Defaults to
                                <option>none</option>.</para></listitem>
                        </varlistentry>

790 791 792
                </variablelist>
        </refsect1>

793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854
        <refsect1>
                <title>Compatibility Options</title>

                <para>The following options are also available in the
                <literal>[Service]</literal> section, but exist purely
                for compatibility reasons and should not be used in
                newly written service files.</para>

                <variablelist>
                        <varlistentry>
                                <term><varname>SysVStartPriority=</varname></term>
                                <listitem><para>Set the SysV start
                                priority to use to order this service
                                in relation to SysV services lacking
                                LSB headers. This option is only
                                necessary to fix ordering in relation
                                to legacy SysV services, that have no
                                ordering information encoded in the
                                script headers. As such it should only
                                be used as temporary compatibility
                                option, and not be used in new unit
                                files. Almost always it is a better
                                choice to add explicit ordering
                                directives via
                                <varname>After=</varname> or
                                <varname>Before=</varname>,
                                instead. For more details see
                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
                                used, pass an integer value in the
                                range 0-99.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>FsckPassNo=</varname></term>
                                <listitem><para>Set the fsck passno
                                priority to use to order this service
                                in relation to other file system
                                checking services. This option is only
                                necessary to fix ordering in relation
                                to fsck jobs automatically created for
                                all <filename>/etc/fstab</filename>
                                entries with a value in the fs_passno
                                column > 0. As such it should only be
                                used as option for fsck
                                services. Almost always it is a better
                                choice to add explicit ordering
                                directives via
                                <varname>After=</varname> or
                                <varname>Before=</varname>,
                                instead. For more details see
                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
                                used, pass an integer value in the
                                same range as
                                <filename>/etc/fstab</filename>'s
                                fs_passno column. See
                                <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                for details.</para></listitem>
                        </varlistentry>

                </variablelist>
        </refsect1>

855 856 857
        <refsect1>
                  <title>See Also</title>
                  <para>
858
                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
859 860 861
                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
862 863 864 865
                  </para>
        </refsect1>

</refentry>