This is documentation for EA software. It may contain information that is out of date and subject to change. Last updated: 3 October 2018.

Gateway Hub Installation Guide

Overview

This guide details how to install and validate an installation of Gateway Hub.

For pre- install information, see Gateway Hub Pre-Install Guide.

For publishing from Geneos to Gateway Hub, see Publish to Gateway Hub User Guide.

Procedure

Ensure you have consulted the Gateway Hub Pre-Install Guide before beginning the installation.

The workflow will guide you through how to install the Gateway Hub, install the required SSL certificates, and validate your Gateway Hub installation.

How to download and unpack Gateway Hub

Ensure you have an installation machine set up with the prerequisites before installing Gateway Hub. See Installation machine prerequisites.

To download and unpack the Gateway Hub on to your installation machine, follow these steps:

  1. Download the Gateway Hub binaries from the ITRS group website:
    • The binaries are named gateway-hub-<version>.tar.gz.
  2. Move the Gateway Hub .tar.gz file into the desired directory.
  3. Unpack the Gateway Hub binary using the command line.
    • This creates a folder called hub-deployment.

How to install Gateway Hub on a server

Ensure you have a valid target server to install Gateway Hub on. See Gateway Hub server prerequisites.

Ensure you have the required software installed on the target server. See Additional software requirements.

The steps here assume you have a already unpacked the Gateway Hub binaries to your chosen folder.

To install Gateway Hub to a server, follow these steps:

  1. Go to the folder called hub-deployment in your chosen directory.
  2. Run hub-setup.sh install with the following flags:
    • --disks — A comma-seperated list of data (MapR) disks on the target machines.

      Caution: The disks must be available, unformatted, and not mounted. You cannot specify a disk that is currently being used by any other file system.

    • --disk-pool-size — Size of the disk pools on the target machine. A disk pool is a unit of storage made up of one or more disks. Default is 1.
    • --hosts — A comma-separated list of IP addresses of target machines.
    • --hub-setup-user — The user performing the installation on the target machine.

      Caution: You must have already created this user. The user must be on the sudoers list on the target machine. See Users.

    • --no-user-create — Instructs the install script not to make any users.
    • --global-user — Name of the runtime user. See Users.
    • --global-group — Group of the runtime user.
    • If you are using passwordless SSH, use the following flag to specify the location of your Kafka disk:
      • --ansible-flags "-e kafka_partition_log_location=<kafka_disk>" — Replace <kafka_disk> with the location of your Kafka disk.
    • Caution: The disk must be available and formatted. You cannot specify a disk that is currently being used by any other file system.

    • If you are not using passwordless SSH, you must use the following flag to specify the location of your Kafka disk:
      • --ansible-flags "--ask-pass -e kafka_partition_log_location=<kafka_disk>" — Replace <kafka_disk> with the location of your Kafka disk. The install asks you for the password of the installation user (the one specified using --hub-setup-user).
    Below is an example of the command:
    $ ./hub-setup.sh install --hosts 54.171.64.45 --disks /dev/nvme1n1 --disk-pool-size 1 --hub-setup-user ec2-user --no-user-create --global-user hub --global-group hub --ansible-flags "--ask-pass -e kafka_partition_log_location=/mnt/kafka_data" 
  3. Wait for the installation to finish. This takes approximately 10-15 minutes.

How to install SSL certificates on a server

After installing Gateway Hub, you must add the SSL certificates to each server in your instance.

Before installing the certificates, you must have:

  • Generated an SSL certificate and a Certificate Signing Request (CSR). The certificate must be signed by a valid Certificate Authority (CA).
  • The CA root/intermediate certificates available. These are needed to generate the ssl_truststore.
  • Installed Java Keytool, and have it available in your PATH.

The instructions below use of the following terms:

  • <CA_crt> — One or more files, usually ending in .crt, containing the root/intermediate certificate from the CA. This is provided with the <server_crt> by the CA.
  • <password> — Password chosen by you to use in the ssl_keystore and ssl_truststore.
  • <server_crt> — File, usually ending in .crt, containing certificate generated by the CA after signing the CSR.
  • <server_key> — File, usually ending in .key or .pem, containing the server key created to generate the CSR.
  • <server_name> — String specifying the "friendly name" for the certificate and private key.

In order to install the SSL certificates, a ssl_keystore and ssl_truststore must be generated. To generate a ssl_keystore and ssl_truststore, follow these steps:

  1. Put the <server_crt>, <server_key> and <CA_crt> into the same folder and generate a pkcs12 certificate. Use the following command, replacing the terms in <> with your information using the terms above:
$ openssl pkcs12 \
	-export \
	-chain \
	-in <server_crt> \
	-inkey <server_key> \
	-out <server_name>.pk12 \
	-name <server_name> \
	-CAfile <CA_crt> \
	-passout pass:<password>
  1. Create the ssl_keystore from the previous .pk12 file. Use the following command, replacing the terms in <> with your information using the terms above:
$ keytool --importkeystore \
	-noprompt \
	-deststorepass <password> \
	-destkeystore ssl_keystore \ 
	-srckeystore <server_name>.pk12 \
	-srcstoretype PKCS12 \
	-srcstorepass <password>
  1. Create the ssl_truststore from the <CA_crt> files (the root/intermediate certificate from the CA). Repeat the following command for each <CA_crt> file. Use the following command, replacing the terms in <> with your information using the terms above:
$ keytool -importcert \
	-trustcacerts \
	-noprompt \
	-file <CA_crt> \
	-keystore ssl_truststore \
	-alias <server_name> \
	-keypass <password> \
	-storepass <password>

You have now generated the ssl_keystore and ssl_truststore files. They now must be copied and installed on each node in a cluster:

  1. Copy the ssl_keystore and ssl_truststore to each node. Use the following command, replacing the terms in <> with your installation user (the one specified using --hub-setup-user on install) and node IP:
$ scp -i <hub-setup-user_pem_key> ./ansible/roles/itrs-install-certs/files/ssl_* <hub-setup-user>@<node_ip>:/tmp
  1. SSH into the host and stop MapR Warden and MapR Zookeeper in each node of the cluster. Use the following commands:
$ sudo systemctl stop mapr-warden
$ sudo systemctl stop mapr-zookeeper
  1. Copy the SSL files to the correct location and set the permissions. Use the following commands, replacing the terms in <> with your runtime user and runtime user group (the one specified using --global-user and --global-group on install):
$ sudo cp /tmp/ssl_* /opt/mapr/conf/
$ sudo chown <runtime_user>:<runtime_user_group> /opt/mapr/conf/ssl_*
$ sudo chmod 444 /opt/mapr/conf/ssl_keystore
$ sudo chmod 444 /opt/mapr/conf/ssl_truststore
  1. Restart MapR Warden and MapR Zookeeper on each node. Use the following commands:
$ sudo systemctl start mapr-zookeeper
$ sudo systemctl start mapr-warden

How to request a permanent MapR licence for Gateway Hub

When a new Gateway Hub instance is generated, a trial licence is also generated providing access for 30 days. This enables functionality required for install, and may be sufficient for short-lived environments.

For longer-term instances, a permanent licence must be acquired. To acquire a permanent licence, follow these steps:

  1. Log into the MapR admin instance by entering https://<hostname>:8443 in a web browser, replacing <hostname> with the hostname of the Gateway Hub server:

    • Use the username and password of your Gateway Hub runtime user.
    • Click Log In.

    Note: If a secure certificate hasn't been installed you may need to ignore any certificate error.

  2. Navigate to Admin > Cluster Settings using the toolbar at the top of the page.
  3. On the Admin / Cluster Settings page, select the Licenses tab.
  4. Make a note of the Cluster ID.
  5. Contact ITRS support or your technical representative and request a new licence. Include the following information:
    • Account name.
    • The cluster ID from step 3.
    • Number of nodes in the cluster.
  6. Once you have received a licence from MapR, log in to the MapR admin instance again, as detailed in step 1.
  7. Navigate back to Admin > Cluster Settings > Licenses.
  8. Add the licence using Upload Licence File.
  9. Press Submit when ready.

How to validate a Gateway Hub installation

The steps here assume you have already installed the Gateway Hub to a target server.

You can validate the installation with either of the following methods:

  1. Use a browser, a dedicated client such as Postman, or curl -k in the command line, to query the REST address followed by /v0/ping. The default REST address is https://<hostname>:8080/.

    If the installation is successful, this returns 200 OK, and no output.

  2. Log into the MapR admin instance by entering https://<hostname>:8443 in a web browser, replacing <hostname> with the hostname of the Gateway Hub server:

    • Use the username and password of your Gateway Hub runtime user.
    • Click Log In.

    If the installation is successful, the page shows the admin interface.

Next steps

After successfully installing Gateway Hub, see Publish to Gateway Hub User Guide for how to connect a Gateway and start publishing to Gateway Hub.

Appendix

Installation flags

Below is a list of all the possible flags that could be specified using the hub-setup.sh install command:

Flag Effect
--disks A comma-seperated list of disks on the target machines.
--disk-pool-size Size of the disk pools on the target machine. A disk pool is a unit of storage made up of one or more disks.
--global-group Specifies the group for the single user defined with --global-user.
--global-user Specifies the single user for Gateway Hub admin and services and MapR. The user must exist.
--hosts A comma-separated list of IP addresses of target machines.
--hub-setup-user Specifies the user performing the installation on the target machine. The user must exist.
--no-user-create Specifies the install script not to create users.
--user-api Specifies the user that runs the REST API daemon.