<%NUMBERING1%>.<%NUMBERING2%>.<%NUMBERING3%> PRTG Manual: Custom Sensors

Custom sensors can perform a number of monitoring tasks that extend the standard sensor set. Apart from parameterized versions of Simple Network Management Protocol (SNMP), Packet Sniffer, and NetFlow sensors, you can create your own sensors using Windows Management Instrumentation Query Language (WQL) or Python, by compiling an .exe file, using any Windows software development tool, and you can request any Representational State Transfer (REST) application programming interface (API) that returns JavaScript Object Notation (JSON) or Extensible Markup Language (XML) and map the results to channels.

The following documentation describes the custom EXE/Script, Python Script, and SSH Script sensors. The defined XML and JSON formats for the advanced sensors are also used for advanced HTTP data sensors and the REST Custom sensor.

For more information about custom sensors based on SNMP, Windows Management Instrumentation (WMI), Packet Sniffing, and xFlow (NetFlow, jFlow, sFlow, IPFIX), see the respective custom sensors.

For each sensor interval, PRTG can run an external process. The process can be a Windows .exe file, or a .dll, .bat, .cmd, .vbs, or PowerShell file, as well as a Python or Secure Shell (SSH) script.

In this section:

• Standard and Advanced EXE/Script Sensor
• Standard and Advanced SSH Script Sensor
• Interface Definition for EXE/BAT/CMD/VBS/PowerShell/SSH Sensors
• Return Values for EXE/BAT/CMD/VBS/PowerShell/SSH Sensors
• Standard EXE/Script Sensor
• Standard SSH Script Sensor
• Advanced Script, HTTP Data, and REST Custom Sensors
• Advanced Script, HTTP Data, and REST Custom Sensors: Elements
• Interface Definition for DLL Sensors
• Command-line Parameters
• Escape Special Characters and Whitespaces in Parameters
• Environment Values
• PRTG Script World

Standard and Advanced EXE/Script Sensor

You must create the sensor as a file and store it in a specific subfolder on the probe system. In a cluster, you must store it on each cluster node.

Place executables (.exe, .dll), batch files (.cmd, .bat), VBS scripts (.vbs), or PowerShell scripts (.ps1) into a subfolder of the PRTG program directory. For the standard EXE/Script sensor, this is the following subfolder of the PRTG program directory:

Custom Sensors\EXE

If your executable or script returns XML or JSON, you use it with the EXE/Script Advanced sensor. In this case, store your file in the following subfolder of the PRTG program directory:

Custom Sensors\EXEXML

You find a sample set of demo sensors in these subfolders, too. As soon as a file is placed into the subfolders mentioned above, you can create your own custom EXE sensor and select the new file from the list of files.

The probe then executes the file on the probe system using the account configured for the PRTG probe service ("system" is the default). The local probe runs the file on the local PRTG core server system. For remote probes, the file actually runs on the remote probe system.

If your custom sensor code relies on other files (for example, .dll files, .NET framework, Windows PowerShell) you must manually copy or install these files on the probe system.

EXE sensors fail if they attempt to open any graphical user interface windows using the Win32 APIs. This is not allowed for processes that are started by a system service.

Standard and Advanced SSH Script Sensor

You must create the sensor as an SSH script and place it in a specific directory on the target system running your Linux/Unix installation where the script is executed.

Place your SSH script files for the standard SSH Script sensor in the following directory of the target system:

/var/prtg/scripts

If your SSH script returns XML or JSON, you use it with the SSH Script Advanced sensor. In this case, store your file in the following directory of the target system:

/var/prtg/scriptsxml

As soon as a file is placed into the respective directory, you can create your own SSH script sensor and select the new script file from the list of scripts.

With each scanning interval, PRTG executes the script on the target system and receives the result as a sensor result.

Interface Definition for EXE/BAT/CMD/VBS/PowerShell/SSH Sensors

Every time the sensor is run, the selected file is executed. The string entered in the Parameters field of the sensor's settings is used as command line (you can use placeholders, see Command-line Parameters). The executable file must send the results to the Standard OUT. For the format of returned data, see below.

If the executable file does not return control to the PRTG process, it is killed as soon as the timeout value set for this sensor is reached.

You can test the .exe file that you want to use for the sensor via the command line (cmd.exe). To do so, start the .exe file and pipe the results into a file.

Remarks

• For PowerShell scripts, make sure that they are executed by either signing the files or changing the security policy for Powershell.exe accordingly.
• In SSH scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings in the Parameters field of the sensor's settings.
• The API interface for custom EXE sensors is compatible with the custom EXE sensors provided by PRTG.

Return Values for EXE/BAT/CMD/VBS/PowerShell/SSH Sensors

The expected return values are different, depending on the type of EXE/Script sensor used. The standard sensor needs a simple value:message pair. The EXE/Script Advanced sensor processes an XML or JSON return value. When using the standard SSH Script sensor, it expects returncode:value:message as result. See details below.

Standard EXE/Script Sensor

The returned data for standard EXE/Script sensors must be in the following format:

value:message

Value has to be a 64-bit integer or float. It is used as the resulting value for this sensor (for example, bytes, milliseconds) and stored in the database. The message can be any string (maximum length: 2000 characters).

