Maintenance et dépannage

Le quotidien de l’administrateur : garder le parc propre, intervenir sur un hôte, revenir en arrière après une mauvaise configuration, lire les journaux.

Agir sur un hôte

Toutes ces commandes ciblent un hôte (ou un motif / une liste) via colmena :

Commande	Effet
`just enter <host>`	Ouvrir un shell SSH (alias `e`)
`just reboot <host>`	Redémarrer
`just halt <host>`	Éteindre
`just gc <host>`	Purger les générations + nettoyer le store
`just fix-boot <host>`	Réinstaller le chargeur d’amorçage

Nettoyer et formater le code

Avant de committer ou déployer, normaliser le dépôt :

just clean      # fix + check + generate + format

just check-all : tests unitaires + vérification des flakes (avant un déploiement).
just gc <host> : récupère l’espace disque (ancien générations supprimées).

Revenir en arrière

Chaque déploiement crée une génération NixOS. En cas de problème :

Au démarrage : choisir une génération précédente dans le menu de boot.
À chaud : revenir à la génération précédente puis la rendre active :
Fenêtre de terminal
```
just enter <host>
sudo nixos-rebuild switch --rollback
```
Par le code : git revert la mauvaise configuration, puis redéployer :
Fenêtre de terminal
```
just apply <host>
```

Lire les journaux

just enter <host>
journalctl -u <service> -n 100 --no-pager     # logs d'un service
journalctl -p err -b                          # erreurs depuis le démarrage
systemctl status <service>                    # état d'une unité

Services en échec après un redémarrage de passerelle

Symptôme : systemctl --failed liste, juste après le boot, des unités qui repartent sans broncher une fois relancées à la main (montages NFS, provisionnement OIDC, tout ce qui résout un nom).

Cause : sur une passerelle, le résolveur du système est AdGuard Home (nameserver 127.0.0.1). Son unité est Type=simple, donc systemd la déclare active dès que le processus démarre — une vingtaine de secondes avant qu’elle n’écoute réellement sur le port 53. Tout ce qui résout un nom pendant cette fenêtre échoue.

Le framework pose une barrière pour ça : dns-ready.service interroge le résolveur local jusqu’à obtenir une réponse, et bloque nss-lookup.target jusque-là.

systemctl status dns-ready              # date à laquelle les noms ont résolu
journalctl -b -u adguardhome | head -30 # moment où le proxy DNS écoute enfin

Une unité qui résout un nom au démarrage doit donc s’ordonner derrière cette cible — after = [ "nss-lookup.target" ] pour un service, l’option de montage x-systemd.after=nss-lookup.target pour un point de montage. Sur les hôtes non passerelles, la cible est atteinte immédiatement : aucun délai ajouté.

Certificats TLS d’une passerelle expirés

Une passerelle ne demande pas ses propres certificats : c’est le HCS qui les obtient, et l’unité sync-caddy-certs les recopie toutes les dix minutes depuis le HCS vers le stockage Caddy local.

systemctl status sync-caddy-certs   # dernier passage et son résultat
journalctl -u sync-caddy-certs -n 50
systemctl list-timers sync-caddy-certs

Le transfert passe par deux répertoires :

Chemin	Rôle
`/var/lib/caddy-cert-sync`	Zone de transit (`StateDirectory` de l’unité)
`/var/lib/caddy/storage`	Stockage Caddy réellement servi

L’unité tourne en root, tire depuis le HCS avec la clé SSH de l’utilisateur nix, puis publie vers le stockage Caddy. Elle échoue franchement à la première erreur : un systemctl status en failed est donc le signal à surveiller, et un échec répété annonce une expiration de certificat.