182 lines
5.9 KiB
Markdown
182 lines
5.9 KiB
Markdown
---
|
|
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 <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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
- [OPNsense Firewall](./opnsense-firewall) — parent firewall documentation
|
|
- [Forgejo](./forgejo) — Git repository host on Netgrimoire
|
|
- [Kopia Backups](./kopia) — offsite backup chain
|