summaryrefslogtreecommitdiff
path: root/man/systemd.service.xml
blob: d573ec6f96a3721652cc330b3f09eecc98502317 (plain)
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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
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
340
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
478
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
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
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
<?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>

                <para>A unit configuration file whose name ends in
                <filename>.service</filename> encodes information
                about a process controlled and supervised by
                systemd.</para>

                <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
                files. The common configuration items are configured
                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>

                <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>

                <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>

                <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>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <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
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
                options specific to the <literal>[Service]</literal>
                section of service units are the following:</para>

                <variablelist>
                        <varlistentry>
                                <term><varname>Type=</varname></term>

                                <listitem><para>Configures the process
                                start-up type for this service
                                unit. One of <option>simple</option>,
                                <option>forking</option>,
                                <option>oneshot</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, 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>

                                <para>If set to
                                <option>forking</option> it is
                                expected that the process configured
                                with <varname>ExecStart=</varname>
                                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
                                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>oneshot</option> is similar
                                to <option>simple</option>, however
                                it is expected that the process has to
                                exit before systemd starts follow-up
                                units. <varname>RemainAfterExit=</varname>
                                is particularly useful for this type
                                of service.</para>

                                <para>Behaviour of
                                <option>dbus</option> is similar to
                                <option>simple</option>, however it is
                                expected that the daemon acquires a
                                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
                                acquired. Service units with this
                                option configured implicitly gain
                                dependencies on the
                                <filename>dbus.target</filename>
                                unit.</para>

                                <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
                                <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 implicitly be set to
                                <option>main</option>.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RemainAfterExit=</varname></term>

                                <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>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>PIDFile=</varname></term>

                                <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>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>BusName=</varname></term>

                                <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>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStart=</varname></term>
                                <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, 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
                                <literal>argv[0]</literal> to the
                                executed process, followed by the
                                further arguments specified. If the
                                first token is prefixed with
                                <literal>-</literal> an exit code of
                                the command normally considered a
                                failure (i.e. non-zero exit status or
                                abormal exit due to signal) is ignored
                                and considered success. If both
                                <literal>-</literal> and
                                <literal>@</literal> are used for the
                                same command the former must preceed
                                the latter. Unless
                                <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
                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. On
                                top of that basic environment variable
                                substitution is supported, where
                                <literal>${FOO}</literal> is replaced
                                by the string value of the environment
                                variable of the same name. Also
                                <literal>$FOO</literal> may appear as
                                separate word on the command line in
                                which case the variable is replaced by
                                its value split at whitespaces. Note
                                that the first argument (i.e. the
                                binary to execute) may not be a
                                variable, and must be a literal and
                                absolute path name.</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>. Multiple
                                command lines may be concatenated in a
                                single directive, by seperating them
                                by semicolons (these semicolons must
                                be passed as separate words). In that
                                case, the commands are executed one
                                after the other,
                                serially. Alternatively, these
                                directives may be specified more than
                                once whith the same effect. However,
                                the latter syntax is not recommended
                                for compatibility with parsers
                                suitable for XDG
                                <filename>.desktop</filename> files.
                                Use of these settings is
                                optional. Specifier and environment
                                variable substitution is
                                supported.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecReload=</varname></term>
                                <listitem><para>Commands to execute to
                                trigger a configuration reload in the
                                service. This argument takes multiple
                                command lines, following the same
                                scheme as pointed out for
                                <varname>ExecStartPre=</varname>
                                above. Use of this setting is
                                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
                                $(MAINPID)</command>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStop=</varname></term>
                                <listitem><para>Commands to execute to
                                stop the service started via
                                <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
                                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. Specifier and environment
                                variable substitution is supported
                                (including
                                <literal>$(MAINPID)</literal>, see
                                above).</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>. This
                                argument takes multiple command lines,
                                following the same scheme as pointed
                                out for
                                <varname>ExecStartPre</varname>. Use
                                of these settings is
                                optional. Specifier and environment
                                variable substitution is
                                supported.</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
                                <varname>KillMode=</varname>
                                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>no</option>,
                                <option>on-success</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>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
                                <varname>TimeoutSec=</varname> option)
                                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>
                        </varlistentry>

                </variablelist>
        </refsect1>

        <refsect1>
                  <title>See Also</title>
                  <para>
                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                          <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>
                  </para>
        </refsect1>

</refentry>