This article applies as of PRTG 22

I want to use the SSH Script sensor. Is there an example? What is the return format?

SSH Script sensor

The expected return format for the scripts used with the SSH Script sensor is documented in the PRTG Manual: Application Programming Interface (API) Definition.

Snippet from the PRTG API documentation

The returned data for standard SSH Script sensors must be in the following format: returncode:value:message

Value must be a 64-bit integer or float and will be used as the resulting value for this sensor (for example bytes, milliseconds, etc.), message can be any string and will be stored in the database.

The SSH script's "returncode" has to be one of the following values:

Example shell script

This example script will run on the target host and check if a service on a specific port is running. Change it to your liking.

#!/bin/bash

port="80"
service="WEB"

NETSTAT=`which netstat`
ID=`which id`

die(){
	exit 999
}

is_root(){
	local id=$($ID -u)
	if [ $id -ne 0 ] 
	then
		echo "4:500:You have to be root to run $0."    # returncode 4 = put sensor in DOWN status
		die
	fi
}

preparation(){
	if [ ! -x $NETSTAT ]
	then 
		echo "2:500:netstat not found."
		die
	fi
	if [ ! -x $ID ]
	then
		echo "2:500:id not found."    # returncode = 2 = put sensor in DOWN status
		die
	fi
	is_root
}

check_service(){
	serviceIsRunning=false
	openPorts=$($NETSTAT -tulpn | grep -vE '^Active|Proto' | grep 'LISTEN' | awk '{ print $4}' | awk -F: '{print $NF}' | sed '/^$/d' | sort -u)
	for openPort in $openPorts
	do
		if [ "$port" == "$openPort" ]
		then
			serviceIsRunning=true
			echo "0:200:$service is running."    # returncode 0 = put sensor in OK status
			break
		fi
	done
	if [ $serviceIsRunning == false ]
	then
		echo "1:404:$service is not running."    # returncode 1 = put sensor in WARNING status
	fi
}

main(){
	preparation
	check_service
}

main

A simple script for advanced SSH script bandwidth monitoring for Eth0. It is possible to add additional channels for other interfaces. The measure is based on ifconfig output and counter sensor mode:

#!/bin/bash
#
echo -n "<prtg>
  <result>
    <channel>Eth0 RX</channel>
    <unit>BytesBandwidth</unit>
    <VolumeSize>KiloBit</VolumeSize>
    <mode>Difference</mode>
    <value>"
ifconfig eth0 | gawk '
/RX bytes/ {\
  sub (/.*RX bytes:/,"");\
  sub(/ \(.*:/,"</value>\n  </result>\n  <result>\n    <channel>Eth0 TX</channel>\n    <unit>BytesBandwidth</unit>\n    <VolumeSize>KiloBit</VolumeSize>\n    <mode>Difference</mode>\n    <value>");\
  sub(/ \(.*/,"</value>\n  </result>\n</prtg>");print $0}
' 

The output looks like this:

<prtg> 
<result> 
<channel>Eth0 RX</channel> 
<unit>BytesBandwidth</unit> 
<VolumeSize>KiloBit</VolumeSize> 
<mode>Difference</mode> 

<value>6174822801</value> 
</result> 
<result> 
<channel>Eth0 TX</channel> 
<unit>BytesBandwidth</unit> 
<VolumeSize>KiloBit</VolumeSize> 
<mode>Difference</mode> 
<value>144638053073</value> 
</result> 
</prtg> 

ifconfig in newer versions of Linux produces a different output. This is a new version of the SSH script for bandwidth monitoring:

#!/bin/bash
#
ifconfig eth0 | gawk '
/[RT]X packets/ {if (!tx) print "<prtg>";
print "  <result>\
\n    <channel>eth " $1 "</channel>\
\n    <unit>BytesBandwidth</unit>\
\n    <VolumeSize>KiloBit</VolumeSize>\
\n    <mode>Difference</mode>\
\n    <value>" $5 "</value>\
\n  </result>";
if (tx++) print "</prtg>"}'

These few lines cover a lot of simple service check needs.

Here's a super simple service check script used on Ubuntu systems. When you set it up in PRTG, just put the service name you want to check in the parameter box. That becomes $1 in the script. $? is the status of the service as reported by the service command. This is all assembled in the echo to be formatted to make PRTG show pretty and informative results.

#!/bin/sh

service $1 status 2>&1 1>/dev/null

if [ $? -ne 0 ]; then
  echo "1:$?:$1 down"
else
  echo "0:$?:OK"
fi