mirror of
https://github.com/nix-community/nixos-anywhere.git
synced 2024-09-11 08:35:24 +03:00
Merge #113
113: Added Quickstart guide r=Mic92 a=JillThornhill Co-authored-by: Jill <jill.thornhill@zol.co.zw> Co-authored-by: Jörg Thalheim <joerg@thalheim.io>
This commit is contained in:
commit
0586b4da4f
@ -1,6 +1,162 @@
|
||||
# Quickstart Guide: nixos-anywhere
|
||||
|
||||
This document describes how to use **nixos-anywhere** in its simplest case:
|
||||
installing NixOS on an existing Linux distribution via SSH.
|
||||
**_Install NixOS everywhere via ssh_**
|
||||
|
||||
TODO: Populate this guide
|
||||
<img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" width="150" height="150">
|
||||
|
||||
## Inroduction
|
||||
|
||||
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
|
||||
in the [How To Guide](./howtos.md) as and when they are available.
|
||||
|
||||
You will need:
|
||||
|
||||
- A [flake](https://nixos.wiki/wiki/Flakes) that controls the actions to be
|
||||
performed
|
||||
- A disk configuration containing details of the file system that will be
|
||||
created on the new server.
|
||||
|
||||
**nixos-anywhere** doesn’t need to be installed. You can run it directly from
|
||||
[Numtide's repository on Github.](https://github.com/numtide/nixos-anywhere)
|
||||
|
||||
Details of the flake, the disk configuration and the CLI command are discussed
|
||||
below.
|
||||
|
||||
## Steps required to run nixos-anywhere
|
||||
|
||||
1. Create a directory for the flake and configuration files, and ensure flakes
|
||||
are enabled on your system. The
|
||||
[Nixos Wiki](https://nixos.wiki/wiki/Flakes#enable-flakes) describes how to
|
||||
enable flakes.
|
||||
|
||||
1. In this directory, run the following command to create a flake.
|
||||
|
||||
```
|
||||
nix flake init
|
||||
```
|
||||
|
||||
This will create a flake in a file named flake.nix. Edit the flake to suit your
|
||||
requirements. For a minimal installation, you can paste in the contents of the
|
||||
example flake from
|
||||
[here](https://github.com/numtide/nixos-anywhere-examples/blob/main/flake.nix).
|
||||
|
||||
Lines 29 in the sample file reads:
|
||||
|
||||
```
|
||||
# change this to your ssh key
|
||||
"CHANGE"
|
||||
```
|
||||
|
||||
Substitute the text that reads `CHANGE` with your own SSH key. This is
|
||||
important, otherwise you will not be able to log on to the target machine after
|
||||
NixOS has been installed.
|
||||
|
||||
3. In the same directory, create a file named `disk-config.nix`. This will be
|
||||
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
|
||||
[here](https://github.com/numtide/nixos-anywhere-examples/blob/main/disk-config.nix).
|
||||
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
|
||||
doesn’t meet your requirements, choose an example that suits your disk
|
||||
layout from the
|
||||
[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)
|
||||
|
||||
4. Run the following command to create the `flake.lock` file:
|
||||
|
||||
```
|
||||
nix flake lock
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
5. On the target machine, make sure you have access as root via ssh by adding
|
||||
your SSH key to the file `authorized_keys` in the directory `/root/.ssh`
|
||||
|
||||
6. You can now run **nixos-anywhere** from the command line as shown below,
|
||||
where:
|
||||
|
||||
- `<path to configuration>` is the path to the directory or repository
|
||||
containing `flake.nix` and `disk-config.nix`
|
||||
|
||||
- `<configuration name>` must match the name that immediately follows the
|
||||
text `nixosConfigurations.` in the flake, as indicated by the comment in
|
||||
the
|
||||
[example](https://github.com/numtide/nixos-anywhere-examples/blob/main/flake.nix)).
|
||||
|
||||
- `<ip address>` is the IP address of the target machine.
|
||||
|
||||
```
|
||||
nix run github:numtide/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
|
||||
```
|
||||
|
||||
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`:
|
||||
|
||||
```
|
||||
nix run github:numtide/nixos-anywhere -- --flake /home/mydir/test#hetzner-cloud root@37.27.18.135
|
||||
```
|
||||
|
||||
**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:
|
||||
ssh-keygen -f ~/.ssh/known_hosts" -R "<ip addrress>"
|
||||
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 text
|
||||
editor to remove the old entry from the `known_hosts` file. The next connection
|
||||
attempt will then treat this as a new server.
|
||||
|
||||
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.
|
||||
|
||||
**Note:** If you subsequently make any changes to either the `flake.nix` or
|
||||
`disk-config.nix` file, you will need to run the following command in the
|
||||
directory containing the flake to update `flake.lock` before rerunning
|
||||
**nixos-anywhere**:
|
||||
|
||||
```
|
||||
nix flake update
|
||||
```
|
||||
|
||||
For more information on different use cases of **nixos-anywhere** please refer
|
||||
to the [How to Guide](./howtos.md), and for more technical information and
|
||||
explanation of known error messages, refer to the
|
||||
[Reference Manual](./reference.md).
|
||||
|
Loading…
Reference in New Issue
Block a user