Skip to main content

​
Overview

The netbird up command connects your device to the NetBird network. It brings up the WireGuard interface, connects to the management server, and establishes peer-to-peer connections with other peers in your network.

​
Description

This command performs the following actions:
  1. Authenticates with the management server (via SSO or setup key)
  2. Creates or updates the WireGuard interface
  3. Retrieves network configuration from the management server
  4. Establishes P2P connections with authorized peers
  5. Configures DNS, routes, and firewall rules as needed

​
Flags

​
Connection Options

​
boolean
default:"false"
Start service in foreground mode instead of connecting to the daemonShort form: -FNote: In foreground mode, the process runs directly without using the system service.
​
string
Profile name to use for the connection. If not specified, the last used profile will be used.
​
boolean
default:"false"
Do not open the browser for SSO login. Useful for headless servers or automated scripts.

​
Network Configuration

​
string
default:"wt0"
WireGuard interface nameNote: On macOS, the interface name must use the utun prefix (e.g., utun1, utun199).
​
integer
default:"51820"
WireGuard interface listening port
​
integer
default:"1280"
Set MTU (Maximum Transmission Unit) for the WireGuard interface
​
boolean
default:"true (Windows/macOS), false (Linux/FreeBSD)"
Manage network monitoring for detecting network changesShort form: -NExample: --network-monitor=false to disable or --network-monitor=true to enable

​
NAT and DNS

​
string[]
Sets external IPs maps between local addresses and interfaces. Useful when behind NAT.You can specify:
  • Single IP: --external-ip-map 12.34.56.78
  • IP to IP mapping: --external-ip-map 12.34.56.78/10.0.0.1
  • IP to interface: --external-ip-map 12.34.56.80/eth1
  • Multiple mappings: --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1
  • Clear configuration: --external-ip-map ""
​
string
Sets a custom address for NetBird’s local DNS resolverIf set, the agent won’t attempt to discover the best IP and port to listen on.Examples:
  • --dns-resolver-address 127.0.0.1:5053
  • Clear: --dns-resolver-address ""
​
string[]
Sets DNS labels for the peer. You can specify up to 32 labels.Examples:
  • Single label: --extra-dns-labels vpc1
  • Multiple labels: --extra-dns-labels vpc1,mgmt1
  • Clear labels: --extra-dns-labels ""
​
duration
default:"1m"
DNS route update interval

​
Security Options

​
boolean
default:"false"
[Experimental] Enable Rosenpass for post-quantum securityIf enabled, connections will be post-quantum secured via Rosenpass.
​
boolean
default:"false"
[Experimental] Enable Rosenpass in permissive modeAllows this peer to accept WireGuard connections without requiring Rosenpass from peers that don’t have it enabled.

​
Auto-Connect

​
boolean
default:"false"
Disables auto-connect featureIf enabled, the client won’t connect automatically when the service starts.
​
boolean
default:"false"
[Experimental] Enable lazy connection featureIf enabled, the client will establish connections on-demand.Note: This setting may be overridden by management configuration.

​
Advanced Options

​
string[]
Extra list of default interfaces to ignore for listening

​
SSH Server Options

​
boolean
default:"false"
Allow SSH server on this peer, enabling other peers to SSH into this machine
​
boolean
default:"false"
Enable root login for SSH server
​
boolean
default:"false"
Enable SFTP subsystem for SSH server
​
boolean
default:"false"
Enable local port forwarding for SSH server
​
boolean
default:"false"
Enable remote port forwarding for SSH server
​
boolean
default:"false"
Disable SSH authentication
​
integer
default:"0"
SSH JWT token cache TTL in seconds (0=disabled)

​
Examples

​
Basic Connection

Connect to NetBird network with SSO:

​
Connect with Setup Key

Register and connect using a setup key (non-interactive):

​
Connect to Self-Hosted Management Server

​
Connect without Opening Browser

Useful for headless servers:
You’ll receive a URL to open manually for SSO authentication.

​
Set Custom Interface Name

On macOS:

​
Configure External IP Mapping

Useful when behind NAT:

​
Set Custom Hostname

​
Enable SSH Server

Allow other peers to SSH into this machine:
With SFTP and port forwarding:

​
Disable Auto-Connect

​
Use Environment Variables

​
Run in Foreground Mode

Useful for testing or containers:

​
Daemon vs Foreground Mode

​
Daemon Mode (Default)

In daemon mode, netbird up connects to the NetBird system service:
  • The NetBird daemon must be running (netbird service start)
  • Connection persists after the command exits
  • System service manages the connection
  • Recommended for production use

​
Foreground Mode

In foreground mode (-F), NetBird runs as a foreground process:
  • No system service required
  • Connection terminates when the process exits
  • Useful for testing, debugging, or containerized environments
  • Logs output to console by default

​
Authentication Methods

​
SSO (Interactive)

Default method for interactive sessions:
Opens your browser for SSO authentication (Google, Azure AD, Okta, etc.).

​
Setup Key (Non-Interactive)

Ideal for automation, scripts, and headless servers:
Setup keys can be:
  • Reusable or one-time use
  • Time-limited
  • Associated with specific groups
  • Created in the Management Dashboard
See: Register Machines Using Setup Keys

​
Status Messages

  • Connected - Successfully connected to the NetBird network
  • Already connected - The peer is already connected
  • Daemon status: NeedsLogin - Authentication required

​
Common Issues

​
Daemon Not Running

Solution:

​
Port Already in Use

If WireGuard port 51820 is already in use:

​
Interface Name Conflict

If interface name wt0 conflicts:

​
See Also