.. _Portal:

Portal
====================================================================

The Portal feature enables user access to multiple remote desktops through one portal. This single portal simplifies the handling of deployments with many remote desktops, providing increased flexibility and allowing improved usage of large deployments (up to 100s of remote desktops).

The Portal feature is available for Windows and Linux.



Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The  Portal Feature allows a set of remote desktops (called ``Server Nodes``) and portals (called ``Access Nodes``) to be assembled into one coherent ``Portal Deployment``. 


Portal Deployment
--------------------------------------------------------------------

A ``Portal Deployment`` is a network that consists of ``Access Nodes``, ``Server Nodes`` and ``Combined Nodes``. The ``Portal Deployment`` redirects a user to a remote desktop after their successful authentication.


Server Nodes
--------------------------------------------------------------------
``Server Nodes`` provide the remote desktops to the users. At startup, ``Server Nodes`` inform ``Access Nodes`` 
about their availability and can be configured by the :ref:`Server.Portal.InitialNodes` variable
in the configuration file.

Access Nodes
--------------------------------------------------------------------
``Access Nodes`` are the user's interface to the system. All ``Access Nodes`` maintain a list
of available ``Server Nodes`` and their state, i.e.  availability. After a user authenticates successfully
on an ``Access Node``, the ``Access Node`` will try to match the user with an available server node (i.e. not occupied by another user). When the user already has a session running on a ``Server Node``, the user will be routed to that particular ``Server Node``, otherwise the user will be routed to an available ``Server Node`` based on the estimated load.

.. _Doc.Portal.MasterAccessNode:

Master Access Node
............................................................................
A ``Master Access Node`` keeps track of all ``Access-`` and ``Server Nodes`` and serves as the source of truth which nodes in the deployment are available. Typically, there will be only one ``Master Access Node`` per deployment. Should the ``Master Access Node`` disconnect, a regular Access Node will be promoted automatically to ``Master Access Node``. 


See also :ref:`Server.Portal.NodePriority`

Combined Nodes
--------------------------------------------------------------------
``Combined Nodes`` combine the ``Access Node`` with the ``Server Node`` functionality. They enable user access to the system (like an ``Access Node``) and provide the remote desktops to the users (like a ``Server Node``).


Portal Key
--------------------------------------------------------------------
The ``Portal Key`` authorizes a node to participate in the ``Portal Deployment``.
This key needs to stay secure, otherwise non-authorized
machines could connect to the deployment.

The key has been to be initialized at installation time by providing a shared `passphrase`, it will be
encrypted on the particular node. The key is bound to the node's network
address and the node's file location, so any changes to those will require the key to be regenerated.

The key location is specified using :ref:`Server.Portal.KeyFile`. See :ref:`Doc.Portal.Setup` for key generation instructions.

.. caution:: Because the ``Portal Key`` enables any node to participate in the shared environment, make sure that the key file is only readable by host administrators. 


.. _Doc.Portal.Setup:

Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Integrating a node into a ``Portal Deployment`` requires the following steps. 

#. Shut down the service. 
#. Initialize the encrypted key on the host. This step will also enable the Portal feature in the configuration file. 

#. Add add one or more ``Access Nodes`` to the configuration file so the host can integrate the node(s) into the portal network. 
   See :ref:`Server.Portal.InitialNodes` for details. 
   
   .. tip:: Adding additional hosts increases the overall fault tolerance of the network. 
   
#. Restart the service. 


**On Linux**, use following steps:

::

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

   # Change to the application directory
   cd /opt/ice-remoteware/

   # Generate the encrypted key on this host
   sudo ./bin/ice-remoteware --portal-key=<shared-passphrase>

   # Add initial access/combined node(s) to connect to to configuration file
   sudo vi /opt/ice-remoteware/ice-remoteware.xml

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


**On Windows**, the following steps are required: 

#. Stop the ``ice-remoteware`` service using the Services tool:

   #. Open the Task Manager and navigate to the Services tab. 
   #. Right-click ``"ice-remoteware"`` in the list of services and select **Stop** from the list of actions. 
   
#. Open a console and follow these steps:: 

      # Change to the application directory
      cd C:\Program Files\Penguin Solutions\ICE RemoteWare/

      # Generate the encrypted key on this host
      bin\\ice-remoteware.exe /portal-key=<shared-passphrasey>
      
      # Add initial access/combined node(s) to connect to to configuration file
      edit ice-remoteware.xml

#. In the Task Manager Services tab, right-click ``"ice-remoteware"`` and select **Start** from the list of actions. 



