Instruction for Tunneler usage

Ziti Overlay
1

Hi, this link tells me how to install a Tunneler (Tunnelers | OpenZiti). But I cannot find relevant instruction of how to use it after the installation.

  1. How does a tunneler register and enroll to Ziti network?
  2. How does an application/client made aware of the tunneler and use it?

Thanks.

2

Hi @Joe,

Each of the tunnelers is different. ziti-edge-tunnel will show you usage info if you execute it, but basically you just supply an identity file, or a directory where you'll put identities and then start it up. For example:

ziti-edge-tunnel run: run Ziti tunnel (required superuser access)
usage: ziti-edge-tunnel run -i <id.file> [-r N] [-v N] [-d|--dns-ip-range N.N.N.N/n]

        -i|--identity <identity>        run with provided identity file (required)
        -I|--identity-dir <dir> load identities from provided directory
        -v|--verbose N  set log level, higher level -- more verbose (default 3)
        -r|--refresh N  set service polling interval in seconds (default 10)
        -d|--dns-ip-range <ip range>    specify CIDR block in which service DNS names are assigned in N.N.N.N/n format (default 100.64.0.1/10)

You'd run it with something like: sudo ./ziti-edge-tunnel run -i ./zsshSvcServer.json

If you are using a Mac or Windows client, there are "add identity" buttons for both of those:

image
image1304×744 131 KB

The client is instructed by the overlay network itself (via the controller) that it has a service, it's configured for intercepting etc.

I could make a short video showing all that together if you want, and if these screen caps aren't enough for you. You're right, we don't really have a 'how to' guide for this yet, but I can see it being valuable.

If you want a quick video giving a demonstration let me know and I'll make one (I might just make it anyway, if I don't hear back, and I end up making one, I'll post back)

3

Hi @Joe. When I read your second question I took “application/client” to mean the tcp/ip application that is ultimately initiating the connection and being proxied over the Ziti network. If that take is correct, then I’d say your question gets right to the magic of what the tunnelers do. The short answer is that the tcp/ip application is unaware that its outbound connections are being intercepted by the tunneler and then proxied over a Ziti overlay.

Basically the tunneler creates routes and DNS mappings for the IPs and hostnames that are specified in your Ziti service configurations. Depending on the operating system, the tunneler either creates a virtual network interface (called a tun interface) or a special listening socket that can have specific destination addresses diverted to it (via iptables tproxy rules).

The tun and tproxy intercept methods are explained in slightly more detail at ziti/ziti-tunnel at release-next · openziti/ziti · GitHub. Note that this document specifically relates to the older golang-based ziti-tunnel tunneler (which is currently deprecated), but the tun and tproxy overviews are still mostly worthwhile their own.

So connections to IPs are intercepted transparently (that is, without the knowledge of the initiating application) via tun or tproxy. To intercept connections to hostnames, tunnelers run an internal DNS server that maps hostnames in the ziti service configurations to IP addresses that are routed to the tun interface or tproxy listener.

If my mentions of “service configurations” are a little vague, my colleague Geoff wrote a few “how-to” style bogs that show how the service configurations are made (among other things).

Thanks for the question, and please let me know if this answer doesn’t give you what you’re looking for!