]>
Commit | Line | Data |
---|---|---|
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.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
80 | which configure resource control 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 | if neither | |
143 | <varname>Type=</varname> nor | |
144 | <varname>BusName=</varname>, but | |
145 | <varname>ExecStart=</varname> are | |
146 | specified), it is expected that the | |
147 | process configured with | |
148 | <varname>ExecStart=</varname> is the | |
149 | main process of the service. In this | |
150 | mode, if the process offers | |
151 | functionality to other processes on | |
152 | the system, its communication channels | |
153 | should be installed before the daemon | |
154 | is started up (e.g. sockets set up by | |
155 | systemd, via socket activation), as | |
156 | systemd will immediately proceed | |
157 | starting follow-up units.</para> | |
158 | ||
159 | <para>If set to | |
160 | <option>forking</option>, it is | |
161 | expected that the process configured | |
162 | with <varname>ExecStart=</varname> | |
163 | will call <function>fork()</function> | |
164 | as part of its start-up. The parent process is | |
165 | expected to exit when start-up is | |
166 | complete and all communication | |
167 | channels are set up. The child continues | |
168 | to run as the main daemon | |
169 | process. This is the behavior of | |
170 | traditional UNIX daemons. If this | |
171 | setting is used, it is recommended to | |
172 | also use the | |
173 | <varname>PIDFile=</varname> option, so | |
174 | that systemd can identify the main | |
175 | process of the daemon. systemd will | |
176 | proceed with starting follow-up units | |
177 | as soon as the parent process | |
178 | exits.</para> | |
179 | ||
180 | <para>Behavior of | |
181 | <option>oneshot</option> is similar to | |
182 | <option>simple</option>; however, it | |
183 | is expected that the process has to | |
184 | exit before systemd starts follow-up | |
185 | units. <varname>RemainAfterExit=</varname> | |
186 | is particularly useful for this type | |
187 | of service. This is the implied | |
188 | default if neither | |
189 | <varname>Type=</varname> or | |
190 | <varname>ExecStart=</varname> are | |
191 | specified.</para> | |
192 | ||
193 | <para>Behavior of | |
194 | <option>dbus</option> is similar to | |
195 | <option>simple</option>; however, it is | |
196 | expected that the daemon acquires a | |
197 | name on the D-Bus bus, as configured | |
198 | by | |
199 | <varname>BusName=</varname>. systemd | |
200 | will proceed with starting follow-up | |
201 | units after the D-Bus bus name has been | |
202 | acquired. Service units with this | |
203 | option configured implicitly gain | |
204 | dependencies on the | |
205 | <filename>dbus.socket</filename> | |
206 | unit. This type is the default if | |
207 | <varname>BusName=</varname> is | |
208 | specified.</para> | |
209 | ||
210 | <para>Behavior of | |
211 | <option>notify</option> is similar to | |
212 | <option>simple</option>; however, it is | |
213 | expected that the daemon sends a | |
214 | notification message via | |
215 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
216 | or an equivalent call when it has finished | |
217 | starting up. systemd will proceed with | |
218 | starting follow-up units after this | |
219 | notification message has been sent. If | |
220 | this option is used, | |
221 | <varname>NotifyAccess=</varname> (see | |
222 | below) should be set to open access to | |
223 | the notification socket provided by | |
224 | systemd. If | |
225 | <varname>NotifyAccess=</varname> is | |
226 | not set, it will be implicitly set to | |
227 | <option>main</option>. Note that | |
228 | currently | |
229 | <varname>Type=</varname><option>notify</option> | |
230 | will not work if used in combination with | |
231 | <varname>PrivateNetwork=</varname><option>yes</option>.</para> | |
232 | ||
233 | <para>Behavior of | |
234 | <option>idle</option> is very similar | |
235 | to <option>simple</option>; however, | |
236 | actual execution of the service | |
237 | binary is delayed until all jobs are | |
238 | dispatched. This may be used to avoid | |
239 | interleaving of output of shell | |
240 | services with the status output on the | |
241 | console.</para> | |
242 | </listitem> | |
243 | </varlistentry> | |
244 | ||
245 | <varlistentry> | |
246 | <term><varname>RemainAfterExit=</varname></term> | |
247 | ||
248 | <listitem><para>Takes a boolean value | |
249 | that specifies whether the service | |
250 | shall be considered active even when | |
251 | all its processes exited. Defaults to | |
252 | <option>no</option>.</para> | |
253 | </listitem> | |
254 | </varlistentry> | |
255 | ||
256 | <varlistentry> | |
257 | <term><varname>GuessMainPID=</varname></term> | |
258 | ||
259 | <listitem><para>Takes a boolean value | |
260 | that specifies whether systemd should | |
261 | try to guess the main PID of a service | |
262 | if it cannot be determined | |
263 | reliably. This option is ignored | |
264 | unless <option>Type=forking</option> | |
265 | is set and <option>PIDFile=</option> | |
266 | is unset because for the other types | |
267 | or with an explicitly configured PID | |
268 | file, the main PID is always known. The | |
269 | guessing algorithm might come to | |
270 | incorrect conclusions if a daemon | |
271 | consists of more than one process. If | |
272 | the main PID cannot be determined, | |
273 | failure detection and automatic | |
274 | restarting of a service will not work | |
275 | reliably. Defaults to | |
276 | <option>yes</option>.</para> | |
277 | </listitem> | |
278 | </varlistentry> | |
279 | ||
280 | <varlistentry> | |
281 | <term><varname>PIDFile=</varname></term> | |
282 | ||
283 | <listitem><para>Takes an absolute file | |
284 | name pointing to the PID file of this | |
285 | daemon. Use of this option is | |
286 | recommended for services where | |
287 | <varname>Type=</varname> is set to | |
288 | <option>forking</option>. systemd will | |
289 | read the PID of the main process of | |
290 | the daemon after start-up of the | |
291 | service. systemd will not write to the | |
292 | file configured here.</para> | |
293 | </listitem> | |
294 | </varlistentry> | |
295 | ||
296 | <varlistentry> | |
297 | <term><varname>BusName=</varname></term> | |
298 | ||
299 | <listitem><para>Takes a D-Bus bus | |
300 | name that this service is reachable | |
301 | as. This option is mandatory for | |
302 | services where | |
303 | <varname>Type=</varname> is set to | |
304 | <option>dbus</option>.</para> | |
305 | </listitem> | |
306 | </varlistentry> | |
307 | ||
308 | <varlistentry> | |
309 | <term><varname>BusPolicy=</varname></term> | |
310 | ||
311 | <listitem><para>If specified, a custom | |
312 | <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink> | |
313 | endpoint will be created and installed as the | |
314 | default bus node for the service. Such a custom | |
315 | endpoint can hold an own set of policy rules | |
316 | that are enforced on top of the bus-wide ones. | |
317 | The custom endpoint is named after the service | |
318 | it was created for, and its node will be | |
319 | bind-mounted over the default bus node | |
320 | location, so the service can only access the | |
321 | bus through its own endpoint. Note that custom | |
322 | bus endpoints default to a 'deny all' policy. | |
323 | Hence, if at least one | |
324 | <varname>BusPolicy=</varname> directive is | |
325 | given, you have to make sure to add explicit | |
326 | rules for everything the service should be able | |
327 | to do.</para> | |
328 | <para>The value of this directive is comprised | |
329 | of two parts; the bus name, and a verb to | |
330 | specify to granted access, which is one of | |
331 | <option>see</option>, | |
332 | <option>talk</option>, or | |
333 | <option>own</option>. | |
334 | <option>talk</option> implies | |
335 | <option>see</option>, and <option>own</option> | |
336 | implies both <option>talk</option> and | |
337 | <option>see</option>. | |
338 | If multiple access levels are specified for the | |
339 | same bus name, the most powerful one takes | |
340 | effect. | |
341 | </para> | |
342 | <para>Examples:</para> | |
343 | <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting> | |
344 | <programlisting>BusPolicy=org.foo.bar see</programlisting> | |
345 | <para>This option is only available on kdbus enabled systems.</para> | |
346 | </listitem> | |
347 | </varlistentry> | |
348 | ||
349 | <varlistentry> | |
350 | <term><varname>ExecStart=</varname></term> | |
351 | <listitem><para>Commands with their | |
352 | arguments that are executed when this | |
353 | service is started. The value is split | |
354 | into zero or more command lines is | |
355 | according to the rules described below | |
356 | (see section "Command Lines" below). | |
357 | </para> | |
358 | ||
359 | <para>When <varname>Type</varname> is | |
360 | not <option>oneshot</option>, only one | |
361 | command may and must be given. When | |
362 | <varname>Type=oneshot</varname> is | |
363 | used, zero or more commands may be | |
364 | specified. This can be specified by | |
365 | providing multiple command lines in | |
366 | the same directive, or alternatively, | |
367 | this directive may be specified more | |
368 | than once with the same effect. If the | |
369 | empty string is assigned to this | |
370 | option, the list of commands to start | |
371 | is reset, prior assignments of this | |
372 | option will have no effect. If no | |
373 | <varname>ExecStart=</varname> is | |
374 | specified, then the service must have | |
375 | <varname>RemainAfterExit=yes</varname> | |
376 | set.</para> | |
377 | ||
378 | <para>For each of the specified | |
379 | commands, the first argument must be | |
380 | an absolute path to an executable. | |
381 | Optionally, if this file name is | |
382 | prefixed with <literal>@</literal>, | |
383 | the second token will be passed as | |
384 | <literal>argv[0]</literal> to the | |
385 | executed process, followed by the | |
386 | further arguments specified. If the | |
387 | absolute filename is prefixed with | |
388 | <literal>-</literal>, an exit code of | |
389 | the command normally considered a | |
390 | failure (i.e. non-zero exit status or | |
391 | abnormal exit due to signal) is | |
392 | ignored and considered success. If | |
393 | both <literal>-</literal> and | |
394 | <literal>@</literal> are used, they | |
395 | can appear in either order.</para> | |
396 | ||
397 | <para>If more than one command is | |
398 | specified, the commands are invoked | |
399 | sequentially in the order they appear | |
400 | in the unit file. If one of the | |
401 | commands fails (and is not prefixed | |
402 | with <literal>-</literal>), other | |
403 | lines are not executed, and the unit | |
404 | is considered failed.</para> | |
405 | ||
406 | <para>Unless | |
407 | <varname>Type=forking</varname> is | |
408 | set, the process started via this | |
409 | command line will be considered the | |
410 | main process of the daemon.</para> | |
411 | ||
412 | </listitem> | |
413 | </varlistentry> | |
414 | ||
415 | <varlistentry> | |
416 | <term><varname>ExecStartPre=</varname></term> | |
417 | <term><varname>ExecStartPost=</varname></term> | |
418 | <listitem><para>Additional commands | |
419 | that are executed before or after | |
420 | the command in | |
421 | <varname>ExecStart=</varname>, respectively. | |
422 | Syntax is the same as for | |
423 | <varname>ExecStart=</varname>, except | |
424 | that multiple command lines are allowed | |
425 | and the commands are executed one | |
426 | after the other, serially.</para> | |
427 | ||
428 | <para>If any of those commands (not | |
429 | prefixed with <literal>-</literal>) | |
430 | fail, the rest are not executed and | |
431 | the unit is considered failed.</para> | |
432 | </listitem> | |
433 | </varlistentry> | |
434 | ||
435 | <varlistentry> | |
436 | <term><varname>ExecReload=</varname></term> | |
437 | <listitem><para>Commands to execute to | |
438 | trigger a configuration reload in the | |
439 | service. This argument takes multiple | |
440 | command lines, following the same | |
441 | scheme as described for | |
442 | <varname>ExecStart=</varname> | |
443 | above. Use of this setting is | |
444 | optional. Specifier and environment | |
445 | variable substitution is supported | |
446 | here following the same scheme as for | |
447 | <varname>ExecStart=</varname>.</para> | |
448 | ||
449 | <para>One additional, special | |
450 | environment variable is set: if known, | |
451 | <varname>$MAINPID</varname> is set to | |
452 | the main process of the daemon, and | |
453 | may be used for command lines like the | |
454 | following:</para> | |
455 | ||
456 | <programlisting>/bin/kill -HUP $MAINPID</programlisting> | |
457 | ||
458 | <para>Note however that reloading a | |
459 | daemon by sending a signal (as with | |
460 | the example line above) is usually not | |
461 | a good choice, because this is an | |
462 | asynchronous operation and hence not | |
463 | suitable to order reloads of multiple | |
464 | services against each other. It is | |
465 | strongly recommended to set | |
466 | <varname>ExecReload=</varname> to a | |
467 | command that not only triggers a | |
468 | configuration reload of the daemon, | |
469 | but also synchronously waits for it to | |
470 | complete.</para> | |
471 | </listitem> | |
472 | </varlistentry> | |
473 | ||
474 | <varlistentry> | |
475 | <term><varname>ExecStop=</varname></term> | |
476 | <listitem><para>Commands to execute to | |
477 | stop the service started via | |
478 | <varname>ExecStart=</varname>. This | |
479 | argument takes multiple command lines, | |
480 | following the same scheme as described | |
481 | for <varname>ExecStart=</varname> | |
482 | above. Use of this setting is | |
483 | optional. After the commands configured | |
484 | in this option are run, all processes | |
485 | remaining for a service are | |
486 | terminated according to the | |
487 | <varname>KillMode=</varname> setting | |
488 | (see | |
489 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If | |
490 | this option is not specified, the | |
491 | process is terminated immediately when | |
492 | service stop is requested. Specifier | |
493 | and environment variable substitution | |
494 | is supported (including | |
495 | <varname>$MAINPID</varname>, see | |
496 | above).</para></listitem> | |
497 | </varlistentry> | |
498 | ||
499 | <varlistentry> | |
500 | <term><varname>ExecStopPost=</varname></term> | |
501 | <listitem><para>Additional commands | |
502 | that are executed after the service | |
503 | was stopped. This includes cases where | |
504 | the commands configured in | |
505 | <varname>ExecStop=</varname> were used, | |
506 | where the service does not have any | |
507 | <varname>ExecStop=</varname> defined, or | |
508 | where the service exited unexpectedly. This | |
509 | argument takes multiple command lines, | |
510 | following the same scheme as described | |
511 | for <varname>ExecStart</varname>. Use | |
512 | of these settings is | |
513 | optional. Specifier and environment | |
514 | variable substitution is | |
515 | supported.</para></listitem> | |
516 | </varlistentry> | |
517 | ||
518 | <varlistentry> | |
519 | <term><varname>RestartSec=</varname></term> | |
520 | <listitem><para>Configures the time to | |
521 | sleep before restarting a service (as | |
522 | configured with | |
523 | <varname>Restart=</varname>). Takes a | |
524 | unit-less value in seconds, or a time | |
525 | span value such as "5min | |
526 | 20s". Defaults to | |
527 | 100ms.</para></listitem> | |
528 | </varlistentry> | |
529 | ||
530 | <varlistentry> | |
531 | <term><varname>TimeoutStartSec=</varname></term> | |
532 | <listitem><para>Configures the time to | |
533 | wait for start-up. If a | |
534 | daemon service does not signal | |
535 | start-up completion within the | |
536 | configured time, the service will be | |
537 | considered failed and will be shut | |
538 | down again. | |
539 | Takes a unit-less value in seconds, or a | |
540 | time span value such as "5min | |
541 | 20s". Pass <literal>0</literal> to | |
542 | disable the timeout logic. Defaults to | |
543 | <varname>DefaultTimeoutStartSec=</varname> from | |
544 | the manager configuration file, except | |
545 | when <varname>Type=oneshot</varname> is | |
546 | used, in which case the timeout | |
547 | is disabled by default | |
548 | (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
549 | </para></listitem> | |
550 | </varlistentry> | |
551 | ||
552 | <varlistentry> | |
553 | <term><varname>TimeoutStopSec=</varname></term> | |
554 | <listitem><para>Configures the time to | |
555 | wait for stop. If a service is asked | |
556 | to stop, but does not terminate in the | |
557 | specified time, it will be terminated | |
558 | forcibly via <constant>SIGTERM</constant>, | |
559 | and after another timeout of equal duration | |
560 | with <constant>SIGKILL</constant> (see | |
561 | <varname>KillMode=</varname> | |
562 | in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
563 | Takes a unit-less value in seconds, or a | |
564 | time span value such as "5min | |
565 | 20s". Pass <literal>0</literal> to disable | |
566 | the timeout logic. Defaults to | |
567 | <varname>DefaultTimeoutStopSec=</varname> from the | |
568 | manager configuration file | |
569 | (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
570 | </para></listitem> | |
571 | </varlistentry> | |
572 | ||
573 | <varlistentry> | |
574 | <term><varname>TimeoutSec=</varname></term> | |
575 | <listitem><para>A shorthand for configuring | |
576 | both <varname>TimeoutStartSec=</varname> | |
577 | and <varname>TimeoutStopSec=</varname> | |
578 | to the specified value. | |
579 | </para></listitem> | |
580 | </varlistentry> | |
581 | ||
582 | <varlistentry> | |
583 | <term><varname>WatchdogSec=</varname></term> | |
584 | <listitem><para>Configures the | |
585 | watchdog timeout for a service. The | |
586 | watchdog is activated when the start-up is | |
587 | completed. The service must call | |
588 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
589 | regularly with <literal>WATCHDOG=1</literal> | |
590 | (i.e. the "keep-alive ping"). If the time | |
591 | between two such calls is larger than | |
592 | the configured time, then the service | |
593 | is placed in a failed state and it will | |
594 | be terminated with <varname>SIGABRT</varname>. | |
595 | By setting <varname>Restart=</varname> to | |
596 | <option>on-failure</option> or | |
597 | <option>always</option>, the service | |
598 | will be automatically restarted. The | |
599 | time configured here will be passed to | |
600 | the executed service process in the | |
601 | <varname>WATCHDOG_USEC=</varname> | |
602 | environment variable. This allows | |
603 | daemons to automatically enable the | |
604 | keep-alive pinging logic if watchdog | |
605 | support is enabled for the service. If | |
606 | this option is used, | |
607 | <varname>NotifyAccess=</varname> (see | |
608 | below) should be set to open access to | |
609 | the notification socket provided by | |
610 | systemd. If | |
611 | <varname>NotifyAccess=</varname> is | |
612 | not set, it will be implicitly set to | |
613 | <option>main</option>. Defaults to 0, | |
614 | which disables this | |
615 | feature.</para></listitem> | |
616 | </varlistentry> | |
617 | ||
618 | <varlistentry> | |
619 | <term><varname>Restart=</varname></term> | |
620 | <listitem><para>Configures whether the | |
621 | service shall be restarted when the | |
622 | service process exits, is killed, | |
623 | or a timeout is reached. The service | |
624 | process may be the main service | |
625 | process, but it may also be one of the | |
626 | processes specified with | |
627 | <varname>ExecStartPre=</varname>, | |
628 | <varname>ExecStartPost=</varname>, | |
629 | <varname>ExecStop=</varname>, | |
630 | <varname>ExecStopPost=</varname>, or | |
631 | <varname>ExecReload=</varname>. | |
632 | When the death of the process is a | |
633 | result of systemd operation (e.g. service | |
634 | stop or restart), the service will not be | |
635 | restarted. Timeouts include missing | |
636 | the watchdog "keep-alive ping" | |
637 | deadline and a service start, reload, | |
638 | and stop operation timeouts.</para> | |
639 | ||
640 | <para>Takes one of | |
641 | <option>no</option>, | |
642 | <option>on-success</option>, | |
643 | <option>on-failure</option>, | |
644 | <option>on-abnormal</option>, | |
645 | <option>on-watchdog</option>, | |
646 | <option>on-abort</option>, or | |
647 | <option>always</option>. If set to | |
648 | <option>no</option> (the default), the | |
649 | service will not be restarted. If set | |
650 | to <option>on-success</option>, it | |
651 | will be restarted only when the | |
652 | service process exits cleanly. In | |
653 | this context, a clean exit means an | |
654 | exit code of 0, or one of the signals | |
655 | <constant>SIGHUP</constant>, | |
656 | <constant>SIGINT</constant>, | |
657 | <constant>SIGTERM</constant> or | |
658 | <constant>SIGPIPE</constant>, and | |
659 | additionally, exit statuses and | |
660 | signals specified in | |
661 | <varname>SuccessExitStatus=</varname>. | |
662 | If set to <option>on-failure</option>, | |
663 | the service will be restarted when the | |
664 | process exits with a non-zero exit | |
665 | code, is terminated by a signal | |
666 | (including on core dump, but excluding | |
667 | the aforementiond four signals), when | |
668 | an operation (such as service reload) | |
669 | times out, and when the configured | |
670 | watchdog timeout is triggered. If set | |
671 | to <option>on-abnormal</option>, the | |
672 | service will be restarted when the | |
673 | process is terminated by a signal | |
674 | (including on core dump, excluding the | |
675 | aforementioned four signals), when an | |
676 | operation times out, or when the | |
677 | watchdog timeout is triggered. If set | |
678 | to <option>on-abort</option>, the | |
679 | service will be restarted only if the | |
680 | service process exits due to an | |
681 | uncaught signal not specified as a | |
682 | clean exit status. If set to | |
683 | <option>on-watchdog</option>, the | |
684 | service will be restarted only if the | |
685 | watchdog timeout for the service | |
686 | expires. If set to | |
687 | <option>always</option>, the service | |
688 | will be restarted regardless of | |
689 | whether it exited cleanly or not, got | |
690 | terminated abnormally by a signal, or | |
691 | hit a timeout.</para> | |
692 | ||
693 | <table> | |
694 | <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> | |
695 | ||
696 | <tgroup cols='2'> | |
697 | <colspec colname='path' /> | |
698 | <colspec colname='expl' /> | |
699 | <thead> | |
700 | <row> | |
701 | <entry>Restart settings/Exit causes</entry> | |
702 | <entry><option>no</option></entry> | |
703 | <entry><option>always</option></entry> | |
704 | <entry><option>on-success</option></entry> | |
705 | <entry><option>on-failure</option></entry> | |
706 | <entry><option>on-abnormal</option></entry> | |
707 | <entry><option>on-abort</option></entry> | |
708 | <entry><option>on-watchdog</option></entry> | |
709 | </row> | |
710 | </thead> | |
711 | <tbody> | |
712 | <row> | |
713 | <entry>Clean exit code or signal</entry> | |
714 | <entry/> | |
715 | <entry>X</entry> | |
716 | <entry>X</entry> | |
717 | <entry/> | |
718 | <entry/> | |
719 | <entry/> | |
720 | <entry/> | |
721 | </row> | |
722 | <row> | |
723 | <entry>Unclean exit code</entry> | |
724 | <entry/> | |
725 | <entry>X</entry> | |
726 | <entry/> | |
727 | <entry>X</entry> | |
728 | <entry/> | |
729 | <entry/> | |
730 | <entry/> | |
731 | </row> | |
732 | <row> | |
733 | <entry>Unclean signal</entry> | |
734 | <entry/> | |
735 | <entry>X</entry> | |
736 | <entry/> | |
737 | <entry>X</entry> | |
738 | <entry>X</entry> | |
739 | <entry>X</entry> | |
740 | <entry/> | |
741 | </row> | |
742 | <row> | |
743 | <entry>Timeout</entry> | |
744 | <entry/> | |
745 | <entry>X</entry> | |
746 | <entry/> | |
747 | <entry>X</entry> | |
748 | <entry>X</entry> | |
749 | <entry/> | |
750 | <entry/> | |
751 | </row> | |
752 | <row> | |
753 | <entry>Watchdog</entry> | |
754 | <entry/> | |
755 | <entry>X</entry> | |
756 | <entry/> | |
757 | <entry>X</entry> | |
758 | <entry>X</entry> | |
759 | <entry/> | |
760 | <entry>X</entry> | |
761 | </row> | |
762 | </tbody> | |
763 | </tgroup> | |
764 | </table> | |
765 | ||
766 | <para>As exceptions to the setting | |
767 | above the service will not be | |
768 | restarted if the exit code or signal | |
769 | is specified in | |
770 | <varname>RestartPreventExitStatus=</varname> | |
771 | (see below). Also, the services will | |
772 | always be restarted if the exit code | |
773 | or signal is specified in | |
774 | <varname>RestartForceExitStatus=</varname> | |
775 | (see below).</para> | |
776 | ||
777 | <para>Setting this to | |
778 | <option>on-failure</option> is the | |
779 | recommended choice for long-running | |
780 | services, in order to increase | |
781 | reliability by attempting automatic | |
782 | recovery from errors. For services | |
783 | that shall be able to terminate on | |
784 | their own choice (and avoid | |
785 | immediate restarting), | |
786 | <option>on-abnormal</option> is an | |
787 | alternative choice.</para> | |
788 | </listitem> | |
789 | </varlistentry> | |
790 | ||
791 | <varlistentry> | |
792 | <term><varname>SuccessExitStatus=</varname></term> | |
793 | <listitem><para>Takes a list of exit | |
794 | status definitions that when returned | |
795 | by the main service process will be | |
796 | considered successful termination, in | |
797 | addition to the normal successful exit | |
798 | code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>, | |
799 | <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status | |
800 | definitions can either be numeric exit | |
801 | codes or termination signal names, | |
802 | separated by spaces. For example: | |
803 | <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> | |
804 | ensures that exit codes 1, 2, 8 and | |
805 | the termination signal | |
806 | <constant>SIGKILL</constant> are | |
807 | considered clean service terminations. | |
808 | </para> | |
809 | ||
810 | <para>Note that if a process has a | |
811 | signal handler installed and exits by | |
812 | calling | |
813 | <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
814 | in response to a signal, the | |
815 | information about the signal is lost. | |
816 | Programs should instead perform cleanup and kill themselves with the same signal instead. See | |
817 | <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para> | |
818 | ||
819 | <para>This option may appear more than once, | |
820 | in which case the list of successful | |
821 | exit statuses is merged. If the empty | |
822 | string is assigned to this option, the | |
823 | list is reset, all prior assignments | |
824 | of this option will have no | |
825 | effect.</para></listitem> | |
826 | </varlistentry> | |
827 | ||
828 | <varlistentry> | |
829 | <term><varname>RestartPreventExitStatus=</varname></term> | |
830 | <listitem><para>Takes a list of exit | |
831 | status definitions that when returned | |
832 | by the main service process will | |
833 | prevent automatic service restarts, | |
834 | regardless of the restart setting | |
835 | configured with | |
836 | <varname>Restart=</varname>. Exit | |
837 | status definitions can either be | |
838 | numeric exit codes or termination | |
839 | signal names, and are separated by | |
840 | spaces. Defaults to the empty list, so | |
841 | that, by default, no exit status is | |
842 | excluded from the configured restart | |
843 | logic. For example: | |
844 | <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit | |
845 | codes 1 and 6 and the termination | |
846 | signal <constant>SIGABRT</constant> will | |
847 | not result in automatic service | |
848 | restarting. This | |
849 | option may appear more than once, in | |
850 | which case the list of restart-preventing | |
851 | statuses is merged. If the empty | |
852 | string is assigned to this option, the | |
853 | list is reset and all prior assignments | |
854 | of this option will have no | |
855 | effect.</para></listitem> | |
856 | </varlistentry> | |
857 | ||
858 | <varlistentry> | |
859 | <term><varname>RestartForceExitStatus=</varname></term> | |
860 | <listitem><para>Takes a list of exit | |
861 | status definitions that when returned | |
862 | by the main service process will force | |
863 | automatic service restarts, regardless | |
864 | of the restart setting configured with | |
865 | <varname>Restart=</varname>. The | |
866 | argument format is similar to | |
867 | <varname>RestartPreventExitStatus=</varname>.</para></listitem> | |
868 | </varlistentry> | |
869 | ||
870 | <varlistentry> | |
871 | <term><varname>PermissionsStartOnly=</varname></term> | |
872 | <listitem><para>Takes a boolean | |
873 | argument. If true, the permission-related | |
874 | execution options, as | |
875 | configured with | |
876 | <varname>User=</varname> and similar | |
877 | options (see | |
878 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
879 | for more information), are only applied | |
880 | to the process started with | |
881 | <varname>ExecStart=</varname>, and not | |
882 | to the various other | |
883 | <varname>ExecStartPre=</varname>, | |
884 | <varname>ExecStartPost=</varname>, | |
885 | <varname>ExecReload=</varname>, | |
886 | <varname>ExecStop=</varname>, and | |
887 | <varname>ExecStopPost=</varname> | |
888 | commands. If false, the setting is | |
889 | applied to all configured commands the | |
890 | same way. Defaults to | |
891 | false.</para></listitem> | |
892 | </varlistentry> | |
893 | ||
894 | <varlistentry> | |
895 | <term><varname>RootDirectoryStartOnly=</varname></term> | |
896 | <listitem><para>Takes a boolean | |
897 | argument. If true, the root directory, | |
898 | as configured with the | |
899 | <varname>RootDirectory=</varname> | |
900 | option (see | |
901 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
902 | for more information), is only applied | |
903 | to the process started with | |
904 | <varname>ExecStart=</varname>, and not | |
905 | to the various other | |
906 | <varname>ExecStartPre=</varname>, | |
907 | <varname>ExecStartPost=</varname>, | |
908 | <varname>ExecReload=</varname>, | |
909 | <varname>ExecStop=</varname>, and | |
910 | <varname>ExecStopPost=</varname> | |
911 | commands. If false, the setting is | |
912 | applied to all configured commands the | |
913 | same way. Defaults to | |
914 | false.</para></listitem> | |
915 | </varlistentry> | |
916 | ||
917 | <varlistentry> | |
918 | <term><varname>NonBlocking=</varname></term> | |
919 | <listitem><para>Set the | |
920 | <constant>O_NONBLOCK</constant> flag | |
921 | for all file descriptors passed via | |
922 | socket-based activation. If true, all | |
923 | file descriptors >= 3 (i.e. all except | |
924 | stdin, stdout, and stderr) will have | |
925 | the <constant>O_NONBLOCK</constant> flag | |
926 | set and hence are in | |
927 | non-blocking mode. This option is only | |
928 | useful in conjunction with a socket | |
929 | unit, as described in | |
930 | <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults | |
931 | to false.</para></listitem> | |
932 | </varlistentry> | |
933 | ||
934 | <varlistentry> | |
935 | <term><varname>NotifyAccess=</varname></term> | |
936 | <listitem><para>Controls access to the | |
937 | service status notification socket, as | |
938 | accessible via the | |
939 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
940 | call. Takes one of | |
941 | <option>none</option> (the default), | |
942 | <option>main</option> or | |
943 | <option>all</option>. If | |
944 | <option>none</option>, no daemon status | |
945 | updates are accepted from the service | |
946 | processes, all status update messages | |
947 | are ignored. If <option>main</option>, | |
948 | only service updates sent from the | |
949 | main process of the service are | |
950 | accepted. If <option>all</option>, all | |
951 | services updates from all members of | |
952 | the service's control group are | |
953 | accepted. This option should be set to | |
954 | open access to the notification socket | |
955 | when using | |
956 | <varname>Type=notify</varname> or | |
957 | <varname>WatchdogSec=</varname> (see | |
958 | above). If those options are used but | |
959 | <varname>NotifyAccess=</varname> is not | |
960 | configured, it will be implicitly set | |
961 | to | |
962 | <option>main</option>.</para></listitem> | |
963 | </varlistentry> | |
964 | ||
965 | <varlistentry> | |
966 | <term><varname>Sockets=</varname></term> | |
967 | <listitem><para>Specifies the name of | |
968 | the socket units this service shall | |
969 | inherit socket file descriptors | |
970 | from when the service is | |
971 | started. Normally it should not be | |
972 | necessary to use this setting as all | |
973 | socket file descriptors whose unit | |
974 | shares the same name as the service | |
975 | (subject to the different unit name | |
976 | suffix of course) are passed to the | |
977 | spawned process.</para> | |
978 | ||
979 | <para>Note that the same socket file | |
980 | descriptors may be passed to multiple | |
981 | processes simultaneously. Also note | |
982 | that a different service may be | |
983 | activated on incoming socket traffic | |
984 | than the one which is ultimately | |
985 | configured to inherit the socket file | |
986 | descriptors. Or in other words: the | |
987 | <varname>Service=</varname> setting of | |
988 | <filename>.socket</filename> units | |
989 | does not have to match the inverse of | |
990 | the <varname>Sockets=</varname> | |
991 | setting of the | |
992 | <filename>.service</filename> it | |
993 | refers to.</para> | |
994 | ||
995 | <para>This option may appear more than | |
996 | once, in which case the list of socket | |
997 | units is merged. If the empty string | |
998 | is assigned to this option, the list of | |
999 | sockets is reset, and all prior uses of | |
1000 | this setting will have no | |
1001 | effect.</para></listitem> | |
1002 | </varlistentry> | |
1003 | ||
1004 | <varlistentry> | |
1005 | <term><varname>StartLimitInterval=</varname></term> | |
1006 | <term><varname>StartLimitBurst=</varname></term> | |
1007 | ||
1008 | <listitem><para>Configure service | |
1009 | start rate limiting. By default, | |
1010 | services which are started more | |
1011 | than 5 times within 10 seconds are not | |
1012 | permitted to start any more times | |
1013 | until the 10 second interval ends. With | |
1014 | these two options, this rate limiting | |
1015 | may be modified. Use | |
1016 | <varname>StartLimitInterval=</varname> | |
1017 | to configure the checking interval (defaults to | |
1018 | <varname>DefaultStartLimitInterval=</varname> in | |
1019 | manager configuration file, set to 0 to disable | |
1020 | any kind of rate limiting). Use | |
1021 | <varname>StartLimitBurst=</varname> to | |
1022 | configure how many starts per interval | |
1023 | are allowed (defaults to | |
1024 | <varname>DefaultStartLimitBurst=</varname> in | |
1025 | manager configuration file). These | |
1026 | configuration options are particularly | |
1027 | useful in conjunction with | |
1028 | <varname>Restart=</varname>; however, | |
1029 | they apply to all kinds of starts | |
1030 | (including manual), not just those | |
1031 | triggered by the | |
1032 | <varname>Restart=</varname> logic. | |
1033 | Note that units which are configured | |
1034 | for <varname>Restart=</varname> and | |
1035 | which reach the start limit are not | |
1036 | attempted to be restarted anymore; | |
1037 | however, they may still be restarted | |
1038 | manually at a later point, from which | |
1039 | point on, the restart logic is again | |
1040 | activated. Note that | |
1041 | <command>systemctl | |
1042 | reset-failed</command> will cause the | |
1043 | restart rate counter for a service to | |
1044 | be flushed, which is useful if the | |
1045 | administrator wants to manually start | |
1046 | a service and the start limit | |
1047 | interferes with | |
1048 | that.</para></listitem> | |
1049 | </varlistentry> | |
1050 | ||
1051 | <varlistentry> | |
1052 | <term><varname>StartLimitAction=</varname></term> | |
1053 | ||
1054 | <listitem><para>Configure the action | |
1055 | to take if the rate limit configured | |
1056 | with | |
1057 | <varname>StartLimitInterval=</varname> | |
1058 | and | |
1059 | <varname>StartLimitBurst=</varname> is | |
1060 | hit. Takes one of | |
1061 | <option>none</option>, | |
1062 | <option>reboot</option>, | |
1063 | <option>reboot-force</option>, | |
1064 | <option>reboot-immediate</option>, | |
1065 | <option>poweroff</option>, | |
1066 | <option>poweroff-force</option> or | |
1067 | <option>poweroff-immediate</option>. If | |
1068 | <option>none</option> is set, hitting | |
1069 | the rate limit will trigger no action | |
1070 | besides that the start will not be | |
1071 | permitted. <option>reboot</option> | |
1072 | causes a reboot following the normal | |
1073 | shutdown procedure (i.e. equivalent to | |
1074 | <command>systemctl reboot</command>). | |
1075 | <option>reboot-force</option> causes a | |
1076 | forced reboot which will terminate all | |
1077 | processes forcibly but should cause no | |
1078 | dirty file systems on reboot | |
1079 | (i.e. equivalent to <command>systemctl | |
1080 | reboot -f</command>) and | |
1081 | <option>reboot-immediate</option> | |
1082 | causes immediate execution of the | |
1083 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
1084 | system call, which might result in | |
1085 | data loss. Similar, | |
1086 | <option>poweroff</option>, | |
1087 | <option>poweroff-force</option>, | |
1088 | <option>poweroff-immediate</option> | |
1089 | have the effect of powering down the | |
1090 | system with similar | |
1091 | semantics. Defaults to | |
1092 | <option>none</option>.</para></listitem> | |
1093 | </varlistentry> | |
1094 | ||
1095 | <varlistentry> | |
1096 | <term><varname>FailureAction=</varname></term> | |
1097 | <listitem><para>Configure the action | |
1098 | to take when the service enters a failed | |
1099 | state. Takes the same values as | |
1100 | <varname>StartLimitAction=</varname> | |
1101 | and executes the same actions. | |
1102 | Defaults to <option>none</option>. | |
1103 | </para></listitem> | |
1104 | </varlistentry> | |
1105 | ||
1106 | <varlistentry> | |
1107 | <term><varname>RebootArgument=</varname></term> | |
1108 | <listitem><para>Configure the optional | |
1109 | argument for the | |
1110 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
1111 | system call if | |
1112 | <varname>StartLimitAction=</varname> | |
1113 | or <varname>FailureAction=</varname> | |
1114 | is a reboot action. This works just | |
1115 | like the optional argument to | |
1116 | <command>systemctl reboot</command> | |
1117 | command.</para></listitem> | |
1118 | </varlistentry> | |
1119 | ||
1120 | <varlistentry> | |
1121 | <term><varname>FileDescriptorStoreMax=</varname></term> | |
1122 | <listitem><para>Configure how many | |
1123 | file descriptors may be stored in the | |
1124 | service manager for the service using | |
1125 | <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s | |
1126 | <literal>FDSTORE=1</literal> | |
1127 | messages. This is useful for | |
1128 | implementing service restart schemes | |
1129 | where the state is serialized to | |
1130 | <filename>/run</filename> and the file | |
1131 | descriptors passed to the service | |
1132 | manager, to allow restarts without | |
1133 | losing state. Defaults to 0, i.e. no | |
1134 | file descriptors may be stored in the | |
1135 | service manager by default. All file | |
1136 | descriptors passed to the service | |
1137 | manager from a specific service are | |
1138 | passed back to the service's main | |
1139 | process on the next service | |
1140 | restart. Any file descriptors passed | |
1141 | to the service manager are | |
1142 | automatically closed when POLLHUP or | |
1143 | POLLERR is seen on them, or when the | |
1144 | service is fully stopped and no job | |
1145 | queued or being executed for | |
1146 | it.</para></listitem> | |
1147 | </varlistentry> | |
1148 | ||
1149 | </variablelist> | |
1150 | ||
1151 | <para>Check | |
1152 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1153 | and | |
1154 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1155 | for more settings.</para> | |
1156 | ||
1157 | </refsect1> | |
1158 | ||
1159 | <refsect1> | |
1160 | <title>Command lines</title> | |
1161 | ||
1162 | <para>This section describes command line parsing and | |
1163 | variable and specifier substitions for | |
1164 | <varname>ExecStart=</varname>, | |
1165 | <varname>ExecStartPre=</varname>, | |
1166 | <varname>ExecStartPost=</varname>, | |
1167 | <varname>ExecReload=</varname>, | |
1168 | <varname>ExecStop=</varname>, and | |
1169 | <varname>ExecStopPost=</varname> options.</para> | |
1170 | ||
1171 | <para>Multiple command lines may be concatenated in a | |
1172 | single directive by separating them with semicolons | |
1173 | (these semicolons must be passed as separate words). | |
1174 | Lone semicolons may be escaped as | |
1175 | <literal>\;</literal>.</para> | |
1176 | ||
1177 | <para>Each command line is split on whitespace, with | |
1178 | the first item being the command to execute, and the | |
1179 | subsequent items being the arguments. Double quotes | |
1180 | ("...") and single quotes ('...') may be used, in | |
1181 | which case everything until the next matching quote | |
1182 | becomes part of the same argument. C-style escapes are | |
1183 | also supported, see table below. Quotes themselves are | |
1184 | removed after parsing and escape sequences | |
1185 | substituted. In addition, a trailing backslash | |
1186 | (<literal>\</literal>) may be used to merge lines. | |
1187 | </para> | |
1188 | ||
1189 | <para>This syntax is intended to be very similar to | |
1190 | shell syntax, but only the meta-characters and | |
1191 | expansions described in the following paragraphs are | |
1192 | understood. Specifically, redirection using | |
1193 | <literal><</literal>, <literal><<</literal>, | |
1194 | <literal>></literal>, and | |
1195 | <literal>>></literal>, pipes using | |
1196 | <literal>|</literal>, running programs in the | |
1197 | background using <literal>&</literal>, and | |
1198 | <emphasis>other elements of shell syntax are not | |
1199 | supported</emphasis>.</para> | |
1200 | ||
1201 | <para>The command to execute must an absolute path | |
1202 | name. It may contain spaces, but control characters | |
1203 | are not allowed.</para> | |
1204 | ||
1205 | <para>The command line accepts <literal>%</literal> | |
1206 | specifiers as described in | |
1207 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
1208 | Note that the first argument of the command line | |
1209 | (i.e. the program to execute) may not include | |
1210 | specifiers.</para> | |
1211 | ||
1212 | <para>Basic environment variable substitution is | |
1213 | supported. Use <literal>${FOO}</literal> as part of a | |
1214 | word, or as a word of its own, on the command line, in | |
1215 | which case it will be replaced by the value of the | |
1216 | environment variable including all whitespace it | |
1217 | contains, resulting in a single argument. Use | |
1218 | <literal>$FOO</literal> as a separate word on the | |
1219 | command line, in which case it will be replaced by the | |
1220 | value of the environment variable split at whitespace | |
1221 | resulting in zero or more arguments. For this type of | |
1222 | expansion, quotes and respected when splitting into | |
1223 | words, and afterwards removed.</para> | |
1224 | ||
1225 | <para>Example:</para> | |
1226 | ||
1227 | <programlisting>Environment="ONE=one" 'TWO=two two' | |
1228 | ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> | |
1229 | ||
1230 | <para>This will execute <command>/bin/echo</command> | |
1231 | with four arguments: <literal>one</literal>, | |
1232 | <literal>two</literal>, <literal>two</literal>, and | |
1233 | <literal>two two</literal>.</para> | |
1234 | ||
1235 | <para>Example:</para> | |
1236 | <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= | |
1237 | ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} | |
1238 | ExecStart=/bin/echo $ONE $TWO $THREE</programlisting> | |
1239 | <para>This results in <filename>echo</filename> being | |
1240 | called twice, the first time with arguments | |
1241 | <literal>'one'</literal>, | |
1242 | <literal>'two two' too</literal>, <literal></literal>, | |
1243 | and the second time with arguments | |
1244 | <literal>one</literal>, <literal>two two</literal>, | |
1245 | <literal>too</literal>. | |
1246 | </para> | |
1247 | ||
1248 | <para>To pass a literal dollar sign, use | |
1249 | <literal>$$</literal>. Variables whose value is not | |
1250 | known at expansion time are treated as empty | |
1251 | strings. Note that the first argument (i.e. the | |
1252 | program to execute) may not be a variable.</para> | |
1253 | ||
1254 | <para>Variables to be used in this fashion may be | |
1255 | defined through <varname>Environment=</varname> and | |
1256 | <varname>EnvironmentFile=</varname>. In addition, | |
1257 | variables listed in the section "Environment variables | |
1258 | in spawned processes" in | |
1259 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1260 | which are considered "static configuration", may be | |
1261 | used (this includes e.g. <varname>$USER</varname>, but | |
1262 | not <varname>$TERM</varname>).</para> | |
1263 | ||
1264 | <para>Note that shell command lines are not directly | |
1265 | supported. If shell command lines are to be used, they | |
1266 | need to be passed explicitly to a shell implementation | |
1267 | of some kind. Example:</para> | |
1268 | <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> | |
1269 | ||
1270 | <para>Example:</para> | |
1271 | ||
1272 | <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> | |
1273 | ||
1274 | <para>This will execute <command>/bin/echo</command> | |
1275 | two times, each time with one argument: | |
1276 | <literal>one</literal> and <literal>two two</literal>, | |
1277 | respectively. Because two commands are specified, | |
1278 | <varname>Type=oneshot</varname> must be used.</para> | |
1279 | ||
1280 | <para>Example:</para> | |
1281 | ||
1282 | <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ | |
1283 | /bin/ls</programlisting> | |
1284 | ||
1285 | <para>This will execute <command>/bin/echo</command> | |
1286 | with five arguments: <literal>/</literal>, | |
1287 | <literal>>/dev/null</literal>, | |
1288 | <literal>&</literal>, <literal>;</literal>, and | |
1289 | <literal>/bin/ls</literal>.</para> | |
1290 | ||
1291 | <table> | |
1292 | <title>C escapes supported in command lines and environment variables</title> | |
1293 | <tgroup cols='2'> | |
1294 | <colspec colname='escape' /> | |
1295 | <colspec colname='meaning' /> | |
1296 | <thead> | |
1297 | <row> | |
1298 | <entry>Literal</entry> | |
1299 | <entry>Actual value</entry> | |
1300 | </row> | |
1301 | </thead> | |
1302 | <tbody> | |
1303 | <row> | |
1304 | <entry><literal>\a</literal></entry> | |
1305 | <entry>bell</entry> | |
1306 | </row> | |
1307 | <row> | |
1308 | <entry><literal>\b</literal></entry> | |
1309 | <entry>backspace</entry> | |
1310 | </row> | |
1311 | <row> | |
1312 | <entry><literal>\f</literal></entry> | |
1313 | <entry>form feed</entry> | |
1314 | </row> | |
1315 | <row> | |
1316 | <entry><literal>\n</literal></entry> | |
1317 | <entry>newline</entry> | |
1318 | </row> | |
1319 | <row> | |
1320 | <entry><literal>\r</literal></entry> | |
1321 | <entry>carriage return</entry> | |
1322 | </row> | |
1323 | <row> | |
1324 | <entry><literal>\t</literal></entry> | |
1325 | <entry>tab</entry> | |
1326 | </row> | |
1327 | <row> | |
1328 | <entry><literal>\v</literal></entry> | |
1329 | <entry>vertical tab</entry> | |
1330 | </row> | |
1331 | <row> | |
1332 | <entry><literal>\\</literal></entry> | |
1333 | <entry>backslash</entry> | |
1334 | </row> | |
1335 | <row> | |
1336 | <entry><literal>\"</literal></entry> | |
1337 | <entry>double quotation mark</entry> | |
1338 | </row> | |
1339 | <row> | |
1340 | <entry><literal>\'</literal></entry> | |
1341 | <entry>single quotation mark</entry> | |
1342 | </row> | |
1343 | <row> | |
1344 | <entry><literal>\s</literal></entry> | |
1345 | <entry>space</entry> | |
1346 | </row> | |
1347 | <row> | |
1348 | <entry><literal>\x<replaceable>xx</replaceable></literal></entry> | |
1349 | <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> | |
1350 | </row> | |
1351 | <row> | |
1352 | <entry><literal>\<replaceable>nnn</replaceable></literal></entry> | |
1353 | <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> | |
1354 | </row> | |
1355 | </tbody> | |
1356 | </tgroup> | |
1357 | </table> | |
1358 | </refsect1> | |
1359 | ||
1360 | <refsect1> | |
1361 | <title>Examples</title> | |
1362 | ||
1363 | <example> | |
1364 | <title>Simple service</title> | |
1365 | ||
1366 | <para>The following unit file creates a service | |
1367 | that will execute | |
1368 | <filename>/usr/sbin/foo-daemon</filename>. | |
1369 | Since no <varname>Type=</varname> is specified, | |
1370 | the default | |
1371 | <varname>Type=</varname><option>simple</option> | |
1372 | will be assumed. systemd will assume the unit | |
1373 | to be started immediately after the program has | |
1374 | begun executing.</para> | |
1375 | ||
1376 | <programlisting>[Unit] | |
1377 | Description=Foo | |
1378 | ||
1379 | [Service] | |
1380 | ExecStart=/usr/sbin/foo-daemon | |
1381 | ||
1382 | [Install] | |
1383 | WantedBy=multi-user.target</programlisting> | |
1384 | ||
1385 | <para>Note that systemd assumes here that the | |
1386 | process started by systemd will continue | |
1387 | running until the service terminates. If the | |
1388 | program daemonizes itself (i.e. forks), please | |
1389 | use | |
1390 | <varname>Type=</varname><option>forking</option> | |
1391 | instead.</para> | |
1392 | ||
1393 | <para>Since no <varname>ExecStop=</varname> was | |
1394 | specified, systemd will send SIGTERM to all | |
1395 | processes started from this service, and after | |
1396 | a timeout also SIGKILL. This behavior can be | |
1397 | modified, see | |
1398 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1399 | for details.</para> | |
1400 | ||
1401 | <para>Note that this unit type does not include | |
1402 | any type of notification when a service has | |
1403 | completed initialization. For this, you should | |
1404 | use other unit types, such as | |
1405 | <varname>Type=</varname><option>notify</option> | |
1406 | if the service understands systemd's | |
1407 | notification protocol, | |
1408 | <varname>Type=</varname><option>forking</option> | |
1409 | if the service can background itself or | |
1410 | <varname>Type=</varname><option>dbus</option> | |
1411 | if the unit acquires a DBus name once | |
1412 | initialization is complete. See below.</para> | |
1413 | </example> | |
1414 | ||
1415 | <example> | |
1416 | <title>Oneshot service</title> | |
1417 | ||
1418 | <para>Sometimes units should just execute an | |
1419 | action without keeping active processes, such | |
1420 | as a filesystem check or a cleanup action on | |
1421 | boot. For this, | |
1422 | <varname>Type=</varname><option>oneshot</option> | |
1423 | exists. Units of this type will wait until the | |
1424 | process specified terminates and then fall back | |
1425 | to being inactive. The following unit will | |
1426 | perform a clenaup action:</para> | |
1427 | ||
1428 | <programlisting>[Unit] | |
1429 | Description=Cleanup old Foo data | |
1430 | ||
1431 | [Service] | |
1432 | Type=oneshot | |
1433 | ExecStart=/usr/sbin/foo-cleanup | |
1434 | ||
1435 | [Install] | |
1436 | WantedBy=multi-user.target</programlisting> | |
1437 | ||
1438 | <para>Note that systemd will consider the unit | |
1439 | to be in the state 'starting' until the program | |
1440 | has terminated, so ordered dependencies will | |
1441 | wait for the program to finish before starting | |
1442 | themselves. The unit will revert to the | |
1443 | 'inactive' state after the execution is | |
1444 | done, never reaching the 'active' state. That | |
1445 | means another request to start the unit will | |
1446 | perform the action again.</para> | |
1447 | ||
1448 | <para><varname>Type=</varname><option>oneshot</option> | |
1449 | are the only service units that may have more | |
1450 | than one <varname>ExecStart=</varname> | |
1451 | specified. They will be executed in order until | |
1452 | either they are all successful or one of them | |
1453 | fails.</para> | |
1454 | </example> | |
1455 | ||
1456 | <example> | |
1457 | <title>Stoppable oneshot service</title> | |
1458 | ||
1459 | <para>Similarly to the oneshot services, there | |
1460 | are sometimes units that need to execute a | |
1461 | program to set up something and then execute | |
1462 | another to shut it down, but no process remains | |
1463 | active while they are considered | |
1464 | 'started'. Network configuration can sometimes | |
1465 | fall into this category. Another use case is if | |
1466 | a oneshot service shall not be executed a | |
1467 | each time when they are pulled in as a | |
1468 | dependency, but only the first time.</para> | |
1469 | ||
1470 | <para>For this, systemd knows the setting | |
1471 | <varname>RemainAfterExit=</varname><option>yes</option>, | |
1472 | which causes systemd to consider the unit to be | |
1473 | active if the start action exited successfully. | |
1474 | This directive can be used with all types, but | |
1475 | is most useful with | |
1476 | <varname>Type=</varname><option>oneshot</option> | |
1477 | and | |
1478 | <varname>Type=</varname><option>simple</option>. | |
1479 | With | |
1480 | <varname>Type=</varname><option>oneshot</option> | |
1481 | systemd waits until the start action has | |
1482 | completed before it considers the unit to be | |
1483 | active, so dependencies start only after the | |
1484 | start action has succeeded. With | |
1485 | <varname>Type=</varname><option>simple</option> | |
1486 | dependencies will start immediately after the | |
1487 | start action has been dispatched. The following | |
1488 | unit provides an example for a simple static | |
1489 | firewall.</para> | |
1490 | ||
1491 | <programlisting>[Unit] | |
1492 | Description=Simple firewall | |
1493 | ||
1494 | [Service] | |
1495 | Type=oneshot | |
1496 | RemainAfterExit=yes | |
1497 | ExecStart=/usr/local/sbin/simple-firewall-start | |
1498 | ExecStop=/usr/local/sbin/simple-firewall-stop | |
1499 | ||
1500 | [Install] | |
1501 | WantedBy=multi-user.target</programlisting> | |
1502 | ||
1503 | <para>Since the unit is considered to be | |
1504 | running after the start action has exited, | |
1505 | invoking <command>systemctl start</command> on | |
1506 | that unit again will cause no action to be | |
1507 | taken.</para> | |
1508 | </example> | |
1509 | ||
1510 | <example> | |
1511 | <title>Traditional forking services</title> | |
1512 | ||
1513 | <para>Many traditional daemons/services | |
1514 | background (i.e. fork, daemonize) themselves | |
1515 | when starting. Set | |
1516 | <varname>Type=</varname><option>forking</option> | |
1517 | in the service's unit file to support this mode | |
1518 | of operation. systemd will consider the service | |
1519 | to be in the process of initialization while | |
1520 | the original program is still running. Once | |
1521 | it exits successfully and at least a process | |
1522 | remains (and | |
1523 | <varname>RemainAfterExit=</varname><option>no</option>), | |
1524 | the service is considered started.</para> | |
1525 | ||
1526 | <para>Often a traditional daemon only consists | |
1527 | of one process. Therefore, if only one process | |
1528 | is left after the original process terminates, | |
1529 | systemd will consider that process the main | |
1530 | process of the service. In that case, the | |
1531 | <varname>$MAINPID</varname> variable will be | |
1532 | available in <varname>ExecReload=</varname>, | |
1533 | <varname>ExecStop=</varname>, etc.</para> | |
1534 | ||
1535 | <para>In case more than one process remains, | |
1536 | systemd will be unable to determine the main | |
1537 | process, so it will not assume there is one. | |
1538 | In that case, <varname>$MAINPID</varname> will | |
1539 | not expand to anything. However, if the process | |
1540 | decides to write a traditional PID file, | |
1541 | systemd will be able to read the main PID from | |
1542 | there. Please set <varname>PIDFile=</varname> | |
1543 | accordingly. Note that the daemon should write | |
1544 | that file before finishing with its | |
1545 | initialization, otherwise systemd might try to | |
1546 | read the file before it exists.</para> | |
1547 | ||
1548 | <para>The following example shows a simple | |
1549 | daemon that forks and just starts one process | |
1550 | in the background:</para> | |
1551 | ||
1552 | <programlisting>[Unit] | |
1553 | Description=Some simple daemon | |
1554 | ||
1555 | [Service] | |
1556 | Type=forking | |
1557 | ExecStart=/usr/sbin/my-simple-daemon -d | |
1558 | ||
1559 | [Install] | |
1560 | WantedBy=multi-user.target</programlisting> | |
1561 | ||
1562 | <para>Please see | |
1563 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1564 | for details on how you can influence the way | |
1565 | systemd terminates the service.</para> | |
1566 | </example> | |
1567 | ||
1568 | <example> | |
1569 | <title>DBus services</title> | |
1570 | ||
1571 | <para>For services that acquire a name on the | |
1572 | DBus system bus, use | |
1573 | <varname>Type=</varname><option>dbus</option> | |
1574 | and set <varname>BusName=</varname> | |
1575 | accordingly. The service should not fork | |
1576 | (daemonize). systemd will consider the service | |
1577 | to be initialized once the name has been | |
1578 | acquired on the system bus. The following | |
1579 | example shows a typical DBus service:</para> | |
1580 | ||
1581 | <programlisting>[Unit] | |
1582 | Description=Simple DBus service | |
1583 | ||
1584 | [Service] | |
1585 | Type=dbus | |
1586 | BusName=org.example.simple-dbus-service | |
1587 | ExecStart=/usr/sbin/simple-dbus-service | |
1588 | ||
1589 | [Install] | |
1590 | WantedBy=multi-user.target</programlisting> | |
1591 | ||
1592 | <para>For <emphasis>bus-activatable</emphasis> | |
1593 | services, don't include a | |
1594 | <literal>[Install]</literal> section in the | |
1595 | systemd service file, but use the | |
1596 | <varname>SystemdService=</varname> option in | |
1597 | the corresponding DBus service file, for | |
1598 | example | |
1599 | (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> | |
1600 | ||
1601 | <programlisting>[D-BUS Service] | |
1602 | Name=org.example.simple-dbus-service | |
1603 | Exec=/usr/sbin/simple-dbus-service | |
1604 | User=root | |
1605 | SystemdService=simple-dbus-service.service</programlisting> | |
1606 | ||
1607 | <para>Please see | |
1608 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1609 | for details on how you can influence the way | |
1610 | systemd terminates the service.</para> | |
1611 | </example> | |
1612 | ||
1613 | <example> | |
1614 | <title>Services that notify systemd about their initialization</title> | |
1615 | ||
1616 | <para><varname>Type=</varname><option>simple</option> | |
1617 | services are really easy to write, but have the | |
1618 | major disadvantage of systemd not being able to | |
1619 | tell when initialization of the given service | |
1620 | is complete. For this reason, systemd supports | |
1621 | a simple notification protocol that allows | |
1622 | daemons to make systemd aware that they are | |
1623 | done initializing. Use | |
1624 | <varname>Type=</varname><option>notify</option> | |
1625 | for this. A typical service file for such a | |
1626 | daemon would look like this:</para> | |
1627 | ||
1628 | <programlisting>[Unit] | |
1629 | Description=Simple notifying service | |
1630 | ||
1631 | [Service] | |
1632 | Type=notify | |
1633 | ExecStart=/usr/sbin/simple-notifying-service | |
1634 | ||
1635 | [Install] | |
1636 | WantedBy=multi-user.target</programlisting> | |
1637 | ||
1638 | <para>Note that the daemon has to support | |
1639 | systemd's notification protocol, else systemd | |
1640 | will think the service hasn't started yet and | |
1641 | kill it after a timeout. For an example of how | |
1642 | to update daemons to support this protocol | |
1643 | transparently, take a look at | |
1644 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
1645 | systemd will consider the unit to be in the | |
1646 | 'starting' state until a readiness notification | |
1647 | has arrived.</para> | |
1648 | ||
1649 | <para>Please see | |
1650 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1651 | for details on how you can influence the way | |
1652 | systemd terminates the service.</para> | |
1653 | </example> | |
1654 | </refsect1> | |
1655 | ||
1656 | <refsect1> | |
1657 | <title>See Also</title> | |
1658 | <para> | |
1659 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
1660 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
1661 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1662 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1663 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1664 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1665 | <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
1666 | </para> | |
1667 | </refsect1> | |
1668 | ||
1669 | </refentry> |