Toolkit Plug-In User Guide

Overview

This guide discusses the installation, set-up, and configuration of the Toolkit sampler. It is intended to provide different sample scripts of user scenarios and basic information to use this plug-in.

The Toolkit plug-in integrates output from custom commands and scripts into Geneos. This plug-in executes these commands or scripts on a periodic basis and converts their output into a dataview.

These custom commands can execute standard output application written in C/C++, Perl, TCL, Python, and scripts, such as VB, batch, and shell script.

For more information on plug-in configuration, see Toolkit Plug-In Technical Reference.

Prerequisites

The following requirements must be met prior to the configuration and setup of the Toolkit plug-in:

Netprobe must have the appropriate access to execute the commands and scripts.
Results of the commands and scripts must be to standard output (stdout).
Results must be in the custom comma separated values (CSV) format.

User requirements

To use this plug-in, you must meet the following requirements:

Basic understanding of programming languages, such as C/C++, Perl, TCL, and shell script that can execute the custom commands.
Use of batch scripting or PowerShell scripting in Windows, and other third-party scripting languages.

Introduction

A typical view constructed using the Toolkit plug-in has several headline variables followed by a detailed table. The Toolkit plug-in uses the comma as a delimiter for cells.

Common delimiters used for Toolkit configuration are commas (,), semicolon (;), quotes (“,’), or slashes (/, \). This is a sample script used in Gateway Setup Editor:

$ ./toolkit_test03.bash
id,name,status,Value
<!>AlertDetails,this is red alert
001,agila,up,97
002,lawin,down,85

The $ ./toolkit_test03.bash is used in the Sampler script field:

Given the sample script used in the example, the generic format to display in the dataview is:

column1,column2,column3,column4
<!>headlineName,headlineValue
row1,row1col2,row1col3,row1col4
row2,row2col2,row2col3,row2col4

The dataview of this sampler configuration displays in Active Console:

In reference to the sample dataview above, there are two types of headline cells:

Variable	Description
execDuration	A headline variable that shows the script execution time. It is displayed by default, but you can set the `showExecutionDuration` to false to hide it.
<user_defined>	Specified by either the result of the script (using the <!> tag) or by a compute engine cell.

Warning: If the script fails by either returning no output or failing to run within the timeout period for five successive samples, then the Netprobe disables sampling for that instance of the toolkit. To re-enable the sampling, you can force a manual sample (using the Sample Now button), restart the plug-in through reconfiguration, or restart the Netprobe.

Commas within view cells

Since the comma is the cell delimiter, it is not possible for the toolkit's scripts to have these within the cell’s content.

To include an actual comma within the cell’s content, precede the comma with a backslash “\,”.

Sample command script:

queue3, 7\,331, 45\,000,0.16, online

Expected output:

queue3 | 7,331 | 45,000 | 0.16 | online

Environment variables

In addition to Geneos variables, user variables can be set in the Environment Variables and Secure Environment sections for the plug-in to utilise.

Go to Gateway Setup Editor > Sampler > Toolkit plug-in.
Click the Advanced tab.

Secure Environment Variables are encrypted using the AES 256 encryption. This is useful for storing passwords or any sensitive data.

To learn how to use these variables, see the Appendix section.

Display CSV file in the dataview

Toolkit plug-in allows you to display the data in the Active Console dataview by using a command to display the file to a standard output.

To display the content of a .csv file:

In the Gateway Setup Editor, open the Toolkit sampler.
Enter the command script in the Sampler script following the directory path of the file. For example:

/bin/cat /home/documents/toolkit.csv

Click Save current document to apply changes.

On Unix, /bin/cat is the common program, while on Windows, use cmd.exe command interpreter to execute the type built-in. For example:

C:\Windows\system32\cmd.exe /c type C:\Users\Administrator\Documents\toolkit.csv

For more information, see samplerScript in Toolkit Plug-In Technical Reference.

Install and set up

Ensure that you have read and can follow the system requirements prior to installation and set-up of this plug-in.

This provides instructions on how to set up a basic configuration using a Toolkit plug-in:

To select the Toolkit plug-in, go to Gateway > Probes > Managed entity > Samplers.
In the Samplers section, select Toolkit on the Plugin menu.
In the Sampler script field, enter the command to execute the script.

Note: The Sampler script specifies the name of the command that the plug-in runs on a periodic basis. If there are any spaces in your path, you must enclose it in double quotation marks. Otherwise, the sampler fails to execute the script.

In this example, the command and script is entered in the Sampler script field:

./toolkit_test.bash

Click Save current document to save your changes.
Go to the Toolkit dataview in the Active Console to check if your configuration to monitor the path is working.

These Toolkit sampler configurations below show the different user scenarios that you can use to execute commands.

Use command argument

To execute command using Command argument, follow these instructions:

In the Sampler script field, enter the command to execute the script.

In this example, the command and script entered in the Sampler script field is:

/bin/cat toolkit_command_args.txt

Click Save current document to save your changes.
Go to the Toolkit dataview in Active Console to check if your configuration to monitor the path is working.

Use PowerShell

To execute command using Powershell script, follow these instructions:

In the Sampler script field, enter the command to execute the script.

In this example, the command and script entered in the Sampler script field is:

C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe -noprofile -executionpolicy bypass -file "C:\Users\Administrator\Downloads\Test Scripts\output-select-lines.ps1"

Click Save current document to save your changes.
Go to the Toolkit dataview in Active Console to check if your configuration to monitor the path is working.

Use Windows BAT files

To execute command using Windows bat script, follow these instruction:

In the Sampler script field, enter the command to execute the script.

In this example, the command and script entered in the Sampler script field is:

"C:\Users\Administrator\Downloads\Test Scripts\toolkit_pebl_col273.bat"

Click Save current document to save your changes.
Go to the Toolkit dataview in Active Console to check if your configuration to monitor the path is working.

Appendices

Use the secured environment variables

This procedure has two steps:

Generate the key file and encrypted value.
Decrypt the encrypted value before the Toolkit executes the script.

Generate the encrypted password

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

Generate and use a key file as follows:

openssl enc -aes-256-cbc -k "Now is thewinter of our discontent" -P -md sha1 >key-file

The key file is required for the encryption and decryption of AES 256 passwords.

Generate the encrypted value.

./active/gateway2.linux -aes256-encrypt 12345 -key-file key-file -skip-cache

The 12345 is a user-specified password which is then encrypted. The Gateway produces the output in hexadecimal:

Encoded text: +encs+69B1E12815FA83702F0016B0E7FBD33B

A Gateway binary, such as gateway2.linux_64 is needed to create the AES 256 password. The -skip-cache is needed only the first time you wish to change the key file.

In the Toolkit sampler, create a secured environment variable.
Add the encrypted password to the secured environment variable. You can convert the sampler view to XML.

Decrypt the encrypted value

Use the sample shell script below that decodes the hexadecimal or encrypted value:

./decode.sh +encs+69B1E12815FA83702F0016B0E7FBD33B

decode.sh:

#!/bin/bash
hex=${1#*+encs+}
salt=$(grep salt key-file)
key=$(grep key key-file)
iv=$(grep iv key-file)
echo ${hex}| xxd -r -p | base64 | openssl enc -d -aes-256-cbc -S ${salt#*=} -K ${key#*=} -iv ${iv#*=} -a

To convert an environment variable, replace the '1' in the second line with the name of the environment variable. All encrypted variables start with +encs+, so this removes the prefix prior to decoding.

Note: xxd is part of the vim-common package which you may have to install separately.