NetBird: Securely Connect Linux Machines with a WireGuard Mesh VPN

Imagine you have a laptop, a build server, and a database server, each on a different network behind NAT. Normally, getting them to communicate means configuring firewalls, opening ports, and managing VPN keys, which can quickly become complicated.

NetBird makes this much easier by connecting each device to a coordination service, automatically exchanging WireGuard keys, and establishing secure peer-to-peer connections whenever possible.

What NetBird Actually Does

WireGuard is a fast, lightweight VPN protocol that securely encrypts network traffic. However, using WireGuard by itself requires you to manually generate keys, create configuration files, and configure every device that needs to connect.

NetBird simplifies this process by building on top of WireGuard and handling all of the setup automatically.

Each device runs a small NetBird agent that connects to a management service, either NetBird Cloud or your own self-hosted NetBird server.

After a device is authenticated, NetBird automatically exchanges WireGuard keys with other authorized devices and establishes a secure peer-to-peer connection whenever possible.

When the connection is created, NetBird brings up a WireGuard network interface named wt0. If a direct peer-to-peer connection can’t be established because of network restrictions, NetBird automatically routes the traffic through a relay server so the connection continues to work without any manual configuration.

The steps in this guide were tested on Ubuntu 26.04 and RHEL 10, but they also work on current Debian, Ubuntu, Fedora, Rocky Linux, and other RHEL-based distributions that use systemd.

Installing NetBird on Ubuntu and Debian

NetBird provides a simple one-line installer that automatically detects your Linux distribution and installs the correct package. This is the quickest way to get the NetBird agent up and running on a single system.

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

If you plan to install NetBird on multiple systems, it’s better to add the official APT repository. This lets you receive future updates through the normal apt update and apt upgrade process.

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
sudo apt-get update
sudo apt-get install netbird -y

Here’s what each command does:

• sudo apt-get update refreshes the local package index so APT knows about the latest available packages.
• sudo apt-get install ca-certificates curl gnupg -y installs the tools needed to securely download and verify packages.
• curl -sSL ... | sudo gpg --dearmor ... downloads NetBird’s public signing key and converts it into the format APT uses.
• echo 'deb ...' | sudo tee ... adds the NetBird repository to your system so APT can install and update NetBird packages.
• sudo apt-get update refreshes the package index again to include the newly added repository.
• sudo apt-get install netbird -y installs the NetBird agent.

The sudo command runs each command with administrator privileges. This is required because installing software and writing files under /etc/apt/ are system-level operations that regular users cannot perform. Without sudo, you’ll get permission errors.

Installing NetBird on RHEL and Rocky Linux

On RHEL, Rocky Linux, Fedora, and other RHEL-based distributions, NetBird is installed from its official DNF/YUM repository.

First, create the repository configuration file:

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

Next, install the NetBird package:

sudo dnf install netbird -y

Here’s what these commands do:

• sudo tee /etc/yum.repos.d/netbird.repo <<EOF creates a new repository configuration file using a heredoc, allowing you to write multiple lines to a file directly from the terminal.
• The entries between EOF and the closing EOF define the NetBird software repository, including its location and the GPG key used to verify downloaded packages.
• sudo dnf install netbird -y downloads and installs the NetBird agent from the newly added repository.

Using tee with a heredoc is a convenient way to create configuration files from the command line, especially when automating server deployments or writing installation scripts.

If you’re using RHEL 7, replace dnf with yum. The installation command remains the same:

sudo yum install netbird -y

Connecting Your First Peer

After installing the NetBird agent, the next step is to connect your machine to your NetBird network.

Run the following command:

sudo netbird up

This command starts the NetBird agent and begins the device enrollment process.

When you run it for the first time, NetBird displays a URL in the terminal. Open the link in your web browser, sign in to your NetBird account (or your self-hosted NetBird dashboard), and approve the device.

Within a few seconds, the agent completes the setup and assigns your machine an IP address from the 100.64.0.0/10 range. This is NetBird’s private network, which is separate from your local network.

Once the connection is established, you’ll see output similar to this:

NetBird status: Connected
Management: Connected
Signal: Connected
Relays: 2/2 Available
Peers count: 3/3 Connected

Here’s what each line means:

• NetBird status: Shows whether the local NetBird agent is connected.
• Management: Indicates the connection to the management service.
• Signal: Shows whether the signaling service used to establish peer connections is reachable.
• Relays: Displays the number of relay servers that are currently available if a direct peer-to-peer connection cannot be established.
• Peers count: Shows how many authorized peer devices are currently connected.

The Peers count line is the most important one to check. For example, 3/3 Connected means this machine has established secure connections with all three peers it is allowed to communicate with.

If you see 0/3, the device has successfully authenticated, but it hasn’t connected to any of its peers yet.

Using a Setup Key for Unattended Servers

If you’re installing NetBird on a server without a web browser, you can use a setup key instead of approving the device manually. Generate a setup key from your NetBird dashboard, then run:

sudo netbird up --setup-key 

Replace with the actual setup key generated from your NetBird dashboard. Do not include the angle brackets (< >) when entering the command.

