.. _configuration_cluster:

Configuring ThinLinc Servers in a Cluster
-----------------------------------------

In this section, we will describe how to configure a ThinLinc cluster
with multiple agent servers to allow load-balancing and redundancy.

.. note::

   This section does *not* address configuration of high availability
   (HA). For information on configuring your ThinLinc cluster for high
   availability, see :ref:`HA`.

A ThinLinc cluster consists of one master server (or multiple master
servers in a HA configuration) with multiple agent servers grouped into
subclusters. While ThinLinc in its simplest configuration may be run
with both the master and agent installed on the same machine, running
ThinLinc in a cluster configuration conveys numerous advantages:

1. A cluster configuration allows automatic load-balancing of sessions
   across multiple agents

2. Having multiple agents offers redundancy; for example, if one agent
   goes down or is taken out of service for maintenance, other agents
   are still available to handle user sessions

3. A cluster configuration is scalable. Since most of the workload is
   taken up by the agents and not the master, adding more capacity to
   your ThinLinc installation is generally as easy as installing one or
   more new agent servers

Cluster Configuration
~~~~~~~~~~~~~~~~~~~~~

When configuring ThinLinc servers as a cluster, one needs to configure
both the master server and the agents. The master server needs
configuration for subclusters (even if there is only one agent) and the
agents need to know which server is the master for access control.

The configuration parameter :servconf:`/vsmagent/master_hostname` for
each agent that is included in a ThinLinc cluster should be configured
with the address of the master server for the cluster. This gives the
master access to communicate with and control the agent server.

Once the master and agents within a cluster are configured, and the
**vsmagent** and **vsmserver** services have been restarted, these
ThinLinc servers will then function as a cluster.

.. _configuration_subcluster:

Subclusters
^^^^^^^^^^^

A subcluster is a group of agents. At least one subcluster is always
active, even in a single server setup. Each subcluster can serve a
specific purpose within the ThinLinc cluster. The dimension for grouping
can be chosen at will and could for example be; location, project,
application etc.

ThinLinc ships with one default subcluster configuration which is used
for creating new sessions by any user. It is allowed to define as many
subclusters as needed. Each subcluster can be associated with users and
with user groups.

To associate a user with a subcluster, either use the |users| or
|groups| configuration parameter for the specific subcluster. See
:ref:`configuration_subcluster_params` for details on these subcluster
configuration parameters.

.. |users| replace::
   :servconf:`users </vsmserver/subclusters/<name>/users>`
.. |groups| replace::
   :servconf:`groups </vsmserver/subclusters/<name>/groups>`

If a subcluster does have neither user nor group associations
configured, it is used as a default subcluster. Users that does not
belong to any subcluster, will have their sessions created on the
default subcluster. If a user is not associated with a subcluster and
there is no default subcluster configured, the user will not be able to
logon to the ThinLinc cluster.

Loadbalancing of new sessions is performed using the list of agents
defined in the |agents| parameter within each subcluster. See
:ref:`stop_new_sessions_on_agent` for details on preventing new sessions
on some agents.

.. |agents| replace::
   :servconf:`agents </vsmserver/subclusters/<name>/agents>`

.. note::

   The subcluster association rules limit the creation of new sessions
   and does not apply to already existing sessions. So given a case
   where subcluster association was changed after session startup, the
   user is able to reconnect to a session outside their configured
   subcluster. However, next time this user creates a session it will be
   created on the configured subcluster.

A subcluster is defined as a folder under the
:servconf:`/vsmserver/subclusters` configuration folder in
:file:`vsmserver.hconf`. The foldername defines a unique subcluster
name.

Here follows an example subcluster configuration for a geographic
location based grouping of agents:

.. code:: ini

   [/vsmserver/subclusters/default]
   agents=tla01.eu.cendio.com tla02.eu.cendio.com

   [/vsmserver/subclusters/usa]
   agents=tla01.usa.cendio.com tla02.usa.cendio.com
   groups=ThinLinc_USA

   [/vsmserver/subclusters/india]
   agents=tal01.india.cendio.com tla02.india.cendio.com
   groups=ThinLinc_India

During the selection process for which subcluster a new session is
created on, the following rules apply:

1. |users| has precidence over |groups|. This means that if a user
   belongs to a group that is associated with subcluster A and the user
   also is specified in |users| for subcluster B, the user session will
   be created on subcluster B.

2. |groups| has precidence over the default subcluster. This means that
   if a user belongs to a group that is associated with subcluster B,
   the user session will be created subcluster B and not on the default
   subcluster A.

3. If user does not belong to an associated group nor is explictly
   specified by |users| for a subcluster, the new session will be
   created on the default subcluster.

.. note::

   Try to avoid the following configurations that will result in
   undefined behaviors for subclusters:

   1. Avoid two subclusters without associated |users| and |groups|, eg.
      default subclusters. It is undefined which of them that will be
      the default subcluster used for users that are not associated to a
      specific subcluster.

   2. If a user is a member of two user groups which are used for two
      different subclusters, it is undefined which subcluster the new
      session will be created on.

   3. If a user is specifed in |users| of two different subclusters, it
      is undefined which subcluster the new session will be created on.

.. _keeping_agents_synced:

Keeping agent configuration synchronized in a cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When multiple agents have been configured as part of a cluster, it is
usually desirable to keep their configurations synchronised. Instead of
making the same change seperately on each agent, ThinLinc ships with the
tool :program:`tl-rsync-all` to ensure that configuration changes can be
synchronised easily across all agents in a cluster. See
:ref:`commands` for more information on how to use this tool.

The :program:`tl-rsync-all` command should be run on the master server,
since it is the master which has the knowledge of which agents there are
in the cluster. For this reason, it is often useful to configure the
master server as an agent as well, even if it will not be used to host
user sessions in general. This allows the master to be used as a
"template" agent, where configuration changes can be made and tested by
an administrator before pushing them out to the rest of the agents in
the cluster. In this way, configuration changes are never made on the
agents themselves; rather, the changes are always made on the master
server, and then distributed to the agents using
:program:`tl-rsync-all`.

An example of how one might implement such a system is to configure the
master server as an agent which only accepts sessions for a single
administrative user. The steps to do this are as follows:

1. Configure the master as an agent too. On a ThinLinc master, the
   **vsmagent** service should already have been installed during the
   ThinLinc installation process; make sure that this service is
   running.

2. Create an administrative user, for example **tladmin** . Give this
   user administrative privileges if required, i.e. sudo access.

3. Create a subcluster for the master server and associate administrator
   user **tladmin** to it. See following example:

   .. code:: ini

      [/vsmserver/subclusters/Template]
      agents=127.0.0.1
      users=tladmin

   See :ref:`configuration_subcluster` for details on subcluster
   configuration.

4. Restart the **vsmserver** service.

In this way, configuration changes are never made on the agents
themselves; rather, the changes are always made on the master server,
and then tested by logging in as the **tladmin** user. If successful,
these changes are then distributed to the agents using
:program:`tl-rsync-all`.

.. _stop_new_sessions_on_agent:

Stopping new session creation on select agents in a cluster
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When, for example, a maintenance window is scheduled for some agents
servers it is sometimes desirable that no new sessions are started on
that part of the cluster. It is possible to prevent new sessions from
being started without affecting running sessions.

To stop new session creation on specific agents, those agents need to be
removed from the |agents| configuration variable in the associated
subcluster. Once the **vsmserver** service is restarted on the master
server, new user sessions will not be created on the removed agents.
Users with existing sessions can continue working normally and users
with disconnected sessions will still be able to reconnect.
