.github | ||
docs | ||
src | ||
terraform | ||
tests | ||
.envrc | ||
.gitignore | ||
bors.toml | ||
flake.lock | ||
flake.nix | ||
LICENSE | ||
README.md |
nixos-anywhere - install nixos everywhere via ssh
![](https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png)
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 to boot into a NixOS installer from a running Linux system. It then uses disko to partition and format the disks on the target system before it installs the user provided nixos configuration.
Requirements
nixos-anywhere
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-anywhere
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
- 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 configuration as we can see in our example
Afterwards you can just run:
nix run github:numtide/nixos-anywhere -- root@yourip --flake github:your-user/your-repo#your-system
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
Usage: nixos-anywhere [options] ssh-host
Options:
* -f, --flake flake
set the flake to install the system from
* -L, --print-build-logs
print full build logs
* -s, --store-paths
set the store paths to the disko-script and nixos-system directly
if this is give, flake is not needed
* --no-reboot
do not reboot after installation, allowing further customization of the target installation.
* --kexec url
use another kexec tarball to bootstrap NixOS
* --stop-after-disko
exit after disko formating, you can then proceed to install manually or some other way
* --extra-files files
files to copy into the new nixos installation
* --disk-encryption-keys remote_path local_path
copy the contents of the file or pipe in local_path to remote_path in the installer environment,
after kexec but before installation. Can be repeated.
* --no-substitute-on-destination
disable passing --substitute-on-destination to nix-copy
* --debug
enable debug output
* --option KEY VALUE
nix option to pass to every nix related command
* --from store-uri
URL of the source Nix store to copy the nixos and disko closure from
Using your own kexec image
By default nixos-anywhere
will download the kexec image from
here. It is also
possible to provide your own by providing a file to --kexec
. The image will
than uploaded prior to executing.
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
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' \
root@yourip
Developer guide
To run nixos-anywhere
from the repo:
nix run . -- --help
To format the code
nix fmt