Machine folder, layout and migration

Each host has its own usr/machines/<hôte>/ folder. Files there are organised by who writes them : you, the installation, the machine itself or the generator. The framework imports them one by one, there is no default.nix.

Layout

usr/machines/<hôte>/
  configuration.nix              # vous : seul fichier à éditer
  <autres>.nix                   # vous : importés depuis configuration.nix
  install/
    disko.nix                    # disposition du disque, figée à l'installation
    state.nix                    # system.stateVersion, figé à l'installation
  hardware/
    hardware-configuration.nix   # relevé sur la machine
    detected-hardware.nix        # pilotes réseau relevés (just detect-hw)

var/generated/hosts/<hôte>.nix   # drapeaux de démarrage déduits du disque

File	Written by	Rewritten	If lost
configuration.nix	you (seeded by just generate)	never	work lost
install/disko.nix	just generate (profile and devices)	as long as the host is not installed	actual disk layout unknown
install/state.nix	just install, just install-key	never	inconsistent service data
hardware/	just install, copy-hw, detect-hw	on each capture	recapture needed on the machine
var/generated/hosts/<hôte>.nix	just generate	on each generation	nothing, it is recomputed

var/generated/hosts/<hôte>.nix only exists if the disk requires boot settings (software RAID, NEEDEDFORBOOT markers).

The installation seal

install/state.nix seals the host. just install writes it just before formatting, with the current nixpkgs release (the value nixos-generate-config would write).

• Before: install/disko.nix follows etc/config.yaml on each just generate.
• After: install/disko.nix no longer changes. The disko block in etc/config.yaml has no more effect.

Need	Action
Reinstall identically (restore, databases)	do nothing
Change disk while keeping data	delete install/disko.nix, then just generate
Start from a like-new machine, without recovery	delete install/state.nix

Don’t delete state.nix from a host with data

system.stateVersion sets the defaults related to persistent data (PostgreSQL major version for example). A more recent value on restored data creates an empty cluster next to the old one. See Migrating gateway hardware.

Don’t edit install/disko.nix before installation

just generate rewrites it. A specific layout goes in a usr/hosts/disko/<nom>.nix profile, referenced by disko.profile. A local profile shadows the framework profile of the same name.

Host without state.nix

A host with a machine folder but without install/state.nix uses the current nixpkgs release as stateVersion, and evaluation shows a warning : deployed as is, it would change it at every nixpkgs upgrade.

Migrating from the old layout

Breaking change : the old layout (default.nix imported as entry point) is no longer read.

Old	New
default.nix	configuration.nix, without imports or stateVersion
system.stateVersion from default.nix	install/state.nix
disko.nix	install/disko.nix
hardware-configuration.nix	hardware/hardware-configuration.nix
detected-hardware.nix	hardware/detected-hardware.nix
generated-configuration.nix	var/generated/hosts/<hôte>.nix, generated

1. Find the forced devices in the old generated-configuration.nix (disko.devices.disk.<disque>.device = lib.mkForce "…" lines). They are no longer generated.

2. Move the files

   cd usr/machines/<hôte>
   mkdir -p install hardware
   git mv disko.nix install/disko.nix
   git mv hardware-configuration.nix hardware/   # si présent
   git mv detected-hardware.nix hardware/        # si présent
   git mv default.nix configuration.nix
   git rm generated-configuration.nix

3. Port the devices found in step 1 to install/disko.nix, when they differ from the device value in the file.

4. Create install/state.nix with the exact value of the old system.stateVersion :

   # usr/machines/<hôte>/install/state.nix
   { system.stateVersion = "25.11"; }

5. Lighten configuration.nix : remove the imports of not-detected.nix, generated-configuration.nix, hardware-configuration.nix, disko.nix, detected-hardware.nix and the system.stateVersion line. Keep everything else.

6. Regenerate and commit

   just clean
   git add usr/machines var/generated

state.nix before any just generate

Without install/state.nix, a host whose disko block is still present is not sealed : just generate rewrites its install/disko.nix from the profile.

Local profiles

Framework profiles replace hard-coded disk paths with @DEVICE:<disque>@ tokens, filled from disko.devices. A profile in usr/hosts/disko/ must do the same, or be used without devices.