.. _Setup:

Setup
=====================================

.. attention:: We recommend using the latest config file as a starting
  point and moving changes from your old config file into the new one.

Configuration values are defined by nested XML elements in the
``ice-remoteware.xml`` config file. This can be found:

* Linux: ``/opt/ice-remoteware/ice-remoteware.xml``
* MacOS: ``/Applications/ICE RemoteWare.app/Contents/Resources/ice-remoteware.xml``
* Windows:  ``C:\Program Files\Penguin Solutions\ICE RemoteWare\ice-remoteware.xml``. 

This section describes properties in the config file.

For the purpose of this document, we refer to properties by using dot
notation.  For example, ``config.Server.Log.Level`` indicates that
``LogLevel`` is a property within ``Server``, which is a property
within ``config``.  Since all properties begin with 'config', for
brevity we ignore it.  Properties are case-sensitive.

.. warning:: The config file and private key files contains sensitive
  information that can compromise security if an attacker can read it.
  We strongly recommend limiting read and write access to the root /
  system administrator account.

.. warning:: The ICE RemoteWare™ software includes a default private key, 
  certificate file, username, and password that are not secure and should be
  changed.

Applying Config File Changes
-------------------------------------

Saved changes to the config file are only applicable once the service
restarts.  The Server.Auth.ShadowPassword setting is the one exception
to this rule - saved changes to it are applicable immediately.

**In Linux** you can restart the service using the
``systemctl restart`` command:

::

  systemctl restart ice-remoteware.service

**In Windows** you can restart the service using the Services tool.  First
open the Task Manager by right-clicking on the Task Bar and select
``Start Task Manager``.  At the Task Manager, go to the ``Services`` tab
and click on ``Services``.  Right-click on ``ice-remoteware`` in the list
of services and select ``Restart`` from the dropdown of actions.

**In MacOS** you can restart the service by calling the application with
the ``--service restart`` flag.  For example:

::

   # Change to the application directory
   cd /Applications/ICE RemoteWare.app/Contents/MacOS

   # Restart the service
   sudo ./ice-remoteware --service restart


The ICE RemoteWare sign-in page should return after a few seconds.


.. attention:: We recommend using the latest config file as a starting
  point and moving changes from your old config file into the new one.

The default config file comes with appropriate values for nearly all
of the server settings.

In this section we discuss config settings that are commonly changed
from the default config file.

License Management
-------------------------------------

For more information on license management, please see:
:ref:`LicenseManagement`.

.. _Doc.Setup.ServerAuthentication:

Server Authentication
--------------------------------------------------------------------------

Users are authenticated using credentials defined by the
config file or by the ScyldCloudAuth web service.  To disable
any of these, simply comment out these elements by wrapping them with
``<!--`` and ``-->``.

Authentication is enabled by default and in should not be disabled in
production systems.  :ref:`Server.Auth.Enabled` should always be set to
``true``.

There are several authentication schemes supported by the ICE RemoteWare software.
Each system is independent and can be enabled in parallel.

* Config File Authentication
* ScyldCloudAuth Authentication
* OS Credential Authentication

.. _Doc.Setup.ConfigFileAuthentication:

Config File Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to OS credentials, you can setup a
username and hashed password in the config file to sign in to the
ICE RemoteWare software. These config file credentials can sign into the ICE RemoteWare
product at any time.  This differs from OS credentials, which can only sign
into the ICE RemoteWare software if the OS greeter screen or that user's desktop is
showing.  Config file credentials are independent from LDAP, the remote
operating system, and ScyldCloudAuth.

Config file credentials are only enabled if ``Server.Auth.Username``
and ``Server.Auth.ShadowPassword`` tags exist, are uncommented, and
both have values.  The following settings control Config File Authentication:

* :ref:`Server.Auth.Username`
* :ref:`Server.Auth.ShadowPassword`
* :ref:`Server.Auth.MinPasswordLength`

Config File Authentication can be disabled by commenting or
removing :ref:`Server.Auth.Username` and :ref:`Server.Auth.ShadowPassword`.

To set the password, verify that the ``Server.Auth.Username`` and
``Server.Auth.ShadowPassword`` tags exist **and are uncommented** in the
config file (that is, they are not surrounded by ``<!--`` and ``-->``).  
If the value of either tag is blank, the account is considered disabled.

