Troubleshoot Installation

Overview

This guide is intended to help you troubleshoot your Gateway Hub instance during installation. If you encounter problems with a running Gateway Hub, consult Troubleshoot Maintenance.

Common errors are often caused by a failure to meet Gateway Hub's requirements, you must ensure your environment meets all these before proceeding.

To do this, consult the following pages before proceeding:

You can check many, but not all, requirements by running the hubcheck tool, and you should resolve any errors before proceeding.

For more information, see Validate environment.

Installation

Certificates

Obtain the Subject Alternative Name of a certificate

You can extract the Subject Alternative Name from a certificate using the OpenSSL command line tool. This allows you to ensure it matches the Gateway Hub domain. For more information, see Installation configuration file in Install.

To extract the Subject Alternative Name, run:

openssl x509 -in <certificate_file> -text -noout

Which will return output similar to:

X509v3 Key Usage:
    Digital Signature, Non Repudiation, Key Encipherment
X509v3 Extended Key Usage:
    TLS Web Server Authentication, TLS Web Client Authentication
X509v3 Subject Alternative Name:
    DNS:DNS-name-1, DNS:DNS-name-2, ...

Add Gateway Hub certificate authority to Grafana

In order for Grafana to connect to Gateway Hub securely, the certificate authority (CA) that has signed the TLS/SSL certificate used by Gateway Hub must be trusted by the system running Grafana.

If Gateway Hub is installed using certificates signed by an non-trusted CA, including the internal CA, you must add the relevant CA certificate to the trust store of the Grafana host. If Gateway Hub has been configured using production certificates that are trusted across an organisation, this is not required.

If you attempt to connect Grafana and Gateway Hub using non-trusted certificates, the connection will fail and Grafana will receive no data. The server logs will include a Failed to get access token error and state certificate signed by unknown authority.

To add Gateway Hub to a Linux system's recognised certificate authorities:

Locate the CA certificate used to sign Gateway Hub certificates. In a default installation, using an internal CA, this is /opt/hub/hub-2.2.0-GA/tls/ca.crt.
Copy the CA certificate to the trust store of the Grafana host. In a CentOS or Red Hat system this is located at /etc/pki/ca-trust/source/anchors/.
To update the recognised certificate authorities, run:
```
update-ca-trust extract
```
1. You can verify the updated list by running:
```
trust list
```
Restart Grafana.
In the Grafana web interface, open the ITRSGeneosGateway Hub Datasource settings and disable Skip TLS Verify.

Renew Gateway Hub server certificate

When installing Gateway Hub, you can choose to use self-signed certificates for TLS connections between Gateway Hub components.

The installer generates a self-signed CA certificate and uses it to sign the server certificate used by Gateway Hub. The CA certificate generated by the installer has a lifetime of 100 years. However, the server certificate has a lifetime of 397 days and you must generate a new certificate before it expires.

To generate a new server certificate, run:

hubctl setup reconfigure config.yml