.. meta::
   :description: This section provides an overview of license management
                 in ThinLinc, including license counting, file handling,
                 and monitoring.

.. _licensehandling:

License handling
================

Overview
--------

To run a session against a ThinLinc cluster, the master server must be
equipped with license files. The license files specify the number of
concurrent users the cluster is allowed to run.

If no license files are installed on the cluster, a maximum of three
concurrent users are allowed.

Each cluster can have one or several license files. Each file contains
licenses for a specific number of concurrent users. When the master
service (:file:`vsmserver.service`) starts up, it reads all license
files and creates a sum of the number of concurrent users allowed based
on the licenses from all files.

Licenses are backwards compatible, meaning a license issued for a newer
version of ThinLinc is valid for that version and all older versions of
the software. Conversely, licenses are not forwards compatible: a
license issued for an older version of ThinLinc cannot be used with
newer versions of the software.

Version compatibility applies to the **x** (major) and **y** (minor)
parts of ThinLinc **x.y.z** versioning. The **z** (patch) number is
exempt: any license valid for a given **x.y** version will work across
all patch (**z**) releases.

License files have one soft and one hard limit. When the soft limit is
reached, new sessions can still be started, but a license violation will
be logged and sent to the administrator (see
:ref:`licensekeys_logemail`). If however the hard limit has been
reached, new sessions cannot be started. The purpose of this system is
to allow growing organizations some time to adapt the number of licenses
to a growing number of concurrent sessions, avoiding loss of production.

Licenses from different agreements can **not** be combined in order to
achieve a larger total license count. In such situations, the license
count will reflect the agreement that has the most valid licenses.

License counting
----------------

One license is required for each pair of (**username**,
**client hardware**). This means that if a user runs several sessions
from the same client, only one license is used. If the same user runs
multiple concurrent sessions from different client hardware, multiple
licenses are required by the user.

.. _licensekeys_location:

Location and format of license files
------------------------------------

License files are delivered either in the form of text files (filename
extension :file:`.license`) or ZIP files (filename extension
:file:`.zip`). Transfer each file to your ThinLinc master server and
place it in :file:`/opt/thinlinc/etc/licenses`. Make sure that the
transfer of the files uses binary mode, or the license file might not be
verifiable. We recommend transferring via SCP or SFTP.

After adding new license files, either restart the master service by
running :command:`/bin/systemctl restart vsmserver` or wait until the
master service automatically reads in the new licenses, something that
happens once every 12 hours.

.. note::

   In a high availability setup (see :ref:`HA`) with multiple master
   nodes, license files should be copied to
   :file:`/opt/thinlinc/etc/licenses` on both nodes.

.. _licensekeys_logemail:

License monitoring and alerts
-----------------------------

ThinLinc licenses are time-limited, and the system continuously monitors
both the subscription period and the number of allowed users. When a
subscription approaches its end or a license violation occurs, the
system automatically triggers alerts to ensure the administrator is
informed well in advance. Administrative emails are sent to the address
specified in the parameter :servconf:`/vsmserver/admin_email` in
:file:`vsmserver.hconf`.

Simultaneously, the system records these events on the master server,
logging specific license violations to
:file:`/var/log/thinlinc-user-licenses` and general license messages to
:file:`/var/log/vsmserver.log`.

If the subscription is not renewed and the system runs with invalid
licenses, warning messages will also be displayed to end-users. However,
these invalid states do not block access; users can still start and
connect to their sessions normally while being notified of the license
status.

Checking the number of valid licenses
-------------------------------------

You can use the command :doc:`man/tlctl-license.8` to verify the number
of valid user licenses. There is also a graph available in the
administrative interface. See the :ref:`tlwebadm_status` for more
information.
