Geneos
Geneos
Recommended Reads

Gateway Installation Guide

Overview

This document describes the prerequisites for a Geneos Gateway, how to install and how to start using a Gateway.

For information describing the features of a Gateway, see Gateway Introduction. For more information on configuring Gateway, see Centralised Gateways User Guide.

Prerequisites

Gateway System Requirements

Prerequisite Description
Gateway Machine
OS: RedHat Linux (Preferred), Suse Linux
CPU: Dual CPU, Dual Core
Memory: 8GB (64-bit)
Network: 1 Network Card or 2 bonded Network cards (100 mbps)
Disk: 500 MB* software only, does not include database table space
Hardware: Virtual or Physical
SSH Access SSH access to the Gateway server is required for initial installation and configuration of the Geneos software.
SCP Access The Geneos software is installed in a nominated directory (/opt/geneos) or a user's home directory. This should be a common directory across all machines. SCP access to each server and directory is required to copy the Gateway binaries.
Port 7039 Default port for communication between the Gateway server and Active Console.
SendMail In order to perform actions such as e-mail alerts the Gateway server requires a sendmail daemon to be running so that outgoing messages can be properly routed.

When Security-Enhanced Linux (SELinux) is running in Enforcing mode, it may deny certain functions of Geneos depending on the implemented configurations and policies.

To see which functions SELinux denies, check the audit log. The log is typically located in /var/log/audit.log, where the log type entry is AVC. The audit log provides the details of any denied access. For example, denied connection to the TCP port.

If you experience issues related to this mode, you may opt to disable SELinux, or create policy modules to grant the required access. Please contact your administrator or security team for assistance.

Gateway licensing

For the Gateway to function, an appropriate licensing method must be in place. See Gateway Licensing.

Prerequisite considerations

Installation directory

The Gateway files are installed into a directory. For new installations the following directory is recommended:

/usr/local/geneos/gateway

Port numbers

Each installed Gateway must have a unique port to listen for client connections. The default gateway ports are:

  • 7039 for insecure channel.
  • 7038 for secure channel.

If these ports are unavailable or you are hosting multiple Gateways on a single machine, then you need to select available unique ports for the Gateway. See operatingEnvironment > listenPorts.

Gateway name

Each installed Gateway must have a unique name. The name is important as it is used when selecting data and defining rules. Select a unique name that can be used to identify this Gateway's purpose within your organisation.

Note: Changing the Gateway name once monitoring has begun is not recommended. You must select a suitable name from the outset.

Gateway ID

The Gateway process uses a unique 32-bit integer value as a Gateway ID.

This ID allows data generated by this Gateway to be identified by connecting processes. If the ID is not specified, it is automatically generated by the Gateway using the Gateway name.

It is highly recommended that each Gateway has an explicitly defined ID and name.

Select log file and setup directories

The Gateway generates a log file and requires at least one master setup file per running instance. As it is common to have multiple Gateway instances running on a single host, it is useful to organise these files.

Geneos can accommodate if your organisation has specific guidelines as to where configuration and log files must reside.

See Gateway Log File, Centralised Gateways User Guide.

Gateway resources

The Gateway is shipped with a set of xslt resource files and a timezone file. The resources directory, or a symbolic link to it, must exist in the working directory of the Gateway at startup time because these files are part of the runtime source code.

The files should not be edited by users and doing so may result in unexpected behaviour. When a Gateway binary is upgraded the resource files must also be upgraded to the version supplied with the new Gateway.

The Gateway time zone resources file is also available separately as a package from ITRS Resources. The package contains the time zone file and a README file with installation instructions.

Procedure

This section describes how to install a Gateway up to the point where the setup can be edited by a connected Gateway Setup Editor.

How to download and unpack Gateway

Ensure you have machine set up with the prerequisites before installing the Gateway.

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

  1. Download the Gateway binaries from the ITRS group website:
    • The binaries are named geneos-gateway-<version number>.<platform>.tar.gz.
  2. Move the Gateway .tar.gz file into the desired installation directory.
  3. Unpack the Gateway binary using the command line.
    • The binary contains the following:
    FileDescription
    gateway2.<platform>Executable binary file for the Gateway process
    kafkacatSee kafkacat in Publish to Kafka.
    lib64Contains required libraries.
    LICENCE 
    LICENCE_README.txt 
    NOTICES 
    resources

    Contains resources files for this version.

    templatesContains template start up and files and scripts.

