--- title: OpnSense - GIT Integration description: Git Integration published: true date: 2026-02-23T21:53:24.522Z tags: editor: markdown dateCreated: 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: ```bash 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):** ```bash # 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 -- config.xml # Apply the restored config /usr/local/sbin/opnsense-importer config.xml ``` ### Diffing Changes To see exactly what a specific change did: ```bash # In Forgejo: click any commit → view the diff # Alternatively, from the OPNsense shell: cd 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 - [OPNsense Firewall](./opnsense-firewall) — parent firewall documentation - [Forgejo](./forgejo) — Git repository host on Netgrimoire - [Kopia Backups](./kopia) — offsite backup chain