Site connector version: 3.8

Introduction to Site connector

Site connector provides a bridge between the network of the Ubisense Core Server and other Ubisense controllers or clients, making two disjoint networks appear to be connected to the same instance of the platform. A Site connector server runs on the Core Server machine and Site connector clients run on other servers hosting Ubisense controllers, or on Windows client machines which are used to run GUI based administrative tools. Traffic between a Site connector server and Site connector clients flows over a TCP/IP connection, providing a tunnel which permits access through a single port. This connector offers the possibility to bridge the Ubisense protocols, via SSH, through firewalls and over the internet.

As a Ubisense system comprises numerous Ubisense services, which communicate directly with each other, Site connector is needed to expose the end points of services running on remote machines to allow services running in different networks to contact each other. Clients that work with multiple Ubisense services need Site connector to find and communicate with those services. Command line tools on a client machine can operate as if they are running on the server by using Site connector.

The most common use case enables a Windows client machine to manage a remote Ubisense server. The Ubisense server can be either another Windows host or a Linux host. Some installations use multiple servers to distribute Ubisense services across different machines. For example, there may be a server dedicated to providing logging. In this case, unicast cluster is the recommended approach to connect a server to another server, although Site connector can still be used.

Purpose of this Manual

The following is a guide to the use and operation of the Ubisense Site connector system. It is divided into the following sections:

1. System Overview: brief description of the system and its components
2. Intended Uses: the main system use cases
3. Server Management: installation, configuration, monitoring
4. Client Management: installation, configuration, monitoring
5. System Configuration: how to configure the system for different uses

The user should read this entire manual before attempting to install and configure the system.

The system is quite complex. The user should perform the minimum installation and configuration required for their application and should not set configuration parameters unless they fully understand what the impact will be.

System Overview

The Site connector consists of, first, a server application and second, a set of client applications.

The Site connector server is an independent service rather than a package deployed via the Ubisense platform. On Windows, it is installed as a Windows Service. On Linux, it should be started in the same way as core and controller, via systemd.

The client applications run as system services (e.g., Windows service or Linux daemon).

In the occurrence of any fatal failure that would lead to an unexpected termination of an application (either server or clients), the application will automatically be re-launched causing the re-binding connections to return to a fully functional tunnel.

The Site connector bridges the following Ubisense protocols:

• Service finder
• Invocation protocol
• SRM (Scalable Reliable Multicast)
• Monitoring
• Configuration protocol

Sensor traffic through the tunnel is not supported.

To be harnessed, the Site connector requires both the server and at least one client to be installed. Furthermore, some configuration steps might be required.

From version 3.8 there are two different Windows Clients.

• The Site connector Client is intended for connecting a client PC to a server. It is intended to only be connected while the client PC is in use.
• The Site connector Client for Servers is intended to connect a server running a local controller to a central server running the Ubisense Core Server.

Intended Uses

Windows client machine to administer a Linux server

If the servers are on a single network and Site connector is being used to connect a remote computer which will interact with the servers using Ubisense programs, such as Service Manager and SmartSpace Config, then all that is required is:

1. Install Site connector Server on server machine and Site connector Client on remote machine.
2. Set server IP address in client configuration.
3. Start Site connector Client and check that it connects.

The section Client Management describes installing and configuring the Client, the section Server Management provides more information on Server configuration, and the section Basic connection describes basic connection.

Connecting two servers

To connect a Core Server with a Ubisense controller that is running on another machine, you need to enable unicast mode. See SmartSpace Unicast Cluster Setup Guide.

Server Management

The site connector server is an independent service. On Windows, this is installed as a Windows Service. On Linux, it should be started in the same way as core and controller, via systemd.

Installation

If a legacy Site Connector package is installed in the dataset, you should undeploy and remove it, using the Service Manager, before installing this release.

Installing Site connector server on Windows

1. Go to the UbisenseSiteConnectorForServers directory of your Site connector distribution directory.
2. Double-click the UbisenseSiteConnectorForServers.msi file and the Ubisense Site Connector Service Setup wizard appears.

3. Click Next.

