Build a Secure WireGuard Mesh Network for Linux

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.

If this TUN device fix saved you time, share this guide with your team so the next person can solve it in minutes instead of hours.

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.

If this article helped, share it with someone on your team.