]>
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> | |
e670b166 | 51 | <para><filename><replaceable>service</replaceable>.service</filename></para> |
d1ab0ca0 LP |
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 | 75 | are executed in, and in |
d868475a | 76 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
4819ff03 | 77 | which define the way the processes of the service are |
d868475a | 78 | terminated, and in |
3fde5f30 LP |
79 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
80 | which configure resource control settings for the | |
d868475a | 81 | processes of the service.</para> |
62adf224 LP |
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> | |
59a3e1bc LP |
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 | |
99800333 LP |
104 | SysV. Note that this compatibility is quite |
105 | comprehensive but not 100%. For details about the | |
bb31a4ac | 106 | incompatibilities see the <ulink |
99800333 LP |
107 | url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities |
108 | with SysV</ulink> document. | |
109 | </para> | |
d1ab0ca0 LP |
110 | </refsect1> |
111 | ||
112 | <refsect1> | |
113 | <title>Options</title> | |
114 | ||
62adf224 LP |
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 | |
4819ff03 LP |
121 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
122 | and | |
123 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The | |
62adf224 LP |
124 | options specific to the <literal>[Service]</literal> |
125 | section of service units are the following:</para> | |
0d624a78 | 126 | |
ccc9a4f9 | 127 | <variablelist class='unit-directives'> |
d1ab0ca0 LP |
128 | <varlistentry> |
129 | <term><varname>Type=</varname></term> | |
0d624a78 LP |
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>, | |
34e9ba66 | 135 | <option>oneshot</option>, |
0d624a78 | 136 | <option>dbus</option>, |
a8ad0f89 LP |
137 | <option>notify</option> or |
138 | <option>idle</option>.</para> | |
0d624a78 LP |
139 | |
140 | <para>If set to | |
141 | <option>simple</option> (the default | |
0b86feac | 142 | value if <varname>BusName=</varname> |
79640424 | 143 | is not specified), it is expected that |
0b86feac | 144 | the process configured with |
0d624a78 LP |
145 | <varname>ExecStart=</varname> is the |
146 | main process of the service. In this | |
b1690fe7 LP |
147 | mode, if the process offers |
148 | functionality to other processes on | |
79640424 | 149 | the system, its communication channels |
b1690fe7 LP |
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> | |
0d624a78 LP |
155 | |
156 | <para>If set to | |
79640424 | 157 | <option>forking</option>, it is |
0d624a78 LP |
158 | expected that the process configured |
159 | with <varname>ExecStart=</varname> | |
b1690fe7 LP |
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 | |
79640424 | 164 | channels are set up. The child continues |
b1690fe7 | 165 | to run as the main daemon |
c5315881 | 166 | process. This is the behavior of |
b1690fe7 | 167 | traditional UNIX daemons. If this |
0d624a78 LP |
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 | ||
c5315881 | 177 | <para>Behavior of |
34e9ba66 | 178 | <option>oneshot</option> is similar |
0d624a78 LP |
179 | to <option>simple</option>, however |
180 | it is expected that the process has to | |
181 | exit before systemd starts follow-up | |
02ee865a | 182 | units. <varname>RemainAfterExit=</varname> |
0d624a78 LP |
183 | is particularly useful for this type |
184 | of service.</para> | |
185 | ||
c5315881 | 186 | <para>Behavior of |
0d624a78 | 187 | <option>dbus</option> is similar to |
62adf224 LP |
188 | <option>simple</option>, however it is |
189 | expected that the daemon acquires a | |
0d624a78 LP |
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 | |
62adf224 | 195 | acquired. Service units with this |
b1690fe7 | 196 | option configured implicitly gain |
62adf224 | 197 | dependencies on the |
177b3ffe | 198 | <filename>dbus.socket</filename> |
0b86feac LP |
199 | unit. This type is the default if |
200 | <varname>BusName=</varname> is | |
201 | specified.</para> | |
0d624a78 | 202 | |
c5315881 | 203 | <para>Behavior of |
0d624a78 LP |
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 | |
79640424 | 213 | this option is used, |
62adf224 | 214 | <varname>NotifyAccess=</varname> (see |
b1690fe7 | 215 | below) should be set to open access to |
0d624a78 | 216 | the notification socket provided by |
62adf224 | 217 | systemd. If |
02c4ef9c LP |
218 | <varname>NotifyAccess=</varname> is |
219 | not set, it will be implicitly set to | |
1361a3e3 LP |
220 | <option>main</option>. Note that |
221 | currently | |
222 | <varname>Type=</varname><option>notify</option> | |
79640424 | 223 | will not work if used in combination with |
1361a3e3 | 224 | <varname>PrivateNetwork=</varname><option>yes</option>.</para> |
a8ad0f89 | 225 | |
c5315881 | 226 | <para>Behavior of |
a8ad0f89 | 227 | <option>idle</option> is very similar |
349b915d | 228 | to <option>simple</option>, however |
bb31a4ac | 229 | actual execution of the service |
a8ad0f89 LP |
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> | |
d1ab0ca0 LP |
235 | </listitem> |
236 | </varlistentry> | |
0d624a78 | 237 | |
d1ab0ca0 | 238 | <varlistentry> |
02ee865a | 239 | <term><varname>RemainAfterExit=</varname></term> |
0d624a78 LP |
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> | |
d1ab0ca0 | 246 | </listitem> |
3185a36b LP |
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 | |
bb31a4ac | 255 | if it cannot be determined |
3185a36b LP |
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 | |
79640424 | 265 | the main PID cannot be determined, |
3185a36b LP |
266 | failure detection and automatic |
267 | restarting of a service will not work | |
268 | reliably. Defaults to | |
269 | <option>yes</option>.</para> | |
270 | </listitem> | |
d1ab0ca0 LP |
271 | </varlistentry> |
272 | ||
273 | <varlistentry> | |
274 | <term><varname>PIDFile=</varname></term> | |
0d624a78 LP |
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 | |
be039669 LP |
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> | |
d1ab0ca0 LP |
286 | </listitem> |
287 | </varlistentry> | |
288 | ||
289 | <varlistentry> | |
290 | <term><varname>BusName=</varname></term> | |
0d624a78 LP |
291 | |
292 | <listitem><para>Takes a D-Bus bus | |
bb31a4ac | 293 | name, that this service is reachable |
0d624a78 LP |
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> | |
d1ab0ca0 LP |
301 | </listitem> |
302 | </varlistentry> | |
303 | ||
304 | <varlistentry> | |
305 | <term><varname>ExecStart=</varname></term> | |
22f38abe LP |
306 | <listitem><para>Commands with their |
307 | arguments that are executed when this | |
22382c3f MA |
308 | service is started. The first |
309 | argument must be an absolute path | |
310 | name.</para> | |
2480f0c6 | 311 | |
4c42e8e1 ZJS |
312 | <para>When <varname>Type</varname> is |
313 | not <option>oneshot</option>, only one | |
314 | command may be given. When | |
b1690fe7 | 315 | <varname>Type=oneshot</varname> is |
2480f0c6 ZJS |
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. | |
4c42e8e1 | 328 | Lone semicolons may be escaped as |
909f413d | 329 | <literal>\;</literal>. If the empty |
79640424 | 330 | string is assigned to this option, the |
74051b9b LP |
331 | list of commands to start is reset, |
332 | prior assignments of this option will | |
333 | have no effect.</para> | |
2480f0c6 | 334 | |
4c42e8e1 ZJS |
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 | |
909f413d | 340 | prefixed with <literal>-</literal>), |
4c42e8e1 ZJS |
341 | other lines are not executed and the |
342 | unit is considered failed.</para> | |
343 | ||
2480f0c6 ZJS |
344 | <para>Unless |
345 | <varname>Type=forking</varname> is | |
346 | set, the process started via this | |
347 | command line will be considered the | |
22f38abe LP |
348 | main process of the daemon.</para> |
349 | ||
350 | <para>The command line accepts | |
909f413d | 351 | <literal>%</literal> specifiers as |
22f38abe LP |
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> | |
b1690fe7 | 357 | |
4c42e8e1 ZJS |
358 | <para>Basic environment variable |
359 | substitution is supported. Use | |
7734f773 | 360 | <literal>${FOO}</literal> as part of a |
bb31a4ac | 361 | word, or as a word of its own on the |
7734f773 BS |
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 | |
4c42e8e1 | 371 | at whitespace, resulting in zero or |
72f4d966 | 372 | more arguments. To pass a literal dollar sign, |
f4d213c1 | 373 | use <literal>$$</literal>. Note that the first |
7734f773 | 374 | argument (i.e. the program to execute) |
22382c3f MA |
375 | may not be a variable, since it must |
376 | be a literal and absolute path | |
a2927192 LP |
377 | name.</para> |
378 | ||
74051b9b LP |
379 | <para>Optionally, if the absolute file |
380 | name is prefixed with | |
909f413d | 381 | <literal>@</literal>, the second token |
74051b9b LP |
382 | will be passed as |
383 | <literal>argv[0]</literal> to the | |
384 | executed process, followed by the | |
385 | further arguments specified. If the | |
e9dd9f95 | 386 | absolute filename is prefixed with |
79640424 | 387 | <literal>-</literal>, an exit code of |
74051b9b LP |
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 | |
909f413d | 392 | <literal>-</literal> and |
79640424 | 393 | <literal>@</literal> are used, they |
74051b9b LP |
394 | can appear in either order.</para> |
395 | ||
a2927192 LP |
396 | <para>Note that this setting does not |
397 | directly support shell command | |
398 | lines. If shell command lines are to | |
79640424 | 399 | be used, they need to be passed |
a2927192 | 400 | explicitly to a shell implementation |
4c42e8e1 ZJS |
401 | of some kind. Example:</para> |
402 | <programlisting>ExecStart=/bin/sh -c 'dmesg | tac' | |
403 | </programlisting> | |
97ae63e2 LP |
404 | |
405 | <para>For services run by a user | |
406 | instance of systemd the special | |
407 | environment variable | |
4c42e8e1 | 408 | <varname>$MANAGERPID</varname> is set |
97ae63e2 LP |
409 | to the PID of the systemd |
410 | instance.</para> | |
a2927192 | 411 | </listitem> |
0d624a78 LP |
412 | </varlistentry> |
413 | ||
414 | <varlistentry> | |
415 | <term><varname>ExecStartPre=</varname></term> | |
416 | <term><varname>ExecStartPost=</varname></term> | |
417 | <listitem><para>Additional commands | |
16dad32e | 418 | that are executed before or after |
0d624a78 | 419 | the command in |
2480f0c6 ZJS |
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> | |
4c42e8e1 ZJS |
426 | |
427 | <para>If any of those commands (not | |
909f413d | 428 | prefixed with <literal>-</literal>) |
4c42e8e1 ZJS |
429 | fail, the rest are not executed and |
430 | the unit is considered failed.</para> | |
2480f0c6 | 431 | </listitem> |
0d624a78 LP |
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 | |
b3eaa628 LP |
438 | service. This argument takes multiple |
439 | command lines, following the same | |
2480f0c6 ZJS |
440 | scheme as described for |
441 | <varname>ExecStart=</varname> | |
b3eaa628 | 442 | above. Use of this setting is |
420a0166 LP |
443 | optional. Specifier and environment |
444 | variable substitution is supported | |
445 | here following the same scheme as for | |
4c42e8e1 ZJS |
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 | |
97ae63e2 LP |
451 | the main process of the daemon, and |
452 | may be used for command lines like the | |
4c42e8e1 ZJS |
453 | following:</para> |
454 | ||
455 | <programlisting>/bin/kill -HUP $MAINPID</programlisting> | |
456 | </listitem> | |
0d624a78 LP |
457 | </varlistentry> |
458 | ||
459 | <varlistentry> | |
460 | <term><varname>ExecStop=</varname></term> | |
461 | <listitem><para>Commands to execute to | |
462 | stop the service started via | |
b3eaa628 LP |
463 | <varname>ExecStart=</varname>. This |
464 | argument takes multiple command lines, | |
2480f0c6 ZJS |
465 | following the same scheme as described |
466 | for <varname>ExecStart=</varname> | |
b3eaa628 | 467 | above. Use of this setting is |
0d624a78 LP |
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 | |
4819ff03 LP |
473 | (see |
474 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If | |
79640424 | 475 | this option is not specified, the |
4819ff03 LP |
476 | process is terminated right-away when |
477 | service stop is requested. Specifier | |
478 | and environment variable substitution | |
479 | is supported (including | |
4c42e8e1 | 480 | <varname>$MAINPID</varname>, see |
420a0166 | 481 | above).</para></listitem> |
0d624a78 LP |
482 | </varlistentry> |
483 | ||
484 | <varlistentry> | |
485 | <term><varname>ExecStopPost=</varname></term> | |
486 | <listitem><para>Additional commands | |
487 | that are executed after the service | |
3ae390ba MB |
488 | was stopped. This includes cases where |
489 | the commands configured in | |
490 | <varname>ExecStop=</varname> were used, | |
6b4991cf | 491 | where the service does not have any |
3ae390ba MB |
492 | <varname>ExecStop=</varname> defined, or |
493 | where the service exited unexpectedly. This | |
b3eaa628 | 494 | argument takes multiple command lines, |
2480f0c6 ZJS |
495 | following the same scheme as described |
496 | for <varname>ExecStart</varname>. Use | |
b3eaa628 | 497 | of these settings is |
420a0166 LP |
498 | optional. Specifier and environment |
499 | variable substitution is | |
500 | supported.</para></listitem> | |
0d624a78 LP |
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> | |
d568a335 | 516 | <term><varname>TimeoutStartSec=</varname></term> |
0d624a78 | 517 | <listitem><para>Configures the time to |
d568a335 | 518 | wait for start-up. If a |
0d624a78 LP |
519 | daemon service does not signal |
520 | start-up completion within the | |
d568a335 | 521 | configured time, the service will be |
0d624a78 | 522 | considered failed and be shut down |
d568a335 MS |
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 | |
63ba209d | 527 | logic. Defaults to <varname>TimeoutStartSec=</varname> from the |
1f19a534 | 528 | manager configuration file, except when |
d568a335 | 529 | <varname>Type=oneshot</varname> is |
63ba209d | 530 | used, in which case the timeout |
d568a335 MS |
531 | is disabled by default. |
532 | </para></listitem> | |
533 | </varlistentry> | |
534 | ||
535 | <varlistentry> | |
536 | <term><varname>TimeoutStopSec=</varname></term> | |
537 | <listitem><para>Configures the time to | |
538 | wait for stop. If a service is asked | |
539 | to stop but does not terminate in the | |
540 | specified time, it will be terminated | |
05cc7267 | 541 | forcibly via <constant>SIGTERM</constant>, and after |
0d624a78 | 542 | another delay of this time with |
05cc7267 | 543 | <constant>SIGKILL</constant> (See |
62adf224 | 544 | <varname>KillMode=</varname> |
d568a335 MS |
545 | in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
546 | Takes a unit-less value in seconds, or a | |
0d624a78 LP |
547 | time span value such as "5min |
548 | 20s". Pass 0 to disable the timeout | |
63ba209d | 549 | logic. Defaults to <varname>TimeoutStartSec=</varname> from the |
1f19a534 | 550 | manager configuration file. |
d568a335 MS |
551 | </para></listitem> |
552 | </varlistentry> | |
553 | ||
554 | <varlistentry> | |
555 | <term><varname>TimeoutSec=</varname></term> | |
556 | <listitem><para>A shorthand for configuring | |
557 | both <varname>TimeoutStartSec=</varname> | |
558 | and <varname>TimeoutStopSec=</varname> | |
559 | to the specified value. | |
560 | </para></listitem> | |
0d624a78 LP |
561 | </varlistentry> |
562 | ||
bb242b7b MO |
563 | <varlistentry> |
564 | <term><varname>WatchdogSec=</varname></term> | |
e8ab3ccb | 565 | <listitem><para>Configures the |
a827e373 ZJS |
566 | watchdog timeout for a service. The |
567 | watchdog is activated when the start-up is | |
e8ab3ccb | 568 | completed. The service must call |
bb242b7b | 569 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
dac051ad LP |
570 | regularly with "WATCHDOG=1" (i.e. the |
571 | "keep-alive ping"). If the time | |
572 | between two such calls is larger than | |
79640424 | 573 | the configured time, then the service |
dac051ad LP |
574 | is placed in a failure state. By |
575 | setting <varname>Restart=</varname> to | |
576 | <option>on-failure</option> or | |
79640424 | 577 | <option>always</option>, the service |
e8ab3ccb LP |
578 | will be automatically restarted. The |
579 | time configured here will be passed to | |
580 | the executed service process in the | |
581 | <varname>WATCHDOG_USEC=</varname> | |
dac051ad LP |
582 | environment variable. This allows |
583 | daemons to automatically enable the | |
584 | keep-alive pinging logic if watchdog | |
585 | support is enabled for the service. If | |
79640424 | 586 | this option is used, |
02c4ef9c LP |
587 | <varname>NotifyAccess=</varname> (see |
588 | below) should be set to open access to | |
589 | the notification socket provided by | |
590 | systemd. If | |
dac051ad LP |
591 | <varname>NotifyAccess=</varname> is |
592 | not set, it will be implicitly set to | |
02c4ef9c | 593 | <option>main</option>. Defaults to 0, |
e8ab3ccb LP |
594 | which disables this |
595 | feature.</para></listitem> | |
bb242b7b MO |
596 | </varlistentry> |
597 | ||
0d624a78 LP |
598 | <varlistentry> |
599 | <term><varname>Restart=</varname></term> | |
600 | <listitem><para>Configures whether the | |
a827e373 ZJS |
601 | service shall be restarted when the |
602 | service process exits, is killed, | |
603 | or a timeout is reached. The service | |
604 | process may be the main service | |
605 | process, but also one of the processes | |
606 | specified with | |
607 | <varname>ExecStartPre=</varname>, | |
608 | <varname>ExecStartPost=</varname>, | |
609 | <varname>ExecStopPre=</varname>, | |
610 | <varname>ExecStopPost=</varname>, or | |
611 | <varname>ExecReload=</varname>. | |
612 | When the death of the process is a | |
613 | result of systemd operation (e.g. service | |
614 | stop or restart), the service will not be | |
615 | restarted. Timeouts include missing | |
616 | the watchdog "keep-alive ping" | |
617 | deadline and a service start, reload, | |
618 | and stop operation timeouts.</para> | |
619 | ||
620 | <para>Takes one of | |
525ee6f4 | 621 | <option>no</option>, |
50caaedb LP |
622 | <option>on-success</option>, |
623 | <option>on-failure</option>, | |
dc99a976 | 624 | <option>on-watchdog</option>, |
a827e373 | 625 | <option>on-abort</option>, or |
50caaedb | 626 | <option>always</option>. If set to |
79640424 | 627 | <option>no</option> (the default), the |
a827e373 | 628 | service will not be restarted. If set to |
79640424 | 629 | <option>on-success</option>, it will be |
a827e373 ZJS |
630 | restarted only when the service process |
631 | exits cleanly. | |
632 | In this context, a clean exit means | |
633 | an exit code of 0, or one of the signals | |
05cc7267 | 634 | <constant>SIGHUP</constant>, <constant>SIGINT</constant>, <constant>SIGTERM</constant>, or <constant>SIGPIPE</constant>, and |
d2bbca68 | 635 | additionally, exit statuses and signals |
a827e373 | 636 | specified in <varname>SuccessExitStatus=</varname>. |
79640424 | 637 | If set to <option>on-failure</option>, |
a827e373 ZJS |
638 | the service will be restarted when the |
639 | process exits with an nonzero exit code, | |
640 | is terminated by a signal (including on | |
5389fedd | 641 | core dump), when an operation (such as |
a827e373 ZJS |
642 | service reload) times out, and when the |
643 | configured watchdog timeout is triggered. | |
644 | If set to | |
79640424 | 645 | <option>on-abort</option>, the service |
a827e373 ZJS |
646 | will be restarted only if the service |
647 | process exits due to an uncaught | |
648 | signal not specified as a clean exit | |
649 | status. | |
650 | If set to | |
79640424 | 651 | <option>on-watchdog</option>, the service |
dc99a976 HR |
652 | will be restarted only if the watchdog |
653 | timeout for the service expires. | |
654 | If set to | |
79640424 | 655 | <option>always</option>, the service |
5389fedd LP |
656 | will be restarted regardless whether |
657 | it exited cleanly or not, got | |
658 | terminated abnormally by a signal or | |
a827e373 ZJS |
659 | hit a timeout.</para> |
660 | ||
661 | <para>In addition to the above settings, | |
662 | the service will not be restarted if the | |
663 | exit code or signal is specified in | |
664 | <varname>RestartPreventExitStatus=</varname> | |
665 | (see below).</para></listitem> | |
0d624a78 LP |
666 | </varlistentry> |
667 | ||
96342de6 | 668 | <varlistentry> |
abdf7993 LP |
669 | <term><varname>SuccessExitStatus=</varname></term> |
670 | <listitem><para>Takes a list of exit | |
671 | status definitions that when returned | |
672 | by the main service process will be | |
673 | considered successful termination, in | |
674 | addition to the normal successful exit | |
05cc7267 ZJS |
675 | code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>, |
676 | <constant>SIGTERM</constant> and <constant>SIGPIPE</constant>. Exit status | |
abdf7993 | 677 | definitions can either be numeric exit |
a827e373 ZJS |
678 | codes or termination signal names, |
679 | separated by spaces. Example: | |
909f413d | 680 | <literal>SuccessExitStatus=1 2 8 |
05cc7267 | 681 | <constant>SIGKILL</constant></literal>, ensures that exit |
abdf7993 | 682 | codes 1, 2, 8 and the termination |
05cc7267 | 683 | signal <constant>SIGKILL</constant> are considered clean |
74051b9b LP |
684 | service terminations. This option may |
685 | appear more than once in which case | |
686 | the list of successful exit statuses | |
687 | is merged. If the empty string is | |
79640424 | 688 | assigned to this option, the list is |
74051b9b LP |
689 | reset, all prior assignments of this |
690 | option will have no | |
691 | effect.</para></listitem> | |
96342de6 LN |
692 | </varlistentry> |
693 | ||
694 | <varlistentry> | |
abdf7993 LP |
695 | <term><varname>RestartPreventExitStatus=</varname></term> |
696 | <listitem><para>Takes a list of exit | |
697 | status definitions that when returned | |
698 | by the main service process will | |
699 | prevent automatic service restarts | |
700 | regardless of the restart setting | |
701 | configured with | |
702 | <varname>Restart=</varname>. Exit | |
703 | status definitions can either be | |
704 | numeric exit codes or termination | |
705 | signal names, and are separated by | |
706 | spaces. Defaults to the empty list, so | |
707 | that by default no exit status is | |
708 | excluded from the configured restart | |
709 | logic. Example: | |
909f413d ZJS |
710 | <literal>RestartPreventExitStatus=1 6 |
711 | SIGABRT</literal>, ensures that exit | |
74051b9b LP |
712 | codes 1 and 6 and the termination |
713 | signal SIGABRT will not result in | |
714 | automatic service restarting. This | |
715 | option may appear more than once in | |
716 | which case the list of restart preventing | |
717 | statuses is merged. If the empty | |
79640424 | 718 | string is assigned to this option, the |
74051b9b LP |
719 | list is reset, all prior assignments |
720 | of this option will have no | |
721 | effect.</para></listitem> | |
96342de6 LN |
722 | </varlistentry> |
723 | ||
0d624a78 LP |
724 | <varlistentry> |
725 | <term><varname>PermissionsStartOnly=</varname></term> | |
726 | <listitem><para>Takes a boolean | |
727 | argument. If true, the permission | |
728 | related execution options as | |
729 | configured with | |
730 | <varname>User=</varname> and similar | |
731 | options (see | |
732 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
733 | for more information) are only applied | |
734 | to the process started with | |
735 | <varname>ExecStart=</varname>, and not | |
736 | to the various other | |
737 | <varname>ExecStartPre=</varname>, | |
738 | <varname>ExecStartPost=</varname>, | |
739 | <varname>ExecReload=</varname>, | |
740 | <varname>ExecStop=</varname>, | |
741 | <varname>ExecStopPost=</varname> | |
742 | commands. If false, the setting is | |
743 | applied to all configured commands the | |
744 | same way. Defaults to | |
745 | false.</para></listitem> | |
746 | </varlistentry> | |
747 | ||
748 | <varlistentry> | |
749 | <term><varname>RootDirectoryStartOnly=</varname></term> | |
750 | <listitem><para>Takes a boolean | |
751 | argument. If true, the root directory | |
752 | as configured with the | |
753 | <varname>RootDirectory=</varname> | |
754 | option (see | |
755 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
756 | for more information) is only applied | |
757 | to the process started with | |
758 | <varname>ExecStart=</varname>, and not | |
759 | to the various other | |
760 | <varname>ExecStartPre=</varname>, | |
761 | <varname>ExecStartPost=</varname>, | |
762 | <varname>ExecReload=</varname>, | |
763 | <varname>ExecStop=</varname>, | |
764 | <varname>ExecStopPost=</varname> | |
765 | commands. If false, the setting is | |
766 | applied to all configured commands the | |
767 | same way. Defaults to | |
768 | false.</para></listitem> | |
769 | </varlistentry> | |
770 | ||
0d624a78 LP |
771 | <varlistentry> |
772 | <term><varname>NonBlocking=</varname></term> | |
773 | <listitem><para>Set O_NONBLOCK flag | |
774 | for all file descriptors passed via | |
775 | socket-based activation. If true, all | |
776 | file descriptors >= 3 (i.e. all except | |
777 | STDIN/STDOUT/STDERR) will have | |
778 | the O_NONBLOCK flag set and hence are in | |
779 | non-blocking mode. This option is only | |
780 | useful in conjunction with a socket | |
781 | unit, as described in | |
782 | <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults | |
783 | to false.</para></listitem> | |
784 | </varlistentry> | |
785 | ||
786 | <varlistentry> | |
787 | <term><varname>NotifyAccess=</varname></term> | |
788 | <listitem><para>Controls access to the | |
789 | service status notification socket, as | |
790 | accessible via the | |
791 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
792 | call. Takes one of | |
793 | <option>none</option> (the default), | |
794 | <option>main</option> or | |
795 | <option>all</option>. If | |
79640424 | 796 | <option>none</option>, no daemon status |
f8553ccb | 797 | updates are accepted from the service |
0d624a78 | 798 | processes, all status update messages |
79640424 | 799 | are ignored. If <option>main</option>, |
0d624a78 LP |
800 | only service updates sent from the |
801 | main process of the service are | |
79640424 | 802 | accepted. If <option>all</option>, all |
0d624a78 LP |
803 | services updates from all members of |
804 | the service's control group are | |
02c4ef9c | 805 | accepted. This option should be set to |
0d624a78 LP |
806 | open access to the notification socket |
807 | when using | |
02c4ef9c | 808 | <varname>Type=notify</varname> or |
28137202 | 809 | <varname>WatchdogSec=</varname> (see |
02c4ef9c | 810 | above). If those options are used but |
79640424 JE |
811 | <varname>NotifyAccess=</varname> is not |
812 | configured, it will be implicitly set | |
02c4ef9c LP |
813 | to |
814 | <option>main</option>.</para></listitem> | |
d1ab0ca0 LP |
815 | </varlistentry> |
816 | ||
f72192c0 LP |
817 | <varlistentry> |
818 | <term><varname>Sockets=</varname></term> | |
819 | <listitem><para>Specifies the name of | |
820 | the socket units this service shall | |
821 | inherit the sockets from when the | |
4f025f4c | 822 | service is started. Normally it |
f72192c0 LP |
823 | should not be necessary to use this |
824 | setting as all sockets whose unit | |
825 | shares the same name as the service | |
4f025f4c | 826 | (ignoring the different suffix of course) |
f72192c0 LP |
827 | are passed to the spawned |
828 | process.</para> | |
829 | ||
830 | <para>Note that the same socket may be | |
831 | passed to multiple processes at the | |
832 | same time. Also note that a different | |
833 | service may be activated on incoming | |
834 | traffic than inherits the sockets. Or | |
74051b9b | 835 | in other words: the |
f72192c0 LP |
836 | <varname>Service=</varname> setting of |
837 | <filename>.socket</filename> units | |
6b4991cf | 838 | does not have to match the inverse of |
74051b9b LP |
839 | the <varname>Sockets=</varname> |
840 | setting of the | |
841 | <filename>.service</filename> it | |
842 | refers to.</para> | |
843 | ||
844 | <para>This option may appear more than | |
845 | once, in which case the list of socket | |
846 | units is merged. If the empty string | |
79640424 | 847 | is assigned to this option, the list of |
74051b9b LP |
848 | sockets is reset, all prior uses of |
849 | this setting will have no | |
850 | effect.</para></listitem> | |
f72192c0 LP |
851 | </varlistentry> |
852 | ||
092317d0 LP |
853 | <varlistentry> |
854 | <term><varname>StartLimitInterval=</varname></term> | |
855 | <term><varname>StartLimitBurst=</varname></term> | |
856 | ||
857 | <listitem><para>Configure service | |
79640424 | 858 | start rate limiting. By default, |
092317d0 LP |
859 | services which are started more often |
860 | than 5 times within 10s are not | |
861 | permitted to start any more times | |
862 | until the 10s interval ends. With | |
79640424 | 863 | these two options, this rate limiting |
092317d0 LP |
864 | may be modified. Use |
865 | <varname>StartLimitInterval=</varname> | |
3f41e1e5 LN |
866 | to configure the checking interval (defaults to |
867 | <varname>DefaultStartLimitInterval=</varname> in | |
868 | manager configuration file, set to 0 to disable | |
092317d0 LP |
869 | any kind of rate limiting). Use |
870 | <varname>StartLimitBurst=</varname> to | |
871 | configure how many starts per interval | |
3f41e1e5 LN |
872 | are allowed (defaults to |
873 | <varname>DefaultStartLimitBurst=</varname> in | |
874 | manager configuration file). These | |
092317d0 LP |
875 | configuration options are particularly |
876 | useful in conjunction with | |
6ffd3337 LP |
877 | <varname>Restart=</varname>, however |
878 | apply to all kinds of starts | |
879 | (including manual), not just those | |
880 | triggered by the | |
881 | <varname>Restart=</varname> logic. | |
882 | Note that units which are configured | |
883 | for <varname>Restart=</varname> and | |
884 | which reach the start limit are not | |
f1c8f75b LP |
885 | attempted to be restarted anymore, |
886 | however they may still be restarted | |
887 | manually at a later point from which | |
888 | point on the restart logic is again | |
451b34cc LP |
889 | activated. Note that |
890 | <command>systemctl | |
891 | reset-failed</command> will cause the | |
892 | restart rate counter for a service to | |
893 | be flushed, which is useful if the | |
894 | administrator wants to manually start | |
895 | a service and the start limit | |
896 | interferes with | |
897 | that.</para></listitem> | |
092317d0 LP |
898 | </varlistentry> |
899 | ||
900 | <varlistentry> | |
901 | <term><varname>StartLimitAction=</varname></term> | |
902 | ||
903 | <listitem><para>Configure the action | |
904 | to take if the rate limit configured | |
905 | with | |
906 | <varname>StartLimitInterval=</varname> | |
907 | and | |
908 | <varname>StartLimitBurst=</varname> is | |
909 | hit. Takes one of | |
910 | <option>none</option>, | |
911 | <option>reboot</option>, | |
912 | <option>reboot-force</option> or | |
913 | <option>reboot-immediate</option>. If | |
914 | <option>none</option> is set, | |
915 | hitting the rate limit will trigger no | |
916 | action besides that the start will not | |
917 | be | |
918 | permitted. <option>reboot</option> | |
919 | causes a reboot following the normal | |
920 | shutdown procedure (i.e. equivalent to | |
921 | <command>systemctl reboot</command>), | |
922 | <option>reboot-force</option> causes | |
923 | an forced reboot which will terminate | |
924 | all processes forcibly but should | |
925 | cause no dirty file systems on reboot | |
926 | (i.e. equivalent to <command>systemctl | |
927 | reboot -f</command>) and | |
928 | <option>reboot-immediate</option> | |
929 | causes immediate execution of the | |
930 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
931 | system call, which might result in | |
932 | data loss. Defaults to | |
933 | <option>none</option>.</para></listitem> | |
934 | </varlistentry> | |
935 | ||
d1ab0ca0 | 936 | </variablelist> |
4819ff03 LP |
937 | |
938 | <para>Check | |
939 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
940 | and | |
941 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
942 | for more settings.</para> | |
943 | ||
d1ab0ca0 LP |
944 | </refsect1> |
945 | ||
c485d3ba LP |
946 | <refsect1> |
947 | <title>Compatibility Options</title> | |
948 | ||
949 | <para>The following options are also available in the | |
950 | <literal>[Service]</literal> section, but exist purely | |
951 | for compatibility reasons and should not be used in | |
952 | newly written service files.</para> | |
953 | ||
ccc9a4f9 | 954 | <variablelist class='unit-directives'> |
c485d3ba LP |
955 | <varlistentry> |
956 | <term><varname>SysVStartPriority=</varname></term> | |
957 | <listitem><para>Set the SysV start | |
958 | priority to use to order this service | |
959 | in relation to SysV services lacking | |
960 | LSB headers. This option is only | |
961 | necessary to fix ordering in relation | |
962 | to legacy SysV services, that have no | |
963 | ordering information encoded in the | |
964 | script headers. As such it should only | |
965 | be used as temporary compatibility | |
966 | option, and not be used in new unit | |
967 | files. Almost always it is a better | |
968 | choice to add explicit ordering | |
969 | directives via | |
970 | <varname>After=</varname> or | |
971 | <varname>Before=</varname>, | |
972 | instead. For more details see | |
973 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If | |
974 | used, pass an integer value in the | |
975 | range 0-99.</para></listitem> | |
976 | </varlistentry> | |
977 | ||
c485d3ba LP |
978 | </variablelist> |
979 | </refsect1> | |
980 | ||
d1ab0ca0 LP |
981 | <refsect1> |
982 | <title>See Also</title> | |
983 | <para> | |
f3e219a2 | 984 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
0d624a78 LP |
985 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
986 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
4819ff03 | 987 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
3fde5f30 | 988 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
9cc2c8b7 ZJS |
989 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
990 | <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
d1ab0ca0 LP |
991 | </para> |
992 | </refsect1> | |
993 | ||
994 | </refentry> |