--- title: "Gateway Installation Guide" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway_installation_guide/index.html" --- ## 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway_introduction/index.html). For more information on configuring Gateway, see [Centralised Gateways User Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-hub/gateway-centralised-config/index.html). ## Prerequisites ### Gateway System Requirements 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.
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](/processing/../administration/gateway_licensing/#gateway-licensing). ### Prerequisite considerations Beginning Geneos version 5.0.0, this component is only compatible with other Geneos components that are version 3.6.0 or higher. For more information, see the [Geneos Compatibility Matrix](https://docs.itrsgroup.com/docs/all/geneos/7x-release/compat-matrix/). #### Installation directory The Gateway files are installed into a directory. For new installations the following directory is recommended: ```sh /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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/gateway_operating_environment/index.html#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. #### 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-administration/gateway_log_file/index.html), [Centralised Gateways User Guide](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/gateway-hub/gateway-centralised-config/index.html). #### 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](https://resources.itrsgroup.com/downloads/gateway-2-timezones). 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](https://resources.itrsgroup.com/downloads/gateway-2): - The binaries are named `geneos-gateway-..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:
File Description
gateway2.<platform> Executable binary file for the Gateway process
kafkacat See kafkacat in Gateway Publishing to Kafka and Nanomsg.
lib64 Contains required libraries.
LICENCE
LICENCE_README.txt
NOTICES
resources

Contains resources files for this version.
templates Contains template start up and files and scripts.
### How to create a start script for Gateway 1. Copy `gateway.setup.xml.tmpl` from the `templates/` folder to the working directory. 2. Rename the copy of `gateway.setup.xml.tmpl` to `gateway.setup.xml`. 3. Edit `gateway.setup.xml` to add a Gateway name: ```xml exampleGatewayName 7039 ``` 4. Copy `start_gateway2.tmpl` from the `templates/` folder to the working directory. 5. Rename the copy of `start_gateway2.tmpl` to `start_gateway2`. 6. Edit `start_gateway2` so that the Gateway runs in the background: ``` ### Run the gateway in the foreground #./gateway2.linux\_64 ${SECURE_PARAMS} ### Run the gateway in the background with logging nohup ./gateway2.linux\_64 ${SECURE_PARAMS} -log gateway2.log & ``` See [Command line options](#command-line-options) for other command line options when starting the Gateway. ### 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. 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. ### How to install using Helm The Gateway can also be deployed via Helm. Refer to [Gateway deployments](https://docs.itrsgroup.com/docs/geneos/7.11.0/administration/orchestrated-environments/installation-using-helm/index.html#gateway-deployments) for more information. ### 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. For example: ``` - - ``` 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
-aes-key-script

Runs the specified script once at Gateway startup and uses its standard output as the main AES key. This option allows the Gateway to retrieve the key from an external provider without storing it on disk.

A non-zero exit status or timeout is fatal. Standard error is not used as key material. If standard output is blank, the option is treated as unset and the Gateway uses its built-in key.

This option is mutually exclusive with -key-file.

For more information, see Secure Passwords.
-app-key

Specifies the path to the file that contains the API key used to connect securely to SSO Agent, Gateway Hub, or ITRS Analytics.

For more information about using an API key, refer to SSO Agent User Guide and Application Keys .
-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.

-demo Run the Gateway in a demo mode, without a license daemon, to trial the software. For more information, see Demo mode in Gateway Licensing.
-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 Connection.
-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-name <name>

Name of the Gateway setup.

If no setup file is specified, then Gateway fetches the named setup from Gateway Hub. See Centralised Gateways User Guide for more information.

However, if a local setup file is specified then the Gateway starts using that setup and with the name specified on the command line. If the setup file specifies a Gateway name, it must match the name specified using the -gateway-name command line option, otherwise the setup file will be rejected. This means that by omitting a Gateway name, you can use a single setup file for multiple Gateways. This is often useful in orchestrated environments, such as Kubernetes.

If the -demo command line option is also used, then the Gateway name set on the command line must be Demo Gateway otherwise the Gateway will fail to start.

-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-credential-cache <path> Path to the credential cache file. You can use the -kerberos-principal command line option with this option to specify the principal.
-kerberos-principal <principal>

A unique identity that Kerberos can assign tickets to.

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

-key-file

Specify a key file to encrypt all the AES passwords in your Gateway setup.

For more information, see 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.
-logMaskingRules <path>

Specifies a YAML or JSON file that defines log masking rules applied to Gateway log lines before they are written. A starter file is packaged as templates/log-masking-rules.yaml in the Gateway package.
-manual-failback

Prevents a primary Gateway from automatically taking over from a secondary Gateway upon restart.

A Gateway command is available on the secondary Gateway to return control to the primary. This allows you to restart your Gateway and transfer control at a convenient time.

Both Gateways must be started with this option to enable manual failback functionality.

For more information, see Manual failback in Hot Standby.
-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
  • 1.3

For more details, see Secure Communications.
-iax <URL>

URL of ITRS Analytics.

Required when using Centralised Configuration in ITRS Analytics.

Example: https://itrs-analytics.example.com
-iax-timeout

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

Default value: 5 seconds
-openssl-cipher <ciphers> To set the available TLS ciphers use the `-openssl-cipher ` command line option, replacing `` with a comma separated list of ciphers. For more information, see TLS ciphers in 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.

-previous-aes-key-script

Runs the specified script once at Gateway startup and uses its standard output as the previous AES key during key rotation.

A non-zero exit status is logged as an error and the Gateway continues without a previous key. Standard error is not used as key material. Blank standard output is treated as unset.

This option requires either -key-file or -aes-key-script, and is mutually exclusive with -previous-key-file and -previous-key-geneos.

For more information, see Secure Passwords.
-previous-key-file

Specify a fallback keyfile to encrypt AES passowrds. Allows Gateway to use two keys while you transition to a new key.

For more information, see Secure Passwords
-previous-key-geneos

Uses the Geneos built-in AES key as the previous key while migrating to a custom main key.

This option requires either -key-file or -aes-key-script, and is mutually exclusive with -previous-key-file and -previous-aes-key-script.

For more information, see Secure Passwords.
-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 the default port 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.
-store-app-key

Generates an API key file from a provided client_id and client_secret.

The command uses the format ./gateway2.linux_64 -store-app-key <filename> <client_id> <client_secret>.

For more information about using an API key, see Connect securely using SSO or API keys, SSO Agent User Guide, Gateway Hub SSO Agent , and Application Keys .
-validate

Used to validate setup files without using ActiveConsole. It performs Gateway validation, see Validation types for more information. 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. See Validation types for more information.

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.

## Required libraries #### RHEL 10 | Library Name | Package Name | | --- | --- | | libssl.so.3 | openssl-libs | | libcrypto.so.3 | openssl-libs | | libcrypt.so.2 | libxcrypt | | libresolv.so.2 | glibc | | libz.so.1 | zlib | | libm.so.6 | glibc | | libc.so.6 | glibc | #### RHEL 9 | Library Name | Package Name | | --- | --- | | libssl.so.3 | openssl-libs | | libcrypto.so.3 | openssl-libs | | libcrypt.so.2 | libxcrypt | | libresolv.so.2 | glibc | | libz.so.1 | zlib | | libm.so.6 | glibc | | libc.so.6 | glibc | #### RHEL 8 For Geneos 7.11.2 and later, use the generic Linux x86-64 package. | Library Name | Package Name | | --- | --- | | libutil.so.1 | glibc | | libnsl.so.1 | libnsl | | libpthread.so.0 | glibc | | libdl.so.2 | glibc | | libcrypt.so.1 | libxcrypt | | libresolv.so.2 | glibc | | libz.so.1 | zlib | | librt.so.1 | glibc | | libm.so.6 | glibc | | libc.so.6 | glibc | For Geneos 7.11.1 and earlier, use the dedicated RHEL 8 package. | Library Name | Package Name | | --- | --- | | libssl.so.1.1 | openssl-libs | | libcrypto.so.1.1 | openssl-libs | | libutil.so.1 | glibc | | libnsl.so.2 | libnsl | | libpthread.so.0 | glibc | | libdl.so.2 | glibc | | libcrypt.so.1 | libxcrypt | | libresolv.so.2 | glibc | | libz.so.1 | zlib | | librt.so.1 | glibc | | libm.so.6 | glibc | | libc.so.6 | glibc | #### SUSE 12 and 15 (64-bit) |Library Name |Package Name| | ----|----| |libutil.so.1 |glibc| |libnsl.so.1 |glibc or libnsl-2 on RHEL 8 and CentOS 8| |libpthread.so.0 |glibc| |libdl.so.2 |glibc| |libcrypt.so.1 |glibc| |libresolv.so.2 |glibc| |librt.so.1 |glibc| |libm.so.6 |glibc| |libc.so.6 |glibc| |ld-linux.so.2 |glibc| |libz.so.1 |libz1| |libstdc++.so.6 |libstdc++| |libgcc_s.so.1 |libgcc-4| #### Ubuntu 18 |Library Name |Package Name| | ----| ----| |libutil.so.1 |libc6| |libnsl.so.1 |libc6| |libpthread.so.0 |libc6| |libdl.so.2 |libc6| |libcrypt.so.1 |libc6| |libresolv.so.2 |libc6| |libz.so.1 |zlib1g| |librt.so.1 |libc6| |libm.so.6 |libc6| |libgcc_s.so.1 |libgcc1| |libc.so.6 |libc6| #### Ubuntu 20 and 22 |Library Name |Package Name| |:----|:----| |libutil.so.1 |libc6| |libnsl.so.1 |libc6| |libpthread.so.0 |libc6| |libdl.so.2 |libc6| |libcrypt.so.1 |libcrypt1| |libresolv.so.2 |libc6| |libz.so.1 |zlib1g| |librt.so.1 |libc6| |libm.so.6 |libc6| |libgcc_s.so.1 |libgcc-s1| |libc.so.6 |libc6|