Linux tunneler help

[qrkourier]

Some notes that we could fold-in to https://openziti.github.io/ziti/clients/tunneler.html#linux

ziti-edge-tunnel

• C-SDK tunneler aka "tunneler SDK"
• a bit more advanced and less user-friendly than ziti-tunnel but has a superior approach to built-in DNS
• is more performant than ziti-tunnel
• run mode uses tun device IP routes to intercept service traffic and answer DNS via resolvectl
• Future development will probably land first in the tunneler SDK
• Experimental Docker container exists: netfoundry/ziti-edge-tunnel
• systemd install

# transparent install procedure for ziti-edge-tunnel

# where to install the executable binary
❯ ZITI_EDGE_TUNNEL_BIN_DIR=/usr/local/bin

# where to look at startup for enrolled identity JSON config files
❯ ZITI_EDGE_TUNNEL_ID_DIR=~/.ziti-edge-tunnel

# create the identity directory
❯ mkdir -pvm0700 $ZITI_EDGE_TUNNEL_ID_DIR

# create a systemd service
❯ cat <<ZITI_SERVICE | sudo tee /usr/lib/systemd/system/ziti-edge-tunnel.service                
[Unit]
Description=Ziti Edge Tunnel
After=network.target
ConditionDirectoryNotEmpty=$ZITI_EDGE_TUNNEL_ID_DIR

[Service]
User=root
ExecStart=${ZITI_EDGE_TUNNEL_BIN_DIR}/ziti-edge-tunnel run --verbose 4 --identity-dir $ZITI_EDGE_TUNNEL_ID_DIR
Restart=always
RestartSec=2
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
ZITI_SERVICE

# load the new systemd config
❯ sudo systemctl daemon-reload

# download some version of ziti-edge-tunnel
❯ curl -sSLf https://raw.githubusercontent.com/openziti/ziti-tunnel-sdk-c/main/docker/fetch-github-releases.sh | ZITI_VERSION=0.17.7 bash -x /dev/stdin ziti-edge-tunnel

# install in a directory that is in the executable search PATH
❯ sudo mv -v ./ziti-edge-tunnel ${ZITI_EDGE_TUNNEL_BIN_DIR}/

# verify the installed version
❯ sudo ziti-edge-tunnel version

# use a downloaded enrollment token to generate an identity
❯ sudo ziti-edge-tunnel enroll --jwt ~/Downloads/linuxTunneler1.jwt --identity ${ZITI_EDGE_TUNNEL_ID_DIR}/linuxTunneler1.json

# start the daemon
❯ sudo systemctl start ziti-edge-tunnel.service

# view the logs
❯ sudo journalctl -lfu ziti-edge-tunnel.service

ziti-tunnel

• the first Linux tunneler
• Go-SDK tunneler
• has useful modes proxy and host in addition to tproxy (IPtables intercepts)
• works fairly well today in Docker: netfoundry/ziti-tunnel

[sabedevops]

Consider adding some sanity checks to the systemd unit file like ConditionDirectoryNotEmpty

Additionally, should we be steering users to the XDG Base Directory Specification?

[qrkourier]

@sabedevops Good stuff. I added that unit conditional and XDG_DATA_HOME looks like something we should use with the (eventual) install package for this service unit, unless you see a specific way we could apply it in this manual install procedure.

[sabedevops]

For the purposes of this script, this can be done generically like this:

[ ! -z "$XDG_DATA_HOME" ] && ZITI_EDGE_TUNNEL_ID_DIR="$XDG_DATA_HOME/ziti-edge-tunnel" || ZITI_EDGE_TUNNEL_ID="$HOME/.ziti-edge-tunnel"

This may not align with current documentation and user expectations, so it may be worth ignoring at this time.

Also, please be advised the approach in this script is not bulletproof, since things like Kerberized NFS homedirs with root squashing will cause the service to fail due to permissions. Nonetheless, it's a great start @qrkourier

[qrkourier]

@dovholuknf Based on today's conversation about the older and newer Linux tunnelers we should refactor this document to position the preferred tunneler as such, and document the dwindling-few unique capabilities of the non-preferred tunneler ziti-tunnel. You may assign this issue to me. :+1: