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.

Prerequisites

Gateway System Requirements

Prerequisite Description
Gateway Machine
OS: RedHat Linux (Preferred), Suse Linux, Solaris (X86 and Sparc)
CPU: Dual CPU, Dual Core
Memory: 2GB (32bit), 8GB (64bit)
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 for actions such as e-mail alerts to be demonstrated the Gateway server requires a sendmail daemon running so outgoing messages can be properly routed.

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: It is difficult to change the Gateway name once monitoring has begun so 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.

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.

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 gateway2.<platform>.GA<version number>.tar.
  2. Move the Gateway .tar.gz file into the desired directory.
  3. Unpack the Gateway binary using the command line.
    • The binary contains the following:
    FileDescription
    gateway2.<platform>libExecutable binary file for the Gateway process
    templates/gateway.setup.xml.tmplTemplate Gateway setup file.
    templates/start_gateway2.tmpl Template start script file.
    templates/gateway.setup.withdefaults.xml.tmpl 
    resources

    The resources files for this version.

    resources/databases
    resources/diagnostics
    resources/expressreports
    resources/hooks
    resources/nanomsg_stats
    resources/standardisedformats
    resources/xslt
    resources/timezone
    LICENCE 
    NOTICES 
    LICENCE_README.txt 
    compatSolaris Intel x86 and Linux gateway packages only. This folder contains some required libraries.

How to create a start script for Gateway

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

    setenv LD_LIBRARY_PATH <SetupDirectory>/compat
  2. Create the a setup directory.
  3. Copy gateway.setup.xml.tmpl to this setup directory.
  4. Rename gateway.setup.xml.tmpl to gateway.setup.xml.
  5. Rename start_gateway2.tmpl to start_gateway2.
  6. Edit start_gateway2 with the following:

    ### Run the gateway in the foreground
    #./gateway2.linux
    
    ### Run the gateway in the background with logging
    setenv LOG_FILENAME <LogDirectory>/gateway.log
    ./gateway2.linux -setup <SetupDirectory>/gateway.setup.xml -port <Port> &

    For the script above, note the following:

    • The Gateway process is configured to run in the background.
    • The log file is set via the LOG_FILENAME environment variable. This can alternatively this be set using the command line or in the setup file.
    • The setup file is set using the -setup command line option.
    • The listen port is set using the -port command line option. You can also use operatingEnvironment > listenPorts.
    • See 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 ActiveConsole 2 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.

Appendix

Required libraries

The Linux version of the Gateway 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.

CentOS / Redhat(64-bit)

Library Name Package Name
libutil.so.1 glibc-2.5-34.i686
libnsl.so.1 glibc-2.5-34.i686
libpthread.so.0 glibc-2.5-34.i686
libdl.so.2 libdl.so.2
libcrypt.so.1 glibc-2.5-34.i686
libz.so.1 zlib-1.2.3-3.i386
libresolv.so.2 glibc-2.5-34.i686
libstdc++.so.5 compat-libstdc++-33-3.2.3-61.i386
libm.so.6 glibc-2.5-34.i686
libgcc_s.so.1 libgcc-4.1.2-44.el5.i386
libc.so.6 glibc-2.5-34.i686
ld-linux.so.2 glibc-2.5-34.i686

Suse (64-bit)

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

Command line options

You can start the Gateway using the command line. The following command line options are available:

Option

Use
-help [topic]

Displays help about the topic if specified, or this help message. Topic can be any of the parameters shown below.

-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.

-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.

-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.

-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.

-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 Gateway needs 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.

-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.

-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>.

-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.

-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.

-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.

-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.
-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 that the Licence Daemon is listens on. The 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.

-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.

-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.

-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(*).

-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.

-ase256-encrypt

-key-file

-en

-pw

These options relate to storing passwords in the Gateway setup. They are explained in Secure Passwords.

-ssl-certificate

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

-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.

-ssl-certificate-chain

Specifies the file that contains the trusted certificate authority.

-minTLSversion

Specifies the minimum TLS version. The accepted values are:

  • 1
  • 1.0
  • 1.1
  • 1.2

For more details, see Secure Communications.