nixos/doc: document how to use kexecTree
This documents how to build kexec artifacts.
This commit is contained in:
Florian Klink
parent
cdaaf95e20
commit
06aa64684c
4 changed files with 160 additions and 0 deletions
|
|
@ -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 '<nixpkgs/nixos/release.nix>'
|
||||
</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 + "/installer/netboot/netboot-minimal.nix")
|
||||
];
|
||||
|
||||
services.openssh.enable = true;
|
||||
users.users.root.openssh.authorizedKeys.keys = [
|
||||
"my-ssh-pubkey"
|
||||
];
|
||||
}
|
||||
</programlisting>
|
||||
<programlisting>
|
||||
nix-build '<nixpkgs/nixos>' \
|
||||
--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>
|
||||
|
|
@ -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" />
|
||||
|
|
|
|||
64
nixos/doc/manual/installation/installing-kexec.section.md
Normal file
64
nixos/doc/manual/installation/installing-kexec.section.md
Normal file
|
|
@ -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`).
|
||||
|
|
@ -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" />
|
||||
|
|
|
|||
Loading…
Reference in a new issue