Submit a ticketCall us

Don’t fall victim to a ransomware attack
Backups are helpful, but sometimes that’s not enough to protect your business against ransomware. At our live webcast we will discuss how to protect against ransomware attacks with SolarWinds® Patch Manager and how to leverage log data to detect ransomware. Register now for our live webcast.

Home > Success Center > Server & Application Monitor (SAM) > SAM 6.4 Administrator Guide > Manage application monitor templates and component monitors > Creating a Linux/Unix Script monitor

Creating a Linux/Unix Script monitor

doc-icon.png For the ultimate custom template guide, see  SAM Custom Template Guide.  

Updated: 3-9-2017

This 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 use scripts with Nagios formats, we recommend using the Nagios Script monitor.

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

You need to include credentials that can run scripts on the monitored Linux-based computer. Agentless monitoring does not require these credentials.

You need to 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"

See the Python site for documentation and install commands. The following command typically updates and installs the required Python libraries: apt-get install python

Depending on your Linux distribution, you may need to verify 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. For full configuration details for all services, see Linux system configurations for component monitors.

Field Descriptions

Description

This field provides a default description of the monitor. You have the ability to override the default description by adding to or replacing the text, which is automatically saved. The variable to access this field is ${UserDescription}.

Enable Component

Determines whether 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 that can access the Linux or Unix server over SSH, and that has sufficient rights to run scripts. If the credentials you need are not already present in the credentials list, use the Quick Credentials section to add a new credential.

When providing credentials, make sure:

  • The account exists on the system receiving the executed script
  • The account has elevated permissions

If you do not enter credentials or select Inherit from node, the monitor executes the script under the agent credentials (SWIAgent). These credentials may not have the elevated permissions required for executing scripts.

Port Number

This field allows you to specify the port number used for the SSH connection. The default value for this field is 22.

Script Working Directory

This field allows you to specify the working directory of the script process.

Count Statistic as Difference

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

Command Line

This field allows you to 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

This field allows you to specify the script you want to run on the Linux or Unix server.

Status Roll-Up

This option allows you to 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

This field allows you to add notes for easy reference. You can access this field by using the variable, ${UserNotes}.

Create a Linux or Unix script monitor

Linux and Unix Script component monitors allow you 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. On the Web Console, 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/UnixScript Monitor.
  3. Click Submit then select credentials with SSH permissions in the Credential for Monitoring field.
  4. Type 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.

Here is a sample Perl script using the Linux/Unix component monitor returning multiple output pairs, in this case, two:

The code in red shows where the output pairs are defined.

#!/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 = <OUTMEM>) {	
	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:

File:Success_Center/Reusable_content_-_InfoDev/SAM/SAM-Admin-MT/0L0/0D0/sam_script_output_linux.png

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.

You can use the following variable in the command line field:

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

You can 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.

Example Scripts

There are several sample scripts installed with SolarWinds SAM you can use to create Linux/Unix script component monitors. These sample scripts are installed on your SolarWinds SAM server, in the folder: C:\Program Files\SolarWinds\Orion\APM\SampleScriptMonitors\LinuxScripts

Scripts Must Report Status Through Exit Codes

Scripts must report their status by exiting with the appropriate exit code.

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 Up status, you would 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

If you are using this component monitor with Nagios and polled by Orion agent for Linux, you need to enter a script as follows. The argument would be python $(SCRIPT) with a body of:

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.

 
Last modified
10:21, 17 Mar 2017

Tags

Classifications

Public