.. meta::
   :description: Overview of ThinLinc session startup customization,
                 including scripts, profiles, and environment settings.

.. _configuration_customizing_user_session:

Customizing the user's session
------------------------------

In this section, we will describe how the session startup in ThinLinc
can be customized. Also see :ref:`profiles` for details on the main
session customization tool.

.. _configuration_session-startup-bigpicture:

Session startup --- the big picture
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The session setup is constructed to be easy to use and configure yet
still easy to customize for advanced use cases.

.. _configuration_vsm-server-session-setup:

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

   Session startup procedure --- on the master

In :numref:`configuration_vsm-server-session-setup`, shows a
(simplified) description of what happens on the master when a client
connects to log in:

-  The master checks if the user has an existing session.

-  If a session exists, the master contacts the agent running on the
   host where the session is running, and asks it to verify that the
   session is still alive.

-  If the session was alive, the master runs any scripts placed in
   :file:`/opt/thinlinc/etc/sessionreconnect.d`. When all such scripts
   are completed, session information is returned to the client. The
   client proceeds by contacting the agent on which the session is
   running.

-  If the existing session was not alive, or if there were no existing
   sessions at all, the master finds out which agent has the least
   load, and contacts this agent to request a new session.

-  When the agent responds that a new session has been created, the
   master runs any scripts placed in
   :file:`/opt/thinlinc/etc/sessionstartup.d`. When all such scripts are
   completed, session information is sent back to the client. The client
   proceeds by contacting the agent on which the session was started.

.. _configuration_scripts_startup_reconnect:

Session startup/reconnect scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Scripts in :file:`/opt/thinlinc/etc/sessionstartup.d` and
:file:`/opt/thinlinc/etc/sessionreconnect.d` are run by the root user,
on the master. Session information will not be sent back to the client
until these scripts have completed. This makes it possible to ensure
that commands have been run before the client connects to the agent.

If background execution is desired, place the command to be run in the
background and make sure all file descriptors are closed. Here's an
example on how to execute a script in the background.

.. code:: bash

   /opt/thinlinc/sbin/tl-limit-printers < /dev/null > /dev/null 2>&1 &

.. _configuration_session-startup-vsmagent:

Session startup on agent
~~~~~~~~~~~~~~~~~~~~~~~~

.. _configuration_session-startup-vsmagent-figure:

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

   Session startup procedure --- on the agent

:numref:`configuration_session-startup-vsmagent-figure` outlines what
happens when an agent is contacted by the master to request a new
session. In detail, the following happens:

1. The agent (the machine where the session will reside) executes
   the script :file:`/opt/thinlinc/etc/xsession`.

2. The file :file:`/opt/thinlinc/etc/xsession` is a shell script that
   can be customized by advanced users. In its standard version, as
   delivered with ThinLinc, it will check if there is a file named
   :file:`~/.thinlinc/xstartup` in the user's home directory. If there
   is such a file, it will be executed. If no such file exists, the file
   :file:`/opt/thinlinc/etc/xstartup.default` is executed instead. See
   :ref:`configuration_profiles-xstartup` for a description of the
   standard behavior of this file.

This system allows for experienced users to customize how their session
startup should work by editing the file :file:`~/.thinlinc/xstartup`. On
the other hand, at sites where users should not be able to customize
their system startup, :file:`/opt/thinlinc/etc/xsession` can be modified
so that it doesn't try to execute user-specific xstartup-files. The
standard setup should however suit the needs of the majority of
installations.

.. _configuration_profiles-xstartup:

xstartup.default
~~~~~~~~~~~~~~~~

As described in :ref:`configuration_session-startup-bigpicture`,
:file:`/opt/thinlinc/etc/xstartup.default` is executed if there is no
:file:`~/.thinlinc/xstartup` for the user. This file, in its unmodified
version as delivered with ThinLinc, executes three steps, as outlined in
:numref:`configuration_profile-setup-figure`.

