.. _install:

Installation
++++++++++++++++++++++++++++++++++++++++++++

Learn more about installing the ICE RemoteWare™ server and client. 

Server Installation
=============================================

The ICE RemoteWare server can be installed on the following operating
systems:

* Rocky Linux 8 and 9
* Windows 10, 11, and Windows Server 2019
* Windows Server 2022 (server-side only)
* MacOS Monterey 12 to MacOS Sonoma 14
* Ubuntu 20, 22 and 24

Required Files
-----------------------------------------------------------

Installation packages and documentation can be downloaded from:
https://updates.penguincomputing.com/irw/download/.  Rocky, CentOS and RHEL users should
add the repository as a YUM repo using the OS-specific instructions
that follow.

Installation of the ICE RemoteWare server requires the following files:

* The ICE RemoteWare server installation package for your operating
  system:

  - Rocky Linux 8: ``ice-remoteware-16.0.0-0.el8.x86_64.rpm``
  - Rocky Linux 9: ``ice-remoteware-16.0.0-0.el9.x86_64.rpm``
  - Ubuntu 20: ``ice-remoteware_16.0.0.0-0ubuntu1.20_amd64.deb``
  - Ubuntu 22: ``ice-remoteware_16.0.0.0-0ubuntu1.22_amd64.deb``
  - Ubuntu 24: ``ice-remoteware_16.0.0.0-0ubuntu1.24_amd64.deb``
  - Windows 10, 11, and Windows Server 2019, 2022: ``ICE RemoteWare-16.0.0.0.msi``
  - MacOS Monterey 12 to MacOS Sonoma 14: ``ice-remoteware-16.0.0.0.pkg``

* One of the following:

  - A trial license file (``ice-remoteware.lic``)
  - A floating license file (``ice-flexlm.lic``) and
    the license server (ICE FlexLM).

.. _RockyLinuxInstall:

Installing the Server on Rocky Linux
-----------------------------------------------------------

Follow the steps below to install the ICE RemoteWare server, replace the default 
SSL key and certificate files, install the license file, and change your
X server from XWayland to Xorg.  After a service restart, you
should be able to sign in with standard OS credentials.

1. Use the ``wget`` command to install the ICE RemoteWare YUM repository
   for your version of Rocky Linux:

   .. code-block:: bash

      % ## Rocky Linux 8 only
      % sudo wget https://updates.penguincomputing.com/irw/irw-el8.repo -P /etc/yum.repos.d

      % ## Rocky Linux 9 only
      % sudo wget https://updates.penguincomputing.com/irw/irw-el9.repo -P /etc/yum.repos.d

2. Use the ``yum install`` command to install ``ice-remoteware``.

   .. code-block:: bash

      % sudo yum install -y ice-remoteware

   The installer does the following:

   * Installs ICE RemoteWare files to ``/opt/ice-remoteware``
   * Installs ice-remoteware.service to ``/lib/systemd/system/``
   * Reloads the systemd manager configuration using ``systemctl daemon-reload``
   * Enables the unit file with ``systemctl enable ice-remoteware.service``

3. If you have a trusted SSL certificate for your server's domain,
   open the configuration file
   (``/opt/ice-remoteware/ice-remoteware.xml``) and set the value
   of ``openssl.server.privateKeyFile`` and
   ``openssl.server.certificateFile`` to its path.  Using a trusted SSL
   certificate is recommended for maximum security.

4. Install the license.

   - If you have a trial license (``ice-remoteware.lic``),
     copy it into ``/opt/ice-remoteware/bin``.

   - If you have a floating license
     (``ice-flexlm.lic``), proceed to
     :ref:`LicenseManagement` for instructions on installing
     ICE FlexLM.

5. Verify that your firewall rules allow traffic over HTTPS (port 443).

6. ONLY IF you are using XWayland as your X server (enabled by default
   in Rocky Linux), enable Xorg by following these steps:

   a. Open editor to open: ``/etc/gdm/custom.conf``

   b. Look for the lines below:

      .. code-block:: ini

         [daemon]
         # Uncomment the line below to force the login screen to use Xorg
         #WaylandEnable=false

   c. Uncomment (remove the '#') preceding the 'WaylandEnable'
      variable.

   d. Save the file and reboot the system.  The service will start
      after the reboot.