If these tags do not already exist, insert both of them and set a
value for ``Server.Auth.Username``.  For example:

::

  <Server>
    ...
    <Auth>
      ...
      <Username>admin</Username>
      <ShadowPassword></ShadowPassword>
      ...
    </Auth>
    ...
  </Server>

You can now set this password by opening a terminal, changing to
the directory of the ICE RemoteWare binary, and running ice-remoteware
with an OS-specific ``passwd`` flag:

::

  # Linux:
  sudo ice-remoteware.sh --passwd

  # Windows (as an Administrator):
  ice-remoteware.exe /passwd

  # MacOS:
  sudo ice-remoteware --passwd

The password change takes effect immediately.

Password strength requirements are described in the Setup chapter
under :ref:`Server.Auth.ShadowPassword`.

.. important:: This only changes the Server.Auth.ShadowPassword entry
  in the config file.  It does not change the passwords used by
  the remote operating system, LDAP, or ScyldCloudAuth.

ScyldCloudAuth Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ScyldCloudAuth Authentication uses the ScyldCloudAuth proxy service
for authentication.  To enable ScyldCloudAuth for authentication,
set:

* :ref:`Server.Auth.ScyldCloudAuth.URL`
* :ref:`Server.Auth.ScyldCloudAuth.Allow`
* :ref:`Server.Auth.ScyldCloudAuth.Deny`
* :ref:`Server.Auth.ScyldCloudAuth.ApiKey`
* :ref:`Server.Auth.ScyldCloudAuth.ApiSecret`


ScyldCloudAuth can be disabled by commenting or removing
:ref:`Server.Auth.ScyldCloudAuth.URL`.

OS Credential Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The credentials accepted by your remote Linux, Windows, or MacOS host
can be used to sign into the ICE RemoteWare product. This supports ActiveDirectory
for Windows, and LDAP / PAM for Linux.

.. important:: While config file or ScyldCloudAuth usernames can be
   used to sign in to the ICE RemoteWare product at any time, only a single set of 
   OS credentials can be used to sign-in at a time.  This prevents
   different OS credentials from signing in at the same time.

This feature can be disabled by setting :ref:`Server.Auth.OSAuth.Enabled` to
``false`` or removing it from the config file.

External Sign-In Pages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your organization wants to use an external webpage for signing into the
ICE RemoteWare product, you can set the :ref:`Server.Auth.ExternalSignInPage` setting
to the URL.  The ICE RemoteWare sign-in page will show a link to the external
sign-in page instead of the default sign-in interface.

Server Security
--------------------------------------------------------------------------

.. _Doc.Setup.ServerHTTPsSecuriy:

HTTPs Security
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The cipher list will determine what ciphers are used to encrypt
communication between your clients and your server.  It is always a
good idea to keep your server's OpenSSL updated to the latest version.

We recommend using the default values for :ref:`openSSL.server.cipherList`.

.. _Doc.Setup.ClientSecuriy:

Client Security
--------------------------------------------------------------------------

Clients and browsers that meet the requirements listed in
:ref:`ClientRequirements` support TLS 1.2, WebGL, and
WebSockets by default and require no further setup.

.. attention:: Contact your system administrator if TLS 1.2, WebGL, or
  WebSockets are disabled.


.. _Firewall:

Firewall
--------------------------------------------------------------------------

Your server host's firewall needs to allows incoming connections
to the server over port 443 if you are using use HTTPS or port 80 if
you are using HTTP.

**In Linux**, you will have to update your firewall using iptables.  In
most cases, adding the following line to your rules file (Rocky/CentOS/RHEL:
``/etc/sysconfig/iptables``) and restarting the iptables service will
allow incoming HTTPS traffic.

::

  # Allow all https
  -A INPUT -p tcp --dport 443 -j ACCEPT

Change 443 to 80 in the line above to accept incoming HTTP traffic
over port 80 instead.

**In Windows** these rules are automatically set by the installer and
removed by the uninstaller.

.. _Doc.Setup.HTTPSSSLCertificates:

HTTPS / SSL Certificates
-------------------------------------