4. Choose the Destination Folder for the software.
   You can accept the default C:\Program Files (x64)\Ubisense 3\ or change to another destination.
5. Click Next and click Install.
6. When the installation is complete, click Finish to close the Ubisense Site Connector Service Setup wizard.

After installation is complete, start the service using Windows Services manager:

1. Open Services by typing View local services in the Start menu.

2. Start the service UbisenseSiteConnectorServer 3.

   The service is configured to start automatically on reboot.

You can also stop and start the site connector service from the command prompt (as an administrator):

Installing Site connector server on Linux

For Linux, you can find the Site connector server executable in your distribution directory under linux/server. To install the executable:

1. Copy ubisense_site_connector_server onto your server
2. Create a systemd configuration to run the executable on startup.

Configuration

Several parameters can be set via the ubisense_configuration_client application. The command

ubisense_configuration_client set <parameter name> <parameter value>

sets the configuration parameter <parameter name> to the value <parameter value>. Table 1: Parameters of the Site Connector server lists the parameters specific to the tunnel server. There is no need to set parameters for which an acceptable default value is listed.

Table 1: Parameters of the Site Connector server

Parameter name	Description	Default value
tunnel_server_port	Port number	49983
tunnel_server_log_output_diagnosis	Activate the diagnosis log stream	0
tunnel_server_log_output_message	Activate the message log stream	1
tunnel_server_send_monitor	Send the monitor packets through the tunnel	1
tunnel_server_max_clients	Maximum number of clients	20
tunnel_server_max_mem_queue_clients	Maximum memory in bytes allocated for all the sending queues	200,000,000
tunnel_server_max_mem_queue_client	Maximum memory in bytes allocated for one sending queue	100,000,000
tunnel_stack_size	Sets the stack size in kB	512

Monitoring

The server logs its monitoring messages using the standard Ubisense logging mechanism. The log streams can be viewed using SmartSpace Config. The platform_monitor configuration parameter must contain ‘site_connector’.

The streams can also be viewed using ubisense_trace_receiver, e.g.

ubisense_trace_receiver | grep site_connector

Monitoring levels describes the monitoring levels.

Client Management

The client (ubisense_site_connector_client) should run as a Windows service or Linux daemon. In order to perform the installation you must know both the server address and the port number on which the server is listening.

Note: Only one client can be running per machine (i.e., for a given client, its address must be unique). Furthermore, the server and a client cannot coexist in the same machine.

Windows

Installation

The Windows Site Connector Client is installed using UbisenseSiteConnectorClient.msi. The Windows Site Connector Client for Servers is installed using UbisenseSiteConnectorClientForServers.msi. The setup wizard will guide you through installing the client.

To install the Windows Site Connector Client:

1. Go to the UbisenseSiteConnectorClient directory of your Site connector distribution directory.
2. Double-click the UbisenseSiteConnectorClient.msi file and the Ubisense Site Connector Client Setup wizard appears.

3. Click Next.

4. Choose the Destination Folder for the software.
   You can accept the default C:\Program Files (x64)\Ubisense 3\ or change to another destination.
5. Click Next.

6. Enter the server settings.

   You can accept the defaults:

   • Address: 127.0.0.1

   • Port number: 49983

   • Run in standalone mode: selected

7. Click Next and click Install.
8. When the installation is complete, click Finish to close the Ubisense Site Connector Client Setup wizard.

To install the Windows Site Connector Client for Servers:

1. Go to the UbisenseSiteConnectorClientForServers directory of your Site connector distribution directory.
2. Double-click the UbisenseSiteConnectorClientForServers.msi file and the Ubisense Site Connector Client for Servers Setup wizard appears.

3. Click Next.

4. Choose the Destination Folder for the software.
   You can accept the default C:\Program Files (x64)\Ubisense 3\ or change to another destination.
5. Click Next.

6. Enter the server settings.

   You can accept the defaults:

   • Address: 127.0.0.1

   • Port number: 49983

   • Run in standalone mode: selected

7. Click Next and click Install.
8. When the installation is complete, click Finish to close the Ubisense Site Connector Client for Servers Setup wizard.

The Site Connector Client can be installed from the command line, without the UI, using msiexec. For example:

msiexec /i UbisenseSiteConnectorClient.msi /passive

A number of setup parameters can be specified on the command line (see Table 2: Command line parameters of setup MSI.).

Table 2: Command line parameters of setup MSI.

Parameter name	Description	Default
ALLUSERS	Specify whether the client should be installed for all users, i.e. per machine, or a single user, i.e. per user. For per user set ALLUSERS=””.	All users
SERVICE_START	Specify whether the Site Connector Client should start automatically after a PC reboot. Set SERVICE_START=”automatic” for automatic re-starts.	Manual
SERVER_IP	Specify the IP address of the Site Connector server.	127.0.0.1
SERVER_PORT	Specify the port number to connector to on the server.	49983
STANDALONE_MODE	Specify whether the client should be in standalone mode. Set STANDALONE_MODE=”0” for non-standalone mode.	1

The following example will install the Site Connector Client for Servers for a single user, connecting to address 10.42.1.101:44444, with automatic re-starts:

msiexec /i UbisenseSiteConnectorClientForServers.msi ALLUSERS=”” SERVICE_START=”automatic” SERVER_IP=”10.42.1.101” SERVER_PORT=”44444” /passive

Note that even when automatic re-starts are specified, the client needs to be started for the first time: this can be done manually, see Basic Settings and Connection, or by rebooting the PC.

Basic Settings and Connection

After the installation has been successfully performed, the client can be started, stopped and configured using the Site Connector Control application. This can be found on the Programs menu under Ubisense 3 > Site Connector Control 3. The main screen of the application is shown in Figure 4.

Figure 4: Site Connector Control main dialog

The current status of the client is shown in the ‘Client status’. This will usually be ‘Running’ or ‘Stopped’.

When the client is ‘Stopped’ it can be started with the Start button. The behavior is different for the Client and the Client for Servers:

• When the Client for Servers is started it will be set to automatically re-start after a reboot. Therefore the client will run until the user stops it. When the client is ‘Running’ it can be stopped with the Stop button. When the client is stopped it will be set to not automatically re-start after a reboot. The buttons are enabled and disabled according to the current status of the client.
• When the Client is started it is not set to automatically re-start. It will only run as long as Site Connector Control is running. If the PC is rebooted the client will not re-start. If the client loses connection the Site Connector Control will try to re-start it for a few minutes but then give up.

The ‘Connection failure action’ explains what actions are taken if the client loses its connection.

The Event Log shows diagnostic information about the client. For example, in Figure 4, the top line of the Event Log shows the server the client is connecting to and the bottom line shows that the client has successfully connected.

If the client fails to connect then diagnostic messages will appear in the event log. If the client encounters a problem then it will stop itself.

If this happens to the Client for Server the Windows Service Manager will restart it to try connecting again. This can lead to the client continually stopping and restarting. The Event Log should reveal the problem.

For the Client the Site Connector Control will try to re-start it for a few minutes but then give up.

The host name or IP address and port number for the server can be changed in the Change Server dialog (see Figure 5: Change Server dialog).

Figure 5: Change Server dialog

The Change Server dialog lists the servers that the client has recently connected to. Selecting one of these will fill in the ‘Host name or address’, ‘Port number’ and ‘Server name’ values. If the required server is not listed then these three values can be entered by hand. The ‘Host name or address’ can be the name of the server, e.g. ‘serv12’ or an IP address, e.g. 10.42.1.101. The ‘Server name’ is optional and may be used when an IP address is specified to provide a user-friendly name, e.g. ‘production server’. The port will normally take the default value of 49983.

Press OK to use the new server settings or Cancel to abandon the changes. If the Site Connector Client is running when the server address is changed it will immediately stop and the Windows Service Manager will restart it with the new server settings. The ‘Client status’ and ‘Current server’ values in the main dialog should update. If the Site Connector Client is not running then you can start it with the new server address by pressing the Start button.

Once the Client for Servers is connected the Site Connector Control application can be closed, however for the Client the application must remain open while the connection is in use. In this case the Client will be stopped when the application is closed.

Advanced users can view the state of the client and start and stop it using the Windows Computer Management application. Look for the UbisenseSiteConnectorClient 3 under Services and Applications > Services.

