Options and Modes

ziti-edge-tunnel Environment Variables

ZITI_TIME_FORMAT=utc - set the log message time format to UTC timestamp instead of milliseconds since start

ZITI_LOG=4 - set the log level of the underlying Ziti C SDK, higher is more verbose (level 4 means DEBUG)

TLSUV_DEBUG=4 - set the log level of the underlying libuv library, higher is more verbose (level 4 means DEBUG)

For more information about configuring the underlying Ziti C SDK with environment variables, see the Ziti C SDK documentation.

ziti-edge-tunnel Global Options

You can start ziti-edge-tunnel with different options, some of the most commonly used options are listed below.

# Load a single identity.
--identity <identity>

# Load all identities in a dir, ignoring files with a .bak or .original filename suffix.
--identity-dir <dir>

# Set log level, higher is more verbose (default level 3 means INFO).
--verbose N

# Set service polling interval in seconds (default 10).
--refresh N

Run Modes

There are two run modes:

• run: transparent proxy with DNS nameserver
• run-host: hosting-only without proxy or nameserver

run Mode

ziti-edge-tunnel run provides a transparent proxy and nameserver. The nameserver may be configured to be authoritative (the default) or recursive with command-line option --dns-upstream. systemd-resolved, if enabled, automatically configures the Ziti nameserver. You may inspect the configuration with these commands.

resolvectl dns     # inspect the association of tun device and nameserver
resolvectl domain  # inspect the configuration of query routing domains

If any interface has a wildcard routing domain configured, ziti-edge-tunnel will also configure its tun with a wildcard routing domain. If no other interface has a wildcard routing domain configured, neither will the ziti-edge-tunnel tun.

# Specify the tun interface address and the subnet to which Service domain names are resolved (default 100.64.0.1/10). The nameserver address is always the tun interface address +1, default is 100.64.0.2.
--dns-ip-range <ip range>

How does run configure nameservers?

ziti-edge-tunnel run provides a built-in nameserver for the services it is authorized to dial. The nameserver is automatically configured by systemd-resolved, if enabled.

If systemd-resolved is not enabled, you must configure your resolver to query the tunneler's nameserver. Add Ziti's nameserver to the connection manager, e.g., NetworkManager, Netplan, or by directly editing /etc/resolv.conf.

You may configure the system resolver to use the tunneler's nameserver as the first or only nameserver.

When the tunneler nameserver is the first of multiple nameservers and the requested DNS record does not match an authorized service's intercept domain name, it sets the query status to REFUSE. This implies that the caller should keep trying to resolve the domain name with other nameservers.

To use the tunneler nameserver as the only nameserver, you must specify an upstream nameserver for recursion: ziti-edge-tunnel run --dns-upstream 208.67.222.222. In this configuration, the query status from the upstream nameserver is returned, e.g., NXDOMAIN if the domain name is not found in the tunneler nameserver or the upstream nameserver.

The IP address of the nameserver (default: 100.64.0.2) is determined by the tunneler's dns-ip-range (default: 100.64.0.1/10).

System Requirements for Mode run

ziti-edge-tunnel run requires Linux capabilities for managing the /dev/net/tun device, running resolvectl to assign nameservers and domain routes to the tun interface, and running ip route to manage IP routes.

• tun device and route management are permitted by passing the CAP_NET_ADMIN to the ziti-edge-tunnel process via AmbientCapabilities in the systemd service unit.
• systemd-resolved DNS configuration is permitted by a PolKit rule installed with the RPM or DEB package.

run-host Mode

ziti-edge-tunnel run-host is a mode for hosting (listening) for services which does provide service intercepts or DNS. Services configured for 'Bind' will be hosted by the tunneler.

System Requirements for Mode run-host

ziti-edge-tunnel run-host does not require elevated privileges or the above device or socket, only network egress to the servers for which it is hosting Services.