How to Install & run the Ziti-edge-tunnel for Linux


ziti-edge-tunnel is a CLI and privileged daemon that configures a bi-directional edge for a Ziti network. This means the device where it is running will be able to connect to any Ziti services by Ziti domain name or Ziti IP address, and other endpoints on the same Ziti network will be able to connect to any normal domain name or IP address that is reachable by this device.

This is especially useful when it is impossible to embed the OpenZiti Edge SDK in an application, 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 application. For example, by running ziti-edge-tunnel on the same device as the client or server application. That way, the exposure of packets is limited to that same device and is protected by Ziti when it leaves the device on the wire.

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.


Note: This guide is written considering ubuntu 20.4 as the base. The config steps may vary for different Linux environments. 


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


Note: Make sure that the GLIBC is on version 2.25 or higher on your Linux OS



The upgrade procedure forziti-edge-tunnel is identical to the install procedure.


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} | grep 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


What about ziti-tunnel?

ziti-tunnel was the first tunneler software and lacks the newest features of the preferred Linux tunneler. The most important distinction is that ziti-edge-tunnel shares a common library with Ziti Desktop Edge for MacOS and Windows, and so this common ancestry of features and fixes will ensure the best possible support for all tunneler apps.


The Log collection guide for Linux Ziti-Edge-Tunnel can be found here.



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



Article is closed for comments.