.. _usage:

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


.. _LogOutput:

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 :ref:`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 :ref:`Doc.Setup.ServerAuthentication` 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.

.. _Doc.Usage.ToggleAudio:

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.

.. _Doc.Usage.KeyboardMenu:

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

.. _Doc.Usage.CopyText:

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 :ref:`Server.Clipboard.Copy.Enabled` to ``false``.

When multiple clients are connected, only the current Controller (see :ref:`Doc.Usage.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.


.. _Doc.Usage.PasteText:

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 :ref:`Doc.Usage.Collaboration`) can paste text into the server's clipboard.

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

.. note:: Paste with keyboard shortcuts see :ref:`Server.Clipboard.Paste.KeyboardShortcut`


.. _Doc.Usage.FileMenu:

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 :ref:`Doc.Usage.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 :ref:`Settings File Upload <Doc.Glossary.FileUpload>`

``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 :ref:`Settings File Download <Doc.Glossary.FileDownload>`

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

.. _Doc.Usage.SettingsMenu:

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. 

``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 :ref:`Doc.Usage.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 :ref:`Settings LogViewer <Doc.Glossary.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 :ref:`Doc.Usage.Collaboration`). The Client will remember the setting.

Configuration options can be found at :ref:`Settings Clipboard <Doc.Glossary.Clipboard>`

See also :ref:`Doc.Usage.CopyText`

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 :ref:`Doc.Setup.MultiSession`

.. _Doc.Usage.Collaboration:

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 :ref:`Doc.Usage.TransferContol`

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.

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.

.. _Doc.Usage.TransferContol:

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


