]>
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 | |
bcddd5bf | 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 | |
96fb8242 | 142 | if neither |
12b25f30 | 143 | <varname>Type=</varname> nor |
96fb8242 LP |
144 | <varname>BusName=</varname>, but |
145 | <varname>ExecStart=</varname> are | |
12b25f30 ZJS |
146 | specified), it is expected that the |
147 | process configured with | |
0d624a78 LP |
148 | <varname>ExecStart=</varname> is the |
149 | main process of the service. In this | |
b1690fe7 LP |
150 | mode, if the process offers |
151 | functionality to other processes on | |
79640424 | 152 | the system, its communication channels |
b1690fe7 LP |
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> | |
0d624a78 LP |
158 | |
159 | <para>If set to | |
79640424 | 160 | <option>forking</option>, it is |
0d624a78 LP |
161 | expected that the process configured |
162 | with <varname>ExecStart=</varname> | |
b1690fe7 LP |
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 | |
79640424 | 167 | channels are set up. The child continues |
b1690fe7 | 168 | to run as the main daemon |
c5315881 | 169 | process. This is the behavior of |
b1690fe7 | 170 | traditional UNIX daemons. If this |
0d624a78 LP |
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 | |
bcddd5bf JSJ |
176 | proceed with starting follow-up units |
177 | as soon as the parent process | |
0d624a78 LP |
178 | exits.</para> |
179 | ||
c5315881 | 180 | <para>Behavior of |
96fb8242 LP |
181 | <option>oneshot</option> is similar to |
182 | <option>simple</option>; however, it | |
183 | is expected that the process has to | |
0d624a78 | 184 | exit before systemd starts follow-up |
02ee865a | 185 | units. <varname>RemainAfterExit=</varname> |
0d624a78 | 186 | is particularly useful for this type |
96fb8242 LP |
187 | of service. This is the implied |
188 | default if neither | |
189 | <varname>Type=</varname> or | |
190 | <varname>ExecStart=</varname> are | |
191 | specified.</para> | |
0d624a78 | 192 | |
c5315881 | 193 | <para>Behavior of |
0d624a78 | 194 | <option>dbus</option> is similar to |
bcddd5bf | 195 | <option>simple</option>; however, it is |
62adf224 | 196 | expected that the daemon acquires a |
0d624a78 LP |
197 | name on the D-Bus bus, as configured |
198 | by | |
199 | <varname>BusName=</varname>. systemd | |
bcddd5bf JSJ |
200 | will proceed with starting follow-up |
201 | units after the D-Bus bus name has been | |
62adf224 | 202 | acquired. Service units with this |
b1690fe7 | 203 | option configured implicitly gain |
62adf224 | 204 | dependencies on the |
177b3ffe | 205 | <filename>dbus.socket</filename> |
0b86feac LP |
206 | unit. This type is the default if |
207 | <varname>BusName=</varname> is | |
208 | specified.</para> | |
0d624a78 | 209 | |
c5315881 | 210 | <para>Behavior of |
0d624a78 | 211 | <option>notify</option> is similar to |
bcddd5bf | 212 | <option>simple</option>; however, it is |
0d624a78 LP |
213 | expected that the daemon sends a |
214 | notification message via | |
215 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
bcddd5bf JSJ |
216 | or an equivalent call when it has finished |
217 | starting up. systemd will proceed with | |
0d624a78 LP |
218 | starting follow-up units after this |
219 | notification message has been sent. If | |
79640424 | 220 | this option is used, |
62adf224 | 221 | <varname>NotifyAccess=</varname> (see |
b1690fe7 | 222 | below) should be set to open access to |
0d624a78 | 223 | the notification socket provided by |
62adf224 | 224 | systemd. If |
02c4ef9c LP |
225 | <varname>NotifyAccess=</varname> is |
226 | not set, it will be implicitly set to | |
1361a3e3 LP |
227 | <option>main</option>. Note that |
228 | currently | |
229 | <varname>Type=</varname><option>notify</option> | |
79640424 | 230 | will not work if used in combination with |
1361a3e3 | 231 | <varname>PrivateNetwork=</varname><option>yes</option>.</para> |
a8ad0f89 | 232 | |
c5315881 | 233 | <para>Behavior of |
a8ad0f89 | 234 | <option>idle</option> is very similar |
bcddd5bf | 235 | to <option>simple</option>; however, |
bb31a4ac | 236 | actual execution of the service |
a8ad0f89 LP |
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> | |
d1ab0ca0 LP |
242 | </listitem> |
243 | </varlistentry> | |
0d624a78 | 244 | |
d1ab0ca0 | 245 | <varlistentry> |
02ee865a | 246 | <term><varname>RemainAfterExit=</varname></term> |
0d624a78 LP |
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> | |
d1ab0ca0 | 253 | </listitem> |
3185a36b LP |
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 | |
bb31a4ac | 262 | if it cannot be determined |
3185a36b LP |
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 | |
bcddd5bf | 268 | file, the main PID is always known. The |
3185a36b LP |
269 | guessing algorithm might come to |
270 | incorrect conclusions if a daemon | |
271 | consists of more than one process. If | |
79640424 | 272 | the main PID cannot be determined, |
3185a36b LP |
273 | failure detection and automatic |
274 | restarting of a service will not work | |
275 | reliably. Defaults to | |
276 | <option>yes</option>.</para> | |
277 | </listitem> | |
d1ab0ca0 LP |
278 | </varlistentry> |
279 | ||
280 | <varlistentry> | |
281 | <term><varname>PIDFile=</varname></term> | |
0d624a78 LP |
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 | |
be039669 LP |
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> | |
d1ab0ca0 LP |
293 | </listitem> |
294 | </varlistentry> | |
295 | ||
296 | <varlistentry> | |
297 | <term><varname>BusName=</varname></term> | |
0d624a78 LP |
298 | |
299 | <listitem><para>Takes a D-Bus bus | |
bcddd5bf | 300 | name that this service is reachable |
0d624a78 LP |
301 | as. This option is mandatory for |
302 | services where | |
303 | <varname>Type=</varname> is set to | |
304 | <option>dbus</option>, but its use | |
bcddd5bf JSJ |
305 | is otherwise recommended if the process |
306 | takes a name on the D-Bus bus.</para> | |
d1ab0ca0 LP |
307 | </listitem> |
308 | </varlistentry> | |
309 | ||
310 | <varlistentry> | |
311 | <term><varname>ExecStart=</varname></term> | |
22f38abe LP |
312 | <listitem><para>Commands with their |
313 | arguments that are executed when this | |
ec6039bc ZJS |
314 | service is started. For each of the |
315 | specified commands, the first argument | |
316 | must be an absolute and literal path | |
317 | to an executable.</para> | |
2480f0c6 | 318 | |
4c42e8e1 ZJS |
319 | <para>When <varname>Type</varname> is |
320 | not <option>oneshot</option>, only one | |
96fb8242 | 321 | command may and must be given. When |
b1690fe7 | 322 | <varname>Type=oneshot</varname> is |
96fb8242 LP |
323 | used, none or more than one command |
324 | may be specified. Multiple command | |
325 | lines may be concatenated in a single | |
326 | directive by separating them with | |
327 | semicolons (these semicolons must be | |
328 | passed as separate | |
329 | words). Alternatively, this directive | |
330 | may be specified more than once with | |
331 | the same effect. Lone semicolons may | |
332 | be escaped as | |
909f413d | 333 | <literal>\;</literal>. If the empty |
79640424 | 334 | string is assigned to this option, the |
74051b9b LP |
335 | list of commands to start is reset, |
336 | prior assignments of this option will | |
96fb8242 LP |
337 | have no effect. If no |
338 | <varname>ExecStart=</varname> is | |
339 | specified, then the service must have | |
340 | <varname>RemainAfterExit=yes</varname> | |
341 | set.</para> | |
2480f0c6 | 342 | |
ec6039bc ZJS |
343 | <para>Each command line is split on |
344 | whitespace, with the first item being | |
345 | the command to execute, and the | |
346 | subsequent items being the arguments. | |
347 | Double quotes ("...") and single | |
348 | quotes ('...') may be used, in which | |
349 | case everything until the next | |
350 | matching quote becomes part of the | |
351 | same argument. Quotes themselves are | |
352 | removed after parsing. In addition, a | |
353 | trailing backslash | |
354 | (<literal>\</literal>) may be used to | |
355 | merge lines. This syntax is intended | |
356 | to be very similar to shell syntax, | |
357 | but only the meta-characters and | |
358 | expansions described in the following | |
359 | paragraphs are understood. | |
360 | Specifically, redirection using | |
361 | <literal><</literal>, | |
362 | <literal><<</literal>, | |
363 | <literal>></literal>, and | |
364 | <literal>>></literal>, pipes | |
365 | using <literal>|</literal>, and | |
366 | running programs in the background | |
367 | using <literal>&</literal> | |
368 | and <emphasis>other elements of shell | |
369 | syntax are not supported</emphasis>. | |
370 | </para> | |
371 | ||
4c42e8e1 ZJS |
372 | <para>If more than one command is |
373 | specified, the commands are invoked | |
bcddd5bf JSJ |
374 | sequentially in the order they appear |
375 | in the unit file. If one of the | |
376 | commands fails (and is not prefixed | |
377 | with <literal>-</literal>), other lines | |
378 | are not executed, and the unit is | |
379 | considered failed.</para> | |
4c42e8e1 | 380 | |
2480f0c6 ZJS |
381 | <para>Unless |
382 | <varname>Type=forking</varname> is | |
383 | set, the process started via this | |
384 | command line will be considered the | |
22f38abe LP |
385 | main process of the daemon.</para> |
386 | ||
387 | <para>The command line accepts | |
909f413d | 388 | <literal>%</literal> specifiers as |
22f38abe | 389 | described in |
ec6039bc ZJS |
390 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. |
391 | Note that the first argument of the | |
392 | command line (i.e. the program to | |
393 | execute) may not include | |
394 | specifiers.</para> | |
b1690fe7 | 395 | |
4c42e8e1 ZJS |
396 | <para>Basic environment variable |
397 | substitution is supported. Use | |
7734f773 | 398 | <literal>${FOO}</literal> as part of a |
bcddd5bf | 399 | word, or as a word of its own, on the |
7734f773 BS |
400 | command line, in which case it will be |
401 | replaced by the value of the | |
402 | environment variable including all | |
403 | whitespace it contains, resulting in a | |
c5b37953 | 404 | single argument. Use |
7734f773 BS |
405 | <literal>$FOO</literal> as a separate |
406 | word on the command line, in which | |
407 | case it will be replaced by the value | |
c5b37953 ZJS |
408 | of the environment variable split at |
409 | whitespace, resulting in zero or more | |
410 | arguments. To pass a literal dollar | |
411 | sign, use <literal>$$</literal>. | |
412 | Variables whose value is not known at | |
413 | expansion time are treated as empty | |
414 | strings. Note that the first argument | |
415 | (i.e. the program to execute) may not | |
416 | be a variable.</para> | |
417 | ||
418 | <para>Variables to be used in this | |
419 | fashion may be defined through | |
420 | <varname>Environment=</varname> and | |
421 | <varname>EnvironmentFile=</varname>. | |
bcddd5bf | 422 | In addition, variables listed in the |
c5b37953 ZJS |
423 | section "Environment variables in |
424 | spawned processes" in | |
bcddd5bf | 425 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
c5b37953 | 426 | which are considered "static |
bcddd5bf | 427 | configuration", may be used (this includes |
c5b37953 ZJS |
428 | e.g. <varname>$USER</varname>, but not |
429 | <varname>$TERM</varname>).</para> | |
a2927192 | 430 | |
74051b9b LP |
431 | <para>Optionally, if the absolute file |
432 | name is prefixed with | |
909f413d | 433 | <literal>@</literal>, the second token |
74051b9b LP |
434 | will be passed as |
435 | <literal>argv[0]</literal> to the | |
436 | executed process, followed by the | |
437 | further arguments specified. If the | |
e9dd9f95 | 438 | absolute filename is prefixed with |
79640424 | 439 | <literal>-</literal>, an exit code of |
74051b9b LP |
440 | the command normally considered a |
441 | failure (i.e. non-zero exit status or | |
442 | abnormal exit due to signal) is ignored | |
443 | and considered success. If both | |
909f413d | 444 | <literal>-</literal> and |
79640424 | 445 | <literal>@</literal> are used, they |
74051b9b LP |
446 | can appear in either order.</para> |
447 | ||
a2927192 LP |
448 | <para>Note that this setting does not |
449 | directly support shell command | |
450 | lines. If shell command lines are to | |
79640424 | 451 | be used, they need to be passed |
a2927192 | 452 | explicitly to a shell implementation |
4c42e8e1 | 453 | of some kind. Example:</para> |
9fccdb0f | 454 | <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> |
ec6039bc | 455 | <para>Example:</para> |
9fccdb0f | 456 | <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> |
ec6039bc ZJS |
457 | <para>This will execute |
458 | <command>/bin/echo</command> two | |
bcddd5bf | 459 | times, each time with one argument: |
ec6039bc ZJS |
460 | <literal>one</literal> and |
461 | <literal>two two</literal>, | |
bcddd5bf | 462 | respectively. Because two commands are |
b040723e | 463 | specified, |
ec6039bc ZJS |
464 | <varname>Type=oneshot</varname> must |
465 | be used.</para> | |
466 | ||
467 | <para>Example:</para> | |
468 | <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ | |
9fccdb0f | 469 | /bin/ls</programlisting> |
ec6039bc ZJS |
470 | <para>This will execute |
471 | <command>/bin/echo</command> with five | |
472 | arguments: <literal>/</literal>, | |
473 | <literal>>/dev/null</literal>, | |
474 | <literal>&</literal>, | |
475 | <literal>;</literal>, and | |
476 | <literal>/bin/ls</literal>.</para> | |
477 | ||
478 | <para>Example:</para> | |
479 | <programlisting>Environment="ONE=one" 'TWO=two two' | |
9fccdb0f | 480 | ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> |
ec6039bc ZJS |
481 | <para>This will execute |
482 | <command>/bin/echo</command> with four | |
483 | arguments: <literal>one</literal>, | |
484 | <literal>two</literal>, | |
485 | <literal>two</literal>, and | |
486 | <literal>two two</literal>.</para> | |
487 | </listitem> | |
0d624a78 LP |
488 | </varlistentry> |
489 | ||
490 | <varlistentry> | |
491 | <term><varname>ExecStartPre=</varname></term> | |
492 | <term><varname>ExecStartPost=</varname></term> | |
493 | <listitem><para>Additional commands | |
16dad32e | 494 | that are executed before or after |
0d624a78 | 495 | the command in |
2480f0c6 ZJS |
496 | <varname>ExecStart=</varname>, respectively. |
497 | Syntax is the same as for | |
498 | <varname>ExecStart=</varname>, except | |
499 | that multiple command lines are allowed | |
500 | and the commands are executed one | |
501 | after the other, serially.</para> | |
4c42e8e1 ZJS |
502 | |
503 | <para>If any of those commands (not | |
909f413d | 504 | prefixed with <literal>-</literal>) |
4c42e8e1 ZJS |
505 | fail, the rest are not executed and |
506 | the unit is considered failed.</para> | |
2480f0c6 | 507 | </listitem> |
0d624a78 LP |
508 | </varlistentry> |
509 | ||
510 | <varlistentry> | |
511 | <term><varname>ExecReload=</varname></term> | |
512 | <listitem><para>Commands to execute to | |
513 | trigger a configuration reload in the | |
b3eaa628 LP |
514 | service. This argument takes multiple |
515 | command lines, following the same | |
2480f0c6 ZJS |
516 | scheme as described for |
517 | <varname>ExecStart=</varname> | |
b3eaa628 | 518 | above. Use of this setting is |
420a0166 LP |
519 | optional. Specifier and environment |
520 | variable substitution is supported | |
521 | here following the same scheme as for | |
4c42e8e1 ZJS |
522 | <varname>ExecStart=</varname>.</para> |
523 | ||
bcddd5bf JSJ |
524 | <para>One additional, special |
525 | environment variable is set: if known, | |
4c42e8e1 | 526 | <varname>$MAINPID</varname> is set to |
97ae63e2 LP |
527 | the main process of the daemon, and |
528 | may be used for command lines like the | |
4c42e8e1 ZJS |
529 | following:</para> |
530 | ||
531 | <programlisting>/bin/kill -HUP $MAINPID</programlisting> | |
33169701 LP |
532 | |
533 | <para>Note however that reloading a | |
534 | daemon by sending a signal (as with | |
535 | the example line above) is usually not | |
536 | a good choice, because this is an | |
537 | asynchronous operation and hence not | |
538 | suitable to order reloads of multiple | |
539 | services against each other. It is | |
540 | strongly recommended to set | |
541 | <varname>ExecReload=</varname> to a | |
851fafe5 | 542 | command that not only triggers a |
33169701 | 543 | configuration reload of the daemon, |
851fafe5 | 544 | but also synchronously waits for it to |
33169701 | 545 | complete.</para> |
4c42e8e1 | 546 | </listitem> |
0d624a78 LP |
547 | </varlistentry> |
548 | ||
549 | <varlistentry> | |
550 | <term><varname>ExecStop=</varname></term> | |
551 | <listitem><para>Commands to execute to | |
552 | stop the service started via | |
b3eaa628 LP |
553 | <varname>ExecStart=</varname>. This |
554 | argument takes multiple command lines, | |
2480f0c6 ZJS |
555 | following the same scheme as described |
556 | for <varname>ExecStart=</varname> | |
b3eaa628 | 557 | above. Use of this setting is |
bcddd5bf JSJ |
558 | optional. After the commands configured |
559 | in this option are run, all processes | |
560 | remaining for a service are | |
0d624a78 LP |
561 | terminated according to the |
562 | <varname>KillMode=</varname> setting | |
4819ff03 LP |
563 | (see |
564 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If | |
79640424 | 565 | this option is not specified, the |
bcddd5bf | 566 | process is terminated immediately when |
4819ff03 LP |
567 | service stop is requested. Specifier |
568 | and environment variable substitution | |
569 | is supported (including | |
4c42e8e1 | 570 | <varname>$MAINPID</varname>, see |
420a0166 | 571 | above).</para></listitem> |
0d624a78 LP |
572 | </varlistentry> |
573 | ||
574 | <varlistentry> | |
575 | <term><varname>ExecStopPost=</varname></term> | |
576 | <listitem><para>Additional commands | |
577 | that are executed after the service | |
3ae390ba MB |
578 | was stopped. This includes cases where |
579 | the commands configured in | |
580 | <varname>ExecStop=</varname> were used, | |
6b4991cf | 581 | where the service does not have any |
3ae390ba MB |
582 | <varname>ExecStop=</varname> defined, or |
583 | where the service exited unexpectedly. This | |
b3eaa628 | 584 | argument takes multiple command lines, |
2480f0c6 ZJS |
585 | following the same scheme as described |
586 | for <varname>ExecStart</varname>. Use | |
b3eaa628 | 587 | of these settings is |
420a0166 LP |
588 | optional. Specifier and environment |
589 | variable substitution is | |
590 | supported.</para></listitem> | |
0d624a78 LP |
591 | </varlistentry> |
592 | ||
593 | <varlistentry> | |
594 | <term><varname>RestartSec=</varname></term> | |
595 | <listitem><para>Configures the time to | |
596 | sleep before restarting a service (as | |
597 | configured with | |
598 | <varname>Restart=</varname>). Takes a | |
599 | unit-less value in seconds, or a time | |
600 | span value such as "5min | |
601 | 20s". Defaults to | |
602 | 100ms.</para></listitem> | |
603 | </varlistentry> | |
604 | ||
605 | <varlistentry> | |
d568a335 | 606 | <term><varname>TimeoutStartSec=</varname></term> |
0d624a78 | 607 | <listitem><para>Configures the time to |
d568a335 | 608 | wait for start-up. If a |
0d624a78 LP |
609 | daemon service does not signal |
610 | start-up completion within the | |
d568a335 | 611 | configured time, the service will be |
bcddd5bf JSJ |
612 | considered failed and will be shut |
613 | down again. | |
d568a335 MS |
614 | Takes a unit-less value in seconds, or a |
615 | time span value such as "5min | |
bcddd5bf JSJ |
616 | 20s". Pass <literal>0</literal> to |
617 | disable the timeout logic. Defaults to | |
5e34b37c | 618 | <varname>DefaultTimeoutStartSec=</varname> from |
bcddd5bf JSJ |
619 | the manager configuration file, except |
620 | when <varname>Type=oneshot</varname> is | |
63ba209d | 621 | used, in which case the timeout |
5e34b37c ZJS |
622 | is disabled by default |
623 | (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
d568a335 MS |
624 | </para></listitem> |
625 | </varlistentry> | |
626 | ||
627 | <varlistentry> | |
628 | <term><varname>TimeoutStopSec=</varname></term> | |
629 | <listitem><para>Configures the time to | |
630 | wait for stop. If a service is asked | |
bcddd5bf | 631 | to stop, but does not terminate in the |
d568a335 | 632 | specified time, it will be terminated |
bcddd5bf JSJ |
633 | forcibly via <constant>SIGTERM</constant>, |
634 | and after another timeout of equal duration | |
635 | with <constant>SIGKILL</constant> (see | |
62adf224 | 636 | <varname>KillMode=</varname> |
d568a335 MS |
637 | in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
638 | Takes a unit-less value in seconds, or a | |
0d624a78 | 639 | time span value such as "5min |
bcddd5bf JSJ |
640 | 20s". Pass <literal>0</literal> to disable |
641 | the timeout logic. Defaults to | |
5e34b37c ZJS |
642 | <varname>DefaultTimeoutStopSec=</varname> from the |
643 | manager configuration file | |
644 | (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
d568a335 MS |
645 | </para></listitem> |
646 | </varlistentry> | |
647 | ||
648 | <varlistentry> | |
649 | <term><varname>TimeoutSec=</varname></term> | |
650 | <listitem><para>A shorthand for configuring | |
651 | both <varname>TimeoutStartSec=</varname> | |
652 | and <varname>TimeoutStopSec=</varname> | |
653 | to the specified value. | |
654 | </para></listitem> | |
0d624a78 LP |
655 | </varlistentry> |
656 | ||
bb242b7b MO |
657 | <varlistentry> |
658 | <term><varname>WatchdogSec=</varname></term> | |
e8ab3ccb | 659 | <listitem><para>Configures the |
a827e373 ZJS |
660 | watchdog timeout for a service. The |
661 | watchdog is activated when the start-up is | |
e8ab3ccb | 662 | completed. The service must call |
bb242b7b | 663 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
bcddd5bf JSJ |
664 | regularly with <literal>WATCHDOG=1</literal> |
665 | (i.e. the "keep-alive ping"). If the time | |
dac051ad | 666 | between two such calls is larger than |
79640424 | 667 | the configured time, then the service |
bcddd5bf | 668 | is placed in a failed state. By |
dac051ad LP |
669 | setting <varname>Restart=</varname> to |
670 | <option>on-failure</option> or | |
79640424 | 671 | <option>always</option>, the service |
e8ab3ccb LP |
672 | will be automatically restarted. The |
673 | time configured here will be passed to | |
674 | the executed service process in the | |
675 | <varname>WATCHDOG_USEC=</varname> | |
dac051ad LP |
676 | environment variable. This allows |
677 | daemons to automatically enable the | |
678 | keep-alive pinging logic if watchdog | |
679 | support is enabled for the service. If | |
79640424 | 680 | this option is used, |
02c4ef9c LP |
681 | <varname>NotifyAccess=</varname> (see |
682 | below) should be set to open access to | |
683 | the notification socket provided by | |
684 | systemd. If | |
dac051ad LP |
685 | <varname>NotifyAccess=</varname> is |
686 | not set, it will be implicitly set to | |
02c4ef9c | 687 | <option>main</option>. Defaults to 0, |
e8ab3ccb LP |
688 | which disables this |
689 | feature.</para></listitem> | |
bb242b7b MO |
690 | </varlistentry> |
691 | ||
0d624a78 LP |
692 | <varlistentry> |
693 | <term><varname>Restart=</varname></term> | |
694 | <listitem><para>Configures whether the | |
a827e373 ZJS |
695 | service shall be restarted when the |
696 | service process exits, is killed, | |
697 | or a timeout is reached. The service | |
698 | process may be the main service | |
bcddd5bf JSJ |
699 | process, but it may also be one of the |
700 | processes specified with | |
a827e373 ZJS |
701 | <varname>ExecStartPre=</varname>, |
702 | <varname>ExecStartPost=</varname>, | |
c32acc96 | 703 | <varname>ExecStop=</varname>, |
a827e373 ZJS |
704 | <varname>ExecStopPost=</varname>, or |
705 | <varname>ExecReload=</varname>. | |
706 | When the death of the process is a | |
707 | result of systemd operation (e.g. service | |
708 | stop or restart), the service will not be | |
709 | restarted. Timeouts include missing | |
710 | the watchdog "keep-alive ping" | |
711 | deadline and a service start, reload, | |
712 | and stop operation timeouts.</para> | |
713 | ||
714 | <para>Takes one of | |
525ee6f4 | 715 | <option>no</option>, |
50caaedb LP |
716 | <option>on-success</option>, |
717 | <option>on-failure</option>, | |
6cfe2fde | 718 | <option>on-abnormal</option>, |
dc99a976 | 719 | <option>on-watchdog</option>, |
a827e373 | 720 | <option>on-abort</option>, or |
50caaedb | 721 | <option>always</option>. If set to |
79640424 | 722 | <option>no</option> (the default), the |
6cfe2fde LP |
723 | service will not be restarted. If set |
724 | to <option>on-success</option>, it | |
725 | will be restarted only when the | |
726 | service process exits cleanly. In | |
727 | this context, a clean exit means an | |
728 | exit code of 0, or one of the signals | |
bcddd5bf JSJ |
729 | <constant>SIGHUP</constant>, |
730 | <constant>SIGINT</constant>, | |
6cfe2fde LP |
731 | <constant>SIGTERM</constant> or |
732 | <constant>SIGPIPE</constant>, and | |
733 | additionally, exit statuses and | |
734 | signals specified in | |
735 | <varname>SuccessExitStatus=</varname>. | |
79640424 | 736 | If set to <option>on-failure</option>, |
a827e373 | 737 | the service will be restarted when the |
6cfe2fde LP |
738 | process exits with a non-zero exit |
739 | code, is terminated by a signal | |
740 | (including on core dump, but excluding | |
741 | the aforementiond four signals), when | |
742 | an operation (such as service reload) | |
743 | times out, and when the configured | |
744 | watchdog timeout is triggered. If set | |
745 | to <option>on-abnormal</option>, the | |
746 | service will be restarted when the | |
747 | process is terminated by a signal | |
748 | (including on core dump, excluding the | |
749 | aforementioned four signals), when an | |
750 | operation times out, or when the | |
751 | watchdog timeout is triggered. If set | |
752 | to <option>on-abort</option>, the | |
753 | service will be restarted only if the | |
754 | service process exits due to an | |
755 | uncaught signal not specified as a | |
756 | clean exit status. If set to | |
757 | <option>on-watchdog</option>, the | |
758 | service will be restarted only if the | |
759 | watchdog timeout for the service | |
760 | expires. If set to | |
79640424 | 761 | <option>always</option>, the service |
6cfe2fde LP |
762 | will be restarted regardless of |
763 | whether it exited cleanly or not, got | |
bcddd5bf | 764 | terminated abnormally by a signal, or |
a827e373 ZJS |
765 | hit a timeout.</para> |
766 | ||
6cfe2fde LP |
767 | <table> |
768 | <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> | |
769 | ||
770 | <tgroup cols='2'> | |
771 | <colspec colname='path' /> | |
772 | <colspec colname='expl' /> | |
773 | <thead> | |
774 | <row> | |
775 | <entry>Restart settings/Exit causes</entry> | |
776 | <entry><option>no</option></entry> | |
777 | <entry><option>always</option></entry> | |
778 | <entry><option>on-success</option></entry> | |
779 | <entry><option>on-failure</option></entry> | |
780 | <entry><option>on-abnormal</option></entry> | |
781 | <entry><option>on-abort</option></entry> | |
782 | <entry><option>on-watchdog</option></entry> | |
783 | </row> | |
784 | </thead> | |
785 | <tbody> | |
786 | <row> | |
787 | <entry>Clean exit code or signal</entry> | |
788 | <entry/> | |
789 | <entry>X</entry> | |
790 | <entry>X</entry> | |
791 | <entry/> | |
792 | <entry/> | |
793 | <entry/> | |
794 | <entry/> | |
795 | </row> | |
796 | <row> | |
797 | <entry>Unclean exit code</entry> | |
798 | <entry/> | |
799 | <entry>X</entry> | |
800 | <entry/> | |
801 | <entry>X</entry> | |
802 | <entry/> | |
803 | <entry/> | |
804 | <entry/> | |
805 | </row> | |
806 | <row> | |
807 | <entry>Unclean signal</entry> | |
808 | <entry/> | |
809 | <entry>X</entry> | |
810 | <entry/> | |
811 | <entry>X</entry> | |
812 | <entry>X</entry> | |
813 | <entry>X</entry> | |
814 | <entry/> | |
815 | </row> | |
816 | <row> | |
817 | <entry>Timeout</entry> | |
818 | <entry/> | |
819 | <entry>X</entry> | |
820 | <entry/> | |
821 | <entry>X</entry> | |
822 | <entry>X</entry> | |
823 | <entry/> | |
824 | <entry/> | |
825 | </row> | |
826 | <row> | |
827 | <entry>Watchdog</entry> | |
828 | <entry/> | |
829 | <entry>X</entry> | |
830 | <entry/> | |
831 | <entry>X</entry> | |
832 | <entry>X</entry> | |
833 | <entry/> | |
834 | <entry>X</entry> | |
835 | </row> | |
836 | </tbody> | |
837 | </tgroup> | |
838 | </table> | |
839 | ||
ab016c45 LP |
840 | <para>As exceptions to the setting |
841 | above the service will not be | |
842 | restarted if the exit code or signal | |
843 | is specified in | |
a827e373 | 844 | <varname>RestartPreventExitStatus=</varname> |
ab016c45 LP |
845 | (see below). Also, the services will |
846 | always be restarted if the exit code | |
847 | or signal is specified in | |
848 | <varname>RestartForceExitStatus=</varname> | |
6cfe2fde LP |
849 | (see below).</para> |
850 | ||
851 | <para>Setting this to | |
852 | <option>on-failure</option> is the | |
853 | recommended choice for long-running | |
854 | services, in order to increase | |
855 | reliability by attempting automatic | |
856 | recovery from errors. For services | |
857 | that shall be able to terminate on | |
ab016c45 LP |
858 | their own choice (and avoid |
859 | immediate restarting), | |
6cfe2fde LP |
860 | <option>on-abnormal</option> is an |
861 | alternative choice.</para> | |
862 | </listitem> | |
0d624a78 LP |
863 | </varlistentry> |
864 | ||
96342de6 | 865 | <varlistentry> |
abdf7993 LP |
866 | <term><varname>SuccessExitStatus=</varname></term> |
867 | <listitem><para>Takes a list of exit | |
868 | status definitions that when returned | |
869 | by the main service process will be | |
870 | considered successful termination, in | |
871 | addition to the normal successful exit | |
05cc7267 | 872 | code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>, |
a9a30533 | 873 | <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status |
abdf7993 | 874 | definitions can either be numeric exit |
a827e373 | 875 | codes or termination signal names, |
4a3fa6ac | 876 | separated by spaces. For example: |
37520c1b | 877 | <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> |
73e231ab JE |
878 | ensures that exit codes 1, 2, 8 and |
879 | the termination signal | |
880 | <constant>SIGKILL</constant> are | |
881 | considered clean service terminations. | |
882 | </para> | |
883 | ||
884 | <para>Note that if a process has a | |
885 | signal handler installed and exits by | |
886 | calling | |
887 | <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
888 | in response to a signal, the | |
889 | information about the signal is lost. | |
890 | Programs should instead perform cleanup and kill themselves with the same signal instead. See | |
891 | <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para> | |
892 | ||
893 | <para>This option may appear more than once, | |
894 | in which case the list of successful | |
895 | exit statuses is merged. If the empty | |
896 | string is assigned to this option, the | |
897 | list is reset, all prior assignments | |
898 | of this option will have no | |
899 | effect.</para></listitem> | |
96342de6 LN |
900 | </varlistentry> |
901 | ||
902 | <varlistentry> | |
abdf7993 LP |
903 | <term><varname>RestartPreventExitStatus=</varname></term> |
904 | <listitem><para>Takes a list of exit | |
905 | status definitions that when returned | |
906 | by the main service process will | |
bcddd5bf | 907 | prevent automatic service restarts, |
abdf7993 LP |
908 | regardless of the restart setting |
909 | configured with | |
910 | <varname>Restart=</varname>. Exit | |
911 | status definitions can either be | |
912 | numeric exit codes or termination | |
913 | signal names, and are separated by | |
914 | spaces. Defaults to the empty list, so | |
bcddd5bf | 915 | that, by default, no exit status is |
abdf7993 | 916 | excluded from the configured restart |
37520c1b LP |
917 | logic. For example: |
918 | <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit | |
74051b9b | 919 | codes 1 and 6 and the termination |
bcddd5bf JSJ |
920 | signal <constant>SIGABRT</constant> will |
921 | not result in automatic service | |
922 | restarting. This | |
923 | option may appear more than once, in | |
924 | which case the list of restart-preventing | |
74051b9b | 925 | statuses is merged. If the empty |
79640424 | 926 | string is assigned to this option, the |
bcddd5bf | 927 | list is reset and all prior assignments |
74051b9b LP |
928 | of this option will have no |
929 | effect.</para></listitem> | |
96342de6 LN |
930 | </varlistentry> |
931 | ||
37520c1b LP |
932 | <varlistentry> |
933 | <term><varname>RestartForceExitStatus=</varname></term> | |
934 | <listitem><para>Takes a list of exit | |
935 | status definitions that when returned | |
936 | by the main service process will force | |
937 | automatic service restarts, regardless | |
938 | of the restart setting configured with | |
939 | <varname>Restart=</varname>. The | |
940 | argument format is similar to | |
941 | <varname>RestartPreventExitStatus=</varname>.</para></listitem> | |
942 | </varlistentry> | |
943 | ||
0d624a78 LP |
944 | <varlistentry> |
945 | <term><varname>PermissionsStartOnly=</varname></term> | |
946 | <listitem><para>Takes a boolean | |
bcddd5bf JSJ |
947 | argument. If true, the permission-related |
948 | execution options, as | |
0d624a78 LP |
949 | configured with |
950 | <varname>User=</varname> and similar | |
951 | options (see | |
952 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
bcddd5bf | 953 | for more information), are only applied |
0d624a78 LP |
954 | to the process started with |
955 | <varname>ExecStart=</varname>, and not | |
956 | to the various other | |
957 | <varname>ExecStartPre=</varname>, | |
958 | <varname>ExecStartPost=</varname>, | |
959 | <varname>ExecReload=</varname>, | |
bcddd5bf | 960 | <varname>ExecStop=</varname>, and |
0d624a78 LP |
961 | <varname>ExecStopPost=</varname> |
962 | commands. If false, the setting is | |
963 | applied to all configured commands the | |
964 | same way. Defaults to | |
965 | false.</para></listitem> | |
966 | </varlistentry> | |
967 | ||
968 | <varlistentry> | |
969 | <term><varname>RootDirectoryStartOnly=</varname></term> | |
970 | <listitem><para>Takes a boolean | |
bcddd5bf | 971 | argument. If true, the root directory, |
0d624a78 LP |
972 | as configured with the |
973 | <varname>RootDirectory=</varname> | |
974 | option (see | |
975 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
bcddd5bf | 976 | for more information), is only applied |
0d624a78 LP |
977 | to the process started with |
978 | <varname>ExecStart=</varname>, and not | |
979 | to the various other | |
980 | <varname>ExecStartPre=</varname>, | |
981 | <varname>ExecStartPost=</varname>, | |
982 | <varname>ExecReload=</varname>, | |
bcddd5bf | 983 | <varname>ExecStop=</varname>, and |
0d624a78 LP |
984 | <varname>ExecStopPost=</varname> |
985 | commands. If false, the setting is | |
986 | applied to all configured commands the | |
987 | same way. Defaults to | |
988 | false.</para></listitem> | |
989 | </varlistentry> | |
990 | ||
0d624a78 LP |
991 | <varlistentry> |
992 | <term><varname>NonBlocking=</varname></term> | |
bcddd5bf JSJ |
993 | <listitem><para>Set the |
994 | <constant>O_NONBLOCK</constant> flag | |
0d624a78 LP |
995 | for all file descriptors passed via |
996 | socket-based activation. If true, all | |
997 | file descriptors >= 3 (i.e. all except | |
6db27428 | 998 | stdin, stdout, and stderr) will have |
bcddd5bf JSJ |
999 | the <constant>O_NONBLOCK</constant> flag |
1000 | set and hence are in | |
0d624a78 LP |
1001 | non-blocking mode. This option is only |
1002 | useful in conjunction with a socket | |
1003 | unit, as described in | |
1004 | <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults | |
1005 | to false.</para></listitem> | |
1006 | </varlistentry> | |
1007 | ||
1008 | <varlistentry> | |
1009 | <term><varname>NotifyAccess=</varname></term> | |
1010 | <listitem><para>Controls access to the | |
1011 | service status notification socket, as | |
1012 | accessible via the | |
1013 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
1014 | call. Takes one of | |
1015 | <option>none</option> (the default), | |
1016 | <option>main</option> or | |
1017 | <option>all</option>. If | |
79640424 | 1018 | <option>none</option>, no daemon status |
f8553ccb | 1019 | updates are accepted from the service |
0d624a78 | 1020 | processes, all status update messages |
79640424 | 1021 | are ignored. If <option>main</option>, |
0d624a78 LP |
1022 | only service updates sent from the |
1023 | main process of the service are | |
79640424 | 1024 | accepted. If <option>all</option>, all |
0d624a78 LP |
1025 | services updates from all members of |
1026 | the service's control group are | |
02c4ef9c | 1027 | accepted. This option should be set to |
0d624a78 LP |
1028 | open access to the notification socket |
1029 | when using | |
02c4ef9c | 1030 | <varname>Type=notify</varname> or |
28137202 | 1031 | <varname>WatchdogSec=</varname> (see |
02c4ef9c | 1032 | above). If those options are used but |
79640424 JE |
1033 | <varname>NotifyAccess=</varname> is not |
1034 | configured, it will be implicitly set | |
02c4ef9c LP |
1035 | to |
1036 | <option>main</option>.</para></listitem> | |
d1ab0ca0 LP |
1037 | </varlistentry> |
1038 | ||
f72192c0 LP |
1039 | <varlistentry> |
1040 | <term><varname>Sockets=</varname></term> | |
1041 | <listitem><para>Specifies the name of | |
1042 | the socket units this service shall | |
1043 | inherit the sockets from when the | |
4f025f4c | 1044 | service is started. Normally it |
f72192c0 LP |
1045 | should not be necessary to use this |
1046 | setting as all sockets whose unit | |
1047 | shares the same name as the service | |
4f025f4c | 1048 | (ignoring the different suffix of course) |
f72192c0 LP |
1049 | are passed to the spawned |
1050 | process.</para> | |
1051 | ||
1052 | <para>Note that the same socket may be | |
1053 | passed to multiple processes at the | |
1054 | same time. Also note that a different | |
1055 | service may be activated on incoming | |
bcddd5bf JSJ |
1056 | traffic than that which inherits the |
1057 | sockets. Or in other words: the | |
f72192c0 LP |
1058 | <varname>Service=</varname> setting of |
1059 | <filename>.socket</filename> units | |
6b4991cf | 1060 | does not have to match the inverse of |
74051b9b LP |
1061 | the <varname>Sockets=</varname> |
1062 | setting of the | |
1063 | <filename>.service</filename> it | |
1064 | refers to.</para> | |
1065 | ||
1066 | <para>This option may appear more than | |
1067 | once, in which case the list of socket | |
1068 | units is merged. If the empty string | |
79640424 | 1069 | is assigned to this option, the list of |
bcddd5bf | 1070 | sockets is reset, and all prior uses of |
74051b9b LP |
1071 | this setting will have no |
1072 | effect.</para></listitem> | |
f72192c0 LP |
1073 | </varlistentry> |
1074 | ||
092317d0 LP |
1075 | <varlistentry> |
1076 | <term><varname>StartLimitInterval=</varname></term> | |
1077 | <term><varname>StartLimitBurst=</varname></term> | |
1078 | ||
1079 | <listitem><para>Configure service | |
79640424 | 1080 | start rate limiting. By default, |
bcddd5bf JSJ |
1081 | services which are started more |
1082 | than 5 times within 10 seconds are not | |
092317d0 | 1083 | permitted to start any more times |
bcddd5bf | 1084 | until the 10 second interval ends. With |
79640424 | 1085 | these two options, this rate limiting |
092317d0 LP |
1086 | may be modified. Use |
1087 | <varname>StartLimitInterval=</varname> | |
3f41e1e5 LN |
1088 | to configure the checking interval (defaults to |
1089 | <varname>DefaultStartLimitInterval=</varname> in | |
1090 | manager configuration file, set to 0 to disable | |
092317d0 LP |
1091 | any kind of rate limiting). Use |
1092 | <varname>StartLimitBurst=</varname> to | |
1093 | configure how many starts per interval | |
3f41e1e5 LN |
1094 | are allowed (defaults to |
1095 | <varname>DefaultStartLimitBurst=</varname> in | |
1096 | manager configuration file). These | |
092317d0 LP |
1097 | configuration options are particularly |
1098 | useful in conjunction with | |
bcddd5bf JSJ |
1099 | <varname>Restart=</varname>; however, |
1100 | they apply to all kinds of starts | |
6ffd3337 LP |
1101 | (including manual), not just those |
1102 | triggered by the | |
1103 | <varname>Restart=</varname> logic. | |
1104 | Note that units which are configured | |
1105 | for <varname>Restart=</varname> and | |
1106 | which reach the start limit are not | |
bcddd5bf JSJ |
1107 | attempted to be restarted anymore; |
1108 | however, they may still be restarted | |
1109 | manually at a later point, from which | |
1110 | point on, the restart logic is again | |
451b34cc LP |
1111 | activated. Note that |
1112 | <command>systemctl | |
1113 | reset-failed</command> will cause the | |
1114 | restart rate counter for a service to | |
1115 | be flushed, which is useful if the | |
1116 | administrator wants to manually start | |
1117 | a service and the start limit | |
1118 | interferes with | |
1119 | that.</para></listitem> | |
092317d0 LP |
1120 | </varlistentry> |
1121 | ||
1122 | <varlistentry> | |
1123 | <term><varname>StartLimitAction=</varname></term> | |
1124 | ||
1125 | <listitem><para>Configure the action | |
1126 | to take if the rate limit configured | |
1127 | with | |
1128 | <varname>StartLimitInterval=</varname> | |
1129 | and | |
1130 | <varname>StartLimitBurst=</varname> is | |
1131 | hit. Takes one of | |
1132 | <option>none</option>, | |
1133 | <option>reboot</option>, | |
f07756bf LP |
1134 | <option>reboot-force</option>, |
1135 | <option>reboot-immediate</option>, | |
1136 | <option>poweroff</option>, | |
1137 | <option>poweroff-force</option> or | |
1138 | <option>poweroff-immediate</option>. If | |
1139 | <option>none</option> is set, hitting | |
1140 | the rate limit will trigger no action | |
1141 | besides that the start will not be | |
1142 | permitted. <option>reboot</option> | |
092317d0 LP |
1143 | causes a reboot following the normal |
1144 | shutdown procedure (i.e. equivalent to | |
bcddd5bf | 1145 | <command>systemctl reboot</command>). |
f07756bf LP |
1146 | <option>reboot-force</option> causes a |
1147 | forced reboot which will terminate all | |
1148 | processes forcibly but should cause no | |
1149 | dirty file systems on reboot | |
092317d0 LP |
1150 | (i.e. equivalent to <command>systemctl |
1151 | reboot -f</command>) and | |
1152 | <option>reboot-immediate</option> | |
1153 | causes immediate execution of the | |
1154 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
1155 | system call, which might result in | |
f07756bf LP |
1156 | data loss. Similar, |
1157 | <option>poweroff</option>, | |
1158 | <option>poweroff-force</option>, | |
1159 | <option>poweroff-immediate</option> | |
1160 | have the effect of powering down the | |
1161 | system with similar | |
1162 | semantics. Defaults to | |
092317d0 LP |
1163 | <option>none</option>.</para></listitem> |
1164 | </varlistentry> | |
1165 | ||
2928b0a8 LP |
1166 | <varlistentry> |
1167 | <term><varname>FailureAction=</varname></term> | |
1168 | <listitem><para>Configure the action | |
1169 | to take when the service enters a failed | |
1170 | state. Takes the same values as | |
1171 | <varname>StartLimitAction=</varname> | |
1172 | and executes the same actions. | |
1173 | Defaults to <option>none</option>. | |
1174 | </para></listitem> | |
1175 | </varlistentry> | |
1176 | ||
efe6e7d3 MO |
1177 | <varlistentry> |
1178 | <term><varname>RebootArgument=</varname></term> | |
1179 | <listitem><para>Configure the optional | |
1180 | argument for the | |
1181 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
1182 | system call if | |
1183 | <varname>StartLimitAction=</varname> | |
2928b0a8 | 1184 | or <varname>FailureAction=</varname> |
efe6e7d3 MO |
1185 | is a reboot action. This works just |
1186 | like the optional argument to | |
1187 | <command>systemctl reboot</command> | |
1188 | command.</para></listitem> | |
1189 | </varlistentry> | |
1190 | ||
d1ab0ca0 | 1191 | </variablelist> |
4819ff03 LP |
1192 | |
1193 | <para>Check | |
1194 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1195 | and | |
1196 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1197 | for more settings.</para> | |
1198 | ||
d1ab0ca0 LP |
1199 | </refsect1> |
1200 | ||
c485d3ba LP |
1201 | <refsect1> |
1202 | <title>Compatibility Options</title> | |
1203 | ||
1204 | <para>The following options are also available in the | |
1205 | <literal>[Service]</literal> section, but exist purely | |
1206 | for compatibility reasons and should not be used in | |
1207 | newly written service files.</para> | |
1208 | ||
ccc9a4f9 | 1209 | <variablelist class='unit-directives'> |
c485d3ba LP |
1210 | <varlistentry> |
1211 | <term><varname>SysVStartPriority=</varname></term> | |
1212 | <listitem><para>Set the SysV start | |
1213 | priority to use to order this service | |
1214 | in relation to SysV services lacking | |
1215 | LSB headers. This option is only | |
1216 | necessary to fix ordering in relation | |
bcddd5bf | 1217 | to legacy SysV services that have no |
c485d3ba | 1218 | ordering information encoded in the |
bcddd5bf JSJ |
1219 | script headers. As such, it should only |
1220 | be used as a temporary compatibility | |
1221 | option and should not be used in new unit | |
1222 | files. Almost always, it is a better | |
c485d3ba LP |
1223 | choice to add explicit ordering |
1224 | directives via | |
1225 | <varname>After=</varname> or | |
1226 | <varname>Before=</varname>, | |
bcddd5bf JSJ |
1227 | instead. For more details, see |
1228 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
1229 | If used, pass an integer value in the | |
c485d3ba LP |
1230 | range 0-99.</para></listitem> |
1231 | </varlistentry> | |
c485d3ba LP |
1232 | </variablelist> |
1233 | </refsect1> | |
1234 | ||
d1ab0ca0 LP |
1235 | <refsect1> |
1236 | <title>See Also</title> | |
1237 | <para> | |
f3e219a2 | 1238 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
67826132 | 1239 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
0d624a78 | 1240 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
4819ff03 | 1241 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
3fde5f30 | 1242 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
9cc2c8b7 ZJS |
1243 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
1244 | <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
d1ab0ca0 LP |
1245 | </para> |
1246 | </refsect1> | |
1247 | ||
1248 | </refentry> |