Gateway Hub ["Geneos"]

Installation machine requirements

Overview

Before installing Gateway Hub on a server, you must have an installation machine set up to perform the installation. This machine can act as a node but is not required to. The installation machine has additional software requirements.

During the installation, this machine copies the Gateway Hub binaries from itself to the servers that constitute your Gateway Hub cluster.

Operating Systems

Your installation machine must be one of the following operating systems:

  • Linux
  • macOS X
  • Windows Subsystem for Linux

Software requirements

Your installation machine must have:

Requirement Versions Supported
Python 3.6 or newer
PyYAML ≥ 5.3.1 and < 6.0.0
Ansible ≥ 2.8.0 and ≤ 2.10.0
GNU Tar  
JMESPath  
   

A list of requirements for performing installation can be found in hubctl/requirements.txt and installed by running pip3 install --user --requirement requirements.txt.

Additional download and installation instructions for Ansible can be found here.

Note: Python packages should be installed using their Python 3 version.

Ansible compatibility

Certain versions of Ansible require additional configuration to operate correctly.

The Gateway Hub installer is only compatible with Ansible versions belonging to major version 2.

SaltStack

The salt configuration managment tool is sometimes used with PyYAML. This may cause the the C-extension of PyYAML to be used by Ansible resulting in an error.

If you are using Ansible version 2.9, then the salt package is not supported. If it exists, you must remove this package from the installation machine.

Mitogen

Gateway Hub uses Mitogen as a connection layer to improve Ansible performance.

If you are using Ansible versions 2.9.x or 2.10, then Mitogen is not supported. You must disable Mitogen when running the installer.

If you are using Ansible 2.9.x then, when running the hubcheck tool, you may encounter a timed out waiting for ping module test success: Object of type bytes is not JSON serializable error if you have not disabled Mitogen.

To disable Mitogen, add the following to the installation section of your configuration file:


                                

                            

                            

                                
Insufficient temporary storage

                                
Before performing the installation, the installer must unpack the Gateway Hub tarball on your installation machine. By default, the installer will use your temporary directory. On Linux systems this is usually /tmp and on Windows systems this depends on your version. You must ensure there is sufficient space to unpack the tarball, as of Gateway Hub version 2.4.1 the uncompressed size is 1.6 GB. If your temporary directory does not have sufficient space, you will need to use an alternate directory. 

                                
For example, on a Linux system you can use  /var/tmp instead of the default /tmp by performing the following steps:

                                
    
                                    
  1. 
                                        
    Delete and re-create directory /tmp/.ansible-<hub user>, where <hub_user> is the  Gateway Hub runtime user, as defined in the installation descriptor.
    rm -Rf /tmp/.ansible-gwh; mkdir -p /tmp/.ansible-gwh
    
                                    
    2. 
                                    
  2. 
                                        
    Create a symlink from your alternate  directory to  the /tmp/.ansible-<hub user> directory you just created. 
    ln -fs /var/tmp /tmp/.ansible-gwh
    
                                    
    3. 
                                    
  3. 
                                        
    Run the installer using your alternate directory, by specifying the TMPDIR variable in the command.
    TMPDIR=/var/tmp hubctl setup install hub.yml
    
                                    
    4.