How to Use the Linux Tunneler


ziti-edge-tunnel is a CLI that configures a bi-directional edge for a Ziti network. This is useful when it is impossible to Zitify the client or server applications and so a proxy is necessary to tether non-Ziti apps to the Ziti network as clients or servers or both. It is a best practice to bring the Ziti Edge as close as possible to the client or server application. For example, by running `ziti-edge-tunnel` on the same device as the client or server application. That way, the exposure of IP traffic is limited to that same device and is protected by Ziti when it leaves the device.

The easiest way to manage a Linux tunneler is with a Dockerized tunneler. The remainder of this article will be about running a Linux tunneler without the benefits of stored configuration and process management that Docker provides.


ziti-edge-tunnel requires elevated privileges and systemd-resolved to manage tundevices, IP routes, and the device's DNS resolver configuration.


Your network dashboard links to the best downloads for your network (secondary link). 


You will download a zip file for your CPU architecture, e.g. and inflate in the directory where it will be executed. You will need to ensure the downloaded file has the execute permission bit set.

chmod +x ./ziti-edge-tunnel


Create an endpoint in the NetFoundry web console and save the JWT file for the enrollment step. Here's the general article about endpoints as a reference. Then, enroll the endpoint identity you downloaded from the web console. The permanent identity JSON file will be created at the path specified as a JSON file.

./ziti-edge-tunnel enroll --jwt myTunneler.jwt --identity myTunneler.json


Run the transparent intercepting proxy (tun device) with built-in nameserver.

sudo ./ziti-edge-tunnel run --identity myTunneler.json

The device's local DNS resolver configuration will be updated by resolvctl and outgoing IP packets that matche a service by domain name or destination IP address will be "intercepted" i.e. securely re-directed to the Ziti Edge instead of the normal IP underlay, the internet.

Multiple Identities

You may instead run ziti-edge-tunnel with all enrolled identities in a directory loaded at startup. Newly-added identities are not loaded, and so a restart is necessary.

sudo ./ziti-edge-tunnel run --identity-dir ./myTunnelers/

Troubleshooting DNS

ziti-edge-tunnel configures localhost DNS automatically with resolvctl. In case you had previously configured DNS manually for an earlier version of Linux tunneler, then you may need to restore the default localhost DNS configuration for systemd-resolved.

Most Linux distributions provide a symbolic link for the C-lib resolver /etc/resolv.conf to systemd-resolved stub resolver. This allows systemd-resolved to handle DNS queries according to its configuration. The default symlink looks like this.

$ ls -l /etc/resolv.conf
lrwxrwxrwx 1 root root 37 Mar 1 11:15 /etc/resolv.conf -> /run/systemd/resolve/stub-resolv.conf

If this file /etc/resolv.conf is not a symbolic link then you may wish to revert to the default symlink with this command:

sudo ln -sfvn /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf 

Another possible cause of DNS trouble is that NetworkManager's running configuration or saved connections or both may have been customized to accomodate an earlier version of the Linux tunneler. These customizations may override systemd-resolved stub resolver. You may investigate whether NetworkManager's built-in dnsmasq server is enabled with this command.

$ egrep dnsmasq /etc/NetworkManager/NetworkManager.conf

In case dnsmasq is enabled as shown then the include configs in the following directory are effective.

ls -l /etc/NetworkManager/dnsmasq.d/

Inspect your NetworkManager saved connections for customizations with nmcli.

$ nmcli connection show ${CONNECTION} | egrep dns 
connection.mdns: -1 (default)
ipv4.dns: --
ipv4.dns-search: --
ipv4.dns-options: --
ipv4.dns-priority: 0
ipv4.ignore-auto-dns: no
ipv6.dns: --
ipv6.dns-search: --
ipv6.dns-options: --
ipv6.dns-priority: 0
ipv6.ignore-auto-dns: no



Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.