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
72 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
73 which define the execution environment the commands
74 are executed in.</para>
78 <title>Options</title>
80 <para>Service files must include a [Service] section,
81 which carries information about the service and the
82 process it supervises. A number of options that may be
83 used in this section are shared with other unit
84 types. These options are documented in
85 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
86 options specific to the [Service] section of service
87 units are the following:</para>
91 <term><varname>Type=</varname></term>
93 <listitem><para>Configures the process
94 start-up type for this service
95 unit. One of <option>simple</option>,
96 <option>forking</option>,
97 <option>finish</option>,
98 <option>dbus</option>,
99 <option>notify</option>.</para>
102 <option>simple</option> (the default
103 value) it is expected that the process
105 <varname>ExecStart=</varname> is the
106 main process of the service. In this
107 mode, communication channels must be
108 installed before the daemon is started
109 up (e.g. sockets set up by systemd,
110 via socket activation), as systemd
111 will immediately proceed starting
112 follow-up units.</para>
115 <option>forking</option> it is
116 expected that the process configured
117 with <varname>ExecStart=</varname>
118 will start up and call
119 <function>fork()</function>. The
120 parent process is expected to finish
121 when start-up is complete and all
122 communication channels set up. The
123 child continues to run as the main
124 daemon process. This is the behaviour
125 of traditional UNIX daemons. If this
126 setting is used, it is recommended to
128 <varname>PIDFile=</varname> option, so
129 that systemd can identify the main
130 process of the daemon. systemd will
131 proceed starting follow-up units as
132 soon as the parent process
136 <option>finish</option> is similar
137 to <option>simple</option>, however
138 it is expected that the process has to
139 exit before systemd starts follow-up
140 units. <varname>ValidNoProcess=</varname>
141 is particularly useful for this type
145 <option>dbus</option> is similar to
146 <option>simple</option>, however it
147 is expected that the daemon acquires a
148 name on the D-Bus bus, as configured
150 <varname>BusName=</varname>. systemd
151 will proceed starting follow-up units
152 after the D-Bus bus name has been
156 <option>notify</option> is similar to
157 <option>simple</option>, however it is
158 expected that the daemon sends a
159 notification message via
160 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
161 or an equivalent call when it finished
162 starting up. systemd will proceed
163 starting follow-up units after this
164 notification message has been sent. If
166 <option>NotifyAccess=</option> (see
167 below) must be set to open access to
168 the notification socket provided by
174 <term><varname>ValidNoProcess=</varname></term>
176 <listitem><para>Takes a boolean value
177 that specifies whether the service
178 shall be considered active even when
179 all its processes exited. Defaults to
180 <option>no</option>.</para>
185 <term><varname>PIDFile=</varname></term>
187 <listitem><para>Takes an absolute file
188 name pointing to the PID file of this
189 daemon. Use of this option is
190 recommended for services where
191 <varname>Type=</varname> is set to
192 <option>forking</option>.</para>
197 <term><varname>BusName=</varname></term>
199 <listitem><para>Takes a D-Bus bus
200 name, where this service is reachable
201 as. This option is mandatory for
203 <varname>Type=</varname> is set to
204 <option>dbus</option>, but its use
205 is otherwise recommended as well if
206 the process takes a name on the D-Bus
212 <term><varname>ExecStart=</varname></term>
213 <listitem><para>Takes a command line
214 that is executed when this service
215 shall be started up. The first token
216 of the command line must be an
217 absolute file name, then followed by
218 arguments for the process. It is
219 mandatory to set this option for all
220 services. This option may not be
221 specified more than once. Optionally,
222 if the absolute file name is prefixed
223 with @, the second token will be
224 passed as argv[0] to the executed
225 process, followed by the further
226 arguments specified. Unless
227 <option>Type=forking</option> is set,
228 the process started via this command
229 line will be considered the main
231 daemon.</para></listitem>
235 <term><varname>ExecStartPre=</varname></term>
236 <term><varname>ExecStartPost=</varname></term>
237 <listitem><para>Additional commands
238 that are executed before (resp. after)
240 <varname>ExecStart=</varname>. If
241 specified more than once, all commands
242 are executed one after the other,
243 serially. Use of these settings is
244 optional.</para></listitem>
248 <term><varname>ExecReload=</varname></term>
249 <listitem><para>Commands to execute to
250 trigger a configuration reload in the
251 service. If used more than once, all
252 commands are executed one after the
253 other, serially. Use of this setting is optional.
258 <term><varname>ExecStop=</varname></term>
259 <listitem><para>Commands to execute to
260 stop the service started via
261 <varname>ExecStart=</varname>. If used
262 more than once, all commands are
263 executed one after the other,
264 serially. Use of this setting is
265 optional. All processes remaining for
266 a service after the commands
267 configured in this option are run are
268 terminated according to the
269 <varname>KillMode=</varname> setting
270 (see below). If this option is not
271 specified the process is terminated
272 right-away when service stop is
273 requested.</para></listitem>
277 <term><varname>ExecStopPost=</varname></term>
278 <listitem><para>Additional commands
279 that are executed after the service
280 was stopped using the commands
282 <varname>ExecStop=</varname>. If
283 specified more than once, all commands
284 are executed one after the other,
285 serially. Use of these settings is
286 optional.</para></listitem>
290 <term><varname>RestartSec=</varname></term>
291 <listitem><para>Configures the time to
292 sleep before restarting a service (as
294 <varname>Restart=</varname>). Takes a
295 unit-less value in seconds, or a time
296 span value such as "5min
298 100ms.</para></listitem>
302 <term><varname>TimeoutSec=</varname></term>
303 <listitem><para>Configures the time to
304 wait for start-up and stop. If a
305 daemon service does not signal
306 start-up completion within the
307 configured time the service will be
308 considered failed and be shut down
309 again. If a service is asked to stop
310 but does not terminate in the
311 specified time it will be terminated
312 forcibly via SIGTERM, and after
313 another delay of this time with
315 <option>KillMode=</option>
316 below.) Takes a unit-less value in seconds, or a
317 time span value such as "5min
318 20s". Pass 0 to disable the timeout
320 60s.</para></listitem>
324 <term><varname>Restart=</varname></term>
325 <listitem><para>Configures whether the
326 main service process shall be restarted when
327 it exists. Takes one of
328 <option>once</option>,
329 <option>restart-on-success</option> or
330 <option>restart-always</option>. If
331 set to <option>once</option> (the
332 default) the service will not be
333 restarted when it exits. If set to
334 <option>restart-on-success</option> it
335 will be restarted only when it exited
336 cleanly, i.e. terminated with an exit
338 <option>restart-always</option> the
339 service will be restarted regardless
340 whether it exited cleanly or not, or
341 got terminated abnormally by a
342 signal.</para></listitem>
346 <term><varname>PermissionsStartOnly=</varname></term>
347 <listitem><para>Takes a boolean
348 argument. If true, the permission
349 related execution options as
351 <varname>User=</varname> and similar
353 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
354 for more information) are only applied
355 to the process started with
356 <varname>ExecStart=</varname>, and not
358 <varname>ExecStartPre=</varname>,
359 <varname>ExecStartPost=</varname>,
360 <varname>ExecReload=</varname>,
361 <varname>ExecStop=</varname>,
362 <varname>ExecStopPost=</varname>
363 commands. If false, the setting is
364 applied to all configured commands the
365 same way. Defaults to
366 false.</para></listitem>
370 <term><varname>RootDirectoryStartOnly=</varname></term>
371 <listitem><para>Takes a boolean
372 argument. If true, the root directory
373 as configured with the
374 <varname>RootDirectory=</varname>
376 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
377 for more information) is only applied
378 to the process started with
379 <varname>ExecStart=</varname>, and not
381 <varname>ExecStartPre=</varname>,
382 <varname>ExecStartPost=</varname>,
383 <varname>ExecReload=</varname>,
384 <varname>ExecStop=</varname>,
385 <varname>ExecStopPost=</varname>
386 commands. If false, the setting is
387 applied to all configured commands the
388 same way. Defaults to
389 false.</para></listitem>
393 <term><varname>SysVStartPriority=</varname></term>
394 <listitem><para>Set the SysV start
395 priority to use to order this service
396 in relation to SysV services lacking
397 LSB headers. This option is only
398 necessary to fix ordering in relation
399 to legacy SysV services, that have no
400 ordering information encoded in the
401 script headers. As such it should only
402 be used as temporary compatibility
403 option, and not be used in new unit
404 files. Almost always it is a better
405 choice to add explicit ordering
407 <varname>After=</varname> or
408 <varname>Before=</varname>,
409 instead. For more details see
410 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
411 used, pass an integer value in the
412 range 0-99.</para></listitem>
416 <term><varname>KillMode=</varname></term>
417 <listitem><para>Specifies how
418 processes of this service shall be
420 <option>control-group</option>,
421 <option>process-group</option>,
422 <option>process</option>,
423 <option>none</option>.</para>
426 <option>control-group</option> all
427 remaining processes in the control
428 group of this service will be
429 terminated on service stop, after the
430 stop command (as configured with
431 <varname>ExecStop=</varname>) is
433 <option>process-group</option> only
434 the members of the process group of
435 the main service process are
437 <option>process</option> only the main
438 process itself is killed. If set to
439 <option>none</option> no process is
440 killed. In this case only the stop
441 command will be executed on service
442 stop, but no process be killed
443 otherwise. Processes remaining alive
444 after stop are left in their control
445 group and the control group continues
446 to exist after stop unless it is
448 <option>control-croup</option>.</para>
450 <para>Processes will first be
451 terminated via SIGTERM. If then after
452 a delay (configured via the
453 <option>TimeoutSec=</option> option)
454 processes still remain, the
455 termination request is repeated with
456 the SIGKILL signal. See
457 <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
459 information.</para></listitem>
463 <term><varname>NonBlocking=</varname></term>
464 <listitem><para>Set O_NONBLOCK flag
465 for all file descriptors passed via
466 socket-based activation. If true, all
467 file descriptors >= 3 (i.e. all except
468 STDIN/STDOUT/STDERR) will have
469 the O_NONBLOCK flag set and hence are in
470 non-blocking mode. This option is only
471 useful in conjunction with a socket
472 unit, as described in
473 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults
474 to false.</para></listitem>
478 <term><varname>NotifyAccess=</varname></term>
479 <listitem><para>Controls access to the
480 service status notification socket, as
482 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
484 <option>none</option> (the default),
485 <option>main</option> or
486 <option>all</option>. If
487 <option>none</option> no daemon status
488 updates are accepted by the service
489 processes, all status update messages
490 are ignored. If <option>main</option>
491 only service updates sent from the
492 main process of the service are
493 accepted. If <option>all</option> all
494 services updates from all members of
495 the service's control group are
496 accepted. This option must be set to
497 open access to the notification socket
499 <varname>Type=notify</varname> (see above).</para></listitem>
506 <title>See Also</title>
508 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
509 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
510 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
511 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>