[thirdparty/systemd.git] / man / systemd.kill.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1+ -->

<refentry id="systemd.kill">
  <refentryinfo>
    <title>systemd.kill</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd.kill</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd.kill</refname>
    <refpurpose>Process killing procedure
    configuration</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename><replaceable>service</replaceable>.service</filename>,
    <filename><replaceable>socket</replaceable>.socket</filename>,
    <filename><replaceable>mount</replaceable>.mount</filename>,
    <filename><replaceable>swap</replaceable>.swap</filename>,
    <filename><replaceable>scope</replaceable>.scope</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>Unit configuration files for services, sockets, mount
    points, swap devices and scopes share a subset of configuration
    options which define the killing procedure of processes belonging
    to the unit.</para>

    <para>This man page lists the configuration options shared by
    these five unit types. See
    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    for the common options shared by all unit configuration files, and
    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    and
    <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    for more information on the configuration file options specific to
    each unit type.</para>

    <para>The kill procedure configuration options are configured in
    the [Service], [Socket], [Mount] or [Swap] section, depending on
    the unit type.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <variablelist class='unit-directives'>

      <varlistentry>
        <term><varname>KillMode=</varname></term>
        <listitem><para>Specifies how processes of this unit shall be
        killed. One of
        <option>control-group</option>,
        <option>process</option>,
        <option>mixed</option>,
        <option>none</option>.</para>

        <para>If set to <option>control-group</option>, all remaining
        processes in the control group of this unit will be killed on
        unit stop (for services: after the stop command is executed,
        as configured with <varname>ExecStop=</varname>). If set to
        <option>process</option>, only the main process itself is
        killed. If set to <option>mixed</option>, the
        <constant>SIGTERM</constant> signal (see below) is sent to the
        main process while the subsequent <constant>SIGKILL</constant>
        signal (see below) is sent to all remaining processes of the
        unit's control group. If set to <option>none</option>, no
        process is killed. In this case, only the stop command will be
        executed on unit stop, but no process will 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.</para>

        <para>Processes will first be terminated via <constant>SIGTERM</constant> (unless the signal to send
        is changed via <varname>KillSignal=</varname> or <varname>RestartKillSignal=</varname>). Optionally,
        this is immediately followed by a <constant>SIGHUP</constant> (if enabled with
        <varname>SendSIGHUP=</varname>). If processes still remain after the main process of a unit has
        exited or the delay configured via the <varname>TimeoutStopSec=</varname> has passed, the termination
        request is repeated with the <constant>SIGKILL</constant> signal or the signal specified via
        <varname>FinalKillSignal=</varname> (unless this is disabled via the <varname>SendSIGKILL=</varname>
        option). See <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
        for more information.</para>

        <para>Defaults to <option>control-group</option>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>KillSignal=</varname></term>
        <listitem><para>Specifies which signal to use when stopping a service. This controls the signal that
        is sent as first step of shutting down a unit (see above), and is usually followed by
        <constant>SIGKILL</constant> (see above and below). For a list of valid signals, see
        <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
        Defaults to <constant>SIGTERM</constant>.</para>

        <para>Note that, right after sending the signal specified in this setting, systemd will always send
        <constant>SIGCONT</constant>, to ensure that even suspended tasks can be terminated cleanly.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>RestartKillSignal=</varname></term>
        <listitem><para>Specifies which signal to use when restarting a service. The same as
        <varname>KillSignal=</varname> described above, with the exception that this setting is used in a
        restart job. Not set by default, and the value of <varname>KillSignal=</varname> is used.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>SendSIGHUP=</varname></term>
        <listitem><para>Specifies whether to send
        <constant>SIGHUP</constant> to remaining processes immediately
        after sending the signal configured with
        <varname>KillSignal=</varname>. This is useful to indicate to
        shells and shell-like programs that their connection has been
        severed. Takes a boolean value. Defaults to "no".
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>SendSIGKILL=</varname></term>
        <listitem><para>Specifies whether to send
        <constant>SIGKILL</constant> (or the signal specified by
        <varname>FinalKillSignal=</varname>) to remaining processes
        after a timeout, if the normal shutdown procedure left
        processes of the service around. When disabled, a
        <varname>KillMode=</varname> of <constant>control-group</constant>
        or <constant>mixed</constant> service will not restart if
        processes from prior services exist within the control group.
        Takes a boolean value. Defaults to "yes".
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>FinalKillSignal=</varname></term>
        <listitem><para>Specifies which signal to send to remaining
        processes after a timeout if <varname>SendSIGKILL=</varname>
        is enabled. The signal configured here should be one that is
        not typically caught and processed by services (<constant>SIGTERM</constant>
        is not suitable). Developers can find it useful to use this to
        generate a coredump to troubleshoot why a service did not
        terminate upon receiving the initial <constant>SIGTERM</constant>
        signal. This can be achieved by configuring <varname>LimitCORE=</varname>
        and setting <varname>FinalKillSignal=</varname> to either
        <constant>SIGQUIT</constant> or <constant>SIGABRT</constant>
        Defaults to <constant>SIGKILL</constant>.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>WatchdogSignal=</varname></term>
        <listitem><para>Specifies which signal to use to terminate the
        service when the watchdog timeout expires (enabled through
        <varname>WatchdogSec=</varname>). Defaults to <constant>SIGABRT</constant>.
        </para></listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
      <title>See Also</title>
      <para>
        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
        <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>
      </para>
  </refsect1>

