Install

Overview

Before installing Gateway Hub, make sure you meet the following requirements:

You have an installation machine set up with the required software. See Installation machine requirements.
Your nodes meet the hardware and software requirements of Gateway Hub. See Hardware requirements and Software requirements.
You have run hubcheck and resolved all high severity errors. See Validate environment.
You are familiar with running hubctl commands. See hubctl tool.

Caution: If you are installing from a node, this machine must fulfil both the Hardware requirements and the Installation machine requirements.

Installation of the Gateway Hub is performed through the command line on your installation machine, following a configuration you can specify using a YAML file. The installation copies the binaries from the installation machine and configures your servers.

After installing Gateway Hub, you can connect to Gateway to enable:

Publishing metrics from Gateway to Gateway Hub. See Gateway Hub quickstart and Gateway Hub configuration.
Monitoring Gateway Hub performance from Gateway. See Gateway Hub self monitoring.
Centralised configuration of Gateways. See Centralised Gateways User Guide.

Download and unpack Gateway Hub

The Gateway Hub binaries are downloaded and unpacked onto your installation machine.

Perform the following:

Download the Gateway Hub binaries from ITRS Downloads:
- The binaries are packaged as a .tar.gz file named <version>.tar.gz.
Move the Gateway Hub.tar.gz file into a user writeable directory.
Unpack the Gateway Hub binary using the command line.
- This creates a folder called hub-installer-<version>.

Install

Installation is performed using a program called hubctl, which is located in the hub directory of your installation machine as part of the download package.

The hubctl tool reads configuration information from a YAML file that you must create. When you have completed the installation, store the installation configuration file safely in a known location.

You can use hubctl and your configuration file to reconfigure, upgrade, or uninstall Gateway Hub. Starting with version 2.3.0, Gateway Hub keeps a copy of the installation configuration file used in each installation, reconfiguration, or upgrade operation in the /opt/hub/hub-current/etc/hub-installer/configuration-history directory of each node.

For an introduction to hubctl, see hubctl tool.

More information on creating configuration files is provided below.

Installation procedure

To install Gateway Hub, follow these steps:

Go to the folder called hubctl in your chosen directory.
- This folder was created when you unpacked Gateway Hub.
Run hubctl setup install <install_config_file>, replacing <install_config_file> with the location of your installation descriptor file.
Wait for the installation to finish.

To create an installation descriptor file, start by copying the minimal file below. You will need to change the parameters included to match your deployment.

In addition, you may want to specify configurations for the following:

SSH private key authentication.
TLS certificates.
Running Gateway Hub as a different user to the installation user.
Separate disks for each storage subsystem.
Memory allowance for each service.
TCP ports of each service.

Note: Before performing the installation, the installer must unpack the Gateway Hub tarball. By default, the installer will use your temporary directory, if there is insufficient space you must provide an alternate directory. For more information, see Insufficient temporary storage in Installation machine requirements.

A full list of available options and descriptions of each are included in the full Installation configuration file example.

You can use the flag hubctl <command> --help to bring up the command line help during the installation. For an introduction to hubctl, see hubctl tool.

Success: The PLAY RECAP output on the command line states a number of ok or changed configurations, and zero unreachable or failed, similar to the example below:

Registration with systemd

After installing Gateway Hub, you can configure systemd to automatically start Gateway Hub services when a host system boots. Performing this configuration requires root privileges.

To register the Gateway Hub orchestration service with systemd, do the following on each node:

Stop the currently running Gateway Hub service:
```
hubctl stop <config_file>
```

Copy the provided orchestration.service file to the system level systemd directory:

sudo cp /opt/hub/hub-<version>/etc/hub-orchestration.service /usr/lib/systemd/system

Restart and enable the Gateway Hub service:

sudo systemctl daemon-reload
sudo systemctl enable hub-orchestration
sudo systemctl start hub-orchestration

Python on RHEL 8

By default, Ansible expects Python 2 to be available from /usr/bin/python. However, on RHEL 8.x systems this is not the case, and you must provide an alternative Python interpreter.

To set the Python interpreter, add the following to the Ansible flags section of your configuration file:

Security

Gateway Hub uses TLS to encrypt communications between Gateway Hub components and client applications. You can configure Gateway Hub to run using an internal certificate authority to sign certificates for development environments. In production environments, you must provide trusted certificates. For more information about configuring TLS, see Installation configuration file.

Installation configuration file

A Gateway Hub installation configuration file can be created as a YAML file. All sections and subsections must be written following the correct YAML syntax. The installation configuration file includes two root level sections: installation and hub.

When creating an installation configuration file, note the following:

The hub > logs_max_file_size option uses the industry standard Logback framework. As a result, files will reach an approximate maximum size but small variations from the specified size are expected. For more information, see the Logback Documentation.
When performing a local installation, the user running the installer must be the same as the Gateway Hub runtime user specified by the hub > user option. Otherwise, the installation will fail.
When providing a .pem file to configure TLS, if your Gateway Hub certificate was signed by a non-root CA certificate you should include the full CA trust chain. This is required to connect to Gateway correctly. For example, if your Gateway Hub certificate is signed using a root CA certificate, then the contents of your .pem file should be: [ Private Key, Gateway Hub Certificate, CA Certificate]. However, if your Gateway Hub certificate is signed using a non-root CA certificate, then the contents of your .pem file should be: [ Private Key, Gateway Hub Certificate, Intermediate CA Certificate, Root CA Certificate].

The following is a template file: