Reference architecture — Monitoring, logging, and backup

A firewall without observability is a firewall the operator cannot diagnose. The reference architecture integrates with the RunBook Academy Observability stack:

• Logs go to Loki via syslog or Promtail.
• Metrics go to Prometheus via the OPNsense exporter.
• Configuration is backed up off-device and verified weekly.

Logging to the central stack

OPNsense ships syslog. The configuration under System → Settings → Logging allows:

• Remote syslog server (IP and port, typically UDP 514 or TCP 601).
• Per-log-class filtering (firewall, system, DNS, VPN).
• TLS for syslog (RFC 5425).

The reference architecture ships all log classes to the central syslog endpoint, with TLS enabled. The TLS certificate is the OPNsense-bundled certificate or an internal-CA-signed certificate.

$ syslog-ng -F --cfgfile=/var/etc/syslog-ng.conf

[2026-08-14 14:23:01] syslog-ng starting up; version='4.5'

The central observability stack receives the syslog traffic on its syslog endpoint (e.g., Promtail’s syslog listener or syslog-ng-relay). Promtail extracts labels (facility, severity, hostname, programme) and ships the records to Loki.

Metrics to Prometheus

The OPNsense Prometheus exporter runs on the firewall itself or on a small Linux VM that polls the OPNsense API. The exporter exposes:

• opnsense_system_cpu_usage (gauge)
• opnsense_system_memory_usage (gauge)
• opnsense_interface_* (per-interface traffic, errors, drops)
• opnsense_gateway_status (per-gateway up/down)
• opnsense_firewall_rule_count (gauge)
• opnsense_state_table_entries (gauge)
• opnsense_dhcp_leases_total (gauge)

The exporter authenticates to the OPNsense API with a dedicated read-only API key (created under System → Access → Users → API keys).

Prometheus scrapes the exporter endpoint every 15 seconds. Grafana dashboards query Prometheus for the metrics.

Configuration backup

OPNsense’s configuration backup is an XML file containing the entire configuration. The reference architecture backs up:

• Daily, the XML configuration, pushed to an off-device storage (Ansible-pull, scp, or a backup tool).
• Encrypted, using openssl enc -aes-256-gcm or gpg with a passphrase from the secrets manager.
• Versioned, in a Git repository with meaningful commit messages.

$ curl -k -u "$KEY:$SECRET" https://opnsense.example.com/api/core/backup/download/this -o /var/backups/opnsense/$(date +%Y%m%d).xml

Backup verification

A backup that has never been restored is a backup that might not work. The reference architecture runs a weekly verification:

1. Pull the latest backup from storage.
2. Decrypt with the passphrase from the secrets manager.
3. Validate the XML (xmllint or Python xml parser).
4. Diff against the running configuration to identify any expected or unexpected drift.
5. Restore to a disposable VM and verify that it boots and that the GUI is reachable.

The verification is automated. A failure (XML invalid, restore VM does not boot) pages the on-call operator.

What is not in the reference architecture

The reference architecture deliberately does not include:

• Direct Internet management access. The GUI is reachable only from the management VLAN.
• Default-allow rules. Every inter-VLAN rule is explicit.
• Cleartext remote syslog. All syslog is TLS.
• Storing VPN private keys on the firewall in plain text. WireGuard private keys live in the OPNsense config, which is encrypted at rest by the configuration backup pipeline.
• Configuration snapshots older than 90 days in primary storage. Older backups go to cold storage; the primary storage carries the last 90 days for fast recovery.