From 1ff03c70dd612f9f379481824cc05bef3f917a8b Mon Sep 17 00:00:00 2001 From: Administrator Date: Mon, 23 Feb 2026 21:48:14 +0000 Subject: [PATCH] docs: create Netgrimoire/Network/Security/OpnSense_Git --- Netgrimoire/Network/Security/OpnSense_Git.md | 182 +++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 Netgrimoire/Network/Security/OpnSense_Git.md diff --git a/Netgrimoire/Network/Security/OpnSense_Git.md b/Netgrimoire/Network/Security/OpnSense_Git.md new file mode 100644 index 0000000..e689d33 --- /dev/null +++ b/Netgrimoire/Network/Security/OpnSense_Git.md @@ -0,0 +1,182 @@ +--- +title: OpnSense +description: Git Integration +published: true +date: 2026-02-23T21:48:01.779Z +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