Prepare physical machines

Summary

To install Clan on physical machines, you need to start our custom installer image from a boot device. The minimal system will then be reachable by your setup machine and a deployment can be triggered remotely.

If you only plan to use virtual machines, you can skip this step.

Why nixos-anywhere Doesn't Work on Physical Hardware?

nixos-anywhere relies on kexec to replace the running kernel with our custom one. This method often has compatibility issues with real hardware, especially systems with dedicated graphics cards like laptops and servers, leading to crashes and black screens.

Reasons for a Custom Install Image

Our custom install images are built to include essential tools like nixos-facter and support for ZFS. They're also optimized to run on systems with as little as 1 GB of RAM, ensuring efficient performance even on lower-end hardware.

Requirements

Estimated time for this step: 20 minutes
A USB drive with at least 1.5GB total space (!! all data will be lost !!)
A Linux/NixOS machine with internet access to create the boot stick. You can use your setup device or any other machine for this step.
One or more physical target machines (!! all data will be lost !!)

Minimum target system requirements: 2 CPUs, 4GB RAM, 30gb HDD space, network interface

Identify the USB Flash Drive

Insert your USB flash drive into the Linux computer you want to create the boot stick on.

Identify your flash drive with lsblk:

lsblk

NAME                                          MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
sdb                                             8:0    1 117,2G  0 disk
└─sdb1                                          8:1    1 117,2G  0 part  /run/media/qubasa/INTENSO
nvme0n1                                       259:0    0   1,8T  0 disk
├─nvme0n1p1                                   259:1    0   512M  0 part  /boot
└─nvme0n1p2                                   259:2    0   1,8T  0 part
  └─luks-f7600028-9d83-4967-84bc-dd2f498bc486 254:0    0   1,8T  0 crypt /nix/store

In this case the USB device is sdb

Ensure all partitions on the drive are unmounted. Replace sdb1 in the command below with your device identifier (like sdc1, etc.):

sudo umount /dev/sdb1

Installer Creation

Linux OSOther OS

Create a Custom Installer

We recommend to build your own installer because of the following reasons:

Include your ssh public keys into the image that allows passwordless ssh connection later on.
Set your preferred language and keymap

clan flash write --flake https://git.clan.lol/clan/clan-core/archive/main.tar.gz \
  --ssh-pubkey $HOME/.ssh/id_ed25519.pub \
  --keymap us \
  --language en_US.UTF-8 \
  --disk main /dev/sd<X> \
  flash-installer

Note

Replace $HOME/.ssh/id_ed25519.pub with a path to your SSH public key. Replace /dev/sd<X> with the drive path you want to flash

Specifying the wrong device can lead to unrecoverable data loss.

The clan flash utility will erase the disk. Make sure to specify the correct device

SSH-Pubkey Option

To add an ssh public key into the installer image append the option:
```
--ssh-pubkey <pubkey_path>
```
If you do not have an ssh key yet, you can generate one with ssh-keygen -t ed25519 command. This ssh key will be installed into the root user.
Connect to the installer

On boot, the installer will display on-screen the IP address it received from the network. If you need to configure Wi-Fi first, refer to the next section. If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the flash-installer.local address.
List Keymaps

You can get a list of all keymaps with the following command:
```
clan flash list keymaps
```
List Languages

You can get a list of all languages with the following command:
```
clan flash list languages
```

Download Generic Installer

For x86_64:

wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-x86_64-linux.iso

For generic arm64 / aarch64 (probably does not work on raspberry pi...)

wget https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-installer-aarch64-linux.iso

Note

If you don't have wget installed, you can use curl --progress-bar -OL <url> instead.

Flash the Installer to the USB Drive

Specifying the wrong device can lead to unrecoverable data loss.

The dd utility will erase the disk. Make sure to specify the correct device (of=...)

For example if the USB device is sdb use of=/dev/sdb (on macOS it will look more like /dev/disk1)

On Linux, you can use the lsblk utility to identify the correct disko

lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT

On macos use diskutil:

diskutil list

Use the dd utility to write the NixOS installer image to your USB drive. Replace /dev/sd<X> with your external drive from above.

sudo dd bs=4M conv=fsync status=progress if=./nixos-installer-x86_64-linux.iso of=/dev/sd<X>

**Connect to the installer

