Advanced NetBird Client Commands – FAQ

This FAQ focuses on advanced and less commonly used NetBird client commands and flags, excluding everyday commands such as up, down, login, and basic usage.

General Status & Diagnostics

How can I see only currently connected peers?

netbird status -d --filter-by-status connected

This shows only peers with an active connection and hides disconnected ones.

How can I filter peer status by specific IPs?

netbird status -d --filter-by-ips 100.64.0.10,100.64.0.20

Useful when checking connectivity to specific peers in large networks.

How can I filter by peer hostname or FQDN?

netbird status -d --filter-by-names peer-a,peer-b.netbird.cloud

Helpful in environments with descriptive naming conventions.

Can I get status output in JSON for automation?

netbird status -d --json

Ideal for:

Monitoring systems

Scripts

Parsing with jq

CI/CD health checks

YAML output is also available:

netbird status -d --yaml

How do I show only this machine’s NetBird IP?

netbird status --ipv4

Useful for scripting or service discovery.

How can I anonymise status output for sharing?

netbird status -d --anonymize

Removes IP addresses and non-netbird domains before sharing logs publicly.

Debugging & Log Management

How do I generate a debug bundle?

netbird debug bundle --system-info

Includes:

Logs

Status snapshot

Network interfaces

Routing information

How do I anonymise sensitive information in a debug bundle?

netbird debug bundle --system-info --anonymize

Can I capture logs for a specific time period?

netbird debug for 5m --system-info

Collects logs for 5 minutes, then generates a bundle automatically.

How do I temporarily increase log verbosity?

netbird debug log level debug

Or for deeper troubleshooting:

netbird debug log level trace

This change is temporary until the daemon restarts.

How do I permanently change the log level?

Set an environment variable:

export NB_LOG_LEVEL=debug

Or configure it via your service manager depending on your platform.

How can I run the agent in foreground mode for live debugging?

Linux/macOS:

sudo netbird service stop
sudo netbird up -F

This prints logs directly to the terminal.

How do I debug GRPC communication issues?

sudo bash -c 'GRPC_GO_LOG_VERBOSITY_LEVEL=99 GRPC_GO_LOG_SEVERITY_LEVEL=info netbird up -F'

Useful for diagnosing control plane connectivity issues.

How do I debug ICE (P2P) connectivity?

sudo bash -c 'PIONS_LOG_DEBUG=all NB_LOG_LEVEL=debug netbird up -F'

Helpful when diagnosing NAT traversal problems.

Advanced Connection Behaviour

How can I block all inbound connections on a peer?

netbird up --block-inbound

Overrides any inbound policies received from the management server.

Useful for:

High security servers

Zero-trust endpoint hardening

One-way connectivity scenarios

How do I disable automatic reconnection?

netbird up --disable-auto-connect

The peer will not automatically reconnect when the service starts.

How do I specify a custom WireGuard port?

netbird up --wireguard-port 51830

Can help in restricted firewall environments.

How do I map external IP addresses manually?

netbird up --external-ip-map 203.0.113.5/eth0

Or multiple:

netbird up --external-ip-map 203.0.113.5/10.0.0.5,198.51.100.10/eth1

Useful when:

Running in complex NAT environments

Using multiple interfaces

Deploying in hybrid cloud setups

How do I set a custom DNS resolver for NetBird?

netbird up --dns-resolver-address 127.0.0.1:5053

Helpful when integrating with:

Local DNS filters

Split DNS environments

Advanced service meshes

How do I enable post-quantum security (Rosenpass)?

netbird up --enable-rosenpass

Or permissive mode:

netbird up --enable-rosenpass --rosenpass-permissive

Experimental feature for quantum-resistant key exchange.

SSH Advanced Controls

How do I enable the built-in SSH server?

netbird up --allow-server-ssh

How do I disable SSH JWT authentication?

netbird up --disable-ssh-auth

Not recommended unless you fully trust the network.

How do I enable SSH port forwarding?

Local forwarding:

netbird up --allow-server-ssh --enable-ssh-local-port-forwarding

Remote forwarding:

netbird up --allow-server-ssh --enable-ssh-remote-port-forwarding

How do I enable SFTP over NetBird SSH?

netbird up --allow-server-ssh --enable-ssh-sftp

Service Management

How do I change the daemon socket address?

export NB_DAEMON_ADDR="tcp://localhost:8080"

Advanced use case for:

Containerised deployments

Custom orchestration

Remote CLI control

How do I disable profiles feature?

export NB_DISABLE_PROFILES=true

How do I disable update settings functionality?

export NB_DISABLE_UPDATE_SETTINGS=true

Useful in tightly controlled production environments.

Privacy & Operational Controls

How do I disable anonymous metrics (self-hosted management)?

Set the management service flag:

--disable-anonymous-metrics=true

How can I share a debug bundle without admin privileges?

netbird debug bundle --system-info --upload-bundle

Uploads the bundle and returns a shareable upload key.

Automation Tips

How can I monitor connection health in scripts?

Example:

netbird status --json | jq '.peers[] | select(.status=="Connected")'

Use cases:

Monitoring alerts

Prometheus exporters

Auto-remediation scripts