man/systemd.service.5

   1 '\" t
   2 .\"     Title: systemd.service
   3 .\"    Author: Lennart Poettering <lennart@poettering.net>
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 02/15/2012
   6 .\"    Manual: systemd.service
   7 .\"    Source: systemd
   8 .\"  Language: English
   9 .\"
  10 .TH "SYSTEMD\&.SERVICE" "5" "02/15/2012" "systemd" "systemd.service"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 systemd.service \- systemd service configuration files
  32 .SH "SYNOPSIS"
  33 .PP
  34 systemd\&.service
  35 .SH "DESCRIPTION"
  36 .PP
  37 A unit configuration file whose name ends in
  38 \&.service
  39 encodes information about a process controlled and supervised by systemd\&.
  40 .PP
  41 This man page lists the configuration options specific to this unit type\&. See
  42 \fBsystemd.unit\fR(5)
  43 for the common options of all unit configuration files\&. The common configuration items are configured in the generic
  44 [Unit]
  45 and
  46 [Install]
  47 sections\&. The service specific configuration options are configured in the
  48 [Service]
  49 section\&.
  50 .PP
  51 Additional options are listed in
  52 \fBsystemd.exec\fR(5), which define the execution environment the commands are executed in\&.
  53 .PP
  54 Unless
  55 \fIDefaultDependencies=\fR
  56 is set to
  57 \fBfalse\fR, service units will implicitly have dependencies of type
  58 \fIRequires=\fR
  59 and
  60 \fIAfter=\fR
  61 on
  62 basic\&.target
  63 as well as dependencies of type
  64 \fIConflicts=\fR
  65 and
  66 \fIBefore=\fR
  67 on
  68 shutdown\&.target\&. These ensure that normal service units pull in basic system initialization, and are terminated cleanly prior to system shutdown\&. Only services involved with early boot or late system shutdown should disable this option\&.
  69 .PP
  70 If a service is requested under a certain name but no unit configuration file is found, systemd looks for a SysV init script by the same name (with the
  71 \&.service
  72 suffix removed) and dynamically creates a service unit from that script\&. This is useful for compatibility with SysV\&.
  73 .SH "OPTIONS"
  74 .PP
  75 Service files must include a
  76 [Service]
  77 section, which carries information about the service and the process it supervises\&. A number of options that may be used in this section are shared with other unit types\&. These options are documented in
  78 \fBsystemd.exec\fR(5)\&. The options specific to the
  79 [Service]
  80 section of service units are the following:
  81 .PP
  82 \fIType=\fR
  83 .RS 4
  84 Configures the process start\-up type for this service unit\&. One of
  85 \fBsimple\fR,
  86 \fBforking\fR,
  87 \fBoneshot\fR,
  88 \fBdbus\fR,
  89 \fBnotify\fR\&.
  90 .sp
  91 If set to
  92 \fBsimple\fR
  93 (the default value) it is expected that the process configured with
  94 \fIExecStart=\fR
  95 is the main process of the service\&. In this mode, if the process offers functionality to other processes on the system its communication channels should be installed before the daemon is started up (e\&.g\&. sockets set up by systemd, via socket activation), as systemd will immediately proceed starting follow\-up units\&.
  96 .sp
  97 If set to
  98 \fBforking\fR
  99 it is expected that the process configured with
 100 \fIExecStart=\fR
 101 will call
 102 \fBfork()\fR
 103 as part of its start\-up\&. The parent process is expected to exit when start\-up is complete and all communication channels set up\&. The child continues to run as the main daemon process\&. This is the behaviour of traditional UNIX daemons\&. If this setting is used, it is recommended to also use the
 104 \fIPIDFile=\fR
 105 option, so that systemd can identify the main process of the daemon\&. systemd will proceed starting follow\-up units as soon as the parent process exits\&.
 106 .sp
 107 Behaviour of
 108 \fBoneshot\fR
 109 is similar to
 110 \fBsimple\fR, however it is expected that the process has to exit before systemd starts follow\-up units\&.
 111 \fIRemainAfterExit=\fR
 112 is particularly useful for this type of service\&.
 113 .sp
 114 Behaviour of
 115 \fBdbus\fR
 116 is similar to
 117 \fBsimple\fR, however it is expected that the daemon acquires a name on the D\-Bus bus, as configured by
 118 \fIBusName=\fR\&. systemd will proceed starting follow\-up units after the D\-Bus bus name has been acquired\&. Service units with this option configured implicitly gain dependencies on the
 119 dbus\&.socket
 120 unit\&.
 121 .sp
 122 Behaviour of
 123 \fBnotify\fR
 124 is similar to
 125 \fBsimple\fR, however it is expected that the daemon sends a notification message via
 126 \fBsd_notify\fR(3)
 127 or an equivalent call when it finished starting up\&. systemd will proceed starting follow\-up units after this notification message has been sent\&. If this option is used
 128 \fINotifyAccess=\fR
 129 (see below) should be set to open access to the notification socket provided by systemd\&. If
 130 \fINotifyAccess=\fR
 131 is not set, it will be implicitly set to
 132 \fBmain\fR\&.
 133 .RE
 134 .PP
 135 \fIRemainAfterExit=\fR
 136 .RS 4
 137 Takes a boolean value that specifies whether the service shall be considered active even when all its processes exited\&. Defaults to
 138 \fBno\fR\&.
 139 .RE
 140 .PP
 141 \fIGuessMainPID=\fR
 142 .RS 4
 143 Takes a boolean value that specifies whether systemd should try to guess the main PID of a service should if it cannot be determined reliably\&. This option is ignored unless
 144 \fBType=forking\fR
 145 is set and
 146 \fBPIDFile=\fR
 147 is unset because for the other types or with an explicitly configured PID file the main PID is always known\&. The guessing algorithm might come to incorrect conclusions if a daemon consists of more than one process\&. If the main PID cannot be determined failure detection and automatic restarting of a service will not work reliably\&. Defaults to
 148 \fByes\fR\&.
 149 .RE
 150 .PP
 151 \fIPIDFile=\fR
 152 .RS 4
 153 Takes an absolute file name pointing to the PID file of this daemon\&. Use of this option is recommended for services where
 154 \fIType=\fR
 155 is set to
 156 \fBforking\fR\&. systemd will read the PID of the main process of the daemon after start\-up of the service\&. systemd will not write to the file configured here\&.
 157 .RE
 158 .PP
 159 \fIBusName=\fR
 160 .RS 4
 161 Takes a D\-Bus bus name, where this service is reachable as\&. This option is mandatory for services where
 162 \fIType=\fR
 163 is set to
 164 \fBdbus\fR, but its use is otherwise recommended as well if the process takes a name on the D\-Bus bus\&.
 165 .RE
 166 .PP
 167 \fIExecStart=\fR
 168 .RS 4
 169 Takes a command line that is executed when this service shall be started up\&. The first token of the command line must be an absolute file name, then followed by arguments for the process\&. It is mandatory to set this option for all services\&. This option may not be specified more than once, except when
 170 \fIType=oneshot\fR
 171 is used in which case more than one
 172 \fIExecStart=\fR
 173 line is accepted which are then invoked one by one, sequentially in the order they appear in the unit file\&.
 174 .sp
 175 Optionally, if the absolute file name is prefixed with
 176 @, the second token will be passed as
 177 argv[0]
 178 to the executed process, followed by the further arguments specified\&. If the first token is prefixed with
 179 \-
 180 an exit code of the command normally considered a failure (i\&.e\&. non\-zero exit status or abnormal exit due to signal) is ignored and considered success\&. If both
 181 \-
 182 and
 183 @
 184 are used for the same command the former must precede the latter\&. Unless
 185 \fIType=forking\fR
 186 is set, the process started via this command line will be considered the main process of the daemon\&. The command line accepts % specifiers as described in
 187 \fBsystemd.unit\fR(5)\&.
 188 .sp
 189 On top of that basic environment variable substitution is supported\&. Use
 190 ${FOO}
 191 as part of a word, or as word of its own on the command line, in which case it will be replaced by the value of the environment variable including all whitespace it contains, resulting in a single argument\&. Use
 192 $FOO
 193 as a separate word on the command line, in which case it will be replaced by the value of the environment variable split up at whitespace, resulting in no or more arguments\&. Note that the first argument (i\&.e\&. the program to execute) may not be a variable, and must be a literal and absolute path name\&.
 194 .RE
 195 .PP
 196 \fIExecStartPre=\fR, \fIExecStartPost=\fR
 197 .RS 4
 198 Additional commands that are executed before (resp\&. after) the command in
 199 \fIExecStart=\fR\&. Multiple command lines may be concatenated in a single directive, by separating them by semicolons (these semicolons must be passed as separate words)\&. In that case, the commands are executed one after the other, serially\&. Alternatively, these directives may be specified more than once with the same effect\&. However, the latter syntax is not recommended for compatibility with parsers suitable for XDG
 200 \&.desktop
 201 files\&. Use of these settings is optional\&. Specifier and environment variable substitution is supported\&.
 202 .RE
 203 .PP
 204 \fIExecReload=\fR
 205 .RS 4
 206 Commands to execute to trigger a configuration reload in the service\&. This argument takes multiple command lines, following the same scheme as pointed out for
 207 \fIExecStartPre=\fR
 208 above\&. Use of this setting is optional\&. Specifier and environment variable substitution is supported here following the same scheme as for
 209 \fIExecStart=\fR\&. One special environment variable is set: if known
 210 $MAINPID
 211 is set to the main process of the daemon, and may be used for command lines like the following:
 212 \fB/bin/kill \-HUP $MAINPID\fR\&.
 213 .RE
 214 .PP
 215 \fIExecStop=\fR
 216 .RS 4
 217 Commands to execute to stop the service started via
 218 \fIExecStart=\fR\&. This argument takes multiple command lines, following the same scheme as pointed out for
 219 \fIExecStartPre=\fR
 220 above\&. Use of this setting is optional\&. All processes remaining for a service after the commands configured in this option are run are terminated according to the
 221 \fIKillMode=\fR
 222 setting (see below)\&. If this option is not specified the process is terminated right\-away when service stop is requested\&. Specifier and environment variable substitution is supported (including
 223 $MAINPID, see above)\&.
 224 .RE
 225 .PP
 226 \fIExecStopPost=\fR
 227 .RS 4
 228 Additional commands that are executed after the service was stopped using the commands configured in
 229 \fIExecStop=\fR\&. This argument takes multiple command lines, following the same scheme as pointed out for
 230 \fIExecStartPre\fR\&. Use of these settings is optional\&. Specifier and environment variable substitution is supported\&.
 231 .RE
 232 .PP
 233 \fIRestartSec=\fR
 234 .RS 4
 235 Configures the time to sleep before restarting a service (as configured with
 236 \fIRestart=\fR)\&. Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Defaults to 100ms\&.
 237 .RE
 238 .PP
 239 \fITimeoutSec=\fR
 240 .RS 4
 241 Configures the time to wait for start\-up and stop\&. If a daemon service does not signal start\-up completion within the configured time the service will be considered failed and be shut down again\&. If a service is asked to stop but does not terminate in the specified time it will be terminated forcibly via SIGTERM, and after another delay of this time with SIGKILL\&. (See
 242 \fIKillMode=\fR
 243 below\&.) Takes a unit\-less value in seconds, or a time span value such as "5min 20s"\&. Pass 0 to disable the timeout logic\&. Defaults to 90s\&.
 244 .RE
 245 .PP
 246 \fIWatchdogSec=\fR
 247 .RS 4
 248 Configures the watchdog timeout for a service\&. This is activated when the start\-up is completed\&. The service must call
 249 \fBsd_notify\fR(3)
 250 regularly with "WATCHDOG=1"\&. If the time between two such calls is larger than the configured time then the service is placed in a failure state\&. By setting
 251 \fIRestart=\fR
 252 to
 253 \fBon\-failure\fR
 254 or
 255 \fBalways\fR
 256 the service will be automatically restarted\&. The time configured here will be passed to the executed service process in the
 257 \fIWATCHDOG_USEC=\fR
 258 environment variable\&. If this option is used
 259 \fINotifyAccess=\fR
 260 (see below) should be set to open access to the notification socket provided by systemd\&. If
 261 \fINotifyAccess=\fR
 262 is not set, it will be implicitly set to
 263 \fBmain\fR\&. Defaults to 0, which disables this feature\&.
 264 .RE
 265 .PP
 266 \fIRestart=\fR
 267 .RS 4
 268 Configures whether the main service process shall be restarted when it exits\&. Takes one of
 269 \fBno\fR,
 270 \fBon\-success\fR,
 271 \fBon\-failure\fR,
 272 \fBon\-abort\fR
 273 or
 274 \fBalways\fR\&. If set to
 275 \fBno\fR
 276 (the default) the service will not be restarted when it exits\&. If set to
 277 \fBon\-success\fR
 278 it will be restarted only when it exited cleanly, i\&.e\&. terminated with an exit code of 0\&. If set to
 279 \fBon\-failure\fR
 280 it will be restarted only when it exited with an exit code not equalling 0, when terminated by a signal, when an operation times out or when the configured watchdog timeout is triggered\&. If set to
 281 \fBon\-abort\fR
 282 it will be restarted only if it exits due to reception of an uncaught signal\&. If set to
 283 \fBalways\fR
 284 the service will be restarted regardless whether it exited cleanly or not, got terminated abnormally by a signal or hit a timeout\&.
 285 .RE
 286 .PP
 287 \fIPermissionsStartOnly=\fR
 288 .RS 4
 289 Takes a boolean argument\&. If true, the permission related execution options as configured with
 290 \fIUser=\fR
 291 and similar options (see
 292 \fBsystemd.exec\fR(5)
 293 for more information) are only applied to the process started with
 294 \fIExecStart=\fR, and not to the various other
 295 \fIExecStartPre=\fR,
 296 \fIExecStartPost=\fR,
 297 \fIExecReload=\fR,
 298 \fIExecStop=\fR,
 299 \fIExecStopPost=\fR
 300 commands\&. If false, the setting is applied to all configured commands the same way\&. Defaults to false\&.
 301 .RE
 302 .PP
 303 \fIRootDirectoryStartOnly=\fR
 304 .RS 4
 305 Takes a boolean argument\&. If true, the root directory as configured with the
 306 \fIRootDirectory=\fR
 307 option (see
 308 \fBsystemd.exec\fR(5)
 309 for more information) is only applied to the process started with
 310 \fIExecStart=\fR, and not to the various other
 311 \fIExecStartPre=\fR,
 312 \fIExecStartPost=\fR,
 313 \fIExecReload=\fR,
 314 \fIExecStop=\fR,
 315 \fIExecStopPost=\fR
 316 commands\&. If false, the setting is applied to all configured commands the same way\&. Defaults to false\&.
 317 .RE
 318 .PP
 319 \fISysVStartPriority=\fR
 320 .RS 4
 321 Set the SysV start priority to use to order this service in relation to SysV services lacking LSB headers\&. This option is only necessary to fix ordering in relation to legacy SysV services, that have no ordering information encoded in the script headers\&. As such it should only be used as temporary compatibility option, and not be used in new unit files\&. Almost always it is a better choice to add explicit ordering directives via
 322 \fIAfter=\fR
 323 or
 324 \fIBefore=\fR, instead\&. For more details see
 325 \fBsystemd.unit\fR(5)\&. If used, pass an integer value in the range 0\-99\&.
 326 .RE
 327 .PP
 328 \fIKillMode=\fR
 329 .RS 4
 330 Specifies how processes of this service shall be killed\&. One of
 331 \fBcontrol\-group\fR,
 332 \fBprocess\fR,
 333 \fBnone\fR\&.
 334 .sp
 335 If set to
 336 \fBcontrol\-group\fR
 337 all remaining processes in the control group of this service will be terminated on service stop, after the stop command (as configured with
 338 \fIExecStop=\fR) is executed\&. If set to
 339 \fBprocess\fR
 340 only the main process itself is killed\&. If set to
 341 \fBnone\fR
 342 no process is killed\&. In this case only the stop command will be executed on service stop, but no process be killed otherwise\&. Processes remaining alive after stop are left in their control group and the control group continues to exist after stop unless it is empty\&. Defaults to
 343 \fBcontrol\-group\fR\&.
 344 .sp
 345 Processes will first be terminated via SIGTERM (unless the signal to send is changed via
 346 \fIKillSignal=\fR)\&. If then after a delay (configured via the
 347 \fITimeoutSec=\fR
 348 option) processes still remain, the termination request is repeated with the SIGKILL signal (unless this is disabled via the
 349 \fISendSIGKILL=\fR
 350 option)\&. See
 351 \fBkill\fR(2)
 352 for more information\&.
 353 .RE
 354 .PP
 355 \fIKillSignal=\fR
 356 .RS 4
 357 Specifies which signal to use when killing a service\&. Defaults to SIGTERM\&.
 358 .RE
 359 .PP
 360 \fISendSIGKILL=\fR
 361 .RS 4
 362 Specifies whether to send SIGKILL to remaining processes after a timeout, if the normal shutdown procedure left processes of the service around\&. Takes a boolean value\&. Defaults to "yes"\&.
 363 .RE
 364 .PP
 365 \fINonBlocking=\fR
 366 .RS 4
 367 Set O_NONBLOCK flag for all file descriptors passed via socket\-based activation\&. If true, all file descriptors >= 3 (i\&.e\&. all except STDIN/STDOUT/STDERR) will have the O_NONBLOCK flag set and hence are in non\-blocking mode\&. This option is only useful in conjunction with a socket unit, as described in
 368 \fBsystemd.socket\fR(5)\&. Defaults to false\&.
 369 .RE
 370 .PP
 371 \fINotifyAccess=\fR
 372 .RS 4
 373 Controls access to the service status notification socket, as accessible via the
 374 \fBsd_notify\fR(3)
 375 call\&. Takes one of
 376 \fBnone\fR
 377 (the default),
 378 \fBmain\fR
 379 or
 380 \fBall\fR\&. If
 381 \fBnone\fR
 382 no daemon status updates are accepted from the service processes, all status update messages are ignored\&. If
 383 \fBmain\fR
 384 only service updates sent from the main process of the service are accepted\&. If
 385 \fBall\fR
 386 all services updates from all members of the service\*(Aqs control group are accepted\&. This option should be set to open access to the notification socket when using
 387 \fIType=notify\fR
 388 or
 389 \fIWatchdogUsec=\fR
 390 (see above)\&. If those options are used but
 391 \fINotifyAccess=\fR
 392 not configured it will be implicitly set to
 393 \fBmain\fR\&.
 394 .RE
 395 .PP
 396 \fISockets=\fR
 397 .RS 4
 398 Specifies the name of the socket units this service shall inherit the sockets from when the service is started\&. Normally it should not be necessary to use this setting as all sockets whose unit shares the same name as the service (ignoring the different suffix of course) are passed to the spawned process\&.
 399 .sp
 400 Note that the same socket may be passed to multiple processes at the same time\&. Also note that a different service may be activated on incoming traffic than inherits the sockets\&. Or in other words: The
 401 \fIService=\fR
 402 setting of
 403 \&.socket
 404 units doesn\*(Aqt have to match the inverse of the
 405 \fISockets=\fR
 406 setting of the
 407 \&.service
 408 it refers to\&.
 409 .RE
 410 .PP
 411 \fIFsckPassNo=\fR
 412 .RS 4
 413 Set the fsck passno priority to use to order this service in relation to other file system checking services\&. This option is only necessary to fix ordering in relation to fsck jobs automatically created for all
 414 /etc/fstab
 415 entries with a value in the fs_passno column > 0\&. As such it should only be used as option for fsck services\&. Almost always it is a better choice to add explicit ordering directives via
 416 \fIAfter=\fR
 417 or
 418 \fIBefore=\fR, instead\&. For more details see
 419 \fBsystemd.unit\fR(5)\&. If used, pass an integer value in the same range as
 420 /etc/fstab\*(Aqs fs_passno column\&. See
 421 \fBfstab\fR(5)
 422 for details\&.
 423 .RE
 424 .PP
 425 \fIStartLimitInterval=\fR, \fIStartLimitBurst=\fR
 426 .RS 4
 427 Configure service start rate limiting\&. By default services which are started more often than 5 times within 10s are not permitted to start any more times until the 10s interval ends\&. With these two options this rate limiting may be modified\&. Use
 428 \fIStartLimitInterval=\fR
 429 to configure the checking interval (defaults to 10s, set to 0 to disable any kind of rate limiting)\&. Use
 430 \fIStartLimitBurst=\fR
 431 to configure how many starts per interval are allowed (defaults to 5)\&. These configuration options are particularly useful in conjunction with
 432 \fIRestart=\fR\&.
 433 .RE
 434 .PP
 435 \fIStartLimitAction=\fR
 436 .RS 4
 437 Configure the action to take if the rate limit configured with
 438 \fIStartLimitInterval=\fR
 439 and
 440 \fIStartLimitBurst=\fR
 441 is hit\&. Takes one of
 442 \fBnone\fR,
 443 \fBreboot\fR,
 444 \fBreboot\-force\fR
 445 or
 446 \fBreboot\-immediate\fR\&. If
 447 \fBnone\fR
 448 is set, hitting the rate limit will trigger no action besides that the start will not be permitted\&.
 449 \fBreboot\fR
 450 causes a reboot following the normal shutdown procedure (i\&.e\&. equivalent to
 451 \fBsystemctl reboot\fR),
 452 \fBreboot\-force\fR
 453 causes an forced reboot which will terminate all processes forcibly but should cause no dirty file systems on reboot (i\&.e\&. equivalent to
 454 \fBsystemctl reboot \-f\fR) and
 455 \fBreboot\-immediate\fR
 456 causes immediate execution of the
 457 \fBreboot\fR(2)
 458 system call, which might result in data loss\&. Defaults to
 459 \fBnone\fR\&.
 460 .RE
 461 .SH "SEE ALSO"
 462 .PP
 463
 464 \fBsystemd\fR(1),
 465 \fBsystemctl\fR(8),
 466 \fBsystemd.unit\fR(5),
 467 \fBsystemd.exec\fR(5)
 468 .SH "AUTHOR"
 469 .PP
 470 \fBLennart Poettering\fR <\&lennart@poettering\&.net\&>
 471 .RS 4
 472 Developer
 473 .RE