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: Flexera License Management.

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 .

Authentication is enabled by default and in should not be disabled in production systems. 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

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:

Config File Authentication can be disabled by commenting or removing Server.Auth.Username and 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 ). 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 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:

ScyldCloudAuth can be disabled by commenting or removing 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 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 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#

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 openSSL.server.cipherList.

Client Security#

Clients and browsers that meet the requirements listed in Client Requirements 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#

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.

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 openSSL.server.requireTLSv1_2 to true and enable HTTPS by setting Server.Network.Secure to true.

Set openSSL.server.privateKeyFile and 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 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:

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 Server.Video.Encoding.H264.MaxFrameRate for more information.

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

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.

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.

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.

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 Server.Customization for a list of possible adjustments.

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 Server.UserNotifications

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:

Choose short and descriptive names for the services.

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

Disable the ‘default service’ using the systemctl command:

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

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. For the example services, it creates /opt/ice-remoteware//opt/ice-remoteware-gpu0.xml and /opt/ice-remoteware//opt/ice-remoteware-gpu1.xml

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

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

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

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.

Install virtual X-server:

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

sudo apt install xvfb -y                   # Ubuntu

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
```

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 Server.MultiSession.PortNumbersBegin and Server.MultiSession.PortNumbersEnd

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>
```
Restart the ice-remoteware service:
```
sudo systemctl restart ice-remoteware
```
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 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 Server.MultiSession.PortNumbersBegin and Server.MultiSession.PortNumbersEnd settings.
Number of Allowed Concurrent User Sessions

The maximum number of users who can login concurrently is set using the Server.MultiSession.MaxClients setting.
Desktop Resolution of User Sessions

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

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 Server.MultiSession.Secure.HidePIDs.GroupID to the newly created group id.

See 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 Server.MultiSession.Secure.PrivTmp.Enabled

Usage#

Open a browser and connect to the remote server.
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 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 and install the downloaded package:

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

Test GPU Forwarding#

Log in to the server as a guest user.
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.

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

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 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)

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)