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.
# Load all identities in a dir, ignoring files with a .bak or .original filename suffix.
# Set log level, higher is more verbose (default level 3 means INFO).
# Set service polling interval in seconds (default 10).
There are two run modes:
run: transparent proxy with DNS nameserver
run-host: hosting-only without proxy or nameserver
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
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
# 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>
run configure nameservers?
ziti-edge-tunnel run provides a built-in nameserver that will answer queries that exactly match authorized OpenZiti services' intercept domain names and will respond with a hard-fail
NXDOMAIN code if the query does not match an authorized service.
You may enable DNS recursion by specifying an upstream nameserver to answer queries for other domain names that are not services' intercept domain names:
ziti-edge-tunnel run --dns-upstream 126.96.36.199.
ziti-edge-tunnel uses the
libsystemd D-Bus RPC client and will try to configure the OS's resolvers with
systemd-resolved. If that's not possible for any reason then
ziti-edge-tunnel run will fall back to shell commands like
resolvectl fails then
ziti-edge-tunnel run will attempt to modify
/etc/resolv.conf directly to install the built-in nameserver as the primary resolver.
If the DNS record exists it returns the answer and sets query status to
NO_ERROR. If it does not exist then it sends the query to an upstream DNS server if configured. Otherwise, it sets the query status to
REFUSE. This implies that the caller should keep trying to resolve the domain name with other nameservers.
System Requirements for Mode
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_ADMINto the ziti-edge-tunnel process via
AmbientCapabilitiesin the systemd service unit.
systemd-resolvedDNS configuration is permitted by a PolKit rule installed with the RPM or DEB package.
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 tunneller.
System Requirements for Mode
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.