NetBird Setup Guide: Building a WireGuard Mesh VPN

NetBird combines zero-configuration peer-to-peer networking with a centralized access control layer. This platform allows you to build a secure private network for professional or personal use while bypassing the complexities typically associated with traditional VPNs.

Technically, NetBird functions as an overlay network built on top of WireGuard. It automatically establishes encrypted tunnels between devices, removing the need to open ports, manage convoluted firewall rules, or maintain a dedicated VPN gateway. Access policies remain granular and are managed through a single web console, ensuring secure remote access remains functional regardless of your underlying infrastructure.

Installation by Platform

Linux

Automated Install Script

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Ubuntu/Debian (APT)

1. Add the repository:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
curl -sSL https://pkgs.netbird.io/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/netbird-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netbird-archive-keyring.gpg] https://pkgs.netbird.io/debian stable main' | sudo tee /etc/apt/sources.list.d/netbird.list

2. Update the package cache:

sudo apt-get update

3. Install the client:

# For the CLI only:
sudo apt-get install netbird
# For CLI and GUI:
sudo apt-get install netbird-ui

RHEL/Amazon Linux 2 (RPM)

1. Add the repository:

sudo tee /etc/yum.repos.d/netbird.repo <<EOF
[netbird]
name=netbird
baseurl=https://pkgs.netbird.io/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.netbird.io/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF

2. Install the client:

# For the CLI only:
sudo yum install netbird
# For CLI and GUI:
sudo yum install libappindicator-gtk3 libappindicator netbird-ui

Fedora/Amazon Linux 2023 (DNF)

1. Add the repository:

# For Fedora 40 or earlier / Amazon Linux 2023 (DNF 4):
sudo dnf config-manager --add-repo /etc/yum.repos.d/netbird.repo
# For Fedora 41 or later (DNF 5):
sudo dnf config-manager addrepo --from-repofile=/etc/yum.repos.d/netbird.repo

2. Install the client:

# For the CLI only:
sudo dnf install netbird
# For CLI and GUI:
sudo dnf install libappindicator-gtk3 libappindicator netbird-ui

Note: On recent GNOME versions, you may require the AppIndicator extension:

sudo dnf install gnome-shell-extension-appindicator
sudo gnome-extensions enable [email protected]

Under X11, restart GNOME Shell by pressing Alt+F2, typing r, and hitting Enter. Wayland users must log out and back in.

openSUSE (zypper)

1. Add the repository:

sudo zypper addrepo https://pkgs.netbird.io/yum/ netbird

2. Install the client:

# For MicroOS (immutable with SELinux):
transactional-update pkg in netbird
reboot

# For Tumbleweed or Leap:
zypper in netbird

NixOS (22.11+ / Unstable)

1. Modify your configuration.nix:

{ config, pkgs, ... }:
{
  services.netbird.enable = true;   # Enables the service and CLI
  environment.systemPackages = [ pkgs.netbird-ui ];   # Optional GUI
}

2. Apply the configuration:

sudo nixos-rebuild switch

Binary Installation (CLI Only)

1. Download the specific release:

curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz

Replace VERSION, OS (linux/darwin/windows), and Arch with the values corresponding to your system.

2. Extract and move the binary:

tar xzf ./netbird_<VERSION>.tar.gz
sudo mv netbird /usr/bin/netbird
sudo chown root:root /usr/bin/netbird
sudo chmod +x /usr/bin/netbird

3. Install and start the service:

sudo netbird service install
sudo netbird service start

Updates

If installed via a package manager, use the standard system update commands. For manual script installations, use:

netbird down
curl -fsSLO https://pkgs.netbird.io/install.sh
chmod +x install.sh
./install.sh --update
netbird up

Windows

1. Download the preferred installer:
   • [EXE Installer]
   • [MSI Installer]
2. Execute the installer. The client is installed to C:\Program Files\NetBird and registers a background daemon service.
3. To remove, use the standard "Add or Remove Programs" menu.

macOS

One-Line Installation

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Manual Package Installation

1. Download the installer for your architecture:
   • Intel: [NetBird for Intel]
   • Apple Silicon (M1/M2/M3): [NetBird for Apple Silicon]
2. Run the .pkg file. The application is placed in /Applications and the daemon service is configured automatically.
3. To uninstall, move the NetBird app to the Trash.

Homebrew

1. If you have an existing NetBird installation via Homebrew, clean it up first:

sudo netbird service stop
sudo netbird service uninstall
brew unlink netbird

2. Install the new version:

# For the CLI only:
brew install netbirdio/tap/netbird
# For CLI and GUI:
brew install --cask netbirdio/tap/netbird-ui

For CLI-only installations, initialize the service:

sudo netbird service install
sudo netbird service start

Docker

Run Command

Define your NB_SETUP_KEY and execute:

docker run --rm --name netbird-client --hostname netbird-peer --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY=<SETUP_KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest

Docker Compose

services:
  netbird:
      container_name: netbird
      hostname: <HOSTNAME>
      cap_add:
          - NET_ADMIN
          - SYS_ADMIN
          - SYS_RESOURCE
      network_mode: host
      environment:
          - NB_SETUP_KEY=<SETUP_KEY>
      volumes:
          - netbird-client:/etc/netbird
      image: netbirdio/netbird:latest
volumes:
  netbird-client:
      name: netbird-client

Quick Start Guide

Step 1: Connect Your Devices

In this example, we will connect a MacBook and an AWS EC2 Linux instance.

1. Install and connect your workstation:

   • Download the macOS installer.
   • Select "Connect" from the menu bar icon or run netbird up in your terminal.
   • Authenticate via the browser using your preferred identity provider (Google, GitHub, etc.).
   • The device will register, and the icon will indicate an active connection.

2. Connect the EC2 Node:

   • Log in to the NetBird Management Dashboard.
   • Navigate to Setup Keys and create a new key.
   • In the EC2 terminal, run:

curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key <YOUR_SETUP_KEY>

Step 2: Verify Connectivity

In the Peers section of the dashboard, both devices should now be listed as online. Verify the peer-to-peer connection via ping:

• From your MacBook: ping ec2-node.netbird.cloud
• From the EC2 instance: ping macbook.netbird.cloud

Technical Overview

• The Agent: Every device runs a NetBird agent that manages the local WireGuard interface.
• Management Service: A centralized service maintains the network state, assigns private IP addresses, and synchronizes updates across all nodes.
• Discovery (ICE): The agent uses WebRTC ICE (via the pion/ice library) to discover potential connection paths for peer-to-peer links.
• STUN & TURN: Nodes discover their public mapping via STUN servers. If direct NAT traversal is impossible (e.g., behind carrier-grade NAT), the system falls back to a TURN relay, routing the WireGuard tunnel through the relay server.
• Coturn: NetBird typically utilizes Coturn to provide both STUN and TURN functionality.