Backup automatisé de la config OPNsense : ne plus jamais perdre sa configuration

Sur mon infra BOTUM, la configuration OPNsense représente des semaines de travail. Une panne, une mise à jour ratée ou une VM corrompue sans backup — et c'est tout à reconstruire. Ce guide couvre l'automatisation complète des sauvegardes OPNsense : XML, packages, stratégie 3-2-1, et disaster recovery en moins de 15 minutes.

Cet article fait partie de la série Stack OPNsense Enterprise. Retrouvez tous les billets sur le Hub du Stack OPNsense Enterprise.

Pourquoi sauvegarder la config OPNsense

OPNsense stocke toute sa configuration dans un seul fichier XML : /conf/config.xml. Ce fichier contient vos règles de pare-feu, vos VLANs, vos tunnels VPN, vos certificats SSL, vos utilisateurs et vos alias — potentiellement des jours de travail condensés en quelques kilooctets.

Sans backup, un crash disque, une mise à jour ratée, une corruption système ou une simple erreur humaine peut vous faire perdre toute votre configuration réseau en quelques secondes. Dans un contexte PME ou homelab avancé, cela signifie une coupure réseau totale jusqu'à ce que tout soit reconfiguré manuellement. Avec 200+ règles de firewall et une dizaine de VLANs, on parle d'une journée entière de travail.

Ce qu'il faut sauvegarder :

• config.xml — L'intégralité de la configuration : règles, interfaces, VPN, certificats, utilisateurs
• Packages installés — Liste des plugins (os-zerotier, os-wireguard, os-acme, etc.) pour réinstallation rapide
• RRD data — Graphiques de performance réseau (optionnel mais pratique)
• Certificats additionnels — Inclus dans config.xml mais à exporter séparément si utilisés dans d'autres services

La bonne nouvelle : OPNsense expose une API REST complète qui permet d'automatiser entièrement ce processus — sans plugin tiers, sans accès SSH requis, en quelques lignes de bash.

Backup manuel via l'interface OPNsense

Avant d'automatiser, comprendre le backup manuel est fondamental. Dans l'interface OPNsense, naviguez vers Diagnostics → Backup.

Trois options principales :

• Download configuration as XML : télécharge le config.xml complet, chiffré ou non
• Include extra data : inclut les données RRD (graphiques de performance)
• Include package info : liste les packages installés pour documentation

Pour la restauration manuelle, la même interface permet d'uploader un config.xml sauvegardé. OPNsense valide le fichier et redémarre automatiquement après application.

Commande cURL équivalente pour un test rapide :

# Backup one-shot via API OPNsense
curl -k -u 'votre-apikey:votre-apisecret' \
  -o opnsense-backup-$(date +%Y%m%d).xml \
  'https://192.168.1.1/api/core/backup/download/this'

Automatiser avec l'API REST OPNsense

L'API REST OPNsense est la clé de l'automatisation. Pour l'utiliser, créez d'abord une clé API dans System → Access → Users → [votre user] → API keys. Générez une paire clé/secret — gardez le secret en lieu sûr, il ne sera affiché qu'une seule fois.

Endpoints de backup essentiels :

# Télécharger la configuration courante
GET  /api/core/backup/download/this

# Lister les backups internes OPNsense
GET  /api/core/backup/list

# Restaurer un backup par ID
POST /api/core/backup/revertto/{backup_id}

# Supprimer un backup par ID
POST /api/core/backup/deleteback/{backup_id}

L'authentification utilise HTTP Basic Auth avec votre clé API et secret. Jamais votre mot de passe admin — les clés API sont révocables individuellement sans affecter l'accès admin.

Script de backup quotidien vers Git privé

Stocker la config OPNsense dans un repo Git privé offre des avantages uniques : historique complet de chaque modification, diff lisible entre versions (qui a changé quelle règle et quand), rollback instantané vers n'importe quel état passé, et audit trail pour la conformité.

#!/bin/bash
# /usr/local/bin/opnsense-backup.sh
# Backup quotidien OPNsense vers Git privé
set -euo pipefail

OPNSENSE_HOST='192.168.1.1'
API_KEY='votre-api-key'
API_SECRET='votre-api-secret'
BACKUP_DIR='/opt/opnsense-backups'
GIT_REPO='git@github.com:yourorg/opnsense-configs.git'
DATE=$(date +%Y-%m-%d_%H-%M)
LOG='/var/log/opnsense-backup.log'

log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG"; }

# Initialiser le repo si nécessaire
if [ ! -d "$BACKUP_DIR/.git" ]; then
  git clone "$GIT_REPO" "$BACKUP_DIR"
  log "Repo initialisé"
