2023-05-14 15:08:40 +03:00
|
|
|
|
# Quickstart Guide: nixos-anywhere
|
|
|
|
|
|
2023-05-16 20:06:24 +03:00
|
|
|
|
**_Install NixOS everywhere via ssh_**
|
2023-05-14 15:08:40 +03:00
|
|
|
|
|
2023-11-22 22:15:27 +03:00
|
|
|
|
<img src="https://raw.githubusercontent.com/nix-community/nixos-anywhere/main/docs/logo.png" width="150" height="150">
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-05-24 16:24:14 +03:00
|
|
|
|
[Documentation Index](./INDEX.md)
|
|
|
|
|
|
2023-05-24 15:21:18 +03:00
|
|
|
|
## Introduction
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-05-19 08:08:40 +03:00
|
|
|
|
This guide documents a simple installation of NixOS using **nixos-anywhere** on
|
|
|
|
|
a target machine running x86_64 Linux with
|
|
|
|
|
[kexec](https://man7.org/linux/man-pages/man8/kexec.8.html) support. The example
|
|
|
|
|
used in this guide installs NixOS on a Hetzner cloud machine. The configuration
|
|
|
|
|
may be different for some other instances. We will be including further examples
|
2023-09-17 17:10:10 +03:00
|
|
|
|
in the [How To Guide](./howtos/INDEX.md) as and when they are available.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
|
|
|
|
You will need:
|
|
|
|
|
|
2024-04-10 02:17:53 +03:00
|
|
|
|
- A [flake](https://wiki.nixos.org/wiki/Flakes) that controls the actions to be
|
2023-05-19 08:08:40 +03:00
|
|
|
|
performed
|
|
|
|
|
- A disk configuration containing details of the file system that will be
|
|
|
|
|
created on the new server.
|
2024-06-14 11:39:23 +03:00
|
|
|
|
- A target machine, reachable via SSH, with your SSH public key deployed and the
|
|
|
|
|
privilege to either login directly as root or to use password-less sudo.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-05-19 08:08:40 +03:00
|
|
|
|
**nixos-anywhere** doesn’t need to be installed. You can run it directly from
|
2024-06-17 14:51:23 +03:00
|
|
|
|
[the Github repository.](https://github.com/nix-community/nixos-anywhere)
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-05-19 08:08:40 +03:00
|
|
|
|
Details of the flake, the disk configuration and the CLI command are discussed
|
|
|
|
|
below.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
|
|
|
|
## Steps required to run nixos-anywhere
|
|
|
|
|
|
2023-10-20 12:17:32 +03:00
|
|
|
|
1. **Enable Flakes**:
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-20 12:17:32 +03:00
|
|
|
|
Ensure that flakes are enabled on your system. To enable flakes, refer to the
|
2024-04-10 02:17:53 +03:00
|
|
|
|
[NixOS Wiki](https://wiki.nixos.org/wiki/Flakes#enable-flakes).
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-20 12:17:32 +03:00
|
|
|
|
2. **Initialize a Flake**:
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-20 12:17:32 +03:00
|
|
|
|
The easiest way to start is to copy our
|
2023-12-30 01:04:43 +03:00
|
|
|
|
[example flake.nix](https://github.com/nix-community/nixos-anywhere-examples/blob/main/flake.nix)
|
2023-10-20 12:17:32 +03:00
|
|
|
|
into a new directory. This example is tailored for a virtual machine setup
|
|
|
|
|
similar to one on [Hetzner Cloud](https://www.hetzner.com/cloud), so you
|
|
|
|
|
might need to adapt it for your setup.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-20 12:17:32 +03:00
|
|
|
|
**Hardware-Specific Configuration**: If you're not using a virtual machine,
|
|
|
|
|
you'll need to generate a custom hardware configuration with
|
|
|
|
|
`nixos-generate-config`.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-20 12:17:32 +03:00
|
|
|
|
- **Get `nixos-generate-config` onto the Target Machine**:
|
2023-08-31 14:46:36 +03:00
|
|
|
|
|
|
|
|
|
1. **Option 1**: If NixOS is not installed, boot into an installer without
|
|
|
|
|
first installing NixOS.
|
|
|
|
|
2. **Option 2**: Use the kexec tarball method, as described
|
|
|
|
|
[here](https://github.com/nix-community/nixos-images#kexec-tarballs).
|
|
|
|
|
|
|
|
|
|
- **Generate Configuration**: Run the following command on the target machine:
|
|
|
|
|
|
|
|
|
|
```bash
|
2024-06-19 16:01:05 +03:00
|
|
|
|
nixos-generate-config --no-filesystems --dir /mnt
|
2023-08-31 14:46:36 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This creates the necessary configuration files under `/mnt/etc/nixos/`, which
|
2023-10-19 18:10:16 +03:00
|
|
|
|
you can then customize as needed and copy them to your local machine in order
|
|
|
|
|
to include them in your flake.
|
2023-08-31 14:46:36 +03:00
|
|
|
|
|
2023-09-17 11:30:59 +03:00
|
|
|
|
3. **Find SSH Key Line**:\
|
2023-08-31 14:46:36 +03:00
|
|
|
|
if you cloned
|
2023-12-30 01:04:43 +03:00
|
|
|
|
[our nixos-anywhere-example](https://github.com/nix-community/nixos-anywhere-examples/blob/main/configuration.nix)
|
2023-08-31 14:46:36 +03:00
|
|
|
|
you will also replace the SSH key like this: In your configuration, locate
|
|
|
|
|
the line that reads:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# change this to your ssh key
|
|
|
|
|
"CHANGE"
|
|
|
|
|
```
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-08-31 14:46:36 +03:00
|
|
|
|
Replace the text `CHANGE` with your own SSH key. This is crucial, as you will
|
|
|
|
|
not be able to log into the target machine post-installation without it.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-08-31 14:46:36 +03:00
|
|
|
|
4. In the same directory, create a file named `disk-config.nix`. This will be
|
2023-05-24 15:21:18 +03:00
|
|
|
|
used to specify the disk layout to the **disko** tool, which nixos-anywhere
|
|
|
|
|
uses to partition, format and mount the disks. Again, for a simple
|
|
|
|
|
installation you can paste the contents from the example
|
2023-12-30 01:04:43 +03:00
|
|
|
|
[here](https://github.com/nix-community/nixos-anywhere-examples/blob/main/disk-config.nix).
|
2023-05-24 15:21:18 +03:00
|
|
|
|
This configures a standard GPT (GUID Partition Table) partition compatible
|
|
|
|
|
with both EFI and BIOS systems, and mounts the disk as `/dev/sda`. If this
|
2023-05-29 15:54:03 +03:00
|
|
|
|
doesn’t meet your requirements, choose an example that suits your disk layout
|
|
|
|
|
from the
|
2023-05-24 15:21:18 +03:00
|
|
|
|
[disko examples](https://github.com/nix-community/disko/tree/master/example).
|
|
|
|
|
For more information about this configuration, refer to the
|
|
|
|
|
[disko documentation.](https://github.com/nix-community/disko)
|
|
|
|
|
|
2023-08-31 14:46:36 +03:00
|
|
|
|
5. Run the following command to create the `flake.lock` file:
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-19 17:57:58 +03:00
|
|
|
|
```
|
|
|
|
|
nix flake lock
|
|
|
|
|
```
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-19 17:57:58 +03:00
|
|
|
|
Optionally, you can commit these files to a repo such as Github, or you can
|
|
|
|
|
simply reference your local directory when you run **nixos-anywhere**. This
|
|
|
|
|
example uses a local directory on the source machine.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-08-31 14:46:36 +03:00
|
|
|
|
6. On the target machine, make sure you have access as root via ssh by adding
|
2023-05-24 15:21:18 +03:00
|
|
|
|
your SSH key to the file `authorized_keys` in the directory `/root/.ssh`
|
|
|
|
|
|
2024-04-20 01:08:15 +03:00
|
|
|
|
Optionally, bootstrapping can also be performed through password login. For
|
|
|
|
|
example through the `image-installer-*` provided by
|
|
|
|
|
`nix-community/nixos-images`. Assign your password to the `SSH_PASS`
|
|
|
|
|
environment variable and specify `--env-password` as an additional command
|
|
|
|
|
line option. This will provide `ssh-copy-id` with the required password.
|
|
|
|
|
|
2023-08-31 14:46:36 +03:00
|
|
|
|
7. (Optional) Test your nixos and disko configuration:
|
2023-07-20 22:48:27 +03:00
|
|
|
|
|
2023-10-19 17:57:58 +03:00
|
|
|
|
The following command will automatically test your nixos configuration and
|
|
|
|
|
run disko inside a virtual machine, where
|
2023-07-20 22:48:27 +03:00
|
|
|
|
|
2023-10-19 17:57:58 +03:00
|
|
|
|
- `<path to configuration>` is the path to the directory or repository
|
|
|
|
|
containing `flake.nix` and `disk-config.nix`
|
2023-07-20 22:48:27 +03:00
|
|
|
|
|
2023-10-19 17:57:58 +03:00
|
|
|
|
- `<configuration name>` must match the name that immediately follows the
|
|
|
|
|
text `nixosConfigurations.` in the flake, as indicated by the comment in
|
|
|
|
|
the
|
2023-12-30 01:04:43 +03:00
|
|
|
|
[example](https://github.com/nix-community/nixos-anywhere-examples/blob/main/flake.nix)).
|
2023-07-20 22:48:27 +03:00
|
|
|
|
|
2023-10-19 17:57:58 +03:00
|
|
|
|
```
|
2023-11-22 22:15:27 +03:00
|
|
|
|
nix run github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> --vm-test
|
2023-10-19 17:57:58 +03:00
|
|
|
|
```
|
2023-07-20 22:48:27 +03:00
|
|
|
|
|
2023-08-31 14:46:36 +03:00
|
|
|
|
8. You can now run **nixos-anywhere** from the command line as shown below,
|
2023-05-24 15:21:18 +03:00
|
|
|
|
where:
|
2023-05-29 15:54:03 +03:00
|
|
|
|
|
2023-05-24 15:21:18 +03:00
|
|
|
|
- `<path to configuration>` is the path to the directory or repository
|
|
|
|
|
containing `flake.nix` and `disk-config.nix`
|
2023-05-29 15:54:03 +03:00
|
|
|
|
|
2023-05-24 15:21:18 +03:00
|
|
|
|
- `<configuration name>` must match the name that immediately follows the
|
|
|
|
|
text `nixosConfigurations.` in the flake, as indicated by the comment in
|
|
|
|
|
the
|
2023-12-30 01:04:43 +03:00
|
|
|
|
[example](https://github.com/nix-community/nixos-anywhere-examples/blob/main/flake.nix)).
|
2023-05-29 15:54:03 +03:00
|
|
|
|
|
2023-05-24 15:21:18 +03:00
|
|
|
|
- `<ip address>` is the IP address of the target machine.
|
2023-05-16 20:06:24 +03:00
|
|
|
|
|
2023-10-19 17:57:58 +03:00
|
|
|
|
```
|
2023-11-22 22:15:27 +03:00
|
|
|
|
nix run github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
|
2023-10-19 17:57:58 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The command would look like this if you had created your files in a
|
|
|
|
|
directory named `/home/mydir/test` and the IP address of your target
|
|
|
|
|
machine is `37.27.18.135`:
|
|
|
|
|
|
|
|
|
|
```
|
2023-11-22 22:15:27 +03:00
|
|
|
|
nix run github:nix-community/nixos-anywhere -- --flake /home/mydir/test#hetzner-cloud root@37.27.18.135
|
2023-10-19 17:57:58 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**nixos-anywhere** will then run, showing various output messages at each
|
|
|
|
|
stage. It may take some time to complete, depending on Internet speeds. It
|
|
|
|
|
should finish by showing the messages below before returning to the command
|
|
|
|
|
prompt.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Installation finished. No error reported.
|
|
|
|
|
Warning: Permanently added '<ip-address>' (ED25519) to the list of known hosts
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
When this happens, the target server will have been overwritten with a new
|
|
|
|
|
installation of NixOS. Note that the server's public SSH key will have
|
|
|
|
|
changed.
|
|
|
|
|
|
|
|
|
|
If you have previously accessed this server using SSH, you may see the
|
|
|
|
|
following message the next time you try to log in to the target.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
|
|
|
|
|
@ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
|
|
|
|
|
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
|
|
|
|
|
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
|
|
|
|
|
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
|
|
|
|
|
It is also possible that a host key has just been changed.
|
|
|
|
|
The fingerprint for the ED25519 key sent by the remote host is
|
|
|
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.
|
|
|
|
|
Please contact your system administrator.
|
|
|
|
|
Add correct host key in ~/.ssh/known_hosts to get rid of this message.
|
|
|
|
|
Offending ECDSA key in ~/.ssh/known_hosts:6
|
|
|
|
|
remove with:
|
2024-04-23 11:35:44 +03:00
|
|
|
|
ssh-keygen -f ~/.ssh/known_hosts" -R "<ip address>"
|
2023-10-19 17:57:58 +03:00
|
|
|
|
Host key for <ip_address> has changed and you have requested strict checking.
|
|
|
|
|
Host key verification failed.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This is because the `known_hosts` file in the `.ssh` directory now contains
|
|
|
|
|
a mismatch, since the server has been overwritten. To solve this, use a
|
2024-06-21 19:57:47 +03:00
|
|
|
|
text editor to remove the old entry from the `known_hosts` file (or use the
|
|
|
|
|
command `ssh-keygen -R <ip_address>`). The next connection attempt will
|
|
|
|
|
then treat this as a new server.
|
2023-10-19 17:57:58 +03:00
|
|
|
|
|
|
|
|
|
The error message line `Offending ECDSA key in ~/.ssh/known_hosts:` gives
|
|
|
|
|
the line number that needs to be removed from the `known_hosts` file.
|
|
|
|
|
|
|
|
|
|
The new server's configurations are defined in the flake. `nixos-anywhere`
|
|
|
|
|
does not create `etc/nixos/configuration.nix`, since it expects the server
|
|
|
|
|
to be administered remotely. Any future changes to the configuration should
|
|
|
|
|
be made to the flake, and you would reference this flake when doing the
|
|
|
|
|
nixos-rebuild command or a deployment tool of your choice i.e.
|
|
|
|
|
[colmena](https://github.com/zhaofengli/colmena),
|
|
|
|
|
[nixinate](https://github.com/MatthewCroughan/nixinate).
|
|
|
|
|
|
|
|
|
|
This example can be run from the machine itself for updating (replace
|
|
|
|
|
`<URL to your flake>` with your flake i.e. `.#` if your flake is in the
|
|
|
|
|
current directory):
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
nixos-rebuild switch --flake <URL to your flake>
|
|
|
|
|
```
|
|
|
|
|
|
2024-04-23 11:35:44 +03:00
|
|
|
|
You can also run `nixos-rebuild` to update a machine remotely, if you have
|
2023-10-19 17:57:58 +03:00
|
|
|
|
set up an openssh server and your ssh key for the root user:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
nixos-rebuild switch --flake <URL to your flake> --target-host "root@<ip address>"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For more information on different use cases of **nixos-anywhere** please
|
|
|
|
|
refer to the [How to Guide](./howtos/INDEX.md), and for more technical
|
|
|
|
|
information and explanation of known error messages, refer to the
|
|
|
|
|
[Reference Manual](./reference.md).
|