HTTPS and trusted SSL certificates are required to make all of your
interactions with the server secure.

To ensure that connections are using the latest TLS protocol (as of
2015), set :ref:`openSSL.server.requireTLSv1_2` to ``true`` and enable HTTPS
by setting :ref:`Server.Network.Secure` to ``true``.

Set :ref:`openSSL.server.privateKeyFile` and :ref:`openSSL.server.certificateFile`
to the appropriate private key and SSL certificate paths.

If you have set a passphrase for your private key you will need to set
:ref:`openSSL.server.privateKeyPassphraseHandler.options.password`.

An SSL certificate signed by a trusted certificate authority
(CA) is used to encrypt and authenticate communication between a
browser and server.  To obtain an SSL certificate from a CA, you need
to generate a certificate signing request (CSR) and submit it to the
CA.  A list of popular CA's is given below:

* https://www.digicert.com/
* http://www.entrust.com/ssl-certificates/
* http://www.geotrust.com/
* https://www.thawte.com/

Linux users need to install OpenSSL on the server to
complete setup.  For example:

::

  # Rocky, CentOS and RHEL Linux
  sudo yum install openssl

  # Ubuntu
  sudo apt-get install openssl

The following sections describe how to use the ``openSSL`` command to
create a new private key and CSR, a new CSR from an existing private
key, and a self-signed SSL certificate (not recommended).

Create a Private Key and a CSR
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use the ``openssl`` command to creates a 2048-bit private key
(domain.key) and a CSR (domain.csr).  If your CA supports SHA-2, add
the -sha256 option to sign the CSR with SHA-2.

::

  openssl req -newkey rsa:2048 -nodes -sha256 -keyout domain.key -out domain.csr

Fill out the prompted questions to complete the CSR.

.. warning:: The contents of your private key should never be shared
   with anyone.

Create a CSR from an Existing Private Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To create a CSR from an existing private key:

::

  openssl req -key domain.key -new -out domain.csr

Fill out the prompted questions to complete the CSR.

Create a Private Key and Self-Signed SSL Certificate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can create a self-signed SSL certificate instead of having one
signed by a CA.  The disadvantage to this is that in order to
establish trust between the browser and the server, you must make a
security exception for this certificate when you visit the page or
install it in every browser.

::

  openssl req \
          -newkey rsa:2048 -nodes -sha256 -keyout domain.key \
          -x509 -days 365 -out domain.crt

Fill out the prompted questions to complete the CSR.

.. warning:: The contents of your private key should never be shared
   with anyone.

Create a Self-Signed SSL Certificate from an Existing Private Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To create a self-signed certificate from an existing private key:

::

  openssl req \
          -key domain.key -new \
          -x509 -sha256 -days 365 -out domain.crt

Fill out the prompted questions to complete the CSR.

Video Setup
-------------------------------------------

Selecting a Video Source and Max Frame Rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ICE RemoteWare software currently supports these video sources: ``x11``,
``nvfbc``, ``stream``, ``windda``, and ``default``.

* The ``x11`` video source uses software encoding and only works for
  Linux systems.  It supports a max frame rate of up to 60 fps.

* The ``nvfbc`` video source is for Linux systems with an NVIDIA GPU
  and driver that support NVIDIA GRID or NVIDIA NvFBC.  It supports a
  max frame rate of up to 60 fps.

* The ``windda`` video source is optimized for Windows and supports a
  max frame rate of up to 60 fps.

* The ``stream`` video source uses software encoding and is available
  on all operating systems.  This video source supports a max frame
  rate of up to 60 fps on ARM-based Macs and 30 fps on all other
  systems.

* The ``default`` video source selects the default video source
  for your system:  
    
    * On Windows systems, ``windda`` is selected. 

    * On Linux systems, ``x11`` is selected. .  

    * On MacOS systems, ``stream`` is selected.

The table below summarizes the default and configurable maximum frame
rate settings for each video source:

  =================  =====================  =========================
  Video Source       Default MaxFrameRate   Configurable MaxFrameRate
  =================  =====================  =========================
  x11 (Linux)        30                     60
  stream (Linux)     30                     30
  nvfbc (Linux)      30                     60
  default (Linux)    see: x11               see: x11
  windda (Windows)   30                     60
  stream (Window)    30                     30
  default (Windows)  see: windda (Windows)  see: windda (Windows)
  stream (MacOS)     30                     60
  default (MacOS)    see: stream (MacOS)    see: stream (MacOS)
  =================  =====================  =========================