Checking Status and Verifying the Tunnel

You can quickly check whether NetBird is running by using the status command. For more detailed information about each connected device, use the --detail option.

netbird status --detail

This command displays information about every peer in your NetBird network.

Look at the Status field for each peer:

• Connected (P2P) means the device has established a direct peer-to-peer WireGuard connection, which provides the best performance.
• Connected (Relayed) means a direct connection wasn’t possible, so traffic is passing through a relay server. The connection remains fully encrypted, but you may notice slightly higher latency.

You can also verify that the WireGuard network interface has been created by checking for the wt0 interface:

ip link show wt0

If the interface exists, you’ll see information about the wt0 network device, confirming that the WireGuard tunnel is active.

If wt0 is missing, the WireGuard kernel module may not be loaded. This can happen on minimal Linux installations or older systems where the module isn’t loaded automatically.

Load the module manually with:

sudo modprobe wireguard

After loading the module, run netbird status or ip link show wt0 again to verify that the interface has been created successfully.

Common Error: TUN Device Missing

If netbird up reports an error about a missing TUN device, first check whether the device exists on your system:

ls -l /dev/net/tun

If the command lists the device, the TUN interface is present. If you get a No such file or directory error, the TUN device is missing.

This is most common on minimal Linux installations, containers, or some cloud VM images where the TUN device isn’t created automatically.

You can create it manually with the following commands:

sudo mkdir -p /dev/net
sudo mknod /dev/net/tun c 10 200
sudo chmod 0755 /dev/net/tun

Here’s what each command does:

• sudo mkdir -p /dev/net creates the /dev/net directory if it doesn’t already exist.
• sudo mknod /dev/net/tun c 10 200 creates the TUN character device with the required major and minor device numbers.
• sudo chmod 0755 /dev/net/tun sets the appropriate permissions on the device.

After creating the TUN device, run the following command again to connect the machine:

sudo netbird up

If the TUN device was the problem, NetBird should now be able to create the wt0 interface and establish the VPN connection.

Opening the Right Firewall Ports

NetBird uses UDP port 3478 for STUN (Session Traversal Utilities for NAT), which helps devices discover their public IP addresses and establish direct peer-to-peer connections across NAT.

If this port is blocked by your firewall, NetBird can still connect using relay servers, but direct peer-to-peer connections may not work, which can increase network latency.

On Ubuntu and Debian

If you’re using UFW (Uncomplicated Firewall), allow UDP port 3478 with:

sudo ufw allow 3478/udp

On RHEL and Rocky Linux

If you’re using firewalld, run:

sudo firewall-cmd --add-port=3478/udp --permanent
sudo firewall-cmd --reload

Here’s what these commands do:

• --add-port=3478/udp --permanent permanently allows incoming UDP traffic on port 3478.
• --reload applies the new firewall rule without restarting the system.

After updating the firewall rules, run netbird status --detail again. If your network allows direct connections, peers that were previously shown as Connected (Relayed) may now appear as Connected (P2P).

Viewing NetBird Logs

If a peer still isn’t connecting after opening the required firewall port, check the NetBird service logs to see what’s happening.

Run:

sudo journalctl -u netbird -f

This command displays the NetBird service logs in real time, making it easier to spot connection or authentication issues as they occur.

Here’s what the options mean:

• -u netbird shows log messages only for the NetBird service.
• -f continuously follows the log, displaying new entries as they are written.

Keep this command running while you retry netbird up or reconnect a peer. As the agent attempts to establish the connection, you’ll see status messages, errors, and other useful information that can help identify the cause of the problem.

Disconnecting and Removing NetBird

If you want to temporarily disconnect your machine from the NetBird network without uninstalling the software, use:

sudo netbird down

This command stops the WireGuard tunnel but keeps the NetBird agent and its configuration on your system, so you can reconnect later by running netbird up again.

If you no longer need NetBird, stop the service and uninstall it.

First, stop and uninstall the NetBird service:

sudo netbird service stop
sudo netbird service uninstall

Then remove the NetBird package using your distribution’s package manager.

On Ubuntu and Debian:

sudo apt-get remove netbird -y

On RHEL and Rocky Linux:

sudo dnf remove netbird -y

These commands remove the NetBird package from your system. If you also want to remove any remaining configuration files, you can delete them manually after uninstalling, if needed.

Conclusion

In this guide, you learned how to install NetBird on Ubuntu, Debian, RHEL, and Rocky Linux, connect your first device to a NetBird network, and verify that the VPN tunnel is working correctly.

You also learned how to check peer connection status, troubleshoot common issues such as a missing TUN device or blocked firewall port, view service logs, and safely disconnect or uninstall NetBird when it’s no longer needed.

With just a few commands, NetBird makes it easy to build a secure WireGuard-based mesh network between your devices without manually managing VPN keys or configuration files.

If you have multiple systems on different networks, try connecting them with NetBird and verify that they appear as connected peers. It’s a simple way to confirm that your mesh network is working as expected.

If you have any questions or run into issues while setting up NetBird, let us know in the comments. We’d be happy to help.