Linux Client

The NetBird client for Linux provides secure mesh networking capabilities through WireGuard. Multiple installation methods are available to suit different Linux distributions and preferences.

Installation

Install Script
Debian/Ubuntu (APT)
RHEL/Fedora/CentOS (DNF/YUM)
Binary Installation
NixOS

The easiest way to install NetBird on Linux is using the official installation script:

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

This script automatically:

Detects your Linux distribution
Installs from the appropriate package manager (apt, dnf, yum, or rpm-ostree)
Sets up the NetBird service
Starts the daemon automatically

The install script requires curl and sudo (or doas) to be installed on your system.

For Debian-based distributions, you can manually add the NetBird repository:

Add the NetBird 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 -o /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

Install NetBird

sudo apt-get update
sudo apt-get install netbird -y

For desktop environments, also install the UI:

sudo apt-get install netbird-ui -y

For Red Hat-based distributions:

Add the NetBird 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

Install NetBird

For Fedora (using DNF):

sudo dnf -y install netbird
sudo dnf -y install netbird-ui  # Optional: for desktop environments

For CentOS/RHEL (using YUM):

sudo yum -y install netbird
sudo yum -y install netbird-ui  # Optional: for desktop environments

Install NetBird using pre-compiled binaries:

export USE_BIN_INSTALL=true
curl -fsSL https://pkgs.netbird.io/install.sh | sh

This installs NetBird to /usr/bin without using a package manager.

For NixOS users, add NetBird to your configuration.nix:

services.netbird.enable = true;

For the UI (optional):

environment.systemPackages = [ pkgs.netbird-ui ];

Then rebuild your system:

sudo nixos-rebuild switch

Initial Setup

After installation, connect to your NetBird network:

Start the NetBird service

The service should start automatically after installation. If not:

netbird service install
netbird service start

Connect to NetBird

Using SSO (Interactive Login):

netbird up

Using a Setup Key:

netbird up --setup-key <YOUR_SETUP_KEY>

For self-hosted installations:

netbird up --management-url https://your-management-url.com --setup-key <YOUR_SETUP_KEY>

Verify connection

Check your NetBird status:

netbird status

You should see:

Daemon status: Connected
Management: Connected
Signal: Connected
NetBird IP: 100.x.x.x/16

Service Management

NetBird runs as a systemd service on Linux. Manage it using the netbird service command:

# Check service status
netbird service status

# Start the service
netbird service start

# Stop the service
netbird service stop

# Restart the service
netbird service restart

# Uninstall the service
netbird service uninstall

Or use systemd directly:

# Check status
sudo systemctl status netbird

# Enable auto-start on boot
sudo systemctl enable netbird

# View logs
sudo journalctl -u netbird -f

Configuration

Config File Location

The NetBird configuration file is located at:

Standard: /etc/netbird/config.json
FreeBSD: /var/db/netbird/config.json

Log Files

Logs are written to /var/log/netbird/client.log by default. View logs in real-time:

tail -f /var/log/netbird/client.log

Environment Variables

NetBird supports configuration through environment variables with the NB_ prefix. Common examples:

Variable	Description	Example
`NB_MANAGEMENT_URL`	Management server URL	`https://api.netbird.io`
`NB_LOG_LEVEL`	Logging level	`info`, `debug`, `error`
`NB_LOG_FILE`	Log file path	`/var/log/netbird/client.log`
`NB_INTERFACE_NAME`	WireGuard interface name	`wt0`
`NB_WIREGUARD_PORT`	WireGuard listening port	`51820`
`NB_CONFIG`	Config file path	`/etc/netbird/config.json`

Set service environment variables:

netbird service install --service-env="NB_LOG_LEVEL=debug,NB_WIREGUARD_PORT=51820"

Command-Line Options

Key CLI flags for netbird up:

# Set custom WireGuard interface name
netbird up --interface-name wt0

# Set custom WireGuard port
netbird up --wireguard-port 51820

# Set custom MTU
netbird up --mtu 1280

# Set custom hostname
netbird up --hostname my-linux-server

# Disable auto-connect on service start
netbird up --disable-auto-connect

