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 [Unit] and [Install] sections. The
68 service specific configuration options are configured
69 in the [Service] section.</para>
71 <para>Additional options are listed in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
75 <title>Options</title>
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>
88 <term><varname>Type=</varname></term>
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>
99 <option>simple</option> (the default
100 value) it is expected that the process
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>
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
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
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
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
147 <varname>BusName=</varname>. systemd
148 will proceed starting follow-up units
149 after the D-Bus bus name has been
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
163 <option>NotifyAccess=</option> (see
164 below) must be set to open access to
165 the notification socket provided by
171 <term><varname>ValidNoProcess=</varname></term>
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>
182 <term><varname>PIDFile=</varname></term>
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>
194 <term><varname>BusName=</varname></term>
196 <listitem><para>Takes a D-Bus bus
197 name, where this service is reachable
198 as. This option is mandatory for
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
209 <term><varname>ExecStart=</varname></term>
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
228 daemon.</para></listitem>
232 <term><varname>ExecStartPre=</varname></term>
233 <term><varname>ExecStartPost=</varname></term>
234 <listitem><para>Additional commands
235 that are executed before (resp. after)
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>
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.
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>
274 <term><varname>ExecStopPost=</varname></term>
275 <listitem><para>Additional commands
276 that are executed after the service
277 was stopped using the commands
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>
287 <term><varname>RestartSec=</varname></term>
288 <listitem><para>Configures the time to
289 sleep before restarting a service (as
291 <varname>Restart=</varname>). Takes a
292 unit-less value in seconds, or a time
293 span value such as "5min
295 100ms.</para></listitem>
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
312 <option>KillMode=</option>
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
317 60s.</para></listitem>
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
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>
343 <term><varname>PermissionsStartOnly=</varname></term>
344 <listitem><para>Takes a boolean
345 argument. If true, the permission
346 related execution options as
348 <varname>User=</varname> and similar
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
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>
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>
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
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>
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
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>
413 <term><varname>KillMode=</varname></term>
414 <listitem><para>Specifies how
415 processes of this service shall be
417 <option>control-group</option>,
418 <option>process-group</option>,
419 <option>process</option>,
420 <option>none</option>.</para>
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
430 <option>process-group</option> only
431 the members of the process group of
432 the main service process are
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
445 <option>control-croup</option>.</para>
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>
456 information.</para></listitem>
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>
475 <term><varname>NotifyAccess=</varname></term>
476 <listitem><para>Controls access to the
477 service status notification socket, as
479 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
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
496 <varname>Type=notify</varname> (see above).</para></listitem>
503 <title>See Also</title>
505 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
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>