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

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 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 Server.Portal.KeyFile. See 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.

Setup#

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

  1. Shut down the service.

  2. Initialize the encrypted key on the host. This step will also enable the Portal feature in the configuration file.

  3. Add add one or more Access Nodes to the configuration file so the host can integrate the node(s) into the portal network. See Server.Portal.InitialNodes for details.

    Tip

    Adding additional hosts increases the overall fault tolerance of the network.

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

  1. Stop the ice-remoteware service using the Services tool:

    1. Open the Task Manager and navigate to the Services tab.

    2. Right-click "ice-remoteware" in the list of services and select Stop from the list of actions.

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

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

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

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

  3. Stop the ICE RemoteWare service on all nodes

  4. Pick a shared passphrase and set up the shared keys on the nodes using the instructions in the Setup section.

  5. Edit the configuration files (ice-remoteware.xml) on the nodes.

    1. On all nodes, set the Server.Portal.NodeType variable to server, access, or combined depending on the node type.

    2. On all nodes, add the names or addresses of the Access Nodes and the Combined Node in 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>

  1. Restart all nodes to apply the configuration changes.

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