netbird-docs/src/pages/get-started/install/opnsense.mdx

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


<YouTube videoId="AK0Ct-ULFKg" start={669} />

<Note>
    The NetBird package is officially included starting from OPNsense `25.7.3`.
</Note>


## Prerequisites
- Shell or Web UI access to your OPNsense system
- A [setup key](/manage/peers/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

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

<p>
    <img src="/docs-static/img/get-started/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/get-started/opnsense/status.png" alt="connection status" className="imagewrapper-big"/>
</p>

### 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/get-started/opnsense/interface_assignment.png" alt="interfaceAssignment" className="imagewrapper-big"/>
</p>

Click `Add` to assign the interface.
<p>
    <img src="/docs-static/img/get-started/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/get-started/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/get-started/opnsense/firewall_rules.png" alt="firewallRules" className="imagewrapper-big"/>
</p>

### Config for Troubleshooting Relayed Connections

By default, OPNsense uses automatic outbound NAT which randomizes source ports. This can cause issues with NetBird's NAT traversal (hole punching). To ensure reliable direct connections, you must configure a Static Port mapping.

1.  **Change Outbound NAT Mode**:
    -   Navigate to `Firewall` > `NAT` > `Outbound`.
    -   Select `Hybrid outbound NAT rule generation`.
    -   Click `Save`.

2.  **Add Static Port Rule**:
    -   Click `+` to add a new rule.
    -   **Interface**: `WAN`
    -   **TCP/IP Version**: `IPv4`
    -   **Protocol**: `UDP`
    -   **Source address**: `Single host or Network` (enter the IP address of your NetBird host)
    -   **Destination address**: `any`
    -   **Translation / Static-port**: Check `Static-port` box
    -   **Description**: `NetBird Static Port`
    -   Click `Save` and then `Apply changes`.

3.  **Reset States**:
    -   Go to `Firewall` > `Diagnostics` > `States`.
    -   Filter by the NetBird host IP.
    -   Delete the states.

4.  **Restart NetBird**:
    -   Run `netbird service restart` on the device.
    -   Run `netbird status -d` to verify the connection.

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