sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 07:26:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document missing CLI flags and client environment variables (#687)

Browse Source
This commit is contained in:
Viktor Liu
2026-04-08 22:19:49 +08:00
committed by GitHub
parent 6755dbdb00
commit 5a575acdee
4 changed files with 444 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
src/components/NavigationDocs.jsx
View File

@@ -660,6 +660,7 @@ export const docsNavigation = [
title: 'CLIENT',
links: [
{ title: 'Profiles', href: '/client/profiles' },
{ title: 'Environment Variables', href: '/client/environment-variables' },
{
title: 'Settings',
isOpen: false,

127
src/pages/client/environment-variables.mdx Normal file
View File

@@ -0,0 +1,127 @@
# Client Environment Variables
The NetBird client supports environment variables for advanced configuration. These are separate from the CLI flag environment variables (like `NB_LOG_LEVEL`) which are described in the [CLI reference](/get-started/cli#environment-variables).
## Setting environment variables
Environment variables must be set on the **daemon process**, not the CLI. When running NetBird as a system service, use `--service-env` to persist them:
```shell
# Set during install
sudo netbird service install --service-env NB_WG_KERNEL_DISABLED=true
# Or reconfigure a running service
sudo netbird service reconfigure --service-env NB_WG_KERNEL_DISABLED=true
# Multiple variables
sudo netbird service install --service-env NB_LOG_LEVEL=debug,NB_USE_LEGACY_ROUTING=true
```
When running in foreground mode, set them in the shell before starting:
```shell
NB_WG_KERNEL_DISABLED=true netbird up --foreground-mode
```
<Note>
To clear all saved service parameters (including env vars), run `sudo netbird service reset-params` followed by `sudo netbird service reconfigure`.
</Note>
## Networking and routing
| Variable | Platform | Description |
|---|---|---|
| `NB_USE_LEGACY_ROUTING` | Linux | Bypass the fwmark/ip-rule based routing and fall back to the simpler pre-0.26 routing method. Useful when exit nodes cause connectivity issues due to rp_filter or missing sysctl settings. |
| `NB_SKIP_SOCKET_MARK` | Linux | Backward-compatibility alias for `NB_USE_LEGACY_ROUTING`. |
| `NB_DISABLE_CUSTOM_ROUTING` | All | Revert to the routing behavior from before exit node support was added. No exclusion routes or fwmark-based socket routing will be used; all dialers and listeners fall back to plain `net.Dial`/`net.Listen`. Routes with a prefix of /7 or larger (e.g. default routes, 0.0.0.0/0) will be rejected. |
| `NB_ROUTE_PROTO_FLAG` | macOS, BSD | Set a custom route flag on routes the client adds to the routing table. Accepted values: `2` (RTF_PROTO2) or `3` (RTF_PROTO3); defaults to RTF_PROTO1. Not used on Linux (Linux uses netlink with its own protocol field). |
| `NB_DISABLE_ROUTE_CACHE` | Windows | Disable the 2-second cache on Windows routing table lookups. The client reads the OS routing table (via Win32 API) when adding or removing routes; without the cache, each operation triggers a fresh read. Only needed for debugging route conflicts. |
## WireGuard and interface
| Variable | Platform | Description |
|---|---|---|
| `NB_WG_KERNEL_DISABLED` | Linux | Skip loading the WireGuard kernel module and run entirely in userspace (wireguard-go). Use this when the kernel module is broken, missing, or conflicts with other software. |
| `NB_WG_DEBUG` | All | Set to `true` to print low-level WireGuard protocol messages (handshakes, keypairs, timers) to the log. Very verbose. |
| `NB_DISABLE_EBPF_WG_PROXY` | Linux | Disable the eBPF-based proxy that intercepts WireGuard UDP traffic and fall back to the classic UDP port proxy. |
| `NB_USE_NETSTACK_MODE` | All | Run WireGuard on top of a userspace TCP/IP stack (gVisor netstack) instead of a TUN device. Required for environments without TUN support (e.g. unprivileged containers). |
| `NB_NETSTACK_SKIP_PROXY` | All | When using netstack mode, do not start the built-in SOCKS5 proxy that exposes the WireGuard network to local applications. |
| `NB_SOCKS5_LISTENER_PORT` | All | Override the port the netstack SOCKS5 proxy listens on (default: `1080`). Only relevant when netstack mode is active. |
## Firewall
| Variable | Platform | Description |
|---|---|---|
| `NB_SKIP_NFTABLES_CHECK` | Linux | Do not probe for nftables support at startup; go straight to the iptables backend. Useful on systems where nftables is installed but non-functional (e.g. missing kernel modules). |
| `NB_NFTABLES_TABLE` | Linux | Name of the nftables table the client creates for ACL rules (default: `netbird`). Change this if the default name conflicts with existing firewall configuration. |
| `NB_DISABLE_CONNTRACK` | All | Turn off the stateful connection tracker in the userspace packet filter. With conntrack enabled (default), inbound rules for return traffic sent by management are ignored because conntrack handles them automatically. Disabling conntrack means those inbound rules will be applied explicitly instead. |
| `NB_DISABLE_USERSPACE_ROUTING` | All | Prevent the userspace packet filter from forwarding packets between interfaces. Routing rules from the management server will be ignored when this is set. |
| `NB_DISABLE_MSS_CLAMPING` | All | Stop the userspace filter from rewriting TCP SYN/SYN-ACK MSS options to fit the WireGuard MTU. May cause path-MTU black holes if disabled. |
| `NB_FORCE_USERSPACE_ROUTER` | All | Force packet forwarding through the userspace router even when a native firewall backend (nftables/iptables) is available. Normally, the presence of a native backend causes the client to delegate route forwarding to the kernel. This flag overrides that: the native backend still handles ACL rules, but routed packets are forwarded by the userspace filter instead. On macOS, Windows, and netstack mode the userspace router is always used regardless of this setting. |
| `NB_ENABLE_LOCAL_FORWARDING` | All | Allow the userspace filter to forward packets destined for local addresses (not just routed subnets). Off by default to prevent unexpected local service exposure. |
| `NB_ENABLE_NETSTACK_LOCAL_FORWARDING` | All | Same as `NB_ENABLE_LOCAL_FORWARDING` but applies only when running in netstack mode. Takes precedence over the general setting when both are set. |
| `NB_USPFILTER_LOG_BUFFER` | All | Number of log messages the userspace packet filter can queue before dropping (default: `1000`). Increase this on high-throughput nodes to avoid losing firewall log entries. |
## ICE and connectivity
| Variable | Platform | Description |
|---|---|---|
| `NB_FORCE_RELAY` | All | Skip direct connectivity entirely: the client will not start the ICE listener or attempt peer-to-peer connections. All traffic goes through relay servers. Useful for strict egress-only environments. |
| `NB_ICE_KEEP_ALIVE_INTERVAL_SEC` | All | How often (in seconds) ICE sends keepalive packets to maintain NAT bindings and detect connection liveness (default: `4`). |
| `NB_ICE_DISCONNECTED_TIMEOUT_SEC` | All | Seconds of silence before ICE marks a connection as disconnected and starts recovery (default: `6`). |
| `NB_ICE_FAILED_TIMEOUT_SEC` | All | Seconds of silence before ICE gives up on the connection entirely and falls back to relay (default: `6`). |
| `NB_ICE_RELAY_ACCEPTANCE_MIN_WAIT_SEC` | All | Minimum seconds ICE waits for a direct (P2P) candidate before accepting a relay candidate. Higher values give direct connections more time to succeed at the cost of slower initial connection (default: `2`). |
| `NB_ICE_MONITOR_PERIOD` | All | Interval between ICE connection health checks that verify handshake freshness and trigger reconnection if needed (Go duration, default: `5m`). |
| `NB_ENABLE_EXPERIMENTAL_LAZY_CONN` | All | Open WireGuard tunnels to peers only when traffic is detected, instead of connecting to all peers at startup. Same effect as the `--enable-lazy-connection` CLI flag. |
| `NB_LAZY_CONN_INACTIVITY_THRESHOLD` | All | How long a lazy connection can be idle before it is torn down (Go duration, default: `15m`). Only applies when lazy connections are enabled. |
## DNS
| Variable | Platform | Description |
|---|---|---|
| `NB_DNS_FORWARDER_PORT` | All | Override the port the internal DNS forwarder binds to for handling DNS routes received from clients (default: `22054`). The forwarder is separate from the local resolver. |
| `NB_SKIP_DNS_PROBE` | All | Skip the startup check that sends a test query to the local resolver to verify it is reachable. Set this if the probe causes delays (e.g. in air-gapped networks). |
| `NB_UNCLEAN_SHUTDOWN_RESOLV_FILE` | Linux, FreeBSD | Custom file path to store a backup of `/etc/resolv.conf` before the client modifies it. Used to restore the original on next startup if the client crashed without cleaning up (default: `<state-dir>/resolv.conf`, i.e. `/var/lib/netbird/resolv.conf` on Linux, `/var/db/netbird/resolv.conf` on FreeBSD). |
## Connection retry
These control the exponential backoff when the client loses its connection to the management or signal server.
| Variable | Platform | Description |
|---|---|---|
| `NB_CONN_RETRY_INTERVAL_TIME` | All | Initial wait time before the first reconnection attempt (Go duration, e.g. `5s`). |
| `NB_CONN_MAX_RETRY_INTERVAL_TIME` | All | Upper bound on the backoff interval; retries will never wait longer than this (Go duration). |
| `NB_CONN_MAX_RETRY_TIME_TIME` | All | Total time the client will keep retrying before giving up and reporting a persistent failure (Go duration). Note: the double `_TIME` suffix is intentional and matches the variable name in the source code. |
| `NB_CONN_RETRY_MULTIPLIER` | All | Factor by which the retry interval grows after each attempt (float, e.g. `1.7`). |
## SSH
| Variable | Platform | Description |
|---|---|---|
| `NB_DISABLE_SSH_CONFIG` | All | Prevent the client from writing NetBird peer entries into the system SSH config directory (`/etc/ssh/ssh_config.d/99-netbird.conf` on Unix, `%PROGRAMDATA%\ssh\ssh_config.d\99-netbird.conf` on Windows). By default, the client adds `Host` blocks so you can `ssh peer-name` without specifying the IP. |
| `NB_FORCE_SSH_CONFIG` | All | Write the SSH config entries even when the peer count exceeds the default limit of 200. Without this, the client skips SSH config generation for large networks to avoid slow file writes. |
## Relay
| Variable | Platform | Description |
|---|---|---|
| `NB_RELAY_HC_ATTEMPT_THRESHOLD` | All | Number of consecutive failed WebSocket pings before the client considers a relay server unreachable and switches to a different one (default: `1`). |
## Management
| Variable | Platform | Description |
|---|---|---|
| `NB_MANAGEMENT_GRPC_MAX_MSG_SIZE` | All | Maximum size (in bytes) of a single gRPC message from the management server. Increase this when the network map (peers, firewall rules, routes, DNS config) exceeds the default 4 MB gRPC limit. |
## Other
| Variable | Platform | Description |
|---|---|---|
| `NB_STATE_DIR` | All | Override the directory where the client stores persistent state files (config, state.json, WireGuard keys). Defaults to `/var/lib/netbird` on Linux/macOS, `/var/db/netbird` on FreeBSD, `%PROGRAMDATA%\Netbird` on Windows. |
| `NB_DNS_STATE_FILE` | All | Override the path to the client state file (`state.json`). Despite the name, this is not DNS-specific: it stores all shutdown/recovery state including DNS settings, SSH config, routes, and auto-update progress. The default path is per-profile (e.g. `/var/lib/netbird/state.json` for the default profile). Setting this bypasses per-profile state isolation. Primarily used by the embedded client API (`embed.Options.StatePath`). |
| `NB_ROSENPASS_LOG_LEVEL` | All | Log level for the Rosenpass post-quantum key exchange subprocess. Accepted values: `debug`, `info`, `warn`, `error` (default: `info`). Separate from the main client log level. |
| `NB_AUTO_UPDATE_DRY_RUN` | All | Set to `true` to run the auto-update check and download steps without actually replacing the binary. Useful for testing update infrastructure. |
| `NB_PPROF_ADDR` | All | Start a Go pprof HTTP endpoint at this address (e.g. `localhost:6060`). For profiling CPU, memory, and goroutine usage in production. |
| `NB_METRICS_PUSH_ENABLED` | All | Set to `true` to enable periodic push of client telemetry (connection quality, peer counts) to a metrics server. Disabled by default. |
| `NB_METRICS_INTERVAL` | All | How often to push metrics when enabled (Go duration, e.g. `60s`). |
| `NB_METRICS_SERVER_URL` | All | URL of the metrics collection server. Only needed when overriding the built-in default. |
| `NB_METRICS_CONFIG_URL` | All | URL to fetch remote metrics configuration (which metrics to collect, sampling rates). Only needed when overriding the built-in default. |

370
src/pages/get-started/cli.mdx
View File

@@ -10,7 +10,7 @@ Use the following syntax to run `netbird` commands from your terminal window:
```shell
netbird [command] [subcommand] [flags]
```
* `command`: Specifies the operation that you want to perform or a top-level command: `up`, `login`, `down`, `status`, `ssh`, `expose`, `version`, and `service`
* `command`: Specifies the operation that you want to perform or a top-level command: `up`, `login`, `down`, `status`, `ssh`, `expose`, `networks`, `profile`, `debug`, `service`, and `version`
* `subcommand`: Specifies the operation to be executed for a top-level command like `service`: `install`, `uninstall`, `start`, and `stop`
* `flags`: Specifies optional flags. For example, you can use the `--setup-key` flag to specify the setup key to be used in the commands `login` and `up`
@@ -18,6 +18,12 @@ netbird [command] [subcommand] [flags]
To see detailed command information, use the flag `--help` after each command
</Note>
### Flag value syntax
- **Boolean flags** that default to `false` can be enabled by simply passing the flag: `--block-inbound`.
- **Boolean flags** that default to `true` must use `=false` to disable: `--strict-host-key-checking=false`, `--network-monitor=false`.
- **String flags** that support clearing a previous value accept an empty string: `--dns-resolver-address ""`.
## Configuration precedence
This is the CLI configuration precedence (highest to lowest priority):
@@ -33,15 +39,18 @@ We are preserving the unusual priority of environment variables for backwards co
Below is the list of global flags:
```shell
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io")
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io:443")
-A, --anonymize anonymize IP addresses and non-netbird.io domains in logs and status output
-c, --config string Overrides the default profile file location. Deprecated on `up` and `login`; use `--service-env NB_CONFIG=<path>` instead.
--daemon-addr string Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netbird.sock")
--log-file string sets NetBird log path. If console is specified the the log will be output to stdout (default "/var/log/netbird/client.log")
-l, --log-level string sets NetBird log level (default "info")
-n, --hostname string Sets a custom hostname for the device
--log-file console Sets NetBird log paths written to simultaneously. If "console" is specified the log will be output to stdout. If "syslog" is specified the log will be sent to the syslog daemon. You can pass the flag multiple times or separate entries by comma (default [/var/log/netbird/client.log])
-l, --log-level string Sets NetBird log level (default "info")
-m, --management-url string Management Service URL [http|https]://[host]:[port] (default "https://api.netbird.io:443")
-p, --preshared-key string Sets Wireguard PreSharedKey property. If set, then only peers that have the same key can communicate.
--preshared-key string Sets WireGuard PreSharedKey property. If set, then only peers that have the same key can communicate.
-s, --service string NetBird system service name (default "netbird")
-k, --setup-key string Setup key obtained from the Management Service Dashboard (used to register peer)
--setup-key-file string Path to a file containing a setup key (used to register peer). Ignored if --setup-key is provided.
```
### Environment Variables
Every flag of a `netbird` command can be passed as an environment variable. We are using the following rule for the environment variables composition:
@@ -72,6 +81,8 @@ export NB_LOG_LEVEL=debug
export NB_DAEMON_ADDR="tcp://localhost:8080"
```
Beyond flag-derived variables, the client also supports a number of advanced environment variables for tuning networking, firewall, ICE connectivity, and more. See the [Client Environment Variables](/client/environment-variables) reference for the full list.
## Commands
### up
Single command to log in and start the NetBird client. It can send a signal to the daemon service or run in the foreground with the flag `--foreground-mode`.
@@ -79,30 +90,36 @@ Single command to log in and start the NetBird client. It can send a signal to t
The command will check if the peer is logged in and connect to the management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
#### Flags
```shell
--allow-server-ssh Allow SSH server on peer. If enabled, the SSH server will be permitted
--disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
--disable-client-routes Disable client routes. If enabled, the client won't process client routes received from the management service.
--disable-dns Disable DNS. If enabled, the client won't configure DNS settings.
--disable-firewall Disable firewall configuration. If enabled, the client won't modify firewall rules.
--disable-server-routes Disable server routes. If enabled, the client won't act as a router for server routes received from the management service.
--disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication
--dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best ip and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
--ssh-jwt-cache-ttl int SSH JWT token cache TTL in seconds. Set to 0 to disable caching (default). E.g. --ssh-jwt-cache-ttl 3600 for 1-hour cache
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
--enable-ssh-local-port-forwarding Enable local port forwarding on SSH server. Requires --allow-server-ssh
--enable-ssh-remote-port-forwarding Enable remote port forwarding on SSH server. Requires --allow-server-ssh
--enable-ssh-root Enable root user login on SSH server. Requires --allow-server-ssh
--enable-ssh-sftp Enable SFTP subsystem on SSH server. Requires --allow-server-ssh
--external-ip-map strings Sets external IPs maps between local addresses and interfaces.You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map ""
--extra-dns-labels strings Sets DNS labels. You can specify a comma-separated list of up to 32 labels. An empty string "" clears the previous configuration. E.g. --extra-dns-labels vpc1 or --extra-dns-labels vpc1,mgmt1 or --extra-dns-labels ""
-F, --foreground-mode start service in foreground
-h, --help help for up
--interface-name string Wireguard interface name (default "utun100")
--rosenpass-permissive [Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled.
--wireguard-port uint16 Wireguard interface listening port (default 51820)
--block-inbound Block inbound connections. If enabled, the client will not allow any inbound connections to the local machine nor routed networks. This overrides any policies received from the management service.
--block-lan-access Block LAN access. If enabled, the client will not allow NetBird peers to access the local network.
--allow-server-ssh Allow SSH server on peer
--block-inbound Block inbound connections. If enabled, the client will not allow any inbound connections to the local machine nor routed networks. This overrides any policies received from the management service.
--block-lan-access Block access to local networks (LAN) when using this peer as a router or exit node
--disable-auto-connect Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.
--disable-client-routes Disable client routes. If enabled, the client won't process client routes received from the management service.
--disable-dns Disable DNS. If enabled, the client won't configure DNS settings.
--disable-firewall Disable firewall configuration. If enabled, the client won't modify firewall rules.
--disable-ipv6 Disable IPv6 overlay. If enabled, the client won't request or use an IPv6 overlay address.
--disable-server-routes Disable server routes. If enabled, the client won't act as a router for server routes received from the management service.
--disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication.
--dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best IP and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
--dns-router-interval duration DNS route update interval (default 1m0s)
--enable-lazy-connection [Experimental] Enable the lazy connection feature. If enabled, the client will establish connections on-demand. Note: this setting may be overridden by management configuration.
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
--enable-ssh-local-port-forwarding Enable local port forwarding for SSH server
--enable-ssh-remote-port-forwarding Enable remote port forwarding for SSH server
--enable-ssh-root Enable root login for SSH server
--enable-ssh-sftp Enable SFTP subsystem for SSH server
--external-ip-map strings Sets external IPs maps between local addresses and interfaces. You can specify a comma-separated list with a single IP and IP/IP or IP/Interface Name. An empty string "" clears the previous configuration. E.g. --external-ip-map 12.34.56.78/10.0.0.1 or --external-ip-map 12.34.56.200,12.34.56.78/10.0.0.1,12.34.56.80/eth1 or --external-ip-map ""
--extra-dns-labels strings Sets DNS labels. You can specify a comma-separated list of up to 32 labels. An empty string "" clears the previous configuration. E.g. --extra-dns-labels vpc1 or --extra-dns-labels vpc1,mgmt1 or --extra-dns-labels ""
--extra-iface-blacklist strings Extra list of default interfaces to ignore for listening
-F, --foreground-mode Start service in foreground
--interface-name string WireGuard interface name (default "wt0")
--mtu uint16 Set MTU (Maximum Transmission Unit) for the WireGuard interface (default 1280)
-N, --network-monitor Manage network monitoring. Defaults to true on Windows and macOS, false on Linux and FreeBSD. E.g. --network-monitor=false to disable or --network-monitor=true to enable.
--no-browser Do not open the browser for SSO login
--profile string Profile name to use for the login. If not specified, the last used profile will be used.
--rosenpass-permissive [Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled.
--ssh-jwt-cache-ttl int SSH JWT token cache TTL in seconds (default 0, disabled). When enabled, the client caches the JWT so repeated SSH connections skip the OIDC login flow. The receiving SSH server rejects tokens older than 10 minutes, so values above 600 will result in authentication failures for cached tokens.
--wireguard-port uint16 WireGuard interface listening port (default 51820)
```
#### Usage
The minimal form of running the command is:
@@ -134,6 +151,11 @@ netbird up --setup-key AAAA-BBB-CCC-DDDDDD --extra-dns-labels vpc1,mgmt1
### login
Command to authenticate the NetBird client to a management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
#### Flags
```shell
--no-browser Do not open the browser for SSO login
--profile string Profile name to use for the login. If not specified, the last used profile will be used.
```
#### Usage
The minimal form of running the command is:
```shell
@@ -164,15 +186,16 @@ netbird down
Retrieves the peer status from the daemon service.
#### Flags
```shell
-d, --detail display detailed status information in human-readable format
--filter-by-ips strings filters the detailed output by a list of one or more IPs, e.g., --filter-by-ips 100.64.0.100,100.64.0.200
--filter-by-names strings filters the detailed output by a list of one or more peer FQDN or hostnames, e.g., --filter-by-names peer-a,peer-b.netbird.cloud
--filter-by-status string filters the detailed output by connection status(connected|disconnected), e.g., --filter-by-status connected
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the status output
-h, --help help for status
--ipv4 display only NetBird IPv4 of this peer, e.g., --ipv4 will output 100.64.0.33
--json display detailed status information in json format
--yaml display detailed status information in yaml format
--check string Run a health check and exit with code 0 on success, 1 on failure (live|ready|startup)
-d, --detail Display detailed status information in human-readable format
--filter-by-connection-type string Filter the detailed output by connection type (P2P|Relayed), e.g., --filter-by-connection-type P2P
--filter-by-ips strings Filter the detailed output by a list of one or more IPs (v4 or v6), e.g., --filter-by-ips 100.64.0.100,fd00::1
--filter-by-names strings Filter the detailed output by a list of one or more peer FQDN or hostnames, e.g., --filter-by-names peer-a,peer-b.netbird.cloud
--filter-by-status string Filter the detailed output by connection status (idle|connecting|connected), e.g., --filter-by-status connected
--ipv4 Display only NetBird IPv4 of this peer, e.g., --ipv4 will output 100.64.0.33
--ipv6 Display only NetBird IPv6 of this peer
--json Display detailed status information in JSON format
--yaml Display detailed status information in YAML format
```
#### Usage
The minimal form of running the command is:
@@ -416,13 +439,20 @@ Connect to a remote peer via SSH with an interactive shell or execute a command.
**Flags:**
```shell
-L, --local-forward string Local port forwarding (e.g., 8080:localhost:80)
-R, --remote-forward string Remote port forwarding (e.g., 8080:localhost:3000)
-p, --port int Remote SSH port (default: 22)
-L stringArray Local port forwarding [bind_address:]port:host:hostport
-R stringArray Remote port forwarding [bind_address:]port:host:hostport
-o, --known-hosts string Path to known_hosts file (default: ~/.ssh/known_hosts)
--login string SSH username (alias for --user)
--no-browser Do not open the browser for SSO login
--no-cache Skip cached JWT token and force fresh authentication
-p, --port int Remote SSH port (default 22)
--strict-host-key-checking Enable strict host key checking (default true)
-t, --tty Force pseudo-terminal allocation
-u, --user string SSH username
```
**Arguments:**
* `user@host`: The remote user and NetBird peer IP address
* `[user@]host`: The remote user and NetBird peer hostname or IP address
* `[command]`: Optional command to execute on the remote peer
**Usage:**
@@ -495,15 +525,16 @@ Command to expose a local port to the public internet via the NetBird reverse pr
#### Flags
```shell
--with-pin string Protect the exposed service with a 6-digit PIN (e.g. --with-pin 123456)
--with-password string Protect the exposed service with a password (e.g. --with-password my-secret)
--with-user-groups strings Restrict access to specific user groups (e.g. --with-user-groups devops,Backend)
--protocol string Protocol to use: http, https, tcp, udp, or tls (e.g. --protocol tcp) (default "http")
--with-custom-domain string Custom domain for the exposed service, must be configured to your account (e.g. --with-custom-domain myapp.example.com)
--with-external-port uint16 Public-facing external port on the proxy cluster (defaults to the target port for L4)
--with-name-prefix string Prefix for the generated service name (e.g. --with-name-prefix my-app)
--protocol string Protocol to use: 'http' or 'https' (e.g. --protocol http) (default "http")
--with-password string Protect the exposed service with a password (e.g. --with-password my-secret)
--with-pin string Protect the exposed service with a 6-digit PIN (e.g. --with-pin 123456)
--with-user-groups strings Restrict access to specific user groups with SSO (e.g. --with-user-groups devops,Backend)
```
#### Usage
Expose a local HTTP server running on port 8080:
Expose a local service running on port 8080 (defaults to HTTP):
```shell
netbird expose 8080
```
@@ -530,6 +561,14 @@ Expose with SSO user group restriction:
```shell
netbird expose 8080 --with-user-groups engineering,devops
```
Expose a raw TCP service (e.g. a database or game server):
```shell
netbird expose 5432 --protocol tcp
```
Expose a TLS-terminated service:
```shell
netbird expose 8443 --protocol tls
```
Expose using a custom domain (must be pre-configured in your account):
```shell
netbird expose 8080 --with-custom-domain app.example.com
@@ -540,6 +579,60 @@ Press `Ctrl+C` to stop exposing the service. The service is automatically remove
Each peer can have up to 10 active expose sessions simultaneously. The session is kept alive with automatic renewals every 30 seconds and expires after 90 seconds if the client disconnects unexpectedly.
</Note>
### networks
Commands to list, select, or deselect networks. This replaces the older `routes` command (which still works as an alias).
#### Usage
```shell
netbird networks [command]
```
#### Subcommands
- `list`: List all available networks and their selection status.
- `select`: Select networks to connect to.
- `deselect`: Deselect networks.
#### networks select
Select a list of networks by identifiers, or `all` to clear all selections and accept all (including new) networks.
Default mode is replace; use `-a` to append to the current selection.
```shell
netbird networks select network...|all [flags]
```
**Flags:**
```shell
-a, --append Append to current network selection instead of replacing
```
**Examples:**
```shell
netbird networks select all
netbird networks select route1 route2
netbird networks select -a route3
```
#### networks deselect
Deselect a list of networks by identifiers, or `all` to deselect all.
```shell
netbird networks deselect network...|all
```
### profile
Commands to list, add, remove, and switch profiles. Profiles allow you to maintain different accounts in one client app.
#### Usage
```shell
netbird profile [command]
```
#### Subcommands
- `list`: List all profiles.
- `add`: Add a new profile.
- `remove`: Remove a profile.
- `select`: Select a profile to use.
### version
Outputs the `netbird` command version.
#### Usage
@@ -575,15 +668,31 @@ sudo netbird service install --config /opt/netbird/config.json
#### Service-specific flags
```shell
--disable-profiles Disables profiles feature. If enabled, the client will not be able to change or edit any profile. To persist this setting, use: netbird service install --disable-profiles
--disable-update-settings Disables update settings feature. If enabled, the client will not be able to change or edit any settings. To persist this setting, use: netbird service install --disable-update-settings
--disable-profiles Disables profiles feature.
--disable-update-settings Disables update settings feature.
--service-env strings Sets extra environment variables for the service. You can specify a comma-separated list of KEY=VALUE pairs. E.g. --service-env NB_LOG_LEVEL=debug,CUSTOM_VAR=value
```
These flags are intended for managed or shared machines where non-admin users should not be able to alter the client configuration through the CLI or UI:
- `--disable-profiles` prevents users from adding, removing, or switching profiles. The client stays locked to the profile that was active at install time. Any attempt to switch profiles via CLI or UI is rejected.
- `--disable-update-settings` prevents users from changing daemon settings (management URL, log level, DNS resolver address, etc.) via CLI or UI. The configuration can only be changed by an administrator who reinstalls the service or uses `service reconfigure`.
Typical use: an IT admin deploys NetBird with a setup key and locks the configuration so end users cannot disconnect from the corporate account or point the client at a different management server.
```shell
sudo netbird service install \
--setup-key AAAA-BBB-CCC-DDDDDD \
--disable-profiles \
--disable-update-settings
```
<Note>
The `--disable-profiles` flag can also be set using the `NB_DISABLE_PROFILES` environment variable. Set it to any value (e.g., `true`, `1`, `yes`) to enable this feature.
The `--disable-update-settings` flag can also be set using the `NB_DISABLE_UPDATE_SETTINGS` environment variable. Set it to any value (e.g., `true`, `1`, `yes`) to enable this feature.
Install parameters (including `--disable-profiles`, `--disable-update-settings`, and `--service-env`) are persisted to a `service.json` file and survive uninstall/reinstall cycles. To clear saved parameters and revert to defaults, run `netbird service reset-params` followed by `netbird service reconfigure`.
</Note>
<Note>
These flags can also be set via environment variables: `NB_DISABLE_PROFILES` and `NB_DISABLE_UPDATE_SETTINGS`.
</Note>
### service uninstall
@@ -631,16 +740,22 @@ sudo netbird service status
```
### service reconfigure
Reconfigures the daemon service with current settings
#### Usage
The minimal form of running the command is:
Reconfigures the daemon service with new settings without manual uninstall/install. The command temporarily stops the service, updates its configuration, and restarts it if it was running.
#### Flags
```shell
sudo netbird service reconfigure
--service-env strings Sets extra environment variables for the service. E.g. --service-env NB_LOG_LEVEL=debug,CUSTOM_VAR=value
```
#### Usage
```shell
sudo netbird service reconfigure --service-env NB_LOG_LEVEL=debug
```
<Note>
If you installed the service with `--disable-profiles` or `--disable-update-settings`, these settings will persist and the respective features will remain disabled after reconfiguration.
</Note>
### service reset-params
Removes the saved `service.json` file so the next install uses default parameters.
#### Usage
```shell
sudo netbird service reset-params
```
### debug
The `debug` command provides tools for diagnosing and understanding the internal operations of the NetBird daemon.
@@ -654,6 +769,7 @@ netbird debug [command]
- `bundle`: Create a debug bundle that includes logs and system information for troubleshooting.
- `for`: Run the daemon with trace logging for a specified duration and create a debug bundle.
- `log`: Manage logging levels for the NetBird daemon.
- `trace`: Trace a packet through the firewall.
#### Flags
```shell
@@ -662,13 +778,13 @@ netbird debug [command]
### debug bundle
Generates a compressed archive containing diagnostic information, which can be used for troubleshooting.
The file will be generated in the a temporary directory and the path will be printed to the console.
The file will be generated in a temporary directory and the path will be printed to the console.
The file is only accessible as root/Administrator.
#### Usage
To create a debug bundle:
```shell
netbird debug bundle [-A] [-S]
netbird debug bundle [-A] [-S] [-U] [-C <count>]
```
#### Examples
@@ -684,9 +800,11 @@ This will output:
#### Flags
```shell
-h, --help help for bundle
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the debug output
-S, --system-info Adds system information to the debug bundle
-A, --anonymize Anonymize IP addresses and non-netbird.io domains in the debug output
-C, --log-file-count uint32 Number of rotated log files to include in debug bundle (default 1)
-S, --system-info Adds system information to the debug bundle (default true)
-U, --upload-bundle Uploads the debug bundle to a server
--upload-bundle-url string Service URL to get an upload URL for the debug bundle (default "https://upload.debug.netbird.io/upload-url")
```
### debug for
@@ -696,7 +814,7 @@ This is useful for capturing detailed logs over a period where issues are occurr
#### Usage
To run debugging for a specific time period:
```shell
netbird debug for <time> [-A] [-S]
netbird debug for <time> [-A] [-S] [-U] [-C <count>]
```
#### Examples
@@ -721,12 +839,13 @@ Log level restored to INFO
#### Flags
```shell
-h, --help help for for
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the debug output
-S, --system-info Adds system information to the debug bundle
-A, --anonymize Anonymize IP addresses and non-netbird.io domains in the debug output
-C, --log-file-count uint32 Number of rotated log files to include in debug bundle (default 1)
-S, --system-info Adds system information to the debug bundle (default true)
-U, --upload-bundle Uploads the debug bundle to a server
--upload-bundle-url string Service URL to get an upload URL for the debug bundle (default "https://upload.debug.netbird.io/upload-url")
```
### debug log
This subcommand manages the logging level for the NetBird daemon during the current session.
The change in logging level is temporary and will revert back to the configured default upon daemon restart.
@@ -757,3 +876,114 @@ This will output:
Log level set successfully to debug
```
### debug trace
Traces a packet through the firewall rules to diagnose policy issues. You specify the direction, source IP, destination IP, protocol, and optional port/flag parameters. Use `self` as an alias for the local peer's IP.
<Note>
On Linux, the userspace packet filter is only active when the kernel firewall backend is not available. By default, Linux uses the kernel-mode nftables/iptables backend, so `debug trace` is primarily useful on macOS and Windows where the userspace filter is always used.
</Note>
#### Usage
```shell
netbird debug trace <direction> <source-ip> <dest-ip> [flags]
```
#### Flags
```shell
--ack TCP ACK flag
--dport uint16 Destination port
--fin TCP FIN flag
--icmp-code uint8 ICMP code
--icmp-type uint8 ICMP type
-p, --protocol string Protocol: tcp, udp, or icmp (default "tcp")
--psh TCP PSH flag
--rst TCP RST flag
--sport uint16 Source port
--syn TCP SYN flag
--urg TCP URG flag
```
#### Understanding the output
The trace walks the packet through each processing stage of the firewall. Each line shows the stage name and its result. Here is an example of an allowed inbound SSH connection:
```
$ netbird debug trace in 100.64.1.1 self -p tcp --dport 22 --syn
Packet trace 100.64.1.1:54728 → self:22 (TCP)
Received: Received TCP packet: 100.64.1.1:54728 -> 100.64.0.1:22
Inbound Port DNAT: TCP port DNAT applied: 100.64.0.1:22 -> 100.64.0.1:22022
Inbound 1:1 NAT: 1:1 NAT not enabled
Connection Tracking: No existing connection found
Routing: Packet destined for local delivery
Peer ACL: Allowed by peer ACL rules (d2kab80l3is5mqgsj2b0)
Completed: Processing completed
Final disposition: ALLOWED
```
The stages in order:
1. **Received**: The raw packet as it enters the filter.
2. **Inbound Port DNAT**: Port-level destination NAT (e.g. SSH port 22 is rewritten to 22022 where the NetBird SSH server listens).
3. **Inbound 1:1 NAT**: Full address rewrite if 1:1 NAT is configured for this peer.
4. **Connection Tracking**: Checks if this packet belongs to an already-established connection. If it does, it is allowed immediately and later stages are skipped.
5. **Routing**: Determines whether the packet is destined for local delivery or needs to be forwarded to another network.
6. **Peer ACL / Route ACL**: Evaluates the access control rules from your policies. The output includes the policy ID for easier debugging.
7. **Forwarding** (routed packets only): Shows which route handler will forward the packet.
8. **Completed**: Final result.
Here is a denied packet (no matching ACL rule):
```
$ netbird debug trace in 100.64.2.1 self -p tcp --dport 80 --syn
Packet trace 100.64.2.1:58026 → self:80 (TCP)
Received: Received TCP packet: 100.64.2.1:58026 -> 100.64.0.1:80
Inbound Port DNAT: No matching port DNAT rule
Inbound 1:1 NAT: 1:1 NAT not enabled
Connection Tracking: No existing connection found
Routing: Packet destined for local delivery
Peer ACL: Blocked by peer ACL rules
Completed: Packet dropped - ACL denied
Final disposition: DENIED
```
And a routed packet that is allowed and forwarded:
```
$ netbird debug trace in 100.64.1.1 10.10.0.1 -p tcp --dport 443 --syn
Packet trace 100.64.1.1:49659 → 10.10.0.1:443 (TCP)
Received: Received TCP packet: 100.64.1.1:49659 -> 10.10.0.1:443
Inbound Port DNAT: No matching port DNAT rule
Inbound 1:1 NAT: 1:1 NAT not enabled
Connection Tracking: No existing connection found
Routing: Routing enabled, checking ACLs
Route ACL: Allowed by route ACLs (d1se3g0l3is3n6ucpmt0)
Forwarding: Forwarding to proxy-remote [proxy-remote to 10.10.0.1:443]
Completed: Processing completed
Final disposition: ALLOWED
```
#### Examples
Trace an inbound TCP SYN to SSH:
```shell
netbird debug trace in 100.64.1.1 self -p tcp --dport 22 --syn
```
Trace an outbound UDP packet to port 53:
```shell
netbird debug trace out self 100.64.1.2 -p udp --dport 53
```
Trace an inbound ICMP echo request:
```shell
netbird debug trace in 100.64.1.2 self -p icmp --icmp-type 8 --icmp-code 0
```

16
src/pages/help/troubleshooting-client.mdx
View File

@@ -242,6 +242,22 @@ The upload key is automatically copyable by clicking on it. Share this key throu
- Bundles are automatically uploaded to NetBird's secure storage (or your configured upload endpoint for self-hosted deployments)
- Upload keys expire after 30 days for security
### Tracing firewall rules
If a connection is being blocked and you suspect a policy issue, the `debug trace` command lets you simulate a packet through the firewall rules without sending real traffic. See the [CLI reference](/get-started/cli#debug-trace) for full usage and examples.
```shell
netbird debug trace in 100.64.1.1 self -p tcp --dport 80
```
<Note>
On Linux, the userspace packet filter is only active when the kernel firewall backend (nftables/iptables) is not available. `debug trace` is primarily useful on macOS and Windows.
</Note>
### Advanced environment variables
The client has environment variables for tuning routing, firewall behavior, ICE connectivity, and WireGuard mode. These can help work around edge cases (e.g. `NB_USE_LEGACY_ROUTING` for routing loop issues, `NB_WG_KERNEL_DISABLED` to force userspace WireGuard, `NB_SKIP_NFTABLES_CHECK` to fall back to iptables). See the full list at [Client Environment Variables](/client/environment-variables).
## Enabling debug logs on agent
Logs can be temporarily set using the following command.