# Enable Rosenpass (post-quantum security)
netbird up --enable-rosenpass

# Set custom DNS resolver address
netbird up --dns-resolver-address 127.0.0.1:5053

# Add extra DNS labels
netbird up --extra-dns-labels vpc1,prod

Advanced Configuration

Running in Foreground Mode

For debugging or testing without the daemon:

netbird up --foreground-mode

Custom External IP Mapping

For machines behind NAT or with multiple interfaces:

# Map external IP to local IP
netbird up --external-ip-map 203.0.113.5/192.168.1.10

# Map external IP to interface
netbird up --external-ip-map 203.0.113.5/eth0

# Multiple mappings
netbird up --external-ip-map 203.0.113.5,203.0.113.6/192.168.1.10

Network Monitor

Control network change detection:

# Enable network monitoring (default on some distros)
netbird up --network-monitor=true

# Disable network monitoring
netbird up --network-monitor=false

Headless Servers

For servers without a desktop environment, use setup keys for authentication:

netbird up --setup-key <YOUR_SETUP_KEY>

The NetBird UI is automatically skipped during installation on systems without XDG_CURRENT_DESKTOP or DESKTOP_SESSION environment variables.

Troubleshooting

Check Connection Status

# Basic status
netbird status

# Detailed status with peer information
netbird status --detail

# JSON output for parsing
netbird status --json

View Only Your NetBird IP

netbird status --ipv4

Common Issues

Service won't start

Check if the service is properly installed:

netbird service status

Reinstall the service:

netbird service uninstall
netbird service install
netbird service start

Connection timeout

Ensure UDP port 3478 is open for STUN/TURN connectivity:

sudo ufw allow 3478/udp

Check if the WireGuard module is loaded:

lsmod | grep wireguard

TUN device errors

Ensure the TUN module is loaded:

sudo modprobe tun

# Verify TUN device exists
ls -l /dev/net/tun

Debug logs

Enable debug logging:

netbird service stop
netbird service install --service-env="NB_LOG_LEVEL=debug"
netbird service start

# View logs
tail -f /var/log/netbird/client.log

Updating NetBird

APT (Debian/Ubuntu)
DNF (Fedora)
YUM (CentOS/RHEL)
Binary Installation

sudo apt-get update
sudo apt-get upgrade netbird netbird-ui

sudo dnf upgrade netbird netbird-ui

sudo yum update netbird netbird-ui

export UPDATE_NETBIRD=true
curl -fsSL https://pkgs.netbird.io/install.sh | sh

Uninstalling

Stop and uninstall the service

netbird service stop
netbird service uninstall

Remove packages

APT
DNF/YUM

sudo apt-get remove --purge netbird netbird-ui
sudo rm -rf /etc/netbird /var/log/netbird

sudo dnf remove netbird netbird-ui
# or
sudo yum remove netbird netbird-ui

sudo rm -rf /etc/netbird /var/log/netbird

Get Started

Architecture

Deployment

Client Setup

Network Management

Security

Operations

Installation

Initial Setup

Service Management

Configuration

Config File Location

Log Files

Environment Variables

Command-Line Options

Advanced Configuration

Running in Foreground Mode

Custom External IP Mapping

Network Monitor

Headless Servers

Troubleshooting

Check Connection Status

View Only Your NetBird IP

Common Issues

Updating NetBird

Uninstalling

​Installation

​Initial Setup

​Service Management

​Configuration

​Config File Location

​Log Files

​Environment Variables

​Command-Line Options

​Advanced Configuration

​Running in Foreground Mode

​Custom External IP Mapping

​Network Monitor

​Headless Servers

​Troubleshooting

​Check Connection Status

​View Only Your NetBird IP

​Common Issues

​Updating NetBird

​Uninstalling

Installation

Initial Setup

Service Management

Configuration

Config File Location

Log Files

Environment Variables

Command-Line Options

Advanced Configuration

Running in Foreground Mode

Custom External IP Mapping

Network Monitor

Headless Servers

Troubleshooting

Check Connection Status

View Only Your NetBird IP

Common Issues

Updating NetBird

Uninstalling