By default, the maximum frame rate is set to 30.  To enable a maximum
frame rate of 60 fps for the supported cases listed above, set
``Server.Video.Encoding.H264.MaxFrameRate`` in the config file.  See
:ref:`Server.Video.Encoding.H264.MaxFrameRate` for more information.

To change the video source, see :ref:`Server.Video.VideoSource` for more
information.

.. _ChangeResolution:

Change Screen Resolution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. warning:: Changing screen resolutions has these known issues:

  #. **Multiple rapid resolution changes may lead to service
     instability.** Changing the screen resolution more than 5 times
     over a few seconds may cause the service to restart or quit.

  #. **Windows users with an NVIDIA graphics card should use the
     NVIDIA Control Panel to change screen resolution.**

Change your screen resolution by using the provided Linux OS
tools (dependent on distribution).

In Windows, right-click on the desktop and select ``Screen resolution``.
Change the resolution dropdown to your desired resolution and then click ``OK``.

Downscale Screen Resolution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

System administrators have the ability to restrict the maximum screen
resolution in the config file at ``ice-remoteware.xml`` using the
``Server.Video.MaxWidth`` and ``Server.Video.MaxHeight`` settings.
This is useful for preventing clients from being overwhelmed by the
processing power required to work with high-resolution video.

If the user attempts to use a higher screen resolution, the user will
get an alert and the video will be scaled down.

.. _Enable4K:

Enable 4K Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As of v7.0.0 it is possible to support 4K desktops with the native,
non-browser based client.  This feature is not enabled by default and
requires a configuration file change to disable the default
screen size and bitrate caps.  We recommend having a downlink of at
least 20 Mbps to support the increased screen size.

In future releases 4K support will be enabled automatically.

.. note:: If you are not going to use 4K resolutions, then leave the
          following settings at their defaults by commenting them out
          or deleting them from the config file.  The default screen
          size and bitrate caps are used to ensure a good user
          experience for slower clients.

To enable 4K support:

  #. Open the xml config file.

  #. Uncomment the ``Server.Video.MaxWidth`` and ``Server.Video.MaxHeight``
     tags and set the values to ``-1`` to disable the resolution cap.

  #. Save the config file and restart the service.

.. _VideoBitRateSelection:

Configure Video Bit-Rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As of v9.1.9, the default video bit-rate is calculated by using a
linear regression of two values: 3000 kbps at 1280x720 and 6000 kbps
at 1920x1080.  A system administrator can customize bit-rates for
different resolutions by adding two or more resolution and bit-rate
pairings within the ``Server.Video.AvgBitRate`` config file setting.
The syntax is as follows::

  <width>x<height>=<bitrate>,<width>x<height>=<bitrate>,...

**Example 1**: The following is equivalent to the default bit-rate
values: ``1280x720=3000k,1920x1080=6000k``.

**Example 2**: The following can be used to specify a single average
bit-rate setting across all resolutions: ``1024x768=2m,1600x900=2m``.

The linear regression algorithm is based on the two closest
resolutions to allow a fine-grained bit-rate control.  If the value
only specifies one resolution and bit-rate, the service will use
the specified average bit-rate for all resolutions.


.. _Doc.Setup.Customization:

Local-site Customization
--------------------------------------------------------------------------

You can modify the text and header fields on the ICE RemoteWare sign-in page.
This allows you to guide users when connecting to the remote server by adding
text for special purpose servers or by reminding users of special policies
on a host. You can also change sign-in page if you have a customized
authentication method like using a smart card generated key login token rather
than a password. 

See :ref:`Doc.Glossary.Customization` for a list of possible adjustments.


.. _Doc.Setup.Notifications:

User Notifications
--------------------------------------------------------------------------

ICE RemoteWare displays by default a message on the server OS when a new user connects
to the server mentioning user name and remote ip address. This behavior and the timeout
of the notifications can be controlled by the configuration.

See :ref:`Doc.Glossary.Notifications`

