Général 5 min de lecture · 933 mots

Mes notes de dépannage : le runbook du moi fatigué

Un runbook, c'est juste un pense-bête : « quand ça arrive, voilà quoi regarder et quoi taper ». Comment en écrire pour ton homelab, avec un exemple complet.

Mes notes de dépannage : le runbook du moi fatigué
Général · 2026.11.19

Le mot runbook fait un peu entreprise, mais l’idée est d’une simplicité désarmante : c’est un pense-bête qui dit quoi faire quand quelque chose casse.

Pourquoi en écrire pour soi-même ? Parce que le jour où ton service tombe, tu ne seras probablement pas dans ton meilleur état : fatigué, pressé, un peu stressé de voir que la famille attend. Et le toi d’aujourd’hui, qui comprend tout parfaitement, n’a rien à voir avec le toi de dans six mois, qui ne se souviendra plus de rien.

Écris donc pour le moi fatigué de dans six mois.

Ce qu’un bon runbook contient

Pas de roman. Un runbook utile se lit en trente secondes et suit toujours la même forme :

  1. Le symptôme : ce qu’on observe (« Nextcloud ne synchronise plus »).
  2. Les vérifications : quoi regarder, dans l’ordre, du plus probable au moins probable.
  3. Les corrections : les commandes à copier-coller pour chaque cause.
  4. La vérification finale : comment s’assurer que c’est vraiment réparé.
  5. Les liens : où trouver le reste (mot de passe dans le gestionnaire, doc officielle, postmortem précédent).

L’ordre des vérifications compte : mets en premier les causes les plus fréquentes. La plupart des pannes d’un homelab viennent des mêmes suspects.

Un exemple complet : « Le service ne répond plus »

Voici un runbook général que je te recommande d’avoir sous la main. Tu peux le copier tel quel et l’adapter.

# Runbook : un service ne répond plus

## Symptôme
Une page web ne s'ouvre plus, ou répond avec une erreur (502, 504, timeout).

## 1. Est-ce que la machine répond ?
ping 192.168.1.XX
→ Pas de réponse : voir « Machine injoignable » plus bas.

## 2. Est-ce que le disque est plein ?
df -h
→ Un volume à 100 % : voir « Disque plein ».

## 3. Est-ce que le service tourne ?
systemctl status nom-du-service
(ou, pour Docker : docker compose ps)
→ Arrêté : relancer, puis lire les logs.

## 4. Que disent les logs ?
journalctl -u nom-du-service -n 100 --no-pager
(ou : docker compose logs --tail=100)

## 5. Est-ce un problème de mémoire ?
free -h
journalctl -k | grep -i "out of memory"

## 6. Est-ce le reverse proxy ?
Tester le service en direct, sans proxy : curl -I http://IP:PORT
→ Si ça marche, le souci vient du proxy ou du DNS.

## Vérification finale
La page s'ouvre. L'alerte est revenue au vert.
Si c'est une nouvelle panne : écrire un mini-postmortem.

Tu remarqueras qu’il ne contient aucune explication théorique. Juste des questions simples et des commandes.

Un deuxième exemple : « Disque plein »

# Runbook : disque plein

## Trouver ce qui prend la place
sudo du -xh / --max-depth=2 2>/dev/null | sort -h | tail -20

## Les suspects habituels
- Logs : journalctl --disk-usage  puis  sudo journalctl --vacuum-size=500M
- Docker : docker system df  puis  docker system prune (ATTENTION : lire ce qui sera supprimé)
- Anciennes sauvegardes dans /srv/sauvegardes
- Snapshots oubliés (Proxmox, ZFS)

## Après nettoyage
df -h pour confirmer, puis relancer les services qui se sont arrêtés.

## Pour que ça ne se reproduise pas
Vérifier qu'une alerte existe à 85 %.

Remarque la mention « ATTENTION » sur docker system prune. Dans un runbook, signale en gras les commandes destructrices. Le moi fatigué de 3 h du matin est le premier à copier-coller sans relire.

Quels runbooks écrire en premier ?

Ne cherche pas l’exhaustivité. Commence par une page par scénario qui t’a déjà posé problème :

  • Un service ne répond plus (le modèle ci-dessus).
  • Un disque est plein.
  • Une machine est injoignable.
  • Un certificat HTTPS a expiré.
  • Restaurer une VM ou un conteneur depuis une sauvegarde.

Le dernier est le plus précieux. La restauration d’une sauvegarde est exactement le moment où tu veux une procédure écrite à l’avance, et pas improvisée dans la panique.

Où les ranger (surtout pas sur la machine en panne)

C’est le piège classique : stocker ses runbooks sur le service qui est en panne. Si ton wiki est hébergé sur la machine qui vient de tomber, tu ne peux plus lire la procédure pour la réparer.

Quelques idées simples :

  • Un dépôt git, avec une copie sur ton ordinateur portable (donc consultable hors ligne).
  • Des fichiers Markdown dans un dossier synchronisé.
  • Une version imprimée des trois ou quatre procédures vitales (oui, du papier !). Pour « comment restaurer une sauvegarde », c’est tout sauf ridicule.

L’important : le runbook doit rester lisible quand ton homelab est éteint.

Les faire vivre

Un runbook qui n’est jamais mis à jour devient dangereux : il te fait taper des commandes qui ne correspondent plus à ta machine. Trois habitudes l’entretiennent sans effort :

  1. Après chaque panne, relis le runbook concerné et corrige ce qui manquait (c’est la question 5 de ton mini-postmortem).
  2. Teste-le une fois, tranquillement, un dimanche : suis les étapes et vérifie qu’elles marchent vraiment.
  3. Date-le : une ligne « dernière vérification : mois/année » en haut.

Pour conclure

Un runbook ne sert pas à impressionner : il sert à réparer plus vite et plus sereinement, quand l’énergie manque. Cinq pages bien rangées valent mieux qu’un wiki parfait que personne n’a jamais ouvert.

Commence aujourd’hui avec le modèle « un service ne répond plus ». Dix minutes pour le copier et l’adapter, et la prochaine panne sera déjà un peu moins stressante.

À propos de l'auteur

Pascal

Pascal — SRE & Observability Engineer. J'applique les pratiques SRE (SLI/SLO, alerting, observabilité) à mon homelab Proxmox, avec les mêmes exigences qu'en production.

Une remarque, un retour ?

Cet article est vivant - corrections, contre-arguments et retours de production sont les bienvenus. Trois canaux, choisis celui qui te convient.

Laisser un commentaire