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>oneshot</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, if the process offers
133 functionality to other processes on
134 the system its communication channels
135 should be installed before the daemon
136 is started up (e.g. sockets set up by
137 systemd, via socket activation), as
138 systemd will immediately proceed
139 starting follow-up units.</para>
142 <option>forking</option> it is
143 expected that the process configured
144 with <varname>ExecStart=</varname>
145 will call <function>fork()</function>
146 as part of its start-up. The parent process is
147 expected to exit when start-up is
148 complete and all communication
149 channels set up. The child continues
150 to run as the main daemon
151 process. This is the behaviour of
152 traditional UNIX daemons. If this
153 setting is used, it is recommended to
155 <varname>PIDFile=</varname> option, so
156 that systemd can identify the main
157 process of the daemon. systemd will
158 proceed starting follow-up units as
159 soon as the parent process
163 <option>oneshot</option> is similar
164 to <option>simple</option>, however
165 it is expected that the process has to
166 exit before systemd starts follow-up
167 units. <varname>RemainAfterExit=</varname>
168 is particularly useful for this type
172 <option>dbus</option> is similar to
173 <option>simple</option>, however it is
174 expected that the daemon acquires a
175 name on the D-Bus bus, as configured
177 <varname>BusName=</varname>. systemd
178 will proceed starting follow-up units
179 after the D-Bus bus name has been
180 acquired. Service units with this
181 option configured implicitly gain
183 <filename>dbus.socket</filename>
187 <option>notify</option> is similar to
188 <option>simple</option>, however it is
189 expected that the daemon sends a
190 notification message via
191 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
192 or an equivalent call when it finished
193 starting up. systemd will proceed
194 starting follow-up units after this
195 notification message has been sent. If
197 <varname>NotifyAccess=</varname> (see
198 below) should be set to open access to
199 the notification socket provided by
201 <varname>NotifyAccess=</varname> is not
202 set, it will implicitly be set to
203 <option>main</option>.</para>
208 <term><varname>RemainAfterExit=</varname></term>
210 <listitem><para>Takes a boolean value
211 that specifies whether the service
212 shall be considered active even when
213 all its processes exited. Defaults to
214 <option>no</option>.</para>
219 <term><varname>GuessMainPID=</varname></term>
221 <listitem><para>Takes a boolean value
222 that specifies whether systemd should
223 try to guess the main PID of a service
224 should if it cannot be determined
225 reliably. This option is ignored
226 unless <option>Type=forking</option>
227 is set and <option>PIDFile=</option>
228 is unset because for the other types
229 or with an explicitly configured PID
230 file the main PID is always known. The
231 guessing algorithm might come to
232 incorrect conclusions if a daemon
233 consists of more than one process. If
234 the main PID cannot be determined
235 failure detection and automatic
236 restarting of a service will not work
237 reliably. Defaults to
238 <option>yes</option>.</para>
243 <term><varname>PIDFile=</varname></term>
245 <listitem><para>Takes an absolute file
246 name pointing to the PID file of this
247 daemon. Use of this option is
248 recommended for services where
249 <varname>Type=</varname> is set to
250 <option>forking</option>. systemd will
251 read the PID of the main process of
252 the daemon after start-up of the
253 service. systemd will not write to the
254 file configured here.</para>
259 <term><varname>BusName=</varname></term>
261 <listitem><para>Takes a D-Bus bus
262 name, where this service is reachable
263 as. This option is mandatory for
265 <varname>Type=</varname> is set to
266 <option>dbus</option>, but its use
267 is otherwise recommended as well if
268 the process takes a name on the D-Bus
274 <term><varname>ExecStart=</varname></term>
275 <listitem><para>Takes a command line
276 that is executed when this service
277 shall be started up. The first token
278 of the command line must be an
279 absolute file name, then followed by
280 arguments for the process. It is
281 mandatory to set this option for all
282 services. This option may not be
283 specified more than once, except when
284 <varname>Type=oneshot</varname> is
285 used in which case more than one
286 <varname>ExecStart=</varname> line is
287 accepted which are then invoked one by
288 one, sequentially in the order they
289 appear in the unit file.</para>
291 <para>Optionally, if the absolute file
292 name is prefixed with
293 <literal>@</literal>, the second token
295 <literal>argv[0]</literal> to the
296 executed process, followed by the
297 further arguments specified. If the
298 first token is prefixed with
299 <literal>-</literal> an exit code of
300 the command normally considered a
301 failure (i.e. non-zero exit status or
302 abnormal exit due to signal) is ignored
303 and considered success. If both
304 <literal>-</literal> and
305 <literal>@</literal> are used for the
306 same command the former must precede
308 <varname>Type=forking</varname> is
309 set, the process started via this
310 command line will be considered the
311 main process of the daemon. The
312 command line accepts % specifiers as
314 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
316 <para>On top of that basic environment
317 variable substitution is
319 <literal>${FOO}</literal> as part of a
320 word, or as word of its own on the
321 command line, in which case it will be
322 replaced by the value of the
323 environment variable including all
324 whitespace it contains, resulting in a
326 <literal>$FOO</literal> as a separate
327 word on the command line, in which
328 case it will be replaced by the value
329 of the environment variable split up
330 at whitespace, resulting in no or more
331 arguments. Note that the first
332 argument (i.e. the program to execute)
333 may not be a variable, and must be a
334 literal and absolute path
335 name.</para></listitem>
339 <term><varname>ExecStartPre=</varname></term>
340 <term><varname>ExecStartPost=</varname></term>
341 <listitem><para>Additional commands
342 that are executed before (resp. after)
344 <varname>ExecStart=</varname>. Multiple
345 command lines may be concatenated in a
346 single directive, by separating them
347 by semicolons (these semicolons must
348 be passed as separate words). In that
349 case, the commands are executed one
351 serially. Alternatively, these
352 directives may be specified more than
353 once with the same effect. However,
354 the latter syntax is not recommended
355 for compatibility with parsers
357 <filename>.desktop</filename> files.
358 Use of these settings is
359 optional. Specifier and environment
360 variable substitution is
361 supported.</para></listitem>
365 <term><varname>ExecReload=</varname></term>
366 <listitem><para>Commands to execute to
367 trigger a configuration reload in the
368 service. This argument takes multiple
369 command lines, following the same
370 scheme as pointed out for
371 <varname>ExecStartPre=</varname>
372 above. Use of this setting is
373 optional. Specifier and environment
374 variable substitution is supported
375 here following the same scheme as for
376 <varname>ExecStart=</varname>. One
377 special environment variable is set:
378 if known <literal>$MAINPID</literal> is
379 set to the main process of the
380 daemon, and may be used for command
381 lines like the following:
382 <command>/bin/kill -HUP
383 $MAINPID</command>.</para></listitem>
387 <term><varname>ExecStop=</varname></term>
388 <listitem><para>Commands to execute to
389 stop the service started via
390 <varname>ExecStart=</varname>. This
391 argument takes multiple command lines,
392 following the same scheme as pointed
394 <varname>ExecStartPre=</varname>
395 above. Use of this setting is
396 optional. All processes remaining for
397 a service after the commands
398 configured in this option are run are
399 terminated according to the
400 <varname>KillMode=</varname> setting
401 (see below). If this option is not
402 specified the process is terminated
403 right-away when service stop is
404 requested. Specifier and environment
405 variable substitution is supported
407 <literal>$MAINPID</literal>, see
408 above).</para></listitem>
412 <term><varname>ExecStopPost=</varname></term>
413 <listitem><para>Additional commands
414 that are executed after the service
415 was stopped using the commands
417 <varname>ExecStop=</varname>. This
418 argument takes multiple command lines,
419 following the same scheme as pointed
421 <varname>ExecStartPre</varname>. Use
423 optional. Specifier and environment
424 variable substitution is
425 supported.</para></listitem>
429 <term><varname>RestartSec=</varname></term>
430 <listitem><para>Configures the time to
431 sleep before restarting a service (as
433 <varname>Restart=</varname>). Takes a
434 unit-less value in seconds, or a time
435 span value such as "5min
437 100ms.</para></listitem>
441 <term><varname>TimeoutSec=</varname></term>
442 <listitem><para>Configures the time to
443 wait for start-up and stop. If a
444 daemon service does not signal
445 start-up completion within the
446 configured time the service will be
447 considered failed and be shut down
448 again. If a service is asked to stop
449 but does not terminate in the
450 specified time it will be terminated
451 forcibly via SIGTERM, and after
452 another delay of this time with
454 <varname>KillMode=</varname>
455 below.) Takes a unit-less value in seconds, or a
456 time span value such as "5min
457 20s". Pass 0 to disable the timeout
459 90s.</para></listitem>
463 <term><varname>WatchdogSec=</varname></term>
464 <listitem><para>Configures the watchdog
465 timeout for a service. This is activated
466 when the start-up is completed. The service
468 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
469 regularly with "WATCHDOG=1". If the time
470 between two such calls is larger than
471 the configured time then the service
472 enters a failure state. By setting
473 <term><varname>Restart=</varname></term>
474 to <option>on-failure</option> or
475 <option>always</option> the service can
476 be restarted. Defaults to 0s, which
477 disables this feature.</para></listitem>
481 <term><varname>Restart=</varname></term>
482 <listitem><para>Configures whether the
483 main service process shall be
484 restarted when it exits. Takes one of
486 <option>on-success</option>,
487 <option>on-failure</option>,
488 <option>on-abort</option> or
489 <option>always</option>. If set to
490 <option>no</option> (the default) the
491 service will not be restarted when it
493 <option>on-success</option> it will be
494 restarted only when it exited cleanly,
495 i.e. terminated with an exit code of
497 <option>on-failure</option> it will be
498 restarted only when it exited with an
499 exit code not equalling 0, or when
500 terminated by a signal. If set to
501 <option>on-abort</option> it will be
502 restarted only if it exits due to
503 reception of an uncaught signal. If
504 set to <option>always</option> the
505 service will be restarted regardless
506 whether it exited cleanly or not, or
507 got terminated abnormally by a
508 signal.</para></listitem>
512 <term><varname>PermissionsStartOnly=</varname></term>
513 <listitem><para>Takes a boolean
514 argument. If true, the permission
515 related execution options as
517 <varname>User=</varname> and similar
519 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
520 for more information) are only applied
521 to the process started with
522 <varname>ExecStart=</varname>, and not
524 <varname>ExecStartPre=</varname>,
525 <varname>ExecStartPost=</varname>,
526 <varname>ExecReload=</varname>,
527 <varname>ExecStop=</varname>,
528 <varname>ExecStopPost=</varname>
529 commands. If false, the setting is
530 applied to all configured commands the
531 same way. Defaults to
532 false.</para></listitem>
536 <term><varname>RootDirectoryStartOnly=</varname></term>
537 <listitem><para>Takes a boolean
538 argument. If true, the root directory
539 as configured with the
540 <varname>RootDirectory=</varname>
542 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
543 for more information) is only applied
544 to the process started with
545 <varname>ExecStart=</varname>, and not
547 <varname>ExecStartPre=</varname>,
548 <varname>ExecStartPost=</varname>,
549 <varname>ExecReload=</varname>,
550 <varname>ExecStop=</varname>,
551 <varname>ExecStopPost=</varname>
552 commands. If false, the setting is
553 applied to all configured commands the
554 same way. Defaults to
555 false.</para></listitem>
559 <term><varname>SysVStartPriority=</varname></term>
560 <listitem><para>Set the SysV start
561 priority to use to order this service
562 in relation to SysV services lacking
563 LSB headers. This option is only
564 necessary to fix ordering in relation
565 to legacy SysV services, that have no
566 ordering information encoded in the
567 script headers. As such it should only
568 be used as temporary compatibility
569 option, and not be used in new unit
570 files. Almost always it is a better
571 choice to add explicit ordering
573 <varname>After=</varname> or
574 <varname>Before=</varname>,
575 instead. For more details see
576 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
577 used, pass an integer value in the
578 range 0-99.</para></listitem>
582 <term><varname>KillMode=</varname></term>
583 <listitem><para>Specifies how
584 processes of this service shall be
586 <option>control-group</option>,
587 <option>process</option>,
588 <option>none</option>.</para>
591 <option>control-group</option> all
592 remaining processes in the control
593 group of this service will be
594 terminated on service stop, after the
595 stop command (as configured with
596 <varname>ExecStop=</varname>) is
598 <option>process</option> only the main
599 process itself is killed. If set to
600 <option>none</option> no process is
601 killed. In this case only the stop
602 command will be executed on service
603 stop, but no process be killed
604 otherwise. Processes remaining alive
605 after stop are left in their control
606 group and the control group continues
607 to exist after stop unless it is
609 <option>control-group</option>.</para>
611 <para>Processes will first be
612 terminated via SIGTERM (unless the
613 signal to send is changed via
614 <varname>KillSignal=</varname>). If
615 then after a delay (configured via the
616 <varname>TimeoutSec=</varname> option)
617 processes still remain, the
618 termination request is repeated with
619 the SIGKILL signal (unless this is
621 <varname>SendSIGKILL=</varname>
623 <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
625 information.</para></listitem>
629 <term><varname>KillSignal=</varname></term>
630 <listitem><para>Specifies which signal
631 to use when killing a
632 service. Defaults to SIGTERM.
637 <term><varname>SendSIGKILL=</varname></term>
638 <listitem><para>Specifies whether to
639 send SIGKILL to remaining processes
640 after a timeout, if the normal
641 shutdown procedure left processes of
642 the service around. Takes a boolean
643 value. Defaults to "yes".
648 <term><varname>NonBlocking=</varname></term>
649 <listitem><para>Set O_NONBLOCK flag
650 for all file descriptors passed via
651 socket-based activation. If true, all
652 file descriptors >= 3 (i.e. all except
653 STDIN/STDOUT/STDERR) will have
654 the O_NONBLOCK flag set and hence are in
655 non-blocking mode. This option is only
656 useful in conjunction with a socket
657 unit, as described in
658 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
659 to false.</para></listitem>
663 <term><varname>NotifyAccess=</varname></term>
664 <listitem><para>Controls access to the
665 service status notification socket, as
667 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
669 <option>none</option> (the default),
670 <option>main</option> or
671 <option>all</option>. If
672 <option>none</option> no daemon status
673 updates are accepted from the service
674 processes, all status update messages
675 are ignored. If <option>main</option>
676 only service updates sent from the
677 main process of the service are
678 accepted. If <option>all</option> all
679 services updates from all members of
680 the service's control group are
681 accepted. This option must be set to
682 open access to the notification socket
684 <varname>Type=notify</varname> (see above).</para></listitem>
688 <term><varname>Sockets=</varname></term>
689 <listitem><para>Specifies the name of
690 the socket units this service shall
691 inherit the sockets from when the
692 service is started. Normally it
693 should not be necessary to use this
694 setting as all sockets whose unit
695 shares the same name as the service
696 (ignoring the different suffix of course)
697 are passed to the spawned
700 <para>Note that the same socket may be
701 passed to multiple processes at the
702 same time. Also note that a different
703 service may be activated on incoming
704 traffic than inherits the sockets. Or
706 <varname>Service=</varname> setting of
707 <filename>.socket</filename> units
708 doesn't have to match the inverse of the
709 <varname>Sockets=</varname> setting of
710 the <filename>.service</filename> it
711 refers to.</para></listitem>
715 <term><varname>FsckPassNo=</varname></term>
716 <listitem><para>Set the fsck passno
717 priority to use to order this service
718 in relation to other file system
719 checking services. This option is only
720 necessary to fix ordering in relation
721 to fsck jobs automatically created for
722 all <filename>/etc/fstab</filename>
723 entries with a value in the fs_passno
724 column > 0. As such it should only be
725 used as option for fsck
726 services. Almost always it is a better
727 choice to add explicit ordering
729 <varname>After=</varname> or
730 <varname>Before=</varname>,
731 instead. For more details see
732 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
733 used, pass an integer value in the
735 <filename>/etc/fstab</filename>'s
736 fs_passno column. See
737 <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
738 for details.</para></listitem>
745 <title>See Also</title>
747 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
748 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
749 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
750 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>