fi

cd "$BACKUP_DIR"
git pull --rebase origin main

# Télécharger la config XML
curl -sk -u "${API_KEY}:${API_SECRET}" \
  "https://${OPNSENSE_HOST}/api/core/backup/download/this" \
  -o "config-${DATE}.xml"

# Vérifier que le fichier est un XML OPNsense valide
if ! grep -q '' "config-${DATE}.xml" 2>/dev/null; then
  log "ERREUR: config.xml invalide, backup annulé"
  rm -f "config-${DATE}.xml"
  exit 1
fi

# Symlink vers latest
ln -sf "config-${DATE}.xml" config-latest.xml

# Commit et push (seulement si changements)
git add -A
if ! git diff --staged --quiet; then
  git commit -m "backup: ${DATE} [auto]"
  git push origin main
  log "Backup poussé vers Git: config-${DATE}.xml"
else
  log "Pas de changements depuis le dernier backup"
fi

# Rotation : garder les 30 derniers XML
ls -t config-20*.xml 2>/dev/null | tail -n +31 | xargs -r rm -f
git add -A
git diff --staged --quiet || git commit -m "rotation: nettoyage vieux backups"
git push origin main 2>/dev/null || true

Ajouter au cron pour une exécution quotidienne à 2h00 :

# crontab -e (en tant que root)
0 2 * * * /usr/local/bin/opnsense-backup.sh >> /var/log/opnsense-backup.log 2>&1

Backup vers stockage distant

Le Git local est un premier niveau, mais il ne protège pas contre la perte physique du serveur ou le feu dans le datacenter. Il faut absolument un backup hors site.

Option A — Amazon S3 (ou compatible : Wasabi, MinIO)

# Installer aws-cli sur le serveur de backup
apt install awscli -y
aws configure  # saisir key ID, secret, région

# Ajouter dans opnsense-backup.sh après le commit Git :
aws s3 cp "config-${DATE}.xml" \
  s3://mon-bucket-backup/opnsense/config-${DATE}.xml \
  --storage-class STANDARD_IA

# Politique de rétention S3 Lifecycle : 90 jours automatique

Option B — SFTP vers NAS ou serveur distant

# Générer une clé SSH sans passphrase pour l'automatisation
ssh-keygen -t ed25519 -f ~/.ssh/backup_opnsense -N ''
ssh-copy-id -i ~/.ssh/backup_opnsense.pub backup@nas.local

# Dans opnsense-backup.sh :
sftp -i ~/.ssh/backup_opnsense -b - backup@nas.local <

Option C — Proxmox Backup Server (PBS)

Si votre OPNsense tourne en VM Proxmox (voir le Billet 1 de la série), PBS peut sauvegarder l'intégralité de la VM automatiquement via les snapshots Proxmox. C'est la solution la plus complète : snapshots cohérents de la VM entière, restauration en 5 minutes.

# Dans Proxmox : configurer backup job pour la VM OPNsense
# Datacenter → Backup → Add job
# Storage: PBS, Mode: snapshot, Schedule: daily 03:00

Stratégie 3-2-1 appliquée à OPNsense

La stratégie 3-2-1 est le standard de référence de l'industrie pour les backups professionnels. Appliquée à OPNsense, voici l'implémentation concrète :

• 3 copies : config.xml sur le serveur local + repo Git privé + bucket S3
• 2 supports différents : stockage disque local + cloud object storage
• 1 hors site : S3 dans une région différente, ou SFTP vers un serveur distant

Ma configuration recommandée pour une PME :

# Fréquences recommandées
Backup local Git    : quotidien à 2h00 (cron)
Push S3             : intégré dans le script Git (automatique)
Snapshot PBS/Proxmox: hebdomadaire (dimanche 3h00)
Test de restauration: trimestriel (ajouté au calendrier)

Coût mensuel estimé : < $3/mois sur S3 Standard-IA pour 90 jours de backups OPNsense (fichiers XML = quelques centaines de KB).

Tester la restauration : procédure complète

Un backup non testé est un backup inutile. Je recommande de tester la restauration complète au moins une fois par trimestre, idéalement sur un OPNsense de test dans une VM Proxmox séparée.

Méthode 1 — Via l'interface web

1. Connectez-vous à OPNsense → Diagnostics → Backup
2. Section "Restore" → cliquer "Browse" → choisir le fichier config.xml sauvegardé
3. Cocher "Reboot after restore" → cliquer "Restore configuration"
4. Attendre le redémarrage (~2 minutes) → reconnecter à l'interface
5. Vérifier les règles, VLANs, VPN

