<refsect1>
<title>Signals</title>
+ <para>The service listens to various UNIX process signals that can be used to request various actions
+ asynchronously. The signal handling is enabled very early during boot, before any further processes are
+ invoked. However, a supervising container manager or similar that intends to request these operations via
+ this mechanism must take into consideration that this functionality is not available during the earliest
+ initialization phase. An <function>sd_notify()</function> notification message carrying the
+ <varname>X_SYSTEMD_SIGNALS_LEVEL=2</varname> field is emitted once the signal handlers are enabled, see
+ below. This may be used to schedule submission of these signals correctly.</para>
+
<variablelist>
<varlistentry>
<term><constant>SIGTERM</constant></term>
<varlistentry>
<term><varname>$NOTIFY_SOCKET</varname></term>
- <listitem><para>Set by systemd for supervised processes for
- status and start-up completion notification. See
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- for more information.</para></listitem>
+ <listitem><para>Set by service manager for its services for status and readiness notifications. Also
+ consumed by service manager for notifying supervising container managers or service managers up the
+ stack about its own progress. See
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> and the
+ relevant section below for more information.</para></listitem>
</varlistentry>
</variablelist>
</varlistentry>
<varlistentry>
- <term><varname>systemd.crash_reboot</varname></term>
+ <term><varname>systemd.crash_action=</varname></term>
- <listitem><para>Takes a boolean argument or enables the option if specified
- without an argument. If enabled, the system manager (PID 1) will reboot the
- machine automatically when it crashes, after a 10s delay. Otherwise, the
- system will hang indefinitely. Defaults to disabled, in order to avoid a
- reboot loop. If combined with <varname>systemd.crash_shell</varname>, the
- system is rebooted after the shell exits.</para>
+ <listitem><para>Takes one of <literal>freeze</literal>, <literal>reboot</literal> or
+ <literal>poweroff</literal>. Defaults to <literal>freeze</literal>. If set to
+ <literal>freeze</literal>, the system will hang indefinitely when the system manager (PID 1) crashes.
+ If set to <literal>reboot</literal>, the system manager (PID 1) will reboot the machine automatically
+ when it crashes, after a 10s delay. If set to <literal>poweroff</literal>, the system manager (PID 1)
+ will power off the machine immediately when it crashes. If combined with
+ <varname>systemd.crash_shell</varname>, the configured crash action is executed after the shell
+ exits.</para>
- <xi:include href="version-info.xml" xpointer="v227"/></listitem>
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
</refsect1>
<refsect1>
- <title>System credentials</title>
+ <title>System Credentials</title>
<para>During initialization the service manager will import credentials from various sources into the
system's set of credentials, which can then be propagated into services and consumed by
<term><varname>vmm.notify_socket</varname></term>
<listitem>
<para>Contains a <constant>AF_VSOCK</constant> or <constant>AF_UNIX</constant> address where to
- send a <constant>READY=1</constant> notification datagram when the system has finished booting. See
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
- more information. Note that in case the hypervisor does not support <constant>SOCK_DGRAM</constant>
- over <constant>AF_VSOCK</constant>, <constant>SOCK_SEQPACKET</constant> will be tried instead. The
- credential payload for <constant>AF_VSOCK</constant> should be in the form
- <literal>vsock:CID:PORT</literal>.</para>
-
- <para>This feature is useful for hypervisors/VMMs or other processes on the host to receive a
+ send a <constant>READY=1</constant> notification message when the service manager has completed
+ booting. See
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+ the next section for more information. Note that in case the hypervisor does not support
+ <constant>SOCK_DGRAM</constant> over <constant>AF_VSOCK</constant>,
+ <constant>SOCK_SEQPACKET</constant> will be tried instead. The credential payload for
+ <constant>AF_VSOCK</constant> should be a string in the form
+ <literal>vsock:CID:PORT</literal>. <literal>vsock-stream</literal>, <literal>vsock-dgram</literal>
+ and <literal>vsock-seqpacket</literal> can be used instead of <literal>vsock</literal> to force
+ usage of the corresponding socket type.</para>
+
+ <para>This feature is useful for machine managers or other processes on the host to receive a
notification via VSOCK when a virtual machine has finished booting.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
</variablelist>
+
+ <para>For a list of system credentials various other components of systemd consume, see
+ <citerefentry><refentrytitle>systemd.system-credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Readiness Protocol</title>
+
+ <para>The service manager implements a readiness notification protocol both between the manager and its
+ services (i.e. down the stack), and between the manager and a potential supervisor further up the stack
+ (the latter could be a machine or container manager, or in case of a per-user service manager the system
+ service manager instance). The basic protocol (and the suggested API for it) is described in
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+ <para>The notification socket the service manager (including PID 1) uses for reporting readiness to its
+ own supervisor is set via the usual <varname>$NOTIFY_SOCKET</varname> environment variable (see
+ above). Since this is directly settable only for container managers and for the per-user instance of the
+ service manager, an additional mechanism to configure this is available, in particular intended for use
+ in VM environments: the <varname>vmm.notify_socket</varname> system credential (see above) may be set to
+ a suitable socket (typically an <constant>AF_VSOCK</constant> one) via SMBIOS Type 11 vendor strings. For
+ details see above.</para>
+
+ <para>The notification protocol from the service manager up the stack towards a supervisor supports a
+ number of extension fields that allow a supervisor to learn about specific properties of the system and
+ track its boot progress. Specifically the following fields are sent:</para>
+
+ <itemizedlist>
+ <listitem><para>An <varname>X_SYSTEMD_HOSTNAME=…</varname> message will be sent out once the initial
+ hostname for the system has been determined. Note that during later runtime the hostname might be
+ changed again programmatically, and (currently) no further notifications are sent out in that case.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+ <listitem><para>An <varname>X_SYSTEMD_MACHINE_ID=…</varname> message will be sent out once the machine
+ ID of the system has been determined. See
+ <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+ details.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+ <listitem><para>An <varname>X_SYSTEMD_SIGNALS_LEVEL=…</varname> message will be sent out once the
+ service manager installed the various UNIX process signal handlers described above. The field's value
+ is an unsigned integer formatted as decimal string, and indicates the supported UNIX process signal
+ feature level of the service manager. Currently, only a single feature level is defined:</para>
+
+ <itemizedlist>
+ <listitem><para><varname>X_SYSTEMD_SIGNALS_LEVEL=2</varname> covers the various UNIX process signals
+ documented above – which are a superset of those supported by the historical SysV init
+ system.</para></listitem>
+ </itemizedlist>
+
+ <para>Signals sent to PID 1 before this message is sent might not be handled correctly yet. A consumer
+ of these messages should parse the value as an unsigned integer indication the level of support. For
+ now only the mentioned level 2 is defined, but later on additional levels might be defined with higher
+ integers, that will implement a superset of the currently defined behaviour.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+ <listitem><para><varname>X_SYSTEMD_UNIT_ACTIVE=…</varname> and
+ <varname>X_SYSTEMD_UNIT_INACTIVE=…</varname> messages will be sent out for each target unit as it
+ becomes active or stops being active. This is useful to track boot progress and functionality. For
+ example, once the <filename>ssh-access.target</filename> unit is reported started SSH access is
+ typically available, see
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ details.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+ <listitem><para>An <varname>X_SYSTEMD_SHUTDOWN=…</varname> message will be sent out very shortly before
+ the system shuts down. The value is one of the strings <literal>reboot</literal>,
+ <literal>halt</literal>, <literal>poweroff</literal>, <literal>kexec</literal> and indicates which kind
+ of shutdown is being executed.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+
+ <listitem><para>An <varname>X_SYSTEMD_REBOOT_PARAMETER=…</varname> message will also be sent out very
+ shortly before the system shuts down. Its value is the reboot argument as configured with
+ <command>systemctl --reboot-argument=…</command>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+ </itemizedlist>
+
+ <para>Note that these extension fields are sent in addition to the regular <literal>READY=1</literal> and
+ <literal>RELOADING=1</literal> notifications.</para>
</refsect1>
<refsect1>
</varlistentry>
<varlistentry>
- <term><option>--crash-vt=</option><replaceable>VT</replaceable></term>
+ <term><option>--crash-vt=<replaceable>VT</replaceable></option></term>
<listitem><para>Switch to a specific virtual console (VT) on crash. This switch has no effect when
running as user instance. Same as <varname>systemd.crash_chvt=</varname> above (but not the
</varlistentry>
<varlistentry>
- <term><option>--crash-reboot</option></term>
+ <term><option>--crash-action=</option></term>
- <listitem><para>Automatically reboot the system on crash. This switch has no effect when running as
- user instance. See <varname>systemd.crash_reboot</varname> above.</para>
+ <listitem><para>Specify what to do when the system manager (PID 1) crashes. This switch has no
+ effect when systemd is running as user instance. See <varname>systemd.crash_action=</varname>
+ above.</para>
- <xi:include href="version-info.xml" xpointer="v227"/></listitem>
+ <xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
projects / thirdparty / systemd.git / blobdiff