.. meta::
   :description: Overview of ThinLinc's session lifecycle, how sessions are
                 created, and which aspects can be customized.

.. _session_lifecycle:

Session lifecycle
-----------------

This chapter details the lifecycle of ThinLinc sessions, how they are
created, and which aspects in the session startup and cleanup can be
customized.

.. _configuration_session-startup-vsmserver:

Master session startup
~~~~~~~~~~~~~~~~~~~~~~

When a user connects to a ThinLinc cluster, they are first connected to
the master server.

.. _configuration_vsm-server-session-setup:

.. figure:: images/vsm-server-session-startup.svg

   Session startup procedure --- on the master

:numref:`configuration_vsm-server-session-setup` shows a high-level
description of what happens on the master when a ThinLinc client
connects:

.. rubric:: Check for existing sessions

1. The master checks if there are any existing sessions for the user in
   the master's session database.

2. The master makes sure this information is up-to-date by asking the
   agent in question to verify that the sessions are still running.

.. rubric:: Path A: Existing session

This path is taken if *an existing session was found*.

1. The master runs the scripts in
   :file:`/opt/thinlinc/etc/sessionreconnect.d/` as the root user. See
   :ref:`configuration_master_scripts`.

2. The master sends session information back to the client. Based on
   this information, the client connects directly to the agent hosting
   the session.
   
.. rubric:: Path B: New session

This path is taken if *no sessions were found*.

1. The master determines which :ref:`subcluster
   <configuration_subcluster>` the user belongs to. Based on this, it
   determines which agents are candidates for hosting the user's
   session.
   
2. The master's :ref:`load balancer <load_balancing>` picks the agent
   best suited to host the session from the list of candidates.

3. The master contacts the chosen agent, requesting a new graphical
   session for the user.

4. The master runs the scripts in
   :file:`/opt/thinlinc/etc/sessionstartup.d/` as the root user. See
   :ref:`configuration_master_scripts`.

5. The master sends session information back to the client. Based on
   this information, the client connects directly to the agent hosting
   the session.

.. _configuration_session-startup-vsmagent:

Agent session startup
~~~~~~~~~~~~~~~~~~~~~~

.. _configuration_session-startup-vsmagent-figure:

.. figure:: images/session-startup.svg

   Session startup procedure --- on the agent

:numref:`configuration_session-startup-vsmagent-figure` outlines the
flow after the master requests a new session to be created on the agent:

.. rubric:: Check for user-configured session startup

The agent selected to host the session first executes the script
:file:`/opt/thinlinc/etc/xsession`. If :file:`~/.thinlinc/xstartup` is
not present in the user's home directory,
:ref:`configuration_profiles-default-startup` will be taken. If present,
:ref:`configuration_profiles-user-startup` will be taken.

.. note::

   If it is undesirable to leave control over the session startup to to
   the end-user, the shell script :file:`/opt/thinlinc/etc/xsession` can
   be modified so it does not execute :file:`~/.thinlinc/xstartup`.

   Any changes to :file:`/opt/thinlinc/etc/xsession` must be reapplied
   after the ThinLinc server has been upgraded.


.. _configuration_profiles-default-startup:
.. rubric:: Path A: Default session startup

This path is taken if :file:`~/.thinlinc/xstartup` *was not found*. The
agent then runs the script
:file:`/opt/thinlinc/etc/xstartup.default`:

:numref:`configuration_profile-setup-figure` outlines the high-level
flow of what happens then:

.. _configuration_profile-setup-figure:

.. figure:: images/profiles-xstartup.svg

   The ThinLinc profiles and :file:`xstartup.default`

1. All files in :file:`/opt/thinlinc/etc/xstartup.d/` are executed. See
   :ref:`configuration_agent_scripts`.

3. When all scripts in :file:`xstartup.d/` have been executed, the
   profile specified by the environment variable :environ:`TLPROFILE` is
   run. This environment variable is typically set by the :ref:`profile
   chooser <profiles>` (:file:`xstartup.d/20-tl-select-profile.sh`).

   For example, if :environ:`TLPROFILE` is set to **mate**, the profile
   configured in :servconf:`/profiles/mate </profiles/\<profile key\>>`
   will be run.

4. Once the profile has exited, typically by the user logging out, the
   scripts in :file:`/opt/thinlinc/etc/xlogout.d/` are run. See
   :ref:`configuration_agent_scripts`.

.. _configuration_profiles-user-startup:
.. rubric:: Path B: User-defined session startup

This path is taken if :file:`~/.thinlinc/xstartup` *was found*. In this
case, that file is executed instead of
:file:`/opt/thinlinc/etc/xstartup.default`.

The :file:`~/.thinlinc/xstartup` script is conceptually similar to the
:file:`~/.xinitrc` commonly used for local graphical sessions.