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