.. _Doc.Setup.MultiServer:

Multi Server (Linux only)
-------------------------------------

The ICE RemoteWare™ system can be set up to run multiple server instances as services on a single host
machine.  For example, this can be used to provide access to different X11 sessions on the same machine.  In order to configure an installation this way, a few steps have to be undertaken:

1. Choose short and descriptive names for the services.

   In the following text, we will use 'gpu0' and 'gpu1' to identify the services.

2. Disable the 'default service' using the ``systemctl`` command::

    sudo systemctl stop ice-remoteware.service
    sudo systemctl disable ice-remoteware.service

3. Run the following script with the service name as a parameter to configurate each service::

    sudo /opt/ice-remoteware/bin/setup-service-instances.sh <SERVICE_ID>

   e.g.::

    sudo /opt/ice-remoteware/bin/setup-service-instances.sh gpu0
    sudo /opt/ice-remoteware/bin/setup-service-instances.sh gpu1

The script creates a configuration file for each service. The file is named /opt/ice-remoteware//opt/ice-remoteware-<SERVICE_ID>.xml. In our example, it creates /opt/ice-remoteware//opt/ice-remoteware-gpu0.xml and /opt/ice-remoteware//opt/ice-remoteware-gpu1.xml

4. Update the parameters of the newly created configuration file(s).

a. Define a unique port number under which the services are readable. See :ref:`Server.Network.Port` for details.
b. Adjust firewall settings to allow external hosts to reach the services. 
c. If the services should access different X11 servers, change either the X11 display ID or the X11 seat. See :ref:`Server.X11.Seat` and :ref:`Server.X11.Display` for details.


5. Enable and start the newly defined services using the ``systemctl`` command::

    sudo systemctl enable ice-remoteware@<SERVICE_ID>.service
    sudo systemctl start ice-remoteware@<SERVICE_ID>.service

   e.g.::

    sudo systemctl enable ice-remoteware@gpu0.service
    sudo systemctl start ice-remoteware@gpu0.service

    sudo systemctl enable ice-remoteware@gpu1.service
    sudo systemctl start ice-remoteware@gpu1.service


6. When you want to remove the services use the following commands::

    sudo systemctl stop ice-remoteware@<SERVICE_ID>.service
    sudo systemctl disable ice-remoteware@<SERVICE_ID>.service
    sudo systemctl daemon-reload

   e.g.::

    sudo systemctl stop ice-remoteware@gpu0.service
    sudo systemctl disable ice-remoteware@gpu0.service
    sudo systemctl daemon-reload


.. _Doc.Setup.MultiSession:

Multi Session (Linux only)
-------------------------------------

The Multi Session feature allows multiple users to run their own sessions
concurrently. When Multi Session is enabled, an X-server and an ICE RemoteWare server
are started for each user. After the start of the X-server, the ICE RemoteWare software
connects the user to the user's specific X-server. This feature is different from the 
collaboration feature, which allows multiple users to connect to the same 
X-server.

The spawned sessions can be monitored by standard tools, e.g. querying the status using systemctl::

  [root@localhost]# systemctl list-units | grep irw
    irw-session-user-a-9202.service  loaded active running   "ICE RemoteWare guest session, user user-a"
    irw-session-user-b-9203.service  loaded active running   "ICE RemoteWare guest session, user user-b"

or shutting a single session down::

  [root@localhost]# systemctl stop irw-session-user-b-9203.service


Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Multi Session requires the installation of one additional X11 server, named Xvfb.  

1. Install virtual X-server::

    sudo dnf install xorg-x11-server-Xvfb -y   # RedHat/Rocky

    sudo apt install xvfb -y                   # Ubuntu

2. Disable Wayland and replace with X11 by either editing
   ``/etc/gdm*/custom.conf`` and uncommenting 
   '#WaylandEnable=false/WaylandEnable=false' or by executing the following 
   command::

    sudo sed -i 's/\#WaylandEnable=false/WaylandEnable=false/' /etc/gdm*/custom.conf

3. Temporarily disable firewall for testing purposes::

    sudo systemctl stop firewalld     # RedHat/Rocky

    sudo systemctl stop ufw           # Ubuntu