Méthode 2 — Via l'API REST

# Uploader et restaurer via API
curl -k -u 'apikey:apisecret' \
  -X POST \
  -F 'conffile=@/opt/opnsense-backups/config-latest.xml' \
  'https://192.168.1.1/api/core/backup/restore'

# Vérifier le statut après redémarrage
curl -k -u 'apikey:apisecret' \
  'https://192.168.1.1/api/core/firmware/status'

Checklist de vérification post-restauration :

• ☑ Règles de firewall actives (LAN → WAN fonctionnel)
• ☑ VLANs présents et routés correctement
• ☑ Tunnels WireGuard / OpenVPN actifs
• ☑ DHCP distribuant les bonnes plages par VLAN
• ☑ DNS Unbound résolvant les noms locaux
• ☑ Certificats SSL toujours valides
• ☑ Suricata/CrowdSec actifs si déployés

Intégration Ansible pour disaster recovery < 15 min

Dans le Billet 12, nous avons vu comment déployer et configurer OPNsense entièrement avec Ansible. La combinaison backup automatisé + playbooks Ansible permet un disaster recovery complet en moins de 15 minutes — même sur un hardware neuf.

Le playbook de disaster recovery :

# playbook-opnsense-dr.yml
---
- name: OPNsense Disaster Recovery
  hosts: opnsense_new
  gather_facts: false
  vars:
    backup_source: 'git@github.com:yourorg/opnsense-configs.git'
    backup_file: 'config-latest.xml'

  tasks:
    - name: Clone le repo de backup
      git:
        repo: '{{ backup_source }}'
        dest: /tmp/opnsense-backup
        version: main

    - name: Restaurer la configuration OPNsense
      uri:
        url: 'https://{{ inventory_hostname }}/api/core/backup/restore'
        method: POST
        url_username: '{{ api_key }}'
        url_password: '{{ api_secret }}'
        body_format: form-multipart
        body:
          conffile:
            content: '{{ lookup("file", "/tmp/opnsense-backup/" + backup_file) }}'
            filename: 'config.xml'
        validate_certs: false
      register: restore_result

    - name: Attendre le redémarrage OPNsense
      wait_for:
        host: '{{ inventory_hostname }}'
        port: 443
        delay: 30
        timeout: 300

    - name: Vérifier les règles firewall
      uri:
        url: 'https://{{ inventory_hostname }}/api/firewall/filter/searchrule'
        url_username: '{{ api_key }}'
        url_password: '{{ api_secret }}'
        validate_certs: false
      register: rules_check

    - name: Rapport final
      debug:
        msg: "OPNsense restauré avec {{ rules_check.json.rowCount }} règles firewall"

Timeline typique d'un disaster recovery avec cette approche :

• 0-5 min : Installation OPNsense neuf sur hardware/VM + accès WebUI initial
• 5-8 min : ansible-playbook playbook-opnsense-dr.yml — restore config + redémarrage
• 8-12 min : Vérification automatisée (règles, VPN, DHCP)
• 12-15 min : Tests manuels + confirmation opérationnelle

Temps estimé : ~12 minutes avec un backup Git à jour. Bien en dessous de l'objectif des 15 minutes.

Conclusion : votre filet de sécurité réseau

La stratégie de backup OPNsense que nous venons de mettre en place — backup XML automatisé via API REST, versioning Git, réplication S3, stratégie 3-2-1, et disaster recovery Ansible — transforme une configuration fragile en infrastructure résiliente.

Le coût en temps d'implémentation : 2-3 heures. Le gain : dormir tranquille en sachant que même en cas de catastrophe, le réseau sera de retour en moins de 15 minutes.

Dans le Billet 14, nous passerons à la sécurisation des accès avec Let's Encrypt ACME — plus de certificats auto-signés sur votre interface OPNsense, et des certificats wildcard pour tous vos services internes.

📥 Guide PDF complet

Téléchargez ce guide en PDF pour le consulter hors ligne.

⬇ Télécharger le guide (PDF)

🚀 Aller plus loin avec BOTUM

Ce guide couvre les bases. En production, chaque environnement a ses spécificités. Les équipes BOTUM accompagnent les organisations dans le déploiement, la configuration avancée et la sécurisation de leur infrastructure. Si vous avez un projet, parlons-en.

Discuter de votre projet →

Série OPNsense 📋 Voir la série complète →

← B15 — OPNsense as Code Ansible B17 — Let's Encrypt + ACME →