Merge #53

53: Improve documentation r=Mic92 a=Mic92



Co-authored-by: Jörg Thalheim <[email protected]>

Author: bors[bot]

README.md

@@ -2,25 +2,40 @@
 
 <img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/5bdd3f3c442b923813e301b319290305353a3e7a/docs/logo.png" width="256" height="256">
 
-nixos-anywhere (formally known as nixos-remote) makes it possible to install nixos from Linux machines reachable via ssh.
-Under the hood uses a [kexec image](https://github.com/nix-community/nixos-images#kexec-tarballs) to boot
-into a NixOS installer from a running Linux system.
-It then uses [disko](https://github.com/nix-community/disko) to partition and
-format the disks on the target system before it installs the user provided nixos
+nixos-anywhere (formally known as nixos-remote) makes it possible to install
+nixos from Linux machines reachable via ssh. Under the hood uses a
+[kexec image](https://github.com/nix-community/nixos-images#kexec-tarballs) to
+boot into a NixOS installer from a running Linux system. It then uses
+[disko](https://github.com/nix-community/disko) to partition and format the
+disks on the target system before it installs the user provided nixos
 configuration.
 
 ## Requirements
 
-- x86_64 Linux system with kexec support (most x86_64 machine do have kexec support)
+`nixos-remote` can detect nixos installer if those contain the identifier
+`VARIANT=installer` in their `/etc/os-release` file. This is the case for the
+nixos-unstable installer and will be also part of nixos 23.05. If installer is
+detected `nixos-remote` will not try to kexec into its own image.
+
+If your system is not booted into a nixos installer than the following
+requirements apply for kexec to succeed:
+
+- x86_64 Linux system with kexec support (most x86_64 machine do have kexec
+  support) or you have to provide your own
+  [image](https://github.com/numtide/nixos-anywhere#using-your-own-kexec-image)
 - At least 2.5GB RAM (swap does not count). If you do not have enough RAM you
   will see failures unpacking the initrd), this is because kexec needs to load
   the whole nixos into memory.
 
 ## Usage
-Needs a repo with your configurations with flakes. For a minimal example checkout https://github.com/numtide/nixos-anywhere-examples.
 
-Your NixOS configuration will also need a [disko](https://github.com/nix-community/disko) configuration  as we can see in
-our [example](https://github.com/numtide/nixos-anywhere-examples/blob/9768e438b1467ec55d42e096860e7199bd1ef43d/flake.nix#L15-L19)
+Needs a repo with your configurations with flakes. For a minimal example
+checkout https://github.com/numtide/nixos-anywhere-examples.
+
+Your NixOS configuration will also need a
+[disko](https://github.com/nix-community/disko) configuration as we can see in
+our
+[example](https://github.com/numtide/nixos-anywhere-examples/blob/9768e438b1467ec55d42e096860e7199bd1ef43d/flake.nix#L15-L19)
 
 Afterwards you can just run:
 
@@ -32,7 +47,8 @@ The parameter passed to `--flake` should point to your nixos configuration
 exposed in your flake (`nixosConfigurations.your-system` in the example above).
 
 `nixos-anywhere --help`
-``` shell
+
+```shell
 Usage: nixos-anywhere [options] ssh-host
 
 Options:
@@ -67,21 +83,23 @@ Options:
 
 ## Using your own kexec image
 
-By default `nixos-anywhere` will download the kexec image from [here](https://github.com/nix-community/nixos-images#kexec-tarballs).
-It is also possible to provide your own by providing a file to `--kexec`. The image will than uploaded prior to executing.
+By default `nixos-anywhere` will download the kexec image from
+[here](https://github.com/nix-community/nixos-images#kexec-tarballs). It is also
+possible to provide your own by providing a file to `--kexec`. The image will
+than uploaded prior to executing.
 
-``` shell
+```shell
 nixos-anywhere \
   --kexec "$(nix build --print-out-paths github:nix-community/nixos-images#packages.x86_64-linux.kexec-installer-nixos-unstable)/nixos-kexec-installer-x86_64-linux.tar.gz" \
   --flake 'github:your-user/your-repo#your-system' \
   root@yourip
 ```
 
 `--kexec` can be useful for example for aarch64-linux, where there is no
-pre-build image. The following example assumes that your local machine can
-build for aarch64-linux either natively or through a remote builder
+pre-build image. The following example assumes that your local machine can build
+for aarch64-linux either natively or through a remote builder
 
-``` shell
+```shell
 nixos-anywhere \
   --kexec "$(nix build --print-out-paths github:nix-community/nixos-images#packages.aarch64-linux.kexec-installer-nixos-unstable)/nixos-kexec-installer-aarch64-linux.tar.gz" \
   --flake 'your-flake#your-system' \