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