---
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
