OPNsense Configuration Backup Role

Overview

This role backs up OPNsense firewall configuration using the OPNsense API to dual NAS storage. It downloads the complete configuration as XML, stores it with timestamps, and automatically manages retention by keeping only the last 5 backups per NAS. This provides disaster recovery capability for your firewall configuration.

Purpose

Disaster Recovery: Restore firewall configuration after hardware failure
Configuration Management: Track changes to firewall settings
Version History: Maintain 5 timestamped backups for rollback
Dual Redundancy: Backs up to two separate NAS devices (Synology DS418 and Proxmox OMV)
API-Based: Uses OPNsense’s native backup API
Automated Cleanup: Keeps only the last 5 backups per NAS

Requirements

Ansible 2.9 or higher
OPNsense firewall with API access enabled
API key and secret for backup user (stored in Ansible Vault)
NAS mount points must be accessible and writable
Network connectivity to OPNsense management interface

Role Variables

Required Variables

Variable	Required	Description
`vault_opnsense_bjoffrey_user_api_key`	Yes	OPNsense API key (stored in Ansible Vault)
`vault_opnsense_bjoffrey_user_api_secret`	Yes	OPNsense API secret (stored in Ansible Vault)

Optional Variables

Variable	Default	Description
`opnsense_conf_backup_syno_mount_point`	`/mnt/synology-ds418/opnsense/ansiblebackups`	Synology NAS backup destination
`opnsense_conf_backup_prxmxomv_mount_point`	`/mnt/prxmx-omv/opnsense/ansiblebackups`	Proxmox OMV NAS backup destination
`opnsense_conf_backup_validate_certs`	`true`	Validate SSL certificates
`opnsense_conf_backup_nases_path`	See defaults/main.yml	List of destination paths with timestamps

Variable Details

vault_opnsense_bjoffrey_user_api_key and vault_opnsense_bjoffrey_user_api_secret

API credentials for OPNsense. Must be created in OPNsense and stored in Ansible Vault.

How to create API credentials in OPNsense:

Log into OPNsense web interface
Go to System → Access → Users
Create or edit user for backups
Click ”+” to generate API key
Copy key and secret (secret shown only once!)
Grant user appropriate permissions

Example vault variables:

vault_opnsense_bjoffrey_user_api_key: "abc123def456ghi789jkl012mno345pqr678"
vault_opnsense_bjoffrey_user_api_secret: "xyz789uvw456rst123opq890lmn567ijk234"

opnsense_conf_backup_validate_certs

Set to false if using self-signed certificates on OPNsense.

Example:

opnsense_conf_backup_validate_certs: false

Dependencies

This role has no dependencies on other Ansible roles, but requires:

OPNsense firewall accessible via HTTPS
API user configured with backup permissions
NAS mounts configured (see nas_mount or nas_mount_systemd roles)

Example Playbook

Basic Usage

---
- name: Backup OPNsense Configuration
  hosts: localhost
  become: true

  roles:
    - opnsense_conf_backup

With Self-Signed Certificates

---
- name: Backup OPNsense Config (Self-Signed Cert)
  hosts: localhost
  become: true

  vars:
    opnsense_conf_backup_validate_certs: false

  roles:
    - opnsense_conf_backup

Scheduled Backup with Cron

---
- name: Schedule Daily OPNsense Config Backup
  hosts: localhost
  become: true

  tasks:
    - name: Create cron job for daily OPNsense backup
      ansible.builtin.cron:
        name: "Daily OPNsense Configuration Backup"
        minute: "0"
        hour: "2"
        job: "ansible-playbook /path/to/opnsense_backup.yml"

What This Role Does

Ensures backup directories exist on both NAS mount points
Downloads configuration XML using OPNsense API (/api/core/backup/download/this/)
Saves to both NAS locations with timestamped filename
Finds all existing backups on each NAS
Removes old backups, keeping only the 5 most recent per NAS

Authentication

The role uses HTTP Basic Authentication with API credentials:

GET /api/core/backup/download/this/
Authorization: Basic {base64(api_key:api_secret)}

This is OPNsense’s standard API authentication method.

Backup Format

File Naming

opnsense_backup_YYYYMMDDTHHMMSS.xml

Examples:

opnsense_backup_20260107T143022.xml
opnsense_backup_20260107T190530.xml

XML Content

The backup is a complete OPNsense configuration XML file containing:

<?xml version="1.0"?>
<opnsense>
  <version>26.1</version>
  <lastchange/>
  <system>
    <hostname>opnsense</hostname>
    <domain>localdomain</domain>
    ...
  </system>
  <interfaces>
    <lan>...</lan>
    <wan>...</wan>
  </interfaces>
  <firewall>
    <rule>...</rule>
  </firewall>
  <nat>...</nat>
  <dhcpd>...</dhcpd>
  ...
</opnsense>

Backup Content

The backup includes:

