sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-05-04 08:16: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

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
```