Gateway 2 Recorder - User Guide

Introduction

The Gateway 2 recorder is a utility that is able to connect to one or more Gateway 2 instances and record the data that the gateway(s) are publishing to disk. At a later date the recordings can be played back to simulate the recorded gateway. This feature is intended to be useful for recreating Gateway conditions from a site for reproducing ActiveConsole, Web-Server or Recorder issues. It also enables us to simulate high load environments in the office. Additionally this is useful for feature demo purposes.

Binary Requirements

The recorder is supplied as a windows executable file recorder.windows.exe. It has a runtime dependency on the threading library pthreadVSE.dll, which should be in the same directory where the recorder is run from.

Use

Running recorder.windows.exe with no arguments will print out the usage parameters to the screen. Use this to determine the command line options that work with your version of recorder.

The program operates in two modes: record and playback – these are controlled by a command line option.

Record Mode

In this mode the program behaves like an ActiveConsole, in that it will connect out to one or more Gateways.

To record a single Gateway, the hostname and port of the Gateway can be specified on the command line:

recorder.windows.exe -record -host <host> -port <port> [-secure] [-partial-data] [-user <username>] [-password <password>] [-key-file <aes256-key-file>
                                

The -secure flag is supplied if the recorder is connected to a secure port.

To record multiple Gateways the hostname and port pairs need to be specified in a file, and the filename passed into the recorder on the command line:

recorder.windows.exe -record [-file <filename>] [-auth-file <filename>] [-partial-data] [-user <username>] [-password <password>] [-key-file <aes256-key-file>
                                

The format of the file is the same as if using connection files with the ActiveConsole. The file must be local as the recorder does not support retrieving connection files from a remote URL. The recorder supports the new optional parameter ConnectionSecurity as specified in the Active Console reference guide (Section Remote gateway files).

Where Gateways enforce authentication -auth-file should be used ActiveConsole connection files do not contain connection information. auth files are in the following format:

host:port:INSECURE|SECURE[:user[:password]]

User names and passwords are optional and where not supplied -user and -password specified parameters are used. If none are specified, then the connection is not authenticated.

Here is an example:

localhost:8086:INSECURE:recuser:+encs+601D42AD03CAC9CA87EF91BD8E9EA0B8
itrsops:4533:INSECURE
itrsops:4534:INSECURE
itrsops:4564:INSECURE
itrsops:2346:INSECURE
itrsops:4533:SECURE
                                

Note: Append :user:password to each entry that requires authentication.

The password can be plain text or AES-256 encrypted as above.

An additional switch, -partial-data can be enabled to run the connections in an optimised mode where only red and amber cell updates are sent through. The Gateway must be recent enough to benefit from this optimisation. The amount of data collected in this mode will be less than running in full mode.

The recorder will create a single file for each Gateway connection it is configured to run. The file will be made unique by the hostname and port of the Gateway. If you run the recorder multiple times in the same directory for the same Gateway, previous files will be overwritten.

Converting connection files to authentication files

You may have any number of connections in your connection file and converting them by hand to another format would be tedious and error prone. The Recorder can do the conversion you leaving you to specify the user names and passwords for the connections.

You can do the conversion as follows.

recorder.linux -gen-auth-file <connection-file> <authentication-file>

Securing Gateway Authentication

Passwords may be plain text or AES-256 encrypted. You can get Recorder to encrypt a password for you with:

recorder -aes256-encrypt <password>

It is recommended that you use the most secure method of storing your passwords possible within your configuration. Currently this is an AES 256 implementation.

By default the recorder uses a default key. You may wish to supply your own key to increase the security of your passwords.

Warning

When you do this any existing AES 256 encrypted passwords will no-longer be valid.

To do this you start Recorder with a -key-file <filename> parameter. This tells the Recorder to use the key within this file for all encryption / decryption of AES passwords.

An AES 256 key actually has two parts a key and an initialisation vector. You can generate this using the openssl tool on the command line.

Note: This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org).

For example.

>openssl enc -aes-256-cbc -k "Now is the winter of our discontent" -P -md sha1
salt=359D12769B1F9446
key=92358925C00DE524B4F325A7F488DF1F29646313F6D258090818E8C9B69CF4D8
iv =B8B606E4700FE4D05E24E1A682F5963D
                                    

You should see a different result each time you run this command. The -key-file parameter specifies a file that has “key=…” and “iv =…” lines. You can either copy these lines into a file or redirect the output of this command into a file. However if the output of this command changes you will need to reformat into a valid key file.

Given that you can start a Recorder with a different key you also need a way to generate passwords on the command line using this key. The –aes256-encrypt option has been extended to use a key file.

Recorder -aes256-encrypt <password> [-key-file <key-file>]

Assuming a Linux Recorder a real example command line could look like:

recorder.linux -aes256-encrypt PassW0rd -key-file shh.aes

Playback Mode

In playback mode the program behaves like a Gateway, providing a service on a configured port which multiple ActiveConsole or other Geneos client application can connect to.

The program only supports playback of a single recorded file, so if you have recorded several Gateways you will need to run up several instances of the recorder on different ports to play this back. This mirrors the process model of the Gateways.

The file and port used by the program are specified on the command line:

recorder.windows.exe -playback -file <file> -port <port> [-speed <speed>]

When a client process connects to the recorder, it will start playing back the data from the beginning. If the client resets the connection then the playback will start again at the beginning. By default the data will be played back at the same speed ot was recorded at. There is a command line option to increase or decrease the playback speed if this is required for debugging purposes, this is specified as a floating point number and the default is 1.0. E.g. specify 2.0 for 2x speed, or 0.5 half half speed.