Initial installation

A DNF network is set up step by step, and you can stop at any stage: a single workstation is enough to get started.

The journey

1. A workstation: the administrator’s machine (this page).
2. A gateway: create a zone and connect other workstations to it.
3. Coordination: link the zones together with a VPN (tailnet).

A single configuration

All nodes are described in one NixOS configuration, on the administrator’s machine. From there, the whole network is deployed and evolved. This machine is itself a DNF host: the administration recipes run under its nix deployment account.

Assisted installation

The first workstation installs itself, from the generic ISO, with no other machine: this is the simplest path.

Try it first in a VM

On a Linux with Nix and KVM, a single command boots the ISO in a QEMU window, virtual disk included:

nix run github:darkone-linux/darkone-nixos-framework#try

The disk is kept from one run to the next (~/.local/share/dnf-try); nix run …#try -- --reset starts from scratch.

1. Get the image

   The generic ISO attached to each framework release 🡕 (dnf-installer-vX.Y.Z-x86_64-linux.iso), written to a USB stick.

2. Boot the machine from the stick, wired, Secure Boot disabled.

3. Answer the wizard

   It launches on its own on the console, once the network is up. Ctrl-C gives the command prompt, from where it restarts:

   darkone new

   It asks for the language and keyboard, the administrator’s identity and password, the network domain, the machine name, the disk if there are several (not below 20 GB: the backup key is never offered), then disk encryption and its passphrase. The rest is detected: laptop or desktop, UEFI or BIOS, the country’s time zone. Unencrypted disk: a passphrase for the key backup.

4. Confirm

   The summary shows the final choices (domain, login). The disk is then erased and the system installed, project included, in /etc/nixos.

5. Back up the keys, on a second USB stick

   Plug in a USB stick (FAT, exFAT, ext4…), select it: nothing on it is erased. The wizard writes dnf-backup-<domain>.tar.age to it, then asks you to unplug and replug it to read it back. No reread backup, no end of installation.

6. Reboot, USB sticks removed. Encrypted disk: the passphrase is requested at every boot, with the chosen keyboard. The first session opens a home page in the browser: step 1 of 4 done, the gateway next.

Without a backup, a lost disk takes all the secrets with it

The nix deployment key, the infra age key and the project only exist on this workstation. The backup, encrypted with the disk’s passphrase (or the backup’s passphrase, unencrypted disk), contains them all: store it away from the machine.

The disk passphrase is the fleet’s passphrase

It becomes the shared passphrase (luks-passphrase): every encrypted host installed afterwards is formatted with it. Encryption requires UEFI. See Disk encryption (LUKS).

Scripted installation

An answers file stands in for the questions; a missing answer is requested, or refused with --non-interactive.

reponses.yaml

version: 1
admin:
  login: "alice"
  name: "Alice Martin"
  passwordHash: '$y$j9T$...'    # mkpasswd -m yescrypt
network:
  domain: "example.org"
host:
  hostname: "poste"
disk:
  encrypt: true
locale:
  language: "fr_FR.UTF-8"
backup:
  device: "/dev/disk/by-label/SECOURS"   # clé USB de la sauvegarde

darkone new --answers reponses.yaml --non-interactive --yes \
  --luks-passphrase-file /run/user/1000/luks

The disk passphrase never goes into the answers file, which circulates: --luks-passphrase-file reads it from a file, otherwise it is requested. It also encrypts the backup; unencrypted disk, that is --backup-passphrase-file. In scripted mode, the USB stick is reread without being unplugged.

Key backup

dnf-backup-<domain>.tar.age, encrypted with age, contains:

• nix/: the (SSH) deployment key and the admin age key derived from it;
• infra.key: the infra age key;
• project.bundle: the project, /etc/nixos, as a git bundle.

To open it, on any Linux with age:

age -d dnf-backup-example.org.tar.age | tar -x
git clone dnf-backup/project.bundle mon-reseau

On a new administration workstation, the keys go back in place, under the nix account, in mode 600: /home/nix/.ssh/id_ed25519, /home/nix/.config/sops/age/keys.txt and /etc/sops/age/infra.key. As the project evolves: just backup-admin <device> redoes the backup (recipes).

--dry-run prints the plan without touching anything, on any machine.

Creating the project

Manual path, from an administration machine that is already a DNF host. The project starts from the template provided by the framework: a ready-made structure and a commented etc/config.yaml to fill in.

1. Create the repository

   nix flake new -t github:darkone-linux/darkone-nixos-framework mon-reseau
   cd mon-reseau && git init && git add -A

   The project pins the latest framework release. Another path: the GitHub template dnf-boilerplate 🡕 (the “Use this template” button), a published copy of the same template.

2. Bootstrap the framework

   nix run github:darkone-linux/darkone-nixos-framework#init
   nix develop github:darkone-linux/darkone-nixos-framework

   What does #init do?

   It creates the dnf/ symlink to the framework tree in the nix store: that is what gives just its recipes and the generator its profiles. Then just --list lists all available commands.

   Once the project has its own flake.lock, refresh this symlink with nix run .#init: this form follows the revision pinned by the project, so the tooling never diverges from the built system.

