Back to Geneos FAQ

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

Users can configure gateway actions which provide alert details as environment variables for sending email alerts. Starting from Gateway version GA5.14 (AA-6415), Gateway REST service supports a new endpoint to request a snapshot of a dataview.

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 Copied

Linux Server Copied

• The Linux server should be capable of sending 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 Copied

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

Installation Copied

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. Users 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 messages 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 according to their company policies and environment. Users who may not have an existing password management tool may consider creating a key-file with OpenSSL commands. We have provided a link to the Gateway Secure Passwords documentation below with example commands.

Usage Copied

Action to Email Copied

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 the 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:

Command to Email Copied

1. Users may make use of the scripts in Active Console right-click commands as well.

2. Please update the geneos_command_email.sh script with environment variables similar to gateway actions above.

3. The command should include XPath parameters to populate _VARIABLEPATH variable similar to gateway actions. We have attached a sample XML format configuration in this article.

Email Output Copied

Common Errors Copied

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

• urlopen error [Errno 97] Address family not supported by protocol We have received issue reports from users with certain Python libraries. You may want to check if localhost is resolved to IPv6 addresses, or IPv6 entries in /etc/hosts.

Further Reading Copied

• 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

Related downloads Copied

• geneos_command_email.xml.txt
• geneos_action2html-1.3.zip