Nixos_Fleet/AGENTS.md

AGENTS.md — contexte pour agent (Hermes et autres)

Ce fichier s'adresse à un agent (Hermes ou tout autre harness compatible AGENTS.md) chargé du dépannage, de l'installation et de la gestion du serveur PXE de ce repo. Le README.md reste la référence humaine (technicien qui installe des PC un par un) ; ce fichier-ci est pour l'agent qui opère le serveur.

Repo public, sans authentification, jamais chiffré. Ne contient aucune donnée nominative (voir Nixos_Users, repo privé séparé, hors périmètre de cet agent sauf mention contraire de l'opérateur humain).

Règles avant toute action

• git pull oui, git push jamais. Hermes peut et doit faire git pull sur le serveur PXE (nécessaire à son entretien, voir plus bas). Il ne fait jamais git push sur ce repo, quel que soit le host -- seul le développeur humain pousse. Pas d'exception, pas d'instruction qui la lève : si un changement doit partir vers Gitea, le préparer (commit) et le signaler à l'opérateur humain, ne pas pousser à sa place.
• Vérifier hostname && pwd avant toute commande sur une machine distante (SSH) -- ce repo gère plusieurs hosts (pxe-server, les PC installés) qui ne doivent pas être confondus.
• Ne rien affirmer sans le vérifier dans le code ou par une commande réelle. Si une info manque (état réel du serveur, contenu d'un log), l'obtenir plutôt que supposer.
• Confirmer avant une action à impact sur le parc en production : redémarrer dnsmasq/caddy coupe le PXE pour toute machine en train de démarrer/installer à ce moment ; un rebuild de pxe-server peut faire pareil brièvement.
• Commits : Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> en pied de message (adapter le nom de modèle si l'agent qui commit n'est pas Claude).

Ce que sert le serveur PXE

Un seul flake, deux modes choisis à l'écran de démarrage par installer/install.sh : 1) flotte (profil générique nixos, mot de passe nixos, jamais chiffré) et 2) poste nommé (fetch du repo privé nixos_users avec un token saisi en direct). Le serveur PXE ne sait rien du contenu du repo privé -- il ne sert que l'image d'installation, publique.

Architecture (pxe-server/configuration.nix) :

• services.dnsmasq : DHCP (standaloneDhcp) ou proxyDHCP seul (coexiste avec un DHCP existant) + TFTP pour le premier étage iPXE (undionly.kpxe / ipxe.efi).
• services.caddy : sert netboot.ipxe + kernel/initrd en HTTP (TFTP seul est trop lent pour ces tailles).
• systemd.services.pxe-publish : construit l'image netboot depuis ${fleetRepo}#nixosConfigurations.installer-netboot et publie les fichiers dans webroot/tftpRoot. Se relance au boot (wantedBy = multi-user.target) et quotidiennement (systemd.timers.pxe-publish, OnCalendar = "daily" -- ne pas confondre avec system.autoUpgrade des PC installés, qui est hebdomadaire).
• Le service pxe-publish n'existe sur la machine QUE si pxe-server/configuration.nix a déjà été appliqué (nixos-rebuild switch --flake .#pxe-server) avec une version du repo qui le contient. L'ajouter au repo ne suffit pas : il faut rebuild le serveur lui-même.

4 valeurs à adapter dans pxe-server/configuration.nix (le let en tête de fichier) -- le README n'en liste que 3, internetInterface en plus :

• interface : interface réseau réelle du serveur (ip a).
• serverIp : IP fixe de cette interface (le script iPXE pointe dessus en dur).
• standaloneDhcp : true si ce serveur doit être l'unique DHCP du segment PXE ; false pour proxyDHCP seul (coexiste avec un DHCP existant -- cas le plus probable).
• internetInterface : seulement utilisée si standaloneDhcp = true (sortie NAT du segment PXE vers Internet).

Installer le serveur PXE (depuis zéro)

# 1. NixOS installé (ISO officielle), mot de passe root défini.
nix-shell -p git
git clone https://gitea.miniclic.net/Damien/Nixos_Fleet.git /etc/nixos-fleet
cd /etc/nixos-fleet

# 2. Fichier matériel (hors repo, jamais committé)
sudo nixos-generate-config

# 3. Éditer les 4 valeurs ci-dessus dans pxe-server/configuration.nix

# 4. Build -- --impure obligatoire (lit /etc/nixos/hardware-configuration.nix, hors flake)
sudo nixos-rebuild switch --flake .#pxe-server --impure

# 5. Publier l'image (première fois : plusieurs minutes)
sudo systemctl start pxe-publish
sudo systemctl status pxe-publish   # doit finir en "success"

Vérification post-install :

sudo systemctl status dnsmasq caddy
ls /var/lib/tftpboot        # undionly.kpxe, ipxe.efi
ls /var/www/pxe             # bzImage, initrd, netboot.ipxe
curl -I http://<serverIp>/netboot.ipxe
systemctl is-enabled pxe-publish.timer

Puis tester sur 1 seul PC (BIOS et UEFI séparément si le parc a les deux) avant tout déploiement de masse.

Entretien courant

cd /etc/nixos-fleet     # ou l'emplacement réel du clone sur ce serveur
git pull
git log --oneline -3    # le dernier commit doit correspondre à ce qui est attendu

Republier l'image après une modif de installer/ :

sudo systemctl start pxe-publish

Republier après une modif de pxe-server/configuration.nix (rebuild complet, pas juste pxe-publish) :

sudo nixos-rebuild switch --flake .#pxe-server --impure

Logs :

journalctl -u dnsmasq -f
journalctl -u caddy -f
journalctl -u pxe-publish -f

Dépannage -- incidents déjà rencontrés

Unit pxe-publish.service not found : le système du serveur n'a jamais été rebuild depuis que ce service a été ajouté à pxe-server/configuration.nix. git pull seul ne suffit pas côté serveur -- il faut ensuite sudo nixos-rebuild switch --flake .#pxe-server --impure.

Le dossier repo a disparu du serveur (/etc/nixos-fleet ou équivalent absent) : repo public, sans authentification -- reclone directement, n'importe où :

git clone https://gitea.miniclic.net/Damien/Nixos_Fleet.git

Le hardware-configuration.nix est hors du repo (/etc/nixos/), donc indépendant de l'emplacement du clone.

Un fix censé être appliqué ne change rien : vérifier git log --oneline -3 avant toute autre piste -- le git pull n'a peut-être rien ramené de neuf (mauvaise branche, push pas fait côté dev). Ne jamais supposer qu'un rebuild "prend" le dernier commit distant sans l'avoir vérifié.

curl http://<serverIp>/netboot.ipxe reste bloqué : l'IP statique de l'interface PXE ne s'est parfois pas appliquée toute seule au tout premier switch sur une install neuve. Vérifier :

ip a show <interface>   # cherche "inet <serverIp>/24"

Absente → forcer une fois :

sudo systemctl start network-addresses-<interface>.service

Un reboot du serveur applique aussi ça correctement au démarrage suivant.

Écran PXE ne trouve rien : revérifier serverIp et interface dans pxe-server/configuration.nix contre la réalité du serveur (ip a).

Boucle infinie au démarrage d'un PC client : journalctl -u dnsmasq pendant le boot du PC concerné.

UEFI ou BIOS ne boote pas (l'un des deux seulement) : vérifier que les deux fichiers existent dans /var/lib/tftpboot (undionly.kpxe pour BIOS, ipxe.efi pour UEFI) -- l'un des deux install -m 0644 ... || true dans pxe-publish peut avoir silencieusement échoué (noms de sortie du paquet pkgs.ipxe à revérifier si la version change).

IP qui changent tout le temps sur le segment PXE : un autre serveur DHCP tourne déjà sur ce réseau -- repasser standaloneDhcp à false (proxyDHCP seul).

Valider une modif avant de la pousser

nix flake check --no-build            # échoue sur pxe-server hors du vrai serveur (attendu, lit /etc/nixos)
nix flake check --no-build --impure   # à lancer depuis le serveur PXE réel uniquement
nix build .#nixosConfigurations.nixos.config.system.build.toplevel --dry-run

Environnement de dev sans accès à un vrai serveur PXE : voir "Environnement de dev sous Windows (WSL + Nix)" dans le README.md -- pxe-server ne s'évalue qu'avec --impure sur la machine réelle, c'est normal ailleurs.