Ziti-tunnel proxy vs tproxy vs host configurations

I would like to validate my understanding of the differences between the ziti-tunnel proxy vs tproxy vs host configurations.

Questions that I have are

  • what is different between the proxy and tproxy configurations
  • what specific situations do you want to use a host

Please correct any of the following that is wrong… this will be very helpful

ziti-tunnel proxy mode

used to access a zitified service accessible over the ziti network

postgres db example:
ziti-tunnel proxy -i /mnt/v/temp/tunneler-id.json private-postgres:5432 -v

taken from postgres demo
ziti-sdk-jvm/samples/jdbc-postgres at main · openziti/ziti-sdk-jvm · GitHub

ziti-tunnel tproxy mode

used to access a zitified private DNS accessible over the ziti network

guess on how to use
ziti-tunnel tproxy -i /mnt/v/temp/tunneler-id.json private-dns-name:5432

ziti-tunnel host mode

used to host a zitified service accessible over the ziti network

guess on how to use:
ziti-tunnel host -i /mnt/v/temp/tunneler-id.json

Update release notes. Add support for ziti-tunnel host. Add support f… by plorenz · Pull Request #262 · openziti/ziti · GitHub

Hi @markamind! Good question. Keep in mind that tproxy and host run modes of ziti-tunnel are deprecated by ziti-ege-tunnel, and so you should use ZET unless you have a particular reason for using the deprecated tunneler CLI. For example, if you need the proxy mode or if you’re modifying it in order to take advantage of Go language bindings to add some new capability.


  • ziti-tunnel proxy provides a raw TCP proxy for the named service that is listening on the specified loopback TCP port and does not provide a DNS nameserver. This is an “opaque” proxy because the application must be “aware” of the particular proxy address and port in order to connect. For example, the client application can not naively connect to the hosted service, but must instead connect to TCP://localhost:5432 in order to communicate with the server that is published as Ziti service “private-postgres”.

  • ziti-tunnel tproxy is the “transparent” counterpart to proxy. This run mode provides a DNS nameserver and IPtables rules and IP routes in the OS so that client apps may connect to Ziti services transparently, naively, without being aware of the proxy at all. This mode is deprecated by ziti-edge-tunnel run.

  • ziti-tunnel host merely hosts services without providing any proxy for intercepting IP traffic, and does not provide a nameserver. This mode is deprecated by ziti-edge-tunnel run-host.

Thanks for that… its very helpful… and brings me up to speed.

Just to clarify… when I do a getLatest command… it does not bring down a copy of ziti-edge-tunnel… only ziti-tunnel

That being the case… what is the best way to get a local copy of ziti-edge-tunnel to distribute across the fabric.

Any tips?

Get latest is just a script that uses curl to grab the latest zip file/tgz and unpack the archive in a place. You can look at the source to see how it’s doing things.

You can just download the tunneler for your operating system at Releases · openziti/ziti-tunnel-sdk-c · GitHub

Usually this is for Linux OS, because there’s a store app from MacOS/iOS and an installer for Windows.

I’m thinking the old videos, before we moved to ziti-edge-tunnel should be redone.

You can check out another one I did recently too which uses ziti-router

This is an example shortcut download link that always points to the latest release for the AMD64 / x86_64 build for Linux.


Does the proxy mode still exist? ziti-edge-tunnel help does only show run and run-host mode.

I like to run a sidecar container without priveleged access rights and therefore I like to use the tcp proxy mode.

I see the openziti/ziti-tunnel image but I miss a description in the comtainer documentation Containers | OpenZiti

Hi @Metz, yes. The ziti tunnel proxy command still exists. When you say "sidecar," are you referring to a K8S pod or more generically, e.g., a Compose service?

today I'm still using docker-compose. But plan in future to move to k0s or k3s.
Is there an docker image available for the ziti-tunnel with proxy mode?

For this use case, you want the openziti/ziti-tunnel image because its entrypoint.sh has helpful functionality for enrollment. The image is produced from this Dockerfile whenever ziti is released. It's a thin veneer over the minimal ziti-cli image which itself merely provides the ziti executable.

You can provide any ziti tunnel sub-command as an arg to the openziti/ziti-tunnel image, i.e., proxy, tproxy, or host.

The proxy sub-command fits your use case because it does not require elevated privileges. However, this does introduce a bit of fragility because you must continually ensure the client proxy's bound services and ports are aligned with the dialing application.

Here's an excerpt from the K8S sidecar example that illustrates the env vars and paths you must configure for this container image. You can adapt this to use your desired sub-command instead of tproxy, and remove the additional capability NET_ADMIN since it's not necessary for proxy.

        - image: openziti/ziti-tunnel
          name: ziti-tunnel
          args: ["tproxy"]
          - name: ZITI_IDENTITY_BASENAME
            value: sidecar-client  # the filename in the volume is sidecar-client.json
          - name: sidecar-client-identity
            mountPath: /netfoundry
            readOnly: true
              - NET_ADMIN

You could use the same solution when you migrate to K8S, but there's not yet a Helm chart focused on this use case. There is, however, an established pattern for doing this with the openziti/ziti-router chart, which has the ziti tunnel features on-board when the router is created with tunnel mode enabled. Convenient, right?

I haven't mentioned this use case for the router yet in the K8S workload tunneling overview (I'll take an action to add that), but there's a section in the router chart's README about using proxy mode as a cluster service, optionally with Ingress.

1 Like