Example Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This Step-by-Step guide of a simple ICE RemoteWare Remote Desktop deployment will walk you through a simple remote desktop deployment with three ``Server Nodes``, two ``Access Nodes`` (one of which will become automatically the master node), and one ``Combined Node``.

For simplicity, the names of the three ``Server Nodes`` in this example are `server-1`, `server-2`, and `server-3`, the ``Access Nodes`` are named `accessnode-1` and `accessnode-2`, and the Combined Node is named `comb-node`.

If the ICE RemoteWare software is already running on your nodes, start with step 3

#. Prepare six different VMs (three for ``Server Nodes``, two ``Access Nodes``, and one ``Combined Node``).

#. Install the ICE RemoteWare software on all nodes.
   
   The portal functionality is integrated in the ICE RemoteWare server software, no other software is required. For the installation of the ICE RemoteWare software please refer to :ref:`install`. 

#. Stop the ICE RemoteWare service on all nodes

#. Pick a shared `passphrase` and set up the shared keys on the nodes using the instructions in the :ref:`Doc.Portal.Setup` section. 

#. Edit the configuration files (`ice-remoteware.xml`) on the nodes. 
   
   #. On all nodes, set the :ref:`Server.Portal.NodeType` variable to `server`, `access`, or `combined` depending on the node type.
   #. On all nodes, add the names or addresses of the ``Access Nodes`` and the ``Combined Node`` in :ref:`Server.Portal.InitialNodes`. 


Access Nodes
    
*accessnode-1*:: 

  <Server>
    ...
     <Portal Enabled="true">
       <NodeType>access</NodeType>
       <InitialNodes>accessnode-2,comb-node</InitialNodes>
    </Portal>
    ...
  </Server>

*accessnode-2*::

  <Server>
    ...
     <Portal Enabled="true">
       <NodeType>access</NodeType>
       <InitialNodes>accessnode-1,comb-node</InitialNodes>
    </Portal>
    ...
  </Server>


Server Nodes::

  <Server>
    ...
     <Portal Enabled="true">
       <NodeType>server</NodeType>
       <InitialNodes>accessnode-1,accessnode-2,comb-node</InitialNodes>
    </Portal>
    ...
  </Server>


Combined Node::

  <Server>
    ...
     <Portal Enabled="true">
       <NodeType>combined</NodeType>
       <InitialNodes>accessnode-1,accessnode-2</InitialNodes>
    </Portal>
    ...
  </Server>


7. Restart all nodes to apply the configuration changes.

8. Test the setup. Connect to one of the ``Access Nodes`` or the ``Combined Node`` using a browser or the ICE RemoteWare Client by entering the node's URL (i.e. `https://accessnode-1`) and enter your user credentials. 

If everything is setup correctly, you should be routed to one of the ``Server Nodes`` or to the ``Combined Node`` and see your remote desktop.



Troubleshooting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The administrator can use the server software on the command line to get some visibility into the state
of the individual nodes, e.g. to which other nodes a specific server is connected to.

The following commands are supported:

============================ =======================================
Command
============================ =======================================
isAlive                      Tests if node is alive and responsive
showInfo                     Shows this node's basic information
showMaster                   Shows the ``Master Access Node`` this node is connected to
showNodeCount                Shows the number of nodes this node is connected to
showNodes                    Shows the list of nodes this node is connected to
============================ =======================================

The server needs to have access to the ``Portal Key``, so it needs to be started with administrative privileges. In addition to the command the server has a second option to specify the node to query. If this option is omitted, the local host will be queried.

**On Linux** use following syntax::

   sudo /opt/ice-remoteware/bin/ice-remoteware --portal-cmd=<command> --portal-cmd-host=<host>:<port>

**On Windows** use following syntax with administrator privileges::

   bin\ice-remoteware /portal-cmd=<command> /portal-cmd-host=<host>:<port>


Query Node Information
--------------------------------------------------------------------


``Access Nodes``::

   root@algol>/opt/ice-remoteware/bin/ice-remoteware --portal-cmd=showInfo --portal-cmd-host=accessnode-2
   Host: accessnode-2 192.168.0.249:443 an, prio 4, uId 5, age 0

The output provides the node's id, network address, and port. As this is an ``Access Node`` ('an'), it also shows the priority of the node (see :ref:`Server.Portal.NodePriority`).

``Server Nodes``::


   root@algol>/opt/ice-remoteware/bin/ice-remoteware --portal-cmd=showInfo --portal-cmd-host=server-1
   Host: server-1(*) 192.168.0.173:443 svr, uId 17, age 0, osusr 'testuser', usr 1/16, ms: user-a

