Tunneling on Debian GNU/Linux

Installing the Debian Package

1. Select an OS to see the appropriate steps.

Ubuntu

Ubuntu

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

Debian GNU/Linux

Debian GNU/Linux

Debian	UBUNTU_LTS	Archs
13 Trixie	jammy	x86_64, arm64
12 Bookworm	jammy	x86_64, arm64
11 Bullseye	focal	x86_64, arm64
10 Buster	bionic	x86_64
9 Stretch	xenial	x86_64

1. Refer to the table to find the Ubuntu release name that is the contemporary of the Debian release. Substitute the Ubuntu release name for jammy in the /etc/apt/sources.list.d/openziti.list file.

   UBUNTU_LTS=jammy

2. Subscribe the system to the OpenZiti package repository for the UBUNTU_LTS specified above.

   echo "deb [signed-by=/usr/share/keyrings/openziti.gpg] https://packages.openziti.org/zitipax-openziti-deb-stable $UBUNTU_LTS main" \
   | sudo tee /etc/apt/sources.list.d/openziti.list >/dev/null

3. Install the package signing pubkey.

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

4. Ensure the pubkey is readable by all.

   sudo chmod -c +r /usr/share/keyrings/openziti.gpg

5. Refresh the package list and install ziti-edge-tunnel.

   sudo apt update
   sudo apt install ziti-edge-tunnel

2. Enable and start the service

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

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

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