7. Use the ``systemctl restart`` command to restart the service:

   .. code-block:: bash

      % sudo systemctl restart ice-remoteware.service

8. OPTIONAL: To enable USB Forwarding features, see
   :ref:`RockyLinuxInstallServerUsbModule`.

The ICE RemoteWare product should now be reachable over HTTPS at your server's
hostname or IP address.  For advanced configuration options, please
see :ref:`Setup`.

.. _RockyLinuxInstallServerUsbModule:

Installing Server-USB Module on Rocky Linux
-----------------------------------------------------------

USB devices can be forwarded between native clients and remote servers
that meet the following requirements:

1. The server's license file must have a valid
   'irw-usb' entitlement.  If you do not see this
   entitlement in your license file, please contact Penguin Solutions sales
   for more information.
2. The Server-USB module must be installed on the remote server.
3. The Client-USB module must be installed on the client side.
   See :ref:`InstallClientUsbModule` for more information on this step.

To install the Server-USB modules:

1. Use the ``yum`` command to install
   ``ice-remoteware-server-usb-module``.

   .. code-block:: bash

      % sudo yum install -y ice-remoteware-server-usb-module

2. Use the ``systemctl restart`` command to restart
   the service:

   .. code-block:: bash

      % sudo systemctl restart ice-remoteware.service

.. _Win7Install:

Installing the Server on Windows
-----------------------------------------------------------

.. note:: For virt-manager users: virt-manager's graphical console
   will no longer work after installing the NVIDIA GRID driver and
   restarting Windows.

   To get the virt-manager graphical console to work again, start the
   Windows VM in 'Safe Mode' by restarting the VM, commanding it to
   "Force Off", and restarting the VM again.  Select "Safe Mode with
   Networking" from the menu that appears.

1. Download ``ICE RemoteWare-16.0.0.0.msi`` from
   https://updates.penguincomputing.com/irw/download/

2. Double-click on the ``ICE RemoteWare-16.0.0.0.msi`` installer.

3. Follow the instructions in the GUI.

4. If your server's domain has a trusted SSL certificate, open the
   configuration file (``C:\Program Files\Penguin Solutions\ICE RemoteWare\ice-remoteware.xml``)
   and set the value of ``openssl.server.privateKeyFile`` and
   ``openssl.server.certificateFile`` to its path.  Using a trusted SSL
   certificate is recommended for maximum security.

5. Install the license.

   - If you have a trial license (``ice-remoteware.lic``),
     copy it into ``C:\Program Files\Penguin Solutions\ICE RemoteWare``.

   - If you have a floating license
     (``ice-flexlm.lic``), proceed to
     :ref:`LicenseManagement` for instructions on installing
     ICE FlexLM.

6. OPTIONAL: To enable USB Forwarding features, see
   :ref:`Win7InstallServerUsbModule`.

The ICE RemoteWare product should now be reachable over HTTPS at your server's
hostname or IP address.  For advanced configuration options, please
see :ref:`Setup`.

.. _Win7InstallServerUsbModule:

Installing Server-USB Module on Windows
-----------------------------------------------------------

USB devices can be forwarded between native clients and remote servers
that meet the following requirements:

1. The server's license file must have a valid
   'irw-usb' entitlement.  If you do not see this
   entitlement in your license file, please contact Penguin Solutions sales
   for more information.
2. The Server-USB module must be installed on the remote server.
3. The Client-USB module must be installed on the client side.  See
   :ref:`InstallClientUsbModule` for more information on this step.

To install the Server-USB modules on the remote server:

1. Download ``ICE RemoteWare Server USB Module-16.0.0.0.msi`` from
   https://updates.penguincomputing.com/irw/download/

2. Double-click on the ``ICE RemoteWare Server USB Module-16.0.0.0.msi`` installer.

3. Follow the instructions in the GUI.

.. _UbuntuInstall:

Installing the Server on Ubuntu
-----------------------------------------------------------

Follow the steps below to install the ICE RemoteWare server, replace the default 
SSL key and certificate files, and install the license file.  After a
service restart, you should be able to sign in with standard OS
credentials.

