Skip to main content
Star us on GitHub Star

Linux Tunneler

The purpose of the tunneler 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 OpenZiti Services.

Install Linux Package​

Reasons to use the package:

  1. Install the tunneler as a systemd service.
  2. Create permissions and policies for the tunneler 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 tunneler 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. See manual installation.

Installing the DEB​

  1. Select an OS to see the appropriate steps.

Ubuntu​

Packages are available for all Ubuntu releases since 18.04 (Bionic).


Architectures available:

  • x86_64
  • arm64
note

Please read this script to ensure it is safe before running it.

curl -sSLf https://get.openziti.io/tun/scripts/install-ubuntu.bash | bash

  1. Enable and start the service

    sudo systemctl enable --now ziti-edge-tunnel.service

  2. Add an Identity

Installing the RPM​

  1. Create a repo file like /etc/yum.repos.d/openziti.repo matching the OS.

Red Hat​

Architectures available:

  • x86_64

Use this repo with var $releasever on CentOS 7, Rocky 8-9, and RHEL 7-9.

[OpenZiti]
name=OpenZiti
baseurl=https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat$releasever/$basearch
enabled=1
gpgcheck=0
gpgkey=https://packages.openziti.org/zitipax-openziti-rpm-stable/redhat$releasever/$basearch/repodata/repomd.xml.key
repo_gpgcheck=1

  1. Run sudo yum update to refresh the repo data cache.

  2. Run sudo yum install ziti-edge-tunnel to install the RPM.

  3. Enable and start the service

    sudo systemctl enable --now ziti-edge-tunnel.service

  4. Add an Identity

Manual Installation​

The latest binary release of ziti-edge-tunnel is distributed as an executable for amd64, arm, and arm64 architectures. To upgrade the tunneler perform the installation procedure again.

Install the wget and unzip commands to use this example.

(set -euo pipefail
cd $(mktemp -d)
wget -q \
  "https://github.com/openziti/ziti-tunnel-sdk-c/releases/latest/download/ziti-edge-tunnel-Linux_$(uname -m).zip"
unzip ./ziti-edge-tunnel-Linux_$(uname -m).zip
sudo install -o root -g root ./ziti-edge-tunnel /usr/local/bin/
grep -q '^ziti:' /etc/group || sudo groupadd --system ziti
sudo mkdir -pv /opt/openziti/etc/identities
ziti-edge-tunnel version
)

Run the Manually Installed Binary​

You must run the manually-installed tunneler as root because only the Linux package configures systemd ambient capabilities that enable managing DNS and IP routes with reduced privileges.

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

Learn more about tunneler options and modes.

Adding Identities​

The tunneler 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 tunneler 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 tunneler 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 tunneler 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 tunneler 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 tunneler for any supported Ubuntu LTS.

(set -euo pipefail;
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;
/opt/openziti/bin/ziti-edge-tunnel version;
)

RPM Pre-Release​

Pre-release repo for RedHat-based distros
(set -euo pipefail;

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;
/opt/openziti/bin/ziti-edge-tunnel version;
)

Troubleshooting​

Refer to the troubleshooting guide.