Add OPNsense guide (#404)

* add opnsense docs Signed-off-by: bcmmbaga <bethuelmbaga12@gmail.com> * Add configuration instructions for NetBird interface in OPNsense Signed-off-by: bcmmbaga <bethuelmbaga12@gmail.com> * Clarify navigation steps Signed-off-by: bcmmbaga <bethuelmbaga12@gmail.com> * refactor Signed-off-by: bcmmbaga <bethuelmbaga12@gmail.com> --------- Signed-off-by: bcmmbaga <bethuelmbaga12@gmail.com>
2026-04-16 15:36:36 +00:00 · 2025-08-26 20:25:30 +03:00
parent c810a0a9da
commit 28eb59221d
8 changed files with 115 additions and 0 deletions
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -40,6 +40,7 @@ export const docsNavigation = [
              { title: 'Synology', href: '/how-to/installation/synology' },
              { title: 'Android/iOS', href: '/how-to/installation/mobile' },
              { title: 'pfSense', href: '/how-to/installation/pfsense' },
+              { title: 'OPNsense', href: '/how-to/installation/opnsense' },
            ],
      },
      { title: 'CLI', href: '/how-to/cli' },
--- a/src/pages/how-to/installation/opnsense.mdx
+++ b/src/pages/how-to/installation/opnsense.mdx
@@ -0,0 +1,114 @@
+# OPNsense Installation
+
+The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available,
+there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.
+
+<Note>
+    The NetBird package is officially included starting from OPNsense `26.0`. At the time of writing, it is available via
+    the `opnsense-devel` firmware (`26.1.a_83`) and will be part of the next stable release.
+</Note>
+
+
+## Prerequisites
+- Shell or Web UI access to your OPNsense system
+- A [setup key](/how-to/register-machines-using-setup-keys#types-of-setup-keys) to authenticate and register the OPNsense device
+
+## Installation
+
+1. **Log in to your OPNsense system**
+
+    You can use the Web UI or SSH.
+
+2. **Install the NetBird package**
+
+    In the OPNsense Web UI, navigate to `System` > `Firmware` > `Plugins`, and search for the `os-netbird` package. Click the install button next to it.
+
+3. **Verify the installation**
+
+    Once installed, the NetBird configuration interface will be available under `VPN` > `NetBird` in the OPNsense menu
+
+## Configuration
+
+### Assign NetBird interface
+After installation, a new interface named `wt0` will be available but unassigned. To assign it go to `Interfaces` >
+`Assignments`. Under `Assign a new interface`, set the following values:
+- **Device**: `wt0`
+- **Description**: `NetBird`
+
+<p>
+    <img src="/docs-static/img/how-to-guides/opnsense/interface_assignment.png" alt="interfaceAssignment" className="imagewrapper-big"/>
+</p>
+
+Click `Add` to assign the interface.
+<p>
+    <img src="/docs-static/img/how-to-guides/opnsense/new_interface.png" alt="interfaceAssignment" className="imagewrapper-big"/>
+</p>
+
+
+### Enable the NetBird interface
+Now that the NetBird interface has been added, you need to enable it. Go to `Interfaces` > `[NetBird]`, then configure
+the following options and click `Save`, then `Apply changes` to activate the interface:
+- **Enable**: `✓ Enable Interface`
+- **Lock**: `✓ Prevent interface removal`
+
+<p> <img src="/docs-static/img/how-to-guides/opnsense/enable_interface.png" alt="enableInterface" className="imagewrapper-big"/> </p>
+
+<Note>
+OPNsense includes native WireGuard support, however do not configure or manage the NetBird interface (wt0) via the OPNsense WireGuard UI.
+    NetBird fully manages the WireGuard interface and keys.
+</Note>
+
+### Configure Firewall Rules for the NetBird interface
+To allow NetBird to handle all access control, permit all traffic on the NetBird interface in OPNsense.
+This ensures traffic flows freely, while NetBird’s own policies (ACLs) govern the access restrictions.
+
+1. Navigate to `Firewall` > `Rules` > `NetBird`.
+2. Click `+ Add` to create a new rule.
+3. Configure the rule:
+   - **Action**: `Pass`
+   - **Interface**: `NetBird`
+   - **Direction**: `in`
+   - **TCP/IP Version**: `IPv4`
+   - **Protocol**: `any`
+   - **Source**: `any`
+   - **Destination**: `any`
+   - **Description**: `Allow all on NetBird (managed by NetBird)`
+4. Click `Save`, then `Apply changes`.
+5. Ensure this rule is at the top of the `NetBird` rules list so it isn’t shadowed by other rules.
+
+<p>
+    <img src="/docs-static/img/how-to-guides/opnsense/firewall_rules.png" alt="firewallRules" className="imagewrapper-big"/>
+</p>
+
+### Authenticate the machine
+
+Fill out the authentication form with the following values and click `Save`:
+
+- **Management URL**: Default is `https://app.netbird.io:443`. If self-hosting, enter your custom management server URL.
+- **Setup Key**: Paste the setup key from your NetBird account. .
+
+<p>
+    <img src="/docs-static/img/how-to-guides/opnsense/authentication.png" alt="authentication" className="imagewrapper-big"/>
+</p>
+
+### Verify Connection Status
+
+The Status page shows detailed information about connected peers and control services, helping you monitor your deployment.
+Access it via `VPN` > `NetBird` > `Status` in the OPNsense menu.
+
+Use this section for diagnostics and troubleshooting common connection or setup issues.
+
+<p>
+    <img src="/docs-static/img/how-to-guides/opnsense/status.png" alt="connection status" className="imagewrapper-big"/>
+</p>
+
+
+## Get started
+<p float="center" >
+    <Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
+</p>
+
+- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
+- Follow us [on X](https://x.com/netbird)
+- Join our [Slack Channel](/slack-url)
+- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub