systemd.service.xml 29.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 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
<?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
  under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (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
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  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>
91 92 93 94 95
        </refsect1>

        <refsect1>
                <title>Options</title>

96 97 98 99 100 101
                <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
102
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
103 104
                options specific to the <literal>[Service]</literal>
                section of service units are the following:</para>
105

106 107 108
                <variablelist>
                        <varlistentry>
                                <term><varname>Type=</varname></term>
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162

                                <listitem><para>Configures the process
                                start-up type for this service
                                unit. One of <option>simple</option>,
                                <option>forking</option>,
                                <option>finish</option>,
                                <option>dbus</option>,
                                <option>notify</option>.</para>

                                <para>If set to
                                <option>simple</option> (the default
                                value) it is expected that the process
                                configured with
                                <varname>ExecStart=</varname> is the
                                main process of the service. In this
                                mode, communication channels must 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>

                                <para>If set to
                                <option>forking</option> it is
                                expected that the process configured
                                with <varname>ExecStart=</varname>
                                will start up and call
                                <function>fork()</function>. The
                                parent process is expected to finish
                                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
                                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
                                <option>finish</option> is similar
                                to <option>simple</option>, however
                                it is expected that the process has to
                                exit before systemd starts follow-up
                                units. <varname>ValidNoProcess=</varname>
                                is particularly useful for this type
                                of service.</para>

                                <para>Behaviour of
                                <option>dbus</option> is similar to
163 164
                                <option>simple</option>, however it is
                                expected that the daemon acquires a
165 166 167 168 169
                                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
170 171 172 173 174
                                acquired. Service units with this
                                option configured implicitly have
                                dependencies on the
                                <filename>dbus.target</filename>
                                unit.</para>
175 176 177 178 179 180 181 182 183 184 185 186

                                <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
187
                                <varname>NotifyAccess=</varname> (see
188 189
                                below) must be set to open access to
                                the notification socket provided by
190 191 192 193
                                systemd. If
                                <varname>NotifyAccess=</varname> is not
                                set, it will be implicitly set to
                                <option>main</option>.</para>
194 195
                                </listitem>
                        </varlistentry>
196

197 198
                        <varlistentry>
                                <term><varname>ValidNoProcess=</varname></term>
199 200 201 202 203 204

                                <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>
205 206 207 208 209
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PIDFile=</varname></term>
210 211 212 213 214 215 216

                                <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
                                <option>forking</option>.</para>
217 218 219 220 221
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>BusName=</varname></term>
222 223 224 225 226 227 228 229 230 231

                                <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>
232 233 234 235 236
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStart=</varname></term>
237 238 239 240 241 242 243 244 245 246
                                <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
                                specified more than once. Optionally,
                                if the absolute file name is prefixed
247 248 249 250 251 252
                                with <literal>@</literal>, the second
                                token will be passed as
                                <literal>argv[0]</literal> to the
                                executed process, followed by the
                                further arguments specified. Unless
                                <varname>Type=forking</varname> is set,
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
                                the process started via this command
                                line will be considered the main
                                process of the
                                daemon.</para></listitem>
                        </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
                                <varname>ExecStart=</varname>. If
                                specified more than once, all commands
                                are executed one after the other,
                                serially. Use of these settings is
                                optional.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecReload=</varname></term>
                                <listitem><para>Commands to execute to
                                trigger a configuration reload in the
                                service. If used more than once, all
                                commands are executed one after the
                                other, serially. Use of this setting is optional.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStop=</varname></term>
                                <listitem><para>Commands to execute to
                                stop the service started via
                                <varname>ExecStart=</varname>. If used
                                more than once, all commands are
                                executed one after the other,
                                serially. Use of this setting is
                                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
                                requested.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStopPost=</varname></term>
                                <listitem><para>Additional commands
                                that are executed after the service
                                was stopped using the commands
                                configured in
                                <varname>ExecStop=</varname>. If
                                specified more than once, all commands
                                are executed one after the other,
                                serially. Use of these settings is
                                optional.</para></listitem>
                        </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
340
                                <varname>KillMode=</varname>
341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 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 468 469 470 471 472 473 474 475 476 477
                                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
                                60s.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Restart=</varname></term>
                                <listitem><para>Configures whether the
                                main service process shall be restarted when
                                it exists. Takes one of
                                <option>once</option>,
                                <option>restart-on-success</option> or
                                <option>restart-always</option>. If
                                set to <option>once</option> (the
                                default) the service will not be
                                restarted when it exits. If set to
                                <option>restart-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>restart-always</option> the
                                service will be restarted regardless
                                whether it exited cleanly or not, or
                                got terminated abnormally by a
                                signal.</para></listitem>
                        </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>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>KillMode=</varname></term>
                                <listitem><para>Specifies how
                                processes of this service shall be
                                killed. One of
                                <option>control-group</option>,
                                <option>process-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-group</option> only
                                the members of the process group of
                                the main service process are
                                killed. 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
                                <option>control-croup</option>.</para>

                                <para>Processes will first be
                                terminated via SIGTERM. If then after
                                a delay (configured via the
478
                                <varname>TimeoutSec=</varname> option)
479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524
                                processes still remain, the
                                termination request is repeated with
                                the SIGKILL signal. See
                                <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                for more
                                information.</para></listitem>
                        </varlistentry>

                        <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
                                updates are accepted by the service
                                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
                                accepted. This option must be set to
                                open access to the notification socket
                                when using
                                <varname>Type=notify</varname> (see above).</para></listitem>
525 526 527 528 529 530 531 532 533
                        </varlistentry>

                </variablelist>
        </refsect1>

        <refsect1>
                  <title>See Also</title>
                  <para>
                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
534 535 536
                          <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>
537 538 539 540
                  </para>
        </refsect1>

</refentry>