mirror of
https://github.com/nix-community/nixos-anywhere.git
synced 2024-10-26 08:18:11 +03:00
Merge #115
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:
commit
9caf158d0b
@ -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
12
docs/INDEX.md
Normal 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)
|
@ -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
|
||||
|
@ -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
|
||||
{
|
||||
|
@ -1,7 +0,0 @@
|
||||
# Installation
|
||||
|
||||
- [Bare Metal Platforms](#)
|
||||
- [Virtualized Platforms](#)
|
||||
- [Cloud Platforms](#)
|
||||
- [Local Platforms](#)
|
||||
- [Single Board Computers](#)
|
@ -1,7 +0,0 @@
|
||||
# Introduction
|
||||
|
||||
- [What is nixos-anywhere?](#)
|
||||
- [Quickstart](#)
|
||||
- [Getting Started](#)
|
||||
- [System Requirements](#)
|
||||
- [Support Matrix](#)
|
@ -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>
|
||||
|
@ -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
20
docs/requirements.md
Normal 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
30
docs/supportmatrix.md
Normal 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 |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
| | | | | |
|
||||
|
||||
##
|
Loading…
Reference in New Issue
Block a user