1. Download the debian installer for your Ubuntu version from
   https://updates.penguincomputing.com/irw/download/

   * Ubuntu 20: ``ice-remoteware_16.0.0.0-0ubuntu1.20_amd64.deb``

   * Ubuntu 22: ``ice-remoteware_16.0.0.0-0ubuntu1.22_amd64.deb``

   * Ubuntu 24: ``ice-remoteware_16.0.0.0-0ubuntu1.24_amd64.deb``

2. Use the ``apt install`` command to install the DEB file (adjust
   the file path if necessary):

   .. code-block:: bash

      % ## Ubuntu 20 only
      % sudo apt install ./ice-remoteware_16.0.0.0-0ubuntu1.20_amd64.deb

      % ## Ubuntu 22 only
      % sudo apt install ./ice-remoteware_16.0.0.0-0ubuntu1.22_amd64.deb

      % ## Ubuntu 24 only
      % sudo apt install ./ice-remoteware_16.0.0.0-0ubuntu1.24_amd64.deb

   The installer does the following:

   * Installs ICE RemoteWare files to ``/opt/ice-remoteware``
   * Installs ice-remoteware.service to ``/lib/systemd/system/``
   * Reloads the systemd manager configuration using ``systemctl daemon-reload``
   * Enables the unit file with ``systemctl enable ice-remoteware.service``

3. If your server's domain has a trusted SSL certificate, open the
   configuration file
   (``/opt/ice-remoteware/ice-remoteware.xml``) and set the value
   of ``openssl.server.privateKeyFile`` and
   ``openssl.server.certificateFile`` to its path.  Using a trusted SSL
   certificate is recommended for maximum security.

4. Install the license.

   - If you have a trial license (``ice-remoteware.lic``),
     copy it into ``/opt/ice-remoteware/bin``.

   - If you have a floating license
     (``ice-flexlm.lic``), proceed to
     :ref:`LicenseManagement` for instructions on installing
     ICE FlexLM.

5. Verify that your firewall rules allow traffic over HTTPS (port 443).

6. Use the ``systemctl restart`` command to restart
   the service:

   .. code-block:: bash

      % sudo systemctl restart ice-remoteware.service

7. OPTIONAL: To enable USB Forwarding features, see
   :ref:`UbuntuInstallServerUsbModule`.

The ICE RemoteWare product should now be reachable over HTTPS at your server's
hostname or IP address.  For advanced configuration options, please
see :ref:`Setup`.

.. _UbuntuInstallServerUsbModule:

Installing Server-USB Module on Ubuntu
-----------------------------------------------------------

USB devices can be forwarded between native clients and remote servers
that meet the following requirements:

1. The server's license file must have a valid
   'irw-usb' entitlement.  If you do not see this
   entitlement in your license file, please contact Penguin Solutions sales
   for more information.
2. The Server-USB module must be installed on the remote server.
3. The Client-USB module must be installed on the client side.  See
   :ref:`InstallClientUsbModule` for more information on this step.

To install the Server-USB modules on the remote server:

1. Download the debian installer for your Ubuntu version from
   https://updates.penguincomputing.com/irw/download/

   * Ubuntu 20: ``ice-remoteware-server-usb-module_16.0.0.0-0ubuntu1.20_amd64.deb``

   * Ubuntu 22: ``ice-remoteware-server-usb-module_16.0.0.0-0ubuntu1.22_amd64.deb``

   * Ubuntu 24: ``ice-remoteware-server-usb-module_16.0.0.0-0ubuntu1.24_amd64.deb``

2. Use the ``apt install`` command to update the DEB file (adjust the
   file path if necessary):

   .. code-block:: bash

      % ## Ubuntu 20
      % sudo apt install ./ice-remoteware-server-usb-module_16.0.0.0-0ubuntu1.20_amd64.deb

      % ## Ubuntu 22
      % sudo apt install ./ice-remoteware-server-usb-module_16.0.0.0-0ubuntu1.22_amd64.deb

      % ## Ubuntu 24
      % sudo apt install ./ice-remoteware-server-usb-module_16.0.0.0-0ubuntu1.24_amd64.deb

3. Use the ``systemctl restart`` command to restart
   the service:

   .. code-block:: bash

      % sudo systemctl restart ice-remoteware.service

.. _MacOSInstall:

Installing the Server on MacOS
-----------------------------------------------

1. Download the ``ice-remoteware-16.0.0.0.pkg`` from
   https://updates.penguincomputing.com/irw/download/

