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 unit configuration file whose name ends in
58 <filename>.service</filename> encodes information
59 about a process controlled and supervised by
62 <para>This man page lists the configuration options
63 specific to this unit type. See
64 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
65 for the common options of all unit configuration
66 files. The common configuration items are configured
67 in the generic <literal>[Unit]</literal> and
68 <literal>[Install]</literal> sections. The service
69 specific configuration options are configured in the
70 <literal>[Service]</literal> section.</para>
72 <para>Additional options are listed in
73 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
74 which define the execution environment the commands
75 are executed in.</para>
77 <para>Unless <varname>DefaultDependencies=</varname>
78 is set to <option>false</option>, service units will
79 implicitly have dependencies of type
80 <varname>Requires=</varname> and
81 <varname>After=</varname> on
82 <filename>basic.target</filename> as well as
83 dependencies of type <varname>Conflicts=</varname> and
84 <varname>Before=</varname> on
85 <filename>shutdown.target</filename>. These ensure
86 that normal service units pull in basic system
87 initialization, and are terminated cleanly prior to
88 system shutdown. Only services involved with early
89 boot or late system shutdown should disable this
92 <para>If a service is requested under a certain name
93 but no unit configuration file is found, systemd looks
94 for a SysV init script by the same name (with the
95 <filename>.service</filename> suffix removed) and
96 dynamically creates a service unit from that
97 script. This is useful for compatibility with
102 <title>Options</title>
104 <para>Service files must include a
105 <literal>[Service]</literal> section, which carries
106 information about the service and the process it
107 supervises. A number of options that may be used in
108 this section are shared with other unit types. These
109 options are documented in
110 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
111 options specific to the <literal>[Service]</literal>
112 section of service units are the following:</para>
116 <term><varname>Type=</varname></term>
118 <listitem><para>Configures the process
119 start-up type for this service
120 unit. One of <option>simple</option>,
121 <option>forking</option>,
122 <option>finish</option>,
123 <option>dbus</option>,
124 <option>notify</option>.</para>
127 <option>simple</option> (the default
128 value) it is expected that the process
130 <varname>ExecStart=</varname> is the
131 main process of the service. In this
132 mode, communication channels must be
133 installed before the daemon is started
134 up (e.g. sockets set up by systemd,
135 via socket activation), as systemd
136 will immediately proceed starting
137 follow-up units.</para>
140 <option>forking</option> it is
141 expected that the process configured
142 with <varname>ExecStart=</varname>
143 will start up and call
144 <function>fork()</function>. The
145 parent process is expected to finish
146 when start-up is complete and all
147 communication channels set up. The
148 child continues to run as the main
149 daemon process. This is the behaviour
150 of traditional UNIX daemons. If this
151 setting is used, it is recommended to
153 <varname>PIDFile=</varname> option, so
154 that systemd can identify the main
155 process of the daemon. systemd will
156 proceed starting follow-up units as
157 soon as the parent process
161 <option>finish</option> is similar
162 to <option>simple</option>, however
163 it is expected that the process has to
164 exit before systemd starts follow-up
165 units. <varname>ValidNoProcess=</varname>
166 is particularly useful for this type
170 <option>dbus</option> is similar to
171 <option>simple</option>, however it is
172 expected that the daemon acquires a
173 name on the D-Bus bus, as configured
175 <varname>BusName=</varname>. systemd
176 will proceed starting follow-up units
177 after the D-Bus bus name has been
178 acquired. Service units with this
179 option configured implicitly have
181 <filename>dbus.target</filename>
185 <option>notify</option> is similar to
186 <option>simple</option>, however it is
187 expected that the daemon sends a
188 notification message via
189 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
190 or an equivalent call when it finished
191 starting up. systemd will proceed
192 starting follow-up units after this
193 notification message has been sent. If
195 <varname>NotifyAccess=</varname> (see
196 below) must be set to open access to
197 the notification socket provided by
199 <varname>NotifyAccess=</varname> is not
200 set, it will be implicitly set to
201 <option>main</option>.</para>
206 <term><varname>ValidNoProcess=</varname></term>
208 <listitem><para>Takes a boolean value
209 that specifies whether the service
210 shall be considered active even when
211 all its processes exited. Defaults to
212 <option>no</option>.</para>
217 <term><varname>PIDFile=</varname></term>
219 <listitem><para>Takes an absolute file
220 name pointing to the PID file of this
221 daemon. Use of this option is
222 recommended for services where
223 <varname>Type=</varname> is set to
224 <option>forking</option>.</para>
229 <term><varname>BusName=</varname></term>
231 <listitem><para>Takes a D-Bus bus
232 name, where this service is reachable
233 as. This option is mandatory for
235 <varname>Type=</varname> is set to
236 <option>dbus</option>, but its use
237 is otherwise recommended as well if
238 the process takes a name on the D-Bus
244 <term><varname>ExecStart=</varname></term>
245 <listitem><para>Takes a command line
246 that is executed when this service
247 shall be started up. The first token
248 of the command line must be an
249 absolute file name, then followed by
250 arguments for the process. It is
251 mandatory to set this option for all
252 services. This option may not be
253 specified more than once. Optionally,
254 if the absolute file name is prefixed
255 with <literal>@</literal>, the second
256 token will be passed as
257 <literal>argv[0]</literal> to the
258 executed process, followed by the
259 further arguments specified. If the
260 first token is prefixed with
261 <literal>-</literal> an error code of
262 the command normally considered a
263 failure is ignored and considered
264 success. If both <literal>-</literal>
265 and <literal>@</literal> are used for
266 the same command the latter must
267 preceed the latter. Unless
268 <varname>Type=forking</varname> is
269 set, the process started via this
270 command line will be considered the
271 main process of the daemon. The
272 command line accepts % specifiers as
274 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. On
275 top of that basic environment variable
276 substitution is supported, where
277 <literal>${FOO}</literal> is replaced
278 by the string value of the environment
279 variable of the same name. Also
280 <literal>$FOO</literal> may appear as
281 seperate word on the command line in
282 which case the variable is replaced by
284 whitespaces.</para></listitem>
288 <term><varname>ExecStartPre=</varname></term>
289 <term><varname>ExecStartPost=</varname></term>
290 <listitem><para>Additional commands
291 that are executed before (resp. after)
293 <varname>ExecStart=</varname>. Multiple
294 command lines may be concatenated in a
295 single directive, by seperating them
296 by semicolons (these semicolons must
297 be passed as seperate words). In that
298 case, the commands are executed one
300 serially. Alternatively, these
301 directives may be specified more than
302 once whith the same effect. However,
303 the latter syntax is not recommended
304 for compatibility with parsers
306 <filename>.desktop</filename> files.
307 Use of these settings is
308 optional. Specifier and environment
309 variable substitution is
310 supported.</para></listitem>
314 <term><varname>ExecReload=</varname></term>
315 <listitem><para>Commands to execute to
316 trigger a configuration reload in the
317 service. This argument takes multiple
318 command lines, following the same
319 scheme as pointed out for
320 <varname>ExecStartPre=</varname>
321 above. Use of this setting is
322 optional. Specifier and environment
323 variable substitution is supported
324 here following the same scheme as for
325 <varname>ExecStart=</varname>. One
326 special environment variable is set:
327 if known <literal>$MAINPID</literal> is
328 set to the main process of the
329 daemon, and may be used for command
330 lines like the following:
331 <command>/bin/kill -HUP
332 $(MAINPID)</command>.</para></listitem>
336 <term><varname>ExecStop=</varname></term>
337 <listitem><para>Commands to execute to
338 stop the service started via
339 <varname>ExecStart=</varname>. This
340 argument takes multiple command lines,
341 following the same scheme as pointed
343 <varname>ExecStartPre=</varname>
344 above. Use of this setting is
345 optional. All processes remaining for
346 a service after the commands
347 configured in this option are run are
348 terminated according to the
349 <varname>KillMode=</varname> setting
350 (see below). If this option is not
351 specified the process is terminated
352 right-away when service stop is
353 requested. Specifier and environment
354 variable substitution is supported
356 <literal>$(MAINPID)</literal>, see
357 above).</para></listitem>
361 <term><varname>ExecStopPost=</varname></term>
362 <listitem><para>Additional commands
363 that are executed after the service
364 was stopped using the commands
366 <varname>ExecStop=</varname>. This
367 argument takes multiple command lines,
368 following the same scheme as pointed
370 <varname>ExecStartPre</varname>. Use
372 optional. Specifier and environment
373 variable substitution is
374 supported.</para></listitem>
378 <term><varname>RestartSec=</varname></term>
379 <listitem><para>Configures the time to
380 sleep before restarting a service (as
382 <varname>Restart=</varname>). Takes a
383 unit-less value in seconds, or a time
384 span value such as "5min
386 100ms.</para></listitem>
390 <term><varname>TimeoutSec=</varname></term>
391 <listitem><para>Configures the time to
392 wait for start-up and stop. If a
393 daemon service does not signal
394 start-up completion within the
395 configured time the service will be
396 considered failed and be shut down
397 again. If a service is asked to stop
398 but does not terminate in the
399 specified time it will be terminated
400 forcibly via SIGTERM, and after
401 another delay of this time with
403 <varname>KillMode=</varname>
404 below.) Takes a unit-less value in seconds, or a
405 time span value such as "5min
406 20s". Pass 0 to disable the timeout
408 60s.</para></listitem>
412 <term><varname>Restart=</varname></term>
413 <listitem><para>Configures whether the
414 main service process shall be restarted when
415 it exists. Takes one of
416 <option>once</option>,
417 <option>restart-on-success</option> or
418 <option>restart-always</option>. If
419 set to <option>once</option> (the
420 default) the service will not be
421 restarted when it exits. If set to
422 <option>restart-on-success</option> it
423 will be restarted only when it exited
424 cleanly, i.e. terminated with an exit
426 <option>restart-always</option> the
427 service will be restarted regardless
428 whether it exited cleanly or not, or
429 got terminated abnormally by a
430 signal.</para></listitem>
434 <term><varname>PermissionsStartOnly=</varname></term>
435 <listitem><para>Takes a boolean
436 argument. If true, the permission
437 related execution options as
439 <varname>User=</varname> and similar
441 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
442 for more information) are only applied
443 to the process started with
444 <varname>ExecStart=</varname>, and not
446 <varname>ExecStartPre=</varname>,
447 <varname>ExecStartPost=</varname>,
448 <varname>ExecReload=</varname>,
449 <varname>ExecStop=</varname>,
450 <varname>ExecStopPost=</varname>
451 commands. If false, the setting is
452 applied to all configured commands the
453 same way. Defaults to
454 false.</para></listitem>
458 <term><varname>RootDirectoryStartOnly=</varname></term>
459 <listitem><para>Takes a boolean
460 argument. If true, the root directory
461 as configured with the
462 <varname>RootDirectory=</varname>
464 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
465 for more information) is only applied
466 to the process started with
467 <varname>ExecStart=</varname>, and not
469 <varname>ExecStartPre=</varname>,
470 <varname>ExecStartPost=</varname>,
471 <varname>ExecReload=</varname>,
472 <varname>ExecStop=</varname>,
473 <varname>ExecStopPost=</varname>
474 commands. If false, the setting is
475 applied to all configured commands the
476 same way. Defaults to
477 false.</para></listitem>
481 <term><varname>SysVStartPriority=</varname></term>
482 <listitem><para>Set the SysV start
483 priority to use to order this service
484 in relation to SysV services lacking
485 LSB headers. This option is only
486 necessary to fix ordering in relation
487 to legacy SysV services, that have no
488 ordering information encoded in the
489 script headers. As such it should only
490 be used as temporary compatibility
491 option, and not be used in new unit
492 files. Almost always it is a better
493 choice to add explicit ordering
495 <varname>After=</varname> or
496 <varname>Before=</varname>,
497 instead. For more details see
498 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
499 used, pass an integer value in the
500 range 0-99.</para></listitem>
504 <term><varname>KillMode=</varname></term>
505 <listitem><para>Specifies how
506 processes of this service shall be
508 <option>control-group</option>,
509 <option>process-group</option>,
510 <option>process</option>,
511 <option>none</option>.</para>
514 <option>control-group</option> all
515 remaining processes in the control
516 group of this service will be
517 terminated on service stop, after the
518 stop command (as configured with
519 <varname>ExecStop=</varname>) is
521 <option>process-group</option> only
522 the members of the process group of
523 the main service process are
525 <option>process</option> only the main
526 process itself is killed. If set to
527 <option>none</option> no process is
528 killed. In this case only the stop
529 command will be executed on service
530 stop, but no process be killed
531 otherwise. Processes remaining alive
532 after stop are left in their control
533 group and the control group continues
534 to exist after stop unless it is
536 <option>control-croup</option>.</para>
538 <para>Processes will first be
539 terminated via SIGTERM. If then after
540 a delay (configured via the
541 <varname>TimeoutSec=</varname> option)
542 processes still remain, the
543 termination request is repeated with
544 the SIGKILL signal. See
545 <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
547 information.</para></listitem>
551 <term><varname>NonBlocking=</varname></term>
552 <listitem><para>Set O_NONBLOCK flag
553 for all file descriptors passed via
554 socket-based activation. If true, all
555 file descriptors >= 3 (i.e. all except
556 STDIN/STDOUT/STDERR) will have
557 the O_NONBLOCK flag set and hence are in
558 non-blocking mode. This option is only
559 useful in conjunction with a socket
560 unit, as described in
561 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
562 to false.</para></listitem>
566 <term><varname>NotifyAccess=</varname></term>
567 <listitem><para>Controls access to the
568 service status notification socket, as
570 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
572 <option>none</option> (the default),
573 <option>main</option> or
574 <option>all</option>. If
575 <option>none</option> no daemon status
576 updates are accepted by the service
577 processes, all status update messages
578 are ignored. If <option>main</option>
579 only service updates sent from the
580 main process of the service are
581 accepted. If <option>all</option> all
582 services updates from all members of
583 the service's control group are
584 accepted. This option must be set to
585 open access to the notification socket
587 <varname>Type=notify</varname> (see above).</para></listitem>
594 <title>See Also</title>
596 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
597 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
598 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
599 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>