nixos/doc: document how to use kexecTree

This documents how to build kexec artifacts.

nixos/doc/manual/from_md/installation/installing-kexec.section.xml

@@ -0,0 +1,94 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-booting-via-kexec">
+  <title><quote>Booting</quote> into NixOS via kexec</title>
+  <para>
+    In some cases, your system might already be booted into/preinstalled
+    with another Linux distribution, and booting NixOS by attaching an
+    installation image is quite a manual process.
+  </para>
+  <para>
+    This is particularly useful for (cloud) providers where you can’t
+    boot a custom image, but get some Debian or Ubuntu installation.
+  </para>
+  <para>
+    In these cases, it might be easier to use <literal>kexec</literal>
+    to <quote>jump into NixOS</quote> from the running system, which
+    only assumes <literal>bash</literal> and <literal>kexec</literal> to
+    be installed on the machine.
+  </para>
+  <para>
+    Note that kexec may not work correctly on some hardware, as devices
+    are not fully re-initialized in the process. In practice, this
+    however is rarely the case.
+  </para>
+  <para>
+    To build the necessary files from your current version of nixpkgs,
+    you can run:
+  </para>
+  <programlisting>
+nix-build -A kexec.x86_64-linux '&lt;nixpkgs/nixos/release.nix&gt;'
+</programlisting>
+  <para>
+    This will create a <literal>result</literal> directory containing
+    the following:
+  </para>
+  <itemizedlist spacing="compact">
+    <listitem>
+      <para>
+        <literal>bzImage</literal> (the Linux kernel)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <literal>initrd</literal> (the initrd file)
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        <literal>kexec-boot</literal> (a shellscript invoking
+        <literal>kexec</literal>)
+      </para>
+    </listitem>
+  </itemizedlist>
+  <para>
+    These three files are meant to be copied over to the other already
+    running Linux Distribution.
+  </para>
+  <para>
+    Note it’s symlinks pointing elsewhere, so <literal>cd</literal> in,
+    and use <literal>scp * root@$destination</literal> to copy it over,
+    rather than rsync.
+  </para>
+  <para>
+    Once you finished copying, execute <literal>kexec-boot</literal>
+    <emphasis>on the destination</emphasis>, and after some seconds, the
+    machine should be booting into an (ephemeral) NixOS installation
+    medium.
+  </para>
+  <para>
+    In case you want to describe your own system closure to kexec into,
+    instead of the default installer image, you can build your own
+    <literal>configuration.nix</literal>:
+  </para>
+  <programlisting language="bash">
+{ modulesPath, ... }: {
+  imports = [
+    (modulesPath + &quot;/installer/netboot/netboot-minimal.nix&quot;)
+  ];
+
+  services.openssh.enable = true;
+  users.users.root.openssh.authorizedKeys.keys = [
+    &quot;my-ssh-pubkey&quot;
+  ];
+}
+</programlisting>
+  <programlisting>
+nix-build '&lt;nixpkgs/nixos&gt;' \
+  --arg configuration ./configuration.nix
+  --attr config.system.build.kexecTree
+</programlisting>
+  <para>
+    Make sure your <literal>configuration.nix</literal> does still
+    import <literal>netboot-minimal.nix</literal> (or
+    <literal>netboot-base.nix</literal>).
+  </para>
+</section>

nixos/doc/manual/from_md/installation/installing.chapter.xml

@@ -638,6 +638,7 @@ $ passwd eelco
     <title>Additional installation notes</title>
     <xi:include href="installing-usb.section.xml" />
     <xi:include href="installing-pxe.section.xml" />
+    <xi:include href="installing-kexec.section.xml" />
     <xi:include href="installing-virtualbox-guest.section.xml" />
     <xi:include href="installing-from-other-distro.section.xml" />
     <xi:include href="installing-behind-a-proxy.section.xml" />

nixos/doc/manual/installation/installing-kexec.section.md

@@ -0,0 +1,64 @@
+# "Booting" into NixOS via kexec {#sec-booting-via-kexec}
+
+In some cases, your system might already be booted into/preinstalled with
+another Linux distribution, and booting NixOS by attaching an installation
+image is quite a manual process.
+
+This is particularly useful for (cloud) providers where you can't boot a custom
+image, but get some Debian or Ubuntu installation.
+
+In these cases, it might be easier to use `kexec` to "jump into NixOS" from the
+running system, which only assumes `bash` and `kexec` to be installed on the
+machine.
+
+Note that kexec may not work correctly on some hardware, as devices are not
+fully re-initialized in the process. In practice, this however is rarely the
+case.
+
+To build the necessary files from your current version of nixpkgs,
+you can run:
+
+```ShellSession
+nix-build -A kexec.x86_64-linux '<nixpkgs/nixos/release.nix>'
+```
+
+This will create a `result` directory containing the following:
+ - `bzImage` (the Linux kernel)
+ - `initrd` (the initrd file)
+ - `kexec-boot` (a shellscript invoking `kexec`)
+
+These three files are meant to be copied over to the other already running
+Linux Distribution.
+
+Note it's symlinks pointing elsewhere, so `cd` in, and use
+`scp * root@$destination` to copy it over, rather than rsync.
+
+Once you finished copying, execute `kexec-boot` *on the destination*, and after
+some seconds, the machine should be booting into an (ephemeral) NixOS
+installation medium.
+
+In case you want to describe your own system closure to kexec into, instead of
+the default installer image, you can build your own `configuration.nix`:
+
+```nix
+{ modulesPath, ... }: {
+  imports = [
+    (modulesPath + "/installer/netboot/netboot-minimal.nix")
+  ];
+
+  services.openssh.enable = true;
+  users.users.root.openssh.authorizedKeys.keys = [
+    "my-ssh-pubkey"
+  ];
+}
+```
+
+
+```ShellSession
+nix-build '<nixpkgs/nixos>' \
+  --arg configuration ./configuration.nix
+  --attr config.system.build.kexecTree
+```
+
+Make sure your `configuration.nix` does still import `netboot-minimal.nix` (or
+`netboot-base.nix`).

nixos/doc/manual/installation/installing.chapter.md

@@ -476,6 +476,7 @@ With a partitioned disk.
 ```{=docbook}
 <xi:include href="installing-usb.section.xml" />
 <xi:include href="installing-pxe.section.xml" />
+<xi:include href="installing-kexec.section.xml" />
 <xi:include href="installing-virtualbox-guest.section.xml" />
 <xi:include href="installing-from-other-distro.section.xml" />
 <xi:include href="installing-behind-a-proxy.section.xml" />