2. Double-click on ``ice-remoteware-16.0.0.0.pkg`` to launch the installer
   and follow the GUI instructions.

3. Click OK when the prompt for microphone access appears.

4. **MacOS Monterey 12 and earlier:** Click ``Open System
   Preferences`` when the ``Screen Recording`` prompt appears.

   **MacOS Ventura 13 and later:** Click ``Open System Settings`` when
   the ``Screen Recording`` prompt appears.

5. **MacOS Monterey 12 and earlier:** Click on the Lock icon in the
   ``Security & Privacy`` dialog and enter your password.

6. In the menu on the right locate the checkbox labelled
   ice-remoteware and make sure this box is checked.

7. If you do not see a box for ice-remoteware, click on the ``+``
   symbol, manually add ice-remoteware to the list, and then make sure
   the box is checked.

8. Repeat steps 4-7 when the prompt for ``Accessibility Access``
   appears.

9. If your server's domain has a trusted SSL certificate, open the
   configuration file
   (``/Applications/ICE RemoteWare.app/Contents/Resources/ice-remoteware.xml``) and set the value
   of ``openssl.server.privateKeyFile`` and
   ``openssl.server.certificateFile`` to its path.  Using a trusted SSL
   certificate is recommended for maximum security.

10. Install the license.

    - If you have a trial license (``ice-remoteware.lic``),
      copy it into ``/Applications/ICE RemoteWare.app/Contents/Resources``.

    - If you have a floating license
      (``ice-flexlm.lic``), proceed to
      :ref:`LicenseManagement` for instructions on installing
      ICE FlexLM.

    Once the license file has been installed, the server will start
    automatically and be accessible with a web browser or our native
    client.

11. OPTIONAL: Proceed to :ref:`MacOSAudioInstall` for information on
    adding audio support.

12. OPTIONAL: To enable USB Forwarding features, see
    :ref:`MacOSInstallServerUsbModule`.

.. important:: Putting your remote MacOS server to sleep (for example:
   by closing the lid of the laptop, selecting "Sleep" from the
   Apple menu) will make the ICE RemoteWare software inaccessible.

.. important:: The ICE RemoteWare product prevents Display Sleep from happening in
   MacOS using an application called caffeinate.  This is to prevent
   the server from going to sleep.

The ICE RemoteWare product should now be reachable over HTTPS at your server's
hostname or IP address.  For advanced configuration options, please
see :ref:`Setup`.

.. _MacOSAudioInstall:

Install BlackHole for MacOS Audio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To add remote audio capture, perform the following steps on your
ICE RemoteWare MacOS server:

1. Download and install ``BlackHole 0.2.9`` from
    https://existential.audio/blackhole/.

2. Select ``BlackHole 16ch`` as the Sound Output device.

   * MacOS Monterey 12 and earlier: Open ``System Preferences > Sound > Output`` 
      and select ``BlackHole 16ch``.

   * MacOS Ventura 13 and later: Open ``System Settings > Sound > Output``
      and select ``BlackHole 16ch``.

   .. note:: Selecting ``BlackHole 16ch`` will disable audio
      playback on ``Internal Speakers``, but this can be changed
      using the steps above.  To change devices more easily, check
      the ``Show volume in menu bar`` box.  You can now click on the
      volume control and select one from the Output Device list.

3. Add the ICE RemoteWare software to the ``Login Items`` list for each MacOS user.

   * MacOS Monterey 12 and earlier: Open ``System Preferences
     > Users & Groups``.  Select your username and then the ``Login
     Items`` tab.  Click on the Lock icon and enter your password.
     Now click on the ``+`` button and use the Finder window to add the
     ICE RemoteWare software to the list.

   * MacOS Ventura 13 and later: Open ``System Settings > General >
     Login Items``.  Click on the ``+`` button and use the Finder
     window to add the ICE RemoteWare software to the list.

4. Logout of MacOS and log back in.

The steps above will make audio accessible to clients that connect to your
ICE RemoteWare MacOS server and click on the audio icon.

.. note:: More information about BlackHole can be found at:
  https://github.com/ExistentialAudio/BlackHole

.. _MacOSInstallServerUsbModule:

Installing Server-USB Module on MacOS
-----------------------------------------------------------