How to create a start script for Gateway

  1. Add a reference the lib64 folder to the environment using the following command:

    export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:<SetupDirectory>/lib64
  2. Copy gateway.setup.xml.tmpl from the templates/ folder to the working directory.
  3. Rename the copy of gateway.setup.xml.tmpl to gateway.setup.xml.
  4. Edit gateway.setup.xml to add a Gateway name:

    <operatingEnvironment>
                <!--The gateway name must be set, the listen port should be set-->
                <gatewayName>exampleGatewayName</gatewayName>
                <listenPorts>
                        <insecure>
                                <listenPort>7039</listenPort>
                        </insecure>
                </listenPorts>
 </operatingEnvironment>

  5. Copy start_gateway2.tmpl from the templates/ folder to the working directory.
  6. Rename the copy of start_gateway2.tmpl to start_gateway2.
  7. Edit start_gateway2 so that the Gateway runs in the background:

    ### Run the gateway in the foreground
#./gateway2.linux ${SECURE_PARAMS}

### Run the gateway in the background with logging
 nohup ./gateway2.linux ${SECURE_PARAMS} -log gateway2.log &

    See Command line options for other command line options when starting the Gateway.

    Note: If you are using the 64bit binaries you will need to edit start_gateway2 to run gateway2.linux_64.

How to start and configure the Gateway

  1. Run the start_gateway2 script to start the Gateway process.
  2. Connect an Active Console to the Gateway.
  3. Open the Gateway Setup Editor.
  4. Navigate to Operating environment.
  5. Set the Gateway name and ID.

You can now start adding monitoring configuration via the Gateway Setup Editor.

How to upgrade to a new Gateway version

To upgrade to a later Gateway binary from an existing installation:

  1. Stop the current Gateway process.
  2. Copy the new binary and resources files into the installation directory.
  3. Restart the Gateway process.

Command line options

The Gateway can be started with command line options. These options can be entered on the command line or read from a file.

By default, the Gateway attempts to read command line options from a file called gateway2.gci in the Gateway's working directory. This file is not supplied with the Gateway and you must create it yourself. Alternatively, you can specify the file for the Gateway to read using the -config-file command line option.

Command line options in the file are processed before any on the command line, except for -config-file which is always processed first.

The following command line options are available:

Option

 Use
-ase256-encrypt This option relates to storing passwords in the Gateway setup. It is explained in Secure Passwords.
-autolock

Forces a GSE connected to the Gateway to lock setup files (or include files) if a user wants to update them. Other connected GSEs are notified when a lock on a file becomes available and will have a chance to lock it.

If GSE's are connected to different gateways that share an include file, they are only be prevented from updating the include file at the same time. For more information, see Autolock.
-config-file <path>

Path to configuration file containing command line options. By default, the Gateway attempts to read from a file called gateway2.gci in Gateway's working directory. This file is not supplied with the Gateway and you must create it yourself.

Command line options in the file are processed before any on the command line, except for -config-file which is always processed first.

-display-timezone-defaults

Prints the default timezone for timezone abbreviations by reading the timezone resources file. The defaults are mentioned in Time Zones and Time Formats and marked with asterisk(*).
-dump-xml

Print the contents of the merged xml tree (Gateway setup) to the log file or stdout, then exit. Can be used with -setup, -log or -nolog as required.

The merged nodes have an additional attribute to specify which setup file this node came from. A node coming from main file has the attribute main="true", whereas a node coming from include file has the attribute include="/path/to/include/file/as/specified/in/the/setup". It is implicit that child nodes not having such attribute inherit it from their ancestor node. For illustration, see Merged Setup example.

This mode is intended for testing/debugging purposes.
-en

This option relates to storing passwords in the Gateway setup. It is explained in Secure Passwords.
-gateway-hub <URL>

URL of the Gateway Hub.

Only one URL is supported.

Example: https://hub.example.com:8080

If provided, this takes precedence over the REST address provided in the Gateway Hub section in the GSE. See Gateway Hub Publishing Technical Reference.
-gateway-hub-timeout

Number of seconds that the Gateway waits for a response from Gateway Hub after sending a validation or save request before timing out. The request may time out if the Gateway Hub is responding to other requests.

Default value: 5 seconds.

See Centralised Gateways User Guide for more information.
-gateway-id <ID>

ID of the Gateway setup to acquire from Gateway Hub.

See Centralised Gateways User Guide for more information.
-help [topic]

Displays help about the topic if specified, or this help message. Topic can be any of the parameters shown below.
-hooks-dir <resource-dir>

Specifies the location of the hooks directory. This directory contains the user defined hooks that are run at setup validation and after a setup change is applied by the Gateway. See Gateway Hooks.
-hooks-timeout Changes the hooks timeout from the default of 2 minutes to the value specified. Values greater than the default result in a warning that Gateway performance may be degraded. See Gateway Hooks.
-kerberos-keytab <path> Path to the keytab file. The principal must also be specified.
-kerberos-principal <principal>

A unique identity that Kerberos can assign tickets to.

Examples: user@REALM or user/admin@REAL.

-key-file

This option relates to storing passwords in the Gateway setup. It is explained in Secure Passwords.
-licence

Specifies the location of the temporary licence file that the Gateway uses in absence of a Licence Daemon.
-licd-host

Specifies the host name or IP address of the Licence Daemon the Gateway uses when requesting licences.

Default: localhost.
-licd-port

Specifies the port where the Licence Daemon is listening on.

Default is 7041.
-licd-secure

Specifies that the Gateway connects to the Licence Daemon using TLS.

If this is not used then an insecure protocol is used to transfer licences from the Licence Daemon to the Gateway.

The Gateway and Licence Daemon must be identically configured.
-log <logfile> | -nolog

Used to specify the name of the Gateway log file.

The LOG_FILENAME environment variable can also be used to configure this, however the command line option overrides the environment setting.

Running the Gateway with the -nolog option overrides all other log settings and prints output to stdout.

The Gateway sends its output to stdout if this option is not set.
-max-severity <none|warn|error>

Used to specify the maximum allowable setup severity. The maximum severity controls whether the Gateway allows a setup to be applied.

For example, if the maximum severity is set to warn, and the setup file contains problems with a severity of warning or less, then the setup is applied, otherwise it is rejected.

Possible severity settings are:

  • none — setup is applied only if there are no problems.
  • warn — setup is applied only if any problems are warnings.
  • error — setup is applied only if any problems are errors or warnings.

Default if not specified: error.
-minTLSversion

Specifies the minimum TLS version. The accepted values are:

  • 1
  • 1.0
  • 1.1
  • 1.2

For more details, see Secure Communications.

-port <number>

Used to specify the port the Gateway listens on for other components.

The option must be followed by the listen port, a positive integer in the range 1-65535 inclusive.

Note: On some systems ports in the range 1-1024 are reserved, and the Gateway requires special permissions to listen on a port in this range.

If -port is not specified, the default ports are :

  • 7039 for insecure channel.
  • 7038 for secure channel.

If only the secure listen port is configured in the Gateway setup file, then -port overrides this configuration.

If only insecure listen port is configured in the Gateway setup file, then -port overrides this configuration.

If both secure and insecure listen ports are configured in the Gateway setup file, then -port overrides the secure listen port.

Note: If you specified a port using -port that is already in use, the Gateway uses the port specified in the Gateway setup file. If no port is specified in the setup file, the default is used. See operatingEnvironment > listenPorts.
-process-dump-files

Starts a process to read all the database dump files that have been created by the Gateway and inserts them into the database. See Database dump files section.
-pw

This option relates to storing passwords in the Gateway setup. It is explained in Secure Passwords.
-resources-dir <resource-dir>

Specifies the location of the resource directory. This directory is provided as part of the Gateway package.

By default it is the directory resources in the current working directory of the Gateway. If running multiple Gateways in multiple working directories from the same package, this is option can be used to provide access to the shared resource.
-roll-time <HH:MM>

Sets a predetermined file rollover time for the Gateway log file. When set, the log file roll over occurs when the first log message comes in after the requested rollover time.

