summaryrefslogtreecommitdiff
path: root/man/systemd.service.xml
blob: f33e8df05697529c2012f09178cee6f546277fd9 (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
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
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
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
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
790
791
792
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
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
<?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 Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 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
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser 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>Service unit configuration</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <para><filename><replaceable>service</replaceable>.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, and in
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which define the way the processes of the service are
                terminated, and in
                <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which configure resource control settings for the
                processes of the service.</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. Note that this compatibility is quite
                comprehensive but not 100%. For details about the
                incompatibilities, see the <ulink
                url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities
                with SysV</ulink> document.
                </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>
                and
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
                options specific to the <literal>[Service]</literal>
                section of service units are the following:</para>

                <variablelist class='unit-directives'>
                        <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> or
                                <option>idle</option>.</para>

                                <para>If set to
                                <option>simple</option> (the default
                                if neither
                                <varname>Type=</varname> nor
                                <varname>BusName=</varname>, but
                                <varname>ExecStart=</varname> are
                                specified), 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 are set up. The child continues
                                to run as the main daemon
                                process. This is the behavior 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 with starting follow-up units
                                as soon as the parent process
                                exits.</para>

                                <para>Behavior 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. This is the implied
                                default if neither
                                <varname>Type=</varname> or
                                <varname>ExecStart=</varname> are
                                specified.</para>

                                <para>Behavior 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 with 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.socket</filename>
                                unit. This type is the default if
                                <varname>BusName=</varname> is
                                specified.</para>

                                <para>Behavior 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 has finished
                                starting up. systemd will proceed with
                                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 be implicitly set to
                                <option>main</option>. Note that
                                currently
                                <varname>Type=</varname><option>notify</option>
                                will not work if used in combination with
                                <varname>PrivateNetwork=</varname><option>yes</option>.</para>

                                <para>Behavior of
                                <option>idle</option> is very similar
                                to <option>simple</option>; however,
                                actual execution of 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>
                                </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>GuessMainPID=</varname></term>

                                <listitem><para>Takes a boolean value
                                that specifies whether systemd should
                                try to guess the main PID of a service
                                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>
                        </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>. 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>
                                </listitem>
                        </varlistentry>

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

                                <listitem><para>Takes a D-Bus bus
                                name that this service is reachable
                                as. This option is mandatory for
                                services where
                                <varname>Type=</varname> is set to
                                <option>dbus</option>.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>BusPolicy=</varname></term>

                                <listitem><para>If specified, a custom
                                <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
                                endpoint will be created and installed as the
                                default bus node for the service. Such a custom
                                endpoint can hold an own set of policy rules
                                that are enforced on top of the bus-wide ones.
                                The custom endpoint is named after the service
                                it was created for, and its node will be
                                bind-mounted over the default bus node
                                location, so the service can only access the
                                bus through its own endpoint. Note that custom
                                bus endpoints default to a 'deny all' policy.
                                Hence, if at least one
                                <varname>BusPolicy=</varname> directive is
                                given, you have to make sure to add explicit
                                rules for everything the service should be able
                                to do.</para>
                                <para>The value of this directive is comprised
                                of two parts; the bus name, and a verb to
                                specify to granted access, which is one of
                                <option>see</option>,
                                <option>talk</option>, or
                                <option>own</option>.
                                <option>talk</option> implies
                                <option>see</option>, and <option>own</option>
                                implies both <option>talk</option> and
                                <option>see</option>.
                                If multiple access levels are specified for the
                                same bus name, the most powerful one takes
                                effect.
                                </para>
                                <para>Examples:</para>
                                <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
                                <programlisting>BusPolicy=org.foo.bar see</programlisting>
                                <para>This option is only available on kdbus enabled systems.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStart=</varname></term>
                                <listitem><para>Commands with their
                                arguments that are executed when this
                                service is started. The value is split
                                into zero or more command lines is
                                according to the rules described below
                                (see section "Command Lines" below).
                                </para>

                                <para>When <varname>Type</varname> is
                                not <option>oneshot</option>, only one
                                command may and must be given. When
                                <varname>Type=oneshot</varname> is
                                used, zero or more commands may be
                                specified. This can be specified by
                                providing multiple command lines in
                                the same directive, or alternatively,
                                this directive may be specified more
                                than once with the same effect. If the
                                empty string is assigned to this
                                option, the list of commands to start
                                is reset, prior assignments of this
                                option will have no effect. If no
                                <varname>ExecStart=</varname> is
                                specified, then the service must have
                                <varname>RemainAfterExit=yes</varname>
                                set.</para>

                                <para>For each of the specified
                                commands, the first argument must be
                                an absolute path to an executable.
                                Optionally, if this 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
                                absolute filename is prefixed with
                                <literal>-</literal>, an exit code of
                                the command normally considered a
                                failure (i.e. non-zero exit status or
                                abnormal exit due to signal) is
                                ignored and considered success. If
                                both <literal>-</literal> and
                                <literal>@</literal> are used, they
                                can appear in either order.</para>

                                <para>If more than one command is
                                specified, the commands are invoked
                                sequentially in the order they appear
                                in the unit file. If one of the
                                commands fails (and is not prefixed
                                with <literal>-</literal>), other
                                lines are not executed, and the unit
                                is considered failed.</para>

                                <para>Unless
                                <varname>Type=forking</varname> is
                                set, 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 or after
                                the command in
                                <varname>ExecStart=</varname>, respectively.
                                Syntax is the same as for
                                <varname>ExecStart=</varname>, except
                                that multiple command lines are allowed
                                and the commands are executed one
                                after the other, serially.</para>

                                <para>If any of those commands (not
                                prefixed with <literal>-</literal>)
                                fail, the rest are not executed and
                                the unit is considered failed.</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 described for
                                <varname>ExecStart=</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>.</para>

                                <para>One additional, special
                                environment variable is set: if known,
                                <varname>$MAINPID</varname> is set to
                                the main process of the daemon, and
                                may be used for command lines like the
                                following:</para>

                                <programlisting>/bin/kill -HUP $MAINPID</programlisting>

                                <para>Note however that reloading a
                                daemon by sending a signal (as with
                                the example line above) is usually not
                                a good choice, because this is an
                                asynchronous operation and hence not
                                suitable to order reloads of multiple
                                services against each other. It is
                                strongly recommended to set
                                <varname>ExecReload=</varname> to a
                                command that not only triggers a
                                configuration reload of the daemon,
                                but also synchronously waits for it to
                                complete.</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 described
                                for <varname>ExecStart=</varname>
                                above. Use of this setting is
                                optional. After the commands configured
                                in this option are run, all processes
                                remaining for a service are
                                terminated according to the
                                <varname>KillMode=</varname> setting
                                (see
                                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
                                this option is not specified, the
                                process is terminated immediately when
                                service stop is requested. Specifier
                                and environment variable substitution
                                is supported (including
                                <varname>$MAINPID</varname>, see
                                above).</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ExecStopPost=</varname></term>
                                <listitem><para>Additional commands
                                that are executed after the service
                                was stopped. This includes cases where
                                the commands configured in
                                <varname>ExecStop=</varname> were used,
                                where the service does not have any
                                <varname>ExecStop=</varname> defined, or
                                where the service exited unexpectedly. This
                                argument takes multiple command lines,
                                following the same scheme as described
                                for <varname>ExecStart</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>TimeoutStartSec=</varname></term>
                                <listitem><para>Configures the time to
                                wait for start-up. If a
                                daemon service does not signal
                                start-up completion within the
                                configured time, the service will be
                                considered failed and will be shut
                                down again.
                                Takes a unit-less value in seconds, or a
                                time span value such as "5min
                                20s". Pass <literal>0</literal> to
                                disable the timeout logic. Defaults to
                                <varname>DefaultTimeoutStartSec=</varname> from
                                the manager configuration file, except
                                when <varname>Type=oneshot</varname> is
                                used, in which case the timeout
                                is disabled by default
                                (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TimeoutStopSec=</varname></term>
                                <listitem><para>Configures the time to
                                wait for stop. If a service is asked
                                to stop, but does not terminate in the
                                specified time, it will be terminated
                                forcibly via <constant>SIGTERM</constant>,
                                and after another timeout of equal duration
                                with <constant>SIGKILL</constant> (see
                                <varname>KillMode=</varname>
                                in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                Takes a unit-less value in seconds, or a
                                time span value such as "5min
                                20s". Pass <literal>0</literal> to disable
                                the timeout logic. Defaults to
                                <varname>DefaultTimeoutStopSec=</varname> from the
                                manager configuration file
                                (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>TimeoutSec=</varname></term>
                                <listitem><para>A shorthand for configuring
                                both <varname>TimeoutStartSec=</varname>
                                and <varname>TimeoutStopSec=</varname>
                                to the specified value.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>WatchdogSec=</varname></term>
                                <listitem><para>Configures the
                                watchdog timeout for a service. The
                                watchdog is activated when the start-up is
                                completed. The service must call
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                regularly with <literal>WATCHDOG=1</literal>
                                (i.e. the "keep-alive ping"). If the time
                                between two such calls is larger than
                                the configured time, then the service
                                is placed in a failed state and it will
                                be terminated with <varname>SIGABRT</varname>.
                                By setting <varname>Restart=</varname> to
                                <option>on-failure</option> or
                                <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>
                                environment variable. This allows
                                daemons to automatically enable the
                                keep-alive pinging logic if watchdog
                                support is enabled for the service. 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,
                                which disables this
                                feature.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Restart=</varname></term>
                                <listitem><para>Configures whether the
                                service shall be restarted when the
                                service process exits, is killed,
                                or a timeout is reached. The service
                                process may be the main service
                                process, but it may also be one of the
                                processes specified with
                                <varname>ExecStartPre=</varname>,
                                <varname>ExecStartPost=</varname>,
                                <varname>ExecStop=</varname>,
                                <varname>ExecStopPost=</varname>, or
                                <varname>ExecReload=</varname>.
                                When the death of the process is a
                                result of systemd operation (e.g. service
                                stop or restart), the service will not be
                                restarted. Timeouts include missing
                                the watchdog "keep-alive ping"
                                deadline and a service start, reload,
                                and stop operation timeouts.</para>

                                <para>Takes one of
                                <option>no</option>,
                                <option>on-success</option>,
                                <option>on-failure</option>,
                                <option>on-abnormal</option>,
                                <option>on-watchdog</option>,
                                <option>on-abort</option>, or
                                <option>always</option>. If set to
                                <option>no</option> (the default), the
                                service will not be restarted. If set
                                to <option>on-success</option>, it
                                will be restarted only when the
                                service process exits cleanly.  In
                                this context, a clean exit means an
                                exit code of 0, or one of the signals
                                <constant>SIGHUP</constant>,
                                <constant>SIGINT</constant>,
                                <constant>SIGTERM</constant> or
                                <constant>SIGPIPE</constant>, and
                                additionally, exit statuses and
                                signals specified in
                                <varname>SuccessExitStatus=</varname>.
                                If set to <option>on-failure</option>,
                                the service will be restarted when the
                                process exits with a non-zero exit
                                code, is terminated by a signal
                                (including on core dump, but excluding
                                the aforementiond four signals), when
                                an operation (such as service reload)
                                times out, and when the configured
                                watchdog timeout is triggered.  If set
                                to <option>on-abnormal</option>, the
                                service will be restarted when the
                                process is terminated by a signal
                                (including on core dump, excluding the
                                aforementioned four signals), when an
                                operation times out, or when the
                                watchdog timeout is triggered. If set
                                to <option>on-abort</option>, the
                                service will be restarted only if the
                                service process exits due to an
                                uncaught signal not specified as a
                                clean exit status.  If set to
                                <option>on-watchdog</option>, the
                                service will be restarted only if the
                                watchdog timeout for the service
                                expires.  If set to
                                <option>always</option>, the service
                                will be restarted regardless of
                                whether it exited cleanly or not, got
                                terminated abnormally by a signal, or
                                hit a timeout.</para>

                                <table>
                                        <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title>

                                        <tgroup cols='2'>
                                                <colspec colname='path' />
                                                <colspec colname='expl' />
                                                <thead>
                                                        <row>
                                                                <entry>Restart settings/Exit causes</entry>
                                                                <entry><option>no</option></entry>
                                                                <entry><option>always</option></entry>
                                                                <entry><option>on-success</option></entry>
                                                                <entry><option>on-failure</option></entry>
                                                                <entry><option>on-abnormal</option></entry>
                                                                <entry><option>on-abort</option></entry>
                                                                <entry><option>on-watchdog</option></entry>
                                                        </row>
                                                </thead>
                                                <tbody>
                                                        <row>
                                                                <entry>Clean exit code or signal</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry/>
                                                                <entry/>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Unclean exit code</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry/>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Unclean signal</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Timeout</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry/>
                                                        </row>
                                                        <row>
                                                                <entry>Watchdog</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                                <entry>X</entry>
                                                                <entry/>
                                                                <entry>X</entry>
                                                        </row>
                                                </tbody>
                                        </tgroup>
                                </table>

                                <para>As exceptions to the setting
                                above the service will not be
                                restarted if the exit code or signal
                                is specified in
                                <varname>RestartPreventExitStatus=</varname>
                                (see below). Also, the services will
                                always be restarted if the exit code
                                or signal is specified in
                                <varname>RestartForceExitStatus=</varname>
                                (see below).</para>

                                <para>Setting this to
                                <option>on-failure</option> is the
                                recommended choice for long-running
                                services, in order to increase
                                reliability by attempting automatic
                                recovery from errors. For services
                                that shall be able to terminate on
                                their own choice (and avoid
                                immediate restarting),
                                <option>on-abnormal</option> is an
                                alternative choice.</para>
                                </listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>SuccessExitStatus=</varname></term>
                                <listitem><para>Takes a list of exit
                                status definitions that when returned
                                by the main service process will be
                                considered successful termination, in
                                addition to the normal successful exit
                                code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>,
                                <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status
                                definitions can either be numeric exit
                                codes or termination signal names,
                                separated by spaces. For example:
                                <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
                                ensures that exit codes 1, 2, 8 and
                                the termination signal
                                <constant>SIGKILL</constant> are
                                considered clean service terminations.
                                </para>

                                <para>Note that if a process has a
                                signal handler installed and exits by
                                calling
                                <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                in response to a signal, the
                                information about the signal is lost.
                                Programs should instead perform cleanup and kill themselves with the same signal instead. See
                                <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para>

                                <para>This option may appear more than once,
                                in which case the list of successful
                                exit statuses is merged. If the empty
                                string is assigned to this option, the
                                list is reset, all prior assignments
                                of this option will have no
                                effect.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RestartPreventExitStatus=</varname></term>
                                <listitem><para>Takes a list of exit
                                status definitions that when returned
                                by the main service process will
                                prevent automatic service restarts,
                                regardless of the restart setting
                                configured with
                                <varname>Restart=</varname>. Exit
                                status definitions can either be
                                numeric exit codes or termination
                                signal names, and are separated by
                                spaces. Defaults to the empty list, so
                                that, by default, no exit status is
                                excluded from the configured restart
                                logic. For example:
                                <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit
                                codes 1 and 6 and the termination
                                signal <constant>SIGABRT</constant> will
                                not result in automatic service
                                restarting. This
                                option may appear more than once, in
                                which case the list of restart-preventing
                                statuses is merged. If the empty
                                string is assigned to this option, the
                                list is reset and all prior assignments
                                of this option will have no
                                effect.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RestartForceExitStatus=</varname></term>
                                <listitem><para>Takes a list of exit
                                status definitions that when returned
                                by the main service process will force
                                automatic service restarts, regardless
                                of the restart setting configured with
                                <varname>Restart=</varname>. The
                                argument format is similar to
                                <varname>RestartPreventExitStatus=</varname>.</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>, and
                                <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>, and
                                <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>NonBlocking=</varname></term>
                                <listitem><para>Set the
                                <constant>O_NONBLOCK</constant> flag
                                for all file descriptors passed via
                                socket-based activation. If true, all
                                file descriptors >= 3 (i.e. all except
                                stdin, stdout, and stderr) will have
                                the <constant>O_NONBLOCK</constant> 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 from 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 should be set to
                                open access to the notification socket
                                when using
                                <varname>Type=notify</varname> or
                                <varname>WatchdogSec=</varname> (see
                                above). If those options are used but
                                <varname>NotifyAccess=</varname> is not
                                configured, it will be implicitly set
                                to
                                <option>main</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>Sockets=</varname></term>
                                <listitem><para>Specifies the name of
                                the socket units this service shall
                                inherit socket file descriptors
                                from when the service is
                                started. Normally it should not be
                                necessary to use this setting as all
                                socket file descriptors whose unit
                                shares the same name as the service
                                (subject to the different unit name
                                suffix of course) are passed to the
                                spawned process.</para>

                                <para>Note that the same socket file
                                descriptors may be passed to multiple
                                processes simultaneously. Also note
                                that a different service may be
                                activated on incoming socket traffic
                                than the one which is ultimately
                                configured to inherit the socket file
                                descriptors. Or in other words: the
                                <varname>Service=</varname> setting of
                                <filename>.socket</filename> units
                                does not have to match the inverse of
                                the <varname>Sockets=</varname>
                                setting of the
                                <filename>.service</filename> it
                                refers to.</para>

                                <para>This option may appear more than
                                once, in which case the list of socket
                                units is merged. If the empty string
                                is assigned to this option, the list of
                                sockets is reset, and all prior uses of
                                this setting will have no
                                effect.</para></listitem>
                        </varlistentry>

                        <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
                                than 5 times within 10 seconds are not
                                permitted to start any more times
                                until the 10 second interval ends. With
                                these two options, this rate limiting
                                may be modified. Use
                                <varname>StartLimitInterval=</varname>
                                to configure the checking interval (defaults to
                                <varname>DefaultStartLimitInterval=</varname> in
                                manager configuration file, 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
                                <varname>DefaultStartLimitBurst=</varname> in
                                manager configuration file). These
                                configuration options are particularly
                                useful in conjunction with
                                <varname>Restart=</varname>; however,
                                they apply to all kinds of starts
                                (including manual), not just those
                                triggered by the
                                <varname>Restart=</varname> logic.
                                Note that units which are configured
                                for <varname>Restart=</varname> and
                                which reach the start limit are not
                                attempted to be restarted anymore;
                                however, they may still be restarted
                                manually at a later point, from which
                                point on, the restart logic is again
                                activated. Note that
                                <command>systemctl
                                reset-failed</command> will cause the
                                restart rate counter for a service to
                                be flushed, which is useful if the
                                administrator wants to manually start
                                a service and the start limit
                                interferes with
                                that.</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>,
                                <option>reboot-immediate</option>,
                                <option>poweroff</option>,
                                <option>poweroff-force</option> or
                                <option>poweroff-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 a
                                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. Similar,
                                <option>poweroff</option>,
                                <option>poweroff-force</option>,
                                <option>poweroff-immediate</option>
                                have the effect of powering down the
                                system with similar
                                semantics. Defaults to
                                <option>none</option>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>FailureAction=</varname></term>
                                <listitem><para>Configure the action
                                to take when the service enters a failed
                                state. Takes the same values as
                                <varname>StartLimitAction=</varname>
                                and executes the same actions.
                                Defaults to <option>none</option>.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>RebootArgument=</varname></term>
                                <listitem><para>Configure the optional
                                argument for the
                                <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
                                system call if
                                <varname>StartLimitAction=</varname>
                                or <varname>FailureAction=</varname>
                                is a reboot action. This works just
                                like the optional argument to
                                <command>systemctl reboot</command>
                                command.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>FileDescriptorStoreMax=</varname></term>
                                <listitem><para>Configure how many
                                file descriptors may be stored in the
                                service manager for the service using
                                <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s
                                <literal>FDSTORE=1</literal>
                                messages. This is useful for
                                implementing service restart schemes
                                where the state is serialized to
                                <filename>/run</filename> and the file
                                descriptors passed to the service
                                manager, to allow restarts without
                                losing state. Defaults to 0, i.e. no
                                file descriptors may be stored in the
                                service manager by default. All file
                                descriptors passed to the service
                                manager from a specific service are
                                passed back to the service's main
                                process on the next service
                                restart. Any file descriptors passed
                                to the service manager are
                                automatically closed when POLLHUP or
                                POLLERR is seen on them, or when the
                                service is fully stopped and no job
                                queued or being executed for
                                it.</para></listitem>
                        </varlistentry>

                </variablelist>

                <para>Check
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                and
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for more settings.</para>

        </refsect1>

        <refsect1>
                <title>Command lines</title>

                <para>This section describes command line parsing and
                variable and specifier substitions for
                <varname>ExecStart=</varname>,
                <varname>ExecStartPre=</varname>,
                <varname>ExecStartPost=</varname>,
                <varname>ExecReload=</varname>,
                <varname>ExecStop=</varname>, and
                <varname>ExecStopPost=</varname> options.</para>

                <para>Multiple command lines may be concatenated in a
                single directive by separating them with semicolons
                (these semicolons must be passed as separate words).
                Lone semicolons may be escaped as
                <literal>\;</literal>.</para>

                <para>Each command line is split on whitespace, with
                the first item being the command to execute, and the
                subsequent items being the arguments. Double quotes
                ("...") and single quotes ('...') may be used, in
                which case everything until the next matching quote
                becomes part of the same argument. C-style escapes are
                also supported, see table below. Quotes themselves are
                removed after parsing and escape sequences
                substituted. In addition, a trailing backslash
                (<literal>\</literal>) may be used to merge lines.
                </para>

                <para>This syntax is intended to be very similar to
                shell syntax, but only the meta-characters and
                expansions described in the following paragraphs are
                understood.  Specifically, redirection using
                <literal>&lt;</literal>, <literal>&lt;&lt;</literal>,
                <literal>&gt;</literal>, and
                <literal>&gt;&gt;</literal>, pipes using
                <literal>|</literal>, running programs in the
                background using <literal>&amp;</literal>, and
                <emphasis>other elements of shell syntax are not
                supported</emphasis>.</para>

                <para>The command to execute must an absolute path
                name. It may contain spaces, but control characters
                are not allowed.</para>

                <para>The command line accepts <literal>%</literal>
                specifiers as described in
                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
                Note that the first argument of the command line
                (i.e. the program to execute) may not include
                specifiers.</para>

                <para>Basic environment variable substitution is
                supported. Use <literal>${FOO}</literal> as part of a
                word, or as a 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 at whitespace
                resulting in zero or more arguments. For this type of
                expansion, quotes and respected when splitting into
                words, and afterwards removed.</para>

                <para>Example:</para>

                <programlisting>Environment="ONE=one" 'TWO=two two'
ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>

                <para>This will execute <command>/bin/echo</command>
                with four arguments: <literal>one</literal>,
                <literal>two</literal>, <literal>two</literal>, and
                <literal>two two</literal>.</para>

                <para>Example:</para>
                <programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
                <para>This results in <filename>echo</filename> being
                called twice, the first time with arguments
                <literal>'one'</literal>,
                <literal>'two two' too</literal>, <literal></literal>,
                and the second time with arguments
                <literal>one</literal>, <literal>two two</literal>,
                <literal>too</literal>.
                </para>

                <para>To pass a literal dollar sign, use
                <literal>$$</literal>. Variables whose value is not
                known at expansion time are treated as empty
                strings. Note that the first argument (i.e. the
                program to execute) may not be a variable.</para>

                <para>Variables to be used in this fashion may be
                defined through <varname>Environment=</varname> and
                <varname>EnvironmentFile=</varname>.  In addition,
                variables listed in the section "Environment variables
                in spawned processes" in
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which are considered "static configuration", may be
                used (this includes e.g. <varname>$USER</varname>, but
                not <varname>$TERM</varname>).</para>

                <para>Note that shell command lines are not directly
                supported. If shell command lines are to be used, they
                need to be passed explicitly to a shell implementation
                of some kind. Example:</para>
                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>

                <para>Example:</para>

                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>

                <para>This will execute <command>/bin/echo</command>
                two times, each time with one argument:
                <literal>one</literal> and <literal>two two</literal>,
                respectively. Because two commands are specified,
                <varname>Type=oneshot</varname> must be used.</para>

                <para>Example:</para>

                <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
/bin/ls</programlisting>

                <para>This will execute <command>/bin/echo</command>
                with five arguments: <literal>/</literal>,
                <literal>&gt;/dev/null</literal>,
                <literal>&amp;</literal>, <literal>;</literal>, and
                <literal>/bin/ls</literal>.</para>

                <table>
                        <title>C escapes supported in command lines and environment variables</title>
                        <tgroup cols='2'>
                                <colspec colname='escape' />
                                <colspec colname='meaning' />
                                <thead>
                                        <row>
                                                <entry>Literal</entry>
                                                <entry>Actual value</entry>
                                        </row>
                                </thead>
                                <tbody>
                                        <row>
                                                <entry><literal>\a</literal></entry>
                                                <entry>bell</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\b</literal></entry>
                                                <entry>backspace</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\f</literal></entry>
                                                <entry>form feed</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\n</literal></entry>
                                                <entry>newline</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\r</literal></entry>
                                                <entry>carriage return</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\t</literal></entry>
                                                <entry>tab</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\v</literal></entry>
                                                <entry>vertical tab</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\\</literal></entry>
                                                <entry>backslash</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\"</literal></entry>
                                                <entry>double quotation mark</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\'</literal></entry>
                                                <entry>single quotation mark</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\s</literal></entry>
                                                <entry>space</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\x<replaceable>xx</replaceable></literal></entry>
                                                <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry>
                                        </row>
                                        <row>
                                                <entry><literal>\<replaceable>nnn</replaceable></literal></entry>
                                                <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry>
                                        </row>
                                </tbody>
                        </tgroup>
                </table>
        </refsect1>

        <refsect1>
                <title>Examples</title>

                <example>
                        <title>Simple service</title>

                        <para>The following unit file creates a service
                        that will execute
                        <filename>/usr/sbin/foo-daemon</filename>.
                        Since no <varname>Type=</varname> is specified,
                        the default
                        <varname>Type=</varname><option>simple</option>
                        will be assumed. systemd will assume the unit
                        to be started immediately after the program has
                        begun executing.</para>

                        <programlisting>[Unit]
Description=Foo

[Service]
ExecStart=/usr/sbin/foo-daemon

[Install]
WantedBy=multi-user.target</programlisting>

                        <para>Note that systemd assumes here that the
                        process started by systemd will continue
                        running until the service terminates. If the
                        program daemonizes itself (i.e. forks), please
                        use
                        <varname>Type=</varname><option>forking</option>
                        instead.</para>

                        <para>Since no <varname>ExecStop=</varname> was
                        specified, systemd will send SIGTERM to all
                        processes started from this service, and after
                        a timeout also SIGKILL. This behavior can be
                        modified, see
                        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                        for details.</para>

                        <para>Note that this unit type does not include
                        any type of notification when a service has
                        completed initialization. For this, you should
                        use other unit types, such as
                        <varname>Type=</varname><option>notify</option>
                        if the service understands systemd's
                        notification protocol,
                        <varname>Type=</varname><option>forking</option>
                        if the service can background itself or
                        <varname>Type=</varname><option>dbus</option>
                        if the unit acquires a DBus name once
                        initialization is complete. See below.</para>
                </example>

                <example>
                        <title>Oneshot service</title>

                        <para>Sometimes units should just execute an
                        action without keeping active processes, such
                        as a filesystem check or a cleanup action on
                        boot. For this,
                        <varname>Type=</varname><option>oneshot</option>
                        exists. Units of this type will wait until the
                        process specified terminates and then fall back
                        to being inactive. The following unit will
                        perform a clenaup action:</para>

                        <programlisting>[Unit]
Description=Cleanup old Foo data

[Service]
Type=oneshot
ExecStart=/usr/sbin/foo-cleanup

[Install]
WantedBy=multi-user.target</programlisting>

                        <para>Note that systemd will consider the unit
                        to be in the state 'starting' until the program
                        has terminated, so ordered dependencies will
                        wait for the program to finish before starting
                        themselves. The unit will revert to the
                        'inactive' state after the execution is
                        done, never reaching the 'active' state. That
                        means another request to start the unit will
                        perform the action again.</para>

                        <para><varname>Type=</varname><option>oneshot</option>
                        are the only service units that may have more
                        than one <varname>ExecStart=</varname>
                        specified. They will be executed in order until
                        either they are all successful or one of them
                        fails.</para>
                </example>

                <example>
                        <title>Stoppable oneshot service</title>

                        <para>Similarly to the oneshot services, there
                        are sometimes units that need to execute a
                        program to set up something and then execute
                        another to shut it down, but no process remains
                        active while they are considered
                        'started'. Network configuration can sometimes
                        fall into this category. Another use case is if
                        a oneshot service shall not be executed a
                        each time when they are pulled in as a
                        dependency, but only the first time.</para>

                        <para>For this, systemd knows the setting
                        <varname>RemainAfterExit=</varname><option>yes</option>,
                        which causes systemd to consider the unit to be
                        active if the start action exited successfully.
                        This directive can be used with all types, but
                        is most useful with
                        <varname>Type=</varname><option>oneshot</option>
                        and
                        <varname>Type=</varname><option>simple</option>.
                        With
                        <varname>Type=</varname><option>oneshot</option>
                        systemd waits until the start action has
                        completed before it considers the unit to be
                        active, so dependencies start only after the
                        start action has succeeded. With
                        <varname>Type=</varname><option>simple</option>
                        dependencies will start immediately after the
                        start action has been dispatched. The following
                        unit provides an example for a simple static
                        firewall.</para>

                        <programlisting>[Unit]
Description=Simple firewall

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/simple-firewall-start
ExecStop=/usr/local/sbin/simple-firewall-stop

[Install]
WantedBy=multi-user.target</programlisting>

                        <para>Since the unit is considered to be
                        running after the start action has exited,
                        invoking <command>systemctl start</command> on
                        that unit again will cause no action to be
                        taken.</para>
                </example>

                <example>
                        <title>Traditional forking services</title>

                        <para>Many traditional daemons/services
                        background (i.e. fork, daemonize) themselves
                        when starting. Set
                        <varname>Type=</varname><option>forking</option>
                        in the service's unit file to support this mode
                        of operation. systemd will consider the service
                        to be in the process of initialization while
                        the original program is still running. Once
                        it exits successfully and at least a process
                        remains (and
                        <varname>RemainAfterExit=</varname><option>no</option>),
                        the service is considered started.</para>

                        <para>Often a traditional daemon only consists
                        of one process. Therefore, if only one process
                        is left after the original process terminates,
                        systemd will consider that process the main
                        process of the service. In that case, the
                        <varname>$MAINPID</varname> variable will be
                        available in <varname>ExecReload=</varname>,
                        <varname>ExecStop=</varname>, etc.</para>

                        <para>In case more than one process remains,
                        systemd will be unable to determine the main
                        process, so it will not assume there is one.
                        In that case, <varname>$MAINPID</varname> will
                        not expand to anything. However, if the process
                        decides to write a traditional PID file,
                        systemd will be able to read the main PID from
                        there. Please set <varname>PIDFile=</varname>
                        accordingly. Note that the daemon should write
                        that file before finishing with its
                        initialization, otherwise systemd might try to
                        read the file before it exists.</para>

                        <para>The following example shows a simple
                        daemon that forks and just starts one process
                        in the background:</para>

                        <programlisting>[Unit]
Description=Some simple daemon

[Service]
Type=forking
ExecStart=/usr/sbin/my-simple-daemon -d

[Install]
WantedBy=multi-user.target</programlisting>

                        <para>Please see
                        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                        for details on how you can influence the way
                        systemd terminates the service.</para>
                </example>

                <example>
                        <title>DBus services</title>

                        <para>For services that acquire a name on the
                        DBus system bus, use
                        <varname>Type=</varname><option>dbus</option>
                        and set <varname>BusName=</varname>
                        accordingly. The service should not fork
                        (daemonize). systemd will consider the service
                        to be initialized once the name has been
                        acquired on the system bus. The following
                        example shows a typical DBus service:</para>

                        <programlisting>[Unit]
Description=Simple DBus service

[Service]
Type=dbus
BusName=org.example.simple-dbus-service
ExecStart=/usr/sbin/simple-dbus-service

[Install]
WantedBy=multi-user.target</programlisting>

                        <para>For <emphasis>bus-activatable</emphasis>
                        services, don't include a
                        <literal>[Install]</literal> section in the
                        systemd service file, but use the
                        <varname>SystemdService=</varname> option in
                        the corresponding DBus service file, for
                        example
                        (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para>

                        <programlisting>[D-BUS Service]
Name=org.example.simple-dbus-service
Exec=/usr/sbin/simple-dbus-service
User=root
SystemdService=simple-dbus-service.service</programlisting>

                        <para>Please see
                        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                        for details on how you can influence the way
                        systemd terminates the service.</para>
                </example>

                <example>
                        <title>Services that notify systemd about their initialization</title>

                        <para><varname>Type=</varname><option>simple</option>
                        services are really easy to write, but have the
                        major disadvantage of systemd not being able to
                        tell when initialization of the given service
                        is complete. For this reason, systemd supports
                        a simple notification protocol that allows
                        daemons to make systemd aware that they are
                        done initializing. Use
                        <varname>Type=</varname><option>notify</option>
                        for this. A typical service file for such a
                        daemon would look like this:</para>

                        <programlisting>[Unit]
Description=Simple notifying service

[Service]
Type=notify
ExecStart=/usr/sbin/simple-notifying-service

[Install]
WantedBy=multi-user.target</programlisting>

                        <para>Note that the daemon has to support
                        systemd's notification protocol, else systemd
                        will think the service hasn't started yet and
                        kill it after a timeout. For an example of how
                        to update daemons to support this protocol
                        transparently, take a look at
                        <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
                        systemd will consider the unit to be in the
                        'starting' state until a readiness notification
                        has arrived.</para>

                        <para>Please see
                        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                        for details on how you can influence the way
                        systemd terminates the service.</para>
                </example>
        </refsect1>

        <refsect1>
                  <title>See Also</title>
                  <para>
                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                          <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                  </para>
        </refsect1>

</refentry>