From c8d62e79dc1b03621a544ed3bd493e6c910d1743 Mon Sep 17 00:00:00 2001
From: BeauTroll <->
Date: Thu, 18 Dec 2025 18:09:03 +0100
Subject: [PATCH] Add comprehensive restore testing documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create detailed guide for testing backup restoration at three levels:
quick checks, service restoration, and full disaster recovery.

Changes:
- Add docs/RESTORE-TESTING.md with complete testing procedures
- Include 3 testing levels (monthly, quarterly, semi-annual)
- Document common restoration scenarios
- Provide troubleshooting guides and checklists
- Add RTO/RPO measurement guidelines
- Include report templates for each test level

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 docs/RESTORE-TESTING.md | 714 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 714 insertions(+)
 create mode 100644 docs/RESTORE-TESTING.md

diff --git a/docs/RESTORE-TESTING.md b/docs/RESTORE-TESTING.md
new file mode 100644
index 0000000..922d1dc
--- /dev/null
+++ b/docs/RESTORE-TESTING.md
@@ -0,0 +1,714 @@
+# Guide de test de restauration Borgmatic
+
+> **"Un backup non testé n'est pas un backup"**
+
+Ce guide décrit comment tester vos backups Borgmatic pour garantir que vos données sont restaurables en cas de sinistre.
+
+## Table des matières
+
+- [Pourquoi tester ?](#pourquoi-tester)
+- [Pré-requis](#pré-requis)
+- [Niveau 1 : Test rapide (mensuel)](#niveau-1--test-rapide-mensuel)
+- [Niveau 2 : Test de service (trimestriel)](#niveau-2--test-de-service-trimestriel)
+- [Niveau 3 : Disaster Recovery complet (semestriel)](#niveau-3--disaster-recovery-complet-semestriel)
+- [Scénarios de restauration courants](#scénarios-de-restauration-courants)
+- [Checklist de vérification](#checklist-de-vérification)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Pourquoi tester ?
+
+### Risques sans test de restauration
+
+- ❌ Backup corrompu découvert trop tard
+- ❌ Passphrase incorrecte ou perdue
+- ❌ Clés SSH manquantes ou expirées
+- ❌ Fichiers critiques exclus par erreur
+- ❌ Permissions/ownership incorrects
+- ❌ Temps de restauration inconnu (RTO)
+- ❌ Procédure non documentée
+
+### Bénéfices des tests réguliers
+
+- ✅ Confiance totale dans vos backups
+- ✅ Procédure éprouvée et documentée
+- ✅ Temps de restauration mesuré
+- ✅ Détection précoce des problèmes
+- ✅ Équipe formée en conditions réelles
+
+---
+
+## Pré-requis
+
+### Informations nécessaires
+
+Assurez-vous d'avoir accès à :
+
+```bash
+# Variables d'environnement
+BORG_REPO=ssh://USER@IP:PORT/./backups
+BORG_PASSPHRASE=votre-passphrase-sécurisée
+
+# Clés SSH
+~/.ssh/id_rsa (ou clé configurée pour le serveur de backup)
+```
+
+### Vérifications préliminaires
+
+```bash
+# 1. Vérifier la connexion au repository
+make info
+
+# 2. Lister les archives disponibles
+make list
+
+# 3. Vérifier l'intégrité du repository
+make check
+```
+
+---
+
+## Niveau 1 : Test rapide (mensuel)
+
+**Durée estimée :** 5-10 minutes
+**Fréquence recommandée :** Tous les mois
+**Objectif :** Vérifier que la restauration fonctionne
+
+### Procédure
+
+#### 1. Créer un environnement de test
+
+```bash
+# Créer un dossier de test avec horodatage
+TEST_DIR="/tmp/restore-test-$(date +%Y%m%d-%H%M)"
+mkdir -p "$TEST_DIR"
+cd "$TEST_DIR"
+```
+
+#### 2. Restaurer quelques fichiers critiques
+
+```bash
+# Restaurer la configuration Borgmatic
+borgmatic extract \
+  --archive latest \
+  --path /etc/borgmatic/config.yaml \
+  --destination "$TEST_DIR/"
+
+# Restaurer un fichier Nextcloud
+borgmatic extract \
+  --archive latest \
+  --path /opt/nextcloud/config/config.php \
+  --destination "$TEST_DIR/"
+
+# Restaurer un fichier de configuration système
+borgmatic extract \
+  --archive latest \
+  --path /etc/nginx/nginx.conf \
+  --destination "$TEST_DIR/"
+```
+
+#### 3. Vérifier les fichiers restaurés
+
+```bash
+# Vérifier que les fichiers existent
+ls -lh "$TEST_DIR/etc/borgmatic/"
+ls -lh "$TEST_DIR/opt/nextcloud/config/"
+
+# Comparer avec l'original (si toujours accessible)
+diff /etc/borgmatic/config.yaml "$TEST_DIR/etc/borgmatic/config.yaml"
+
+# Vérifier le contenu
+cat "$TEST_DIR/etc/borgmatic/config.yaml"
+```
+
+#### 4. Nettoyer
+
+```bash
+# Supprimer le dossier de test
+rm -rf "$TEST_DIR"
+echo "✅ Test rapide terminé avec succès"
+```
+
+### Checklist de validation
+
+- [ ] Les fichiers ont été restaurés sans erreur
+- [ ] Le contenu des fichiers est correct
+- [ ] Les permissions semblent correctes
+- [ ] Aucun message d'erreur dans les logs
+
+---
+
+## Niveau 2 : Test de service (trimestriel)
+
+**Durée estimée :** 30-60 minutes
+**Fréquence recommandée :** Tous les 3 mois
+**Objectif :** Vérifier la restauration complète d'un service
+
+### Scénario : Restaurer Nextcloud complet
+
+#### 1. Préparer l'environnement
+
+```bash
+TEST_DIR="/tmp/restore-nextcloud-$(date +%Y%m%d)"
+mkdir -p "$TEST_DIR"
+```
+
+#### 2. Restaurer Nextcloud
+
+```bash
+# Restaurer tous les fichiers Nextcloud
+borgmatic extract \
+  --archive latest \
+  --path /opt/nextcloud \
+  --destination "$TEST_DIR/"
+
+# Chronométrer la restauration
+time borgmatic extract \
+  --archive latest \
+  --path /opt/nextcloud \
+  --destination "$TEST_DIR/"
+```
+
+#### 3. Vérifier la restauration
+
+```bash
+# Vérifier la taille totale
+du -sh "$TEST_DIR/opt/nextcloud/"
+
+# Comparer avec la production
+du -sh /opt/nextcloud/
+
+# Vérifier la structure
+tree -L 2 "$TEST_DIR/opt/nextcloud/"
+
+# Vérifier les fichiers de configuration
+cat "$TEST_DIR/opt/nextcloud/config/config.php"
+
+# Vérifier quelques fichiers utilisateurs
+ls -lh "$TEST_DIR/opt/nextcloud/data/"
+
+# Vérifier les permissions
+ls -la "$TEST_DIR/opt/nextcloud/"
+```
+
+#### 4. Tests approfondis
+
+```bash
+# Compter les fichiers
+find "$TEST_DIR/opt/nextcloud/" -type f | wc -l
+find /opt/nextcloud/ -type f | wc -l
+
+# Vérifier les bases de données (si incluses)
+ls -lh "$TEST_DIR/opt/nextcloud/data/"*.db
+
+# Tester l'intégrité de fichiers aléatoires
+md5sum "$TEST_DIR/opt/nextcloud/data/user1/files/photo.jpg"
+```
+
+#### 5. Documenter les résultats
+
+```bash
+# Créer un rapport
+cat > "$TEST_DIR/test-report.txt" <<EOF
+Test de restauration Nextcloud
+Date: $(date)
+Archive: latest
+Durée: [À REMPLIR]
+Taille restaurée: $(du -sh "$TEST_DIR/opt/nextcloud/" | cut -f1)
+Nombre de fichiers: $(find "$TEST_DIR/opt/nextcloud/" -type f | wc -l)
+Statut: ✅ SUCCÈS / ❌ ÉCHEC
+Notes: [VOS OBSERVATIONS]
+EOF
+
+cat "$TEST_DIR/test-report.txt"
+```
+
+### Autres services à tester
+
+```bash
+# Gitea
+borgmatic extract --archive latest --path /opt/gitea --destination "$TEST_DIR/"
+
+# Mailcow
+borgmatic extract --archive latest --path /opt/mailcow-dockerized --destination "$TEST_DIR/"
+
+# Configurations système
+borgmatic extract --archive latest --path /etc --destination "$TEST_DIR/"
+```
+
+---
+
+## Niveau 3 : Disaster Recovery complet (semestriel)
+
+**Durée estimée :** 2-4 heures
+**Fréquence recommandée :** Tous les 6 mois
+**Objectif :** Simuler une catastrophe totale et restaurer sur un nouveau serveur
+
+### Scénario : "Le serveur de production a brûlé"
+
+#### Phase 1 : Préparation du nouveau serveur
+
+**Option A : VM de test locale**
+
+```bash
+# Créer une VM Ubuntu/Debian avec les mêmes specs
+# - RAM : même quantité que prod
+# - Disque : au moins la taille de vos backups
+# - Réseau : accès Internet
+```
+
+**Option B : Serveur de secours**
+
+```bash
+# Utiliser un serveur de backup/staging
+# S'assurer qu'il est vierge ou sauvegardé
+```
+
+#### Phase 2 : Installation des bases
+
+```bash
+# 1. Mettre à jour le système
+sudo apt update && sudo apt upgrade -y
+
+# 2. Installer les dépendances de base
+sudo apt install -y git curl wget vim
+
+# 3. Cloner le repo de configuration
+cd /opt
+sudo git clone https://git.example.com/agence66-borgmatic.git borgmatic
+cd borgmatic
+
+# 4. Configurer les variables d'environnement
+sudo cp .env.example /etc/borgmatic/.env
+sudo nano /etc/borgmatic/.env
+# Remplir : BORG_REPO, BORG_PASSPHRASE
+
+# 5. Configurer les clés SSH
+sudo mkdir -p /root/.ssh
+sudo cp votre-cle-ssh /root/.ssh/id_rsa
+sudo chmod 600 /root/.ssh/id_rsa
+
+# 6. Installer Borgmatic
+sudo ./install.sh
+```
+
+#### Phase 3 : Vérifier l'accès au repository
+
+```bash
+# Tester la connexion
+sudo borgmatic list
+
+# Lister les archives disponibles
+sudo borgmatic list --archive all
+
+# Choisir l'archive à restaurer (généralement la plus récente)
+ARCHIVE_NAME="backup-20251218-0301"
+```
+
+#### Phase 4 : Restauration complète
+
+**IMPORTANT : Chronométrez chaque étape pour mesurer votre RTO réel**
+
+```bash
+# Démarrer le chronomètre
+START_TIME=$(date +%s)
+
+# Restaurer TOUT
+sudo borgmatic extract \
+  --archive "$ARCHIVE_NAME" \
+  --destination /tmp/full-restore/
+
+# Calculer le temps écoulé
+END_TIME=$(date +%s)
+DURATION=$((END_TIME - START_TIME))
+echo "Durée de restauration: $((DURATION / 60)) minutes"
+```
+
+#### Phase 5 : Reconstruction des services
+
+```bash
+# 1. Copier les fichiers restaurés vers leurs emplacements
+sudo cp -a /tmp/full-restore/opt/* /opt/
+sudo cp -a /tmp/full-restore/etc/* /etc/
+sudo cp -a /tmp/full-restore/var/www/* /var/www/
+
+# 2. Installer Docker et Docker Compose
+sudo apt install -y docker.io docker-compose
+
+# 3. Restaurer les configurations Docker
+cd /opt/nextcloud && sudo docker-compose up -d
+cd /opt/mailcow-dockerized && sudo docker-compose up -d
+cd /opt/gitea && sudo docker-compose up -d
+
+# 4. Vérifier les permissions
+sudo chown -R www-data:www-data /var/www/
+sudo chown -R 1000:1000 /opt/nextcloud/data/
+
+# 5. Redémarrer les services
+sudo systemctl restart nginx
+sudo systemctl restart mysql
+```
+
+#### Phase 6 : Tests de validation
+
+```bash
+# 1. Vérifier que les services démarrent
+docker ps -a
+systemctl status nginx
+systemctl status mysql
+
+# 2. Tester l'accès web
+curl -I http://localhost
+curl -I http://localhost/nextcloud
+
+# 3. Vérifier les bases de données
+mysql -e "SHOW DATABASES;"
+
+# 4. Tester un login utilisateur
+# → Ouvrir le navigateur et tester Nextcloud, Mailcow, etc.
+
+# 5. Vérifier les données
+ls -lh /opt/nextcloud/data/
+ls -lh /var/www/html/
+```
+
+#### Phase 7 : Documentation du processus
+
+```bash
+# Créer un rapport détaillé
+cat > /tmp/disaster-recovery-report-$(date +%Y%m%d).txt <<EOF
+==========================================================
+RAPPORT DE TEST DISASTER RECOVERY
+==========================================================
+
+Date du test: $(date)
+Serveur de test: [NOM/IP]
+Archive utilisée: $ARCHIVE_NAME
+
+CHRONOLOGIE
+-----------
+1. Préparation serveur: [DURÉE]
+2. Installation bases: [DURÉE]
+3. Restauration fichiers: $((DURATION / 60)) minutes
+4. Reconstruction services: [DURÉE]
+5. Validation: [DURÉE]
+
+DURÉE TOTALE (RTO): [DURÉE TOTALE]
+
+SERVICES TESTÉS
+---------------
+[ ] Nextcloud - Statut: ✅/❌
+[ ] Mailcow - Statut: ✅/❌
+[ ] Gitea - Statut: ✅/❌
+[ ] Nginx - Statut: ✅/❌
+[ ] Autres: [LISTE]
+
+PROBLÈMES RENCONTRÉS
+--------------------
+1. [PROBLÈME 1]
+   Solution: [SOLUTION]
+
+2. [PROBLÈME 2]
+   Solution: [SOLUTION]
+
+AMÉLIORATIONS IDENTIFIÉES
+--------------------------
+1. [AMÉLIORATION 1]
+2. [AMÉLIORATION 2]
+
+LEÇONS APPRISES
+---------------
+1. [LEÇON 1]
+2. [LEÇON 2]
+
+PROCHAINES ACTIONS
+------------------
+[ ] Mettre à jour la documentation
+[ ] Corriger les problèmes identifiés
+[ ] Former l'équipe sur la procédure
+[ ] Planifier le prochain test
+
+VALIDATION
+----------
+Testé par: [NOM]
+Validé par: [NOM]
+Signature: _________________
+
+EOF
+
+cat /tmp/disaster-recovery-report-$(date +%Y%m%d).txt
+```
+
+---
+
+## Scénarios de restauration courants
+
+### 1. Fichier supprimé accidentellement
+
+```bash
+# Lister les archives contenant le fichier
+borgmatic list --path /opt/nextcloud/data/user/important.pdf
+
+# Restaurer depuis une archive spécifique
+borgmatic extract \
+  --archive backup-20251215-0301 \
+  --path /opt/nextcloud/data/user/important.pdf \
+  --destination /tmp/restore/
+
+# Copier le fichier restauré
+cp /tmp/restore/opt/nextcloud/data/user/important.pdf /opt/nextcloud/data/user/
+```
+
+### 2. Base de données corrompue
+
+```bash
+# Restaurer le dump de base de données
+borgmatic extract \
+  --archive latest \
+  --path /opt/mailcow-dockerized/backup/mysql \
+  --destination /tmp/restore/
+
+# Importer la base de données
+mysql < /tmp/restore/opt/mailcow-dockerized/backup/mysql/dump.sql
+```
+
+### 3. Configuration cassée
+
+```bash
+# Restaurer l'ancienne configuration
+borgmatic extract \
+  --archive backup-20251210-0301 \
+  --path /etc/nginx/nginx.conf \
+  --destination /tmp/restore/
+
+# Comparer et restaurer
+diff /etc/nginx/nginx.conf /tmp/restore/etc/nginx/nginx.conf
+sudo cp /tmp/restore/etc/nginx/nginx.conf /etc/nginx/nginx.conf
+sudo systemctl restart nginx
+```
+
+### 4. Rollback complet d'un service
+
+```bash
+# Arrêter le service
+cd /opt/nextcloud && docker-compose down
+
+# Sauvegarder l'état actuel
+mv /opt/nextcloud /opt/nextcloud.broken
+
+# Restaurer depuis une archive antérieure
+borgmatic extract \
+  --archive backup-20251201-0301 \
+  --path /opt/nextcloud \
+  --destination /opt/
+
+# Redémarrer
+cd /opt/nextcloud && docker-compose up -d
+```
+
+---
+
+## Checklist de vérification
+
+### Avant la restauration
+
+- [ ] Archive de backup identifiée
+- [ ] Espace disque suffisant (au moins 2x la taille du backup)
+- [ ] BORG_PASSPHRASE disponible
+- [ ] Clés SSH configurées
+- [ ] Accès au repository Borg validé
+- [ ] Services arrêtés si restauration en production
+- [ ] Backup de l'état actuel effectué
+
+### Pendant la restauration
+
+- [ ] Chronométrage des étapes
+- [ ] Logs de restauration sauvegardés
+- [ ] Vérification des erreurs en temps réel
+- [ ] Documentation des problèmes rencontrés
+
+### Après la restauration
+
+- [ ] Fichiers/dossiers présents
+- [ ] Permissions correctes
+- [ ] Ownership correct (user:group)
+- [ ] Taille des données cohérente
+- [ ] Services démarrent correctement
+- [ ] Accès web fonctionnel
+- [ ] Bases de données accessibles
+- [ ] Tests fonctionnels réussis
+- [ ] Logs vérifiés
+- [ ] Rapport de test complété
+
+---
+
+## Troubleshooting
+
+### Erreur : "Permission denied"
+
+```bash
+# Solution : Utiliser sudo
+sudo borgmatic extract ...
+
+# Vérifier les permissions du repository
+ls -la /etc/borgmatic/
+```
+
+### Erreur : "Repository not found"
+
+```bash
+# Vérifier BORG_REPO
+echo $BORG_REPO
+
+# Tester la connexion SSH
+ssh -p 23 u516154@u516154.your-storagebox.de
+
+# Vérifier la clé SSH
+ssh-add -l
+```
+
+### Erreur : "Passphrase incorrect"
+
+```bash
+# Vérifier BORG_PASSPHRASE
+echo $BORG_PASSPHRASE
+
+# Charger depuis .env
+source /etc/borgmatic/.env
+```
+
+### Restauration très lente
+
+```bash
+# Utiliser des options de performance
+borgmatic extract --archive latest --path /opt/nextcloud --threads 4
+
+# Vérifier la bande passante réseau
+iftop
+nload
+```
+
+### Fichiers manquants après restauration
+
+```bash
+# Vérifier qu'ils n'étaient pas exclus
+grep -r "exclude" /etc/borgmatic/config.yaml
+
+# Lister tous les fichiers de l'archive
+borgmatic list --archive latest --short > /tmp/archive-files.txt
+grep "nextcloud" /tmp/archive-files.txt
+```
+
+### Permissions incorrectes
+
+```bash
+# Restaurer les permissions originales
+sudo chown -R www-data:www-data /opt/nextcloud/data/
+sudo chmod -R 755 /opt/nextcloud/
+```
+
+---
+
+## Bonnes pratiques
+
+### 1. Planification des tests
+
+Créez un calendrier de tests :
+
+```
+Janvier    : Test rapide
+Février    : Test rapide
+Mars       : Test rapide + Test service (Nextcloud)
+Avril      : Test rapide
+Mai        : Test rapide
+Juin       : Test rapide + Test service (Mailcow) + DR complet
+Juillet    : Test rapide
+...
+```
+
+### 2. Documentation continue
+
+Après CHAQUE test :
+
+- Mettre à jour ce document avec les leçons apprises
+- Noter les durées réelles
+- Documenter les problèmes et solutions
+- Partager avec l'équipe
+
+### 3. Automatisation
+
+Créer des scripts pour les tests fréquents :
+
+```bash
+# Script de test rapide automatisé
+./scripts/test-restore-quick.sh
+
+# Script de rapport automatique
+./scripts/generate-restore-report.sh
+```
+
+### 4. Formation de l'équipe
+
+- Faire tourner les personnes qui effectuent les tests
+- Documenter la procédure comme si vous la lisiez pour la première fois
+- Simuler des pannes sans prévenir (test surprise)
+
+### 5. Amélioration continue
+
+À chaque test, posez-vous :
+
+- Qu'est-ce qui pourrait être plus rapide ?
+- Qu'est-ce qui manque dans la documentation ?
+- Quels fichiers critiques ne sont pas backupés ?
+- Comment réduire le RTO (temps de restauration) ?
+
+---
+
+## Métriques importantes
+
+### RTO (Recovery Time Objective)
+
+**Temps maximum acceptable pour restaurer le service**
+
+Mesurez lors de vos tests :
+
+- Restauration fichiers uniquement : **\_** minutes
+- Restauration + redémarrage services : **\_** minutes
+- Disaster Recovery complet : **\_** heures
+
+### RPO (Recovery Point Objective)
+
+**Quantité de données qu'on peut accepter de perdre**
+
+Avec backup quotidien à 3h :
+
+- RPO : Maximum 24 heures de données perdues
+
+Si critique, envisager :
+
+- Backups plus fréquents (2x/jour)
+- Réplication en temps réel
+- Snapshots supplémentaires
+
+---
+
+## Conclusion
+
+**Un test de restauration régulier est la SEULE façon de garantir que vos backups fonctionnent.**
+
+N'attendez pas la catastrophe pour découvrir que vos backups sont inutilisables.
+
+### Prochaines étapes
+
+1. [ ] Planifier votre premier test rapide (cette semaine)
+2. [ ] Calendrier de tests pour l'année
+3. [ ] Former au moins une autre personne à la procédure
+4. [ ] Automatiser les tests simples
+5. [ ] Documenter votre RTO/RPO réel
+
+---
+
+**Date de dernière mise à jour :** 2025-12-18
+**Version :** 1.0
+**Mainteneur :** Agence66