Advanced Settings

Advanced settings, required for monitoring, can be edited using the Settings dialog (see Figure 6: Settings dialog). The meaning of these settings is described in the section Configuration and their usage is described in the section Monitoring levels. To accept the changes press the OK button. To abandon them press Cancel. After changing these settings you must stop and restart the client using the Stop and Start buttons in the Site Connector Control main dialog.

Figure 6: Settings dialog

Advanced users can view and modify all the client settings using the Windows Registry Editor. The parameters are located in

Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Ubisense 3\ubisense_site_connector_client.

Configuration

Table 3: Parameters of the client lists the parameters specific to the Site Connector client.

Table 3: Parameters of the client

Parameter name	Description	Default value
PortNumber	Port number of the tunnel server	49983
IpAddress	Address of the tunnel server
LogDiagnosis	Activate the diagnosis log stream	0
LogMessage	Activate the message log stream	1
SendMonitor	Send the monitor packets through the tunnel	1
RecvMonitor	Request monitor packets from the server	1
ReconnectPeriodMinutes	Number of minutes to try reconnecting the simple Client.	5
WindowsServer	Activate the additional features of the Client for Servers. This value should not be changed.	0

 

Monitoring

The Windows client logs its monitoring messages to the Windows Event Log. All messages are displayed in the Event Log in the Site Connector Control application.

Advanced users can view the log streams using the Windows Event Viewer application

The Monitoring levels section describes the monitoring levels.

Linux

Installation

On Linux systems, the Site connector Client can be used to connect a host running a Ubisense local controller with the host running the Ubisense Core Server and Site connector server. This configuration can be used when there may be a server dedicated to providing logging, for example. A better approach is to use unicast cluster instead. If the Site connector Client must be used, the following shows an example of a systemd script for running the Site connector Client as a service.

Configuration

The Linux client is configured using a simple text file: /etc/ubisense/tunnel_site_connector.conf.

Note: If the UCONFIG environment variable has been used to define an alternative location for platform.conf, then site connector client expects the parameter file to be in the same location. For example, if UCONFIG is /home/ubisense/platform.conf, then the tunnel parameter setting file will be
/home/ubisense/tunnel_site_connector.conf.

Bear in mind that the daemon must have sufficient rights to read that file in order for the parameters to be properly set. Furthermore, if the daemon is running when the configuration file is modified, it is necessary to restart the daemon for the new parameter values to take effect.

Table 3: Parameters of the client lists all the parameters that can be specified.

The file format should strictly follow this template: <parameter name> <parameter value>. The name and value must be separated by one, or several, blank space (or tab, or new line). Two name-value compounds must be separated by one, or several, blank space, tab or new line. 

Here is an example of tunnel_site_connector.conf:

IpAddress 10.42.5.116
PortNumber 49983
LogMessage 1
LogDiagnosis 0

Note that if a parameter is not specified in this file the default value is used (see Table 3: Parameters of the client).

Monitoring

The Linux client logs its monitoring messages using Linux’s syslog (with the facility code set to LOG_LOCAL0 and the priority code set to LOG_INFO).

The location of the syslog output varies according to the distribution of Linux being used. The file /etc/syslog.conf will normally contain the location of the monitoring output, which may be /var/log/messages.

The section Monitoring levels describes the monitoring levels.

System Configuration

Monitoring levels

Servers and clients both support two levels of monitoring. MESSAGE level provides basic progress and event tracking. DIAGNOSIS provides more detailed debugging information. The monitoring level can be set on both the client and the server independently (i.e. the monitoring levels do not need to match). On the client LogMessage and LogDiagnosis turn the two monitoring levels on or off. On the server tunnel_server_log_output_message and tunnel_server_log_output_diagnosis perform the same function.

If monitoring messages from the server should be sent to the client then the server parameter tunnel_server_send_monitor should be set to 1. If monitoring messages from the client should be sent to the server then the client parameter SendMonitor should be set to 1.

If the client does not want to receive monitor messages from the server then the client parameter RecvMonitor should be set to 0.

When the network speed is limited, we suggest setting the both flags RecvMonitor and SendMonitor to 0. Otherwise, the risk is for the client to be disconnected from the server. Note that, in practice, RecvMonitor may be more critical than SendMonitor in such a context; therefore if you observe in the server’s log (message stream, see next subsection for further details) that the sending queue has overflowed (i.e., the sentence “Sending message queue has overflowed”) causing the client to be disconnected, you may start by setting RecvMonitor to 0. Then, if the problem persists, set SendMonitor to 0.

Memory usage management

When the server is sending a message to a given client, the message is first enqueued, and then a thread is in charge of dequeueing the messages and sending them through the network (one thread is dedicated for this task for one queue; therefore there are as much threads as sending queues, i.e., as much as connected clients). In practice, this approach works fine most of the time. However, if, for any reasons, a queue is (or several queues are) growing much faster than it is (or they are) emptied, it can be the source of undesirable behavior. For example, if a queue grows to the point of requiring an amount of memory unbearable for the operating system, this may potentially lead to the collapse of the entire system.

For the sake of avoiding such a scenario, a two-fold mechanism has been implemented. First, each sending queue is limited in memory. The parameter tunnel_server_max_mem_queue_client (Table 1: Parameters of the Site Connector server) defines this limit. If this limit is reached, then the client is disconnected.

Second, the global memory employed by the entire set of the connected clients (i.e., the sum of the memory of the queue of each client) is monitored. If this sum reaches the limit set via the parameter tunnel_server_max_mem_queue_clients (Table 1: Parameters of the Site Connector server), then the client that has the queue using the most memory is disconnected.

The best values for tunnel_server_max_mem_queue_client & tunnel_server_max_mem_queue_clients will depend on the memory available on the computer where the Site Connector server is running. The default values, 100MB and 200MB, could be too large on some computers and may need to be reduced to a tenth of these values or less.

The memory usage can also be controlled by setting the maximum number of clients with tunnel_server_max_clients. By default up to 20 clients are allowed.

Advanced users may also want to adjust the value of the Ubisense platform server_max_bytes_per_second parameter to achieve optimum message throughput.

Basic connection

If all platform services are on the server end of the tunnel, and the client is being used to configure the state on the server end, then only 1 parameter needs to be set. The client’s IpAddress parameter must be set to the IP address of the server. The client PortNumber and the server tunnel_server_port parameters are also used but normally do not need to be set as the default will suffice. If they are set then they must be set to the same port number.

Cleaning up schema connections

By default, schema connections used by clients are kept open on the tunnel indefinitely. The tunnel_client_test_interval parameter can be set to expire schema connections that are no longer used, reducing the network bandwidth and central server load. Every tunnel_client_test_interval seconds the tunnel client will check for and expire unused connections.

If schema connection expiring is desired, it is recommended you set this value to 60, which will gracefully and slowly clean up unused schemas. Unused schemas are detected by dropping a packet for that schema and watching for client recovery attempts. Using a shorter client interval will clean up connections more aggressively at the cost of increased client recovery attempts, which might be visible as very brief pauses in real-time data.

The default setting is 0, which turns off this functionality.

FAQ and Troubleshooting

Connection errors

Cannot connect to session host

The server IP address or port number may be wrong. Check that the host and port are correct, that this computer is connected to the internet, and that there is no firewall blocking outgoing TCP/IP connections.

If the Site Connector server is running in standalone mode, it may not have added itself to the firewall exceptions. Try running the server once not in standalone mode and then try again in standalone mode.

Both ends of the connection have core servers running

Either the platform UbisenseCoreServer is running on the machine that Site Connector Client is running on, in which case use Platform Control to stop it, or the client and server are on the same network, in which case enable ‘standalone mode’ on the client with Platform Control.

Configuration server

The configuration list obtained via the ubisense_configuration_client utility seems to be incorrect regarding the address of the boot server (i.e., it shows the address of the machine located on the other end, which is not valid on this end).

This is a normal behavior. The reason lies behind the fact that ubisense_configuration_client is not relying on the configuration protocol to retrieve the list, but on the remote operation protocol instead (in other words, it accesses directly to the UConfig::Params server using RPC).