some file

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 options available.

The NetBird package is officially included starting from OPNsense 25.7.3.

Prerequisites

  • Shell or Web UI access to your OPNsense system
  • A setup key 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

Enable the service

Navigate to VPN > NetBird > Settings and ensure the toggle Enable is turned on in the General section. This will enable us to continue with the next steps.

Authenticate the machine

Fill out the authentication form with the following values and click Save:

  • Management URL: Default is https://api.netbird.io:443. If self-hosting, enter your custom management server URL.
  • Setup Key: Paste the setup key from your NetBird account.

authentication

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.

connection status

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

interfaceAssignment

Click Add to assign the interface.

interfaceAssignment

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

enableInterface

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.

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.

firewallRules

Get started