Limeade ONE Hub Install Guide
Getting the Installation Package
Private Azure Service Bus Namespace
Installing the Limeade ONE Hub Service
Company ID/Shared Key/Environment Name
Service Bus Connection Settings
Upgrading the Limeade ONE Hub Service
Configuring for High Availability
Appendix A – Firewall Configuration
Allow All Outbound Traffic for Port Ranges
Allow Outbound Traffic only to a DNS name
Steps to Determine DNS for Azure Service Bus relay address
DNS based Firewall Configuration
Allow Outbound Traffic only to an IP Address
IP based Firewall Configuration
Appendix B – IP Addresses for one.sitrion.com
Overview
This document covers the installation and configuration for the Limeade ONE Hub windows service. This service allows the Limeade ONE platform to securely read and write data to on-premise systems.
Installing the Hub
Getting the Installation Package
The Hub install file can be downloaded from the Get Started console in the Limeade ONE Admin portal.
Prerequisites
Hardware and Operation System
Recommended:
- A physical or virtualized windows server installation
- Windows Server 2012 or later
- .NET Framework 4.7.1(full installation)
- A CPU with at least two cores
- 4 GB RAM
- 10 GB free disk space
Database
The Limeade ONE Hub configuration settings and user credentials are stored in an encrypted SQL database. This requires a SQL Server instance (2008 or higher).
Connectivity
There are three connectivity modes for the Hub to connect to the Limeade ONE Cloud Platform.
- TCP Relay mode (Preferred): This mode provides the best performance but is not compatible with a web proxy configuration.
- HTTP Relay mode (uses Web sockets): This mode is required in organizations that use web proxies to connect to the Internet.
- HTTPS Queue mode: This mode should only be used when the previous two modes have failed in successfully connecting to the Limeade ONE Cloud platform. This mode is the least performant and is discouraged.
For advanced firewall configuration options see Appendix A: Firewall configuration
Limeade ONE is currently hosted in the following Azure datacenters:
- West US (California)
- West Europe (Netherlands)
The Limeade ONE Hub service requires connectivity to the given backend systems it is expected to access.
Private Azure Service Bus Namespace
This requires that customers use a dedicated Azure Service Bus namespace for each of their production Hub installations. This ensures that all of an organization's traffic is segregated, private and secured when communicating with the Limeade ONE cloud infrastructure. An organization has two options in acquiring a dedicated Service Bus namespace.
Managing an Azure Service Bus Namespace
This option provides the most control for organizations that already have an existing Azure subscription. To learn how to create and manage an Azure Service Bus namespace, see the following documentation.
Create a Service Bus namespace using the Azure portal
Location:
It is recommended that to select the location that is the geographically closest to a customer's specific Limeade ONE Hub instance.
Shared Access Policy
The required shared access policies configuration for the Limeade ONE Hub is send and listen. Limeade recommends that to not provide manage rights to the Service Bus access policy.
Limeade manages the Private Service Bus Namespace
For organizations that do not have an existing Azure subscription or do not want the responsibility of managing their own Service Bus namespace, Limeade is happy to create and manage this for an organization. Just consult a customer success manager for details.
Proxy Configuration
If an organization uses a web proxy for Internet access, a proxy configuration is required.
The proxy, need to be configured manually in the config file for the Hub. The config file is located, by default, in the folder C:\Program Files\Sitrion\Sitrion ONE Service\Sitrion.One.Hub.Service.exe.config. The configuration is a standard .NET application configuration file. The configuration of a proxy is covered in this MSDN article. A sample configuration is supplied in the installed configuration file.
Installing the Limeade ONE Hub Service
After starting the installation file, the user will be presented with a welcome screen. Click Next to continue.
Destination Folder
Choose the folder for the Hub service to be installed in. Click Next to continue.
Encryption Certificate
The Hub requires an encryption certificate to keep confidential information stored in the Hub secure. The certificate to use for encryption is identified by the certificate's thumbprint. Once someone knows the thumbprint of the certificate, enter it in the Certificate Thumbprint field. The user can then use a self-signed certificate or a domain certificate, whichever is preferred.
The account that the Hub will run under will need permissions to access the private key of the certificate a user specifies. Here are instructions for modifying the private key permissions:
Self-signed certificates can be generated easily using PowerShell 4.0. PowerShell 4.0 can be downloaded here:
In an admin level PowerShell window - once PowerShell 4.0 is installed - us this command to generate a self-signed certificate:
$cert = New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -Subject HubConfigEncryption -FriendlyName "Encryption Certificate for Hub Config Settings" -notAfter 2039-12-31 -KeyLength 2048 -KeySpec KeyExchange;
$cert.Thumbprint
Note: the instructions above apply to Windows 10 or Windows 8.1.
For Windows 7, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012 or Windows Server 2012 R2 please refer to:
Click Next to continue.
User Settings
Configure the user for the Windows Service. If not changed, it will install with the Local System account on the installed machine.
Note: If choosing a custom user please make sure that the user has the appropriate rights to run a Windows service.
Click Next to continue.
SQL Server Database
The Hub requires a SQL server database; users can now connect to a SQL server instance. Also, users can configure an SQL User and create a SQL Server Database.
Notes:
- When reinstalling the Hub during an upgrade, uncheck the Check to create database/uncheck to update the checkbox. If a user does forget to uncheck the checkbox, no user data will be lost.
- In order to set up to create the database, please make sure that the user who runs the install has the permissions to create the databases on the specified SQL server.
Click Next to continue.
Company ID/Shared Key/Environment Name
The Company ID and Shared Key are the identifiers of a tenant. The company ID can be retrieved on one.sitrion.com.
The environment name should, by default, target to https://one.sitrion.com.
SERVICE B
US Connection Settings:
Configure the data center that should be used by the Hub to connect with and provide all information (Namespace, key and access key) for the private Service Bus namespace. See details about Service bus namespaces in the Prerequisites section for more details.
Service Bus Protocol
Limeade recommends that the TCP/IP Service Bus relay mode be used. If this mode does not work, please consult with Limeade before using the other protocols as they have performance constraints that may affect the end-users' experience. More info about this can be found in the section Connectivity in the prerequisites.
Ready to install
Click Install to start the installation of the Hub service on the machine.
Finish
The Hub service is now installed and the Windows service has automatically been started on the machine.
Note: To check if the Windows service has been started, go to Start > Control Panel > Administrative Tools > Services.
Click Finish to exit the setup.
Upgrading the Limeade ONE Hub Service
To upgrade a Limeade ONE Hub service, just use a newer installer, which will guide users through the upgrade process.
Configuring for High Availability
Multiple Limeade ONE Hub service servers can be deployed to add fault tolerance to the on-premise Limeade ONE Hub service.
Prerequisites
- A Microsoft SQL server that is configured for high availability
- Two physical or virtualized Windows servers to run the Hub Windows service
- Two Azure Service Bus connections
Steps
- Install Hub 1 using the normal install instructions as outlined above using Server A and Service Bus Connection A.
- Install Hub 2 using the normal install instructions as outlined above using Server B and Service Bus Connection B.
Note: All Hub services must share a single database on a High Availability SQL Server deployment.
Troubleshooting
The Limeade ONE Hub is a windows service. To administer this service, navigate to the windows service management console. This console allows users to do the following:
- Start service
- Stop service
- Restart service
- Set the user context (log on) for the service
- Set recovery settings for the service
The first step in identifying issues with the Hub is to navigate to the Get Started Console in the Limeade ONE Admin portal and verify if the Hub is online or offline.
|
Online Hub |
Offline Hub |
|
|
|
If the Hub is offline, the following steps should be taken before contacting onesupport@limeade.com:
- Ensure the on-premise Limeade ONE Hub service started
- Restart the service and try again
- Review logs in the Event Viewer
- Limeade ONE Hub event logs can be found in the following location:
- Windows Event Viewer > Applications and Services > Sitrion Hub
- Limeade ONE Hub event logs can be found in the following location:
- Ensure the user context set in the login tab of the service is a user that has the following permissions:
- Run windows services
- SQL Server permissions to the Limeade One Hub database.
- Run windows services
- Ensure the SQL server hosting the Hub database is operational
Appendix A – Firewall Configuration
For those customers who block outgoing connections from the Hub service, the firewall will need to be configured to allow certain outgoing connections to the Limeade ONE infrastructure. The Hub service uses Azure Service Bus as the underlying technology to be able to communicate between https://one.sitrion.com and the on-premise Hub service.
There are three possible ways to configure a corporate firewall that will allow the Hub service to connect. None of these options require any port forwarding or opening the firewall to allow inbound traffic (aka poking a hole in the firewall).
- Allow the Hub service server(s) to connect to any IP for a given set of TCP ports
- Allow the Hub service server(s) to connect using DNS name for a given set of TCP ports
- Allow the Hub service server(s) to connect using a destination IP address for a given set of TCP ports
Allow All Outbound Traffic for Port Ranges
This is the easiest option to configure.
Configure the firewall to accept outbound traffic from the Hub service server(s) for the given set of TCP ports:
- TCP port 80
- TCP port 443
- TCP port range 5671-5672
- TCP port range 9350-9359
Allow Outbound Traffic only to a DNS name
This configuration is the most desirable when allowing all outbound traffic for a port range is not possible.
There are three DNS hostnames who will be referenced when creating firewall rules:
- https://one.sitrion.com: this is Limeade ONE's web service
- <yournamespace>.servicebus.windows.net: the hostname for the Service Bus connection itself
- The Azure Service Bus relay hostname: this is a Microsoft internal hostname of whichever internal Azure resource is hosting the Service Bus connection itself. This resource is the endpoint which receives and transmits information from the Hub to http://one.sitrion.com
Steps to Determine DNS for Azure Service Bus relay address
In these steps <yournamespace>.servicebus.windows.net will be the Service Bus URL. The Service Bus URL should be replaced with the one provided by Limeade.
- Open a Command Prompt window
- Enter the command
- Nslookup <yournamespace>.servicebus.windows.net
- This command will output something like this:
Non-authoritative answer:
Name: ns-sb2-prod-am2-001.cloudapp.net
Address: 65.52.128.246
Aliases: yournamespace.servicebus.windows.net
The hostname in bold is the relay host for the Service Bus connection.
The above address is only for demonstration purposes. The hostname and IP will be different for the Service Bus connection.
For more information: https://blogs.msdn.microsoft.com/servicebus/2017/01/13/azure-wcf-relay-dns-support/
DNS based Firewall Configuration
Once the Service Bus relay for the Service Bus namespace has been determined, the firewall can be configured.
The following ports will need to be opened by for the Hub service server(s):
- TCP Port 80 and 443 to one.sitrion.com
- TCP Port 80 and 443 to <yoursnamespace>.servicebus.windows.net
- TCP Port 80 and 443 to <Service Bus Relay DNS address>
- TCP Port 5671-5672 to <yoursnamespace>.servicebus.windows.net
- TCP Port 5671-5672 to <Service Bus Relay DNS address>
- TCP Port 9350-9354 to <yoursnamespace>.servicebus.windows.net
- TCP Port 9350-9354 to <Service Bus Relay DNS address>
The above firewall rules should always use DNS names. If the firewall rules are created using IP addresses, the underlying IPs used by the Service Bus connection and the relay will change over time.
Allow Outbound Traffic only to an IP Address
This configuration is the least desirable configuration method. Anytime the underlying IP address changes, the firewall configuration will need to be updated to match the new values.
There are two IPs who will be referenced when creating firewall rules:
- https://one.sitrion.com: this is Limeade ONE's web service. This IP can be determined by resolving the DNS entry for https://one.sitrion.com
- <yournamespace>.servicebus.windows.net: the hostname for the Service Bus connection itself. This IP can be determined by resolving the DNS entry for the Service Bus connection itself
When resolving IP addresses, it should be done from the Hub server itself. This will ensure the IP address is the correct one for a given service region.
IP based Firewall Configuration
The following ports will need to be opened for the Hub service server(s).
- TCP Port 80 and 443 to one.sitrion.com (see Appendix B or the list of IPs)
- TCP Port 80 and 443 to Service Bus connection IP
- TCP Port 5671-5672 to Service Bus connection IP
- TCP Port 9350-9354 to Service Bus connection IP
Using IP addresses in the above firewall rules has a major disadvantage. Microsoft will change the Service Bus connection IP addresses over time breaking any firewall rules pointing to the old IPs.
Quoting Microsoft’s Documentation:
Q: How often and how much do these IPs change?
A: There is no contract on this, but our expectation is that between 10-20% of the IPs will change every month.
Limeade strongly recommends using DNS filtering to simplify proxy/firewall management.
https://blogs.msdn.microsoft.com/servicebus/2017/01/13/azure-wcf-relay-dns-support/
Appendix B – IP Addresses for one.sitrion.com
- 13.70.178.182
- 52.179.97.72
- 52.237.78.192
- 52.178.73.109
Note: During service outages, additional IP addresses may be required. Once the underlying outage is resolved, an IP in the above set will be used.