netbird service

Overview

The netbird service command manages the NetBird daemon service on your system. The daemon runs in the background and maintains your NetBird connections.

netbird service <subcommand> [flags]

Description

The NetBird daemon service:

Runs in the background as a system service
Maintains persistent connections to the NetBird network
Automatically reconnects after network changes or system restarts
Manages WireGuard interface and routing
Handles peer connections and authentication

The service integrates with your system’s service manager:

Linux: systemd, SysV init, or Upstart
macOS: launchd
Windows: Windows Service Manager
FreeBSD: rc.d

Subcommands

install - Install NetBird as a system service
uninstall - Uninstall NetBird service from the system
start - Start the NetBird service
stop - Stop the NetBird service
restart - Restart the NetBird service
status - Show NetBird service status
run - Run NetBird as a service (used by service manager)
reconfigure - Reconfigure NetBird service with new settings

Service Flags

--disable-profiles

boolean

default:"false"

Disables profiles featureIf enabled, the client will not be able to change or edit any profile.To persist this setting:

netbird service install --disable-profiles

--disable-update-settings

boolean

default:"false"

Disables update settings featureIf enabled, the client will not be able to change or edit any settings.To persist this setting:

netbird service install --disable-update-settings

install

Install NetBird as a system service.

netbird service install [flags]

Flags

--service-env

string[]

Sets extra environment variables for the serviceYou can specify comma-separated list of KEY=VALUE pairs.Examples:

--service-env NB_LOG_LEVEL=debug
--service-env NB_LOG_LEVEL=debug,CUSTOM_VAR=value

Examples

Basic installation:

sudo netbird service install

Install with custom log level:

sudo netbird service install --service-env NB_LOG_LEVEL=debug

Install with multiple environment variables:

sudo netbird service install --service-env NB_LOG_LEVEL=debug,NB_MANAGEMENT_URL=https://api.example.com

Install with profiles disabled:

sudo netbird service install --disable-profiles

Install with custom configuration:

sudo netbird service install --service-env NB_CONFIG=/opt/netbird/config.json

What It Does

Creates service configuration:
- Linux (systemd): /etc/systemd/system/netbird.service
- macOS (launchd): /Library/LaunchDaemons/io.netbird.client.plist
- Windows: Registers Windows Service
- FreeBSD (rc.d): /usr/local/etc/rc.d/netbird
Sets service to start on boot
Configures service user and permissions
Sets environment variables

After installation, you need to start the service:

sudo netbird service start

uninstall

Uninstall NetBird service from the system.

netbird service uninstall

Examples

Uninstall service:

sudo netbird service uninstall

What It Does

Stops the service if running
Removes service configuration files
Disables automatic startup
Does NOT remove:
- Configuration files (/etc/netbird/config.json)
- Log files
- NetBird binary

Uninstalling the service will disconnect you from the NetBird network. Your configuration files will be preserved.

start

Start the NetBird service.

netbird service start

Examples

Start service:

sudo netbird service start

Behavior

Starts the NetBird daemon
If auto-connect is enabled (default), automatically runs netbird up
Service continues running in background
Survives terminal/SSH session closure

stop

Stop the NetBird service.

netbird service stop

Examples

Stop service:

sudo netbird service stop

Behavior

Disconnects from NetBird network
Stops the daemon process
Does not uninstall the service
Service will not auto-start on reboot if stopped manually (on some systems)

restart

Restart the NetBird service.

netbird service restart

Examples

Restart service:

sudo netbird service restart

Useful after configuration changes:

# Edit config
sudo vi /etc/netbird/config.json
# Restart to apply
sudo netbird service restart

Behavior

Stops the service gracefully
Disconnects all peers
Starts the service again
Re-establishes connections

status

Show NetBird service status.

netbird service status

Examples

Check service status:

sudo netbird service status

Example output (systemd):

