nix-community/nixos-anywhere
1
1
Fork 0
mirror of https://github.com/nix-community/nixos-anywhere.git synced 2024-10-26 08:18:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge #115

Browse Source 
115: More changes to documentation r=phaer a=JillThornhill



Co-authored-by: Jill <jill.thornhill@zol.co.zw>
Co-authored-by: zimbatm <zimbatm@zimbatm.com>
Co-authored-by: JillThornhill <jill.thornhill@zol.co.zw>
This commit is contained in:
bors[bot] 2023-05-31 07:11:53 +00:00 committed by GitHub
commit 9caf158d0b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 199 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -4,6 +4,10 @@
<img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" width="150" height="150">
[Documentation Index](docs/INDEX.md)
## README
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
@ -63,7 +67,9 @@ data has been migrated.
## Prerequisites
- Source Machine:
- - Can be any Linux machine with Nix installed, or a NixOS machine.
- Can be any Linux machine with Nix installed, or a NixOS machine.
- Target Machine:
- Unless you're using the option to boot from a NixOS installer image, or

12
docs/INDEX.md Normal file
View File

@ -0,0 +1,12 @@
# Table of Content: - nixos-anywhere
**_Install NixOS everywhere via ssh_**
<img title="" src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" alt="" width="149">
- [README](../README.md)
- [Quickstart](./quickstart.md)
- [System Requirements](./requirements.md)
- [How to Guide](./howtos.md)
- [Support Matrix](./supportmatrix.md)
- [Reference](./reference.md)

35
docs/SUMMARY.md
View File