</refentry>
Commit	Line	Data
4819ff03	1	<?xml version='1.0'?> <!---nxml--->
3a54a157	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
12b42c76	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
0307f791	4	<!-- SPDX-License-Identifier: LGPL-2.1+ -->
4819ff03 LP	5
4819ff03 LP	6	<refentry id="systemd.kill">
798d3a52 ZJS	7	<refentryinfo>
	8	<title>systemd.kill</title>
	9	<productname>systemd</productname>
798d3a52 ZJS	10	</refentryinfo>
	11
	12	<refmeta>
	13	<refentrytitle>systemd.kill</refentrytitle>
	14	<manvolnum>5</manvolnum>
	15	</refmeta>
	16
	17	<refnamediv>
	18	<refname>systemd.kill</refname>
	19	<refpurpose>Process killing procedure
	20	configuration</refpurpose>
	21	</refnamediv>
	22
	23	<refsynopsisdiv>
	24	<para><filename><replaceable>service</replaceable>.service</filename>,
	25	<filename><replaceable>socket</replaceable>.socket</filename>,
	26	<filename><replaceable>mount</replaceable>.mount</filename>,
	27	<filename><replaceable>swap</replaceable>.swap</filename>,
	28	<filename><replaceable>scope</replaceable>.scope</filename></para>
	29	</refsynopsisdiv>
	30
	31	<refsect1>
	32	<title>Description</title>
	33
	34	<para>Unit configuration files for services, sockets, mount
	35	points, swap devices and scopes share a subset of configuration
	36	options which define the killing procedure of processes belonging
	37	to the unit.</para>
	38
	39	<para>This man page lists the configuration options shared by
	40	these five unit types. See
	41	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	42	for the common options shared by all unit configuration files, and
	43	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	44	<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	45	<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	46	<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	47	and
	48	<citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	49	for more information on the configuration file options specific to
	50	each unit type.</para>
	51
	52	<para>The kill procedure configuration options are configured in
	53	the [Service], [Socket], [Mount] or [Swap] section, depending on
	54	the unit type.</para>
	55	</refsect1>
	56
	57	<refsect1>
	58	<title>Options</title>
	59
	60	<variablelist class='unit-directives'>
	61
	62	<varlistentry>
	63	<term><varname>KillMode=</varname></term>
	64	<listitem><para>Specifies how processes of this unit shall be
	65	killed. One of
	66	<option>control-group</option>,
	67	<option>process</option>,
	68	<option>mixed</option>,
	69	<option>none</option>.</para>
	70
	71	<para>If set to <option>control-group</option>, all remaining
	72	processes in the control group of this unit will be killed on
	73	unit stop (for services: after the stop command is executed,
74	as configured with <varname>ExecStop=</varname>). If set to
75	<option>process</option>, only the main process itself is
76	killed. If set to <option>mixed</option>, the
77	<constant>SIGTERM</constant> signal (see below) is sent to the
78	main process while the subsequent <constant>SIGKILL</constant>
79	signal (see below) is sent to all remaining processes of the
80	unit's control group. If set to <option>none</option>, no
81	process is killed. In this case, only the stop command will be
916f595c	82	executed on unit stop, but no process will be killed otherwise.
798d3a52 ZJS	83	Processes remaining alive after stop are left in their control
	84	group and the control group continues to exist after stop
	85	unless it is empty.</para>
	86
2e34d21b	87	<para>Processes will first be terminated via <constant>SIGTERM</constant> (unless the signal to send
b557f1c1 ZJS	88	is changed via <varname>KillSignal=</varname> or <varname>RestartKillSignal=</varname>). Optionally,
	89	this is immediately followed by a <constant>SIGHUP</constant> (if enabled with
	90	<varname>SendSIGHUP=</varname>). If processes still remain after the main process of a unit has
	91	exited or the delay configured via the <varname>TimeoutStopSec=</varname> has passed, the termination
	92	request is repeated with the <constant>SIGKILL</constant> signal or the signal specified via
	93	<varname>FinalKillSignal=</varname> (unless this is disabled via the <varname>SendSIGKILL=</varname>
	94	option). See <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>
	95	for more information.</para>