● netbird.service - Netbird
   Loaded: loaded (/etc/systemd/system/netbird.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2024-01-15 10:30:00 UTC; 2h 15min ago
 Main PID: 1234 (netbird)
    Tasks: 12 (limit: 4915)
   Memory: 45.2M
   CGroup: /system.slice/netbird.service
           └─1234 /usr/bin/netbird service run

Status Information

Loaded: Service configuration loaded
Active: Current running state
Enabled: Will start on boot
PID: Process ID
Uptime: How long service has been running
Memory: Memory usage

run

Run NetBird as a service. This command is used by the service manager and should not be called directly.

netbird service run

Do not run this command directly. Use netbird service start instead.

reconfigure

Reconfigure NetBird service with new settings without manual uninstall/install.

netbird service reconfigure [flags]

Flags

Same flags as install command:

--service-env
--disable-profiles
--disable-update-settings

Examples

Update environment variables:

sudo netbird service reconfigure --service-env NB_LOG_LEVEL=debug,NB_MANAGEMENT_URL=https://new-api.example.com

Enable profiles:

sudo netbird service reconfigure

Behavior

Stops the service if running
Updates service configuration
Restarts the service if it was running

Complete Setup Example

Initial Installation

# 1. Install NetBird (if not already installed)
curl -sSL https://pkgs.netbird.io/install.sh | bash

# 2. Install service
sudo netbird service install

# 3. Start service
sudo netbird service start

# 4. Check status
sudo netbird service status

# 5. Connect to network
netbird up

With Custom Configuration

# Install with custom settings
sudo netbird service install \
  --service-env NB_LOG_LEVEL=debug,NB_MANAGEMENT_URL=https://api.example.com

# Start service
sudo netbird service start

# Connect with setup key
netbird up --setup-key YOUR_SETUP_KEY

Service Environment Variables

Common environment variables to set via --service-env:

NetBird Configuration

NB_CONFIG - Configuration file path
NB_LOG_LEVEL - Log level (trace, debug, info, warn, error)
NB_LOG_FILE - Log file path
NB_MANAGEMENT_URL - Management server URL
NB_ADMIN_URL - Admin panel URL
NB_NO_BROWSER - Disable browser for SSO (true/false)

Example

sudo netbird service install --service-env \
  NB_CONFIG=/opt/netbird/config.json,\
  NB_LOG_LEVEL=debug,\
  NB_LOG_FILE=/var/log/netbird/debug.log,\
  NB_MANAGEMENT_URL=https://management.example.com

Platform-Specific Details

Linux (systemd)

Service file location:

/etc/systemd/system/netbird.service

Manual service management:

sudo systemctl status netbird
sudo systemctl start netbird
sudo systemctl stop netbird
sudo systemctl restart netbird
sudo systemctl enable netbird
sudo systemctl disable netbird

View logs:

sudo journalctl -u netbird -f

macOS (launchd)

Service file location:

/Library/LaunchDaemons/io.netbird.client.plist

Manual service management:

sudo launchctl load /Library/LaunchDaemons/io.netbird.client.plist
sudo launchctl unload /Library/LaunchDaemons/io.netbird.client.plist

View logs:

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

Windows

Service name: Netbird Manual service management (PowerShell):

Get-Service Netbird
Start-Service Netbird
Stop-Service Netbird
Restart-Service Netbird

View logs:

Get-Content $env:PROGRAMDATA\Netbird\client.log -Wait

Troubleshooting

Service Won’t Start

Check service status:

sudo netbird service status

View logs:

# Linux (systemd)
sudo journalctl -u netbird -n 50

# macOS
tail -50 /var/log/netbird/client.log

# Windows
type %PROGRAMDATA%\Netbird\client.log

Check permissions:

# Ensure NetBird binary is executable
ls -l $(which netbird)

# Check config directory
ls -la /etc/netbird/

Service Starts But Can’t Connect

Check if service is running:

netbird status

Restart service:

sudo netbird service restart
netbird up

Permission Denied

Service commands typically require root/administrator privileges:

# Linux/macOS
sudo netbird service <command>

# Windows (run as Administrator)
netbird service <command>

Auto-Start on Boot

The service is configured to start automatically on boot after installation.

Disable Auto-Start

Linux (systemd):

sudo systemctl disable netbird

macOS (launchd):

sudo launchctl unload -w /Library/LaunchDaemons/io.netbird.client.plist

Windows:

Set-Service -Name Netbird -StartupType Manual

Re-enable Auto-Start

Linux (systemd):

sudo systemctl enable netbird

macOS (launchd):

sudo launchctl load -w /Library/LaunchDaemons/io.netbird.client.plist

Windows:

Set-Service -Name Netbird -StartupType Automatic

Commands

​Overview

​Description

​Subcommands

​Service Flags

​install

​Flags

​Examples

​What It Does

​uninstall

​Examples

​What It Does

​start

​Examples

​Behavior

​stop

​Examples

​Behavior

​restart

​Examples

​Behavior

​status

​Examples

​Status Information

​run

​reconfigure

​Flags

​Examples

​Behavior

​Complete Setup Example

​Initial Installation

​With Custom Configuration

​Service Environment Variables

​NetBird Configuration

​Example

​Platform-Specific Details

​Linux (systemd)

​macOS (launchd)

​Windows

​Troubleshooting

​Service Won’t Start

​Service Starts But Can’t Connect

​Permission Denied

​Auto-Start on Boot

​Disable Auto-Start

​Re-enable Auto-Start

​See Also

Build docs developers (and LLMs) love

Overview

Description

Subcommands

Service Flags

install

Flags

Examples

What It Does

uninstall

Examples

What It Does

start

Examples

Behavior

stop

Examples

Behavior

restart

Examples

Behavior

status

Examples

Status Information

run

reconfigure

Flags

Examples

Behavior

Complete Setup Example

Initial Installation

With Custom Configuration

Service Environment Variables

NetBird Configuration

Example

Platform-Specific Details

Linux (systemd)

macOS (launchd)

Windows

Troubleshooting

Service Won’t Start

Service Starts But Can’t Connect

Permission Denied

Auto-Start on Boot

Disable Auto-Start

Re-enable Auto-Start

See Also