Documentation forServer & Application Monitor

Linux/Unix Script Monitor

This SAM component monitor uses SSH to upload a script to a Linux/Unix server, runs the script on the server, and then processes the return value and text output. To create this monitor, see Use the Linux/Unix Script Monitor.

To use scripts with Nagios formats, SolarWinds recommends using the Nagios Script monitor.

For more details, see:

The SAM forum in THWACK also provides content about Linux/Unix scripting.

For sample scripts with Linux/Unix Script Monitors, see this folder on the Orion server: C:\Program Files (x86)\SolarWinds\Orion\APM\SampleScriptMonitors\LinuxScripts

Statistic

The statistic for this component monitor is the Statistic value returned by the script.

A maximum of 10 output pairs can be returned. If you exceed the maximum allowed, remove the excess output pairs or they will simply be ignored.

Prerequisites for Orion agent for Linux

Include credentials that can run scripts on the monitored Linux-based computer. Agentless monitoring does not require these credentials.

Verify your installation of python and python-xml. Depending on your Linux distribution, you may have need to install these libraries. You can verify your Python installed libraries with the following command:

python -c "import sys; from xml.dom.minidom import parseString; print sys.version"

The following command typically updates and installs the required Python libraries: apt-get install python

Depending on your Linux distribution, you may need to install and configure specific applications and services to use the Linux/Unix Script monitor. For example, to use the Linux/Unix Script Monitor with Apache services (as with the Apache template), you need to configure Apache access. See Configure Linux/Unix systems for monitoring by the Orion agent in SAM.

Troubleshooting high CPU usage

This component monitor uses SSH for connecting to target machines. Due to supported key exchange algorithms, the JobWorker process used by SAM may encounter high CPU usage. If the issue is due to the algorithm, you can modify the order of supported algorithms. If you have concerns making these changes, contact Support.

  1. Open the following files in a text editor:
    c:\Program Files (x86)\SolarWinds\Orion\APM\SolarWinds.APM.Probes.dll.config.
  2. Locate this line: <LinuxScriptSettings PromptWait="2" ColumnCount="200" TemporaryScriptFileNamePrefix="APM_" />
  3. Modify the order of algorithms, such as: <LinuxScriptSettings PromptWait="2" ColumnCount="200" TemporaryScriptFileNamePrefix="APM_" KeyExchangeList="diffie-hellman-group-exchange-sha256,diffie-hellman-group-exchange-sha1,diffie-hellman-group1-sha1,diffie-hellman-group14-sha1" />
  4. Save your changes.

Field Descriptions

Description

Provide A default description of the monitor. You can override the default description by adding to or replacing the text, which is automatically saved. The variable to access this field is ${UserDescription}.

Changing the default description to specify what will be monitored can be helpful when receiving alerts and notifications later.

Enable Component

Determines if the component is enabled. Disabling the component leaves it in the application in a deactivated state not influencing either SolarWinds SAM application availability or status.

Authentication Type

Choose either User name and Password or User name and Private Key. The second option allows you to use certificates for authentication.

Credential for Monitoring

Select a credential from the list provided or use the <Inherit credential from node> option. If the credential you need is not in the credentials list, add it in the SAM Credentials Library accessed by clicking Settings > All Settings > SAM Settings.

When providing credentials, make sure that the account:

  • Can access the Linux or Unix server over SSH.
  • Has sufficient rights to run scripts.
  • Exists on the system receiving the executed script.

If you do not enter credentials or use the Inherit option, the monitor uses using Orion agent credentials (SWIAgent) to execute the script and those may not have the necessary elevated permissions. For details, see Credentials and privileges used on Linux/Unix-based computers in the Orion Platform Administrator Guide.

Port Number

Specify the port number used for the SSH connection. The default value is 22.

Script Working Directory

Specify the working directory of the script process.

Count Statistic as Difference

Set the statistic to be the difference in query values between polling cycles.

Command Line

Specify the shell command run after the SSH connection is established. The default command line value perl ${SCRIPT} arg1 arg2 attempts to run in a Perl interpreter the script defined in the Script Body field using the parameters arg1 arg2.

The length of the Command Line field is limited to 266 characters for Solaris systems, minus the length of the ${SCRIPT} variable after being resolved to a file name such as the following: APM_937467589.pl. Since the length of the file name will typically be around 16 characters, this means that the actual user Command Line input cannot be longer than 266 – 16, or about 250 characters (not including the length of the 9 characters for the “${SCRIPT}” variable itself).

If you need to pass a longer command line to the target node, you can create a shell script on the target node (for example myscript.sh) that contains the long command line, and place the call to this script in the Command Line field, for example: /opt/sw/myscript.sh

Script Body

Specify the script you want to run on the Linux or Unix server.

Status Roll-Up

Choose how you would like the monitor to report based on the output provided by the script. The default selection is “Show worst status.”

User Notes

Add notes for easy reference. To access this field, use the variable, ${UserNotes}.

Use the Linux/Unix Script Monitor

As a predefined component monitor included in SAM, you can use the Linux/Unix Script Monitor to execute a command line script that can return statistical data. When collecting information for this monitor, SAM runs the script with the credentials defined with the Credential Library.

A maximum of 10 output pairs can be monitored per script monitor. More than 10 defined pairs results in a failure of the monitor.