3. Initialize the secrets

   just configure-admin-host

   Idempotent

   Creates the age keys, the .sops.yaml file, the reference password and the internal secrets of the declared services. It never recreates what already exists: rerun it after every new service, host or zone.

Describing the configuration

Everything is declared in etc/config.yaml (network, zones, users, hosts). For a first workstation, one zone, one user and one host suffice: every host belongs to a zone (or carries a public ipv4 address).

An editor with yaml-language-server (Zed, VS Code with the YAML extension…) completes and validates every key, thanks to this first line of the file (already present in a project created from the template):

# yaml-language-server: $schema=../dnf/config/config.schema.json

etc/config.yaml

zones:
  main:
    description: "Réseau principal"
    ipPrefix: "10.0"          # cette zone utilise 10.0.0.0/16

users:
  alice:
    uid: 1000
    name: "Alice"
    profile: "nix-admin"
    groups: ["global"]

hosts:
  - hostname: "poste"
    name: "Poste de l'administrateur"
    zone: "main:1.10"         # IP fixe 10.0.1.10 ("main" seul = DHCP)
    profile: "desktop"
    users: ["alice"]
    disko:
      profile: "btrfs-1-disk"
      devices:
        main: "/dev/nvme0n1"

Then regenerate, check and commit:

just generate      # produit var/generated/*.nix depuis etc/config.yaml
just check-flake   # nix flake check
git add . && git commit -m "Premier hôte"

Generated files

var/generated/ is produced by the tool: never edit it by hand. Edit etc/config.yaml, then regenerate. just generate also seeds the files the framework expects: usr/users/<login>/ for each account and usr/machines/<host>/ (configuration.nix, install/disko.nix) for each host with a disko block.

Commit before building

Nix flakes only see files tracked by git. An uncommitted var/generated/hosts.nix or usr/machines/<host>/ makes every build fail.

Installing a workstation

The installation writes an image, boots the machine from it, then applies the full system.

1. Get the image

   just build-iso

   This image carries your deployment key. Another path, without building: the generic ISO attached to each framework release 🡕 (dnf-installer-vX.Y.Z-x86_64-linux.iso); the key then authorizes itself at boot.

2. Boot the machine

   Write the image to a USB stick, plug the computer into the network wired, then boot from the stick. Before the command prompt, the screen shows a DNF welcome message, then the IP address and MAC address of the interface connected to the Internet (served by the local gateway or your router): note them down.

   - IP: 10.0.0.50
   - MAC: aa:bb:cc:dd:ee:ff

   The dnf-netinfo command displays them again.

   With the generic ISO, the screen reminds you: set a password (passwd), then authorize the key from the admin workstation.

   sudo -i -u nix ssh-copy-id nixos@10.0.0.50

3. Set the addresses (as soon as a zone exists)

   The installation ends with a reboot, and the next steps must find the machine again. Two cases:

   • MAC address already declared: nothing to do, the gateway serves the same static address to the USB stick and the installed system;
   • MAC address unknown: read it, then declare it.

   # just host-info <hôte> <ip-actuelle>
   just host-info poste 10.0.0.50

   Enter the value in etc/config.yaml, with a static address, then redeploy the gateway of each affected zone:

   etc/config.yaml

   - hostname: "poste"
     zone: "maison:2.1"
     mac: "aa:bb:cc:dd:ee:ff"

   Outside the dynamic DHCP range

   The static address must be outside the zone’s dhcp-range (by default <prefix>.3.200 to <prefix>.3.249). Inside the range, the reservation is only honored as long as the address has not already been lent to someone else: the machine then changes address at its first boot, silently. The generator refuses this case.

   # Redéployer la passerelle locale
   just clean
   git add . && git commit -m "host(poste): installation"
   just apply gw

4. Install the system

   Before starting the installation

   Make sure the machine reboots by default onto the disk that will hold the system, not the installation USB stick.

   # just full-install <hôte> <utilisateur> <ip>
   just full-install poste nixos 10.0.0.50

   In a few minutes

   full-install installs the system, the programs, the configurations and the users. When it reboots automatically, it probes all known addresses of the machine (the installation one, its zone one, the transient one, its name) and continues on whichever answers. On an encrypted host, it also answers the LUKS prompt by itself. In case of failure, the detailed steps are in the Justfile.

   Installing over an existing system

   A machine already running may hold a dynamic lease older than its reservation. nixos-anywhere freezes its target address for the whole run: as soon as its installer does a new DHCP, the machine switches to its reserved address and the run talks into the void.

   The recipe now refuses to boot on an address the host does not keep. The simplest fix is to reboot the machine before installing, so it takes its reserved address.

   If the case still occurs, nothing is lost: the installer is already loaded in memory on the machine, at the right address this time. Just rerun it there; the loading phase is skipped automatically:

   just full-install poste root 10.0.2.1

5. The system is installed and up to date.

You can stop here

A standalone workstation is already fully usable. The gateway is only needed to create a zone (shared local network).