On boot, the installer will display on-screen the IP address it received from the network. If you need to configure Wi-Fi first, refer to the next section. If Multicast-DNS (Avahi) is enabled on your own machine, you can also access the installer using the nixos-installer.local address.

Checkpoint 1: Boot From USB Stick on Target Device

To see if your new Clan USB boot stick works, plug it into a target device and boot from the USB drive with secure boot turned off.

For step by step instructions go to Disabling Secure Boot

(Optional) Connect to Wifi Manually

If you don't have access via LAN the Installer offers support for connecting via Wifi.

iwctl

This will enter iwd

[iwd]#

Now run the following command to connect to your Wifi:

# Identify your network device.
device list

# Replace 'wlan0' with your wireless device name
# Find your Wifi SSID.
station wlan0 scan
station wlan0 get-networks

# Replace your_ssid with the Wifi SSID
# Connect to your network.
station wlan0 connect your_ssid

# Verify you are connected
station wlan0 show

If the connection was successful you should see something like this:

State                 connected
Connected network     FRITZ!Box (Your router device)
IPv4 address          192.168.188.50 (Your new local ip)

Press Ctrl+D to exit IWD.

Important

Press Ctrl+D again to update the displayed QR code and connection information.

Image Installer

The installer will randomly generate a password and local addresses on boot, then run a SSH server with these preconfigured. The installer shows its deployment relevant information in two formats, a text form, as well as a QR code. This is an example of the booted installer.

┌─────────────────────────────────────────────────────────────────────────────────────┐
│ ┌───────────────────────────┐                                                       │
│ │███████████████████████████│ # This is the QR Code (1)                             │
│ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│                                                       │
│ │██ █   █ █▀▄▄▄█ ▀█ █   █ ██│                                                       │
│ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│                                                       │
│ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│                                                       │
│ │███▀▀▀ █▄▄█ ▀▄   ▄▀▄█   ███│                                                       │
│ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│                                                       │
│ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│                                                       │
│ │██ █   █ █ █  █ ▄▄▄  ▄▀▀ ██│                                                       │
│ │██ █▄▄▄█ █ ▄ ▄    ▄ ▀█ ▄███│                                                       │
│ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│                                                       │
│ │███████████████████████████│                                                       │
│ └───────────────────────────┘                                                       │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │Root password: cheesy-capital-unwell  # password (2)                             │ │
│ │Local network addresses:                                                         │ │
│ │enp1s0           UP    192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │
│ │enp2s0           DOWN                                                            │ │
│ │wlan0            DOWN # connect to wlan (3)                                      │ │
│ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion    │ │
│ │Multicast DNS: nixos-installer.local                                             │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ Press 'Ctrl-C' for console access                                                   │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

1. This is not an actual QR code, because it is displayed rather poorly on text sites. This would be the actual content of this specific QR code prettified:

{
    "pass": "cheesy-capital-unwell",
    "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion",
    "addrs": [
    "2001:9e8:347:ca00:21e:6ff:fe45:3c92"
    ]
}

To generate the actual QR code, that would be displayed use:

echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8

2. The root password for the installer medium. This password is autogenerated and meant to be easily typeable.

Tip

For easy sharing of deployment information via QR code, we highly recommend using KDE Connect.

There are two ways to deploy your machine:

Generating a Hardware Report

The following command will generate a hardware report with nixos-facter and writes it back into your machine folder. The --phases kexec flag makes sure we are not yet formatting anything, instead if the target system is not a NixOS machine it will use kexec to switch to a NixOS kernel.

PasswordQR Code

Password

clan machines install [MACHINE] \
    --update-hardware-config nixos-facter \
    --phases kexec \
    --target-host root@192.168.178.169

QR Code Using a JSON String or File Path: Copy the JSON string contained in the QR Code and provide its path or paste it directly:

clan machines install [MACHINE] --json [JSON] \
    --update-hardware-config nixos-facter \
    --phases kexec

Using an Image Containing the QR Code: Provide the path to an image file containing the QR code displayed by the installer:

clan machines install [MACHINE] --png [PATH] \
    --update-hardware-config nixos-facter \
    --phases kexec

If you are using our template [MACHINE] would be jon

Up Next

If all your machines are physical, you can continue with disk preparations here:

Next Step (Choose Disk Format)

Alternatively, feel free to also add virtual machines into the mix during the next step!