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#
Sign in as a user with Administrator permissions.
Open the Windows Start menu.
In the Search box, type
Command Prompt
, but don’t hitEnter
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
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.
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.
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:
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.
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.
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).