Skip to main content
Star us on GitHub Star

Linux Tunneller

The purpose of the tunneller is to configure host access. This means all users and all processes on the host will share the same level of access. This is accomplished by configuring the OS to have an OpenZiti DNS nameserver and IP routes for authorized services.

Install Linux Package​

Reasons to use the package:

  1. Install the tunneller as a systemd service.
  2. Create permissions and policies for the tunneller to run as a non-root user.
  3. Automatically enroll the identity and clean up the enrollment token in identity directory.
  4. Automatically upgrade the tunneller when a new package is available.

Linux DEB packages are currently available for the x86_64 and arm64 platforms and RPM packages are available for x86_64. ARM/v7 (32bit) binaries are available from GitHub.

Adding Identities​

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

Run with Docker​

Reference the article about running the Linux tunneller in a container for guidance and examples.

Install a Pre-Release​

DEB Pre-Release​

Pre-release repo for Debian-based distros

You may use the following script to install the pre-release version of the tunneller for any supported Ubuntu LTS.

UBUNTU_LTS=focal;

curl -sSLf https://get.openziti.io/tun/package-repos.gpg \
| sudo gpg --dearmor --output /usr/share/keyrings/openziti.gpg;
sudo chmod +r /usr/share/keyrings/openziti.gpg;

sudo tee /etc/apt/sources.list.d/ziti-edge-tunnel-testing.list >/dev/null <<EOF;
deb [signed-by=/usr/share/keyrings/openziti.gpg] https://packages.openziti.org/zitipax-openziti-deb-test ${UBUNTU_LTS} main
EOF

sudo apt update;
sudo apt install ziti-edge-tunnel;
ziti-edge-tunnel version;

RPM Pre-Release​

Pre-release repo for RedHat-based distros
sudo tee /etc/yum.repos.d/ziti-edge-tunnel-testing.repo >/dev/null <<\EOF;
[OpenZitiTunnelTesting]
name=OpenZiti Tunnel Testing
baseurl=https://packages.openziti.org/zitipax-openziti-rpm-test/redhat$releasever/$basearch
enabled=1
gpgcheck=0
gpgkey=https://packages.openziti.org/zitipax-openziti-rpm-test/redhat$releasever/$basearch/repodata/repomd.xml.key
repo_gpgcheck=1
EOF

sudo dnf update;
sudo dnf install ziti-edge-tunnel;
ziti-edge-tunnel version;

Troubleshooting​

Refer to the troubleshooting guide