All posts Guide

How to Back Up OPNsense Firewall Configurations to Your Own S3 Bucket

GUIDE 6 MIN READ NETDEFENSE TEAM

OPNsense keeps a firewall’s whole configuration in one file, and every firewall can export it. Across a fleet, that’s one export, one schedule and one place to check per box, and the copy you need most is the one that sat on the firewall that just failed.

This guide sends that file somewhere else: each firewall encrypts its configuration with a key you set, and NetDefense puts it in an S3-compatible bucket you own, on a schedule, with every firewall’s last result on one page.

TL;DR

  • Create a bucket and an access key that can write to it.
  • Give NetDefense the bucket, a named schedule and an encryption key, test the connection, and turn the configuration on.
  • Turn backups on for each firewall, run one now, and read each firewall’s last backup on the Backups page.
  • The files are yours to read with openssl. NetDefense doesn’t restore, compare or keep a history of them.

How a backup travels

On your schedule or on demand, the firewall encrypts its configuration with a key you set, and NetDefense sends it to an S3-compatible bucket you own. on your schedule, or right now OPNsense Firewall config encrypted here, with a key you set NetDefense sends it to your bucket Your bucket S3-compatible storage

When a backup runs, NetDefense sends the firewall’s agent a backup task carrying the encryption key. The agent encrypts the configuration on the firewall with AES-256, in the same format OPNsense uses for its own encrypted backups, and sends it back to NetDefense, which uploads it to your bucket. Each run writes a new file, named for the firewall and the time: opnsense/config-br-east-albany-20261105T080000Z.xml.

NetDefense holds the key, so it can send it with every backup task, but it never shows it back: neither the web console nor the API returns it once it’s saved. The encryption protects the file in your bucket. It isn’t a secret from NetDefense.

Step 1: A bucket and a key that can write to it

Create a bucket with your storage provider, any that offers an S3-compatible API. It has to be reachable from the internet: NetDefense uploads the file, not the firewall, and it refuses an endpoint that points to a private, loopback or reserved address, both when you save and when you test. Then create an access key for NetDefense that can only reach that bucket:

  • Uploads need permission to write objects: s3:PutObject.
  • Test Connection, in step 3, checks that the bucket exists with a HeadBucket request, which AWS allows with s3:ListBucket.

NetDefense never deletes or overwrites a backup, so the key needs nothing else. How long the files stay is up to the bucket’s own lifecycle rules.

Step 2: Pick a schedule

Backups run on a named schedule, the same kind that drives recurring syncs and commands. Open Schedules, click New schedule, and give it a name, a cron expression and a timezone, such as nightly-backups, 0 2 * * * and America/Chicago. Click Create schedule.

Step 3: Point NetDefense at the bucket

Open Backups and fill in the S3 Backup Configuration card:

  • S3 Endpoint, S3 Bucket, Access Key ID and Secret Access Key, from step 1.
  • S3 Folder/Prefix, optional, such as opnsense, to keep the files in one folder of the bucket.
  • Backup cadence: under Pick a schedule…, choose nightly-backups. It’s attached when you save.
  • Encryption Key and Confirm Encryption Key. Don’t leave the key empty: a firewall with no key isn’t backed up.

Click Create Configuration, then Test Connection. A failed test names the cause, such as rejected credentials, a missing bucket or an endpoint that doesn’t answer.

A new configuration starts out disabled. Turn it on with the switch at the top of the card, and the card reads Scheduled.

Keep your own copy of the key

The console says it plainly: “This key cannot be retrieved once saved. Store it securely - backups cannot be restored without it.” Put the key in your password manager before you save it.

Step 4: Turn backups on for each firewall

Each firewall is off until you turn it on. In the Device Backup Status table on the same page, switch Enabled on for every firewall you want backed up. A firewall left off is never backed up, schedule or not.

A firewall uses the organization’s key unless it has its own. For one whose backups need a separate key, choose Set custom key… in its Encryption Key menu. The same warning applies: keep a copy.

Step 5: Back up now and check

You don’t have to wait for the first night. On Run, pick the Backup command, choose the firewalls or OUs, and click Run now. Only firewalls with backups enabled are backed up. A firewall that’s offline doesn’t take the backup later: its task expires after about a minute.

Back on Backups, each firewall’s row shows its Last Backup, its Status and the Message it ended with: where the file went, or why it failed. Each run is also a BACKUP task on the Tasks page.

Reading a backup without NetDefense

A backup file is the firewall’s config.xml, encrypted. To read one, download it from the bucket and decrypt it with openssl, which asks for the key:

decrypt a backup bash
$ sed '1,/^$/d; /^---- END/d' config-br-east-albany-20261105T080000Z.xml \
  | openssl base64 -d \
  | openssl enc -d -aes-256-cbc -md sha512 -pbkdf2 -iter 100000 -out config.xml

The sed drops the header lines and the footer around the encrypted text. What comes out is the firewall’s configuration as plain XML.

What NetDefense doesn’t do

  • No restore. NetDefense writes the files. It doesn’t put a configuration back on a firewall.
  • No comparing or history in the console. Every run adds a file to your bucket, and the Backups page shows each firewall’s last result only.
  • No cleanup. Old files stay until your bucket’s lifecycle rules remove them.

The same thing from the terminal

Every step has an NDCLI equivalent. ndcli backup config set asks for the secret access key and the encryption key, so neither ends up in your shell history:

ndcli bash
$ ndcli schedule create --name nightly-backups --cron "0 2 * * *" --timezone America/Chicago
$ ndcli backup config set --s3-endpoint https://s3.us-east-1.amazonaws.com --s3-bucket cvl-firewall-backups --s3-folder opnsense --s3-key-id AKIAIOSFODNN7EXAMPLE --schedule nightly-backups
$ ndcli backup config test
$ ndcli backup config enable
$ ndcli backup enable br-east-albany
$ ndcli run backup --device br-east-albany
$ ndcli backup status

The Backups and Schedules guides cover each piece in depth.

Related reading

Security Direct-Peer Remote Sessions: a Straight Line to Your Firewall
Feature WebAdmin Through Connect Now Loads Faster
Security NetDefense Agent 1.31.0: Check SSL Verification Before You Upgrade

Enjoyed this post? Explore more in the documentation.