.. attention:: If you run the server on a cloud system, check if the cloud service provider
                 uses a global firewall independent of the host's settings. If there is a global
                 firewall, you need to open individual ports depending on the server's setup. 
                 
                 See :ref:`Server.MultiSession.PortNumbersBegin` and :ref:`Server.MultiSession.PortNumbersEnd`

4. Enable the ICE RemoteWare Multi Session feature by using the ``Advanced Settings Tool``
   in the client UI or by editing ``/opt/ice-remoteware/ice-remoteware.xml`` and adding the following lines::

    <Server>
     ...
      <MultiSession Enabled="true">
     ...
    </Server>

5. Restart the ``ice-remoteware`` service::

    sudo systemctl restart ice-remoteware


6. Patch the Gnome Display Manager setup::

    sudo bash /opt/ice-remoteware/bin/setup-multisession-host.sh

   This will enable the guest sessions to run in parallel with any host X11 sessions

By default, users connect to the newly spawned sessions. Only the configuration file user
(if set up) can access the host X server by default. Use the :ref:`Server.MultiSession.HostAdmins` configuration setting to grant access to the host X session to selected users.

Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We provide an example configuration file at ``examples/configs/ice-remoteware.MultiSession.xml``.
This file can be used as a starting point to configure the server. 

- Port Range

  After a user logs in, the ICE RemoteWare software assigns a dedicated port to 
  the user's session. The range of available ports is set using the  
  :ref:`Server.MultiSession.PortNumbersBegin` and
  :ref:`Server.MultiSession.PortNumbersEnd` settings.

- Number of Allowed Concurrent User Sessions

  The maximum number of users who can login concurrently is set using the 
  :ref:`Server.MultiSession.MaxClients` setting.

- Desktop Resolution of User Sessions

  The dimensions of the desktop size for all user sessions is set using the 
  :ref:`Server.MultiSession.Guests.DefaultWidth` and :ref:`Server.MultiSession.Guests.DefaultHeight`
  settings.

.. _Doc.Setup.MultiSession.Security:

Security
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By running the guest session as a service, the user session is isolated
from the rest of the system. Currently there are two settings natively supported
by the server:

- HidePIDs

  This setting will trigger the server to remount the ``/proc`` filesystem with the
  option ``hidepid=2`` as soon as the first guest session starts. This will hide all
  process entries in the directory from other users.
  Please note that the changes apply to all users on the server. If certain users need
  to see all pids, you need to create a group and add these users to it. Then
  set the value of :ref:`Server.MultiSession.Secure.HidePIDs.GroupID` to the
  newly created group id.

  See :ref:`Server.MultiSession.Secure.HidePIDs.Enabled`

- PrivateTmp

  This setting will create an overlay of the ``/tmp`` and ``/var/tmp`` directories
  for the service process. This way no data is shared between the users of the server in
  these directories.

  See :ref:`Server.MultiSession.Secure.PrivTmp.Enabled`


Usage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1.  Open a browser and connect to the remote server. 
2.  Enter the user's credentials.  

The user is connected to their desktop.

.. note::

   - For each user who connects, a new X-server is started. When the user 
     stops the session, the X-server is shut down. When the user decides to sign
     out, the session will be kept alive after the user disconnects. This way the
     user can reconnect to the session later.
   - The number of users that can connect concurrently is not limited other than 
     by the resource limitations of the remote server.


GPU Forwarding
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When GPU Forwarding is enabled, set by :ref:`Server.MultiSession.GPUForwarding.Enabled`,
the host server assumes that X11 Xscreens are assigned to a separate GPU and uses this
information to distribute the GPUs evenly to the guest sessions.

The guest session defines the ``VGL_DISPLAY`` environment variable which routes all OpenGL calls to
the appropriate GPU.

Setup
............................................................................
To take advantage of the assigned GPU, the user needs to start any OpenGL program with the helper tool
``vglrun``. This tool will route any OpenGL call to the assigned GPU.


To install ``vglrun`` on RPM-based Linux systems::

    sudo dnf install VirtualGL -y

To install ``vglrun`` on Debian-based Linux systems, download the latest package from the `official VGL website <https://sourceforge.net/projects/virtualgl/files/>`_ and install the downloaded package::

    sudo apt install ./virtualgl_<VERSION>_amd64.deb -y

