diff options
author | Florian Klink <flokli@flokli.de> | 2022-06-09 20:08:34 +0200 |
---|---|---|
committer | Florian Klink <flokli@flokli.de> | 2022-06-09 20:08:34 +0200 |
commit | 06aa64684c6746eb54aea86f981d82b60f544657 (patch) | |
tree | cf4394398cd3e5fd3383f4fb5801d2d4d62816e1 /nixos/doc/manual/installation/installing-kexec.section.md | |
parent | cdaaf95e206c295404b189882db2f7d294d2cbe8 (diff) |
nixos/doc: document how to use kexecTree
This documents how to build kexec artifacts.
Diffstat (limited to 'nixos/doc/manual/installation/installing-kexec.section.md')
-rw-r--r-- | nixos/doc/manual/installation/installing-kexec.section.md | 64 |
1 files changed, 64 insertions, 0 deletions
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 '<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`). |