@ -1,17 +1,20 @@
# Table of Content
# Summary: - nixos-anywhere
- [Introduction](./introduction.md)
- [What is nixos-anywhere?](#)
- [Quickstart](./quickstart.md)
- [Getting Started](#)
- [System Requirements](#)
- [Support Matrix](#)
- [Installation](./installation.md)
- [Bare Metal Platforms](#)
- [Virtualized Platforms](#)
- [Cloud Platforms](#)
- [Local Platforms](#)
- [Single Board Computers](#)
- [Avanced Guides](#)
- [Reference](#)
- [CLI](./cli.md)
**_Install NixOS everywhere via ssh_**
<img title="" src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" alt="" width="149">
The **nixos-anywhere** tool allows you to pre-configure the whole process of
installing NixOS, and run the install remotely with a single CLI command.
Refer to the following documentation for more information.
[Quickstart](./quickstart.md): Instructions for a typical installation
[System Requirements](./requirements.md): CPU and memory requirements
[How to Guide](./howtos.md): Instructions for non-typical use cases
[Support Matrix](./supportmatrix.md): List of tested platforms
[Reference](./reference.md): Reference Guide

68
docs/howtos.md
View File

@ -1,5 +1,11 @@
# How To Guide: nixos-anywhere
**_Install NixOS everywhere via ssh_**
<img title="" src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" alt="" width="129">
[Documentation Index](./INDEX.md)
## Contents
[Installing on a machine with no operating system](#installing-on-a-machine-with-no-operating-system)
@ -10,16 +16,23 @@
## Installing on a machine with no operating system
If your machine does not run any operating system, you can boot the standard
NixOS installer using a USB or netboot. Detailed instructions on how to do this
can be found in the
[NixOS installation guide](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb).
If your machine doesn't currently have an operating system installed, you can
still run `nixos-anywhere` remotely to automate the install. To do this, you
would first need to boot the target machine from the standard NixOS installer.
You can either boot from a USB or use `netboot`.
When you're using `nixos-anywhere`, it will detect a NixOS installer by checking
if the `/etc/os-release` file contains the identifier `VARIANT=installer`
(available since NixOS 23.05). If an installer is detected, `nixos-anywhere`
will not attempt to kexec into its own image. This is particularly useful for
targets that do not have enough RAM for kexec or do not support kexec.
The
[NixOS installation guide](https://nixos.org/manual/nixos/stable/index.html#sec-booting-from-usb)
has detailed instructions on how to boot the installer.
When you run `nixos-anywhere`, it will determine whether a NixOS installer is
present by checking whether the `/etc/os-release` file contains the identifier
`VARIANT=installer`. This identifier is available on releases NixOS 23.05 or
later.
If an installer is detected, `nixos-anywhere`will not attempt to `kexec` into
its own image. This is particularly useful for targets that don't have enough
RAM for `kexec` or don't support `kexec`.
NixOS starts an SSH server on the installer by default, but you need to set a
password in order to access it. To set a password for the `nixos` user, run the
@ -54,7 +67,7 @@ $ ip addr
This will display the IP addresses assigned to your network interface(s),
including the IP address of the installer. In the example output below, the
installer's IP address is `10.0.2.15`, `fec0::5054:ff:fe12:3456`, and
installer's IP addresses are `10.0.2.15`, `fec0::5054:ff:fe12:3456`, and
`fe80::5054:ff:fe12:3456%eth0`:
To test if you can connect and your password works, you can use the following
@ -64,26 +77,32 @@ SSH command (replace the IP address with your own):
ssh -v nixos@fec0::5054:ff:fe12:3456
```
You can then use the IP address and other parameters in nixos-anywhere, like
this:
You can then use the IP address to run `nixos-anywhere` like this:
```
nixos-anywhere --flake '.#' nixos@fec0::5054:ff:fe12:3456
nix run github:numtide/nixos-anywhere -- --flake '.#myconfig' nixos@fec0::5054:ff:fe12:3456
```
This example assumes a flake in the curent directory containing a configuration
named `myconfig`.
## Using your own kexec image
By default, nixos-anywhere downloads the kexec image from the off
By default, `nixos-anywhere` downloads the kexec image from the
[NixOS images repository](https://github.com/nix-community/nixos-images#kexec-tarballs).
However, you can provide your own kexec image file if desired. To do this, use
the `--kexec` command line switch followed by the path to your image file. The
image will be uploaded prior to execution.
However, you can provide your own `kexec` image file if you need to use a
different one. This is particularly useful for architectures other than
`x86_64`, since they don't have a pre-build image.
To do this, use the `--kexec` command line switch followed by the path to your
image file. The image will be uploaded prior to execution.
Here's an example command that demonstrates how to use a custom kexec image with
`nixos-anywhere` for aarch64 instead of the default `x86_64` architecture:
```
nixos-anywhere \
nix run github:numtide/nixos-anywhere -- \
--kexec "$(nix build --print-out-paths github:nix-community/nixos-images#packages.aarch64-linux.kexec-installer-noninteractive-nixos-unstable)/nixos-kexec-installer-noninteractive-aarch64-linux.tar.gz" \
--flake 'github:your-user/your-repo#your-system' \
root@yourip
@ -92,12 +111,15 @@ nixos-anywhere \
Make sure to replace `github:your-user/your-repo#your-system` with the
appropriate Flake URL representing your NixOS configuration.
This is particularly useful for architectures other than `x86_64`, where there
is no pre-build image.
The example above assumes that your local machine can build for aarch64 in one
of the following ways:
The example above assumes that your local machine can build for aarch64 either
natively, through a remote builder or by emulating the architecture with qemu
with the following NixOS configuration:
- Natively
- Through a remote builder
- By emulating the architecture with qemu using the following NixOS
configuration:
```nix
{

7
docs/installation.md
View File

@ -1,7 +0,0 @@
# Installation
- [Bare Metal Platforms](#)
- [Virtualized Platforms](#)
- [Cloud Platforms](#)
- [Local Platforms](#)
- [Single Board Computers](#)

7
docs/introduction.md
View File

@ -1,7 +0,0 @@
# Introduction
- [What is nixos-anywhere?](#)
- [Quickstart](#)
- [Getting Started](#)
- [System Requirements](#)
- [Support Matrix](#)

54
docs/quickstart.md
View File

@ -4,7 +4,9 @@
<img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" width="150" height="150">
## Inroduction
[Documentation Index](./INDEX.md)
## Introduction
This guide documents a simple installation of NixOS using **nixos-anywhere** on
a target machine running x86_64 Linux with
@ -33,7 +35,7 @@ below.
[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.
2. In this directory, run the following command to create a flake.
```
nix flake init
@ -55,20 +57,20 @@ 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)
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:
4. Run the following command to create the `flake.lock` file:
```
nix flake lock
@ -78,21 +80,21 @@ 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`
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:
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`
- `<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)).
- `<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.
- `<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>

43
docs/reference.md
View File

@ -1,13 +1,17 @@
# Reference Manual: nixos-anywhere
**_Install NixOS everywhere via ssh_**
<img title="" src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" alt="" width="141">
[Documentation Index](./INDEX.md)
TODO: Populate this guide properly
## Contents
[Command Line Usage](#command-line-usage)
[Developer guide](#developer-guide)
[Explanation of known error messages](#explanation-of-known-error-messages)
## Command Line Usage
@ -53,7 +57,36 @@ Options:
## Explanation of known error messages
TODO: List actual error messages and meanings. Include:
TODO: Add additional error messages and meanings. Fill in missing explanations
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.
This section lists known error messages and their explanations. Some
explanations may refer to the following CLI syntax:
`nix run github:numtide/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>`
This list is not comprehensive. It's possible you may encounter errors that
originate from the underlying operating system. These should be documented in
the relevant operating system manual.
| Id | Message | Explanation |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | Failure unpacking initrd | You don't have enough RAM to hold `kexec` |
| 2 | Flake <flake_url> does not provide attirbute | The configuration name you specified in your flake URI is not defined as a NixOS configuration in your flake eg if your URI was mydir#myconfig, then myconfig should be included in the flake as `nixosConfigurations.myconfig` |
| 3 | Please specify the name of the NixOS configuration to be installed, as a URI fragment in the flake-uri. | As for error #2 |
| | For example, to use the output nixosConfigurations.foo from the flake.nix, append "#foo" to the flake-uri | |
| 4 | Retrieving host facts via ssh failed. Check with --debug for the root cause, unless you have done so already | TODO: Explain |
| 5 | ssh-host must be set | <ip_address> has not been supplied |
| 6 | <disko_script> and <nixos_system> must be existing store-paths | This occurs if the -s switch has been used to specify the disko script and store path correctly, and the scripts cannot be found at the given URI |
| 7 | flake must be set | This occurs if both the -flake option (use a flake) and the -s option (specify paths directly) have been omitted. Either one or the other must be specified. |
| 8 | no tar command found, but required to unpack kexec tarball | The destination machine does not have a `tar` command available. This is needed to unpack the `kexec`. |
| 9 | no setsid command found, but required to run the kexec script under a new session | The destination machine does not have the `setsid` command available |
| 10 | This script requires Linux as the operating system, but got <operating system> | The destination machine is not running Linux |
| 11 | The default kexec image only support x86_64 cpus. Checkout https://github.com/numtide/nixos-anywhere/#using-your-own-kexec-image for more information. | By default, `nixos-anywhere` uses its own `kexec` image, which will only run on x86_64 CPUs. For other CPU types, you can use your own `kexec` image instead. Refer to the [How To Guide](./howtos#using-your-own-kexec-image) for instructions. |
| 12 | Please specify the name of the NixOS configuration to be installed, as a URI fragment in the flake-uri. | This is a `disko` error. As for Error #2 |
| | For example, to use the output diskoConfigurations.foo from the flake.nix, append \"#foo\" to the flake-uri. | |
| 13 | mode must be either create, mount or zap_create_mount | This is a `disko` error. The `disko` switches have not been used correctly. This could happen if you supplied your own `disko` script using the -s option |
| 14 | disko config must be an existing file or flake must be set | This is a `disko` error. This will happen if the `disko.devices` entry in your flake doesn't match the name of a file in the same location as your flake. |
| | | |
| | | |
| | | |
| | | |

20
docs/requirements.md Normal file
View File

@ -0,0 +1,20 @@
# System Requirements: nixos-anywhere
**_Install NixOS everywhere via ssh_**
<img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" width="150" height="150">
[Documentation Index](./INDEX.md)
## Requirements
- Source Machine:
- Can be any Linux or Mac computer with Nix installed, or a NixOS machine.
- Destination Machine:
- Must be an x86-64 machine unless you are able to supply a `kexec` image for
your CPU type.
- If you're not using the option to boot from a Nixos installer image, it
must:
- Be running x86-64 Linux with kexec support . Most x86_64 Linux systems do
have kexec support.
- Have at least 2.5 GB of RAM, excluding swap.

30
docs/supportmatrix.md Normal file
View File

@ -0,0 +1,30 @@
# Support Matrix: nixos-anywhere
**_Install NixOS everywhere via ssh_**
<img src="https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png" width="150" height="150">
[Documentation Index](./INDEX.md)
## List of tested environments
We have verified that **nixos-anywhere** runs successfully on the environments
listed below.
**kexec boot:**    Indicates whether it can work by using a kexec boot
**Image boot:** Indicates whether it can work if booted from a NixOS installer
**Own kexec:**     Indicates whether it can work if you supply your own kexec
| **Platform** | **Operating System** | kexec boot | Image boot | Own kexec |
| ------------- | -------------------- | ---------- | ---------- | --------- |
| Hetzner Cloud | X86-64 Linux | Yes | Yes | Yes |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
##