In addition to the information returned for an ``Access Nodes``, a ``Server Node`` will also return: 

* The currently logged in user (if any, `testuser` in this example)
* The current (1) and maximal number (16) of allowed users (multi-session systems only)
* Users currently connected through ICE RemoteWare (`user-a` in this example).


``Combined Nodes``::

   root@algol>/opt/ice-remoteware/bin/ice-remoteware --portal-cmd=showInfo --portal-cmd-host=comb-node
   Host: comb-node(*) 192.168.0.254:4000 an/svr, prio 4, uId 7, age 0, osusr 'testuser', usr 1/1, ms: user-b

The ``Combined Node`` will display the same information elements as a ``Server Node``, but also the priority of the node like an ``Access Node``.


Verifying ``Master Access Node`` Setup
--------------------------------------------------------------------

For the system to work smoothly all nodes have to agree on one ``Master Access Node``. The ``Master Access Node`` election requires a common view on all nodes, which might not be possible due to network partitions, misconfigured firewalls, and so on.


Each node can be queried for information about the ``Master Access Node``:

::

   root@algol>/opt/ice-remoteware/bin/ice-remoteware --portal-cmd=showMaster --portal-cmd-host=accessnode-2
   Master: accessnode-1 192.168.0.129:443 an, master, prio 4, uId 39, age 6251, synced (10, pending)

The output has the same information elements as a simple query to an ``Access Node`` ('an'), but it also shows if the node used to query is already 'synced' or, when it just recently connected, that it is planning to sync.

All hosts should show the same host as ``Master Access Nodes``.

Querying All Nodes
--------------------------------------------------------------------

Each node can be queried for its current information about the ``Portal Deployment``.

``Access``- and ``Combined Nodes``::

   root@algol>/opt/ice-remoteware/bin/ice-remoteware --portal-cmd=showNodes --portal-cmd-host=accessnode-2
   1: accessnode-1 192.168.0.129:443 an, master, prio 4, uId 39, age 15725 conf, synced (17, 106s)
   2: accessnode-2(*) 192.168.0.249:443 an, prio 4, uId 5, age 467
   3: comb-node 192.168.0.254:4000 an/svr, prio 4, uId 7, age 19305 login session, usr 1/1, ms: user-b
   4: server-1 192.168.0.173:443 svr, uId 18, age 19306, osusr 'testuser', usr 0/16, ms
   5: server-2 192.168.0.39:4000 svr, uId 4, age 19306, osusr 'testuser', usr 0/1, ms
   6: server-3 192.168.0.249:8043 svr, uId 3, age 19306, osusr 'testuser', usr 0/1

The ``Access``- and ``Combined Nodes`` will show information about all nodes in the network. All nodes of these types should give the same information, other than age.

``Server Nodes``::

   root@algol>/opt/ice-remoteware/bin/ice-remoteware --portal-cmd=showNodes --portal-cmd-host=server-1
   1: accessnode-1 192.168.0.129:443 an, master, prio 4, uId 39, age 8914, synced (1, 1s)
   2: accessnode-2 192.168.0.249:443 an, prio 4, uId 6, age 58773
   3: comb-node 192.168.0.254:4000 an/svr, prio 4, uId 7, age 58773 login session, usr 0/1
   4: server-1(*) 192.168.0.173:443 svr, uId 19, age 1160, osusr 'testuser', usr 0/16, ms

``Server Nodes`` don't have any information about any other ``Server Node`` in the network, so the only ``Server Node`` they report are themselves.

On very large networks a quick check is to use the `showNodeCount` command, which will just return the number of known nodes.


Notes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Welcome Messages
--------------------------------------------------------------------

To assist the user with identifying the ``Server Node`` selected by the Portal, you can add a welcome message to the ``ice-remoteware.xml`` configuration file during initial setup, see :ref:`Server.Customization.Message.Text`. This message will then be shown when the user logs in. For example::

  <Server>
    ...
     <Customization>
      <Message>
        <Text>Welcome to server-3</Text>
      </Message>
    ...
   </Customization>
    ...
  </Server>


Multiple Network Interfaces/NAT Firewalls
--------------------------------------------------------------------
If your nodes have multiple network interfaces, choose network addresses that allows all nodes to connect to each other. 

If your network setup uses internal facing network interfaces and external facing ones (i.e. you are running your remote desktop deployment in a corporate VPN) and you want your deployment to be reachable for external users, make sure you are entering the external IP addresses/hostnames of the ``Access Nodes`` in the configuration files of your nodes. 
