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">
7 This file is part of systemd.
9 Copyright 2010 Lennart Poettering
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.
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.
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/>.
25 <refentry id=
"systemd.service">
27 <title>systemd.service
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>systemd.service
</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.service
</refname>
47 <refpurpose>systemd service configuration files
</refpurpose>
51 <para><filename>systemd.service
</filename></para>
55 <title>Description
</title>
57 <para>A configuration file ending in .service encodes
58 information about a process controlled and supervised
61 <para>This man page lists the configuration options
62 specific to this unit type. See
63 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
64 for the common options of all unit configuration
65 files. The common configuration items are configured
66 in the generic [Unit] and [Install] sections. The
67 service specific configuration options are configured
68 in the [Service] section.
</para>
70 <para>Additional options are listed in
<citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
74 <title>Options
</title>
76 <para>Service files must include a [Service] section,
77 which carries information about the service and the
78 process it supervises. A number of options that may be
79 used in this section are shared with other unit
80 types. These options are documented in
81 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
82 options specific to the [Service] section of service
83 units are the following:
</para>
87 <term><varname>Type=
</varname></term>
89 <listitem><para>Configures the process
90 start-up type for this service
91 unit. One of
<option>simple
</option>,
92 <option>forking
</option>,
93 <option>finish
</option>,
94 <option>dbus
</option>,
95 <option>notify
</option>.
</para>
98 <option>simple
</option> (the default
99 value) it is expected that the process
101 <varname>ExecStart=
</varname> is the
102 main process of the service. In this
103 mode, communication channels must be
104 installed before the daemon is started
105 up (e.g. sockets set up by systemd,
106 via socket activation), as systemd
107 will immediately proceed starting
108 follow-up units.
</para>
111 <option>forking
</option> it is
112 expected that the process configured
113 with
<varname>ExecStart=
</varname>
114 will start up and call
115 <function>fork()
</function>. The
116 parent process is expected to finish
117 when start-up is complete and all
118 communication channels set up. The
119 child continues to run as the main
120 daemon process. This is the behaviour
121 of traditional UNIX daemons. If this
122 setting is used, it is recommended to
124 <varname>PIDFile=
</varname> option, so
125 that systemd can identify the main
126 process of the daemon. systemd will
127 proceed starting follow-up units as
128 soon as the parent process
132 <option>finish
</option> is similar
133 to
<option>simple
</option>, however
134 it is expected that the process has to
135 exit before systemd starts follow-up
136 units.
<varname>ValidNoProcess=
</varname>
137 is particularly useful for this type
141 <option>dbus
</option> is similar to
142 <option>simple
</option>, however it
143 is expected that the daemon acquires a
144 name on the D-Bus bus, as configured
146 <varname>BusName=
</varname>. systemd
147 will proceed starting follow-up units
148 after the D-Bus bus name has been
152 <option>notify
</option> is similar to
153 <option>simple
</option>, however it is
154 expected that the daemon sends a
155 notification message via
156 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
157 or an equivalent call when it finished
158 starting up. systemd will proceed
159 starting follow-up units after this
160 notification message has been sent. If
162 <option>NotifyAccess=
</option> (see
163 below) must be set to open access to
164 the notification socket provided by
170 <term><varname>ValidNoProcess=
</varname></term>
172 <listitem><para>Takes a boolean value
173 that specifies whether the service
174 shall be considered active even when
175 all its processes exited. Defaults to
176 <option>no
</option>.
</para>
181 <term><varname>PIDFile=
</varname></term>
183 <listitem><para>Takes an absolute file
184 name pointing to the PID file of this
185 daemon. Use of this option is
186 recommended for services where
187 <varname>Type=
</varname> is set to
188 <option>forking
</option>.
</para>
193 <term><varname>BusName=
</varname></term>
195 <listitem><para>Takes a D-Bus bus
196 name, where this service is reachable
197 as. This option is mandatory for
199 <varname>Type=
</varname> is set to
200 <option>dbus
</option>, but its use
201 is otherwise recommended as well if
202 the process takes a name on the D-Bus
208 <term><varname>ExecStart=
</varname></term>
209 <listitem><para>Takes a command line
210 that is executed when this service
211 shall be started up. The first token
212 of the command line must be an
213 absolute file name, then followed by
214 arguments for the process. It is
215 mandatory to set this option for all
216 services. This option may not be
217 specified more than once. Optionally,
218 if the absolute file name is prefixed
219 with @, the second token will be
220 passed as argv[
0] to the executed
221 process, followed by the further
222 arguments specified. Unless
223 <option>Type=forking
</option> is set,
224 the process started via this command
225 line will be considered the main
227 daemon.
</para></listitem>
231 <term><varname>ExecStartPre=
</varname></term>
232 <term><varname>ExecStartPost=
</varname></term>
233 <listitem><para>Additional commands
234 that are executed before (resp. after)
236 <varname>ExecStart=
</varname>. If
237 specified more than once, all commands
238 are executed one after the other,
239 serially. Use of these settings is
240 optional.
</para></listitem>
244 <term><varname>ExecReload=
</varname></term>
245 <listitem><para>Commands to execute to
246 trigger a configuration reload in the
247 service. If used more than once, all
248 commands are executed one after the
249 other, serially. Use of this setting is optional.
254 <term><varname>ExecStop=
</varname></term>
255 <listitem><para>Commands to execute to
256 stop the service started via
257 <varname>ExecStart=
</varname>. If used
258 more than once, all commands are
259 executed one after the other,
260 serially. Use of this setting is
261 optional. All processes remaining for
262 a service after the commands
263 configured in this option are run are
264 terminated according to the
265 <varname>KillMode=
</varname> setting
266 (see below). If this option is not
267 specified the process is terminated
268 right-away when service stop is
269 requested.
</para></listitem>
273 <term><varname>ExecStopPost=
</varname></term>
274 <listitem><para>Additional commands
275 that are executed after the service
276 was stopped using the commands
278 <varname>ExecStop=
</varname>. If
279 specified more than once, all commands
280 are executed one after the other,
281 serially. Use of these settings is
282 optional.
</para></listitem>
286 <term><varname>RestartSec=
</varname></term>
287 <listitem><para>Configures the time to
288 sleep before restarting a service (as
290 <varname>Restart=
</varname>). Takes a
291 unit-less value in seconds, or a time
292 span value such as
"5min
294 100ms.
</para></listitem>
298 <term><varname>TimeoutSec=
</varname></term>
299 <listitem><para>Configures the time to
300 wait for start-up and stop. If a
301 daemon service does not signal
302 start-up completion within the
303 configured time the service will be
304 considered failed and be shut down
305 again. If a service is asked to stop
306 but does not terminate in the
307 specified time it will be terminated
308 forcibly via SIGTERM, and after
309 another delay of this time with
311 <option>KilleMode=
</option>
312 below.) Takes a unit-less value in seconds, or a
313 time span value such as
"5min
314 20s". Pass
0 to disable the timeout
316 60s.
</para></listitem>
320 <term><varname>Restart=
</varname></term>
321 <listitem><para>Configures whether the
322 main service process shall be restarted when
323 it exists. Takes one of
324 <option>once
</option>,
325 <option>restart-on-success
</option> or
326 <option>restart-always
</option>. If
327 set to
<option>once
</option> (the
328 default) the service will not be
329 restarted when it exits. If set to
330 <option>restart-on-success
</option> it
331 will be restarted only when it exited
332 cleanly, i.e. terminated with an exit
334 <option>restart-always
</option> the
335 service will be restarted regardless
336 whether it exited cleanly or not, or
337 got terminated abnormally by a
338 signal.
</para></listitem>
342 <term><varname>PermissionsStartOnly=
</varname></term>
343 <listitem><para>Takes a boolean
344 argument. If true, the permission
345 related execution options as
347 <varname>User=
</varname> and similar
349 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
350 for more information) are only applied
351 to the process started with
352 <varname>ExecStart=
</varname>, and not
354 <varname>ExecStartPre=
</varname>,
355 <varname>ExecStartPost=
</varname>,
356 <varname>ExecReload=
</varname>,
357 <varname>ExecStop=
</varname>,
358 <varname>ExecStopPost=
</varname>
359 commands. If false, the setting is
360 applied to all configured commands the
361 same way. Defaults to
362 false.
</para></listitem>
366 <term><varname>RootDirectoryStartOnly=
</varname></term>
367 <listitem><para>Takes a boolean
368 argument. If true, the root directory
369 as configured with the
370 <varname>RootDirectory=
</varname>
372 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
373 for more information) is only applied
374 to the process started with
375 <varname>ExecStart=
</varname>, and not
377 <varname>ExecStartPre=
</varname>,
378 <varname>ExecStartPost=
</varname>,
379 <varname>ExecReload=
</varname>,
380 <varname>ExecStop=
</varname>,
381 <varname>ExecStopPost=
</varname>
382 commands. If false, the setting is
383 applied to all configured commands the
384 same way. Defaults to
385 false.
</para></listitem>
389 <term><varname>SysVStartPriority=
</varname></term>
390 <listitem><para>Set the SysV start
391 priority to use to order this service
392 in relation to SysV services lacking
393 LSB headers. This option is only
394 necessary to fix ordering in relation
395 to legacy SysV services, that have no
396 ordering information encoded in the
397 script headers. As such it should only
398 be used as temporary compatibility
399 option, and not be used in new unit
400 files. Almost always it is a better
401 choice to add explicit ordering
403 <varname>After=
</varname> or
404 <varname>Before=
</varname>,
405 instead. For more details see
406 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
407 used, pass an integer value in the
408 range
0-
99.
</para></listitem>
412 <term><varname>KillMode=
</varname></term>
413 <listitem><para>Specifies how
414 processes of this service shall be
416 <option>control-group
</option>,
417 <option>process-group
</option>,
418 <option>process
</option>,
419 <option>none
</option>.
</para>
422 <option>control-group
</option> all
423 remaining processes in the control
424 group of this service will be
425 terminated on service stop, after the
426 stop command (as configured with
427 <varname>ExecStop=
</varname>) is
429 <option>process-group
</option> only
430 the members of the process group of
431 the main service process are
433 <option>process
</option> only the main
434 process itself is killed. If set to
435 <option>none
</option> no process is
436 killed. In this case only the stop
437 command will be executed on service
438 stop, but no process be killed
439 otherwise. Processes remaining alive
440 after stop are left in their control
441 group and the control group continues
442 to exist after stop unless it is
444 <option>control-croup
</option>.
</para>
446 <para>Processes will first be
447 terminated via SIGTERM. If then after
448 a delay (configured via the
449 <option>TimeoutSec=
</option> option)
450 processes still remain, the
451 termination request is repeated with
452 the SIGKILL signal. See
453 <citerefentry><refentrytitle>kill
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
455 information.
</para></listitem>
459 <term><varname>NonBlocking=
</varname></term>
460 <listitem><para>Set O_NONBLOCK flag
461 for all file descriptors passed via
462 socket-based activation. If true, all
463 file descriptors
>=
3 (i.e. all except
464 STDIN/STDOUT/STDERR) will have
465 the O_NONBLOCK flag set and hence are in
466 non-blocking mode. This option is only
467 useful in conjunction with a socket
468 unit, as described in
469 <citerefentry><refentrytitle>systemd.socket
</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
470 to false.
</para></listitem>
474 <term><varname>NotifyAccess=
</varname></term>
475 <listitem><para>Controls access to the
476 service status notification socket, as
478 <citerefentry><refentrytitle>sd_notify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
480 <option>none
</option> (the default),
481 <option>main
</option> or
482 <option>all
</option>. If
483 <option>none
</option> no daemon status
484 updates are accepted by the service
485 processes, all status update messages
486 are ignored. If
<option>main
</option>
487 only service updates sent from the
488 main process of the service are
489 accepted. If
<option>all
</option> all
490 services updates from all members of
491 the service's control group are
492 accepted. This option must be set to
493 open access to the notification socket
495 <varname>Type=notify
</varname> (see above).
</para></listitem>
502 <title>See Also
</title>
504 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
505 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
506 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
507 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>