man/systemctl: say that kexec loads the kernel, mention --force

Fixes #24588.
Fixes #15029.

diff --git a/man/systemctl.xml b/man/systemctl.xml
index e3776fb2776cb4b706f31cd5e46653977d37ae17..e54dd22aaee59dac2245326834b406a35217bf8d 100644 (file)
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -1535,13 +1535,27 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
           <term><command>kexec</command></term>
 
           <listitem>
-            <para>Shut down and reboot the system via <command>kexec</command>. This is equivalent to
-            <command>systemctl start kexec.target --job-mode=replace-irreversibly --no-block</command>. This command is
-            asynchronous; it will return after the reboot operation is enqueued, without waiting for it to
-            complete.</para>
+            <para>Shut down and reboot the system via <command>kexec</command>. This command will load a
+            kexec kernel if one wasn't loaded yet or fail. A kernel may be loaded earlier by a separate step,
+            this is particularly useful if a custom initrd or additional kernel commandline options are
+            desired. The <option>--force</option> can be used to continue without a kexec kernel, i.e. to
+            perform a normal reboot. The final reboot step is equivalent to
+            <command>systemctl start kexec.target --job-mode=replace-irreversibly --no-block</command>.
+            </para>
 
-            <para>This command honors <option>--force</option> and <option>--when=</option> in a similar way
-            as <command>halt</command>.</para>
+            <para>To load a kernel, an enumeration is performed following the
+            <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>,
+            and the default boot entry is loaded. For this step to succeed, the system must be using UEFI
+            and the boot loader entries must be configured appropriately. <command>bootctl list</command>
+            may be used to list boot entries, see
+            <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+            </para>
+
+            <para>This command is asynchronous; it will return after the reboot operation is enqueued,
+            without waiting for it to complete.</para>
+
+            <para>This command honors <option>--force</option> and <option>--when=</option> similarly
+            to <command>halt</command>.</para>
           </listitem>
         </varlistentry>