The exit code of the executable file has to be one of the following values:

Standard SSH Script Sensor

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

returncode:value:message

Value has to be a 64-bit integer or float. It is used as the resulting value for this sensor (for example, bytes, milliseconds) and stored in the database. The message can be any string (maximum length: 2000 characters).

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

Advanced Script, HTTP Data, and REST Custom Sensors

The returned data for the EXE/Script Advanced, Python Script Advanced, SSH Script Advanced, HTTP Push Data Advanced, HTTP Data Advanced, and HTTP IoT Push Data Advanced sensors must be in XML or JSON format, the REST configuration file for the REST Custom sensor must be available as JSON template. Most parameters have a default value and are not required.

The following minimum examples leave most parameters to their default values and return two static channel values.

Advanced Script, HTTP Data, and REST Custom Sensors: Elements

You can optionally define the encoding of your .xml file at the beginning of the document. For example, to define UTF-8, you would use:

<?xml version="1.0" encoding="UTF-8" ?>

You can use the following elements in the section between <result> and </result>. In each section, you can return one channel. You can define a maximum of 50 channels.

If you exceed this limit, PRTG tries to display all channels. However, be aware that this is an unsupported procedure and you experience limited usability and performance.

For XML output, the tag names are not case-sensitive. For example, you can use both "VALUE" and "value". For JSON output, the tag names are case-sensitive but you can also use lowercase. For example, you can use both "CustomUnit" and "customunit".

You can use the following elements in the section between <prtg> and </prtg>, outside the <result> section.

For XML output, the tag names are not case-sensitive. For example, you can use both "TEXT" and "text". For JSON output, the tag names are case-sensitive but you can also use lowercase. For example, you can use both "Text" and "text".

Each run (sensor scan) might return either any number of channels (<result>...</result>) or one error response. It is not possible to mix result and error entries.

You can either write the XML output to standard OUT line by line, or give back the entire expression in one line without breaks.

Interface Definition for DLL Sensors

Every time the sensor is to be checked, a function in the selected .dll file is called. The .dll file must export one function:

function perform(para,msg:pchar):integer; stdcall;

para and msg are zero-terminated strings. The allocated buffer for msg is 255 bytes, the .dll file must make sure that fewer bytes are returned. Msg must be in the following format:

value:message

Value has to be an 32-bit integer and is used as the resulting value for this sensor (for example, bytes, milliseconds, etc.), message can be any string and is stored in the database.

The integer return value of the perform function has to conform to the same rules as the EXE exit code mentioned above.

If the function call in the .dll file does not return control, it could block the whole PRTG system. Make sure to handle your own timeouts and build in a reliable error management. For this reason, EXE sensors are recommended.

Command-line Parameters

In the parameter field, you can use the following placeholders:

You need to escape special characters and whitespaces in your parameters and surround them with double quotes. See section Escape Special Characters and Whitespaces in Parameters for details.

In SSH scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings.

See section Inheritance of Settings for more information on inherited settings.

Escape Special Characters and Whitespaces in Parameters

You need to escape special characters in parameters that you pass to an executable or script and surround them with quotation marks to make sure that the characters are correctly interpreted. PowerShell scripts in particular require adequate escaping so that the parameters are passed in a valid PowerShell syntax. PRTG automatically does most of the escaping for you.

Follow these rules to escape special characters and whitespaces in the parameters fields:

• Use quotes for parameters that contain whitespaces.

-name "Mr John Q Public"
-name 'Mr John Q Public'

• Use double quotes for parameters that contain single quotes.

-name "Mr 'John Q' Public"

• Use single quotes for parameters that contain double quotes.

-name 'Mr "John Q" Public'

• Use a backslash (\) to escape and pass a literal double quote.

-name pub\"lic

• Use double quotes for parameters that contain double and single quotes and escape double quotes.

-name "pu'b\"lic"

In SSH scripts, you can use alphanumeric characters and the special characters ".", "_", "-", "=", and "/" outside of quoted strings.

We recommend that you do not pass passwords in parameters. Use PRTG placeholders instead. See section Custom Sensors for details.

Environment Values

If the Set placeholders as environment values option is enabled in the sensor's settings, the values of all placeholders available for command-line parameters are additionally provided as "Environment Variables" during run time, so you can use them in your executable or script file. The variables' names are the same as for placeholders mentioned above, with the prefix prtg_ and without the % character. For example, refer to the sensor's own name by using the variable prtg_name.

Additionally, the following variables are available:

PRTG Script World

You can find scripts for custom sensors that were written by dedicated PRTG customers in the PRTG Script World.

More

You can find sample projects for these custom sensors and more information about custom scripts here:

• \Custom Sensors\EXE subfolder of the PRTG program directory.

 

KNOWLEDGE BASE

Custom sensors

• https://kb.paessler.com/en/tags/custom-script-exe

Guide for PowerShell-based Custom sensors

• https://kb.paessler.com/en/topic/71356

Application Programming Interface (API) Definition—Topics

• HTTP API
• Live Data

• Single Object Property
• Single Object Status
• Multiple Object Property or Status
• System Information

• Live Graphs
• Historic Data
• Object Manipulation
• Custom Sensors
• Custom Notifications
• Mini Probe API