Manual Installation

The latest stable release of ziti-edge-tunnel is distributed as an executable binary in GitHub.

1. Unzip the downloaded file and copy the binary to a directory in your PATH, such as /usr/local/bin.

   sudo install -o root -g root ./ziti-edge-tunnel /usr/local/bin/

2. Create a POSIX group named ziti if it doesn't already exist. Members of this group can access the identity files and send IPC commands to the socket server.

   sudo groupadd --system ziti

3. Create a directory to hold the identity files. The tunneler will manage the contents of the identity directory.

   sudo mkdir -pv /opt/openziti/etc/identities

4. Run the Manually Installed Binary

   When not using the Linux package, you must run the tunneler as root so it will have permission to manage IP routes and the resolver configuration.

   sudo ziti-edge-tunnel run --identity-dir /opt/openziti/etc/identities

5. Add an Identity

   The tunneller can run with zero or more identities loaded, and needs at least one to make OpenZiti services available on the host. Adding an identity means providing a JWT enrollment token which is used by the tunneller to obtain a client certificate from the OpenZiti controller. Learn more about OpenZiti Identities.

   Add a Single Identity

   Root and members of group ziti may add an identity without restarting.

   sudo ziti-edge-tunnel add --jwt "$(< ./in-file.jwt)" --identity myIdentityName

   Learn more about enrolling.

   Load Identities Directory

   The tunneller will load all enrolled identities in the --identity-dir directory at startup. The default location for identities is is /opt/openziti/etc/identities. Add enrolled identity files to this directory by copying the JSON file into the directory and setting permissions for group ziti.

   note

   Linux package users may place enrollment tokens named *.jwt in this directory for automatic enrollment at next startup.

   Ensure the identities directory is writable by group ziti and not readable by others to protect the confidentiality of the identities.

   sudo chown -cR :ziti        /opt/openziti/etc/identities
   sudo chmod -cR ug=rwX,o-rwx /opt/openziti/etc/identities

   The tunneller process needs to be restarted if the contents of /opt/openziti/etc/identities change.

   # package users can restart with systemd
   sudo systemctl restart ziti-edge-tunnel.service

6. Configure the Resolver

   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).