| | 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"> |
| | 5 | |
| | 6 | <!-- |
| | 7 | This file is part of systemd. |
| | 8 | |
| | 9 | Copyright 2010 Lennart Poettering |
| | 10 | |
| | 11 | systemd is free software; you can redistribute it and/or modify it |
| | 12 | under the terms of the GNU Lesser General Public License as published by |
| | 13 | the Free Software Foundation; either version 2.1 of the License, or |
| | 14 | (at your option) any later version. |
| | 15 | |
| | 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 | Lesser General Public License for more details. |
| | 20 | |
| | 21 | You should have received a copy of the GNU Lesser General Public License |
| | 22 | along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| | 23 | --> |
| | 24 | |
| | 25 | <refentry id="systemd.service"> |
| | 26 | <refentryinfo> |
| | 27 | <title>systemd.service</title> |
| | 28 | <productname>systemd</productname> |
| | 29 | |
| | 30 | <authorgroup> |
| | 31 | <author> |
| | 32 | <contrib>Developer</contrib> |
| | 33 | <firstname>Lennart</firstname> |
| | 34 | <surname>Poettering</surname> |
| | 35 | <email>lennart@poettering.net</email> |
| | 36 | </author> |
| | 37 | </authorgroup> |
| | 38 | </refentryinfo> |
| | 39 | |
| | 40 | <refmeta> |
| | 41 | <refentrytitle>systemd.service</refentrytitle> |
| | 42 | <manvolnum>5</manvolnum> |
| | 43 | </refmeta> |
| | 44 | |
| | 45 | <refnamediv> |
| | 46 | <refname>systemd.service</refname> |
| | 47 | <refpurpose>Service unit configuration</refpurpose> |
| | 48 | </refnamediv> |
| | 49 | |
| | 50 | <refsynopsisdiv> |
| | 51 | <para><filename><replaceable>service</replaceable>.service</filename></para> |
| | 52 | </refsynopsisdiv> |
| | 53 | |
| | 54 | <refsect1> |
| | 55 | <title>Description</title> |
| | 56 | |
| | 57 | <para>A unit configuration file whose name ends in |
| | 58 | <filename>.service</filename> encodes information |
| | 59 | about a process controlled and supervised by |
| | 60 | systemd.</para> |
| | 61 | |
| | 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> |
| | 71 | |
| | 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, and in |
| | 76 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| | 77 | which define the way the processes of the service are |
| | 78 | terminated, and in |
| | 79 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| | 80 | which configure resource control settings for the |
| | 81 | processes of the service.</para> |
| | 82 | |
| | 83 | <para>Unless <varname>DefaultDependencies=</varname> |
| | 84 | is set to <option>false</option>, service units will |
| | 85 | implicitly have dependencies of type |
| | 86 | <varname>Requires=</varname> and |
| | 87 | <varname>After=</varname> on |
| | 88 | <filename>basic.target</filename> as well as |
| | 89 | dependencies of type <varname>Conflicts=</varname> and |
| | 90 | <varname>Before=</varname> on |
| | 91 | <filename>shutdown.target</filename>. These ensure |
| | 92 | that normal service units pull in basic system |
| | 93 | initialization, and are terminated cleanly prior to |
| | 94 | system shutdown. Only services involved with early |
| | 95 | boot or late system shutdown should disable this |
| | 96 | option.</para> |
| | 97 | |
| | 98 | <para>If a service is requested under a certain name |
| | 99 | but no unit configuration file is found, systemd looks |
| | 100 | for a SysV init script by the same name (with the |
| | 101 | <filename>.service</filename> suffix removed) and |
| | 102 | dynamically creates a service unit from that |
| | 103 | script. This is useful for compatibility with |
| | 104 | SysV. Note that this compatibility is quite |
| | 105 | comprehensive but not 100%. For details about the |
| | 106 | incompatibilities, see the <ulink |
| | 107 | url="http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities">Incompatibilities |
| | 108 | with SysV</ulink> document. |
| | 109 | </para> |
| | 110 | </refsect1> |
| | 111 | |
| | 112 | <refsect1> |
| | 113 | <title>Options</title> |
| | 114 | |
| | 115 | <para>Service files must include a |
| | 116 | <literal>[Service]</literal> section, which carries |
| | 117 | information about the service and the process it |
| | 118 | supervises. A number of options that may be used in |
| | 119 | this section are shared with other unit types. These |
| | 120 | options are documented in |
| | 121 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 122 | and |
| | 123 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The |
| | 124 | options specific to the <literal>[Service]</literal> |
| | 125 | section of service units are the following:</para> |
| | 126 | |
| | 127 | <variablelist class='unit-directives'> |
| | 128 | <varlistentry> |
| | 129 | <term><varname>Type=</varname></term> |
| | 130 | |
| | 131 | <listitem><para>Configures the process |
| | 132 | start-up type for this service |
| | 133 | unit. One of <option>simple</option>, |
| | 134 | <option>forking</option>, |
| | 135 | <option>oneshot</option>, |
| | 136 | <option>dbus</option>, |
| | 137 | <option>notify</option> or |
| | 138 | <option>idle</option>.</para> |
| | 139 | |
| | 140 | <para>If set to |
| | 141 | <option>simple</option> (the default |
| | 142 | if neither |
| | 143 | <varname>Type=</varname> nor |
| | 144 | <varname>BusName=</varname>, but |
| | 145 | <varname>ExecStart=</varname> are |
| | 146 | specified), it is expected that the |
| | 147 | process configured with |
| | 148 | <varname>ExecStart=</varname> is the |
| | 149 | main process of the service. In this |
| | 150 | mode, if the process offers |
| | 151 | functionality to other processes on |
| | 152 | the system, its communication channels |
| | 153 | should be installed before the daemon |
| | 154 | is started up (e.g. sockets set up by |
| | 155 | systemd, via socket activation), as |
| | 156 | systemd will immediately proceed |
| | 157 | starting follow-up units.</para> |
| | 158 | |
| | 159 | <para>If set to |
| | 160 | <option>forking</option>, it is |
| | 161 | expected that the process configured |
| | 162 | with <varname>ExecStart=</varname> |
| | 163 | will call <function>fork()</function> |
| | 164 | as part of its start-up. The parent process is |
| | 165 | expected to exit when start-up is |
| | 166 | complete and all communication |
| | 167 | channels are set up. The child continues |
| | 168 | to run as the main daemon |
| | 169 | process. This is the behavior of |
| | 170 | traditional UNIX daemons. If this |
| | 171 | setting is used, it is recommended to |
| | 172 | also use the |
| | 173 | <varname>PIDFile=</varname> option, so |
| | 174 | that systemd can identify the main |
| | 175 | process of the daemon. systemd will |
| | 176 | proceed with starting follow-up units |
| | 177 | as soon as the parent process |
| | 178 | exits.</para> |
| | 179 | |
| | 180 | <para>Behavior of |
| | 181 | <option>oneshot</option> is similar to |
| | 182 | <option>simple</option>; however, it |
| | 183 | is expected that the process has to |
| | 184 | exit before systemd starts follow-up |
| | 185 | units. <varname>RemainAfterExit=</varname> |
| | 186 | is particularly useful for this type |
| | 187 | of service. This is the implied |
| | 188 | default if neither |
| | 189 | <varname>Type=</varname> or |
| | 190 | <varname>ExecStart=</varname> are |
| | 191 | specified.</para> |
| | 192 | |
| | 193 | <para>Behavior of |
| | 194 | <option>dbus</option> is similar to |
| | 195 | <option>simple</option>; however, it is |
| | 196 | expected that the daemon acquires a |
| | 197 | name on the D-Bus bus, as configured |
| | 198 | by |
| | 199 | <varname>BusName=</varname>. systemd |
| | 200 | will proceed with starting follow-up |
| | 201 | units after the D-Bus bus name has been |
| | 202 | acquired. Service units with this |
| | 203 | option configured implicitly gain |
| | 204 | dependencies on the |
| | 205 | <filename>dbus.socket</filename> |
| | 206 | unit. This type is the default if |
| | 207 | <varname>BusName=</varname> is |
| | 208 | specified.</para> |
| | 209 | |
| | 210 | <para>Behavior of |
| | 211 | <option>notify</option> is similar to |
| | 212 | <option>simple</option>; however, it is |
| | 213 | expected that the daemon sends a |
| | 214 | notification message via |
| | 215 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| | 216 | or an equivalent call when it has finished |
| | 217 | starting up. systemd will proceed with |
| | 218 | starting follow-up units after this |
| | 219 | notification message has been sent. If |
| | 220 | this option is used, |
| | 221 | <varname>NotifyAccess=</varname> (see |
| | 222 | below) should be set to open access to |
| | 223 | the notification socket provided by |
| | 224 | systemd. If |
| | 225 | <varname>NotifyAccess=</varname> is |
| | 226 | not set, it will be implicitly set to |
| | 227 | <option>main</option>. Note that |
| | 228 | currently |
| | 229 | <varname>Type=</varname><option>notify</option> |
| | 230 | will not work if used in combination with |
| | 231 | <varname>PrivateNetwork=</varname><option>yes</option>.</para> |
| | 232 | |
| | 233 | <para>Behavior of |
| | 234 | <option>idle</option> is very similar |
| | 235 | to <option>simple</option>; however, |
| | 236 | actual execution of the service |
| | 237 | binary is delayed until all jobs are |
| | 238 | dispatched. This may be used to avoid |
| | 239 | interleaving of output of shell |
| | 240 | services with the status output on the |
| | 241 | console.</para> |
| | 242 | </listitem> |
| | 243 | </varlistentry> |
| | 244 | |
| | 245 | <varlistentry> |
| | 246 | <term><varname>RemainAfterExit=</varname></term> |
| | 247 | |
| | 248 | <listitem><para>Takes a boolean value |
| | 249 | that specifies whether the service |
| | 250 | shall be considered active even when |
| | 251 | all its processes exited. Defaults to |
| | 252 | <option>no</option>.</para> |
| | 253 | </listitem> |
| | 254 | </varlistentry> |
| | 255 | |
| | 256 | <varlistentry> |
| | 257 | <term><varname>GuessMainPID=</varname></term> |
| | 258 | |
| | 259 | <listitem><para>Takes a boolean value |
| | 260 | that specifies whether systemd should |
| | 261 | try to guess the main PID of a service |
| | 262 | if it cannot be determined |
| | 263 | reliably. This option is ignored |
| | 264 | unless <option>Type=forking</option> |
| | 265 | is set and <option>PIDFile=</option> |
| | 266 | is unset because for the other types |
| | 267 | or with an explicitly configured PID |
| | 268 | file, the main PID is always known. The |
| | 269 | guessing algorithm might come to |
| | 270 | incorrect conclusions if a daemon |
| | 271 | consists of more than one process. If |
| | 272 | the main PID cannot be determined, |
| | 273 | failure detection and automatic |
| | 274 | restarting of a service will not work |
| | 275 | reliably. Defaults to |
| | 276 | <option>yes</option>.</para> |
| | 277 | </listitem> |
| | 278 | </varlistentry> |
| | 279 | |
| | 280 | <varlistentry> |
| | 281 | <term><varname>PIDFile=</varname></term> |
| | 282 | |
| | 283 | <listitem><para>Takes an absolute file |
| | 284 | name pointing to the PID file of this |
| | 285 | daemon. Use of this option is |
| | 286 | recommended for services where |
| | 287 | <varname>Type=</varname> is set to |
| | 288 | <option>forking</option>. systemd will |
| | 289 | read the PID of the main process of |
| | 290 | the daemon after start-up of the |
| | 291 | service. systemd will not write to the |
| | 292 | file configured here.</para> |
| | 293 | </listitem> |
| | 294 | </varlistentry> |
| | 295 | |
| | 296 | <varlistentry> |
| | 297 | <term><varname>BusName=</varname></term> |
| | 298 | |
| | 299 | <listitem><para>Takes a D-Bus bus |
| | 300 | name that this service is reachable |
| | 301 | as. This option is mandatory for |
| | 302 | services where |
| | 303 | <varname>Type=</varname> is set to |
| | 304 | <option>dbus</option>.</para> |
| | 305 | </listitem> |
| | 306 | </varlistentry> |
| | 307 | |
| | 308 | <varlistentry> |
| | 309 | <term><varname>BusPolicy=</varname></term> |
| | 310 | |
| | 311 | <listitem><para>If specified, a custom |
| | 312 | <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink> |
| | 313 | endpoint will be created and installed as the |
| | 314 | default bus node for the service. Such a custom |
| | 315 | endpoint can hold an own set of policy rules |
| | 316 | that are enforced on top of the bus-wide ones. |
| | 317 | The custom endpoint is named after the service |
| | 318 | it was created for, and its node will be |
| | 319 | bind-mounted over the default bus node |
| | 320 | location, so the service can only access the |
| | 321 | bus through its own endpoint. Note that custom |
| | 322 | bus endpoints default to a 'deny all' policy. |
| | 323 | Hence, if at least one |
| | 324 | <varname>BusPolicy=</varname> directive is |
| | 325 | given, you have to make sure to add explicit |
| | 326 | rules for everything the service should be able |
| | 327 | to do.</para> |
| | 328 | <para>The value of this directive is comprised |
| | 329 | of two parts; the bus name, and a verb to |
| | 330 | specify to granted access, which is one of |
| | 331 | <option>see</option>, |
| | 332 | <option>talk</option>, or |
| | 333 | <option>own</option>. |
| | 334 | <option>talk</option> implies |
| | 335 | <option>see</option>, and <option>own</option> |
| | 336 | implies both <option>talk</option> and |
| | 337 | <option>see</option>. |
| | 338 | If multiple access levels are specified for the |
| | 339 | same bus name, the most powerful one takes |
| | 340 | effect. |
| | 341 | </para> |
| | 342 | <para>Examples:</para> |
| | 343 | <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting> |
| | 344 | <programlisting>BusPolicy=org.foo.bar see</programlisting> |
| | 345 | <para>This option is only available on kdbus enabled systems.</para> |
| | 346 | </listitem> |
| | 347 | </varlistentry> |
| | 348 | |
| | 349 | <varlistentry> |
| | 350 | <term><varname>ExecStart=</varname></term> |
| | 351 | <listitem><para>Commands with their |
| | 352 | arguments that are executed when this |
| | 353 | service is started. The value is split |
| | 354 | into zero or more command lines is |
| | 355 | according to the rules described below |
| | 356 | (see section "Command Lines" below). |
| | 357 | </para> |
| | 358 | |
| | 359 | <para>When <varname>Type</varname> is |
| | 360 | not <option>oneshot</option>, only one |
| | 361 | command may and must be given. When |
| | 362 | <varname>Type=oneshot</varname> is |
| | 363 | used, zero or more commands may be |
| | 364 | specified. This can be specified by |
| | 365 | providing multiple command lines in |
| | 366 | the same directive, or alternatively, |
| | 367 | this directive may be specified more |
| | 368 | than once with the same effect. If the |
| | 369 | empty string is assigned to this |
| | 370 | option, the list of commands to start |
| | 371 | is reset, prior assignments of this |
| | 372 | option will have no effect. If no |
| | 373 | <varname>ExecStart=</varname> is |
| | 374 | specified, then the service must have |
| | 375 | <varname>RemainAfterExit=yes</varname> |
| | 376 | set.</para> |
| | 377 | |
| | 378 | <para>For each of the specified |
| | 379 | commands, the first argument must be |
| | 380 | an absolute path to an executable. |
| | 381 | Optionally, if this file name is |
| | 382 | prefixed with <literal>@</literal>, |
| | 383 | the second token will be passed as |
| | 384 | <literal>argv[0]</literal> to the |
| | 385 | executed process, followed by the |
| | 386 | further arguments specified. If the |
| | 387 | absolute filename is prefixed with |
| | 388 | <literal>-</literal>, an exit code of |
| | 389 | the command normally considered a |
| | 390 | failure (i.e. non-zero exit status or |
| | 391 | abnormal exit due to signal) is |
| | 392 | ignored and considered success. If |
| | 393 | both <literal>-</literal> and |
| | 394 | <literal>@</literal> are used, they |
| | 395 | can appear in either order.</para> |
| | 396 | |
| | 397 | <para>If more than one command is |
| | 398 | specified, the commands are invoked |
| | 399 | sequentially in the order they appear |
| | 400 | in the unit file. If one of the |
| | 401 | commands fails (and is not prefixed |
| | 402 | with <literal>-</literal>), other |
| | 403 | lines are not executed, and the unit |
| | 404 | is considered failed.</para> |
| | 405 | |
| | 406 | <para>Unless |
| | 407 | <varname>Type=forking</varname> is |
| | 408 | set, the process started via this |
| | 409 | command line will be considered the |
| | 410 | main process of the daemon.</para> |
| | 411 | |
| | 412 | </listitem> |
| | 413 | </varlistentry> |
| | 414 | |
| | 415 | <varlistentry> |
| | 416 | <term><varname>ExecStartPre=</varname></term> |
| | 417 | <term><varname>ExecStartPost=</varname></term> |
| | 418 | <listitem><para>Additional commands |
| | 419 | that are executed before or after |
| | 420 | the command in |
| | 421 | <varname>ExecStart=</varname>, respectively. |
| | 422 | Syntax is the same as for |
| | 423 | <varname>ExecStart=</varname>, except |
| | 424 | that multiple command lines are allowed |
| | 425 | and the commands are executed one |
| | 426 | after the other, serially.</para> |
| | 427 | |
| | 428 | <para>If any of those commands (not |
| | 429 | prefixed with <literal>-</literal>) |
| | 430 | fail, the rest are not executed and |
| | 431 | the unit is considered failed.</para> |
| | 432 | </listitem> |
| | 433 | </varlistentry> |
| | 434 | |
| | 435 | <varlistentry> |
| | 436 | <term><varname>ExecReload=</varname></term> |
| | 437 | <listitem><para>Commands to execute to |
| | 438 | trigger a configuration reload in the |
| | 439 | service. This argument takes multiple |
| | 440 | command lines, following the same |
| | 441 | scheme as described for |
| | 442 | <varname>ExecStart=</varname> |
| | 443 | above. Use of this setting is |
| | 444 | optional. Specifier and environment |
| | 445 | variable substitution is supported |
| | 446 | here following the same scheme as for |
| | 447 | <varname>ExecStart=</varname>.</para> |
| | 448 | |
| | 449 | <para>One additional, special |
| | 450 | environment variable is set: if known, |
| | 451 | <varname>$MAINPID</varname> is set to |
| | 452 | the main process of the daemon, and |
| | 453 | may be used for command lines like the |
| | 454 | following:</para> |
| | 455 | |
| | 456 | <programlisting>/bin/kill -HUP $MAINPID</programlisting> |
| | 457 | |
| | 458 | <para>Note however that reloading a |
| | 459 | daemon by sending a signal (as with |
| | 460 | the example line above) is usually not |
| | 461 | a good choice, because this is an |
| | 462 | asynchronous operation and hence not |
| | 463 | suitable to order reloads of multiple |
| | 464 | services against each other. It is |
| | 465 | strongly recommended to set |
| | 466 | <varname>ExecReload=</varname> to a |
| | 467 | command that not only triggers a |
| | 468 | configuration reload of the daemon, |
| | 469 | but also synchronously waits for it to |
| | 470 | complete.</para> |
| | 471 | </listitem> |
| | 472 | </varlistentry> |
| | 473 | |
| | 474 | <varlistentry> |
| | 475 | <term><varname>ExecStop=</varname></term> |
| | 476 | <listitem><para>Commands to execute to |
| | 477 | stop the service started via |
| | 478 | <varname>ExecStart=</varname>. This |
| | 479 | argument takes multiple command lines, |
| | 480 | following the same scheme as described |
| | 481 | for <varname>ExecStart=</varname> |
| | 482 | above. Use of this setting is |
| | 483 | optional. After the commands configured |
| | 484 | in this option are run, all processes |
| | 485 | remaining for a service are |
| | 486 | terminated according to the |
| | 487 | <varname>KillMode=</varname> setting |
| | 488 | (see |
| | 489 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If |
| | 490 | this option is not specified, the |
| | 491 | process is terminated immediately when |
| | 492 | service stop is requested. Specifier |
| | 493 | and environment variable substitution |
| | 494 | is supported (including |
| | 495 | <varname>$MAINPID</varname>, see |
| | 496 | above).</para></listitem> |
| | 497 | </varlistentry> |
| | 498 | |
| | 499 | <varlistentry> |
| | 500 | <term><varname>ExecStopPost=</varname></term> |
| | 501 | <listitem><para>Additional commands |
| | 502 | that are executed after the service |
| | 503 | was stopped. This includes cases where |
| | 504 | the commands configured in |
| | 505 | <varname>ExecStop=</varname> were used, |
| | 506 | where the service does not have any |
| | 507 | <varname>ExecStop=</varname> defined, or |
| | 508 | where the service exited unexpectedly. This |
| | 509 | argument takes multiple command lines, |
| | 510 | following the same scheme as described |
| | 511 | for <varname>ExecStart</varname>. Use |
| | 512 | of these settings is |
| | 513 | optional. Specifier and environment |
| | 514 | variable substitution is |
| | 515 | supported.</para></listitem> |
| | 516 | </varlistentry> |
| | 517 | |
| | 518 | <varlistentry> |
| | 519 | <term><varname>RestartSec=</varname></term> |
| | 520 | <listitem><para>Configures the time to |
| | 521 | sleep before restarting a service (as |
| | 522 | configured with |
| | 523 | <varname>Restart=</varname>). Takes a |
| | 524 | unit-less value in seconds, or a time |
| | 525 | span value such as "5min |
| | 526 | 20s". Defaults to |
| | 527 | 100ms.</para></listitem> |
| | 528 | </varlistentry> |
| | 529 | |
| | 530 | <varlistentry> |
| | 531 | <term><varname>TimeoutStartSec=</varname></term> |
| | 532 | <listitem><para>Configures the time to |
| | 533 | wait for start-up. If a |
| | 534 | daemon service does not signal |
| | 535 | start-up completion within the |
| | 536 | configured time, the service will be |
| | 537 | considered failed and will be shut |
| | 538 | down again. |
| | 539 | Takes a unit-less value in seconds, or a |
| | 540 | time span value such as "5min |
| | 541 | 20s". Pass <literal>0</literal> to |
| | 542 | disable the timeout logic. Defaults to |
| | 543 | <varname>DefaultTimeoutStartSec=</varname> from |
| | 544 | the manager configuration file, except |
| | 545 | when <varname>Type=oneshot</varname> is |
| | 546 | used, in which case the timeout |
| | 547 | is disabled by default |
| | 548 | (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
| | 549 | </para></listitem> |
| | 550 | </varlistentry> |
| | 551 | |
| | 552 | <varlistentry> |
| | 553 | <term><varname>TimeoutStopSec=</varname></term> |
| | 554 | <listitem><para>Configures the time to |
| | 555 | wait for stop. If a service is asked |
| | 556 | to stop, but does not terminate in the |
| | 557 | specified time, it will be terminated |
| | 558 | forcibly via <constant>SIGTERM</constant>, |
| | 559 | and after another timeout of equal duration |
| | 560 | with <constant>SIGKILL</constant> (see |
| | 561 | <varname>KillMode=</varname> |
| | 562 | in <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
| | 563 | Takes a unit-less value in seconds, or a |
| | 564 | time span value such as "5min |
| | 565 | 20s". Pass <literal>0</literal> to disable |
| | 566 | the timeout logic. Defaults to |
| | 567 | <varname>DefaultTimeoutStopSec=</varname> from the |
| | 568 | manager configuration file |
| | 569 | (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). |
| | 570 | </para></listitem> |
| | 571 | </varlistentry> |
| | 572 | |
| | 573 | <varlistentry> |
| | 574 | <term><varname>TimeoutSec=</varname></term> |
| | 575 | <listitem><para>A shorthand for configuring |
| | 576 | both <varname>TimeoutStartSec=</varname> |
| | 577 | and <varname>TimeoutStopSec=</varname> |
| | 578 | to the specified value. |
| | 579 | </para></listitem> |
| | 580 | </varlistentry> |
| | 581 | |
| | 582 | <varlistentry> |
| | 583 | <term><varname>WatchdogSec=</varname></term> |
| | 584 | <listitem><para>Configures the |
| | 585 | watchdog timeout for a service. The |
| | 586 | watchdog is activated when the start-up is |
| | 587 | completed. The service must call |
| | 588 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| | 589 | regularly with <literal>WATCHDOG=1</literal> |
| | 590 | (i.e. the "keep-alive ping"). If the time |
| | 591 | between two such calls is larger than |
| | 592 | the configured time, then the service |
| | 593 | is placed in a failed state and it will |
| | 594 | be terminated with <varname>SIGABRT</varname>. |
| | 595 | By setting <varname>Restart=</varname> to |
| | 596 | <option>on-failure</option> or |
| | 597 | <option>always</option>, the service |
| | 598 | will be automatically restarted. The |
| | 599 | time configured here will be passed to |
| | 600 | the executed service process in the |
| | 601 | <varname>WATCHDOG_USEC=</varname> |
| | 602 | environment variable. This allows |
| | 603 | daemons to automatically enable the |
| | 604 | keep-alive pinging logic if watchdog |
| | 605 | support is enabled for the service. If |
| | 606 | this option is used, |
| | 607 | <varname>NotifyAccess=</varname> (see |
| | 608 | below) should be set to open access to |
| | 609 | the notification socket provided by |
| | 610 | systemd. If |
| | 611 | <varname>NotifyAccess=</varname> is |
| | 612 | not set, it will be implicitly set to |
| | 613 | <option>main</option>. Defaults to 0, |
| | 614 | which disables this |
| | 615 | feature.</para></listitem> |
| | 616 | </varlistentry> |
| | 617 | |
| | 618 | <varlistentry> |
| | 619 | <term><varname>Restart=</varname></term> |
| | 620 | <listitem><para>Configures whether the |
| | 621 | service shall be restarted when the |
| | 622 | service process exits, is killed, |
| | 623 | or a timeout is reached. The service |
| | 624 | process may be the main service |
| | 625 | process, but it may also be one of the |
| | 626 | processes specified with |
| | 627 | <varname>ExecStartPre=</varname>, |
| | 628 | <varname>ExecStartPost=</varname>, |
| | 629 | <varname>ExecStop=</varname>, |
| | 630 | <varname>ExecStopPost=</varname>, or |
| | 631 | <varname>ExecReload=</varname>. |
| | 632 | When the death of the process is a |
| | 633 | result of systemd operation (e.g. service |
| | 634 | stop or restart), the service will not be |
| | 635 | restarted. Timeouts include missing |
| | 636 | the watchdog "keep-alive ping" |
| | 637 | deadline and a service start, reload, |
| | 638 | and stop operation timeouts.</para> |
| | 639 | |
| | 640 | <para>Takes one of |
| | 641 | <option>no</option>, |
| | 642 | <option>on-success</option>, |
| | 643 | <option>on-failure</option>, |
| | 644 | <option>on-abnormal</option>, |
| | 645 | <option>on-watchdog</option>, |
| | 646 | <option>on-abort</option>, or |
| | 647 | <option>always</option>. If set to |
| | 648 | <option>no</option> (the default), the |
| | 649 | service will not be restarted. If set |
| | 650 | to <option>on-success</option>, it |
| | 651 | will be restarted only when the |
| | 652 | service process exits cleanly. In |
| | 653 | this context, a clean exit means an |
| | 654 | exit code of 0, or one of the signals |
| | 655 | <constant>SIGHUP</constant>, |
| | 656 | <constant>SIGINT</constant>, |
| | 657 | <constant>SIGTERM</constant> or |
| | 658 | <constant>SIGPIPE</constant>, and |
| | 659 | additionally, exit statuses and |
| | 660 | signals specified in |
| | 661 | <varname>SuccessExitStatus=</varname>. |
| | 662 | If set to <option>on-failure</option>, |
| | 663 | the service will be restarted when the |
| | 664 | process exits with a non-zero exit |
| | 665 | code, is terminated by a signal |
| | 666 | (including on core dump, but excluding |
| | 667 | the aforementiond four signals), when |
| | 668 | an operation (such as service reload) |
| | 669 | times out, and when the configured |
| | 670 | watchdog timeout is triggered. If set |
| | 671 | to <option>on-abnormal</option>, the |
| | 672 | service will be restarted when the |
| | 673 | process is terminated by a signal |
| | 674 | (including on core dump, excluding the |
| | 675 | aforementioned four signals), when an |
| | 676 | operation times out, or when the |
| | 677 | watchdog timeout is triggered. If set |
| | 678 | to <option>on-abort</option>, the |
| | 679 | service will be restarted only if the |
| | 680 | service process exits due to an |
| | 681 | uncaught signal not specified as a |
| | 682 | clean exit status. If set to |
| | 683 | <option>on-watchdog</option>, the |
| | 684 | service will be restarted only if the |
| | 685 | watchdog timeout for the service |
| | 686 | expires. If set to |
| | 687 | <option>always</option>, the service |
| | 688 | will be restarted regardless of |
| | 689 | whether it exited cleanly or not, got |
| | 690 | terminated abnormally by a signal, or |
| | 691 | hit a timeout.</para> |
| | 692 | |
| | 693 | <table> |
| | 694 | <title>Exit causes and the effect of the <varname>Restart=</varname> settings on them</title> |
| | 695 | |
| | 696 | <tgroup cols='2'> |
| | 697 | <colspec colname='path' /> |
| | 698 | <colspec colname='expl' /> |
| | 699 | <thead> |
| | 700 | <row> |
| | 701 | <entry>Restart settings/Exit causes</entry> |
| | 702 | <entry><option>no</option></entry> |
| | 703 | <entry><option>always</option></entry> |
| | 704 | <entry><option>on-success</option></entry> |
| | 705 | <entry><option>on-failure</option></entry> |
| | 706 | <entry><option>on-abnormal</option></entry> |
| | 707 | <entry><option>on-abort</option></entry> |
| | 708 | <entry><option>on-watchdog</option></entry> |
| | 709 | </row> |
| | 710 | </thead> |
| | 711 | <tbody> |
| | 712 | <row> |
| | 713 | <entry>Clean exit code or signal</entry> |
| | 714 | <entry/> |
| | 715 | <entry>X</entry> |
| | 716 | <entry>X</entry> |
| | 717 | <entry/> |
| | 718 | <entry/> |
| | 719 | <entry/> |
| | 720 | <entry/> |
| | 721 | </row> |
| | 722 | <row> |
| | 723 | <entry>Unclean exit code</entry> |
| | 724 | <entry/> |
| | 725 | <entry>X</entry> |
| | 726 | <entry/> |
| | 727 | <entry>X</entry> |
| | 728 | <entry/> |
| | 729 | <entry/> |
| | 730 | <entry/> |
| | 731 | </row> |
| | 732 | <row> |
| | 733 | <entry>Unclean signal</entry> |
| | 734 | <entry/> |
| | 735 | <entry>X</entry> |
| | 736 | <entry/> |
| | 737 | <entry>X</entry> |
| | 738 | <entry>X</entry> |
| | 739 | <entry>X</entry> |
| | 740 | <entry/> |
| | 741 | </row> |
| | 742 | <row> |
| | 743 | <entry>Timeout</entry> |
| | 744 | <entry/> |
| | 745 | <entry>X</entry> |
| | 746 | <entry/> |
| | 747 | <entry>X</entry> |
| | 748 | <entry>X</entry> |
| | 749 | <entry/> |
| | 750 | <entry/> |
| | 751 | </row> |
| | 752 | <row> |
| | 753 | <entry>Watchdog</entry> |
| | 754 | <entry/> |
| | 755 | <entry>X</entry> |
| | 756 | <entry/> |
| | 757 | <entry>X</entry> |
| | 758 | <entry>X</entry> |
| | 759 | <entry/> |
| | 760 | <entry>X</entry> |
| | 761 | </row> |
| | 762 | </tbody> |
| | 763 | </tgroup> |
| | 764 | </table> |
| | 765 | |
| | 766 | <para>As exceptions to the setting |
| | 767 | above the service will not be |
| | 768 | restarted if the exit code or signal |
| | 769 | is specified in |
| | 770 | <varname>RestartPreventExitStatus=</varname> |
| | 771 | (see below). Also, the services will |
| | 772 | always be restarted if the exit code |
| | 773 | or signal is specified in |
| | 774 | <varname>RestartForceExitStatus=</varname> |
| | 775 | (see below).</para> |
| | 776 | |
| | 777 | <para>Setting this to |
| | 778 | <option>on-failure</option> is the |
| | 779 | recommended choice for long-running |
| | 780 | services, in order to increase |
| | 781 | reliability by attempting automatic |
| | 782 | recovery from errors. For services |
| | 783 | that shall be able to terminate on |
| | 784 | their own choice (and avoid |
| | 785 | immediate restarting), |
| | 786 | <option>on-abnormal</option> is an |
| | 787 | alternative choice.</para> |
| | 788 | </listitem> |
| | 789 | </varlistentry> |
| | 790 | |
| | 791 | <varlistentry> |
| | 792 | <term><varname>SuccessExitStatus=</varname></term> |
| | 793 | <listitem><para>Takes a list of exit |
| | 794 | status definitions that when returned |
| | 795 | by the main service process will be |
| | 796 | considered successful termination, in |
| | 797 | addition to the normal successful exit |
| | 798 | code 0 and the signals <constant>SIGHUP</constant>, <constant>SIGINT</constant>, |
| | 799 | <constant>SIGTERM</constant>, and <constant>SIGPIPE</constant>. Exit status |
| | 800 | definitions can either be numeric exit |
| | 801 | codes or termination signal names, |
| | 802 | separated by spaces. For example: |
| | 803 | <programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting> |
| | 804 | ensures that exit codes 1, 2, 8 and |
| | 805 | the termination signal |
| | 806 | <constant>SIGKILL</constant> are |
| | 807 | considered clean service terminations. |
| | 808 | </para> |
| | 809 | |
| | 810 | <para>Note that if a process has a |
| | 811 | signal handler installed and exits by |
| | 812 | calling |
| | 813 | <citerefentry><refentrytitle>_exit</refentrytitle><manvolnum>2</manvolnum></citerefentry> |
| | 814 | in response to a signal, the |
| | 815 | information about the signal is lost. |
| | 816 | Programs should instead perform cleanup and kill themselves with the same signal instead. See |
| | 817 | <ulink url="http://www.cons.org/cracauer/sigint.html">Proper handling of SIGINT/SIGQUIT — How to be a proper program</ulink>.</para> |
| | 818 | |
| | 819 | <para>This option may appear more than once, |
| | 820 | in which case the list of successful |
| | 821 | exit statuses is merged. If the empty |
| | 822 | string is assigned to this option, the |
| | 823 | list is reset, all prior assignments |
| | 824 | of this option will have no |
| | 825 | effect.</para></listitem> |
| | 826 | </varlistentry> |
| | 827 | |
| | 828 | <varlistentry> |
| | 829 | <term><varname>RestartPreventExitStatus=</varname></term> |
| | 830 | <listitem><para>Takes a list of exit |
| | 831 | status definitions that when returned |
| | 832 | by the main service process will |
| | 833 | prevent automatic service restarts, |
| | 834 | regardless of the restart setting |
| | 835 | configured with |
| | 836 | <varname>Restart=</varname>. Exit |
| | 837 | status definitions can either be |
| | 838 | numeric exit codes or termination |
| | 839 | signal names, and are separated by |
| | 840 | spaces. Defaults to the empty list, so |
| | 841 | that, by default, no exit status is |
| | 842 | excluded from the configured restart |
| | 843 | logic. For example: |
| | 844 | <programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting> ensures that exit |
| | 845 | codes 1 and 6 and the termination |
| | 846 | signal <constant>SIGABRT</constant> will |
| | 847 | not result in automatic service |
| | 848 | restarting. This |
| | 849 | option may appear more than once, in |
| | 850 | which case the list of restart-preventing |
| | 851 | statuses is merged. If the empty |
| | 852 | string is assigned to this option, the |
| | 853 | list is reset and all prior assignments |
| | 854 | of this option will have no |
| | 855 | effect.</para></listitem> |
| | 856 | </varlistentry> |
| | 857 | |
| | 858 | <varlistentry> |
| | 859 | <term><varname>RestartForceExitStatus=</varname></term> |
| | 860 | <listitem><para>Takes a list of exit |
| | 861 | status definitions that when returned |
| | 862 | by the main service process will force |
| | 863 | automatic service restarts, regardless |
| | 864 | of the restart setting configured with |
| | 865 | <varname>Restart=</varname>. The |
| | 866 | argument format is similar to |
| | 867 | <varname>RestartPreventExitStatus=</varname>.</para></listitem> |
| | 868 | </varlistentry> |
| | 869 | |
| | 870 | <varlistentry> |
| | 871 | <term><varname>PermissionsStartOnly=</varname></term> |
| | 872 | <listitem><para>Takes a boolean |
| | 873 | argument. If true, the permission-related |
| | 874 | execution options, as |
| | 875 | configured with |
| | 876 | <varname>User=</varname> and similar |
| | 877 | options (see |
| | 878 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 879 | for more information), are only applied |
| | 880 | to the process started with |
| | 881 | <varname>ExecStart=</varname>, and not |
| | 882 | to the various other |
| | 883 | <varname>ExecStartPre=</varname>, |
| | 884 | <varname>ExecStartPost=</varname>, |
| | 885 | <varname>ExecReload=</varname>, |
| | 886 | <varname>ExecStop=</varname>, and |
| | 887 | <varname>ExecStopPost=</varname> |
| | 888 | commands. If false, the setting is |
| | 889 | applied to all configured commands the |
| | 890 | same way. Defaults to |
| | 891 | false.</para></listitem> |
| | 892 | </varlistentry> |
| | 893 | |
| | 894 | <varlistentry> |
| | 895 | <term><varname>RootDirectoryStartOnly=</varname></term> |
| | 896 | <listitem><para>Takes a boolean |
| | 897 | argument. If true, the root directory, |
| | 898 | as configured with the |
| | 899 | <varname>RootDirectory=</varname> |
| | 900 | option (see |
| | 901 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 902 | for more information), is only applied |
| | 903 | to the process started with |
| | 904 | <varname>ExecStart=</varname>, and not |
| | 905 | to the various other |
| | 906 | <varname>ExecStartPre=</varname>, |
| | 907 | <varname>ExecStartPost=</varname>, |
| | 908 | <varname>ExecReload=</varname>, |
| | 909 | <varname>ExecStop=</varname>, and |
| | 910 | <varname>ExecStopPost=</varname> |
| | 911 | commands. If false, the setting is |
| | 912 | applied to all configured commands the |
| | 913 | same way. Defaults to |
| | 914 | false.</para></listitem> |
| | 915 | </varlistentry> |
| | 916 | |
| | 917 | <varlistentry> |
| | 918 | <term><varname>NonBlocking=</varname></term> |
| | 919 | <listitem><para>Set the |
| | 920 | <constant>O_NONBLOCK</constant> flag |
| | 921 | for all file descriptors passed via |
| | 922 | socket-based activation. If true, all |
| | 923 | file descriptors >= 3 (i.e. all except |
| | 924 | stdin, stdout, and stderr) will have |
| | 925 | the <constant>O_NONBLOCK</constant> flag |
| | 926 | set and hence are in |
| | 927 | non-blocking mode. This option is only |
| | 928 | useful in conjunction with a socket |
| | 929 | unit, as described in |
| | 930 | <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Defaults |
| | 931 | to false.</para></listitem> |
| | 932 | </varlistentry> |
| | 933 | |
| | 934 | <varlistentry> |
| | 935 | <term><varname>NotifyAccess=</varname></term> |
| | 936 | <listitem><para>Controls access to the |
| | 937 | service status notification socket, as |
| | 938 | accessible via the |
| | 939 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| | 940 | call. Takes one of |
| | 941 | <option>none</option> (the default), |
| | 942 | <option>main</option> or |
| | 943 | <option>all</option>. If |
| | 944 | <option>none</option>, no daemon status |
| | 945 | updates are accepted from the service |
| | 946 | processes, all status update messages |
| | 947 | are ignored. If <option>main</option>, |
| | 948 | only service updates sent from the |
| | 949 | main process of the service are |
| | 950 | accepted. If <option>all</option>, all |
| | 951 | services updates from all members of |
| | 952 | the service's control group are |
| | 953 | accepted. This option should be set to |
| | 954 | open access to the notification socket |
| | 955 | when using |
| | 956 | <varname>Type=notify</varname> or |
| | 957 | <varname>WatchdogSec=</varname> (see |
| | 958 | above). If those options are used but |
| | 959 | <varname>NotifyAccess=</varname> is not |
| | 960 | configured, it will be implicitly set |
| | 961 | to |
| | 962 | <option>main</option>.</para></listitem> |
| | 963 | </varlistentry> |
| | 964 | |
| | 965 | <varlistentry> |
| | 966 | <term><varname>Sockets=</varname></term> |
| | 967 | <listitem><para>Specifies the name of |
| | 968 | the socket units this service shall |
| | 969 | inherit socket file descriptors |
| | 970 | from when the service is |
| | 971 | started. Normally it should not be |
| | 972 | necessary to use this setting as all |
| | 973 | socket file descriptors whose unit |
| | 974 | shares the same name as the service |
| | 975 | (subject to the different unit name |
| | 976 | suffix of course) are passed to the |
| | 977 | spawned process.</para> |
| | 978 | |
| | 979 | <para>Note that the same socket file |
| | 980 | descriptors may be passed to multiple |
| | 981 | processes simultaneously. Also note |
| | 982 | that a different service may be |
| | 983 | activated on incoming socket traffic |
| | 984 | than the one which is ultimately |
| | 985 | configured to inherit the socket file |
| | 986 | descriptors. Or in other words: the |
| | 987 | <varname>Service=</varname> setting of |
| | 988 | <filename>.socket</filename> units |
| | 989 | does not have to match the inverse of |
| | 990 | the <varname>Sockets=</varname> |
| | 991 | setting of the |
| | 992 | <filename>.service</filename> it |
| | 993 | refers to.</para> |
| | 994 | |
| | 995 | <para>This option may appear more than |
| | 996 | once, in which case the list of socket |
| | 997 | units is merged. If the empty string |
| | 998 | is assigned to this option, the list of |
| | 999 | sockets is reset, and all prior uses of |
| | 1000 | this setting will have no |
| | 1001 | effect.</para></listitem> |
| | 1002 | </varlistentry> |
| | 1003 | |
| | 1004 | <varlistentry> |
| | 1005 | <term><varname>StartLimitInterval=</varname></term> |
| | 1006 | <term><varname>StartLimitBurst=</varname></term> |
| | 1007 | |
| | 1008 | <listitem><para>Configure service |
| | 1009 | start rate limiting. By default, |
| | 1010 | services which are started more |
| | 1011 | than 5 times within 10 seconds are not |
| | 1012 | permitted to start any more times |
| | 1013 | until the 10 second interval ends. With |
| | 1014 | these two options, this rate limiting |
| | 1015 | may be modified. Use |
| | 1016 | <varname>StartLimitInterval=</varname> |
| | 1017 | to configure the checking interval (defaults to |
| | 1018 | <varname>DefaultStartLimitInterval=</varname> in |
| | 1019 | manager configuration file, set to 0 to disable |
| | 1020 | any kind of rate limiting). Use |
| | 1021 | <varname>StartLimitBurst=</varname> to |
| | 1022 | configure how many starts per interval |
| | 1023 | are allowed (defaults to |
| | 1024 | <varname>DefaultStartLimitBurst=</varname> in |
| | 1025 | manager configuration file). These |
| | 1026 | configuration options are particularly |
| | 1027 | useful in conjunction with |
| | 1028 | <varname>Restart=</varname>; however, |
| | 1029 | they apply to all kinds of starts |
| | 1030 | (including manual), not just those |
| | 1031 | triggered by the |
| | 1032 | <varname>Restart=</varname> logic. |
| | 1033 | Note that units which are configured |
| | 1034 | for <varname>Restart=</varname> and |
| | 1035 | which reach the start limit are not |
| | 1036 | attempted to be restarted anymore; |
| | 1037 | however, they may still be restarted |
| | 1038 | manually at a later point, from which |
| | 1039 | point on, the restart logic is again |
| | 1040 | activated. Note that |
| | 1041 | <command>systemctl |
| | 1042 | reset-failed</command> will cause the |
| | 1043 | restart rate counter for a service to |
| | 1044 | be flushed, which is useful if the |
| | 1045 | administrator wants to manually start |
| | 1046 | a service and the start limit |
| | 1047 | interferes with |
| | 1048 | that.</para></listitem> |
| | 1049 | </varlistentry> |
| | 1050 | |
| | 1051 | <varlistentry> |
| | 1052 | <term><varname>StartLimitAction=</varname></term> |
| | 1053 | |
| | 1054 | <listitem><para>Configure the action |
| | 1055 | to take if the rate limit configured |
| | 1056 | with |
| | 1057 | <varname>StartLimitInterval=</varname> |
| | 1058 | and |
| | 1059 | <varname>StartLimitBurst=</varname> is |
| | 1060 | hit. Takes one of |
| | 1061 | <option>none</option>, |
| | 1062 | <option>reboot</option>, |
| | 1063 | <option>reboot-force</option>, |
| | 1064 | <option>reboot-immediate</option>, |
| | 1065 | <option>poweroff</option>, |
| | 1066 | <option>poweroff-force</option> or |
| | 1067 | <option>poweroff-immediate</option>. If |
| | 1068 | <option>none</option> is set, hitting |
| | 1069 | the rate limit will trigger no action |
| | 1070 | besides that the start will not be |
| | 1071 | permitted. <option>reboot</option> |
| | 1072 | causes a reboot following the normal |
| | 1073 | shutdown procedure (i.e. equivalent to |
| | 1074 | <command>systemctl reboot</command>). |
| | 1075 | <option>reboot-force</option> causes a |
| | 1076 | forced reboot which will terminate all |
| | 1077 | processes forcibly but should cause no |
| | 1078 | dirty file systems on reboot |
| | 1079 | (i.e. equivalent to <command>systemctl |
| | 1080 | reboot -f</command>) and |
| | 1081 | <option>reboot-immediate</option> |
| | 1082 | causes immediate execution of the |
| | 1083 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> |
| | 1084 | system call, which might result in |
| | 1085 | data loss. Similar, |
| | 1086 | <option>poweroff</option>, |
| | 1087 | <option>poweroff-force</option>, |
| | 1088 | <option>poweroff-immediate</option> |
| | 1089 | have the effect of powering down the |
| | 1090 | system with similar |
| | 1091 | semantics. Defaults to |
| | 1092 | <option>none</option>.</para></listitem> |
| | 1093 | </varlistentry> |
| | 1094 | |
| | 1095 | <varlistentry> |
| | 1096 | <term><varname>FailureAction=</varname></term> |
| | 1097 | <listitem><para>Configure the action |
| | 1098 | to take when the service enters a failed |
| | 1099 | state. Takes the same values as |
| | 1100 | <varname>StartLimitAction=</varname> |
| | 1101 | and executes the same actions. |
| | 1102 | Defaults to <option>none</option>. |
| | 1103 | </para></listitem> |
| | 1104 | </varlistentry> |
| | 1105 | |
| | 1106 | <varlistentry> |
| | 1107 | <term><varname>RebootArgument=</varname></term> |
| | 1108 | <listitem><para>Configure the optional |
| | 1109 | argument for the |
| | 1110 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> |
| | 1111 | system call if |
| | 1112 | <varname>StartLimitAction=</varname> |
| | 1113 | or <varname>FailureAction=</varname> |
| | 1114 | is a reboot action. This works just |
| | 1115 | like the optional argument to |
| | 1116 | <command>systemctl reboot</command> |
| | 1117 | command.</para></listitem> |
| | 1118 | </varlistentry> |
| | 1119 | |
| | 1120 | <varlistentry> |
| | 1121 | <term><varname>FileDescriptorStoreMax=</varname></term> |
| | 1122 | <listitem><para>Configure how many |
| | 1123 | file descriptors may be stored in the |
| | 1124 | service manager for the service using |
| | 1125 | <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s |
| | 1126 | <literal>FDSTORE=1</literal> |
| | 1127 | messages. This is useful for |
| | 1128 | implementing service restart schemes |
| | 1129 | where the state is serialized to |
| | 1130 | <filename>/run</filename> and the file |
| | 1131 | descriptors passed to the service |
| | 1132 | manager, to allow restarts without |
| | 1133 | losing state. Defaults to 0, i.e. no |
| | 1134 | file descriptors may be stored in the |
| | 1135 | service manager by default. All file |
| | 1136 | descriptors passed to the service |
| | 1137 | manager from a specific service are |
| | 1138 | passed back to the service's main |
| | 1139 | process on the next service |
| | 1140 | restart. Any file descriptors passed |
| | 1141 | to the service manager are |
| | 1142 | automatically closed when POLLHUP or |
| | 1143 | POLLERR is seen on them, or when the |
| | 1144 | service is fully stopped and no job |
| | 1145 | queued or being executed for |
| | 1146 | it.</para></listitem> |
| | 1147 | </varlistentry> |
| | 1148 | |
| | 1149 | </variablelist> |
| | 1150 | |
| | 1151 | <para>Check |
| | 1152 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 1153 | and |
| | 1154 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 1155 | for more settings.</para> |
| | 1156 | |
| | 1157 | </refsect1> |
| | 1158 | |
| | 1159 | <refsect1> |
| | 1160 | <title>Command lines</title> |
| | 1161 | |
| | 1162 | <para>This section describes command line parsing and |
| | 1163 | variable and specifier substitions for |
| | 1164 | <varname>ExecStart=</varname>, |
| | 1165 | <varname>ExecStartPre=</varname>, |
| | 1166 | <varname>ExecStartPost=</varname>, |
| | 1167 | <varname>ExecReload=</varname>, |
| | 1168 | <varname>ExecStop=</varname>, and |
| | 1169 | <varname>ExecStopPost=</varname> options.</para> |
| | 1170 | |
| | 1171 | <para>Multiple command lines may be concatenated in a |
| | 1172 | single directive by separating them with semicolons |
| | 1173 | (these semicolons must be passed as separate words). |
| | 1174 | Lone semicolons may be escaped as |
| | 1175 | <literal>\;</literal>.</para> |
| | 1176 | |
| | 1177 | <para>Each command line is split on whitespace, with |
| | 1178 | the first item being the command to execute, and the |
| | 1179 | subsequent items being the arguments. Double quotes |
| | 1180 | ("...") and single quotes ('...') may be used, in |
| | 1181 | which case everything until the next matching quote |
| | 1182 | becomes part of the same argument. C-style escapes are |
| | 1183 | also supported, see table below. Quotes themselves are |
| | 1184 | removed after parsing and escape sequences |
| | 1185 | substituted. In addition, a trailing backslash |
| | 1186 | (<literal>\</literal>) may be used to merge lines. |
| | 1187 | </para> |
| | 1188 | |
| | 1189 | <para>This syntax is intended to be very similar to |
| | 1190 | shell syntax, but only the meta-characters and |
| | 1191 | expansions described in the following paragraphs are |
| | 1192 | understood. Specifically, redirection using |
| | 1193 | <literal><</literal>, <literal><<</literal>, |
| | 1194 | <literal>></literal>, and |
| | 1195 | <literal>>></literal>, pipes using |
| | 1196 | <literal>|</literal>, running programs in the |
| | 1197 | background using <literal>&</literal>, and |
| | 1198 | <emphasis>other elements of shell syntax are not |
| | 1199 | supported</emphasis>.</para> |
| | 1200 | |
| | 1201 | <para>The command to execute must an absolute path |
| | 1202 | name. It may contain spaces, but control characters |
| | 1203 | are not allowed.</para> |
| | 1204 | |
| | 1205 | <para>The command line accepts <literal>%</literal> |
| | 1206 | specifiers as described in |
| | 1207 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. |
| | 1208 | Note that the first argument of the command line |
| | 1209 | (i.e. the program to execute) may not include |
| | 1210 | specifiers.</para> |
| | 1211 | |
| | 1212 | <para>Basic environment variable substitution is |
| | 1213 | supported. Use <literal>${FOO}</literal> as part of a |
| | 1214 | word, or as a word of its own, on the command line, in |
| | 1215 | which case it will be replaced by the value of the |
| | 1216 | environment variable including all whitespace it |
| | 1217 | contains, resulting in a single argument. Use |
| | 1218 | <literal>$FOO</literal> as a separate word on the |
| | 1219 | command line, in which case it will be replaced by the |
| | 1220 | value of the environment variable split at whitespace |
| | 1221 | resulting in zero or more arguments. For this type of |
| | 1222 | expansion, quotes and respected when splitting into |
| | 1223 | words, and afterwards removed.</para> |
| | 1224 | |
| | 1225 | <para>Example:</para> |
| | 1226 | |
| | 1227 | <programlisting>Environment="ONE=one" 'TWO=two two' |
| | 1228 | ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting> |
| | 1229 | |
| | 1230 | <para>This will execute <command>/bin/echo</command> |
| | 1231 | with four arguments: <literal>one</literal>, |
| | 1232 | <literal>two</literal>, <literal>two</literal>, and |
| | 1233 | <literal>two two</literal>.</para> |
| | 1234 | |
| | 1235 | <para>Example:</para> |
| | 1236 | <programlisting>Environment=ONE='one' "TWO='two two' too" THREE= |
| | 1237 | ExecStart=/bin/echo ${ONE} ${TWO} ${THREE} |
| | 1238 | ExecStart=/bin/echo $ONE $TWO $THREE</programlisting> |
| | 1239 | <para>This results in <filename>echo</filename> being |
| | 1240 | called twice, the first time with arguments |
| | 1241 | <literal>'one'</literal>, |
| | 1242 | <literal>'two two' too</literal>, <literal></literal>, |
| | 1243 | and the second time with arguments |
| | 1244 | <literal>one</literal>, <literal>two two</literal>, |
| | 1245 | <literal>too</literal>. |
| | 1246 | </para> |
| | 1247 | |
| | 1248 | <para>To pass a literal dollar sign, use |
| | 1249 | <literal>$$</literal>. Variables whose value is not |
| | 1250 | known at expansion time are treated as empty |
| | 1251 | strings. Note that the first argument (i.e. the |
| | 1252 | program to execute) may not be a variable.</para> |
| | 1253 | |
| | 1254 | <para>Variables to be used in this fashion may be |
| | 1255 | defined through <varname>Environment=</varname> and |
| | 1256 | <varname>EnvironmentFile=</varname>. In addition, |
| | 1257 | variables listed in the section "Environment variables |
| | 1258 | in spawned processes" in |
| | 1259 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| | 1260 | which are considered "static configuration", may be |
| | 1261 | used (this includes e.g. <varname>$USER</varname>, but |
| | 1262 | not <varname>$TERM</varname>).</para> |
| | 1263 | |
| | 1264 | <para>Note that shell command lines are not directly |
| | 1265 | supported. If shell command lines are to be used, they |
| | 1266 | need to be passed explicitly to a shell implementation |
| | 1267 | of some kind. Example:</para> |
| | 1268 | <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting> |
| | 1269 | |
| | 1270 | <para>Example:</para> |
| | 1271 | |
| | 1272 | <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting> |
| | 1273 | |
| | 1274 | <para>This will execute <command>/bin/echo</command> |
| | 1275 | two times, each time with one argument: |
| | 1276 | <literal>one</literal> and <literal>two two</literal>, |
| | 1277 | respectively. Because two commands are specified, |
| | 1278 | <varname>Type=oneshot</varname> must be used.</para> |
| | 1279 | |
| | 1280 | <para>Example:</para> |
| | 1281 | |
| | 1282 | <programlisting>ExecStart=/bin/echo / >/dev/null & \; \ |
| | 1283 | /bin/ls</programlisting> |
| | 1284 | |
| | 1285 | <para>This will execute <command>/bin/echo</command> |
| | 1286 | with five arguments: <literal>/</literal>, |
| | 1287 | <literal>>/dev/null</literal>, |
| | 1288 | <literal>&</literal>, <literal>;</literal>, and |
| | 1289 | <literal>/bin/ls</literal>.</para> |
| | 1290 | |
| | 1291 | <table> |
| | 1292 | <title>C escapes supported in command lines and environment variables</title> |
| | 1293 | <tgroup cols='2'> |
| | 1294 | <colspec colname='escape' /> |
| | 1295 | <colspec colname='meaning' /> |
| | 1296 | <thead> |
| | 1297 | <row> |
| | 1298 | <entry>Literal</entry> |
| | 1299 | <entry>Actual value</entry> |
| | 1300 | </row> |
| | 1301 | </thead> |
| | 1302 | <tbody> |
| | 1303 | <row> |
| | 1304 | <entry><literal>\a</literal></entry> |
| | 1305 | <entry>bell</entry> |
| | 1306 | </row> |
| | 1307 | <row> |
| | 1308 | <entry><literal>\b</literal></entry> |
| | 1309 | <entry>backspace</entry> |
| | 1310 | </row> |
| | 1311 | <row> |
| | 1312 | <entry><literal>\f</literal></entry> |
| | 1313 | <entry>form feed</entry> |
| | 1314 | </row> |
| | 1315 | <row> |
| | 1316 | <entry><literal>\n</literal></entry> |
| | 1317 | <entry>newline</entry> |
| | 1318 | </row> |
| | 1319 | <row> |
| | 1320 | <entry><literal>\r</literal></entry> |
| | 1321 | <entry>carriage return</entry> |
| | 1322 | </row> |
| | 1323 | <row> |
| | 1324 | <entry><literal>\t</literal></entry> |
| | 1325 | <entry>tab</entry> |
| | 1326 | </row> |
| | 1327 | <row> |
| | 1328 | <entry><literal>\v</literal></entry> |
| | 1329 | <entry>vertical tab</entry> |
| | 1330 | </row> |
| | 1331 | <row> |
| | 1332 | <entry><literal>\\</literal></entry> |
| | 1333 | <entry>backslash</entry> |
| | 1334 | </row> |
| | 1335 | <row> |
| | 1336 | <entry><literal>\"</literal></entry> |
| | 1337 | <entry>double quotation mark</entry> |
| | 1338 | </row> |
| | 1339 | <row> |
| | 1340 | <entry><literal>\'</literal></entry> |
| | 1341 | <entry>single quotation mark</entry> |
| | 1342 | </row> |
| | 1343 | <row> |
| | 1344 | <entry><literal>\s</literal></entry> |
| | 1345 | <entry>space</entry> |
| | 1346 | </row> |
| | 1347 | <row> |
| | 1348 | <entry><literal>\x<replaceable>xx</replaceable></literal></entry> |
| | 1349 | <entry>character number <replaceable>xx</replaceable> in hexadecimal encoding</entry> |
| | 1350 | </row> |
| | 1351 | <row> |
| | 1352 | <entry><literal>\<replaceable>nnn</replaceable></literal></entry> |
| | 1353 | <entry>character number <replaceable>nnn</replaceable> in octal encoding</entry> |
| | 1354 | </row> |
| | 1355 | </tbody> |
| | 1356 | </tgroup> |
| | 1357 | </table> |
| | 1358 | </refsect1> |
| | 1359 | |
| | 1360 | <refsect1> |
| | 1361 | <title>Examples</title> |
| | 1362 | |
| | 1363 | <example> |
| | 1364 | <title>Simple service</title> |
| | 1365 | |
| | 1366 | <para>The following unit file creates a service |
| | 1367 | that will execute |
| | 1368 | <filename>/usr/sbin/foo-daemon</filename>. |
| | 1369 | Since no <varname>Type=</varname> is specified, |
| | 1370 | the default |
| | 1371 | <varname>Type=</varname><option>simple</option> |
| | 1372 | will be assumed. systemd will assume the unit |
| | 1373 | to be started immediately after the program has |
| | 1374 | begun executing.</para> |
| | 1375 | |
| | 1376 | <programlisting>[Unit] |
| | 1377 | Description=Foo |
| | 1378 | |
| | 1379 | [Service] |
| | 1380 | ExecStart=/usr/sbin/foo-daemon |
| | 1381 | |
| | 1382 | [Install] |
| | 1383 | WantedBy=multi-user.target</programlisting> |
| | 1384 | |
| | 1385 | <para>Note that systemd assumes here that the |
| | 1386 | process started by systemd will continue |
| | 1387 | running until the service terminates. If the |
| | 1388 | program daemonizes itself (i.e. forks), please |
| | 1389 | use |
| | 1390 | <varname>Type=</varname><option>forking</option> |
| | 1391 | instead.</para> |
| | 1392 | |
| | 1393 | <para>Since no <varname>ExecStop=</varname> was |
| | 1394 | specified, systemd will send SIGTERM to all |
| | 1395 | processes started from this service, and after |
| | 1396 | a timeout also SIGKILL. This behavior can be |
| | 1397 | modified, see |
| | 1398 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 1399 | for details.</para> |
| | 1400 | |
| | 1401 | <para>Note that this unit type does not include |
| | 1402 | any type of notification when a service has |
| | 1403 | completed initialization. For this, you should |
| | 1404 | use other unit types, such as |
| | 1405 | <varname>Type=</varname><option>notify</option> |
| | 1406 | if the service understands systemd's |
| | 1407 | notification protocol, |
| | 1408 | <varname>Type=</varname><option>forking</option> |
| | 1409 | if the service can background itself or |
| | 1410 | <varname>Type=</varname><option>dbus</option> |
| | 1411 | if the unit acquires a DBus name once |
| | 1412 | initialization is complete. See below.</para> |
| | 1413 | </example> |
| | 1414 | |
| | 1415 | <example> |
| | 1416 | <title>Oneshot service</title> |
| | 1417 | |
| | 1418 | <para>Sometimes units should just execute an |
| | 1419 | action without keeping active processes, such |
| | 1420 | as a filesystem check or a cleanup action on |
| | 1421 | boot. For this, |
| | 1422 | <varname>Type=</varname><option>oneshot</option> |
| | 1423 | exists. Units of this type will wait until the |
| | 1424 | process specified terminates and then fall back |
| | 1425 | to being inactive. The following unit will |
| | 1426 | perform a clenaup action:</para> |
| | 1427 | |
| | 1428 | <programlisting>[Unit] |
| | 1429 | Description=Cleanup old Foo data |
| | 1430 | |
| | 1431 | [Service] |
| | 1432 | Type=oneshot |
| | 1433 | ExecStart=/usr/sbin/foo-cleanup |
| | 1434 | |
| | 1435 | [Install] |
| | 1436 | WantedBy=multi-user.target</programlisting> |
| | 1437 | |
| | 1438 | <para>Note that systemd will consider the unit |
| | 1439 | to be in the state 'starting' until the program |
| | 1440 | has terminated, so ordered dependencies will |
| | 1441 | wait for the program to finish before starting |
| | 1442 | themselves. The unit will revert to the |
| | 1443 | 'inactive' state after the execution is |
| | 1444 | done, never reaching the 'active' state. That |
| | 1445 | means another request to start the unit will |
| | 1446 | perform the action again.</para> |
| | 1447 | |
| | 1448 | <para><varname>Type=</varname><option>oneshot</option> |
| | 1449 | are the only service units that may have more |
| | 1450 | than one <varname>ExecStart=</varname> |
| | 1451 | specified. They will be executed in order until |
| | 1452 | either they are all successful or one of them |
| | 1453 | fails.</para> |
| | 1454 | </example> |
| | 1455 | |
| | 1456 | <example> |
| | 1457 | <title>Stoppable oneshot service</title> |
| | 1458 | |
| | 1459 | <para>Similarly to the oneshot services, there |
| | 1460 | are sometimes units that need to execute a |
| | 1461 | program to set up something and then execute |
| | 1462 | another to shut it down, but no process remains |
| | 1463 | active while they are considered |
| | 1464 | 'started'. Network configuration can sometimes |
| | 1465 | fall into this category. Another use case is if |
| | 1466 | a oneshot service shall not be executed a |
| | 1467 | each time when they are pulled in as a |
| | 1468 | dependency, but only the first time.</para> |
| | 1469 | |
| | 1470 | <para>For this, systemd knows the setting |
| | 1471 | <varname>RemainAfterExit=</varname><option>yes</option>, |
| | 1472 | which causes systemd to consider the unit to be |
| | 1473 | active if the start action exited successfully. |
| | 1474 | This directive can be used with all types, but |
| | 1475 | is most useful with |
| | 1476 | <varname>Type=</varname><option>oneshot</option> |
| | 1477 | and |
| | 1478 | <varname>Type=</varname><option>simple</option>. |
| | 1479 | With |
| | 1480 | <varname>Type=</varname><option>oneshot</option> |
| | 1481 | systemd waits until the start action has |
| | 1482 | completed before it considers the unit to be |
| | 1483 | active, so dependencies start only after the |
| | 1484 | start action has succeeded. With |
| | 1485 | <varname>Type=</varname><option>simple</option> |
| | 1486 | dependencies will start immediately after the |
| | 1487 | start action has been dispatched. The following |
| | 1488 | unit provides an example for a simple static |
| | 1489 | firewall.</para> |
| | 1490 | |
| | 1491 | <programlisting>[Unit] |
| | 1492 | Description=Simple firewall |
| | 1493 | |
| | 1494 | [Service] |
| | 1495 | Type=oneshot |
| | 1496 | RemainAfterExit=yes |
| | 1497 | ExecStart=/usr/local/sbin/simple-firewall-start |
| | 1498 | ExecStop=/usr/local/sbin/simple-firewall-stop |
| | 1499 | |
| | 1500 | [Install] |
| | 1501 | WantedBy=multi-user.target</programlisting> |
| | 1502 | |
| | 1503 | <para>Since the unit is considered to be |
| | 1504 | running after the start action has exited, |
| | 1505 | invoking <command>systemctl start</command> on |
| | 1506 | that unit again will cause no action to be |
| | 1507 | taken.</para> |
| | 1508 | </example> |
| | 1509 | |
| | 1510 | <example> |
| | 1511 | <title>Traditional forking services</title> |
| | 1512 | |
| | 1513 | <para>Many traditional daemons/services |
| | 1514 | background (i.e. fork, daemonize) themselves |
| | 1515 | when starting. Set |
| | 1516 | <varname>Type=</varname><option>forking</option> |
| | 1517 | in the service's unit file to support this mode |
| | 1518 | of operation. systemd will consider the service |
| | 1519 | to be in the process of initialization while |
| | 1520 | the original program is still running. Once |
| | 1521 | it exits successfully and at least a process |
| | 1522 | remains (and |
| | 1523 | <varname>RemainAfterExit=</varname><option>no</option>), |
| | 1524 | the service is considered started.</para> |
| | 1525 | |
| | 1526 | <para>Often a traditional daemon only consists |
| | 1527 | of one process. Therefore, if only one process |
| | 1528 | is left after the original process terminates, |
| | 1529 | systemd will consider that process the main |
| | 1530 | process of the service. In that case, the |
| | 1531 | <varname>$MAINPID</varname> variable will be |
| | 1532 | available in <varname>ExecReload=</varname>, |
| | 1533 | <varname>ExecStop=</varname>, etc.</para> |
| | 1534 | |
| | 1535 | <para>In case more than one process remains, |
| | 1536 | systemd will be unable to determine the main |
| | 1537 | process, so it will not assume there is one. |
| | 1538 | In that case, <varname>$MAINPID</varname> will |
| | 1539 | not expand to anything. However, if the process |
| | 1540 | decides to write a traditional PID file, |
| | 1541 | systemd will be able to read the main PID from |
| | 1542 | there. Please set <varname>PIDFile=</varname> |
| | 1543 | accordingly. Note that the daemon should write |
| | 1544 | that file before finishing with its |
| | 1545 | initialization, otherwise systemd might try to |
| | 1546 | read the file before it exists.</para> |
| | 1547 | |
| | 1548 | <para>The following example shows a simple |
| | 1549 | daemon that forks and just starts one process |
| | 1550 | in the background:</para> |
| | 1551 | |
| | 1552 | <programlisting>[Unit] |
| | 1553 | Description=Some simple daemon |
| | 1554 | |
| | 1555 | [Service] |
| | 1556 | Type=forking |
| | 1557 | ExecStart=/usr/sbin/my-simple-daemon -d |
| | 1558 | |
| | 1559 | [Install] |
| | 1560 | WantedBy=multi-user.target</programlisting> |
| | 1561 | |
| | 1562 | <para>Please see |
| | 1563 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 1564 | for details on how you can influence the way |
| | 1565 | systemd terminates the service.</para> |
| | 1566 | </example> |
| | 1567 | |
| | 1568 | <example> |
| | 1569 | <title>DBus services</title> |
| | 1570 | |
| | 1571 | <para>For services that acquire a name on the |
| | 1572 | DBus system bus, use |
| | 1573 | <varname>Type=</varname><option>dbus</option> |
| | 1574 | and set <varname>BusName=</varname> |
| | 1575 | accordingly. The service should not fork |
| | 1576 | (daemonize). systemd will consider the service |
| | 1577 | to be initialized once the name has been |
| | 1578 | acquired on the system bus. The following |
| | 1579 | example shows a typical DBus service:</para> |
| | 1580 | |
| | 1581 | <programlisting>[Unit] |
| | 1582 | Description=Simple DBus service |
| | 1583 | |
| | 1584 | [Service] |
| | 1585 | Type=dbus |
| | 1586 | BusName=org.example.simple-dbus-service |
| | 1587 | ExecStart=/usr/sbin/simple-dbus-service |
| | 1588 | |
| | 1589 | [Install] |
| | 1590 | WantedBy=multi-user.target</programlisting> |
| | 1591 | |
| | 1592 | <para>For <emphasis>bus-activatable</emphasis> |
| | 1593 | services, don't include a |
| | 1594 | <literal>[Install]</literal> section in the |
| | 1595 | systemd service file, but use the |
| | 1596 | <varname>SystemdService=</varname> option in |
| | 1597 | the corresponding DBus service file, for |
| | 1598 | example |
| | 1599 | (<filename>/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service</filename>):</para> |
| | 1600 | |
| | 1601 | <programlisting>[D-BUS Service] |
| | 1602 | Name=org.example.simple-dbus-service |
| | 1603 | Exec=/usr/sbin/simple-dbus-service |
| | 1604 | User=root |
| | 1605 | SystemdService=simple-dbus-service.service</programlisting> |
| | 1606 | |
| | 1607 | <para>Please see |
| | 1608 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 1609 | for details on how you can influence the way |
| | 1610 | systemd terminates the service.</para> |
| | 1611 | </example> |
| | 1612 | |
| | 1613 | <example> |
| | 1614 | <title>Services that notify systemd about their initialization</title> |
| | 1615 | |
| | 1616 | <para><varname>Type=</varname><option>simple</option> |
| | 1617 | services are really easy to write, but have the |
| | 1618 | major disadvantage of systemd not being able to |
| | 1619 | tell when initialization of the given service |
| | 1620 | is complete. For this reason, systemd supports |
| | 1621 | a simple notification protocol that allows |
| | 1622 | daemons to make systemd aware that they are |
| | 1623 | done initializing. Use |
| | 1624 | <varname>Type=</varname><option>notify</option> |
| | 1625 | for this. A typical service file for such a |
| | 1626 | daemon would look like this:</para> |
| | 1627 | |
| | 1628 | <programlisting>[Unit] |
| | 1629 | Description=Simple notifying service |
| | 1630 | |
| | 1631 | [Service] |
| | 1632 | Type=notify |
| | 1633 | ExecStart=/usr/sbin/simple-notifying-service |
| | 1634 | |
| | 1635 | [Install] |
| | 1636 | WantedBy=multi-user.target</programlisting> |
| | 1637 | |
| | 1638 | <para>Note that the daemon has to support |
| | 1639 | systemd's notification protocol, else systemd |
| | 1640 | will think the service hasn't started yet and |
| | 1641 | kill it after a timeout. For an example of how |
| | 1642 | to update daemons to support this protocol |
| | 1643 | transparently, take a look at |
| | 1644 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. |
| | 1645 | systemd will consider the unit to be in the |
| | 1646 | 'starting' state until a readiness notification |
| | 1647 | has arrived.</para> |
| | 1648 | |
| | 1649 | <para>Please see |
| | 1650 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| | 1651 | for details on how you can influence the way |
| | 1652 | systemd terminates the service.</para> |
| | 1653 | </example> |
| | 1654 | </refsect1> |
| | 1655 | |
| | 1656 | <refsect1> |
| | 1657 | <title>See Also</title> |
| | 1658 | <para> |
| | 1659 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| | 1660 | <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| | 1661 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| | 1662 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| | 1663 | <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| | 1664 | <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| | 1665 | <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> |
| | 1666 | </para> |
| | 1667 | </refsect1> |
| | 1668 | |
| | 1669 | </refentry> |
projects / thirdparty / systemd.git / blame_incremental