sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-19 17:06:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
493803e20c87fafa62b7a4a684fa4ba25ee20cbb
netbird-docs/src/pages/how-to/cli.mdx
Viktor Liu 493803e20c Add client cli debug (#186) 
Add cli debug command and update outputs
2024-05-15 18:09:29 +02:00

552 lines
19 KiB
Plaintext
Raw Blame History

# NetBird Agent command line interface (CLI)
The NetBird client installation adds a binary called `netbird` to your system. This binary runs as a daemon service to connect
your computer or server to the NetBirt network as a peer. But it can also be used as a client to control the daemon service.
This section will explore the commands available in `netbird`.
## Syntax
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`, `version`, and `service`
* `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`
<Note>
To see detailed command information, use the flag `--help` after each command
</Note>
## Global flags
`netbird` has a set of global flags that are available in every command. They specify settings that are core or shared between two or more commands, e.g. `--setup-key` is used by `login` and `up` to authenticate the client against a management service.
Below is the list of global flags:
```shell
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io")
-A, --anonymize anonymize IP addresses and non-netbird.io domains in logs and status output
-c, --config string Netbird config file location (default "/etc/netbird/config.json")
--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")
-m, --management-url string Management Service URL [http|https]://[host]:[port] (default "https://api.wiretrustee.com:443")
-p, --preshared-key string Sets Wireguard PreSharedKey property. If set, then only peers that have the same key can communicate.
-k, --setup-key string Setup key obtained from the Management Service Dashboard (used to register peer)
```
### 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:
* `PREFIX_FLAGNAME` and for flags with multiple parts: `PREFIX_FLAGNAMEPART1_FLAGNAMEPART2`
* The prefix is always **NB**
* The flag parts are separated by a dash ("-") when passing as flags and with an underscore ("_") when passing as an environment variable
For example, let's check how we can pass `--config` and `--management-url` as environment variables:
```shell
export NB_CONFIG="/opt/netbird/config.json"
export NB_MANAGEMENT_URL="https://api.self-hosted.com:33073"
netbird up
```
The `up` command would process the variables, read the configuration file on `/opt/netbird/config.json` and attempt to connect to the management service running at `https://api.self-hosted.com:33073`.
## 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`.
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.
--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 ""
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
--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 ""
-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)
```
#### Usage
The minimal form of running the command is:
```shell
netbird up
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird up --management-url https://api.self-hosted.com:33073
```
if you want to run in the foreground, you can use "console" as the value for `--log-file` and run the command with sudo:
```shell
sudo netbird up --log-file console
```
<Note>
On Windows, you may need to run the command from an elevated terminal session.
</Note>
In case you need to use a setup key, use the `--setup-key` flag :
```shell
netbird up --setup-key AAAA-BBB-CCC-DDDDDD
```
### 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.
#### Usage
The minimal form of running the command is:
```shell
netbird login
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird login --management-url https://api.self-hosted.com:33073
```
In case you need to use a setup key, use the `--setup-key` flag:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD
```
Passing a management url and a setup key:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD --management-url https://api.self-hosted.com:33073
```
### down
Command to stop a connection with the management service and other peers in a NetBird network. After running this command, the daemon service will enter an `Idle` state.
#### Usage
The minimal form of running the command is:
```shell
netbird down
```
### status
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
```
#### Usage
The minimal form of running the command is:
```shell
netbird status
```
This will output:
```shell
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 1/1 Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
If you want to see more details about the peer connections, you can use the `--detail` or `-d` flag:
```shell
netbird status -d
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.85.4
Public key: 2lI3F+fDUWh58g5oRN+y7lPHpNcEVWhiDv/wr1/jiF8=
Status: Disconnected
-- detail --
Connection type: -
Direct: false
ICE candidate (Local/Remote): -/-
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 26 seconds ago
Last Wireguard handshake: -
Transfer status (received/sent) 0 B/0 B
Quantum resistance: false
Routes: -
Latency: 10.74ms
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 26 seconds ago
Last Wireguard handshake: 25 seconds ago
Transfer status (received/sent) 2.0 KiB/355 B
Quantum resistance: false
Routes: 10.0.0.0/24
Latency: 20.14ms
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 26 seconds ago
Last Wireguard handshake: 24 seconds ago
Transfer status (received/sent) 2.4 MiB/532 KiB
Quantum resistance: false
Routes: -
Latency: 16.24ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
To filter the peers' output by connection status, you can use the `--filter-by-status` flag with either "connected" or "disconnected" as value:
```shell
netbird status -d --filter-by-status connected
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 28 seconds ago
Last Wireguard handshake: 27 seconds ago
Transfer status (received/sent) 2.0 KiB/355 B
Quantum resistance: false
Routes: 10.0.0.0/24
Latency: 20.14ms
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 28 seconds ago
Last Wireguard handshake: 26 seconds ago
Transfer status (received/sent) 2.4 MiB/532 KiB
Quantum resistance: false
Routes: -
Latency: 16.24ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
To filter the peers' output by peer IP addresses, you can use the `--filter-by-ips` flag with one or more IPs separated by a comma as a value:
```shell
netbird status -d --filter-by-ips 100.119.201.225
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 32 seconds ago
Last Wireguard handshake: 30 seconds ago
Transfer status (received/sent) 2.0 KiB/355 B
Quantum resistance: false
Routes: 10.0.0.0/24
Latency: 20.14ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
You can combine both filters and get the peers that are both connected and with specific IPs:
```shell
netbird status -d --filter-by-status connected --filter-by-ips 100.119.85.4,100.119.230.104
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
ICE candidate endpoints (Local/Remote): -/-
Last connection update: 35 seconds ago
Last Wireguard handshake: 33 seconds ago
Transfer status (received/sent) 2.4 MiB/532 KiB
Quantum resistance: false
Routes: -
Latency: 16.24ms
OS: linux/amd64
Daemon version: 0.27.4
CLI version: 0.27.4
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
Relays:
[stun:stun.netbird.io:5555] is Available
[turns:turn.netbird.io:443?transport=tcp] is Available
Nameservers:
[8.8.8.8:53, 8.8.4.4:53] for [.] is Available
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected
```
<Note>
The peer with IP `100.119.85.4` wasn't returned because it was not connected
</Note>
### ssh
Command to connect using ssh to a remote peer in your NetBird network.
You should run the ssh command with elevated permissions.
#### Flags
```shell
-p, --port int Sets remote SSH port. Defaults to 44338 (default 44338)
```
#### Arguments
The ssh command accepts one argument, `user@host`; this argument indicates the remote host to connect:
* `user`: indicates the remote user to login
* `host`: indicates the remote peer host IP address
#### Usage
The minimal form of running the command is:
```shell
sudo netbird ssh user@100.119.230.104
```
If you the remote peer agent is running the ssh service on a different port, you can use the `--port` or `-p` flag:
```shell
sudo netbird ssh -p 3434 user@100.119.230.104
```
### version
Outputs the `netbird` command version.
#### Usage
The minimal form of running the command is:
```shell
netbird version
```
This will output:
```shell
0.8.2
```
### service
The service command is a top-level command with subcommands to perform operations related to the daemon service.
You should run the service command with elevated permissions.
### service install
The install installs the daemon service on the system.
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service install
```
You can use the global flags to configure the daemon service. For instance, you can set a debug log level with the flag `--log-level`
```shell
sudo netbird service install --log-level debug
```
You can set a custom configuration path with the flag `--config`
```shell
sudo netbird service install --config /opt/netbird/config.json
```
### service uninstall
The uninstall uninstalls the daemon service from the system.
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service uninstall
```
### service start
Starts the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service start
```
### service stop
Stops the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service stop
```
### debug
The `debug` command provides tools for diagnosing and understanding the internal operations of the NetBird daemon.
#### Usage
To access debugging options:
```shell
netbird debug [command]
```
#### Subcommands
- `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.
#### Flags
```shell
-h, --help help for debug
```
### 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 is only accessible as root/Administrator.
#### Usage
To create a debug bundle:
```shell
netbird debug bundle -A
```
#### Examples
Create a debug bundle:
```shell
netbird debug bundle
```
This will output:
```
/tmp/netbird.debug.676945815.zip
```
#### Flags
```shell
-h, --help help for bundle
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the debug output
```
### debug for
Sets the logging level to trace, runs for the specified duration, and then generates a debug bundle.
This is useful for capturing detailed logs over a period where issues are occurring.
#### Usage
To run debugging for a specific time period:
```shell
netbird debug for <time> -A
```
#### Examples
Run debugging for 5 minutes and generate a debug bundle:
```shell
netbird debug for 5m
```
This will output:
```
Netbird down
Log level set to trace.
Netbird up
Remaining time: 00:00:01
Duration completed
Netbird down
Creating debug bundle...
/tmp/netbird.debug.2180993458.zip
```
#### Flags
```shell
-h, --help help for for
-A, --anonymize anonymize IP addresses and non-netbird.io domains in the debug output
```
### 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.
#### Usage
Adjust the logging level of the NetBird daemon:
```shell
netbird debug log level <level>
```
#### Available Levels
- `panic`: for panic level, the highest level of severity.
- `fatal`: for fatal level errors that cause the program to exit.
- `error`: for error conditions.
- `warn`: for warning conditions.
- `info`: for informational messages.
- `debug`: for debug-level messages.
- `trace`: for trace-level messages, which include more fine-grained information than debug.
#### Examples
Set the logging level to debug:
```shell
netbird debug log level debug
```
This will output:
```
Log level set successfully to debug
```
Reference in New Issue View Git Blame Copy Permalink