Unclear example documentation

[hagr]

I'm having difficulties understanding the variables used in your example. It seems you're using a script to launch the client? What I'm missing is the argument, or environment variable, to pass on to create the SSH tunnel to the server. I found some regex in sshd.sh which would have something along the lines of:

-e SSH_TUNNEL_REMOTE=remoteaddr:remoteport

In addition, I'd like the client configuration variable names to be consistent with those of the server's (memcahce, redis, posgresql vs service1, service2 ,service3).

I'd be happy to give you a pull request with updated docs if I just manage to grasp the concept and configuration of the client and server. :-)

[marclennox]

Thanks so much for your offer to help, I would definitely be open to a PR!

I agree the documentation is not complete enough, so for sure would love to get some help on this. I've been using this ambassador image on several machines quite successfully for the past 9 months.

Let me try to demystify the environment variables. My goal for this docker was to avoid a configuration file and use environment variables for all configuration, in a simple and understandable format. I also wanted to allow for both simple and encrypted tunnels.

The docker image can be run in two modes, client and server. For simple TCP tunnels with socat, you don't need the server running on the other end, you simply use environment variables like the following to define your port forwarding rules:

-e TCP_TUNNEL_<NAME>_<PORT>=<remote_host>:<remote_port>

For encrypted tunnels, you run the client on one end, and optionally the server on the other. Note that you don't actually need the server, you can turn gateway ports to "on" in the remote machine's SSH daemon, but I prefer to have a separate dockerized ssh daemon to encapsulate the ambassador connections and to avoid having to turn on gateway ports.

There are 2 types of encrypted tunnels supported, local and remote. Local tunnels forward connections from a local port to a remote port. Remote tunnels are the opposite and allow you to forward remote ports to local.

For local tunnels, the environment format is as follows:

-e SSH_LOCAL_TUNNEL_<NAME>_<PORT>=<remote_service_host>:<remote_service_port>[<optional_ssh_user>@<remote_ssh_host>:<remote_ssh_port>]

The connection parameters inside the square brackets are the parameters used to make the ssh tunnel connection. The connection parameters immediately to the right of the = sign are the host and port of the remote service, as seen by the remote SSH daemon.

For remote tunnels, the environment format is as follows:

-e SSH_REMOTE_TUNNEL_<NAME>_<PORT>=<local_service_host>:<local_service_port>[<optional_ssh_user>@<remote_ssh_host>:<remote_ssh_port>]

The connection parameters inside the square brackets are the parameters used to make the ssh tunnel connection. The connection parameters immediately to the right of the = sign are the host and port of the local service, as seen by the ambassador client.

In all 3 cases, the port number left of the = sign inside the env variable name is the ambassador listener port for the service. In the case of TCP and SSH_LOCAL tunnels, this port is opened on the ambassador client, whereas for SSH_REMOTE this is the remote listening port (on the ssh daemon side).

Hope this makes a bit of sense, but please ask me more if not!