How to Install & run ziti-edge-tunnel on Linux


ziti-edge-tunnel is a CLI and daemon that configures a transparent proxy for the OpenZiti Edge. This means the device where it is running will be able to connect to any OpenZiti services with DNS or IP address, and any servers that are reachable by the device may be published to the OpenZiti Network.

This is most useful when it is impossible to embed the OpenZiti Edge SDK directly into an application, and so a proxy is necessary to tether non-Ziti apps to the OpenZiti Network as clients or servers or both. It is a best practice to bring the OpenZiti 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 OpenZiti's encryption when it leaves the device on the wire.

An alternative way to run a Linux tunneler is with Docker. The remainder of this article will be about running a Linux tunneler without Docker.

Run Modes

Transparent Proxy Mode "run"

Subcommand ziti-edge-tunnel runmust be run as root and expects access to /dev/net/tun and /var/run/dbus/system_bus_socket in order to configure the transparent proxy tunneling interface and systemd-resolved nameserver, respectively.

Service Hosting Mode "run-host"

Subcommand ziti-edge-tunnel run-host requires no special privileges and provides a bind point for services. This is a hosting-only mode that does not provide a proxy or nameserver to the host where it's running, but you may assign any services for which the server addresses are reachable by the host.

Package Installation and Upgrade

You may install ziti-edge-tunnel in transparent proxy mode running as a systemd service with a Linux package manager like yum or apt. Please reference the package installation instructions.

Binary Installation

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

You may manually install the ziti-edge-tunnel binary by downloading the build for your platform. Please reference the binary installation instructions in the OpenZiti documentation.

Binary Upgrade

The upgrade procedure for theziti-edge-tunnel binary is identical to the installation procedure.

Enrollment for Binary Installation

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

For more guidance, please reference the enrollment instructions in the OpenZiti documentation.

Run the Binary

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

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

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

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

Check status

./ziti-edge-tunnel tunnel_status


The log collection guide for ziti-edge-tunnel can be found here.

Please reference the troubleshooting section of the Linux tunneler article in the OpenZiti documentation.

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.



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



Article is closed for comments.