2023-02-01 21:49:46 +03:00
|
|
|
# nixos-anywhere - install nixos everywhere via ssh
|
2022-11-10 18:49:56 +03:00
|
|
|
|
2023-02-01 22:33:08 +03:00
|
|
|
<img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/5bdd3f3c442b923813e301b319290305353a3e7a/docs/logo.png" width="256" height="256">
|
|
|
|
|
2023-02-01 21:49:46 +03:00
|
|
|
nixos-anywhere (formally known as nixos-remote) makes it possible to install nixos from Linux machines reachable via ssh.
|
2022-11-22 23:46:43 +03:00
|
|
|
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)
|
|
|
|
- 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.
|
|
|
|
|
2022-11-10 18:49:56 +03:00
|
|
|
## Usage
|
2023-02-01 21:49:46 +03:00
|
|
|
Needs a repo with your configurations with flakes. For a minimal example checkout https://github.com/numtide/nixos-anywhere-examples.
|
2022-11-22 23:38:11 +03:00
|
|
|
|
|
|
|
Your NixOS configuration will also need a [disko](https://github.com/nix-community/disko) configuration as we can see in
|
2023-02-01 21:49:46 +03:00
|
|
|
our [example](https://github.com/numtide/nixos-anywhere-examples/blob/9768e438b1467ec55d42e096860e7199bd1ef43d/flake.nix#L15-L19)
|
2022-11-22 23:38:11 +03:00
|
|
|
|
|
|
|
Afterwards you can just run:
|
|
|
|
|
2022-11-10 18:49:56 +03:00
|
|
|
```
|
2023-02-01 21:49:46 +03:00
|
|
|
nix run github:numtide/nixos-anywhere -- root@yourip --flake github:your-user/your-repo#your-system
|
2022-11-10 18:49:56 +03:00
|
|
|
```
|
2022-11-22 23:38:11 +03:00
|
|
|
|
|
|
|
The parameter passed to `--flake` should point to your nixos configuration
|
|
|
|
exposed in your flake (`nixosConfigurations.your-system` in the example above).
|
2022-12-31 14:55:20 +03:00
|
|
|
|
2023-02-01 21:49:46 +03:00
|
|
|
`nixos-anywhere --help`
|
2022-12-31 14:55:20 +03:00
|
|
|
``` shell
|
2023-02-01 21:49:46 +03:00
|
|
|
Usage: nixos-anywhere [options] ssh-host
|
2022-12-31 14:55:20 +03:00
|
|
|
|
|
|
|
Options:
|
|
|
|
|
|
|
|
* -f, --flake flake
|
|
|
|
set the flake to install the system from
|
2023-01-12 02:25:14 +03:00
|
|
|
* -L, --print-build-logs
|
|
|
|
print full build logs
|
2022-12-31 14:55:20 +03:00
|
|
|
* -s, --store-paths
|
|
|
|
set the store paths to the disko-script and nixos-system directly
|
|
|
|
if this is give, flake is not needed
|
2023-01-12 02:25:14 +03:00
|
|
|
* --no-reboot
|
|
|
|
do not reboot after installation, allowing further customization of the target installation.
|
2022-12-31 14:55:20 +03:00
|
|
|
* --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
|
2023-01-12 02:25:14 +03:00
|
|
|
* --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.
|
2023-01-17 18:28:44 +03:00
|
|
|
* --no-substitute-on-destination
|
|
|
|
disable passing --substitute-on-destination to nix-copy
|
2022-12-31 14:55:20 +03:00
|
|
|
* --debug
|
|
|
|
enable debug output
|
2023-01-17 18:28:44 +03:00
|
|
|
* --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
|
2022-12-31 14:55:20 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
## Using your own kexec image
|
|
|
|
|
2023-02-01 21:49:46 +03:00
|
|
|
By default `nixos-anywhere` will download the kexec image from [here](https://github.com/nix-community/nixos-images#kexec-tarballs).
|
2022-12-31 14:55:20 +03:00
|
|
|
It is also possible to provide your own by providing a file to `--kexec`. The image will than uploaded prior to executing.
|
|
|
|
|
|
|
|
``` shell
|
2023-02-01 21:49:46 +03:00
|
|
|
nixos-anywhere \
|
2022-12-31 14:55:20 +03:00
|
|
|
--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
|
|
|
|
|
|
|
|
``` shell
|
2023-02-01 21:49:46 +03:00
|
|
|
nixos-anywhere \
|
2022-12-31 14:55:20 +03:00
|
|
|
--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
|
|
|
|
```
|
2023-01-12 17:26:01 +03:00
|
|
|
|
|
|
|
## Developer guide
|
|
|
|
|
2023-02-01 21:49:46 +03:00
|
|
|
To run `nixos-anywhere` from the repo:
|
2023-01-12 17:26:01 +03:00
|
|
|
|
|
|
|
```console
|
|
|
|
nix run . -- --help
|
|
|
|
```
|
|
|
|
|
|
|
|
To format the code
|
|
|
|
|
|
|
|
```console
|
|
|
|
nix fmt
|
|
|
|
```
|