How can I customise the desktop environment within a ThinLinc session?

aaron · 14 September 2023 10:02

Using ThinLinc’s profile selector, it is possible to provide users with a choice of desktop environments (DEs) when starting a new ThinLinc session. This can be useful when users have a strong preference for a certain type of interface, for example tiling vs. floating window managers, or modern graphical shells vs. a more traditional desktop metaphor.

It is also possible to use the profile selector to provide different configurations of the same DE, with different menu layouts and desktop icons presented to each user. This is done with the help of the ThinLinc Desktop Customiser (TLDC). As well as applying different configurations based on the selected profile, TLDC can configure desktops based on username, group membership, or in fact any arbitrary condition such as time of day, or the amount of free memory available on the server.

The following article describes step-by-step how to implement custom desktops for users with TLDC, and also discusses some suggested best-practice configuration for achieving this.

Note: It is not possible to use TLDC with all desktop environments. More specifically, TLDC will not work with DEs such as GNOME Shell or KDE Plasma which do not conform to traditional desktop metaphors. For more information on choosing a DE for use with ThinLinc, see “Which desktop environment should I use with ThinLinc?”. Also, while application menu structure and desktop icons can be configured with TLDC, additional third-party tools may be required for customising other components such as settings and themes.

The recommended configuration for the purposes of this article is to have separate master and agent servers, i.e. with ThinLinc installed in a cluster configuration. While it is possible to use TLDC in single-server configurations, making changes to desktops is made easier when the master can be used as a test-bed before distributing these changes to the agents.

Ensure that master and agent servers are identical in terms of operating system, and installed applications and packages. Hardware does not have to be identical; agent servers will typically be more powerful as this is where the majority of user sessions will be run. However, in order to test desktop configurations on the master first, the environment must be identical to the agents.
Ensure that the vsmagent process is running on all servers in the cluster, and vsmserver only on the master. Disable the tlwebadm process on all servers except for the master, and ensure that this service (running on port 1010 by default) is only accessible from localhost.
Designate a specific administrative system user for performing system configuration. This should not be root, but may be an existing administrative user with privileged access on all servers through utilities such as sudo. This user should be configured to authenticate using a public key.
Set up non-interactive SSH authentication for the root user from the master to all servers in the cluser, including localhost, in order to simplify distribution of desktop configuration files throughout the cluster. One way to do this is using public key authentication.

Note: the private key does not have to be stored on the master in order for this to work; SSH agent forwarding can be used from the client instead. See the man page for ssh(1), specifically the -A flag.

Add the administrative user’s public key to /root/.ssh/authorized_keys on each server - including the master - to enable the administrative user to authenticate as root using their private key. Although it is generally bad practice to allow authenticating directly as root, this can be restricted to a single source - in this case, the master server - using sshd’s DenyUsers and AllowUsers directives. Add the following lines to the sshd configuration on each server, and restart sshd:
```
DenyUsers root@!<master_hostname>,*
AllowUsers *@*
```
The order is important; <master_hostname> should also resolve to a non-routable (i.e. internal) IP address here, as ThinLinc traffic between the master and agents is unencrypted. On the master server, this value should be set to 127.0.0.1.

You should now be able to do the following:
- From a client machine running ssh-agent, log into the master server as the administrative user with public key authentication, using the following command:
  
  ssh -A <admin_user>@<master_hostname>
- From the master server, as the administrative user, log in to any one of the agents as root by running the following command:
  
  ssh root@<agent_hostname>
Make sure that you are not able to log into the agents as root from any other host than the master.
Configure ThinLinc to allow the administrative user - and only this user - to create sessions on the master server. This can be done by creating a new subcluster in /opt/thinlinc/etc/conf.d/vsmserver.hconf on the master, listing 127.0.0.1 as the only server in the cluster, and specifying the relevant username under the users parameter:
```
[/vsmserver/subclusters/admin]
groups=
users=<admin_user>
agents=127.0.0.1
```
The Default cluster should have the IP addresses or hostnames of the agents specified under the agents parameter, with the users and groups parameters empty. Once this has been done, restart the vsmserver process on the master.

On each agent, set the master_hostname parameter in /opt/thinlinc/etc/conf.d/vsmagent.hconf to the IP address or hostname of the master, and make sure that the agent_hostname parameter in the same file on all servers - including the master - is set to an externally resolvable and accessible hostname or IP address. Don’t forget to restart the vsmagent process once you’re done.

On the master, run sudo /opt/thinlinc/sbin/tlctl load list to verify that two subclusters have been formed successfully, and the master is able to communicate with all agents.
Using the ThinLinc client, log in and create a new session as a normal (i.e. non-administrative) user. Check that this session is created on an agent server. Now log out, and do the same thing as the administrative user. Check that this session is created on the master server.
In the desktop session on the master server, open a browser and connect to the ThinLinc Web Administration interface by browsing to https://localhost:1010. Authenticate using the credentials which were specified during ThinLinc installation.
Browse to the “Desktop Customiser” module in the navigation menu, and perform the desired desktop configuration. Details on how to do this using TLDC can be found in the relevant section of the ThinLinc Administrators’ Guide. When performing the configuration, remember to make sure that all changes will be applied for the administrative user as well.
Activate the desktop customiser on all servers, by creating a symlink to the /opt/thinlinc/bin/tl-desktop-activate.sh script. This can be done on all servers in the cluster with one command, by using tl-ssh-all as the administrative user. SSH into the master server with agent forwarding enabled, and run the following command:
```
tl-ssh-all -l root "ln -s /opt/thinlinc/bin/tl-desktop-activate.sh /opt/thinlinc/etc/xstartup.d/35-tl-desktop-activate.sh"
```
If you have configured sudo and public key authentication correctly on all agents, then this command should complete non-interactively. Note that the first time you run this command, you will be asked to verify the fingerprint of each server, however this should not happen on subsequent runs.
Log out of the ThinLinc session, and log back in again. You should see the changes you made in TLDC applied to your desktop environment, in a session on the master server. If you are not happy with the changes, perform any additional configuration using TLDC and restart your session until you are satisfied with the result.
Distribute the desktop configuration defined in TLDC to all agents in the cluster. The files and directories which need to be synced are:
- All subdirectories of /opt/thinlinc/desktops
- The configuration file /opt/thinlinc/etc/conf.d/tl-desktop-customizer.hconf
Use the command tl-rsync-all to sync these files to all agents, by SSHing into the master server as the administrative user, and running the following commands:
```
tl-rsync-all /opt/thinlinc/desktops
tl-rsync-all /opt/thinlinc/etc/conf.d/tl-desktop-customizer.hconf
```
Once these commands have completed, users starting new sessions on any agent in the cluster should be presented with a desktop containing the modifications made in TLDC.

This method should provide a safe and effective means of providing users with custom desktops in ThinLinc. If you are adding a new profile for a specific desktop configuration, make sure to sync the file /opt/thinlinc/etc/conf.d/profiles.hconf across to all agents as well.

To summarise, once the above configuration has been made, the workflow for customising and distributing desktop configurations in ThinLinc using TLDC is as follows:

Log into a ThinLinc session as the administrative user. You should get a session on the master server.
Inside the session, browse to https://localhost:1010 and log into the web administration interface
Make the desired changes to the desktop configuration using TLDC
Log out, and back in again as the administrative user. You should see the updated desktop configuration applied to your session.
If you are not satisfied with the result, repeat the previous two steps until you are.
Distribute the desktop configuration to all agents by SSHing into the master server as the administrative user, and running tl-rsync-all as described in step 11) above