pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-booting-via-kexec">
2 <title><quote>Booting</quote> into NixOS via kexec</title>
3 <para>
4 In some cases, your system might already be booted into/preinstalled
5 with another Linux distribution, and booting NixOS by attaching an
6 installation image is quite a manual process.
7 </para>
8 <para>
9 This is particularly useful for (cloud) providers where you can’t
10 boot a custom image, but get some Debian or Ubuntu installation.
11 </para>
12 <para>
13 In these cases, it might be easier to use <literal>kexec</literal>
14 to <quote>jump into NixOS</quote> from the running system, which
15 only assumes <literal>bash</literal> and <literal>kexec</literal> to
16 be installed on the machine.
17 </para>
18 <para>
19 Note that kexec may not work correctly on some hardware, as devices
20 are not fully re-initialized in the process. In practice, this
21 however is rarely the case.
22 </para>
23 <para>
24 To build the necessary files from your current version of nixpkgs,
25 you can run:
26 </para>
27 <programlisting>
28nix-build -A kexec.x86_64-linux '<nixpkgs/nixos/release.nix>'
29</programlisting>
30 <para>
31 This will create a <literal>result</literal> directory containing
32 the following:
33 </para>
34 <itemizedlist spacing="compact">
35 <listitem>
36 <para>
37 <literal>bzImage</literal> (the Linux kernel)
38 </para>
39 </listitem>
40 <listitem>
41 <para>
42 <literal>initrd</literal> (the initrd file)
43 </para>
44 </listitem>
45 <listitem>
46 <para>
47 <literal>kexec-boot</literal> (a shellscript invoking
48 <literal>kexec</literal>)
49 </para>
50 </listitem>
51 </itemizedlist>
52 <para>
53 These three files are meant to be copied over to the other already
54 running Linux Distribution.
55 </para>
56 <para>
57 Note it’s symlinks pointing elsewhere, so <literal>cd</literal> in,
58 and use <literal>scp * root@$destination</literal> to copy it over,
59 rather than rsync.
60 </para>
61 <para>
62 Once you finished copying, execute <literal>kexec-boot</literal>
63 <emphasis>on the destination</emphasis>, and after some seconds, the
64 machine should be booting into an (ephemeral) NixOS installation
65 medium.
66 </para>
67 <para>
68 In case you want to describe your own system closure to kexec into,
69 instead of the default installer image, you can build your own
70 <literal>configuration.nix</literal>:
71 </para>
72 <programlisting language="bash">
73{ modulesPath, ... }: {
74 imports = [
75 (modulesPath + "/installer/netboot/netboot-minimal.nix")
76 ];
77
78 services.openssh.enable = true;
79 users.users.root.openssh.authorizedKeys.keys = [
80 "my-ssh-pubkey"
81 ];
82}
83</programlisting>
84 <programlisting>
85nix-build '<nixpkgs/nixos>' \
86 --arg configuration ./configuration.nix
87 --attr config.system.build.kexecTree
88</programlisting>
89 <para>
90 Make sure your <literal>configuration.nix</literal> does still
91 import <literal>netboot-minimal.nix</literal> (or
92 <literal>netboot-base.nix</literal>).
93 </para>
94</section>