Gateway Installation Guide

Contains resources files for this version.

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

For more information about using an API key, SSO Agent User Guide and Application Keys.

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.

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.

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

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.

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

URL of the Gateway Hub.

Only one URL is supported.

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.

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.

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

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.

A unique identity that Kerberos can assign tickets to.

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

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

For more information, see Secure Passwords.

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

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

Default: localhost.

Specifies the port where the Licence Daemon is listening on.

Default is 7041.

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.

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.

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.

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.

URL of Obcerv.

Required when using Centralised Configuration in Obcerv.

Example: https://obcerv.example.com

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

Default value: 5 seconds

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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

Specifies the file that contains the trusted certificate authority.

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.

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.

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.

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:

Returns:

• 0 — Success.
• 1 — Warnings present.
• 2 — Errors present.
• 3 — Critical errors present.
• 4 — Fatal errors present.

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