Adapt an existing Perl script to a Linux/Unix Script component monitor in a new template

  1. Click Settings > All Settings > SAM Settings > Create a new template, and then name the template
  2. Click Add Component Monitor, expand the Custom Component Monitors group, and then select Linux/Unix Script Monitor.
  3. Click Submit then select credentials with SSH permissions in the Credential for Monitoring field.
  4. Provide a valid working directory in the Script Working Directory field
  5. Click Edit to open the script dialog and enter your script into the Script Body field.
  6. Type the Linux command that runs the script in the Command Line field. It should be similar to the following: perl ${SCRIPT} arg1 arg2.

    {SCRIPT} is replaced by the actual file name of the script after it’s deployed to the target node. A temporary file is created in temp directory for the script.

  7. Click Get Script Output. SAM then tests the script by executing it and parse its output, then return the values.
  8. Click Save, then specify the critical and warning thresholds and click Submit.

This sample Perl script uses the Linux/Unix component monitor and returns two output pairs:

#!/usr/bin/perl
if (@ARGV[0] =~ /\bhelp\b/)
 {

	print "MemoryUsage.pl SNMPver community hostname\n";
	print "SNMPver - version of SNMP protocol\n";
	print "community - community name of SNMP protocol\n";
	print "hostname - Target host\n";
	exit 1;

}
# Get hostname and trim newline
$localhost = `hostname`;
$localhost =~ s/\s*$//g;
$hostname  = shift ||
$localhost;$community = shift || "public";
$version = shift || "v1";
$results =  "";
$MIB_TotalMemory = "UCD-SNMP-MIB::memTotalReal.0";
#$MIB_TotalMemory = "UCD-SNMP-MIB::memTotalReal.0";
$outres = "snmpget -$version -c $community $hostname $MIB_TotalMemory |";
open(OUTMEM,$outres) || die "Unable read pipe\n";
while ($line = &lt;OUTMEM&gt;) {	
	if ($line =~ /\bINTEGER\b/) {
		$indval = index($line,"="); 
		$indval=inde($line,":",$indval);
		$val = substr($line,$indval+1,length($line) - $indval);
		$val =~ s/[a-zA-Z\/\n ]//
		print "Message.1: Available memory at host \"$hostname\": $val in kB\n";
		print "Statistic.1: $val\n";
		print "Message.2: Again, the available memory at host \"$hostname\": $val in kB\n";
		print "Statistic.2: $val \n";
		exit 0;
	}
}
print "Statistic: 0\n";
exit 1;

Below is the output from this script:

Linux/Unix scripts

Linux/Unix scripts are uploaded by SSH and then run on the target node using the string from the Command Line field.

Use the following variable in the command line field:

  • ${SCRIPT} - Replaced with the script body.

Use the following variables in the script body field:

  • ${IP} - Replaced with the target node’s IP address.
  • ${USER} - Replaced with the user name from the credential.
  • ${PASSWORD} - Replaced with the password from the credential.

SAM includes sample scripts that you can use to create Linux/Unix script component monitors, as provided in this folder on the Orion server: C:\Program Files (x86)\SolarWinds\Orion\APM\SampleScriptMonitors\LinuxScripts

Scripts must report status through exit codes

Scripts must report their status by exiting with the appropriate exit code. The exit code is used to report the status of the monitor, which is seen by the user through the interface

To correctly create this component monitor, you must first return an exit code which results in an Up (0), Warning (2), or Critical (3) status. When one of these exit codes is received the appropriate dynamic evidence table structure is created and all further exit codes are handled correctly. If the component only returns Down (1) or Unknown (4) on first use, the appropriate dynamic evidence table structure is not created appropriately.

Exit Code Meaning

0

Up

1

Down

2

Warning

3

Critical

Any other value

Unknown, for example 4

For example, if you want to inform SolarWinds SAM that a script reports an Up status, exit the script using code similar to the following, where 0 reports Up: Wscript.quit(0)

Scripts with Text Output

Scripts report additional details by sending text to the script’s standard output.

SAM supports multiple values returned by a script using the following format:.

Statistic.Name1: xMessage.Name1: abc

Statistic.Name2: yMessage.Name2: abc

Detail Type Required Meaning

Statistic

Yes

A numeric value used to determine how the monitor compares to its set thresholds. This must be an integer value. Negative numbers are supported.

Statistic.Name1: 123
Statistic.Name2: 456

Message

No

An error or information message to be displayed in the monitor status details. Note: Multi-line messages are supported. To use this functionality, print each line using a separate command. For example:
Message.Name1: abc

Message.Name2: def

There is a limit of ten Statistic and Message pairs for the script. These can be placed anywhere in the script output. The Statistic and Message names you give must contain valid letters and/or numbers.

Sample output:

# Script comment: This shows two pairs. Ten pairs are possible.
Statistic.CPU: 31.08
Message.CPU: svchost.exe cpu usage
			
Statistic.RAM: 1234.56
Message.RAM: svchost.exe ram usage

Nagios scripting

To use this component monitor with Nagios, as polled by Orion agent for Linux, enter a script as follows. For the Script Argument, use python $(SCRIPT).

from random import randint
STAT_PAIRS_COUNT = 10
 
for stat_id in range(STAT_PAIRS_COUNT):
	print 'Statistic.random%d: %d\nMessage.random%d: %s' % (stat_id, randint(1,100), stat_id, 'random number: ' + str(randint(1,100)))

To use scripts with Nagios formats, we recommend using the Nagios Script monitor.