Skip to main content
`Ctrl`+`K`

# 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, on Linux and Windows you have the option to run the server ice-remoteware from the command line. This is usually only useful for debugging purposes.

Windows (options shortened):

    usage: ice-remoteware OPTIONS

    /help                                    Display help information on command line arguments
    /logLevel=level                          Set the log level (ex: trace, debug, information, notice, warning, error,
                                                                    critical, none)
    /version                                 Display the version number
    /application                             Run in application/console)
    /validate                                Validate installation (text or html)
    /passwd                                  Change the admin password
    /broker-passwd                           Change the broker password
    /check-license                           Check, if valid license is installed
    /writeConfigFull=[filename]              Write configuration file (all options)
    /config=filename                         Load additional configuration from file
    /setConfig=<path>=<value>                Set a specific config value
    /disableMouse                            Disable capture of mouse movements

Linux (options shortened):

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

    --help                                    Display help information on command line arguments
    --logLevel=level                          Set the log level (ex: trace, debug, information, notice, warning, error,
                                                                     critical, none)
    --version                                 Display the version number
    --application                             Run in application/console)
    --validate                                Validate installation (text or html)
    --passwd                                  Change the admin password
    --broker-passwd                           Change the broker password
    --check-license                           Check, if valid license is installed
    --writeConfigFull=[filename]              Write configuration file (all options)
    --config=filename                         Load additional configuration from file
    --setConfig=<path>=<value>                Set a specific config value
    --disableMouse                            Disable capture of mouse movements

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

1. Sign in as a user with Administrator permissions.

2. Open the Windows Start menu.

3. In the Search box, type `Command Prompt`, but don’t hit `Enter` just yet.

4. 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

## 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.Log.FileName` 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.Log.Format.

## 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 either the OS username and password, the username and password encrypted in the config file or by ScyldCloudAuth to sign in.

Consult Server Authentication on how to setup server access

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 loading screen that will turn into a remote visualization display within a few seconds. At this point you can interact with the remote operating system. Other user accounts are prevented from signing into the web service until you sign out. This doesn’t apply to the account specified in the config file.

## Main Toolbar

The main toolbar gives access to additional ICE RemoteWare features such as signing out. This menu can be hidden or shown by pressing `Ctrl+F12` or using the hide/show button at the bottom of the screen.

### 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.

### Keyboard Menu

The Keyboard Menu contains a list of special actions and keyboard button presses to transmit to the remote system. The keyboard buttons are `Ctrl-Alt-Del` (Linux and Windows) and `Print Screen`.

#### Copy Remote To Local Clipboard

`Copy From Remote Clipboard` copies plain text contents from the remote clipboard to the local clipboard.

This feature can be disabled by setting Server.Clipboard.Copy.Enabled to `false`.

When multiple clients are connected, only the current Controller (see Collaboration) can copy from the server’s into the local clipboard.

Note

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

Important

Due to the design of X11, Linux users might experience warnings about failing to copy the clipboard. Most of the time copying the buffer again will fix the problem.

#### Paste Local To Remote Clipboard

`Paste To Remote Clipboard` copies plain text contents from the local clipboard to the remote clipboard.

Some browsers require the user to confirm the control of the clipboard contents to the browser. In this case the browser will show a message which requires the user to confirm the transaction. While Chrome remembers the user’s answer, Firefox shows every time a small pop-up asking for confirmation.

When multiple clients are connected, only the current Controller (see Collaboration) can paste text into the server’s clipboard.

This feature can be disabled by setting Server.Clipboard.Paste.Enabled to `false`

Note

Paste with keyboard shortcuts see Server.Clipboard.Paste.KeyboardShortcut

### 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.

When multiple clients are connected, this control is only accessible to the current Controller (see Collaboration).

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

Configuration options can be found at Settings File Upload

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

Configuration options can be found at Settings File Download

### 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.

When multiple clients are connected, this control is only accessible to the current controller.

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 `Full Screen` view or `Fit to Window` view (see Server.Video.ServerScaling).

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

`Advanced Settings` allows administrator to configure the server from the client. Clicking on the icon opens the Advanced Settings page which exposes most of configuration variables of the server. Initially showing only the common settings, the view can be customized to show more advanced settings or show only modified values. Changing some of the values require a server restart which will disconnect all guest users and session.

When multiple clients are connected, this control is only accessible to the current Controller (see Collaboration).

When the `LogViewer` feature is enabled, administrators can open the log files of the server from the client window. A new page will be opened with the current log file loaded. While the user is logged in this page can be refreshed by the browser to update the log file shown.

Configuration options can be found at Settings LogViewer

`Auto-Sync Clipboard` is only accessible in the Native Client. When enabled the Client will sync server and client clipboards. When disabled the Keyboard Menu will show the `Copy From Remote Clipboard` and `Paste To Remote Clipboard` controls.

When multiple clients are connected, this control is only accessible to the current Controller (see Collaboration). The Client will remember the setting.

Configuration options can be found at Settings Clipboard

See also Copy Remote To Local Clipboard

The `Video Quality` slider is enabled when connecting with the Native Client and the display is not shared with other users.

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.

### User Tools Menu

The User Tools Menu provides options for inviting guests, pausing guest video streams, and removing all guests and cancelling guest invites.

## UI Keyboard Shortcuts

The following keyboard shortcuts are supported:

- `Ctrl+F11`: Toggle Fullscreen (Native Clients only)

- `Ctrl+F12`: Toggle Main Toolbar

## 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.

## End Session (Linux, MultiSession only)

When the user is connected to a Guest Session, signing out keeps the session alive to connect at a later time. `End Session` will log out the user and end the session. A later connection will initiate a new session for the user to connect to.

See Multi Session (Linux only)

# Collaboration

## Introduction

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

Hosts 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

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.

Controller

When sharing the same desktop with multiple clients exactly one client controls the session’s remote keyboard and mouse. This `Controller` has some additional privileges like e.g. remote clipboard access. This status can be transferred from one client to another. See Give Keyboard and Mouse Control

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.Collaboration.MaxClientCount` setting in the config file at `ice-remoteware.xml`.

## Collaboration Quick Start

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

1. A Host creates an Invite Link and sends it to Guest users.

2. A Guest opens the Invite Link, enters a Guest name, and requests to sign in.

3. 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.

1. Click the `Invite Guests` button.

2. 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.

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