Usage#

In this section we describe how to start and stop the ICE RemoteWare™ service in either Linux or Windows on the remote server. We then talk about how to connect and interact with the remote desktop interface.

Using the Linux Service#

To start, stop, or restart the ice-remoteware, open a terminal with root or sudo privileges and use the service command:

# Start the service
service ice-remoteware start

# Stop the service
service ice-remoteware stop

# Restart the service
service ice-remoteware restart

To run ice-remoteware directly rather than as a service, use the ice-remoteware.sh start-up script. This is usually only useful for debugging purposes. Usage information can be obtained by passing the --help flag.

usage: ice-remoteware OPTIONS
ice-remoteware -- a GPU accelerated remote desktop web service.

--daemon                                   Run application as a daemon.
--pidfile=path                             Write the process ID of the
                                           application to given file.
-h, --help                                 Display help information on command
                                           line arguments.
-vsvideosource, --videosource=videosource  Choose videosource (nvfbc, stream).
-q, --quiet                                Hide the console when running.
-pwd, --passwd                             Update the password.

Using the Windows Service#

To use the ice-remoteware service, verify that the service is registered with the OS and then start the service.

Open a Command Prompt as an Administrator#

Sign in as a user with Administrator permissions.
Open the Windows Start menu.
In the Search box, type Command Prompt, but don’t hit Enter just yet.
Right-click on the Command Prompt and select Run as administrator.

Register the Windows Service#

To register the windows service, use the ice-remoteware.exe command:

ice-remoteware.exe /registerService /startup=automatic

The ice-remoteware service will now automatically start on reboot.

Note

Service registration should already be handled by the installer. If you see the message below, verify that ice-remoteware has been properly installed. This is usually a sign that the PATH environment variables are not pointing at the ice-remoteware.exe file.

'ice-remoteware.exe' is not recognized as an internal or
 external command, operable program or batch file.

Start and Stop the Windows Service#

To start and stop the registered windows service without rebooting, use the net command:

# Start the service
net start ice-remoteware

# Stop the service
net stop ice-remoteware

Using the MacOS Service#

To start, stop, restart, or check the status of the ICE RemoteWare service, open a terminal and go to the /Applications/ICE RemoteWare.app/Contents/MacOS directory. Next, run the application with the --service flag with sudo privileges:

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

# Start the service
sudo ./ice-remoteware --service start

# Stop the service
sudo ./ice-remoteware --service stop

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

# Check the status of the service
sudo ./ice-remoteware --service status

Manually running the MacOS audio server (advanced)#

The ICE RemoteWare audio server is usually launched after a user logs in to MacOS (assuming it has been added to Login Items for that user). If this is not the case, one alternative way to temporarily launch the audio server is to open a terminal and run these commands:

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

# Start the audio server
./ice-remoteware --audio-server

Creating Config File credentials (optional)#

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.

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.

Log Output#

Log output is organized by priority levels (from highest to lowest: Fatal, Critical, Error, Warning, Notice, Information, Debug, and Trace). By default, ice-remoteware prints Information level messages to /var/log/messages.

Setting LogLevel to information will log all server starts/stops, sign-in attempts, socket connects/disconnects, video source plays/pauses, and additional warning/error messages. This is usually sufficient for production usage.

To see debug and higher level output, open the ice-remoteware.xml config file and set LogLevel to debug.

The most useful log files for the ICE RemoteWare software can be found at these locations:

# Linux:
/opt/ice-remoteware/ice-remoteware.log.

# Windows:
C:\Program Files\Penguin Solutions\ICE RemoteWare\log\ice-remoteware.log
C:\Program Files\Penguin Solutions\ICE RemoteWare\log\ice-remoteware-service.log.

# MacOS:
/var/log/com.penguinsolutions.ice-remoteware/ice-remoteware.log

Note

You can change the path of the output by opening the ice-remoteware.xml config file and setting Server.LogFile to a new destination.

By default, the ICE RemoteWare software displays a timestamp with each log message. To change the timestamp to all of your output, open the ice-remoteware.xml and set LogFormat. For more information, see Server.LogFormat.

Selecting a Video Source and Max Frame Rate#

