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

Build docs developers (and LLMs) love

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

Build docs developers (and LLMs) love

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