.. _configuration_profile-setup-figure:

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

   The ThinLinc profiles and xstartup.default

1. All files in :file:`/opt/thinlinc/etc/xstartup.d/` are executed.
   Files that have filenames ending with :file:`.sh` will be **sourced**
   as shell scripts. Other files are executed normally. This way,
   environment variables that persist down to the session command can be
   set in :file:`*.sh` files.

   If a specific execution order is needed for the scripts in the
   :file:`xstartup.d/` directory, let the names of the scripts begin
   with numbers, where a script with a lower number will be executed
   before one with a higher number. For example :file:`10setuphomedir`
   will be executed before :file:`20copyfiles`.

   By default, the script
   :file:`/opt/thinlinc/etc/xstartup.d/20-tl-select-profile.sh` will let
   the user choose among the possible profiles, see
   :ref:`profiles`. If only one profile is available, it will be selected
   without asking the user. The environment variable
   :environ:`TLPROFILE` is set to the name of the selected profile.

   Worth noting is that the environment variable :environ:`TLPROFILE` is
   available when running the scripts in :file:`xstartup.d`, for
   decisions based on what profile will be run.

2. The command :program:`tl-run-profile` is run. This runs the commands
   associated with the selected profile, for example :command:`startkde`
   to start a KDE session.

3. When the commands run by :program:`tl-run-profile` exits,
   :file:`xstartup.default` runs scripts and commands located in the
   directory :file:`/opt/thinlinc/etc/xlogout.d`. The same information
   that applies to files in :file:`xstartup.d` (as documented in
   step 1. above) applies to files in this directory.

.. note::

   Scripts in :file:`/opt/thinlinc/etc/xstartup.d` and
   :file:`/opt/thinlinc/etc/xlogout.d` are run **on the agent**, with
   the same rights as the user owning the session.

.. _configuration_start_program:

Start program from client
~~~~~~~~~~~~~~~~~~~~~~~~~

If the client has requested that the session should be started with a
command supplied by the client, the agent will set the environment
variable :environ:`TLCOMMAND` to this command. In this case, the profile
selection dialog will be disabled and :program:`tl-run-profile` will
execute the command specified by the client, instead of a profile
command. To disable client supplied start programs, create the file
:file:`/opt/thinlinc/etc/xstartup.d/00-no-startprog.sh`, containing:

.. code:: sh

   unset TLCOMMAND


Speeding up session startup
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If a user has a complicated session startup with many time-consuming
operations, it can take quite a while before the user's desktop
environment (for example KDE or Gnome) begins to start. One example of
when this happens is when mounting local drives.

One way of speeding up this process is to execute some of the operations
in the background. Most often, there is no need to mount the local
drives before starting KDE because it takes longer time to start KDE
than it takes to mount the local drives. The two operations can easily
run in parallel. The same goes for the example of mounting shared
directories.

The easiest way to accomplish this is to add an & sign after commands
run by scripts in :file:`/opt/thinlinc/etc/xstartup.d`.

Make sure that commands that must be run before starting the window
environment are run sequentially. For example, configuring desktops via
TLDC must be done before starting KDE.

Use client language
~~~~~~~~~~~~~~~~~~~

The ThinLinc client reports the language settings on the client side
when requesting a session. This can be used to configure the language on
the server side. The idea is that in an environment where several
languages are in use, a user could automatically get their preferred
language based on what their client computer is configured for.

To activate this, a symlink needs to be created:

.. code:: console

   $ sudo ln -s /opt/thinlinc/libexec/tl-set-clientlang.sh \
      /opt/thinlinc/etc/xstartup.d/00-tl-set-clientlang.sh

Also, make sure no other parts of the startup environment are trying to
set the :environ:`LANG` variable. For example, on Fedora, the files
:file:`/etc/profile.d/lang.sh` and :file:`/etc/profile/lang.csh` will
override the :environ:`LANG` variable set by
:file:`tl-set-clientlang.sh`.