The ICE RemoteWare software currently supports these video sources: x11, nvfbc, stream, windda, and auto (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 auto video source tries to select the best video source for your system based on what is supported.
- On Windows systems, windda is selected.
- On Linux systems that support NVIDIA GRID or NVIDIA NvFBC, nvfbc is selected (otherwise 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

auto (Linux)

see: x11 or nvfbc

see: x11 or nvfbc

windda (Windows)

30

60

stream (Window)

30

30

auto (Windows)

see: windda (Windows)

see: windda (Windows)

stream (MacOS)

30

60

auto (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.VideoSource for more information.

Sign In#

Once the ICE RemoteWare server starts, users can connect their networked client to the server by typing the server’s URL into a web browser. Servers using the HTTPS protocol (default) have URLs like this: https://<server-hostname-or-ip>.

This will take you to the ICE RemoteWare sign-in page. Enter the username and password encrypted in the config file or by ScyldCloudAuth to sign in. You can also use your OS specific credentials to sign in.

Important

While config file or ScyldCloudAuth usernames can be used to sign in to the ICE RemoteWare software 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.

After signing in, you will see a gray canvas that will turn into a remote visualization display within a few seconds. At this point you can interact with the remote operating system. Other users are prevented from signing into the web service until you sign out.

Toggle Audio#

Click the Toggle Audio Streaming button to begin streaming the default audio output device of the remote server. The default output device is managed through your remote operating system’s audio device interface.

Note

For Linux users, Puleaudio version 10.0+ is required.

File Handling Menu#

The File Handling Menu contains support for uploading and downloading files to and from the server. When either of those actions is active, the server displays information about the transfer progress.

Upload Files to Server opens a file explorer on the client to select one or multiple files to be uploaded to server. Alternatively, you can select the files in the client OS file explorer and drag a selection of files to the canvas to be uploaded.

Download Files from Server initiates a transfer of a list of files from the server to the client. The user selects files to be copied to the client by selecting the files in a file browser and pressing the [CTRL] + [C] keys (Windows & Linux). If no files are selected, the server will try to copy all files in the upload directory. See Server.FileDownload.Directory for more information.

USB Menu#

The USB Menu contains a list of USB devices that can be forwarded to the remote server. This menu only appears if you’ve purchased a license for USB Forwarding, you are a host user, and you are the controller of the remote keyboard.

Note

USB Forwarded devices will disconnect every time a user:

disconnects from the ICE RemoteWare service
signs in or signs out of the remote OS
adds or removes a monitor on the remote server
loses controller status (gives up remote keyboard control)

sudo modprobe -r hid_wacom wacom wacom_w8001
sudo modprobe -a hid_wacom wacom wacom_w8001

Settings Menu#

The Settings Menu provides options for adjusting view, monitoring performance, and selecting between three video quality settings (this last option is available to native client users only). If video is being downscaled it also provides a status message.

You can adjust the view settings by toggling Fit to Window view or Full Screen view.

Performance Monitor adds a pop-up at the bottom of the remote desktop window that displays current frames per second (FPS), ping speed (in ms), and video bandwidth (in Kbps). You can close the pop-up by either clicking the X on the pop-up or by toggling Performance Monitor under the Settings menu.

Higher quality video settings result in better color accuracy at the cost of higher bandwidth usage and lower frame-rates. The three video quality settings are: normal (lossy with best frame-rate and lowest bandwidth usage), visually lossless (close to lossless quality with better frame rates and lower bandwidth usage), and truly lossless.

Important

Enabling lossless video on a downscaled video may improve image quality, but is not truly lossless.

Important

Currently only normal video quality is available when multiple users are signed in.

Paste Text from the Local Clipboard#

Text can be pasted from the local client into the remote desktop.

To paste text from a local Linux / Windows clipboard into a remote Linux / Windows desktop, press Ctrl+V.

To paste text from a local MacOS clipboard to a remote Linux / Windows desktop, use your browser’s menu system to select Edit > Paste. This transfers the local clipboard to the remote clipboard. Once this is done, you can use Ctrl+V or use your remote application’s paste feature.

The server administrator can turn off this feature by setting Server.Paste.Enabled to false in ice-remoteware.xml.

Note

Only characters that are supported by both the client and server can be pasted.

Copy Text to the Local Clipboard#

Select Copy Remote Clipboard from the Keyboard Menu to copy plain text from the remote clipboard to the local clipboard.

This feature can be disabled by setting Server.Copy.Enabled to false in the configuration file.

UI Keyboard Shortcuts#

The following keyboard shortcuts are supported:

Ctrl+F11: Toggle Fullscreen (Native Clients only)
Ctrl+F12: Toggle Main Toolbar

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.

Sign Out#

Linux, Windows, and MacOS users change users by using the remote OS’s log out / log in feature. The ICE RemoteWare software does not support “fast user switching” and the service must be restarted if this happens.

Closing your browser or signing out of the ICE RemoteWare session does not sign you out of the remote operating system. Use the remote OS’s signing-out capability to sign out of the remote OS.

Collaboration#

Multiple users can share control of the same desktop. There are two types of users in this case: regular Host users and temporary Guest users.

Hosts are are fully trusted users who have an account on the system and have complete control over what a Guest can access. An ongoing session begins when one Host is signed in and ends when the last Host leaves. All Guests and Invites are removed when an ongoing session ends.

Guests are users who are invited to join an ongoing session. As a Host, this can be useful when you want to share a workstation with a remote colleague who should not have a permanent account on the system.

This section describes how a Host adds and manages Guest users.

Important

The Guest alerts and interface buttons described below are not visible in fullscreen mode.

Set the maximum number of concurrent clients#

By default the server only allows 6 users to be signed on at any given time. This number can be changed by a system administrator by adding a Server.MultiUser.MaxClientCount setting in the config file at ice-remoteware.xml.

Collaboration Quick Start#

At a high level, adding a new guest involves three steps:

A Host creates an Invite Link and sends it to Guest users.
A Guest opens the Invite Link, enters a Guest name, and requests to sign in.
A Host accepts the Guest’s sign in request.

Hosts can use the control buttons to pause video to all Guests or ban all Guests and revoke all pending Invites. Hosts can also click on user buttons to remove individual Guests or give keyboard and mouse control.

Control Buttons#

At the top of the screen there are a row of buttons that allow you to type special keys such as Ctrl-Alt-Del, add guests, pause all guest video, ban all guests, and sign out. Press Ctrl+F12 to show / hide these buttons.

Add New Guests#

Hosts can invite a group of guests by creating an Invite Link.

Click the Invite Guests button.
In the window that appears, specify how many guest sign ins you’d like this link to be accommodate. It is recommended to select the minimum number you will need.
The generated Invite Link is shown. Copy and send this link to Guest users and then close the window.

Warning

Anyone who receives an Invite Link can request Guest access to your system. While these links expire over time and are limited by how often they can be used, it is best practice to keep this link confidential.

When Guests use this link to request a sign in, an alert appears to all Hosts asking whether the user should be Accepted or Declined.

Important

It is best practice to verify the incoming user’s identity via a phone call, text message, or other trusted communication channel.

When a Guest signs in, their username is reserved until all Hosts sign out. Guest usernames must be unique and consist of only letters, numbers, and underscores. Once the session ends, all Guest usernames are freed for use again.

Pause Guest Video#

Guest video can be toggled by clicking on the Pause Guests button. Guest usernames will be greyed out when guest video is paused. Click Resume Guests to re-enable guest video.

Remove Guests and Cancel Invites#

Guests can be removed from the session either individually using the Kick action from their username or all at the same time using the Remove Guests and Cancel Invites button from the User Tools menu. Hosts cannot be banned.

User Buttons#

At the bottom of the screen there are a row of buttons containing usernames and status icons. The first button will always be “You”, indicating the user button for the user signing in. Clicking on the user button will show status information (including frame rate) and actions that can be taken on that user, such as kicking or giving keyboard / mouse control.

Usernames that end with an asterisk are Hosts. Press Ctrl+F12 to show / hide these buttons.

Give Keyboard and Mouse Control#

A Host can give any other user control of the keyboard and mouse using the Give Keyboard and Mouse Control button from the username. The host can regain control using the Take Keyboard and Mouse button from their own user buttons (You).

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 is started for each user who connects to the ICE RemoteWare server (requires that XWayland is disabled). After the X-server starts, 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.

Prerequisites#

Installation of the latest ICE RemoteWare version
Enable the ICE RemoteWare multi session feature by setting Server.MultiSession.Enabled to true, either by using the ICE RemoteWare Advanced Settings menu or by editing ice-remoteware.xml

Setup on Debian-based Linux Systems#

Install SSH server and client:

sudo apt install openssh-client openssh-server

Install virtual X-servers:

sudo apt install xvfb xserver-xephyr -y

Install xdotool:
```
sudo apt install xdotool -y
```
Disable Wayland and replace with X11 by either editing /etc/gdm3/custom.conf and uncommenting ‘#WaylandEnable=false/WaylandEnable=false’ or by executing the following command:
```
sed -i 's/\#WaylandEnable=false/WaylandEnable=false/' /etc/gdm3/custom.conf
```
Temporarily disable firewall for testing purposes:
```
sudo systemctl stop ufw
```
Enable the ICE RemoteWare multi session feature by editing /opt/ice-remoteware/ice-remoteware.xml and adding the following lines:
```
<Server>
 ...
  <MultiSession>
    <Enabled>true<Enabled>
  </MultiSession>
 ...
</Server>
```
Start the ice-remoteware service:
```
systemctl start ice-remoteware
```

Setup on RPM-based Linux systems#

Install SSH server and client:
```
sudo dnf install openssh-server -y
```

Install virtual X-servers:

sudo dnf install xorg-x11-server-Xvfb xorg-x11-server-Xephyr -y

Install xdotool:
```
sudo dnf xdotool -y
```
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:
```
sed -i 's/\#WaylandEnable=false/WaylandEnable=false/' /etc/gdm/custom.conf
```
Temporarily disable firewall for testing purposes:
```
sudo systemctl stop firewalld
```
Enable the ICE RemoteWare multi session feature by editing /opt/ice-remoteware/ice-remoteware.xml and adding the following lines:
```
<Server>
 ...
  <MultiSession>
   <Enabled>true<Enabled>
  </MultiSession>
 ...
 </Server>
```
Start the ice-remoteware service:
```
systemctl start ice-remoteware
```

Configuration#

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.
Guest X-server Binary

Every time a user logs into the remote server, a new guest X-server is started and assigned to that user. The software supports Xvfb and Xephyr as guest X-servers, which can be set using the Server.MultiSession.XServer.Name setting.
Desktop Resolution of User Sessions

The dimensions of the desktop size for all user sessions is set using the Server.MultiSession.Guest.Width and Server.MultiSession.Guest.Height settings.

User Setup#

For each user who will log in to the remote server via the ICE RemoteWare software:

On the ICE RemoteWare server, create a public/private SSH key pair for each user.

Edit ~<username>/.ssh/config and add the following lines:

Host localhost
Port <ssh port>;  #This is optional if ssh port is set to 22 (default)
IdentityFile <Path to public ssh key>

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 disconnects, the X-server is shut down.
The number of users that can connect concurrently is not limited other than by the resource limitations of the remote server.
If you use Xephyr as the guest X-server, you will have to log into the host X-server initially and make sure to deactivate any screen saver

Troubleshooting#

Make sure:

Firewall is disabled while testing
~/.ssh/config is populated
All required tools are installed (see Setup)
Public and Private keys are created
~<username>/.ssh/config is populated

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

Usage#

Using the Linux Service#

Using the Windows Service#

Open a Command Prompt as an Administrator#

Register the Windows Service#

Start and Stop the Windows Service#

Using the MacOS Service#

Manually running the MacOS audio server (advanced)#

Creating Config File credentials (optional)#

Log Output#

Selecting a Video Source and Max Frame Rate#

Sign In#

Main Toolbar#

Toggle Audio#

Keyboard Menu#

File Handling Menu#

USB Menu#

Settings Menu#

User Tools Menu#

Paste Text from the Local Clipboard#

Copy Text to the Local Clipboard#

UI Keyboard Shortcuts#

Change Screen Resolution#

Downscale Screen Resolution#

Enable 4K Support#

Configure Video Bit-Rate#

Sign Out#

Collaboration#

Set the maximum number of concurrent clients#

Collaboration Quick Start#

Control Buttons#

Add New Guests#

Pause Guest Video#

Remove Guests and Cancel Invites#

User Buttons#

Give Keyboard and Mouse Control#

Multi Session (Linux only)#

Prerequisites#

Setup on Debian-based Linux Systems#

Setup on RPM-based Linux systems#

Configuration#

User Setup#

Usage#

Troubleshooting#