Netzilo Agent command line interface (CLI)

The Netzilo client installation adds a binary called netzilo 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 netzilo.

Syntax

Use the following syntax to run netzilo commands from your terminal window:

netzilo [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

To see detailed command information, use the flag --help after each command

Global flags

netzilo 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:

      --admin-url string        Admin Panel URL [http|https]://[host]:[port] (default "https://app.netzilo.com")
  -A, --anonymize               anonymize IP addresses and non-netzilo.com domains in logs and status output
  -c, --config string           netzilo config file location (default "/etc/netzilo/config.json")
      --daemon-addr string      Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netzilo.sock")
      --log-file string         sets Netzilo log path. If console is specified the the log will be output to stdout (default "/var/log/netzilo/client.log")
  -l, --log-level string        sets Netzilo log level (default "info")
  -m, --management-url string   Management Service URL [http|https]://[host]:[port] (default "https://app.netzilo.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 netzilo 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:

export NB_CONFIG="/opt/netzilo/config.json"
export NB_MANAGEMENT_URL="https://api.self-hosted.com:33073"
netzilo up

The up command would process the variables, read the configuration file on /opt/netzilo/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 Netzilo 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

      --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 Netzilo'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:

netzilo up

If you are running on a self-hosted environment, you can pass your management url by running the following:

netzilo 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:

sudo netzilo up --log-file console

On Windows, you may need to run the command from an elevated terminal session.

In case you need to use a setup key, use the --setup-key flag :

netzilo up --setup-key AAAA-BBB-CCC-DDDDDD

Command to authenticate the Netzilo 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:

netzilo login

If you are running on a self-hosted environment, you can pass your management url by running the following:

netzilo login --management-url https://api.self-hosted.com:33073

In case you need to use a setup key, use the --setup-key flag:

netzilo login --setup-key AAAA-BBB-CCC-DDDDDD

Passing a management url and a setup key:

netzilo 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 Netzilo network. After running this command, the daemon service will enter an Idle state.

Usage

The minimal form of running the command is:

netzilo down

status

Retrieves the peer status from the daemon service.

Flags

  -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.netzilo.network
      --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-netzilo.com domains in the status output
  -h, --help                      help for status
      --ipv4                      display only Netzilo 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:

netzilo status

This will output:

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
Netzilo 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:

netzilo status -d

This will output:

Peers detail:
 Peer:
  Netzilo 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:
  Netzilo 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:
  Netzilo 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.netzilo.com:33073
Signal:  Connected to https://signal2.wiretrustee.com:10000
Relays:
  [stun:stun.netzilo.com:5555] is Available
  [turns:turn.netzilo.com:443?transport=tcp] is Available
Nameservers:
  [8.8.8.8:53, 8.8.4.4:53] for [.] is Available
Netzilo 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:

netzilo status -d --filter-by-status connected

This will output:

Peers detail:
 Peer:
  Netzilo 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:
  Netzilo 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.netzilo.com:33073
Signal:  Connected to https://signal2.wiretrustee.com:10000
Relays:
  [stun:stun.netzilo.com:5555] is Available
  [turns:turn.netzilo.com:443?transport=tcp] is Available
Nameservers:
  [8.8.8.8:53, 8.8.4.4:53] for [.] is Available
Netzilo 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:

netzilo status -d --filter-by-ips 100.119.201.225

This will output:

Peers detail:
 Peer:
  Netzilo 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.netzilo.com:33073
Signal:  Connected to https://signal2.wiretrustee.com:10000
Relays:
  [stun:stun.netzilo.com:5555] is Available
  [turns:turn.netzilo.com:443?transport=tcp] is Available
Nameservers:
  [8.8.8.8:53, 8.8.4.4:53] for [.] is Available
Netzilo 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:

netzilo status -d --filter-by-status connected --filter-by-ips 100.119.85.4,100.119.230.104

This will output:

Peers detail:

 Peer:
  Netzilo 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.netzilo.com:33073
Signal:  Connected to https://signal2.wiretrustee.com:10000
Relays:
  [stun:stun.netzilo.com:5555] is Available
  [turns:turn.netzilo.com:443?transport=tcp] is Available
Nameservers:
  [8.8.8.8:53, 8.8.4.4:53] for [.] is Available
Netzilo IP: 100.119.62.6/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 2/3 Connected

The peer with IP 100.119.85.4 wasn't returned because it was not connected

ssh

Command to connect using ssh to a remote peer in your Netzilo network.

You should run the ssh command with elevated permissions.

Flags

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

sudo netzilo ssh [email protected]

If you the remote peer agent is running the ssh service on a different port, you can use the --port or -p flag:

sudo netzilo ssh -p 3434 [email protected]

version

Outputs the netzilo command version.

Usage

The minimal form of running the command is:

netzilo version

This will output:

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:

sudo netzilo 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

sudo netzilo service install --log-level debug

You can set a custom configuration path with the flag --config

sudo netzilo service install --config /opt/netzilo/config.json

service uninstall

The uninstall uninstalls the daemon service from the system.

Usage

The minimal form of running the command is:

sudo netzilo service uninstall

service start

Starts the daemon service

Usage

The minimal form of running the command is:

sudo netzilo service start

service stop

Stops the daemon service

Usage

The minimal form of running the command is:

sudo netzilo service stop

debug

The debug command provides tools for diagnosing and understanding the internal operations of the Netzilo daemon.

Usage

To access debugging options:

netzilo 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 Netzilo daemon.

Flags

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

netzilo debug bundle -A

Examples

Create a debug bundle:

netzilo debug bundle

This will output:

/tmp/netzilo.debug.676945815.zip

Flags

  -h, --help        help for bundle
  -A, --anonymize   anonymize IP addresses and non-netzilo.com 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:

netzilo debug for <time> -A

Examples

Run debugging for 5 minutes and generate a debug bundle:

netzilo debug for 5m

This will output:

netzilo down
Log level set to trace.
netzilo up
Remaining time: 00:00:01
Duration completed
netzilo down
Creating debug bundle...
/tmp/netzilo.debug.2180993458.zip

Flags

  -h, --help       help for for
  -A, --anonymize  anonymize IP addresses and non-netzilo.com domains in the debug output

debug log

This subcommand manages the logging level for the Netzilo 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 Netzilo daemon:

netzilo 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:

netzilo debug log level debug

This will output:

Log level set successfully to debug