2e34d21b LP	96
2e34d21b LP	97	<para>Defaults to <option>control-group</option>.</para></listitem>
798d3a52 ZJS	98	</varlistentry>
	99
	100	<varlistentry>
	101	<term><varname>KillSignal=</varname></term>
b557f1c1 ZJS	102	<listitem><para>Specifies which signal to use when stopping a service. This controls the signal that
	103	is sent as first step of shutting down a unit (see above), and is usually followed by
	104	<constant>SIGKILL</constant> (see above and below). For a list of valid signals, see
3ba3a79d	105	<citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
b557f1c1	106	Defaults to <constant>SIGTERM</constant>.</para>
e8c53936	107
b557f1c1 ZJS	108	<para>Note that, right after sending the signal specified in this setting, systemd will always send
	109	<constant>SIGCONT</constant>, to ensure that even suspended tasks can be terminated cleanly.</para>
	110	</listitem>
	111	</varlistentry>
	112
	113	<varlistentry>
	114	<term><varname>RestartKillSignal=</varname></term>
	115	<listitem><para>Specifies which signal to use when restarting a service. The same as
	116	<varname>KillSignal=</varname> described above, with the exception that this setting is used in a
	117	restart job. Not set by default, and the value of <varname>KillSignal=</varname> is used.</para>
e8c53936	118	</listitem>
798d3a52 ZJS	119	</varlistentry>
	120
	121	<varlistentry>
	122	<term><varname>SendSIGHUP=</varname></term>
	123	<listitem><para>Specifies whether to send
	124	<constant>SIGHUP</constant> to remaining processes immediately
	125	after sending the signal configured with
	126	<varname>KillSignal=</varname>. This is useful to indicate to
	127	shells and shell-like programs that their connection has been
	128	severed. Takes a boolean value. Defaults to "no".
	129	</para></listitem>
	130	</varlistentry>
	131
	132	<varlistentry>
	133	<term><varname>SendSIGKILL=</varname></term>
	134	<listitem><para>Specifies whether to send
fbb48d4c JR	135	<constant>SIGKILL</constant> (or the signal specified by
	136	<varname>FinalKillSignal=</varname>) to remaining processes
	137	after a timeout, if the normal shutdown procedure left
c53d2d54 DB	138	processes of the service around. When disabled, a
	139	<varname>KillMode=</varname> of <constant>control-group</constant>
	140	or <constant>mixed</constant> service will not restart if
	141	processes from prior services exist within the control group.
	142	Takes a boolean value. Defaults to "yes".
fbb48d4c JR	143	</para></listitem>
	144	</varlistentry>
	145
	146	<varlistentry>
	147	<term><varname>FinalKillSignal=</varname></term>
	148	<listitem><para>Specifies which signal to send to remaining
	149	processes after a timeout if <varname>SendSIGKILL=</varname>
	150	is enabled. The signal configured here should be one that is
	151	not typically caught and processed by services (<constant>SIGTERM</constant>
	152	is not suitable). Developers can find it useful to use this to
	153	generate a coredump to troubleshoot why a service did not
	154	terminate upon receiving the initial <constant>SIGTERM</constant>
	155	signal. This can be achieved by configuring <varname>LimitCORE=</varname>
	156	and setting <varname>FinalKillSignal=</varname> to either
	157	<constant>SIGQUIT</constant> or <constant>SIGABRT</constant>
	158	Defaults to <constant>SIGKILL</constant>.
798d3a52 ZJS	159	</para></listitem>
	160	</varlistentry>
	161
c87700a1 AZ	162	<varlistentry>
	163	<term><varname>WatchdogSignal=</varname></term>
	164	<listitem><para>Specifies which signal to use to terminate the
	165	service when the watchdog timeout expires (enabled through
	166	<varname>WatchdogSec=</varname>). Defaults to <constant>SIGABRT</constant>.
	167	</para></listitem>
	168	</varlistentry>
	169
798d3a52 ZJS	170	</variablelist>
	171	</refsect1>
	172
	173	<refsect1>
	174	<title>See Also</title>
	175	<para>
	176	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	177	<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
68d838f7	178	<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52 ZJS	179	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	180	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	181	<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	182	<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	183	<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	184	<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	185	<citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
	186	<citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
3ba3a79d	187	<citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>
798d3a52 ZJS	188	</para>
798d3a52 ZJS	189	</refsect1>
4819ff03 LP	190
4819ff03 LP	191	</refentry>