]>
Commit | Line | Data |
---|---|---|
c129bd5d | 1 | <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> |
d1ab0ca0 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
12b42c76 | 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
d1ab0ca0 LP |
4 | |
5 | <!-- | |
6 | This file is part of systemd. | |
7 | ||
8 | Copyright 2010 Lennart Poettering | |
9 | ||
10 | systemd is free software; you can redistribute it and/or modify it | |
5430f7f2 LP |
11 | under the terms of the GNU Lesser General Public License as published by |
12 | the Free Software Foundation; either version 2.1 of the License, or | |
d1ab0ca0 LP |
13 | (at your option) any later version. |
14 | ||
15 | systemd is distributed in the hope that it will be useful, but | |
16 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
5430f7f2 | 18 | Lesser General Public License for more details. |
d1ab0ca0 | 19 | |
5430f7f2 | 20 | You should have received a copy of the GNU Lesser General Public License |
d1ab0ca0 LP |
21 | along with systemd; If not, see <http://www.gnu.org/licenses/>. |
22 | --> | |
23 | ||
24 | <refentry id="systemd.service"> | |
798d3a52 ZJS |
25 | <refentryinfo> |
26 | <title>systemd.service</title> | |
27 | <productname>systemd</productname> | |
28 | ||
29 | <authorgroup> | |
30 | <author> | |
31 | <contrib>Developer</contrib> | |
32 | <firstname>Lennart</firstname> | |
33 | <surname>Poettering</surname> | |
34 | <email>lennart@poettering.net</email> | |
35 | </author> | |
36 | </authorgroup> | |
37 | </refentryinfo> | |
38 | ||
39 | <refmeta> | |
40 | <refentrytitle>systemd.service</refentrytitle> | |
41 | <manvolnum>5</manvolnum> | |
42 | </refmeta> | |
43 | ||
44 | <refnamediv> | |
45 | <refname>systemd.service</refname> | |
46 | <refpurpose>Service unit configuration</refpurpose> | |
47 | </refnamediv> | |
48 | ||
49 | <refsynopsisdiv> | |
50 | <para><filename><replaceable>service</replaceable>.service</filename></para> | |
51 | </refsynopsisdiv> | |
52 | ||
53 | <refsect1> | |
54 | <title>Description</title> | |
55 | ||
56 | <para>A unit configuration file whose name ends in | |
57 | <filename>.service</filename> encodes information about a process | |
58 | controlled and supervised by systemd.</para> | |
59 | ||
60 | <para>This man page lists the configuration options specific to | |
61 | this unit type. See | |
62 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
63 | for the common options of all unit configuration files. The common | |
64 | configuration items are configured in the generic | |
65 | <literal>[Unit]</literal> and <literal>[Install]</literal> | |
66 | sections. The service specific configuration options are | |
67 | configured in the <literal>[Service]</literal> section.</para> | |
68 | ||
69 | <para>Additional options are listed in | |
70 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
71 | which define the execution environment the commands are executed | |
72 | in, and in | |
73 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
74 | which define the way the processes of the service are terminated, | |
75 | and in | |
76 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
77 | which configure resource control settings for the processes of the | |
78 | service.</para> | |
79 | ||
798d3a52 ZJS |
80 | <para>If a service is requested under a certain name but no unit |
81 | configuration file is found, systemd looks for a SysV init script | |
82 | by the same name (with the <filename>.service</filename> suffix | |
83 | removed) and dynamically creates a service unit from that script. | |
84 | This is useful for compatibility with SysV. Note that this | |
85 | compatibility is quite comprehensive but not 100%. For details | |
86 | about the incompatibilities, see the <ulink | |
87 | url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities | |
c129bd5d LP |
88 | with SysV</ulink> document.</para> |
89 | </refsect1> | |
90 | ||
91 | <refsect1> | |
92 | <title>Automatic Dependencies</title> | |
93 | ||
94 | <para>Services with <varname>Type=dbus</varname> set automatically | |
95 | acquire dependencies of type <varname>Requires=</varname> and | |
96 | <varname>After=</varname> on | |
97 | <filename>dbus.socket</filename>.</para> | |
98 | ||
99 | <para>Socket activated service are automatically ordered after | |
100 | their activated <filename>.socket</filename> units via an | |
101 | automatic <varname>After=</varname> dependency.</para> | |
102 | ||
103 | <para>Unless <varname>DefaultDependencies=</varname> is set to | |
104 | <option>false</option>, service units will implicitly have | |
105 | dependencies of type <varname>Requires=</varname> and | |
106 | <varname>After=</varname> on <filename>sysinit.target</filename>, | |
107 | a dependency of type <varname>After=</varname> on | |
108 | <filename>basic.target</filename> as well as dependencies of | |
109 | type <varname>Conflicts=</varname> and <varname>Before=</varname> | |
110 | on <filename>shutdown.target</filename>. These ensure that normal | |
111 | service units pull in basic system initialization, and are | |
112 | terminated cleanly prior to system shutdown. Only services | |
113 | involved with early boot or late system shutdown should disable | |
114 | this option.</para> | |
115 | ||
ae0a5fb1 LP |
116 | <para>Instanced service units (i.e. service units with an <literal>@</literal> in their name) are assigned by |
117 | default a per-template slice unit (see | |
118 | <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>), named after the | |
119 | template unit, containing all instances of the specific template. This slice is normally stopped at shutdown, | |
120 | together with all template instances. If that is not desired, set <varname>DefaultDependencies=no</varname> in the | |
121 | template unit, and either define your own per-template slice unit file that also sets | |
122 | <varname>DefaultDependencies=no</varname>, or set <varname>Slice=system.slice</varname> (or another suitable slice) | |
123 | in the template unit. Also see | |
124 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> | |
125 | ||
c129bd5d LP |
126 | <para>Additional implicit dependencies may be added as result of |
127 | execution and resource control parameters as documented in | |
128 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
129 | and | |
130 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> | |
798d3a52 ZJS |
131 | </refsect1> |
132 | ||
133 | <refsect1> | |
134 | <title>Options</title> | |
135 | ||
136 | <para>Service files must include a <literal>[Service]</literal> | |
137 | section, which carries information about the service and the | |
138 | process it supervises. A number of options that may be used in | |
139 | this section are shared with other unit types. These options are | |
140 | documented in | |
141 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
142 | and | |
143 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
144 | The options specific to the <literal>[Service]</literal> section | |
145 | of service units are the following:</para> | |
146 | ||
147 | <variablelist class='unit-directives'> | |
148 | <varlistentry> | |
149 | <term><varname>Type=</varname></term> | |
150 | ||
151 | <listitem><para>Configures the process start-up type for this | |
152 | service unit. One of | |
153 | <option>simple</option>, | |
154 | <option>forking</option>, | |
155 | <option>oneshot</option>, | |
156 | <option>dbus</option>, | |
157 | <option>notify</option> or | |
158 | <option>idle</option>.</para> | |
159 | ||
160 | <para>If set to <option>simple</option> (the default if | |
161 | neither <varname>Type=</varname> nor | |
162 | <varname>BusName=</varname>, but <varname>ExecStart=</varname> | |
163 | are specified), it is expected that the process configured | |
164 | with <varname>ExecStart=</varname> is the main process of the | |
165 | service. In this mode, if the process offers functionality to | |
166 | other processes on the system, its communication channels | |
167 | should be installed before the daemon is started up (e.g. | |
168 | sockets set up by systemd, via socket activation), as systemd | |
169 | will immediately proceed starting follow-up units.</para> | |
170 | ||
171 | <para>If set to <option>forking</option>, it is expected that | |
172 | the process configured with <varname>ExecStart=</varname> will | |
173 | call <function>fork()</function> as part of its start-up. The | |
174 | parent process is expected to exit when start-up is complete | |
175 | and all communication channels are set up. The child continues | |
176 | to run as the main daemon process. This is the behavior of | |
177 | traditional UNIX daemons. If this setting is used, it is | |
178 | recommended to also use the <varname>PIDFile=</varname> | |
179 | option, so that systemd can identify the main process of the | |
180 | daemon. systemd will proceed with starting follow-up units as | |
181 | soon as the parent process exits.</para> | |
182 | ||
183 | <para>Behavior of <option>oneshot</option> is similar to | |
184 | <option>simple</option>; however, it is expected that the | |
185 | process has to exit before systemd starts follow-up units. | |
186 | <varname>RemainAfterExit=</varname> is particularly useful for | |
187 | this type of service. This is the implied default if neither | |
188 | <varname>Type=</varname> or <varname>ExecStart=</varname> are | |
189 | specified.</para> | |
190 | ||
191 | <para>Behavior of <option>dbus</option> is similar to | |
192 | <option>simple</option>; however, it is expected that the | |
193 | daemon acquires a name on the D-Bus bus, as configured by | |
194 | <varname>BusName=</varname>. systemd will proceed with | |
195 | starting follow-up units after the D-Bus bus name has been | |
196 | acquired. Service units with this option configured implicitly | |
197 | gain dependencies on the <filename>dbus.socket</filename> | |
198 | unit. This type is the default if <varname>BusName=</varname> | |
199 | is specified.</para> | |
200 | ||
201 | <para>Behavior of <option>notify</option> is similar to | |
202 | <option>simple</option>; however, it is expected that the | |
203 | daemon sends a notification message via | |
204 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
205 | or an equivalent call when it has finished starting up. | |
206 | systemd will proceed with starting follow-up units after this | |
207 | notification message has been sent. If this option is used, | |
208 | <varname>NotifyAccess=</varname> (see below) should be set to | |
209 | open access to the notification socket provided by systemd. If | |
210 | <varname>NotifyAccess=</varname> is not set, it will be | |
211 | implicitly set to <option>main</option>. Note that currently | |
212 | <varname>Type=</varname><option>notify</option> will not work | |
213 | if used in combination with | |
214 | <varname>PrivateNetwork=</varname><option>yes</option>.</para> | |
215 | ||
216 | <para>Behavior of <option>idle</option> is very similar to | |
217 | <option>simple</option>; however, actual execution of the | |
218 | service binary is delayed until all jobs are dispatched. This | |
219 | may be used to avoid interleaving of output of shell services | |
220 | with the status output on the console.</para> | |
221 | </listitem> | |
222 | </varlistentry> | |
223 | ||
224 | <varlistentry> | |
225 | <term><varname>RemainAfterExit=</varname></term> | |
226 | ||
227 | <listitem><para>Takes a boolean value that specifies whether | |
228 | the service shall be considered active even when all its | |
229 | processes exited. Defaults to <option>no</option>.</para> | |
230 | </listitem> | |
231 | </varlistentry> | |
232 | ||
233 | <varlistentry> | |
234 | <term><varname>GuessMainPID=</varname></term> | |
235 | ||
236 | <listitem><para>Takes a boolean value that specifies whether | |
237 | systemd should try to guess the main PID of a service if it | |
238 | cannot be determined reliably. This option is ignored unless | |
239 | <option>Type=forking</option> is set and | |
240 | <option>PIDFile=</option> is unset because for the other types | |
241 | or with an explicitly configured PID file, the main PID is | |
242 | always known. The guessing algorithm might come to incorrect | |
243 | conclusions if a daemon consists of more than one process. If | |
244 | the main PID cannot be determined, failure detection and | |
245 | automatic restarting of a service will not work reliably. | |
246 | Defaults to <option>yes</option>.</para> | |
247 | </listitem> | |
248 | </varlistentry> | |
249 | ||
250 | <varlistentry> | |
251 | <term><varname>PIDFile=</varname></term> | |
252 | ||
253 | <listitem><para>Takes an absolute file name pointing to the | |
254 | PID file of this daemon. Use of this option is recommended for | |
255 | services where <varname>Type=</varname> is set to | |
256 | <option>forking</option>. systemd will read the PID of the | |
257 | main process of the daemon after start-up of the service. | |
341db20b FS |
258 | systemd will not write to the file configured here, although |
259 | it will remove the file after the service has shut down if it | |
260 | still exists. | |
261 | </para> | |
798d3a52 ZJS |
262 | </listitem> |
263 | </varlistentry> | |
264 | ||
265 | <varlistentry> | |
266 | <term><varname>BusName=</varname></term> | |
267 | ||
268 | <listitem><para>Takes a D-Bus bus name that this service is | |
269 | reachable as. This option is mandatory for services where | |
270 | <varname>Type=</varname> is set to | |
271 | <option>dbus</option>.</para> | |
272 | </listitem> | |
273 | </varlistentry> | |
274 | ||
275 | <varlistentry> | |
276 | <term><varname>BusPolicy=</varname></term> | |
277 | ||
b8332e7a | 278 | <listitem><para>If specified, a custom kdbus |
798d3a52 ZJS |
279 | endpoint will be created and installed as the default bus node |
280 | for the service. Such a custom endpoint can hold an own set of | |
281 | policy rules that are enforced on top of the bus-wide ones. | |
282 | The custom endpoint is named after the service it was created | |
283 | for, and its node will be bind-mounted over the default bus | |
284 | node location, so the service can only access the bus through | |
285 | its own endpoint. Note that custom bus endpoints default to a | |
b938cb90 | 286 | "deny all" policy. Hence, if at least one |
798d3a52 ZJS |
287 | <varname>BusPolicy=</varname> directive is given, you have to |
288 | make sure to add explicit rules for everything the service | |
289 | should be able to do.</para> | |
290 | <para>The value of this directive is comprised | |
291 | of two parts; the bus name, and a verb to | |
292 | specify to granted access, which is one of | |
293 | <option>see</option>, | |
294 | <option>talk</option>, or | |
295 | <option>own</option>. | |
296 | <option>talk</option> implies | |
297 | <option>see</option>, and <option>own</option> | |
298 | implies both <option>talk</option> and | |
299 | <option>see</option>. | |
300 | If multiple access levels are specified for the | |
301 | same bus name, the most powerful one takes | |
302 | effect. | |
303 | </para> | |
304 | <para>Examples:</para> | |
305 | <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting> | |
306 | <programlisting>BusPolicy=org.foo.bar see</programlisting> | |
307 | <para>This option is only available on kdbus enabled systems.</para> | |
308 | </listitem> | |
309 | </varlistentry> | |
310 | ||
311 | <varlistentry> | |
312 | <term><varname>ExecStart=</varname></term> | |
313 | <listitem><para>Commands with their arguments that are | |
314 | executed when this service is started. The value is split into | |
a8eaaee7 | 315 | zero or more command lines according to the rules described |
798d3a52 ZJS |
316 | below (see section "Command Lines" below). |
317 | </para> | |
318 | ||
22065311 | 319 | <para>When <varname>Type=</varname> is not |
798d3a52 ZJS |
320 | <option>oneshot</option>, only one command may and must be |
321 | given. When <varname>Type=oneshot</varname> is used, zero or | |
322 | more commands may be specified. This can be specified by | |
323 | providing multiple command lines in the same directive, or | |
324 | alternatively, this directive may be specified more than once | |
325 | with the same effect. If the empty string is assigned to this | |
326 | option, the list of commands to start is reset, prior | |
327 | assignments of this option will have no effect. If no | |
328 | <varname>ExecStart=</varname> is specified, then the service | |
329 | must have <varname>RemainAfterExit=yes</varname> set.</para> | |
330 | ||
331 | <para>For each of the specified commands, the first argument | |
332 | must be an absolute path to an executable. Optionally, if this | |
333 | file name is prefixed with <literal>@</literal>, the second | |
334 | token will be passed as <literal>argv[0]</literal> to the | |
335 | executed process, followed by the further arguments specified. | |
336 | If the absolute filename is prefixed with | |
337 | <literal>-</literal>, an exit code of the command normally | |
338 | considered a failure (i.e. non-zero exit status or abnormal | |
339 | exit due to signal) is ignored and considered success. If both | |
340 | <literal>-</literal> and <literal>@</literal> are used, they | |
341 | can appear in either order.</para> | |
342 | ||
343 | <para>If more than one command is specified, the commands are | |
344 | invoked sequentially in the order they appear in the unit | |
345 | file. If one of the commands fails (and is not prefixed with | |
346 | <literal>-</literal>), other lines are not executed, and the | |
347 | unit is considered failed.</para> | |
348 | ||
349 | <para>Unless <varname>Type=forking</varname> is set, the | |
350 | process started via this command line will be considered the | |
351 | main process of the daemon.</para> | |
352 | </listitem> | |
353 | </varlistentry> | |
354 | ||
355 | <varlistentry> | |
356 | <term><varname>ExecStartPre=</varname></term> | |
357 | <term><varname>ExecStartPost=</varname></term> | |
358 | <listitem><para>Additional commands that are executed before | |
359 | or after the command in <varname>ExecStart=</varname>, | |
360 | respectively. Syntax is the same as for | |
361 | <varname>ExecStart=</varname>, except that multiple command | |
362 | lines are allowed and the commands are executed one after the | |
363 | other, serially.</para> | |
364 | ||
365 | <para>If any of those commands (not prefixed with | |
366 | <literal>-</literal>) fail, the rest are not executed and the | |
367 | unit is considered failed.</para> | |
b481de3b | 368 | |
12e2683d RM |
369 | <para><varname>ExecStart=</varname> commands are only run after |
370 | all <varname>ExecStartPre=</varname> commands that were not prefixed | |
371 | with a <literal>-</literal> exit successfully.</para> | |
372 | ||
373 | <para><varname>ExecStartPost=</varname> commands are only run after | |
374 | the service has started, as determined by <varname>Type=</varname> | |
a8eaaee7 | 375 | (i.e. the process has been started for <varname>Type=simple</varname> |
12e2683d RM |
376 | or <varname>Type=idle</varname>, the process exits successfully for |
377 | <varname>Type=oneshot</varname>, the initial process exits successfully | |
378 | for <varname>Type=forking</varname>, <literal>READY=1</literal> is sent | |
379 | for <varname>Type=notify</varname>, or the <varname>BusName=</varname> | |
380 | has been taken for <varname>Type=dbus</varname>).</para> | |
381 | ||
b481de3b LP |
382 | <para>Note that <varname>ExecStartPre=</varname> may not be |
383 | used to start long-running processes. All processes forked | |
384 | off by processes invoked via <varname>ExecStartPre=</varname> will | |
385 | be killed before the next service process is run.</para> | |
798d3a52 ZJS |
386 | </listitem> |
387 | </varlistentry> | |
388 | ||
389 | <varlistentry> | |
390 | <term><varname>ExecReload=</varname></term> | |
391 | <listitem><para>Commands to execute to trigger a configuration | |
392 | reload in the service. This argument takes multiple command | |
393 | lines, following the same scheme as described for | |
394 | <varname>ExecStart=</varname> above. Use of this setting is | |
395 | optional. Specifier and environment variable substitution is | |
396 | supported here following the same scheme as for | |
397 | <varname>ExecStart=</varname>.</para> | |
398 | ||
399 | <para>One additional, special environment variable is set: if | |
400 | known, <varname>$MAINPID</varname> is set to the main process | |
401 | of the daemon, and may be used for command lines like the | |
402 | following:</para> | |
403 | ||
404 | <programlisting>/bin/kill -HUP $MAINPID</programlisting> | |
405 | ||
406 | <para>Note however that reloading a daemon by sending a signal | |
407 | (as with the example line above) is usually not a good choice, | |
408 | because this is an asynchronous operation and hence not | |
409 | suitable to order reloads of multiple services against each | |
410 | other. It is strongly recommended to set | |
411 | <varname>ExecReload=</varname> to a command that not only | |
412 | triggers a configuration reload of the daemon, but also | |
413 | synchronously waits for it to complete.</para> | |
414 | </listitem> | |
415 | </varlistentry> | |
416 | ||
417 | <varlistentry> | |
418 | <term><varname>ExecStop=</varname></term> | |
419 | <listitem><para>Commands to execute to stop the service | |
420 | started via <varname>ExecStart=</varname>. This argument takes | |
421 | multiple command lines, following the same scheme as described | |
422 | for <varname>ExecStart=</varname> above. Use of this setting | |
423 | is optional. After the commands configured in this option are | |
424 | run, all processes remaining for a service are terminated | |
425 | according to the <varname>KillMode=</varname> setting (see | |
426 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
cceb20c7 LP |
427 | If this option is not specified, the process is terminated by |
428 | sending the signal specified in <varname>KillSignal=</varname> | |
429 | when service stop is requested. Specifier and environment | |
430 | variable substitution is supported (including | |
431 | <varname>$MAINPID</varname>, see above).</para> | |
432 | ||
433 | <para>Note that it is usually not sufficient to specify a | |
434 | command for this setting that only asks the service to | |
b938cb90 | 435 | terminate (for example, by queuing some form of termination |
cceb20c7 LP |
436 | signal for it), but does not wait for it to do so. Since the |
437 | remaining processes of the services are killed using | |
438 | <constant>SIGKILL</constant> immediately after the command | |
b938cb90 | 439 | exited, this would not result in a clean stop. The specified |
cceb20c7 LP |
440 | command should hence be a synchronous operation, not an |
441 | asynchronous one.</para></listitem> | |
798d3a52 ZJS |
442 | </varlistentry> |
443 | ||
444 | <varlistentry> | |
445 | <term><varname>ExecStopPost=</varname></term> | |
446 | <listitem><para>Additional commands that are executed after | |
447 | the service was stopped. This includes cases where the | |
448 | commands configured in <varname>ExecStop=</varname> were used, | |
449 | where the service does not have any | |
450 | <varname>ExecStop=</varname> defined, or where the service | |
451 | exited unexpectedly. This argument takes multiple command | |
452 | lines, following the same scheme as described for | |
22065311 | 453 | <varname>ExecStart=</varname>. Use of these settings is |
798d3a52 ZJS |
454 | optional. Specifier and environment variable substitution is |
455 | supported.</para></listitem> | |
456 | </varlistentry> | |
457 | ||
458 | <varlistentry> | |
459 | <term><varname>RestartSec=</varname></term> | |
460 | <listitem><para>Configures the time to sleep before restarting | |
461 | a service (as configured with <varname>Restart=</varname>). | |
462 | Takes a unit-less value in seconds, or a time span value such | |
463 | as "5min 20s". Defaults to 100ms.</para></listitem> | |
464 | </varlistentry> | |
465 | ||
466 | <varlistentry> | |
467 | <term><varname>TimeoutStartSec=</varname></term> | |
468 | <listitem><para>Configures the time to wait for start-up. If a | |
469 | daemon service does not signal start-up completion within the | |
470 | configured time, the service will be considered failed and | |
471 | will be shut down again. Takes a unit-less value in seconds, | |
472 | or a time span value such as "5min 20s". Pass | |
473 | <literal>0</literal> to disable the timeout logic. Defaults to | |
474 | <varname>DefaultTimeoutStartSec=</varname> from the manager | |
475 | configuration file, except when | |
476 | <varname>Type=oneshot</varname> is used, in which case the | |
477 | timeout is disabled by default (see | |
478 | <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
479 | </para></listitem> | |
480 | </varlistentry> | |
481 | ||
482 | <varlistentry> | |
483 | <term><varname>TimeoutStopSec=</varname></term> | |
484 | <listitem><para>Configures the time to wait for stop. If a | |
485 | service is asked to stop, but does not terminate in the | |
486 | specified time, it will be terminated forcibly via | |
487 | <constant>SIGTERM</constant>, and after another timeout of | |
488 | equal duration with <constant>SIGKILL</constant> (see | |
489 | <varname>KillMode=</varname> in | |
490 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
491 | Takes a unit-less value in seconds, or a time span value such | |
492 | as "5min 20s". Pass <literal>0</literal> to disable the | |
493 | timeout logic. Defaults to | |
494 | <varname>DefaultTimeoutStopSec=</varname> from the manager | |
495 | configuration file (see | |
496 | <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). | |
497 | </para></listitem> | |
498 | </varlistentry> | |
499 | ||
500 | <varlistentry> | |
501 | <term><varname>TimeoutSec=</varname></term> | |
502 | <listitem><para>A shorthand for configuring both | |
503 | <varname>TimeoutStartSec=</varname> and | |
504 | <varname>TimeoutStopSec=</varname> to the specified value. | |
505 | </para></listitem> | |
506 | </varlistentry> | |
507 | ||
508 | <varlistentry> | |
509 | <term><varname>WatchdogSec=</varname></term> | |
510 | <listitem><para>Configures the watchdog timeout for a service. | |
511 | The watchdog is activated when the start-up is completed. The | |
512 | service must call | |
513 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
514 | regularly with <literal>WATCHDOG=1</literal> (i.e. the | |
515 | "keep-alive ping"). If the time between two such calls is | |
516 | larger than the configured time, then the service is placed in | |
517 | a failed state and it will be terminated with | |
22065311 | 518 | <constant>SIGABRT</constant>. By setting |
a0533c6d EV |
519 | <varname>Restart=</varname> to <option>on-failure</option>, |
520 | <option>on-watchdog</option>, <option>on-abnormal</option> or | |
798d3a52 ZJS |
521 | <option>always</option>, the service will be automatically |
522 | restarted. The time configured here will be passed to the | |
523 | executed service process in the | |
524 | <varname>WATCHDOG_USEC=</varname> environment variable. This | |
525 | allows daemons to automatically enable the keep-alive pinging | |
526 | logic if watchdog support is enabled for the service. If this | |
527 | option is used, <varname>NotifyAccess=</varname> (see below) | |
528 | should be set to open access to the notification socket | |
529 | provided by systemd. If <varname>NotifyAccess=</varname> is | |
530 | not set, it will be implicitly set to <option>main</option>. | |
582f2fcb EV |
531 | Defaults to 0, which disables this feature. The service can |
532 | check whether the service manager expects watchdog keep-alive | |
533 | notifications. See | |
534 | <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
a0533c6d EV |
535 | for details. |
536 | <citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
537 | may be used to enable automatic watchdog notification support. | |
582f2fcb | 538 | </para></listitem> |
798d3a52 ZJS |
539 | </varlistentry> |
540 | ||
541 | <varlistentry> | |
542 | <term><varname>Restart=</varname></term> | |
543 | <listitem><para>Configures whether the service shall be | |
544 | restarted when the service process exits, is killed, or a | |
545 | timeout is reached. The service process may be the main | |
546 | service process, but it may also be one of the processes | |
547 | specified with <varname>ExecStartPre=</varname>, | |
548 | <varname>ExecStartPost=</varname>, | |
549 | <varname>ExecStop=</varname>, | |
550 | <varname>ExecStopPost=</varname>, or | |
551 | <varname>ExecReload=</varname>. When the death of the process | |
552 | is a result of systemd operation (e.g. service stop or | |
553 | restart), the service will not be restarted. Timeouts include | |
554 | missing the watchdog "keep-alive ping" deadline and a service | |
555 | start, reload, and stop operation timeouts.</para> | |
556 | ||
557 | <para>Takes one of | |
558 | <option>no</option>, | |
559 | <option>on-success</option>, | |
560 | <option>on-failure</option>, | |
561 | <option>on-abnormal</option>, | |
562 | <option>on-watchdog</option>, | |
563 | <option>on-abort</option>, or | |
564 | <option>always</option>. | |
565 | If set to <option>no</option> (the default), the service will | |
566 | not be restarted. If set to <option>on-success</option>, it | |
567 | will be restarted only when the service process exits cleanly. | |
568 | In this context, a clean exit means an exit code of 0, or one | |
569 | of the signals | |
570 | <constant>SIGHUP</constant>, | |
571 | <constant>SIGINT</constant>, | |
572 | <constant>SIGTERM</constant> or | |
573 | <constant>SIGPIPE</constant>, and | |
574 | additionally, exit statuses and signals specified in | |
575 | <varname>SuccessExitStatus=</varname>. If set to | |
576 | <option>on-failure</option>, the service will be restarted | |
577 | when the process exits with a non-zero exit code, is | |
578 | terminated by a signal (including on core dump, but excluding | |
ff9b60f3 | 579 | the aforementioned four signals), when an operation (such as |
798d3a52 ZJS |
580 | service reload) times out, and when the configured watchdog |
581 | timeout is triggered. If set to <option>on-abnormal</option>, | |
582 | the service will be restarted when the process is terminated | |
583 | by a signal (including on core dump, excluding the | |
584 | aforementioned four signals), when an operation times out, or | |
585 | when the watchdog timeout is triggered. If set to | |
586 | <option>on-abort</option>, the service will be restarted only | |
587 | if the service process exits due to an uncaught signal not | |
588 | specified as a clean exit status. If set to | |
589 | <option>on-watchdog</option>, the service will be restarted | |
590 | only if the watchdog timeout for the service expires. If set | |
591 | to <option>always</option>, the service will be restarted | |
592 | regardless of whether it exited cleanly or not, got terminated | |
593 | abnormally by a signal, or hit a timeout.</para> | |
594 | ||
595 | <table> | |
596 | <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> | |
597 | ||
598 | <tgroup cols='2'> | |
599 | <colspec colname='path' /> | |
600 | <colspec colname='expl' /> | |
601 | <thead> | |
602 | <row> | |
603 | <entry>Restart settings/Exit causes</entry> | |
604 | <entry><option>no</option></entry> | |
605 | <entry><option>always</option></entry> | |
606 | <entry><option>on-success</option></entry> | |
607 | <entry><option>on-failure</option></entry> | |
608 | <entry><option>on-abnormal</option></entry> | |
609 | <entry><option>on-abort</option></entry> | |
610 | <entry><option>on-watchdog</option></entry> | |
611 | </row> | |
612 | </thead> | |
613 | <tbody> | |
614 | <row> | |
615 | <entry>Clean exit code or signal</entry> | |
616 | <entry/> | |
617 | <entry>X</entry> | |
618 | <entry>X</entry> | |
619 | <entry/> | |
620 | <entry/> | |
621 | <entry/> | |
622 | <entry/> | |
623 | </row> | |
624 | <row> | |
625 | <entry>Unclean exit code</entry> | |
626 | <entry/> | |
627 | <entry>X</entry> | |
628 | <entry/> | |
629 | <entry>X</entry> | |
630 | <entry/> | |
631 | <entry/> | |
632 | <entry/> | |
633 | </row> | |
634 | <row> | |
635 | <entry>Unclean signal</entry> | |
636 | <entry/> | |
637 | <entry>X</entry> | |
638 | <entry/> | |
639 | <entry>X</entry> | |
640 | <entry>X</entry> | |
641 | <entry>X</entry> | |
642 | <entry/> | |
643 | </row> | |
644 | <row> | |
645 | <entry>Timeout</entry> | |
646 | <entry/> | |
647 | <entry>X</entry> | |
648 | <entry/> | |
649 | <entry>X</entry> | |
650 | <entry>X</entry> | |
651 | <entry/> | |
652 | <entry/> | |
653 | </row> | |
654 | <row> | |
655 | <entry>Watchdog</entry> | |
656 | <entry/> | |
657 | <entry>X</entry> | |
658 | <entry/> | |
659 | <entry>X</entry> | |
660 | <entry>X</entry> | |
661 | <entry/> | |
662 | <entry>X</entry> | |
663 | </row> | |
664 | </tbody> | |
665 | </tgroup> | |
666 | </table> | |
667 | ||
b938cb90 | 668 | <para>As exceptions to the setting above, the service will not |
798d3a52 ZJS |
669 | be restarted if the exit code or signal is specified in |
670 | <varname>RestartPreventExitStatus=</varname> (see below). | |
671 | Also, the services will always be restarted if the exit code | |
672 | or signal is specified in | |
673 | <varname>RestartForceExitStatus=</varname> (see below).</para> | |
674 | ||
675 | <para>Setting this to <option>on-failure</option> is the | |
676 | recommended choice for long-running services, in order to | |
677 | increase reliability by attempting automatic recovery from | |
678 | errors. For services that shall be able to terminate on their | |
679 | own choice (and avoid immediate restarting), | |
680 | <option>on-abnormal</option> is an alternative choice.</para> | |
681 | </listitem> | |
682 | </varlistentry> | |
683 | ||
684 | <varlistentry> | |
685 | <term><varname>SuccessExitStatus=</varname></term> | |
b938cb90 JE |
686 | <listitem><para>Takes a list of exit status definitions that, |
687 | when returned by the main service process, will be considered | |
798d3a52 ZJS |
688 | successful termination, in addition to the normal successful |
689 | exit code 0 and the signals <constant>SIGHUP</constant>, | |
690 | <constant>SIGINT</constant>, <constant>SIGTERM</constant>, and | |
691 | <constant>SIGPIPE</constant>. Exit status definitions can | |
692 | either be numeric exit codes or termination signal names, | |
693 | separated by spaces. For example: | |
dc83f27a LP |
694 | |
695 | <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> | |
696 | ||
697 | ensures that exit codes 1, 2, 8 and | |
798d3a52 ZJS |
698 | the termination signal <constant>SIGKILL</constant> are |
699 | considered clean service terminations. | |
700 | </para> | |
701 | ||
702 | <para>Note that if a process has a signal handler installed | |
703 | and exits by calling | |
704 | <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
705 | in response to a signal, the information about the signal is | |
706 | lost. Programs should instead perform cleanup and kill | |
707 | themselves with the same signal instead. See | |
708 | <ulink url="http://www.cons.org/cracauer/sigint.html">Proper | |
709 | handling of SIGINT/SIGQUIT — How to be a proper | |
710 | program</ulink>.</para> | |
711 | ||
712 | <para>This option may appear more than once, in which case the | |
713 | list of successful exit statuses is merged. If the empty | |
714 | string is assigned to this option, the list is reset, all | |
715 | prior assignments of this option will have no | |
716 | effect.</para></listitem> | |
717 | </varlistentry> | |
718 | ||
719 | <varlistentry> | |
720 | <term><varname>RestartPreventExitStatus=</varname></term> | |
b938cb90 JE |
721 | <listitem><para>Takes a list of exit status definitions that, |
722 | when returned by the main service process, will prevent | |
798d3a52 ZJS |
723 | automatic service restarts, regardless of the restart setting |
724 | configured with <varname>Restart=</varname>. Exit status | |
725 | definitions can either be numeric exit codes or termination | |
726 | signal names, and are separated by spaces. Defaults to the | |
727 | empty list, so that, by default, no exit status is excluded | |
728 | from the configured restart logic. For example: | |
dc83f27a LP |
729 | |
730 | <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> | |
731 | ||
732 | ensures that exit codes 1 and 6 and the termination signal | |
733 | <constant>SIGABRT</constant> will not result in automatic | |
734 | service restarting. This option may appear more than once, in | |
735 | which case the list of restart-preventing statuses is | |
736 | merged. If the empty string is assigned to this option, the | |
737 | list is reset and all prior assignments of this option will | |
738 | have no effect.</para></listitem> | |
798d3a52 ZJS |
739 | </varlistentry> |
740 | ||
741 | <varlistentry> | |
742 | <term><varname>RestartForceExitStatus=</varname></term> | |
b938cb90 JE |
743 | <listitem><para>Takes a list of exit status definitions that, |
744 | when returned by the main service process, will force automatic | |
798d3a52 ZJS |
745 | service restarts, regardless of the restart setting configured |
746 | with <varname>Restart=</varname>. The argument format is | |
747 | similar to | |
748 | <varname>RestartPreventExitStatus=</varname>.</para></listitem> | |
749 | </varlistentry> | |
750 | ||
751 | <varlistentry> | |
752 | <term><varname>PermissionsStartOnly=</varname></term> | |
753 | <listitem><para>Takes a boolean argument. If true, the | |
754 | permission-related execution options, as configured with | |
755 | <varname>User=</varname> and similar options (see | |
756 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
757 | for more information), are only applied to the process started | |
758 | with | |
759 | <varname>ExecStart=</varname>, and not to the various other | |
760 | <varname>ExecStartPre=</varname>, | |
761 | <varname>ExecStartPost=</varname>, | |
762 | <varname>ExecReload=</varname>, | |
763 | <varname>ExecStop=</varname>, and | |
764 | <varname>ExecStopPost=</varname> | |
765 | commands. If false, the setting is applied to all configured | |
766 | commands the same way. Defaults to false.</para></listitem> | |
767 | </varlistentry> | |
768 | ||
769 | <varlistentry> | |
770 | <term><varname>RootDirectoryStartOnly=</varname></term> | |
771 | <listitem><para>Takes a boolean argument. If true, the root | |
772 | directory, as configured with the | |
773 | <varname>RootDirectory=</varname> option (see | |
774 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
775 | for more information), is only applied to the process started | |
776 | with <varname>ExecStart=</varname>, and not to the various | |
777 | other <varname>ExecStartPre=</varname>, | |
778 | <varname>ExecStartPost=</varname>, | |
779 | <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, | |
780 | and <varname>ExecStopPost=</varname> commands. If false, the | |
781 | setting is applied to all configured commands the same way. | |
782 | Defaults to false.</para></listitem> | |
783 | </varlistentry> | |
784 | ||
785 | <varlistentry> | |
786 | <term><varname>NonBlocking=</varname></term> | |
787 | <listitem><para>Set the <constant>O_NONBLOCK</constant> flag | |
788 | for all file descriptors passed via socket-based activation. | |
789 | If true, all file descriptors >= 3 (i.e. all except stdin, | |
790 | stdout, and stderr) will have the | |
791 | <constant>O_NONBLOCK</constant> flag set and hence are in | |
792 | non-blocking mode. This option is only useful in conjunction | |
793 | with a socket unit, as described in | |
794 | <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
795 | Defaults to false.</para></listitem> | |
796 | </varlistentry> | |
797 | ||
798 | <varlistentry> | |
799 | <term><varname>NotifyAccess=</varname></term> | |
800 | <listitem><para>Controls access to the service status | |
801 | notification socket, as accessible via the | |
802 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
803 | call. Takes one of <option>none</option> (the default), | |
804 | <option>main</option> or <option>all</option>. If | |
805 | <option>none</option>, no daemon status updates are accepted | |
806 | from the service processes, all status update messages are | |
807 | ignored. If <option>main</option>, only service updates sent | |
808 | from the main process of the service are accepted. If | |
809 | <option>all</option>, all services updates from all members of | |
810 | the service's control group are accepted. This option should | |
811 | be set to open access to the notification socket when using | |
812 | <varname>Type=notify</varname> or | |
813 | <varname>WatchdogSec=</varname> (see above). If those options | |
814 | are used but <varname>NotifyAccess=</varname> is not | |
815 | configured, it will be implicitly set to | |
816 | <option>main</option>.</para></listitem> | |
817 | </varlistentry> | |
818 | ||
819 | <varlistentry> | |
820 | <term><varname>Sockets=</varname></term> | |
821 | <listitem><para>Specifies the name of the socket units this | |
822 | service shall inherit socket file descriptors from when the | |
b938cb90 JE |
823 | service is started. Normally, it should not be necessary to use |
824 | this setting, as all socket file descriptors whose unit shares | |
798d3a52 ZJS |
825 | the same name as the service (subject to the different unit |
826 | name suffix of course) are passed to the spawned | |
827 | process.</para> | |
828 | ||
829 | <para>Note that the same socket file descriptors may be passed | |
830 | to multiple processes simultaneously. Also note that a | |
831 | different service may be activated on incoming socket traffic | |
832 | than the one which is ultimately configured to inherit the | |
b938cb90 | 833 | socket file descriptors. Or, in other words: the |
798d3a52 ZJS |
834 | <varname>Service=</varname> setting of |
835 | <filename>.socket</filename> units does not have to match the | |
836 | inverse of the <varname>Sockets=</varname> setting of the | |
837 | <filename>.service</filename> it refers to.</para> | |
838 | ||
839 | <para>This option may appear more than once, in which case the | |
840 | list of socket units is merged. If the empty string is | |
841 | assigned to this option, the list of sockets is reset, and all | |
842 | prior uses of this setting will have no | |
843 | effect.</para></listitem> | |
844 | </varlistentry> | |
845 | ||
846 | <varlistentry> | |
847 | <term><varname>StartLimitInterval=</varname></term> | |
848 | <term><varname>StartLimitBurst=</varname></term> | |
849 | ||
850 | <listitem><para>Configure service start rate limiting. By | |
851 | default, services which are started more than 5 times within | |
852 | 10 seconds are not permitted to start any more times until the | |
853 | 10 second interval ends. With these two options, this rate | |
854 | limiting may be modified. Use | |
855 | <varname>StartLimitInterval=</varname> to configure the | |
856 | checking interval (defaults to | |
857 | <varname>DefaultStartLimitInterval=</varname> in manager | |
858 | configuration file, set to 0 to disable any kind of rate | |
859 | limiting). Use <varname>StartLimitBurst=</varname> to | |
860 | configure how many starts per interval are allowed (defaults | |
861 | to <varname>DefaultStartLimitBurst=</varname> in manager | |
862 | configuration file). These configuration options are | |
863 | particularly useful in conjunction with | |
864 | <varname>Restart=</varname>; however, they apply to all kinds | |
865 | of starts (including manual), not just those triggered by the | |
866 | <varname>Restart=</varname> logic. Note that units which are | |
867 | configured for <varname>Restart=</varname> and which reach the | |
868 | start limit are not attempted to be restarted anymore; | |
869 | however, they may still be restarted manually at a later | |
870 | point, from which point on, the restart logic is again | |
871 | activated. Note that <command>systemctl reset-failed</command> | |
872 | will cause the restart rate counter for a service to be | |
873 | flushed, which is useful if the administrator wants to | |
874 | manually start a service and the start limit interferes with | |
875 | that.</para></listitem> | |
876 | </varlistentry> | |
877 | ||
878 | <varlistentry> | |
879 | <term><varname>StartLimitAction=</varname></term> | |
880 | ||
881 | <listitem><para>Configure the action to take if the rate limit | |
882 | configured with <varname>StartLimitInterval=</varname> and | |
883 | <varname>StartLimitBurst=</varname> is hit. Takes one of | |
884 | <option>none</option>, | |
885 | <option>reboot</option>, | |
886 | <option>reboot-force</option>, | |
887 | <option>reboot-immediate</option>, | |
888 | <option>poweroff</option>, | |
889 | <option>poweroff-force</option> or | |
890 | <option>poweroff-immediate</option>. If | |
891 | <option>none</option> is set, hitting the rate limit will | |
892 | trigger no action besides that the start will not be | |
893 | permitted. <option>reboot</option> causes a reboot following | |
894 | the normal shutdown procedure (i.e. equivalent to | |
895 | <command>systemctl reboot</command>). | |
896 | <option>reboot-force</option> causes a forced reboot which | |
897 | will terminate all processes forcibly but should cause no | |
898 | dirty file systems on reboot (i.e. equivalent to | |
899 | <command>systemctl reboot -f</command>) and | |
900 | <option>reboot-immediate</option> causes immediate execution | |
901 | of the | |
902 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
a8eaaee7 | 903 | system call, which might result in data loss. Similarly, |
798d3a52 ZJS |
904 | <option>poweroff</option>, <option>poweroff-force</option>, |
905 | <option>poweroff-immediate</option> have the effect of | |
906 | powering down the system with similar semantics. Defaults to | |
907 | <option>none</option>.</para></listitem> | |
908 | </varlistentry> | |
909 | ||
910 | <varlistentry> | |
911 | <term><varname>FailureAction=</varname></term> | |
912 | <listitem><para>Configure the action to take when the service | |
913 | enters a failed state. Takes the same values as | |
914 | <varname>StartLimitAction=</varname> and executes the same | |
915 | actions. Defaults to <option>none</option>. </para></listitem> | |
916 | </varlistentry> | |
917 | ||
918 | <varlistentry> | |
919 | <term><varname>RebootArgument=</varname></term> | |
920 | <listitem><para>Configure the optional argument for the | |
921 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
922 | system call if <varname>StartLimitAction=</varname> or | |
923 | <varname>FailureAction=</varname> is a reboot action. This | |
924 | works just like the optional argument to <command>systemctl | |
925 | reboot</command> command.</para></listitem> | |
926 | </varlistentry> | |
927 | ||
928 | <varlistentry> | |
929 | <term><varname>FileDescriptorStoreMax=</varname></term> | |
930 | <listitem><para>Configure how many file descriptors may be | |
931 | stored in the service manager for the service using | |
932 | <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s | |
933 | <literal>FDSTORE=1</literal> messages. This is useful for | |
934 | implementing service restart schemes where the state is | |
935 | serialized to <filename>/run</filename> and the file | |
936 | descriptors passed to the service manager, to allow restarts | |
937 | without losing state. Defaults to 0, i.e. no file descriptors | |
938 | may be stored in the service manager by default. All file | |
939 | descriptors passed to the service manager from a specific | |
940 | service are passed back to the service's main process on the | |
941 | next service restart. Any file descriptors passed to the | |
942 | service manager are automatically closed when POLLHUP or | |
943 | POLLERR is seen on them, or when the service is fully stopped | |
944 | and no job queued or being executed for it.</para></listitem> | |
945 | </varlistentry> | |
946 | ||
8c7c9839 PS |
947 | <varlistentry> |
948 | <term><varname>USBFunctionDescriptors=</varname></term> | |
3d314510 LP |
949 | <listitem><para>Configure the location of a file containing |
950 | <ulink | |
951 | url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB | |
952 | FunctionFS</ulink> descriptors, for implementation of USB | |
a8eaaee7 | 953 | gadget functions. This is used only in conjunction with a |
3d314510 | 954 | socket unit with <varname>ListenUSBFunction=</varname> |
a8eaaee7 | 955 | configured. The contents of this file are written to the |
3d314510 LP |
956 | <filename>ep0</filename> file after it is |
957 | opened.</para></listitem> | |
8c7c9839 PS |
958 | </varlistentry> |
959 | ||
960 | <varlistentry> | |
961 | <term><varname>USBFunctionStrings=</varname></term> | |
3d314510 LP |
962 | <listitem><para>Configure the location of a file containing |
963 | USB FunctionFS strings. Behavior is similar to | |
964 | <varname>USBFunctionDescriptors=</varname> | |
965 | above.</para></listitem> | |
8c7c9839 PS |
966 | </varlistentry> |
967 | ||
798d3a52 ZJS |
968 | </variablelist> |
969 | ||
970 | <para>Check | |
971 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
972 | and | |
973 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
974 | for more settings.</para> | |
975 | ||
976 | </refsect1> | |
977 | ||
978 | <refsect1> | |
979 | <title>Command lines</title> | |
980 | ||
981 | <para>This section describes command line parsing and | |
ff9b60f3 | 982 | variable and specifier substitutions for |
798d3a52 ZJS |
983 | <varname>ExecStart=</varname>, |
984 | <varname>ExecStartPre=</varname>, | |
985 | <varname>ExecStartPost=</varname>, | |
986 | <varname>ExecReload=</varname>, | |
987 | <varname>ExecStop=</varname>, and | |
988 | <varname>ExecStopPost=</varname> options.</para> | |
989 | ||
990 | <para>Multiple command lines may be concatenated in a single | |
991 | directive by separating them with semicolons (these semicolons | |
992 | must be passed as separate words). Lone semicolons may be escaped | |
993 | as <literal>\;</literal>.</para> | |
994 | ||
995 | <para>Each command line is split on whitespace, with the first | |
996 | item being the command to execute, and the subsequent items being | |
997 | the arguments. Double quotes ("...") and single quotes ('...') may | |
998 | be used, in which case everything until the next matching quote | |
999 | becomes part of the same argument. C-style escapes are also | |
388a91b0 ZJS |
1000 | supported. The table below contains the list of allowed escape |
1001 | patterns. Only patterns which match the syntax in the table are | |
1002 | allowed; others will result in an error, and must be escaped by | |
1003 | doubling the backslash. Quotes themselves are removed after | |
798d3a52 ZJS |
1004 | parsing and escape sequences substituted. In addition, a trailing |
1005 | backslash (<literal>\</literal>) may be used to merge lines. | |
1006 | </para> | |
1007 | ||
1008 | <para>This syntax is intended to be very similar to shell syntax, | |
1009 | but only the meta-characters and expansions described in the | |
1010 | following paragraphs are understood. Specifically, redirection | |
1011 | using | |
1012 | <literal><</literal>, | |
1013 | <literal><<</literal>, | |
1014 | <literal>></literal>, and | |
1015 | <literal>>></literal>, pipes using | |
1016 | <literal>|</literal>, running programs in the background using | |
1017 | <literal>&</literal>, and <emphasis>other elements of shell | |
1018 | syntax are not supported</emphasis>.</para> | |
1019 | ||
388a91b0 | 1020 | <para>The command to execute must be an absolute path name. It may |
798d3a52 ZJS |
1021 | contain spaces, but control characters are not allowed.</para> |
1022 | ||
1023 | <para>The command line accepts <literal>%</literal> specifiers as | |
1024 | described in | |
1025 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
1026 | Note that the first argument of the command line (i.e. the program | |
1027 | to execute) may not include specifiers.</para> | |
1028 | ||
1029 | <para>Basic environment variable substitution is supported. Use | |
1030 | <literal>${FOO}</literal> as part of a word, or as a word of its | |
1031 | own, on the command line, in which case it will be replaced by the | |
1032 | value of the environment variable including all whitespace it | |
1033 | contains, resulting in a single argument. Use | |
1034 | <literal>$FOO</literal> as a separate word on the command line, in | |
1035 | which case it will be replaced by the value of the environment | |
b938cb90 | 1036 | variable split at whitespace, resulting in zero or more arguments. |
3faf145d | 1037 | For this type of expansion, quotes are respected when splitting |
798d3a52 ZJS |
1038 | into words, and afterwards removed.</para> |
1039 | ||
1040 | <para>Example:</para> | |
1041 | ||
1042 | <programlisting>Environment="ONE=one" 'TWO=two two' | |
5d9a2698 ZJS |
1043 | ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> |
1044 | ||
798d3a52 ZJS |
1045 | <para>This will execute <command>/bin/echo</command> with four |
1046 | arguments: <literal>one</literal>, <literal>two</literal>, | |
1047 | <literal>two</literal>, and <literal>two two</literal>.</para> | |
5d9a2698 | 1048 | |
798d3a52 ZJS |
1049 | <para>Example:</para> |
1050 | <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= | |
5d9a2698 ZJS |
1051 | ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} |
1052 | ExecStart=/bin/echo $ONE $TWO $THREE</programlisting> | |
798d3a52 ZJS |
1053 | <para>This results in <filename>echo</filename> being |
1054 | called twice, the first time with arguments | |
1055 | <literal>'one'</literal>, | |
1056 | <literal>'two two' too</literal>, <literal></literal>, | |
1057 | and the second time with arguments | |
1058 | <literal>one</literal>, <literal>two two</literal>, | |
1059 | <literal>too</literal>. | |
1060 | </para> | |
1061 | ||
1062 | <para>To pass a literal dollar sign, use <literal>$$</literal>. | |
1063 | Variables whose value is not known at expansion time are treated | |
1064 | as empty strings. Note that the first argument (i.e. the program | |
1065 | to execute) may not be a variable.</para> | |
1066 | ||
1067 | <para>Variables to be used in this fashion may be defined through | |
1068 | <varname>Environment=</varname> and | |
1069 | <varname>EnvironmentFile=</varname>. In addition, variables listed | |
1070 | in the section "Environment variables in spawned processes" in | |
1071 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1072 | which are considered "static configuration", may be used (this | |
1073 | includes e.g. <varname>$USER</varname>, but not | |
1074 | <varname>$TERM</varname>).</para> | |
1075 | ||
1076 | <para>Note that shell command lines are not directly supported. If | |
1077 | shell command lines are to be used, they need to be passed | |
1078 | explicitly to a shell implementation of some kind. Example:</para> | |
1079 | <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> | |
1080 | ||
1081 | <para>Example:</para> | |
1082 | ||
1083 | <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> | |
1084 | ||
1085 | <para>This will execute <command>/bin/echo</command> two times, | |
1086 | each time with one argument: <literal>one</literal> and | |
1087 | <literal>two two</literal>, respectively. Because two commands are | |
1088 | specified, <varname>Type=oneshot</varname> must be used.</para> | |
1089 | ||
1090 | <para>Example:</para> | |
1091 | ||
1092 | <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ | |
30d88d54 ZJS |
1093 | /bin/ls</programlisting> |
1094 | ||
798d3a52 ZJS |
1095 | <para>This will execute <command>/bin/echo</command> |
1096 | with five arguments: <literal>/</literal>, | |
1097 | <literal>>/dev/null</literal>, | |
1098 | <literal>&</literal>, <literal>;</literal>, and | |
1099 | <literal>/bin/ls</literal>.</para> | |
1100 | ||
1101 | <table> | |
1102 | <title>C escapes supported in command lines and environment variables</title> | |
1103 | <tgroup cols='2'> | |
1104 | <colspec colname='escape' /> | |
1105 | <colspec colname='meaning' /> | |
1106 | <thead> | |
1107 | <row> | |
1108 | <entry>Literal</entry> | |
1109 | <entry>Actual value</entry> | |
1110 | </row> | |
1111 | </thead> | |
1112 | <tbody> | |
1113 | <row> | |
1114 | <entry><literal>\a</literal></entry> | |
1115 | <entry>bell</entry> | |
1116 | </row> | |
1117 | <row> | |
1118 | <entry><literal>\b</literal></entry> | |
1119 | <entry>backspace</entry> | |
1120 | </row> | |
1121 | <row> | |
1122 | <entry><literal>\f</literal></entry> | |
1123 | <entry>form feed</entry> | |
1124 | </row> | |
1125 | <row> | |
1126 | <entry><literal>\n</literal></entry> | |
1127 | <entry>newline</entry> | |
1128 | </row> | |
1129 | <row> | |
1130 | <entry><literal>\r</literal></entry> | |
1131 | <entry>carriage return</entry> | |
1132 | </row> | |
1133 | <row> | |
1134 | <entry><literal>\t</literal></entry> | |
1135 | <entry>tab</entry> | |
1136 | </row> | |
1137 | <row> | |
1138 | <entry><literal>\v</literal></entry> | |
1139 | <entry>vertical tab</entry> | |
1140 | </row> | |
1141 | <row> | |
1142 | <entry><literal>\\</literal></entry> | |
1143 | <entry>backslash</entry> | |
1144 | </row> | |
1145 | <row> | |
1146 | <entry><literal>\"</literal></entry> | |
1147 | <entry>double quotation mark</entry> | |
1148 | </row> | |
1149 | <row> | |
1150 | <entry><literal>\'</literal></entry> | |
1151 | <entry>single quotation mark</entry> | |
1152 | </row> | |
1153 | <row> | |
1154 | <entry><literal>\s</literal></entry> | |
1155 | <entry>space</entry> | |
1156 | </row> | |
1157 | <row> | |
1158 | <entry><literal>\x<replaceable>xx</replaceable></literal></entry> | |
1159 | <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> | |
1160 | </row> | |
1161 | <row> | |
1162 | <entry><literal>\<replaceable>nnn</replaceable></literal></entry> | |
1163 | <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> | |
1164 | </row> | |
1165 | </tbody> | |
1166 | </tgroup> | |
1167 | </table> | |
1168 | </refsect1> | |
1169 | ||
1170 | <refsect1> | |
1171 | <title>Examples</title> | |
1172 | ||
1173 | <example> | |
1174 | <title>Simple service</title> | |
1175 | ||
1176 | <para>The following unit file creates a service that will | |
1177 | execute <filename>/usr/sbin/foo-daemon</filename>. Since no | |
1178 | <varname>Type=</varname> is specified, the default | |
1179 | <varname>Type=</varname><option>simple</option> will be assumed. | |
1180 | systemd will assume the unit to be started immediately after the | |
1181 | program has begun executing.</para> | |
1182 | ||
1183 | <programlisting>[Unit] | |
d44efb62 CS |
1184 | Description=Foo |
1185 | ||
1186 | [Service] | |
1187 | ExecStart=/usr/sbin/foo-daemon | |
1188 | ||
1189 | [Install] | |
1190 | WantedBy=multi-user.target</programlisting> | |
1191 | ||
798d3a52 ZJS |
1192 | <para>Note that systemd assumes here that the process started by |
1193 | systemd will continue running until the service terminates. If | |
1194 | the program daemonizes itself (i.e. forks), please use | |
1195 | <varname>Type=</varname><option>forking</option> instead.</para> | |
1196 | ||
1197 | <para>Since no <varname>ExecStop=</varname> was specified, | |
1198 | systemd will send SIGTERM to all processes started from this | |
1199 | service, and after a timeout also SIGKILL. This behavior can be | |
1200 | modified, see | |
1201 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1202 | for details.</para> | |
1203 | ||
1204 | <para>Note that this unit type does not include any type of | |
1205 | notification when a service has completed initialization. For | |
1206 | this, you should use other unit types, such as | |
1207 | <varname>Type=</varname><option>notify</option> if the service | |
1208 | understands systemd's notification protocol, | |
1209 | <varname>Type=</varname><option>forking</option> if the service | |
1210 | can background itself or | |
1211 | <varname>Type=</varname><option>dbus</option> if the unit | |
1212 | acquires a DBus name once initialization is complete. See | |
1213 | below.</para> | |
1214 | </example> | |
1215 | ||
1216 | <example> | |
1217 | <title>Oneshot service</title> | |
1218 | ||
b938cb90 | 1219 | <para>Sometimes, units should just execute an action without |
798d3a52 ZJS |
1220 | keeping active processes, such as a filesystem check or a |
1221 | cleanup action on boot. For this, | |
1222 | <varname>Type=</varname><option>oneshot</option> exists. Units | |
1223 | of this type will wait until the process specified terminates | |
1224 | and then fall back to being inactive. The following unit will | |
ff9b60f3 | 1225 | perform a cleanup action:</para> |
798d3a52 ZJS |
1226 | |
1227 | <programlisting>[Unit] | |
d44efb62 CS |
1228 | Description=Cleanup old Foo data |
1229 | ||
1230 | [Service] | |
1231 | Type=oneshot | |
1232 | ExecStart=/usr/sbin/foo-cleanup | |
1233 | ||
1234 | [Install] | |
1235 | WantedBy=multi-user.target</programlisting> | |
1236 | ||
798d3a52 | 1237 | <para>Note that systemd will consider the unit to be in the |
b938cb90 | 1238 | state "starting" until the program has terminated, so ordered |
798d3a52 | 1239 | dependencies will wait for the program to finish before starting |
b938cb90 JE |
1240 | themselves. The unit will revert to the "inactive" state after |
1241 | the execution is done, never reaching the "active" state. That | |
798d3a52 ZJS |
1242 | means another request to start the unit will perform the action |
1243 | again.</para> | |
1244 | ||
1245 | <para><varname>Type=</varname><option>oneshot</option> are the | |
1246 | only service units that may have more than one | |
1247 | <varname>ExecStart=</varname> specified. They will be executed | |
1248 | in order until either they are all successful or one of them | |
1249 | fails.</para> | |
1250 | </example> | |
1251 | ||
1252 | <example> | |
1253 | <title>Stoppable oneshot service</title> | |
1254 | ||
1255 | <para>Similarly to the oneshot services, there are sometimes | |
1256 | units that need to execute a program to set up something and | |
1257 | then execute another to shut it down, but no process remains | |
b938cb90 | 1258 | active while they are considered "started". Network |
798d3a52 | 1259 | configuration can sometimes fall into this category. Another use |
a8eaaee7 | 1260 | case is if a oneshot service shall not be executed each time |
798d3a52 ZJS |
1261 | when they are pulled in as a dependency, but only the first |
1262 | time.</para> | |
1263 | ||
1264 | <para>For this, systemd knows the setting | |
1265 | <varname>RemainAfterExit=</varname><option>yes</option>, which | |
1266 | causes systemd to consider the unit to be active if the start | |
1267 | action exited successfully. This directive can be used with all | |
1268 | types, but is most useful with | |
1269 | <varname>Type=</varname><option>oneshot</option> and | |
1270 | <varname>Type=</varname><option>simple</option>. With | |
b938cb90 | 1271 | <varname>Type=</varname><option>oneshot</option>, systemd waits |
798d3a52 ZJS |
1272 | until the start action has completed before it considers the |
1273 | unit to be active, so dependencies start only after the start | |
1274 | action has succeeded. With | |
b938cb90 | 1275 | <varname>Type=</varname><option>simple</option>, dependencies |
798d3a52 ZJS |
1276 | will start immediately after the start action has been |
1277 | dispatched. The following unit provides an example for a simple | |
1278 | static firewall.</para> | |
1279 | ||
1280 | <programlisting>[Unit] | |
d44efb62 CS |
1281 | Description=Simple firewall |
1282 | ||
1283 | [Service] | |
1284 | Type=oneshot | |
1285 | RemainAfterExit=yes | |
1286 | ExecStart=/usr/local/sbin/simple-firewall-start | |
1287 | ExecStop=/usr/local/sbin/simple-firewall-stop | |
1288 | ||
1289 | [Install] | |
1290 | WantedBy=multi-user.target</programlisting> | |
1291 | ||
798d3a52 ZJS |
1292 | <para>Since the unit is considered to be running after the start |
1293 | action has exited, invoking <command>systemctl start</command> | |
1294 | on that unit again will cause no action to be taken.</para> | |
1295 | </example> | |
1296 | ||
1297 | <example> | |
1298 | <title>Traditional forking services</title> | |
1299 | ||
1300 | <para>Many traditional daemons/services background (i.e. fork, | |
1301 | daemonize) themselves when starting. Set | |
1302 | <varname>Type=</varname><option>forking</option> in the | |
1303 | service's unit file to support this mode of operation. systemd | |
1304 | will consider the service to be in the process of initialization | |
1305 | while the original program is still running. Once it exits | |
1306 | successfully and at least a process remains (and | |
1307 | <varname>RemainAfterExit=</varname><option>no</option>), the | |
1308 | service is considered started.</para> | |
1309 | ||
b938cb90 | 1310 | <para>Often, a traditional daemon only consists of one process. |
798d3a52 ZJS |
1311 | Therefore, if only one process is left after the original |
1312 | process terminates, systemd will consider that process the main | |
1313 | process of the service. In that case, the | |
1314 | <varname>$MAINPID</varname> variable will be available in | |
1315 | <varname>ExecReload=</varname>, <varname>ExecStop=</varname>, | |
1316 | etc.</para> | |
1317 | ||
1318 | <para>In case more than one process remains, systemd will be | |
1319 | unable to determine the main process, so it will not assume | |
1320 | there is one. In that case, <varname>$MAINPID</varname> will not | |
1321 | expand to anything. However, if the process decides to write a | |
1322 | traditional PID file, systemd will be able to read the main PID | |
1323 | from there. Please set <varname>PIDFile=</varname> accordingly. | |
1324 | Note that the daemon should write that file before finishing | |
b938cb90 | 1325 | with its initialization. Otherwise, systemd might try to read the |
798d3a52 ZJS |
1326 | file before it exists.</para> |
1327 | ||
1328 | <para>The following example shows a simple daemon that forks and | |
1329 | just starts one process in the background:</para> | |
1330 | ||
1331 | <programlisting>[Unit] | |
d44efb62 CS |
1332 | Description=Some simple daemon |
1333 | ||
1334 | [Service] | |
1335 | Type=forking | |
1336 | ExecStart=/usr/sbin/my-simple-daemon -d | |
1337 | ||
1338 | [Install] | |
1339 | WantedBy=multi-user.target</programlisting> | |
1340 | ||
798d3a52 ZJS |
1341 | <para>Please see |
1342 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1343 | for details on how you can influence the way systemd terminates | |
1344 | the service.</para> | |
1345 | </example> | |
1346 | ||
1347 | <example> | |
1348 | <title>DBus services</title> | |
1349 | ||
1350 | <para>For services that acquire a name on the DBus system bus, | |
1351 | use <varname>Type=</varname><option>dbus</option> and set | |
1352 | <varname>BusName=</varname> accordingly. The service should not | |
1353 | fork (daemonize). systemd will consider the service to be | |
1354 | initialized once the name has been acquired on the system bus. | |
1355 | The following example shows a typical DBus service:</para> | |
1356 | ||
1357 | <programlisting>[Unit] | |
d44efb62 CS |
1358 | Description=Simple DBus service |
1359 | ||
1360 | [Service] | |
1361 | Type=dbus | |
1362 | BusName=org.example.simple-dbus-service | |
1363 | ExecStart=/usr/sbin/simple-dbus-service | |
1364 | ||
1365 | [Install] | |
1366 | WantedBy=multi-user.target</programlisting> | |
1367 | ||
7ca41557 | 1368 | <para>For <emphasis>bus-activatable</emphasis> services, do not |
798d3a52 ZJS |
1369 | include a <literal>[Install]</literal> section in the systemd |
1370 | service file, but use the <varname>SystemdService=</varname> | |
1371 | option in the corresponding DBus service file, for example | |
1372 | (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> | |
d44efb62 | 1373 | |
798d3a52 | 1374 | <programlisting>[D-BUS Service] |
d44efb62 CS |
1375 | Name=org.example.simple-dbus-service |
1376 | Exec=/usr/sbin/simple-dbus-service | |
1377 | User=root | |
1378 | SystemdService=simple-dbus-service.service</programlisting> | |
1379 | ||
798d3a52 ZJS |
1380 | <para>Please see |
1381 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1382 | for details on how you can influence the way systemd terminates | |
1383 | the service.</para> | |
1384 | </example> | |
1385 | ||
1386 | <example> | |
1387 | <title>Services that notify systemd about their initialization</title> | |
1388 | ||
1389 | <para><varname>Type=</varname><option>simple</option> services | |
1390 | are really easy to write, but have the major disadvantage of | |
1391 | systemd not being able to tell when initialization of the given | |
1392 | service is complete. For this reason, systemd supports a simple | |
1393 | notification protocol that allows daemons to make systemd aware | |
1394 | that they are done initializing. Use | |
1395 | <varname>Type=</varname><option>notify</option> for this. A | |
1396 | typical service file for such a daemon would look like | |
1397 | this:</para> | |
1398 | ||
1399 | <programlisting>[Unit] | |
d44efb62 CS |
1400 | Description=Simple notifying service |
1401 | ||
1402 | [Service] | |
1403 | Type=notify | |
1404 | ExecStart=/usr/sbin/simple-notifying-service | |
1405 | ||
1406 | [Install] | |
1407 | WantedBy=multi-user.target</programlisting> | |
1408 | ||
798d3a52 | 1409 | <para>Note that the daemon has to support systemd's notification |
7ca41557 | 1410 | protocol, else systemd will think the service has not started yet |
798d3a52 ZJS |
1411 | and kill it after a timeout. For an example of how to update |
1412 | daemons to support this protocol transparently, take a look at | |
1413 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
1414 | systemd will consider the unit to be in the 'starting' state | |
1415 | until a readiness notification has arrived.</para> | |
1416 | ||
1417 | <para>Please see | |
1418 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
1419 | for details on how you can influence the way systemd terminates | |
1420 | the service.</para> | |
1421 | </example> | |
1422 | </refsect1> | |
1423 | ||
1424 | <refsect1> | |
1425 | <title>See Also</title> | |
1426 | <para> | |
1427 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
1428 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
1429 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1430 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1431 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1432 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
1433 | <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
1434 | </para> | |
1435 | </refsect1> | |
d1ab0ca0 LP |
1436 | |
1437 | </refentry> |