System settings (hostname, domain, DNS)
Interface configurations (IPs, VLANs, assignments)
Firewall rules (all rules and aliases)
NAT configuration (port forwards, outbound)
DHCP server settings
VPN configurations (OpenVPN, IPsec, WireGuard)
Routing tables and gateways
Services configuration (DNS, NTP, etc.)
Installed plugins (list only, not plugin data)
Certificate store
User accounts and privileges

The backup does NOT include:

Log files
Package binaries
RRD graphs data
Plugin-specific databases (must backup separately)
Firmware version (configuration is version-agnostic)

Backup Retention

The role implements automatic retention management:

Keeps: Last 5 backups per NAS
Deletes: Backups older than the 5th most recent
Per-NAS logic: Each NAS independently maintains 5 backups

This ensures you have:

5 backups on Synology DS418
5 backups on Proxmox OMV
Total: Up to 10 backup copies across both devices

Restoration

Via OPNsense Web UI

Log into OPNsense
Go to System → Configuration → Backups
Click “Choose File” and select XML backup
Click “Restore Configuration”
OPNsense will reboot with restored configuration

Via Console

# Upload XML to OPNsense
scp opnsense_backup_20260107T143022.xml root@opnsense:/conf/backup/

# Restore via console
/usr/local/etc/rc.restore_config /conf/backup/opnsense_backup_20260107T143022.xml

# Reboot
shutdown -r now

Important Notes

Reboot Required: OPNsense reboots after configuration restore
Version Compatibility: Restore on same or newer OPNsense version
Network Interruption: Expect brief network outage during restore
Test First: Restore to test firewall before production

Security Considerations

API Credentials: Protected with HTTP Basic Auth over HTTPS
Vault Storage: API key/secret must be in Ansible Vault
Certificate Validation: Enabled by default
Sensitive Data: XML contains certificates, VPN keys, passwords (hashed)
File Permissions: Backup files created with default permissions (consider encryption)

Notes

Uses OPNsense inventory variable: hostvars['opnsense']['ip_vlan10']
Downloads complete configuration (not incremental)
Typical XML file size: 50-500 KB depending on configuration complexity
Fast download (<1 second for most configurations)
No impact on firewall performance during backup

Troubleshooting

”Unauthorized” or 401 errors

Verify API credentials:

Check key and secret are correct in OPNsense
Ensure API user has backup permissions
Verify credentials are properly vaulted

Test manually:

curl -u "API_KEY:API_SECRET" \
  https://opnsense-ip/api/core/backup/download/this/ \
  -o test_backup.xml

“Permission denied” when writing to NAS

Ensure:

NAS is mounted: mount | grep synology
Backup directories exist and are writable
User has write permissions

”Connection refused” or timeout errors

Verify:

OPNsense is reachable: ping opnsense-ip
HTTPS port accessible: nc -zv opnsense-ip 443
Firewall allows management access from Ansible host

SSL certificate verification fails

If using self-signed certificate:

opnsense_conf_backup_validate_certs: false

Empty or invalid XML file

Check:

API user has correct permissions in OPNsense
OPNsense API is enabled (System → Settings → Administration)
API endpoint is correct for your OPNsense version

API Endpoint Details

Download Configuration

GET /api/core/backup/download/this/
Authorization: Basic {base64(api_key:api_secret)}

Parameters:

this: Downloads current active configuration

Response: XML file (application/xml)

HTTP Status:

200: Success (XML returned)
401: Authentication failed
403: Insufficient permissions

OPNsense Version Compatibility

OPNsense 21.x: Full support
OPNsense 22.x: Full support
OPNsense 23.x: Full support
OPNsense 24.x: Full support (latest)

The backup API endpoint has been stable across versions.

Best Practices

Schedule daily backups (firewall changes are critical)
Test restoration periodically on test firewall
Keep offsite copies (the dual NAS approach provides good redundancy)
Document restore procedure for disaster recovery
Verify backups occasionally (check XML is valid)
Before major changes take manual backup as safety net

Alternative: Manual Backup

If you prefer manual backup:

# Via API
curl -u "API_KEY:API_SECRET" \
  -o opnsense_backup_$(date +%Y%m%dT%H%M%S).xml \
  https://opnsense-ip/api/core/backup/download/this/

# Via Web UI
# System → Configuration → Backups → Download configuration

This role is standalone but often used with:

opnsense_firewall: Manages firewall rules
opnsense_aliases: Manages firewall aliases
opnsense_source_nat: Configures NAT rules

Disaster Recovery Planning

RTO (Recovery Time Objective): ~10-15 minutes

Install fresh OPNsense (5-10 minutes)
Restore configuration from backup (1 minute)
Reboot and verify (2-3 minutes)

RPO (Recovery Point Objective): Up to 24 hours (if daily backups)

Mitigation:

Run backups more frequently (every 6 hours) for lower RPO
Keep hot standby firewall for HA
Test restoration quarterly

License

MIT

Author

Created for homelab infrastructure management.

OPNsense Conf Backup