Geneos - how to receive email updates with screenshots of my dataviews? (Gateway version GA5.14 and above)

This article includes example scripts for users to make use of these functions. The scripts are provided under the terms of the MIT License.

Note: Geneos users who engaged implementation services from ITRS more recently (since mid-2023) may have the "cordial" package installed with similar tools. Please check with the responsible project team members or ITRS Professional Services.

Pre-requisites

Linux Server

• The Linux server should be capable to send outgoing email. Please check with the Linux admin if email command tools are available. Also, check with the network or security teams on firewall rules and policies as appropriate.
• The Gateway REST command creates output in JSON format. The example script has been written in Python to process this. The server requires Python 3 with JSON libraries installed.

Gateway

• Gateway version GA5.14 and above
• Gateway REST Command is enabled
• If Gateway Authentication is enabled, dedicated username and password should be ready for REST Commands

Installation

1. Download the scripts attached at the bottom of this article. Place them at the Geneos gateway server. You may need Linux chmod command to give execute permission to the scripts.

2. We have created a shell script to test the gateway connection and REST command output. Open the file snapshot_test.sh with a text editor, and update the following variables:

• _GATEWAY (Gateway Name)
• _VARIABLEPATH (From Active Console, pick any headline or table cells and right-click to select the Copy From ... Path menu.)
• GatePort (Gateway Port)

Update the username and password variables that can connect the gateway to run REST Commands.

• GATEWAY_REST_USERNAME
• GATEWAY_REST_PASSWORD
• GATEWAY_REST_PROTOCOL (http / https)
• GATEWAY_REST_VERIFY_SSL_CERTIFICATE (true / false)

3. Execute the ./snapshot_test.sh script. If the provided user can connect the gateway successfully, it should return the whole dataview in HTML format.

4. There is a shell script for use in gateway actions. Open the file geneos_action_email.sh with a text editor. Please make the following updates:

• Gateway REST username, password, and protocol details as above.
• Installation Path
• Command line to send HTML file as email alert. User should consult their Linux server admin as appropriate. There are also resources on the internet with examples using sendmail, mailx, etc. commands. The command should include the below header so that email clients can display HTML message properly.

  Content-Type: text/html

  e.g.

  mailx -a "Content-Type: text/html" -r sender@example.com -s "Geneos Alert" recipient@example.com < ${TEMP_HTML_FILE}

5. As general security practice, users should avoid putting plain text passwords in scripts. Please refer to the Gateway Secure Passwords documentation with examples creating a key-file and other ideas. Users should adapt the script according to their environment and company policies.

Usage

1. Users can now define a gateway action to utilize the scripts for sending email alerts.

2. If the gateway startup script does not have GatePort variable defined, user can create a Macro at the Operating Environment. This should be pointing to the gateway port.

3. The Rule Block can be configured like this:

Email Output

Common Errors

• HTTP Error 404: Not Found
  Please verify gateway version is GA5.14 and above.
  Please check that the REST Service is enabled properly (Gateway Setup Editor => Commands => Advanced tab)
• HTTP Error 403: Forbidden
  Please verify the username and password is authorized to run Gateway REST commands.
• HTTP Error 400: Bad Request
  Please verify gateway port is configured for secure mode or not (http / https).
• urlopen error EOF occurred in violation of protocol
  Please verify gateway port is configured for secure mode or not (http / https).
• urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
  The gateway may be configured with a self-signed certificate which is not imported to the local server. You may try setting the verify SSL certificate variable to false.

Further Reading

• Gateway REST Service - please look for the Fetch a dataview section

• Gateway Authentication
• Gateway Secure Passwords
• Geneos - How to use REST API to get a snapshot of a dataview