2023-05-12 13:41:45 +03:00
|
|
|
|
# nixos-anywhere
|
2022-11-10 18:49:56 +03:00
|
|
|
|
|
2023-05-14 15:08:40 +03:00
|
|
|
|
**_Install NixOS everywhere via ssh_**
|
2023-02-01 22:33:08 +03:00
|
|
|
|
|
2023-05-14 17:11:32 +03:00
|
|
|
|
<img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" width="150" height="150">
|
2022-11-22 23:46:43 +03:00
|
|
|
|
|
2023-05-24 16:12:36 +03:00
|
|
|
|
[Documentation Index](docs/INDEX.md)
|
|
|
|
|
|
|
|
|
|
## README
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
Setting up a new machine is time-consuming, and becomes complicated when it
|
|
|
|
|
needs to be done remotely. If you're installing NixOS, the **nixos-anywhere**
|
|
|
|
|
(formerly known as **nixos-remote**) tool allows you to pre-configure the whole
|
|
|
|
|
process including:
|
2022-11-22 23:46:43 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
- Disk partitioning and formatting
|
2023-06-07 08:40:51 +03:00
|
|
|
|
- Configuring and installing NixOS
|
2023-05-12 13:41:45 +03:00
|
|
|
|
- Installing additional files and software
|
2023-02-02 10:22:40 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
You can then initiate an unattended installation with a single CLI command.
|
|
|
|
|
Since **nixos-anywhere** can access the new machine using SSH, it's ideal for
|
|
|
|
|
remote installations.
|
2023-02-02 10:22:40 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
Once you have initiated the command, there is no need to 'babysit' the
|
|
|
|
|
installation. It all happens automatically.
|
2022-11-22 23:46:43 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
You can use the stored configuration to repeat the same installation if you need
|
|
|
|
|
to.
|
2022-11-22 23:38:11 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
## Overview
|
2023-02-02 10:23:12 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
If you have machines on a mix of platforms, you'll need a common installation
|
|
|
|
|
solution that works anywhere. **nixos-anywhere** is ideal in this situation.
|
2022-11-22 23:38:11 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
**nixos-anywhere** can be used equally well for cloud servers, bare metal
|
|
|
|
|
servers such as Hetzner, and local servers accessible via a LAN. You can create
|
|
|
|
|
standard configurations, and use the same configuration to create identical
|
|
|
|
|
servers anywhere.
|
2022-11-22 23:38:11 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
You first create Nix configurations to specify partitioning, formatting and
|
|
|
|
|
NixOS configurations. Further options can be controlled by a flake and by
|
|
|
|
|
run-time switches.
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
|
|
|
|
Once the configuration has been created, a single command will:
|
|
|
|
|
|
|
|
|
|
- Connect to the remote server via SSH
|
2023-05-14 15:12:42 +03:00
|
|
|
|
- Detect whether a NixOS installer is present; if not, it will use the Linux
|
|
|
|
|
`kexec` tool to boot into a Nixos installer.
|
|
|
|
|
- Use the [disko](https://github.com/nix-community/disko) tool to partition and
|
|
|
|
|
format the hard drive
|
2023-05-12 13:41:45 +03:00
|
|
|
|
- Install NixOS
|
|
|
|
|
- Optionally install any Nix packages and other software required.
|
|
|
|
|
- Optionally copy additional files to the new machine
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
It's also possible to use **nixos-anywhere** to simplify the installation on a
|
|
|
|
|
machine that has no current operating system, first booting from a NixOS
|
|
|
|
|
installer image. This feature is described in the
|
2023-05-14 15:17:09 +03:00
|
|
|
|
[how-to guide](./docs/howtos.md#installing-on-a-machine-with-no-operating-system).
|
2023-05-14 15:12:42 +03:00
|
|
|
|
It's useful because you can pre-configure your required software and
|
|
|
|
|
preferences, and build the new machine with a single command.
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
**Important Note:** Never use a production server as the target. It will be
|
|
|
|
|
completely overwritten and all data lost. This tool should only be used for
|
|
|
|
|
commissioning a new computer or repurposing an old machine once all important
|
|
|
|
|
data has been migrated.
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
|
|
|
|
## Prerequisites
|
|
|
|
|
|
|
|
|
|
- Source Machine:
|
2023-05-30 23:24:24 +03:00
|
|
|
|
|
2023-05-30 13:21:00 +03:00
|
|
|
|
- Can be any machine with Nix installed, e.g. a NixOS machine.
|
2023-05-30 23:24:24 +03:00
|
|
|
|
- Should be able to build nix derivations for the target platform. Otherwise
|
2023-05-30 13:21:00 +03:00
|
|
|
|
`--build-on-remote` can be used.
|
2023-05-14 15:08:40 +03:00
|
|
|
|
|
2023-05-24 15:21:18 +03:00
|
|
|
|
- Target Machine:
|
2023-05-29 15:54:03 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
- Unless you're using the option to boot from a NixOS installer image, or
|
|
|
|
|
providing your own `kexec` image, it must be running x86-64 Linux with kexec
|
2023-05-14 15:28:25 +03:00
|
|
|
|
support. Most `x86_64` Linux systems do have kexec support. By providing
|
|
|
|
|
your own [image](./docs/howtos.md#using-your-own-kexec-image) you can also
|
2023-05-14 15:12:42 +03:00
|
|
|
|
perform kexec for other architectures eg aarch64
|
2023-05-12 13:41:45 +03:00
|
|
|
|
- Must have at least 1.5 GB of RAM, excluding swap.
|
|
|
|
|
|
|
|
|
|
## How to use nixos-anywhere
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
Here’s a quick summary of how to use **nixos-anywhere**. You can find more
|
2023-05-14 15:28:25 +03:00
|
|
|
|
information in the [documentation](./docs).
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
The tool doesn't need to be installed, since it can be run directly from this
|
|
|
|
|
repository.
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
First create a repo that includes the disk configuration and a
|
|
|
|
|
[flake](https://nixos.wiki/wiki/Flakes) to configure your options. This example
|
|
|
|
|
assumes that flakes have been enabled on your source machine.
|
2022-11-22 23:38:11 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
Here’s an example of a simple disk configuration:
|
2022-12-31 14:55:20 +03:00
|
|
|
|
|
2023-05-14 15:08:40 +03:00
|
|
|
|
```nix
|
2023-05-12 13:41:45 +03:00
|
|
|
|
{ disks ? [ "/dev/vda" ], ... }:
|
|
|
|
|
{
|
|
|
|
|
disk = {
|
|
|
|
|
main = {
|
|
|
|
|
type = "disk";
|
|
|
|
|
device = builtins.elemAt disks 0;
|
|
|
|
|
content = {
|
|
|
|
|
type = "table";
|
|
|
|
|
format = "gpt";
|
|
|
|
|
partitions = [
|
|
|
|
|
{
|
|
|
|
|
name = "boot";
|
|
|
|
|
start = "0";
|
|
|
|
|
end = "1M";
|
|
|
|
|
flags = [ "bios_grub" ];
|
|
|
|
|
}
|
|
|
|
|
{
|
|
|
|
|
name = "ESP";
|
|
|
|
|
start = "1M";
|
|
|
|
|
end = "512M";
|
|
|
|
|
bootable = true;
|
|
|
|
|
content = {
|
|
|
|
|
type = "filesystem";
|
|
|
|
|
format = "vfat";
|
|
|
|
|
mountpoint = "/boot";
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
{
|
|
|
|
|
name = "root";
|
|
|
|
|
start = "512M";
|
|
|
|
|
end = "100%";
|
|
|
|
|
content = {
|
|
|
|
|
type = "filesystem";
|
|
|
|
|
format = "ext4";
|
|
|
|
|
mountpoint = "/";
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
];
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
}
|
2022-12-31 14:55:20 +03:00
|
|
|
|
```
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
The
|
|
|
|
|
[disko repository](https://github.com/nix-community/disko/tree/master/example)
|
|
|
|
|
has several examples of disk configurations. You can adapt them to our own
|
|
|
|
|
needs.
|
2022-12-31 14:55:20 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
A simple flake may look like this:
|
2022-12-31 14:55:20 +03:00
|
|
|
|
|
2023-05-14 15:08:40 +03:00
|
|
|
|
```nix
|
2023-05-12 13:41:45 +03:00
|
|
|
|
{
|
|
|
|
|
inputs.nixpkgs.url = github:NixOS/nixpkgs;
|
|
|
|
|
inputs.disko.url = github:nix-community/disko;
|
|
|
|
|
inputs.disko.inputs.nixpkgs.follows = "nixpkgs";
|
|
|
|
|
outputs = { self, nixpkgs, disko, ... }@attrs: {
|
2023-05-14 15:28:25 +03:00
|
|
|
|
#-----------------------------------------------------------
|
|
|
|
|
# The following line names the configuration as hetzner-cloud
|
|
|
|
|
# This name will be referenced when nixos-remote is run
|
|
|
|
|
#-----------------------------------------------------------
|
2023-05-12 13:41:45 +03:00
|
|
|
|
nixosConfigurations.hetzner-cloud = nixpkgs.lib.nixosSystem {
|
|
|
|
|
system = "x86_64-linux";
|
|
|
|
|
specialArgs = attrs;
|
|
|
|
|
modules = [
|
|
|
|
|
({modulesPath, ... }: {
|
|
|
|
|
imports = [
|
|
|
|
|
(modulesPath + "/installer/scan/not-detected.nix")
|
|
|
|
|
(modulesPath + "/profiles/qemu-guest.nix")
|
|
|
|
|
disko.nixosModules.disko
|
|
|
|
|
];
|
|
|
|
|
disko.devices = import ./disk-config.nix {
|
|
|
|
|
lib = nixpkgs.lib;
|
|
|
|
|
};
|
|
|
|
|
boot.loader.grub = {
|
|
|
|
|
devices = [ "/dev/sda" ];
|
|
|
|
|
efiSupport = true;
|
|
|
|
|
efiInstallAsRemovable = true;
|
|
|
|
|
};
|
|
|
|
|
services.openssh.enable = true;
|
2023-05-14 15:28:25 +03:00
|
|
|
|
#-------------------------------------------------------
|
|
|
|
|
# Change the line below replacing <insert your key here>
|
|
|
|
|
# with your own ssh public key
|
|
|
|
|
#-------------------------------------------------------
|
2023-05-12 13:41:45 +03:00
|
|
|
|
users.users.root.openssh.authorizedKeys.keys = [ "<insert your key here>" ];
|
|
|
|
|
})
|
|
|
|
|
];
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
}
|
2022-12-31 14:55:20 +03:00
|
|
|
|
```
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
Once you’ve created the disk configuration and the flake, you can run the tool
|
|
|
|
|
with a single nix command, which may look like this:
|
2022-12-31 14:55:20 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
```
|
2023-08-18 21:05:18 +03:00
|
|
|
|
nix run github:numtide/nixos-anywhere -- --flake <flake URL> <SSH destination>
|
|
|
|
|
# Example:
|
|
|
|
|
# nix run github:numtide/nixos-anywhere -- --flake .#hetzner-cloud root@135.181.254.201
|
2022-12-31 14:55:20 +03:00
|
|
|
|
```
|
2023-01-12 17:26:01 +03:00
|
|
|
|
|
2023-05-14 16:32:43 +03:00
|
|
|
|
Note that this command references the URL of your flake, in this case `.#`,
|
|
|
|
|
together with the name of the system `hetzner-cloud`, as highlighted by the
|
|
|
|
|
comment in the sample flake.
|
2023-01-12 17:26:01 +03:00
|
|
|
|
|
2023-07-09 12:48:36 +03:00
|
|
|
|
This will configure and build the new NixOS server. Since the configurations are
|
|
|
|
|
defined in the flake, it will not create `/etc/nixos/configuration.nix`. If you
|
|
|
|
|
need to make changes to the configuration in future, you should make the changes
|
|
|
|
|
in the flake, and rebuild using the --flake option as shown below:
|
2023-07-09 11:43:57 +03:00
|
|
|
|
|
|
|
|
|
```
|
2023-08-18 21:05:18 +03:00
|
|
|
|
nixos-rebuild --flake <flake URL> --target-host <SSH destination> switch
|
|
|
|
|
# Example:
|
|
|
|
|
# nixos-rebuild --flake .#hetzner-cloud --target-host root@135.181.254.201 switch
|
2023-07-09 11:43:57 +03:00
|
|
|
|
```
|
|
|
|
|
|
2023-05-14 15:17:09 +03:00
|
|
|
|
The [Quickstart Guide](./docs/quickstart.md) gives more information on how to
|
2023-05-14 15:12:42 +03:00
|
|
|
|
run **nixos-anywhere** in its simplest form. For more specific instructions to
|
2023-05-14 15:17:09 +03:00
|
|
|
|
suit individual requirements, see the [How To Guide](./docs/howtos.md).
|
2023-01-12 17:26:01 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
# Further Reading
|
2023-01-12 17:26:01 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
@tfc has written a walkthrough on how use **nixos-anywhere** to bootstrap
|
|
|
|
|
hetzner cloud servers as well as dedicated machines on his
|
|
|
|
|
[blog](https://galowicz.de/2023/04/05/single-command-server-bootstrap/):
|
2023-01-12 17:26:01 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
## Related Tools
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
**nixos-anywhere** makes use of the
|
|
|
|
|
[disko](https://github.com/nix-community/disko) tool to handle the partitioning
|
|
|
|
|
and formatting of the disks.
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
|
|
|
|
## Licensing and Contribution details
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
This software is provided free under the
|
|
|
|
|
[MIT Licence](https://opensource.org/licenses/MIT).
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
This project is supported by [Numtide](https://numtide.com/).
|
|
|
|
|
![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d)
|
2023-05-12 13:41:45 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
We are a team of independent freelancers that love open source. We help our
|
|
|
|
|
customers make their project lifecycles more efficient by:
|
2023-04-05 15:26:39 +03:00
|
|
|
|
|
2023-05-12 13:41:45 +03:00
|
|
|
|
- Providing and supporting useful tools such as this one
|
|
|
|
|
- Building and deploying infrastructure, and offering dedicated DevOps support
|
|
|
|
|
- Building their in-house Nix skills, and integrating Nix with their workflows
|
|
|
|
|
- Developing additional features and tools
|
|
|
|
|
- Carrying out custom research and development.
|
2023-04-05 15:26:39 +03:00
|
|
|
|
|
2023-05-14 15:12:42 +03:00
|
|
|
|
[Contact us](https://numtide.com/contact) if you have a project in mind, or if
|
|
|
|
|
you need help with any of our supported tools, including this one. We'd love to
|