The format must be HH:MM for example 6 am would be specified as -roll-time <06:00>.
-setup <filename>

Used to specify the setup file Gateway should use. The option must be followed by the filename, which should not start with a - (dash) character.

If -setup is not specified, the default file of gateway.setup.xml is used.
-setup-comments <none|optional|required>

Controls if the Gateway Setup Editor (GSE) asks for comments when you change the setup file. There are three options:

  • none — The GSE does not ask for a comment when you press Save on a Gateway setup.
  • optional — The GSE asks for a comment when you press Save on a Gateway setup. However, you are not required to enter any text. Warnings present.
  • required — the GSE asks for a comment when you press Save on a Gateway setup, and the system will not save the file until you have entered some text. Errors present.

Default if not specified: optional.
-skip-cache

Loads setup from files on disk instead of cache even if some setups are inactive (outside their active time). The cache contains setup files that the Gateway was running before shutdown.
-sso-agent <URL>

URL of the SSO Agent that is providing an SSO Token to use with Gateway Hub.

This is only required if you are not using the SSO Agent on port 9999 of the Gateway Hub.

See Centralised Gateways User Guide for more information.
-ssl-certificate

Specifies the file that contains the signed SSL server certificate in PEM (Privacy-enhanced Electronic Mail) format.
-ssl-certificate-chain

Specifies the file that contains the trusted certificate authority.
-ssl-certificate-key

Specifies the file that contains the signed SSL server private key in PEM (Privacy-enhanced Electronic Mail) format. If this is option is not specified, but -ssl-certificate is then the Gateway searches for the private key in the same file as the server certificate.
-stats

Enables gateway load monitoring statistics collection from start-up.

This flag can be useful in diagnosing gateway performance issues only seen on start-up, rather than those occurring during normal gateway operation.
-validate

Used to validate setup files without using ActiveConsole. By default it validates the default Gateway setup file gateway.setup.xml unless the -setup <filename> option is also used. Use with:

-setup <filename> Specifies the filename to validate.
-silent Prevents the Gateway from producing any output. Check the return code for indication of success. This may be useful for automated checking scripts.
-strict Performs stricter validation (by validating against the schema).

Returns:

  • 0 — Success.
  • 1 — Warnings present.
  • 2 — Errors present.
  • 3 — Critical errors present.
  • 4 — Fatal errors present.
-validate-json-output <filename>

This option (which implicitly selects the -validate option) causes the validation results to be written to the specified file, in JSON syntax.
-v, -version

Used to display version information for the Gateway. It contains information about the exact version of the Gateway and all the libraries contained within.

Appendix

Required libraries

The Linux version of this component requires the following libraries to run. These are listed along with the packages they can be found in for the following 64-bit operating systems.

(missing or bad snippet)

CentOS / Redhat(64-bit)

Library NamePackage Name
libutil.so.1glibc-2.5-34
libnsl.so.1glibc-2.5-34 or libnsl on RHEL 8 and CentOS 8
libpthread.so.0glibc-2.5-34
libdl.so.2libdl.so.2
libcrypt.so.1glibc-2.5-34
libz.so.1zlib-1.2.3-3
libresolv.so.2glibc-2.5-34
libstdc++.so.5compat-libstdc++-33-3.2.3-61
libm.so.6glibc-2.5-34
libgcc_s.so.1libgcc-4.1.2-44
libc.so.6glibc-2.5-34
ld-linux.so.2glibc-2.5-34

Suse (64-bit)

Library NamePackage Name
libutil.so.1glibc-32bit-2.4-31.2
libnsl.so.1glibc-32bit-2.4-31.2
libpthread.so.0glibc-32bit-2.4-31.2
libdl.so.2glibc-32bit-2.4-31.2
libcrypt.so.1glibc-32bit-2.4-31.2
libz.so.1zlib-32bit-1.2.3-15.2
libresolv.so.2glibc-32bit-2.4-31.2
libstdc++.so.5compat-libstdc++-5.0.7-22.2
libm.so.6glibc-32bit-2.4-31.2
libgcc_s.so.1libgcc-4.1.0-28.4
libc.so.6glibc-32bit-2.4-31.2
ld-linux.so.2glibc-32bit-2.4-31.2