The ThinLinc client supports a large number of configuration options, the most useful of which are able to be set via the GUI. Other, less common options can either be passed at the command line, or via a plain-text configuration file located at ~/.thinlinc/tlclient.conf.
One of these less frequently used options is the HOST_ALIASES parameter. According to the ThinLinc Administrator’s Guide, the HOST_ALIASES parameter:
…specifies a list of hostname and port translations. This translation list is consulted whenever the client is about to initiate a network connection. This includes the SSH connection to the ThinLinc agent machine.
So by setting this parameter in the client configuration file, ThinLinc can perform a “translation” between one hostname and another, or one port number and another, essentially making a live substitution between the two. But what does this mean in practice, and when is it useful?
NAT Traversal
Probably the most common use-case for the HOST_ALIASES parameter is for accessing multi-node ThinLinc clusters behind a single NAT router, when only one public IP address is available. Normally, each server in a cluster must have its own public IP address for the cluster to be accessible from outside the local network. This is because the master server provides the hostname of the agent on which the user’s session is running, and the client connects directly to this agent.
In such cases, port forwarding can be used in combination with the HOST_ALIASES parameter in order to provide access to each server in the cluster from outside the local network. Once each server has had its IP address mapped to a certain port on the router (via the router’s configuration), the HOST_ALIASES parameter can be used to ensure ThinLinc uses this port to communicate with the server, rather than using the server’s hostname directly. For example, the following configuration will cause ThinLinc to access the two agent servers via separate ports on the router’s external IP address, rather than using the hostname:
HOST_ALIASES=tl-agent2.example.com=<PUBLIC_IP>:2022 tl-agent2.example.com=<PUBLIC_IP>:2023
Each server in the cluster should should be added to the list in a similar fashion.
Note that this configuration is only valid when connecting from outside the local network and shouldn’t be used when connecting from inside, since local IP addresses should be used in that case. If you will be connecting from both inside and outside the network, one tip is to create a specific configuration file to use when connecting from outside the network - for example, ~/.thinlinc/tlclient_external.conf - and launch the client by specifying this configuration file at the command line like so:
tlclient -c ~/.thinlinc/tlclient_external.conf
Note: for another solution to NAT traversal in ThinLinc, see How to make a ThinLinc server behind NAT externally accessible | ThinLinc by Cendio.
Running the SSH server on a non-standard port
The ThinLinc client can connect to an SSH server running on any port, including non-standard ones (i.e. ports other than 22). If all of your ThinLinc servers have SSH running on the same non-standard port, then the easiest way to configure the ThinLinc client is to specify the port in the client GUI, using the SSH Port option under the Security tab. Every SSH connection the client makes will then be to the port specified here. But what if, for example, you use the same client to connect to multiple ThinLinc instances with different port configurations?
Say you have one ThinLinc cluster at tl.non-standard-ssh.com with SSH running on port 2020, and another one which you connect to frequently with SSH running on the standard port 22. By adding the following line to the ThinLinc client configuration file, you can connect to all clusters using the same client, without having to remember to change the port to 2020 in the client GUI (and back again afterwards!) each time you connect to tl.non-standard-ssh.com:
HOST_ALIASES=thinlinc.non-standard-ssh.com=:2020
Note that if you have multiple servers in the cluster - for example, separate agents also using non-standard ports - these would need to be added to the list as well. A similar configuration can also be used if you have a multi-node cluster using different ports for each server (e.g. port 22 on the master, but a non-standard port for the agents).
Jumphost or bastion host traversal
Finally, the HOST_ALIASES parameter can be used for accessing a ThinLinc cluster behind a jumphost, or bastion host. In this case, the ThinLinc servers are not directly accessible from outside the local network, but must be accessed via the bastion host. The setup can be quite complex, but in most cases it is possible to write an executable script to do this for you before launching the ThinLinc client.
The first step is to create an SSH tunnel from the client device, through the bastion host to the ThinLinc server(s) on the other side. This is done using port the port forwarding feature of OpenSSH, and a separate port must be forwarded for each server in the cluster. On Linux and macOS, this can be done at the command line as follows:
ssh -fN -L 2200:tl-master.example.com:22 user@bastion-host.example.com
ssh -fN -L 2201:tl-agent1.example.com:22 user@bastion-host.example.com
ssh -fN -L 2202:tl-agent2.example.com:22 user@bastion-host.example.com
This will forward all traffic sent to port 2200 on localhost - through the bastion host - to port 22 of tl-master.example.com. In the example above, similar tunnels have also been set up for two agent servers.
The next step is to configure the HOST_ALIASES variable so that ThinLinc uses these tunnels, rather than trying to connect to the hostnames directly. To do this:
HOST_ALIASES=tl-master.example.com=localhost:2200 tl-agent1.example.com=localhost:2201 tl-agent2.example.com=localhost:2202
Once these steps have been completed, it should be possible to connect to tl-master.example.com using the ThinLinc client, and access your sessions on the agents behind the bastion host.