diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..95e4b5d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,133 @@ +# 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](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](../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 + +- **Ne jamais `git push`** sans instruction explicite de l'opérateur humain, dans ce repo comme dans tout autre. +- **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. +- Le serveur PXE lui-même fait `git pull` (voir "Entretien" plus bas) -- ce n'est pas une exception à la règle pull-only des PC installés (qui ne font jamais `git pull`), c'est un host de maintenance à part entière. +- Commits : `Co-Authored-By: Claude Sonnet 5 ` 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](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](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) + +```bash +# 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 : + +```bash +sudo systemctl status dnsmasq caddy +ls /var/lib/tftpboot # undionly.kpxe, ipxe.efi +ls /var/www/pxe # bzImage, initrd, netboot.ipxe +curl -I http:///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 + +```bash +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/` : + +```bash +sudo systemctl start pxe-publish +``` + +Republier après une modif de `pxe-server/configuration.nix` (rebuild complet, pas juste `pxe-publish`) : + +```bash +sudo nixos-rebuild switch --flake .#pxe-server --impure +``` + +Logs : + +```bash +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ù : +```bash +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:///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 : +```bash +ip a show # cherche "inet /24" +``` +Absente → forcer une fois : +```bash +sudo systemctl start network-addresses-.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 + +```bash +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](README.md) -- `pxe-server` ne s'évalue qu'avec `--impure` **sur la machine réelle**, c'est normal ailleurs.