Borgmatic Backup

Configuration Borgmatic pour le backup automatique de serveur.

Vue d'ensemble

Ce dépôt contient la configuration complète pour effectuer des backups automatiques quotidiens à 3h du matin via Borgmatic et BorgBackup.

Version Borgmatic requise : ≥ 2.0.0 (pour l'interpolation des variables d'environnement)

Caractéristiques

• Backup quotidien automatique à 3h du matin via systemd timer
• Compression zstd pour un bon ratio performance/compression
• Rétention intelligente : 7 daily, 4 weekly, 6 monthly
• Notifications via ntfy pour succès/échec
• Compatible avec les backups Borg existants
• Sécurisé : chiffrement, exclusions de fichiers sensibles
• Déploiement automatique via Gitea Actions lors d'un push Git

Dossiers sauvegardés

• /var/www - Sites web
• /srv/* - Services applicatifs personnalisés
• /etc - Configurations système
• /opt/* - Applications tierces (Nextcloud, Traefik, Docker, etc.)
• /home - Répertoires utilisateurs

Installation

Prérequis

• Système Linux (Debian/Ubuntu/Arch/Fedora)
• Accès root
• Git installé
• Borgmatic ≥ 2.0.0 (pour l'interpolation des variables d'environnement)

Installation rapide

# Cloner le dépôt
git clone <url-du-repo>
cd agence66-borgmatic

# Copier et configurer les variables d'environnement
cp .env.example .env
nano .env  # Éditer avec vos valeurs

# Éditer la configuration si nécessaire
nano config.yaml  # Ajuster le repository Borg

# Exécuter l'installation
sudo ./install.sh

Configuration manuelle

Si vous préférez installer manuellement :

# Installer Borgmatic ≥ 2.0.0 via pipx (recommandé)
sudo apt install pipx
sudo pipx install borgmatic

# Créer les liens symboliques
sudo ln -sf /root/.local/bin/borgmatic /usr/local/bin/borgmatic
sudo ln -sf /root/.local/bin/generate-borgmatic-config /usr/local/bin/generate-borgmatic-config

# Installer BorgBackup
sudo apt install borgbackup  # Debian/Ubuntu
# ou
sudo pacman -S borg          # Arch Linux

# Copier les fichiers
sudo mkdir -p /etc/borgmatic/hooks
sudo cp config.yaml /etc/borgmatic/
sudo cp hooks/*.sh /etc/borgmatic/hooks/
sudo chmod +x /etc/borgmatic/hooks/*.sh

# Copier les variables d'environnement
sudo cp .env /etc/borgmatic/
sudo chmod 600 /etc/borgmatic/.env

# Installer les services systemd
sudo cp systemd/borgmatic.service /etc/systemd/system/
sudo cp systemd/borgmatic.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable borgmatic.timer
sudo systemctl start borgmatic.timer

Déploiement Automatique

Ce repository inclut un workflow Gitea Actions pour déployer automatiquement les modifications sur le serveur lors d'un push Git.

Configuration du déploiement automatique

1. Générer une clé SSH de déploiement

   ssh-keygen -t ed25519 -C "gitea-deploy-borgmatic" -f ~/.ssh/gitea-deploy-borgmatic
   

2. Installer la clé publique sur le serveur

   ssh-copy-id -i ~/.ssh/gitea-deploy-borgmatic.pub user@server
   

3. Configurer les secrets dans Gitea

   Allez dans Settings → Secrets de votre repository et ajoutez :

   • SERVER_HOST : adresse du serveur
   • SERVER_USER : utilisateur SSH
   • SSH_PRIVATE_KEY : contenu de ~/.ssh/gitea-deploy-borgmatic (clé privée complète)
   • SSH_PORT : port SSH (optionnel, 22 par défaut)

4. Activer Gitea Actions

   Vérifiez que Gitea Actions est activé dans votre instance Gitea (app.ini : [actions] ENABLED = true)

Utilisation

Une fois configuré, chaque push sur main déclenche automatiquement :

cd /opt/borgmatic
git pull origin main
make install

Consultez l'onglet Actions dans votre repository Gitea pour voir le statut du déploiement.

Documentation détaillée

Pour plus d'informations sur la configuration du déploiement automatique, consultez docs/GITEA-ACTIONS.md.

Configuration

Variables d'environnement (.env)

Éditez /etc/borgmatic/.env avec vos valeurs :

# Repository Borg
BORG_REPO=/path/to/your/repository
# ou pour un repo distant:
BORG_REPO=ssh://user@backup.server.com/path/to/repo

# Passphrase de chiffrement
BORG_PASSPHRASE=your-secure-passphrase

# Configuration ntfy
NTFY_URL=https://ntfy.sh/your-topic
NTFY_USER=username:password

Configuration Borgmatic (config.yaml)

Le fichier /etc/borgmatic/config.yaml contient la configuration principale.

Points importants à vérifier :

1. Repository : Décommentez et configurez votre repository dans la section location.repositories
2. Chemins : Ajustez source_directories si nécessaire
3. Exclusions : Personnalisez exclude_patterns selon vos besoins

Configuration de l'authentification SSH (repository distant)

Si vous utilisez un repository distant via SSH, configurez l'authentification par clé :

# 1. Générer une clé SSH pour root (si elle n'existe pas)
sudo ssh-keygen -t ed25519 -C "borgmatic-backup"
# Appuyez sur Entrée pour accepter l'emplacement par défaut
# Laissez la passphrase vide pour l'automatisation

# 2. Afficher la clé publique
sudo cat /root/.ssh/id_ed25519.pub

# 3. Copier la clé sur le serveur distant
sudo ssh-copy-id -p PORT user@backup-server.com

# 4. Tester la connexion (ne doit pas demander de mot de passe)
sudo ssh -p PORT user@backup-server.com

Alternative manuelle (si ssh-copy-id ne fonctionne pas) :

# Se connecter au serveur distant
ssh -p PORT user@backup-server.com

# Ajouter la clé publique
echo "VOTRE_CLE_PUBLIQUE" >> ~/.ssh/authorized_keys
exit

Initialisation du repository Borg

Si vous utilisez un nouveau repository :

# Repository local
borg init --encryption=repokey-blake2 /path/to/repo

# Repository distant
borg init --encryption=repokey-blake2 ssh://user@server/path/to/repo

IMPORTANT : Sauvegardez la clé de chiffrement !

borg key export /path/to/repo backup-key.txt
# Conservez ce fichier en lieu sûr !

Utilisation

Tester la configuration

# 1. Valider la syntaxe du fichier de configuration
sudo borgmatic config validate

# 2. Tester sans exécuter de backup (dry-run)
sudo borgmatic --dry-run --verbosity 2

# 3. Lister les fichiers qui seront sauvegardés
sudo borgmatic list --json

Note : borgmatic config validate vérifie uniquement la syntaxe YAML et la structure du fichier. Le dry-run teste la connexion au repository et simule un backup complet.

Exécuter un backup manuel

# Backup avec verbosité normale
sudo borgmatic --verbosity 1

# Backup avec verbosité détaillée
sudo borgmatic --verbosity 2

Vérifier le timer systemd

# Statut du timer
systemctl status borgmatic.timer

# Voir quand le prochain backup aura lieu
systemctl list-timers | grep borgmatic

# Logs du dernier backup
journalctl -u borgmatic.service -n 100

Lister les backups

# Lister toutes les archives
borgmatic list

# Informations détaillées
borg list /path/to/repo

Restaurer des fichiers

# Monter une archive pour explorer
mkdir /tmp/restore
borg mount /path/to/repo::backup-20250116-0300 /tmp/restore
cd /tmp/restore
# ... copier les fichiers nécessaires ...
cd /
borg umount /tmp/restore

# Extraire directement
borg extract /path/to/repo::backup-20250116-0300 path/to/file

# Avec borgmatic
borgmatic extract --archive backup-20250116-0300 --path path/to/file

Maintenance

Vérifier l'intégrité

# Vérification complète du repository
borgmatic check --verbosity 2

# Vérification rapide
borg check /path/to/repo

Nettoyer l'espace disque

Le nettoyage automatique (prune) est déjà configuré avec :

• 7 backups quotidiens
• 4 backups hebdomadaires
• 6 backups mensuels

Pour forcer un nettoyage manuel :

borgmatic prune --verbosity 1

Compacter le repository

Pour libérer réellement l'espace disque après prune :

borg compact /path/to/repo

Notifications

Les notifications sont envoyées via ntfy :

• ✅ Succès : notification normale avec le nom de l'archive
• ❌ Échec : notification haute priorité avec le message d'erreur

Testez manuellement les notifications :

# Test notification de succès
/etc/borgmatic/hooks/ntfy-success.sh "test-archive" ""

# Test notification d'erreur
/etc/borgmatic/hooks/ntfy-error.sh "Erreur de test"

Sécurité

• Les fichiers .env et les clés ne sont jamais commités (voir .gitignore)
• Les permissions des fichiers sensibles sont restrictives (600)
• Le service systemd utilise ProtectSystem=strict
• Les logs sont dans le journal systemd, accessible uniquement en root

Troubleshooting

Valider la configuration

Avant tout, vérifiez que votre configuration est valide :

# Valider la syntaxe
sudo borgmatic config validate

# Si erreur, vérifier les détails
sudo borgmatic config validate --verbosity 2

Erreurs courantes :

• repositories' is a required property : Manque la section repositories
• Additional properties are not allowed : Propriété invalide pour cette version
• Erreurs YAML : Vérifier l'indentation (utiliser des espaces, pas des tabs)

Le backup ne démarre pas

# Vérifier le timer
systemctl status borgmatic.timer

# Vérifier le service
systemctl status borgmatic.service

# Voir les logs
journalctl -u borgmatic.service -f

Erreur de connexion au repository

# Tester la connexion SSH (si distant)
sudo ssh -p PORT user@backup-server

# Vérifier les clés SSH
sudo ls -la /root/.ssh/

# Vérifier les variables d'environnement
sudo cat /etc/borgmatic/.env

# Tester Borg directement
sudo bash -c 'source /etc/borgmatic/.env && borg list $BORG_REPO'

Demande de mot de passe SSH

Si borgmatic demande le mot de passe du serveur distant :

# 1. Vérifier que la clé SSH existe
sudo ls /root/.ssh/id_ed25519

# 2. Si pas de clé, en générer une
sudo ssh-keygen -t ed25519 -C "borgmatic-backup"

# 3. Copier la clé sur le serveur
sudo ssh-copy-id -p PORT user@backup-server.com

# 4. Tester
sudo ssh -p PORT user@backup-server.com
# Ne doit PAS demander de mot de passe

Problème de permissions

# Vérifier les permissions des fichiers
ls -la /etc/borgmatic/
ls -la /etc/borgmatic/hooks/

# Corriger si nécessaire
sudo chmod 600 /etc/borgmatic/.env
sudo chmod 600 /etc/borgmatic/config.yaml
sudo chmod +x /etc/borgmatic/hooks/*.sh

Notifications ntfy ne fonctionnent pas

# Tester manuellement
curl -u "$NTFY_USER" \
  -H "Title: Test" \
  -d "Message de test" \
  "$NTFY_URL"

# Vérifier les variables
source /etc/borgmatic/.env
echo $NTFY_URL
echo $NTFY_USER

Ressources

• Documentation Borgmatic
• Documentation BorgBackup
• ntfy.sh

Support

Pour tout problème :

1. Consultez la section Troubleshooting
2. Vérifiez les logs : journalctl -u borgmatic.service -n 100
3. Testez en mode verbeux : borgmatic --verbosity 2

Licence

Configuration personnalisée pour usage personnel/professionnel.