USB devices can be forwarded between native clients and remote servers
that meet the following requirements:

1. The server's license file must have a valid
   'irw-usb' entitlement.  If you do not see this
   entitlement in your license file, please contact Penguin Solutions sales
   for more information.
2. The Server-USB module must be installed on the remote server.
3. The Client-USB module must be installed on the client side.  See
   :ref:`InstallClientUsbModule` for more information on this step.

To install the Server-USB modules on the remote server:

1. Download ``ice-remoteware-server-usb-module-16.0.0.0.pkg`` from
   https://updates.penguincomputing.com/irw/download/

2. Double-click on the ``ice-remoteware-server-usb-module-16.0.0.0.pkg`` installer.

3. Follow the instructions in the GUI.

Client Installation
=============================================

Users can connect to the ICE RemoteWare server using commonly available
web browsers or the native client, ICE RemoteWare Client.  The native
client is similar to the web browser in many ways, but it is also
capable of faster video frame rates and additional features, such as:

* USB Forwarding
* Lossless and Visually Lossless Video

ICE RemoteWare Client can be installed on the following operating
systems:

* Rocky Linux 8 and 9
* Windows 10, 11, and Windows Server 2019
* MacOS Big Sur 11 to MacOS Sonoma 14
* Ubuntu 20, 22 and 24

Web Browser Support
-------------------------------------

The following commonly available web browsers can be used to get fast
access to ICE RemoteWare servers:

* Chrome 59+
* FireFox 56+
* Microsoft Edge Legacy 44.17763.1.0+
* Microsoft Edge 79+
* Safari 7+

.. note:: Chrome provides the best performance of all the web
          browsers.

Installing the Client
-------------------------------------

The native client is capable of additional features and faster video
frame rates.

* Rocky Linux 8 users:

  1. Use the ``wget`` command to install the ICE RemoteWare YUM repository
     for Rocky Linux 8.

     .. code-block:: bash

        % sudo wget https://updates.penguincomputing.com/irw/irw-el8.repo -P /etc/yum.repos.d

  2. Use the ``yum install`` command to install ``ice-remoteware-client``.

     .. code-block:: bash

      % sudo yum install -y ice-remoteware-client

* Rocky Linux 9 users:

  1. Use the ``wget`` command to install the ICE RemoteWare YUM repository
     for Rocky Linux 9.

     .. code-block:: bash

        % sudo wget https://updates.penguincomputing.com/irw/irw-el9.repo -P /etc/yum.repos.d

  2. Use the ``yum install`` command to install ``ice-remoteware-client``.

     .. code-block:: bash

      % sudo yum install -y ice-remoteware-client

* Windows, MacOS, and Ubuntu users: Download and install the
  Client installer for your OS from

  https://updates.penguincomputing.com/irw/download/

.. _InstallClientUsbModule:

Installing Client-USB Module on the Client
-----------------------------------------------------------

USB devices can be forwarded between native clients and remote servers
that meet the following requirements:

1. The server's license file must have a valid
   'irw-usb' entitlement.  If you do not see this
   entitlement in your license file, please contact Penguin Solutions sales
   for more information.
2. The Server-USB module must be installed on the remote server.
3. The Client-USB module must be installed on the client side.

* Rocky Linux 8 users:

  1. Use the ``wget`` command to install the ICE RemoteWare YUM repository
     for Rocky Linux 8.

     .. code-block:: bash

        % sudo wget https://updates.penguincomputing.com/irw/irw-el8.repo -P /etc/yum.repos.d

  2. Use the ``yum install`` command to install ``ice-remoteware-client-usb-module``.

     .. code-block:: bash

      % sudo yum install -y ice-remoteware-client-usb-module

* Rocky Linux 9 users:

  1. Use the ``wget`` command to install the ICE RemoteWare YUM repository
     for Rocky Linux 9.

     .. code-block:: bash

        % sudo wget https://updates.penguincomputing.com/irw/irw-el9.repo -P /etc/yum.repos.d

  2. Use the ``yum install`` command to install ``ice-remoteware-client-usb-module``.

     .. code-block:: bash

      % sudo yum install -y ice-remoteware-client-usb-module

* Windows, MacOS, and Ubuntu users: Download and install the
  Client-USB module installer for your OS from

  https://updates.penguincomputing.com/irw/download/
