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

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