traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Netgrimoire/Ward-Grimoire/Firewall/OPNsense-Git-Backup.md
traveler cc574f8aed New Grimoire
2026-04-12 09:53:51 -05:00

5.9 KiB
Raw Blame History

title description published date tags editor dateCreated
OpnSense - GIT Integration Git Integration true 2026-02-23T21:53:24.522Z markdown 2026-02-23T21:48:01.779Z

OPNsense Git Backup (os-git-backup)

Service: os-git-backup Plugin: os-git-backup Host: OPNsense firewall Remote: Forgejo on Netgrimoire Trigger: Automatic on every config change

Overview

Every change made to OPNsense — adding a firewall rule, updating an alias, changing a VPN config — modifies the underlying XML configuration file. By default there is no history of these changes. If a misconfiguration causes an outage, or if you need to audit what changed after a security incident, you have no record to work from.

os-git-backup solves this by committing the OPNsense configuration to a Git repository automatically every time a change is saved. Each commit records exactly what changed, when, and (if configured) which user made the change.

Benefits:

  • Full audit trail of every configuration change
  • One-command rollback to any previous state
  • Offsite backup of firewall config via Forgejo → Kopia chain
  • Diff view to understand exactly what a change did

Pre-requisite: Create Forgejo Repository

Before installing the plugin, create a dedicated repository in Forgejo to receive the OPNsense config backups.

  1. Log into your Forgejo instance on Netgrimoire
  2. Create a new repository: opnsense-config
  3. Set visibility to Private — firewall configs contain sensitive network topology
  4. Do not initialize with a README (the plugin will push the first commit)
  5. Note the SSH clone URL: git@git.netgrimoire.com:youruser/opnsense-config.git

Installation

Step 1 — Install the Plugin

  1. Go to System → Firmware → Plugins
  2. Search for os-git-backup
  3. Click the + install button
  4. Wait for installation to complete
  5. Navigate to System → Configuration → Backups — a Git tab will appear

Configuration

Step 2 — Generate SSH Deploy Key

The OPNsense firewall needs an SSH key to authenticate to Forgejo without a password.

Navigate to System → Configuration → Backups → Git

  1. Click Generate SSH Key
  2. Copy the displayed public key — you will add this to Forgejo next

Step 3 — Add Deploy Key to Forgejo

  1. In Forgejo, go to your opnsense-config repository
  2. Navigate to Settings → Deploy Keys
  3. Click Add Deploy Key
  4. Title: OPNsense Firewall
  5. Key: paste the public key from Step 2
  6. Enable Allow Write Access — the firewall needs to push commits
  7. Click Add Key

Step 4 — Configure the Plugin

Navigate to System → Configuration → Backups → Git

Setting Value Notes
Enabled ✓
URL git@git.netgrimoire.com:youruser/opnsense-config.git SSH URL from your Forgejo repo
Branch main
Name OPNsense Firewall Author name shown in commits
Email opnsense@netgrimoire.com Author email shown in commits
SSH Private Key (auto-populated from Step 2)
Backup Interval On change Commits every time config is saved

Click Save.

Step 5 — Test the Connection

Click Backup Now to trigger a manual backup. Then check your Forgejo repository — you should see an initial commit containing the OPNsense configuration XML.

If the push fails, check:

  1. The deploy key has write access in Forgejo
  2. The SSH URL is correct (use SSH, not HTTPS)
  3. Forgejo is reachable from the firewall — test from OPNsense shell: 
    ssh -T git@git.netgrimoire.com
# Expected: Hi youruser! You've successfully authenticated...

What Gets Backed Up

The plugin commits the OPNsense configuration file:

/conf/config.xml

This single file contains everything — interfaces, firewall rules, NAT, VPN configs, aliases, users, certificates, DHCP, DNS settings, and all plugin configurations. A restore from this file fully recreates the firewall state.

⚠ The config.xml contains hashed passwords, VPN private keys, and API credentials. The Forgejo repository must remain private. Ensure your Forgejo instance is not publicly accessible or that this repository is explicitly private.

Using the Backup

Viewing History

In Forgejo, navigate to the opnsense-config repository. Each commit represents one configuration save, with:

  • Timestamp of the change
  • Diff showing exactly what XML changed
  • Author (OPNsense Firewall)

Rolling Back a Change

If a configuration change causes problems:

Option 1 — Restore via OPNsense UI:

  1. In Forgejo, find the commit you want to restore
  2. Download the config.xml from that commit
  3. In OPNsense: System → Configuration → Backups → Restore
  4. Upload the config.xml and restore

Option 2 — Restore via shell (if UI is unreachable):

# SSH into OPNsense
ssh root@192.168.3.4

# The git repo is cloned locally — find it
find /conf -name ".git" -type d

# Check out the previous config
cd /conf/backup   # or wherever the repo is cloned
git log --oneline -10
git checkout <commit-hash> -- config.xml

# Apply the restored config
/usr/local/sbin/opnsense-importer config.xml

Diffing Changes

To see exactly what a specific change did:

# In Forgejo: click any commit → view the diff
# Alternatively, from the OPNsense shell:
cd <git repo path>
git diff HEAD~1 HEAD -- config.xml

Integration with Kopia Backups

Since the git repository lives in Forgejo on Netgrimoire, it is automatically included in the Netgrimoire Kopia backup chain — no additional configuration needed. The OPNsense config history is backed up offsite along with everything else.

Related Documentation