some file

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

This installation is intended for early adopters while the pfSense package is under review and not yet available in the pfSense package manager.

Prerequisites

  • Shell/SSH access to pfSense (via Web UI shell or remote SSH)
  • A setup key to authenticate and register the pfSense device
  • The latest NetBird .pkg binary from the GitHub Releases

Installation

  1. SSH into your pfSense system

    ssh admin@<pfsense-ip>

    If remote SSH is enabled or use the built-in shell via the pfSense Web UI (Diagnostics > Command Prompt).

  2. Download the NetBird client(agent)

    From a shell on your pfSense system, run:

    fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.2/netbird-0.55.1.pkg

  3. Download the NetBird pfSense package

    From a shell on your pfSense system, run:

    fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.2/pfSense-pkg-NetBird-0.1.0.pkg

  4. Install the packages

    pkg add -f netbird-0.55.1.pkg
pkg add -f pfSense-pkg-NetBird-0.1.0.pkg

  5. Verify the installation

    The NetBird GUI should now appear under VPN > NetBird in the pfSense menu.

Configuration

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

authentication

Verify Connection Status

The Status page shows detailed information about connected peers and control services, helping you monitor your deployment. Access it via Status > NetBird in the pfSense menu.

Use this section for diagnostics and troubleshooting common connection or setup issues.

connection status

Assign NetBird interface

After authentication, a new interface named wt0(wt0) will be available but unassigned. To assign it go to Interfaces > Assignments. Under Available network ports, select the NetBird interface wt0(wt0) and click Add.

NewInterface

Enable the NetBird interface

Now that the NetBird interface has been added, you need to enable it. Go to Interfaces > OPT1, then configure the following options and click Save, then Apply changes to activate the interface:

  • Enable: ✓ Enable Interface
  • Description: NetBird

enableInterface

Configure Firewall Rules for the NetBird interface

To allow NetBird to handle all access control, permit all traffic on the NetBird interface in pfSense. This ensures traffic flows freely, while NetBird’s own policies (ACLs) govern the access restrictions.

Create rules to control traffic coming from your NetBird network into pfSense and your local networks:

  1. Go to Firewall > Rules and select the NetBird (interface) tab and click Add to create rules
  2. Configure the rule:
    • Action: Pass
    • Interface: NETBIRD
    • Address Family: in
    • Protocol: Any
    • Source: Any
    • Destination: Any
    • Description: Allow all on NetBird (managed by NetBird)
  3. Click Save, then Apply Changes

firewallRules

Uninstallation

From a shell on your pfSense system, run:

pkg delete netbird-0.55.1 pfSense-pkg-NetBird-0.1.0

Get started