Test GPU Forwarding
............................................................................

1. Log in to the server as a guest user.

2. In the guest session, open a terminal and run the ``glxgears`` program in a terminal:: 

    glxgears

The program reports the frames per second it can render. Because this is done in software, the numbers should be low.

3. Run the program again with GPU support::

    vglrun glxgears

Because the OpenGL calls are processed by the assigned GPU, the number of frames per second should be significantly higher.


Transparent launch of OpenGL programs
............................................................................

As it is not always possible to prefix all calls to programs with vglrun,
we provide a simple launcher application called ``vgllauncher`` to simplify
automatic GPU assignment.

Depending on your setup, ``vgllauncher`` operates in two modes to support
different usage scenarios. Both modes is in common, that the administrator creates a link
on the launcher, which is named like the executable which should be assigned to a GPU.
The launcher will then locate the target and start it with ``vglrun`` support


- Configuration based on PATH variable

  This is the preferable setup method, but it is more dependent on the way the applications are
  started. Two steps are required. First, the administrator needs to create a directory and links to
  the target executables, e.g.::

    mkdir /usr/share/vgl-bin
    cd  /usr/share/vgl-bin
    ln -s /opt/ice-remoteware/bin/vgllauncher glxgears

  In a second step, the users' environments have to be altered to make the newly created directory the first
  directory in the path variable, e.g.::

    export PATH=/usr/share/vgl-bin:${PATH}

  After reloading the environment all calls to glxgears will be intercepted by the launcher and handed
  over to ``vglrun``.


- Configuration based on modifying file names

  When the application is started by scripts which modify the PATH variable themselves, the setting up the
  system like descripted before might impose various problems. In these cases, it might be easier to follow
  this approach:

  The system administrator has to rename the executables within the original application directory by
  appending the fixed extension ``.vgl-orig`` to the file name. In a second step a link to
  the launcher is created with the original name of the executable, e.g.::

    cd /usr/bin
    mv glxgears glxgears.vgl-orig
    ln -s /opt/ice-remoteware/bin/vgllauncher glxgears

  This way the launcher is called independently of the user's path setting. This is more invasive than the
  first method and will require some clean-up before updating or after deinstalling the application.

When problems show up, set ``VGL_LOG_INFO`` or ``VGL_LOG_DEBUG`` and run the program again. The output shows in
detail which paths are considered and where the executables are found.::

   VGL_LOG_INFO=1 glxgears



.. _Doc.Setup.GPUForwarding.Security:

Security Considerations with GPU Forwarding
............................................................................
As the guest sessions have access to the host's X11 server to render on their assigned GPU, the host's X11 user session might expose resources to the users of the guest sessions.

When :ref:`Server.MultiSession.SecureAdminLogin` is set to true, the host server goes into maintenance mode as soon as an unlocked X11 session is running on the host. In this mode it will disable all guest sessions in order to prevent any risks of malicious user trying to access any private resources of the host session . When the host server's X11 session is terminated, it will then allow users to create guest sessions again, but disable any pasting of passwords into the OS to secure the login session as well.

Any remote ``ssh`` access is unaffected as no X11 resources will be shared.  


Limitations
............................................................................
When Multi-Session is enabled, audio is not supported on the host session.

On Ubuntu guest sessions can't execute any applications which are installed as ``snap(8)`` applicaton from the GUI. There is a disagreement between the ``snapd`` and the guest gnome-session about the proper dbus address. There are two work arounds

- Install the non-snapped version of the applications

- Modify the users' shell environment and start the application from a terminal.

The guest server sets an environment variable ``DBUS_SESSION_BUS_ADDRESS_SNAP`` to simplify user setup. Add the following code to the resource file of the users' shell, e.g. into ``~/.bashrc``::

  if [[ ! -z "${DBUS_SESSION_BUS_ADDRESS_SNAP}" ]] ; then
    export DBUS_SESSION_BUS_ADDRESS=${DBUS_SESSION_BUS_ADDRESS_SNAP}
  fi

This will enable the user to start any applications from a terminal.


Troubleshooting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Make sure:

- Firewall is disabled while testing

- All required tools are installed (see Setup)
