diff options
Diffstat (limited to 'nixos/doc/manual')
6 files changed, 171 insertions, 0 deletions
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 @@ +<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> 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 <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" /> diff --git a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml index 958000687810..79bba37a1358 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml @@ -121,6 +121,14 @@ this version for the entire lifecycle of the 22.11 release. </para> </listitem> + <listitem> + <para> + (Neo)Vim can not be configured with + <literal>configure.pathogen</literal> anymore to reduce + maintainance burden. Use <literal>configure.packages</literal> + instead. + </para> + </listitem> </itemizedlist> </section> <section xml:id="sec-release-22.11-notable-changes"> 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`). 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} <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" /> diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md index 1a14885ed8c3..50bf15ca197d 100644 --- a/nixos/doc/manual/release-notes/rl-2211.section.md +++ b/nixos/doc/manual/release-notes/rl-2211.section.md @@ -50,6 +50,9 @@ In addition to numerous new and upgraded packages, this release has the followin - PHP 7.4 is no longer supported due to upstream not supporting this version for the entire lifecycle of the 22.11 release. +- (Neo)Vim can not be configured with `configure.pathogen` anymore to reduce maintainance burden. +Use `configure.packages` instead. + <!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. --> ## Other Notable Changes {#sec-release-22.11-notable-changes} |