]>
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 | |
12 | under the terms of the GNU General Public License as published by | |
13 | the Free Software Foundation; either version 2 of the License, or | |
14 | (at your option) any later version. | |
15 | ||
16 | systemd is distributed in the hope that it will be useful, but | |
17 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
19 | General Public License for more details. | |
20 | ||
21 | You should have received a copy of the GNU General Public License | |
22 | along with systemd; If not, see <http://www.gnu.org/licenses/>. | |
23 | --> | |
24 | ||
25 | <refentry id="systemd.service"> | |
26 | <refentryinfo> | |
27 | <title>systemd.service</title> | |
28 | <productname>systemd</productname> | |
29 | ||
30 | <authorgroup> | |
31 | <author> | |
32 | <contrib>Developer</contrib> | |
33 | <firstname>Lennart</firstname> | |
34 | <surname>Poettering</surname> | |
35 | <email>lennart@poettering.net</email> | |
36 | </author> | |
37 | </authorgroup> | |
38 | </refentryinfo> | |
39 | ||
40 | <refmeta> | |
41 | <refentrytitle>systemd.service</refentrytitle> | |
42 | <manvolnum>5</manvolnum> | |
43 | </refmeta> | |
44 | ||
45 | <refnamediv> | |
46 | <refname>systemd.service</refname> | |
47 | <refpurpose>systemd service configuration files</refpurpose> | |
48 | </refnamediv> | |
49 | ||
50 | <refsynopsisdiv> | |
51 | <para><filename>systemd.service</filename></para> | |
52 | </refsynopsisdiv> | |
53 | ||
54 | <refsect1> | |
55 | <title>Description</title> | |
56 | ||
1f812fea | 57 | <para>A unit configuration file whose name ends in |
65232ea7 LP |
58 | <filename>.service</filename> encodes information |
59 | about a process controlled and supervised by | |
60 | systemd.</para> | |
d1ab0ca0 LP |
61 | |
62 | <para>This man page lists the configuration options | |
63 | specific to this unit type. See | |
64 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
65 | for the common options of all unit configuration | |
0d624a78 LP |
66 | files. The common configuration items are configured |
67 | in the generic [Unit] and [Install] sections. The | |
68 | service specific configuration options are configured | |
69 | in the [Service] section.</para> | |
70 | ||
71 | <para>Additional options are listed in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> | |
d1ab0ca0 LP |
72 | </refsect1> |
73 | ||
74 | <refsect1> | |
75 | <title>Options</title> | |
76 | ||
0d624a78 LP |
77 | <para>Service files must include a [Service] section, |
78 | which carries information about the service and the | |
79 | process it supervises. A number of options that may be | |
80 | used in this section are shared with other unit | |
81 | types. These options are documented in | |
82 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The | |
83 | options specific to the [Service] section of service | |
84 | units are the following:</para> | |
85 | ||
d1ab0ca0 LP |
86 | <variablelist> |
87 | <varlistentry> | |
88 | <term><varname>Type=</varname></term> | |
0d624a78 LP |
89 | |
90 | <listitem><para>Configures the process | |
91 | start-up type for this service | |
92 | unit. One of <option>simple</option>, | |
93 | <option>forking</option>, | |
94 | <option>finish</option>, | |
95 | <option>dbus</option>, | |
96 | <option>notify</option>.</para> | |
97 | ||
98 | <para>If set to | |
99 | <option>simple</option> (the default | |
100 | value) it is expected that the process | |
101 | configured with | |
102 | <varname>ExecStart=</varname> is the | |
103 | main process of the service. In this | |
104 | mode, communication channels must be | |
105 | installed before the daemon is started | |
106 | up (e.g. sockets set up by systemd, | |
107 | via socket activation), as systemd | |
108 | will immediately proceed starting | |
109 | follow-up units.</para> | |
110 | ||
111 | <para>If set to | |
112 | <option>forking</option> it is | |
113 | expected that the process configured | |
114 | with <varname>ExecStart=</varname> | |
115 | will start up and call | |
116 | <function>fork()</function>. The | |
117 | parent process is expected to finish | |
118 | when start-up is complete and all | |
119 | communication channels set up. The | |
120 | child continues to run as the main | |
121 | daemon process. This is the behaviour | |
122 | of traditional UNIX daemons. If this | |
123 | setting is used, it is recommended to | |
124 | also use the | |
125 | <varname>PIDFile=</varname> option, so | |
126 | that systemd can identify the main | |
127 | process of the daemon. systemd will | |
128 | proceed starting follow-up units as | |
129 | soon as the parent process | |
130 | exits.</para> | |
131 | ||
132 | <para>Behaviour of | |
133 | <option>finish</option> is similar | |
134 | to <option>simple</option>, however | |
135 | it is expected that the process has to | |
136 | exit before systemd starts follow-up | |
137 | units. <varname>ValidNoProcess=</varname> | |
138 | is particularly useful for this type | |
139 | of service.</para> | |
140 | ||
141 | <para>Behaviour of | |
142 | <option>dbus</option> is similar to | |
143 | <option>simple</option>, however it | |
144 | is expected that the daemon acquires a | |
145 | name on the D-Bus bus, as configured | |
146 | by | |
147 | <varname>BusName=</varname>. systemd | |
148 | will proceed starting follow-up units | |
149 | after the D-Bus bus name has been | |
150 | acquired.</para> | |
151 | ||
152 | <para>Behaviour of | |
153 | <option>notify</option> is similar to | |
154 | <option>simple</option>, however it is | |
155 | expected that the daemon sends a | |
156 | notification message via | |
157 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
158 | or an equivalent call when it finished | |
159 | starting up. systemd will proceed | |
160 | starting follow-up units after this | |
161 | notification message has been sent. If | |
162 | this option is used | |
163 | <option>NotifyAccess=</option> (see | |
164 | below) must be set to open access to | |
165 | the notification socket provided by | |
166 | systemd.</para> | |
d1ab0ca0 LP |
167 | </listitem> |
168 | </varlistentry> | |
0d624a78 | 169 | |
d1ab0ca0 LP |
170 | <varlistentry> |
171 | <term><varname>ValidNoProcess=</varname></term> | |
0d624a78 LP |
172 | |
173 | <listitem><para>Takes a boolean value | |
174 | that specifies whether the service | |
175 | shall be considered active even when | |
176 | all its processes exited. Defaults to | |
177 | <option>no</option>.</para> | |
d1ab0ca0 LP |
178 | </listitem> |
179 | </varlistentry> | |
180 | ||
181 | <varlistentry> | |
182 | <term><varname>PIDFile=</varname></term> | |
0d624a78 LP |
183 | |
184 | <listitem><para>Takes an absolute file | |
185 | name pointing to the PID file of this | |
186 | daemon. Use of this option is | |
187 | recommended for services where | |
188 | <varname>Type=</varname> is set to | |
189 | <option>forking</option>.</para> | |
d1ab0ca0 LP |
190 | </listitem> |
191 | </varlistentry> | |
192 | ||
193 | <varlistentry> | |
194 | <term><varname>BusName=</varname></term> | |
0d624a78 LP |
195 | |
196 | <listitem><para>Takes a D-Bus bus | |
197 | name, where this service is reachable | |
198 | as. This option is mandatory for | |
199 | services where | |
200 | <varname>Type=</varname> is set to | |
201 | <option>dbus</option>, but its use | |
202 | is otherwise recommended as well if | |
203 | the process takes a name on the D-Bus | |
204 | bus.</para> | |
d1ab0ca0 LP |
205 | </listitem> |
206 | </varlistentry> | |
207 | ||
208 | <varlistentry> | |
209 | <term><varname>ExecStart=</varname></term> | |
0d624a78 LP |
210 | <listitem><para>Takes a command line |
211 | that is executed when this service | |
212 | shall be started up. The first token | |
213 | of the command line must be an | |
214 | absolute file name, then followed by | |
215 | arguments for the process. It is | |
216 | mandatory to set this option for all | |
217 | services. This option may not be | |
218 | specified more than once. Optionally, | |
219 | if the absolute file name is prefixed | |
220 | with @, the second token will be | |
221 | passed as argv[0] to the executed | |
222 | process, followed by the further | |
223 | arguments specified. Unless | |
224 | <option>Type=forking</option> is set, | |
225 | the process started via this command | |
226 | line will be considered the main | |
227 | process of the | |
228 | daemon.</para></listitem> | |
229 | </varlistentry> | |
230 | ||
231 | <varlistentry> | |
232 | <term><varname>ExecStartPre=</varname></term> | |
233 | <term><varname>ExecStartPost=</varname></term> | |
234 | <listitem><para>Additional commands | |
235 | that are executed before (resp. after) | |
236 | the command in | |
237 | <varname>ExecStart=</varname>. If | |
238 | specified more than once, all commands | |
239 | are executed one after the other, | |
240 | serially. Use of these settings is | |
241 | optional.</para></listitem> | |
242 | </varlistentry> | |
243 | ||
244 | <varlistentry> | |
245 | <term><varname>ExecReload=</varname></term> | |
246 | <listitem><para>Commands to execute to | |
247 | trigger a configuration reload in the | |
248 | service. If used more than once, all | |
249 | commands are executed one after the | |
250 | other, serially. Use of this setting is optional. | |
251 | </para></listitem> | |
252 | </varlistentry> | |
253 | ||
254 | <varlistentry> | |
255 | <term><varname>ExecStop=</varname></term> | |
256 | <listitem><para>Commands to execute to | |
257 | stop the service started via | |
258 | <varname>ExecStart=</varname>. If used | |
259 | more than once, all commands are | |
260 | executed one after the other, | |
261 | serially. Use of this setting is | |
262 | optional. All processes remaining for | |
263 | a service after the commands | |
264 | configured in this option are run are | |
265 | terminated according to the | |
266 | <varname>KillMode=</varname> setting | |
267 | (see below). If this option is not | |
268 | specified the process is terminated | |
269 | right-away when service stop is | |
270 | requested.</para></listitem> | |
271 | </varlistentry> | |
272 | ||
273 | <varlistentry> | |
274 | <term><varname>ExecStopPost=</varname></term> | |
275 | <listitem><para>Additional commands | |
276 | that are executed after the service | |
277 | was stopped using the commands | |
278 | configured in | |
279 | <varname>ExecStop=</varname>. If | |
280 | specified more than once, all commands | |
281 | are executed one after the other, | |
282 | serially. Use of these settings is | |
283 | optional.</para></listitem> | |
284 | </varlistentry> | |
285 | ||
286 | <varlistentry> | |
287 | <term><varname>RestartSec=</varname></term> | |
288 | <listitem><para>Configures the time to | |
289 | sleep before restarting a service (as | |
290 | configured with | |
291 | <varname>Restart=</varname>). Takes a | |
292 | unit-less value in seconds, or a time | |
293 | span value such as "5min | |
294 | 20s". Defaults to | |
295 | 100ms.</para></listitem> | |
296 | </varlistentry> | |
297 | ||
298 | <varlistentry> | |
299 | <term><varname>TimeoutSec=</varname></term> | |
300 | <listitem><para>Configures the time to | |
301 | wait for start-up and stop. If a | |
302 | daemon service does not signal | |
303 | start-up completion within the | |
304 | configured time the service will be | |
305 | considered failed and be shut down | |
306 | again. If a service is asked to stop | |
307 | but does not terminate in the | |
308 | specified time it will be terminated | |
309 | forcibly via SIGTERM, and after | |
310 | another delay of this time with | |
311 | SIGKILL. (See | |
1f812fea | 312 | <option>KillMode=</option> |
0d624a78 LP |
313 | below.) Takes a unit-less value in seconds, or a |
314 | time span value such as "5min | |
315 | 20s". Pass 0 to disable the timeout | |
316 | logic. Defaults to | |
317 | 60s.</para></listitem> | |
318 | </varlistentry> | |
319 | ||
320 | <varlistentry> | |
321 | <term><varname>Restart=</varname></term> | |
322 | <listitem><para>Configures whether the | |
323 | main service process shall be restarted when | |
324 | it exists. Takes one of | |
325 | <option>once</option>, | |
326 | <option>restart-on-success</option> or | |
327 | <option>restart-always</option>. If | |
328 | set to <option>once</option> (the | |
329 | default) the service will not be | |
330 | restarted when it exits. If set to | |
331 | <option>restart-on-success</option> it | |
332 | will be restarted only when it exited | |
333 | cleanly, i.e. terminated with an exit | |
334 | code of 0. If set to | |
335 | <option>restart-always</option> the | |
336 | service will be restarted regardless | |
337 | whether it exited cleanly or not, or | |
338 | got terminated abnormally by a | |
339 | signal.</para></listitem> | |
340 | </varlistentry> | |
341 | ||
342 | <varlistentry> | |
343 | <term><varname>PermissionsStartOnly=</varname></term> | |
344 | <listitem><para>Takes a boolean | |
345 | argument. If true, the permission | |
346 | related execution options as | |
347 | configured with | |
348 | <varname>User=</varname> and similar | |
349 | options (see | |
350 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
351 | for more information) are only applied | |
352 | to the process started with | |
353 | <varname>ExecStart=</varname>, and not | |
354 | to the various other | |
355 | <varname>ExecStartPre=</varname>, | |
356 | <varname>ExecStartPost=</varname>, | |
357 | <varname>ExecReload=</varname>, | |
358 | <varname>ExecStop=</varname>, | |
359 | <varname>ExecStopPost=</varname> | |
360 | commands. If false, the setting is | |
361 | applied to all configured commands the | |
362 | same way. Defaults to | |
363 | false.</para></listitem> | |
364 | </varlistentry> | |
365 | ||
366 | <varlistentry> | |
367 | <term><varname>RootDirectoryStartOnly=</varname></term> | |
368 | <listitem><para>Takes a boolean | |
369 | argument. If true, the root directory | |
370 | as configured with the | |
371 | <varname>RootDirectory=</varname> | |
372 | option (see | |
373 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
374 | for more information) is only applied | |
375 | to the process started with | |
376 | <varname>ExecStart=</varname>, and not | |
377 | to the various other | |
378 | <varname>ExecStartPre=</varname>, | |
379 | <varname>ExecStartPost=</varname>, | |
380 | <varname>ExecReload=</varname>, | |
381 | <varname>ExecStop=</varname>, | |
382 | <varname>ExecStopPost=</varname> | |
383 | commands. If false, the setting is | |
384 | applied to all configured commands the | |
385 | same way. Defaults to | |
386 | false.</para></listitem> | |
387 | </varlistentry> | |
388 | ||
389 | <varlistentry> | |
390 | <term><varname>SysVStartPriority=</varname></term> | |
391 | <listitem><para>Set the SysV start | |
392 | priority to use to order this service | |
393 | in relation to SysV services lacking | |
394 | LSB headers. This option is only | |
395 | necessary to fix ordering in relation | |
396 | to legacy SysV services, that have no | |
397 | ordering information encoded in the | |
398 | script headers. As such it should only | |
399 | be used as temporary compatibility | |
400 | option, and not be used in new unit | |
401 | files. Almost always it is a better | |
402 | choice to add explicit ordering | |
403 | directives via | |
404 | <varname>After=</varname> or | |
405 | <varname>Before=</varname>, | |
406 | instead. For more details see | |
407 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If | |
408 | used, pass an integer value in the | |
409 | range 0-99.</para></listitem> | |
410 | </varlistentry> | |
411 | ||
412 | <varlistentry> | |
413 | <term><varname>KillMode=</varname></term> | |
414 | <listitem><para>Specifies how | |
415 | processes of this service shall be | |
416 | killed. One of | |
417 | <option>control-group</option>, | |
418 | <option>process-group</option>, | |
419 | <option>process</option>, | |
420 | <option>none</option>.</para> | |
421 | ||
422 | <para>If set to | |
423 | <option>control-group</option> all | |
424 | remaining processes in the control | |
425 | group of this service will be | |
426 | terminated on service stop, after the | |
427 | stop command (as configured with | |
428 | <varname>ExecStop=</varname>) is | |
429 | executed. If set to | |
430 | <option>process-group</option> only | |
431 | the members of the process group of | |
432 | the main service process are | |
433 | killed. If set to | |
434 | <option>process</option> only the main | |
435 | process itself is killed. If set to | |
436 | <option>none</option> no process is | |
437 | killed. In this case only the stop | |
438 | command will be executed on service | |
439 | stop, but no process be killed | |
440 | otherwise. Processes remaining alive | |
441 | after stop are left in their control | |
442 | group and the control group continues | |
443 | to exist after stop unless it is | |
444 | empty. Defaults to | |
445 | <option>control-croup</option>.</para> | |
446 | ||
447 | <para>Processes will first be | |
448 | terminated via SIGTERM. If then after | |
449 | a delay (configured via the | |
450 | <option>TimeoutSec=</option> option) | |
451 | processes still remain, the | |
452 | termination request is repeated with | |
453 | the SIGKILL signal. See | |
454 | <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
455 | for more | |
456 | information.</para></listitem> | |
457 | </varlistentry> | |
458 | ||
459 | <varlistentry> | |
460 | <term><varname>NonBlocking=</varname></term> | |
461 | <listitem><para>Set O_NONBLOCK flag | |
462 | for all file descriptors passed via | |
463 | socket-based activation. If true, all | |
464 | file descriptors >= 3 (i.e. all except | |
465 | STDIN/STDOUT/STDERR) will have | |
466 | the O_NONBLOCK flag set and hence are in | |
467 | non-blocking mode. This option is only | |
468 | useful in conjunction with a socket | |
469 | unit, as described in | |
470 | <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults | |
471 | to false.</para></listitem> | |
472 | </varlistentry> | |
473 | ||
474 | <varlistentry> | |
475 | <term><varname>NotifyAccess=</varname></term> | |
476 | <listitem><para>Controls access to the | |
477 | service status notification socket, as | |
478 | accessible via the | |
479 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
480 | call. Takes one of | |
481 | <option>none</option> (the default), | |
482 | <option>main</option> or | |
483 | <option>all</option>. If | |
484 | <option>none</option> no daemon status | |
485 | updates are accepted by the service | |
486 | processes, all status update messages | |
487 | are ignored. If <option>main</option> | |
488 | only service updates sent from the | |
489 | main process of the service are | |
490 | accepted. If <option>all</option> all | |
491 | services updates from all members of | |
492 | the service's control group are | |
493 | accepted. This option must be set to | |
494 | open access to the notification socket | |
495 | when using | |
496 | <varname>Type=notify</varname> (see above).</para></listitem> | |
d1ab0ca0 LP |
497 | </varlistentry> |
498 | ||
499 | </variablelist> | |
500 | </refsect1> | |
501 | ||
502 | <refsect1> | |
503 | <title>See Also</title> | |
504 | <para> | |
505 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
0d624a78 LP |
506 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
507 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, | |
508 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
d1ab0ca0 LP |
509 | </para> |
510 | </refsect1> | |
511 | ||
512 | </refentry> |