From 06aa64684c6746eb54aea86f981d82b60f544657 Mon Sep 17 00:00:00 2001 From: Florian Klink Date: Thu, 9 Jun 2022 20:08:34 +0200 Subject: [PATCH] nixos/doc: document how to use kexecTree This documents how to build kexec artifacts. --- .../installation/installing-kexec.section.xml | 94 +++++++++++++++++++ .../installation/installing.chapter.xml | 1 + .../installation/installing-kexec.section.md | 64 +++++++++++++ .../manual/installation/installing.chapter.md | 1 + 4 files changed, 160 insertions(+) create mode 100644 nixos/doc/manual/from_md/installation/installing-kexec.section.xml create mode 100644 nixos/doc/manual/installation/installing-kexec.section.md diff --git a/nixos/doc/manual/from_md/installation/installing-kexec.section.xml b/nixos/doc/manual/from_md/installation/installing-kexec.section.xml new file mode 100644 index 000000000000..46ea0d59b6c3 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/installing-kexec.section.xml @@ -0,0 +1,94 @@ +
+ <quote>Booting</quote> into NixOS 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: + + +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: + + +{ modulesPath, ... }: { + imports = [ + (modulesPath + "/installer/netboot/netboot-minimal.nix") + ]; + + services.openssh.enable = true; + users.users.root.openssh.authorizedKeys.keys = [ + "my-ssh-pubkey" + ]; +} + + +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). + +
diff --git a/nixos/doc/manual/from_md/installation/installing.chapter.xml b/nixos/doc/manual/from_md/installation/installing.chapter.xml index aee0b30a7076..19ff841f5a67 100644 --- a/nixos/doc/manual/from_md/installation/installing.chapter.xml +++ b/nixos/doc/manual/from_md/installation/installing.chapter.xml @@ -638,6 +638,7 @@ $ passwd eelco Additional installation notes + diff --git a/nixos/doc/manual/installation/installing-kexec.section.md b/nixos/doc/manual/installation/installing-kexec.section.md new file mode 100644 index 000000000000..286cbbda6a69 --- /dev/null +++ b/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 '' +``` + +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 '' \ + --arg configuration ./configuration.nix + --attr config.system.build.kexecTree +``` + +Make sure your `configuration.nix` does still import `netboot-minimal.nix` (or +`netboot-base.nix`). diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md index 8a46d68ae3ba..7e830f8e4583 100644 --- a/nixos/doc/manual/installation/installing.chapter.md +++ b/nixos/doc/manual/installation/installing.chapter.md @@ -476,6 +476,7 @@ With a partitioned disk. ```{=docbook} +