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> [keep]	Purger les générations + nettoyer le store
just fix-boot <host>	Réinstaller le chargeur d’amorçage

Plusieurs hôtes à la fois

La cible accepte un motif ou une liste : just gc '*', just reboot a,b.

L’argument keep de just gc limite la purge :

• just gc <host> : ne garde que la génération courante.
• just gc <host> 3 : garde les 3 dernières générations, courante incluse.
• just gc <host> 3d : supprime les générations de plus de 3 jours.

Nettoyer et formater le code

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

just clean      # fix + check + generate + format

• just check : code + tests unitaires + vérification des flakes (avant déploiement).

Revenir en arrière

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

1. Au démarrage : choisir une génération précédente dans le menu de boot.

2. À chaud : revenir à la génération précédente puis la rendre active :

   just enter <host>
   sudo nixos-rebuild switch --rollback

3. Par le code : git revert la mauvaise configuration, puis redéployer :

   just apply <host>

Attention au GC

just gc supprime les anciennes générations : on ne peut plus y revenir au démarrage. Vérifiez que l’hôte est stable avant de nettoyer.

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é

Diagnostic guidé

Pour la supervision centralisée (métriques + journaux Caddy), voir Supervision. Pour la santé de la réplication d’identités : just idm-fix-replica <hcs> <gateways>.

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é.

Un service qui dépend d’un autre hôte

L’ordonnancement local ne dit rien de la disponibilité d’une machine distante (l’IdM, un serveur NFS, un hôte encore en train de démarrer). Pour ces dépendances-là, la seule réponse fiable est de réessayer : Restart + RestartSec sur l’unité, plutôt qu’un échec définitif à chaque redémarrage.

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 attend d’abord que le tailnet soit réellement monté (jusqu’à cinq minutes), puis réessaie le transfert trois fois avant d’abandonner. Un systemctl status en failed reste donc le signal à surveiller, et un échec répété annonce une expiration de certificat.

Pourquoi cette attente

Au premier démarrage d’une passerelle, tailscaled peut tourner sans que le tailnet soit joignable : le lien WAN — et la box derrière — mettent parfois plusieurs minutes, et le démon repart alors en attente exponentielle avant de retenter sa connexion au plan de contrôle. Le minuteur tirait droit dans ce trou et laissait l’unité en failed jusqu’au passage suivant. S’ordonner derrière tailscaled.service ne suffit pas : cela prouve seulement que le démon a démarré, d’où l’attente explicite sur BackendState et Self.Online.

Zone de transit vide

La publication est refusée si la zone de transit ne contient aucun fichier (message empty staging dir, refusing to publish). Sans ce garde-fou, la synchronisation effacerait les certificats en place et la clé de compte ACME. Si ce message apparaît, le problème est en amont : accès SSH au HCS, tailnet, ou stockage Caddy vide côté HCS.

Effet sur les services exposés

Le HCS vérifie le certificat de la passerelle vers laquelle il relaie. Une passerelle dont la synchronisation n’a jamais abouti répond donc 502 sur ses services exposés, au lieu de relayer vers un certificat non vérifiable. Premier réflexe : systemctl start sync-caddy-certs sur la passerelle.

UID des comptes gdm-greeter décalés

Symptôme, à chaque activation d’un poste GNOME :

warning: not applying UID change of user 'gdm-greeter-2' (60580 -> 60579)

nixpkgs a renuméroté ses comptes gdm-greeter* ; NixOS ne renumérote jamais un compte existant. Les postes installés avant gardent les anciens UID, et deux greeters peuvent partager le même.

just fix-gdm-greeters poste-01,poste-02         # diagnostic, n'écrit rien
just fix-gdm-greeters poste-01,poste-02 apply

apply arrête GDM, recrée les comptes décalés avec les UID déclarés, réattribue leurs fichiers puis relance GDM. Un hôte avec une session graphique ouverte est laissé de côté : relancer après déconnexion. Sauvegarde de /etc/passwd et /etc/shadow dans /var/lib/nixos/backup-gdm-greeters-<date>/.