low riskinformational~20 min

Runbook: Backup Firewall Configuration

1 · Prerequisites

Confirm every item is in place before any state change.

OPNsense appliance running a supported version
Console or GUI access to the firewall
Off-appliance destination for the backup file (not the same disk)

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· Confirm the current configuration is in a known-good state
· Identify the destination for the backup file (a remote server, a version-control repository, or an offsite bucket)
· Confirm the backup file is not stored on the same disk as the firewall configuration
· Confirm the backup filename includes the firmware version and the date

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Open System > Configuration > Backups and click Download configuration
2Save the file with a timestamped name such as opnsense-backup-YYYY-MM-DD.xml
3For a single-section backup, navigate to the relevant section (rules, aliases, firewall) and click Download this section
4For an automated backup, configure System > Configuration > Backups > Backup now and a cron schedule under System > Cron
5For an off-host backup, use the configctl config backup command from the shell and copy the file to the remote destination
6Verify the backup file is a valid XML and contains the expected sections (<rules>, <aliases>, <filter>)
7Note the firmware version and the appliance hostname in the file metadata or as a sibling file
8Repeat the backup on the peer appliance in an HA pair so both configurations are captured

4 · Verification

Confirm the procedure actually fixed the problem.

✓The backup file exists on the off-appliance destination and is readable from a fresh shell
✓The backup file is a valid XML and contains the expected sections
✓A test restore on a lab appliance produces a working configuration

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶If the backup file is corrupt or incomplete, repeat the backup from a fresh capture
↶If the off-appliance destination is unavailable, fall back to a local copy and move it as soon as the destination is reachable
↶Do not delete the previous backup until the new backup is verified

6 · Escalation

When the runbook isn't enough, contact:

· Escalate to the platform team if the backup file cannot be generated from the GUI
· Escalate to the security team if the backup file contains credentials that should be stored elsewhere
· Escalate to the storage team if the off-appliance destination is unavailable

Purpose

Capture a working configuration of an OPNsense appliance so it can be restored after a misconfiguration, a hardware failure, or a software regression.

When to use this runbook

Use this runbook before any significant change, as part of a scheduled backup cadence, and after every successful maintenance window. The backup is the precondition for every other recovery runbook.

Pre-checks

Before starting the procedure, confirm the prerequisites and pre-checks are met. The structured lists are rendered from the frontmatter by the page layout.

Procedure

Follow the steps from the frontmatter procedure steps. The page layout renders the steps as a checklist with copy-to-clipboard affordances.

Verification

After the procedure, the structured verification items from the frontmatter are rendered as a checklist.

Rollback

If the procedure fails or makes things worse, follow the structured rollback steps from the frontmatter.

Escalation

The structured escalation path is rendered from the frontmatter. Use it if the operator cannot complete the procedure safely.