What is this?

This knowledgebase contains questions and answers about PRTG Network Monitor and network monitoring in general.

Learn more

PRTG Network Monitor

Intuitive to Use. Easy to manage.
More than 500,000 users rely on Paessler PRTG every day. Find out how you can reduce cost, increase QoS and ease planning, as well.

Free Download

Top Tags


View all Tags

Guide for PowerShell-based custom sensors

Votes:

3

I have a PowerShell script either from the Knowledge Base, from Support, or from somewhere on the internet. I am a bit lost, though. How do I install this and what do I need to do to get it to work properly?

console executionpolicy powershell script sensors

Created on Sep 22, 2016 7:52:27 AM by  Stephan Linke [Paessler Support]

Last change on Dec 3, 2020 2:53:43 PM by  Brandy Greger [Paessler Support]



11 Replies

Accepted Answer

Votes:

3

This article applies as of PRTG 22

Guide for PowerShell-based custom sensors

For the installation of PowerShell scripts in PRTG, follow these steps:

1. Configure the execution policy of the PRTG core server

The execution policy configured on a host specifies which scripts can be executed on the Windows host. There are several available settings for this:

SettingDescription
RestrictedNo scripts can directly be executed, only within an interactive session.
AllSignedOnly scripts from a trusted author can be executed.
RemoteSignedDownloaded scripts have to be signed prior to execution.
UnrestrictedThere are no restrictions, all codes will be executed.

By default, the execution policy is set to Restricted. It will hinder PRTG from executing scripts, therefore you cannot use them.

So first, you need to set the execution policy. Because the scripts are always executed by the PRTG probe service (the probe is a 32-bit application), we need to use the 32-bit PowerShell:

  1. Open Windows PowerShell (x86), respectively Windows PowerShell (32-bit) as Administrator.
  2. Set the ExecutionPolicy to RemoteSigned with the following command:
    Set-ExecutionPolicy RemoteSigned

Remember that when the device is located on a remote probe, you need to take the steps on the remote probe system, not on the PRTG core server system.

Note: You need to do this only once.

2. Install the PowerShell script

Next, you will have to check the output of the script. There are only two options:

One lineEXE/Script<PRTG Application Directory>\Custom Sensors\EXE\
XMLEXE/Script (Advanced)<PRTG Application Directory>\Custom Sensors\EXEXML\

If you already know the output type, simply copy the script to the corresponding directory.
Make sure that it has .ps1 as extension. However, if you are unsure what kind of script you have, you have two options:

  1. Open the script and search for something like Write-Output or Out-Host
  2. If the output looks like XML, copy the script to the EXEXML folder.
    Otherwise, copy it to the EXE folder.

3. Test the script

The script is now installed. The question is how to correctly use it. If the script is documented properly (either via PowerShell or text documentation), this should be no problem. You can show the PowerShell help for a script as follows:

Get-Help <path-to-the-script> -detailed

It will show you a description of the script and which parameters are supported including their description. If the script entirely lacks documentation, simply open the script with a text editor and search for param. The parameters are listed there. You can then call the script as follows:
-parameter1 <testvalue> -parameter2 <testvalue2> You can omit the parameters if you enter them in the correct order. If the script works fine, you can proceed with creating the sensor in PRTG.

4. Create the sensor in PRTG

Add a new sensor. Select either the EXE/Script sensor or the EXE/Script Advanced sensor.

ParameterDescription
EXE/ScriptSelect the script you have just installed.
ParametersEnter the parameters. Remember that you can use placeholders here.
Security ContextChoose if you want PRTG to run the script using the user account of the PRTG probe service or the account configured in the device.
Mutex NameIf you have many sensors that run concurrently, you can configure different mutex names so that they do not hinder each other.

First aid

ProblemResponse not well formed: (File C:\Program Files (x86)\PRTG Network Monitor\custom sensors\EXE\test.ps1 cannot be loaded because the execution of scripts is disabled on this system.
Solution1The execution policy is not correctly configured on the host. Go through Step 1 of this article to resolve this.
Solution2Double-check that the downloaded script file is not Blocked. Right-click the script file. On the General tab, you will see: This File came from another computed and might be blocked to help protect this computer. Click Unblock.
ProblemThe sensor shows the message UnauthorizedAccess.
SolutionThis is probably because of the user account that is configured in the PRTG probe service or device, depending on what you selected as security context. Make sure that the user has all necessary permissions to properly execute the sensor.
ProblemThe term '<insert-cmdlet-name-here>' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
SolutionThis indicates that either a command or function used by the script is not properly declared within the script or that it uses a cmdlet that is not available on the PRTG core server. Most likely, the latter is the case. Make sure that you are running the latest Windows Management Framework.
ProblemThe sensor displayed incorrect results (0) or no values after migrating it to a new or different server or Windows version. You may also get the error message XML: Junk after document element </text> -- JSON: The returned JSON does not match the expected structure (Invalid JSON.). (code: PE231)
SolutionKeep in mind that newer operating systems will usually run a newer PowerShell version, your cmdlets may be missing parameters, or your variables may not be correctly called within text ($($var) instead of $var). Run the script from the command line to confirm that it still works or adjust it if necessary.

Created on Sep 22, 2016 9:16:26 AM by  Stephan Linke [Paessler Support]

Last change on Jan 4, 2023 2:43:11 PM by  Brandy Greger [Paessler Support]



Votes:

0

Could you by any chance provide a guide on creating lookup files to turn standard xml output into something PRTG can understand?

Created on Jan 12, 2018 3:00:47 PM



Votes:

0

Hey Sam,

You might want to check the REST Custom Sensor, as it allow you to properly evaluate XML/JSON into PRTGesque channels :) Or do you require assistance with that?


Kind regards,
Stephan Linke, Tech Support Team

Created on Jan 15, 2018 7:28:56 AM by  Stephan Linke [Paessler Support]



Votes:

0

I am getting the "Response not well formed ... cannot be loaded because the execution of scripts is disabled on this system" error even though I have tried setting the execution policy to RemoteSigned, Unrestricted, and Bypass on the system where the sensor is located (the probe system itself). I have also tried using the "-Scope LocalMachine" parameter and using both options for Security Context. I can log into the server and run the script from within a PowerShell process myself with no problems. What am I missing?

Created on Mar 7, 2019 10:38:33 PM



Votes:

0

Hey Sam.

I have been down this path and hopefully I am at my end. There is an Advanced HTTP sensor that I am hoping will fit the bill. Stephan's suggestion sounds pefect, until you get under the hood. It is beta, does not support smart URL lookups (sensor only reports locally). The other option is to write a script or EXE which outputs the format you need and the values you need and that could work with a custom sensor. I would love it to take a remote native json or xml output returned as the deity(ies) intended....

If the Rest sensor mentioned was ever updated to support remote URLs as many other similar sensors are... it would be grand...

Created on May 29, 2019 1:56:10 AM



Votes:

0

@TypoProne Thanks for your input. The Sensor is indeed still in beta and likely not make it into a non-beta state, as we're working on a successor that will be easier to handle. But no ETA on that yet :)

Created on May 31, 2019 6:13:39 AM by  Stephan Linke [Paessler Support]

Last change on May 31, 2019 6:13:58 AM by  Stephan Linke [Paessler Support]



Votes:

0

Hi, I have configured a Dedicated machine for just Remote Probe, In that Remote Probe We have added Our client Servers, In the Remote probe, we have given the client LAN Network, This setup we use for all our clients,

Our clients have multiple LAN Interfaces in their servers, And we Want to monitor A specific IP and Its Port which is only reachable from the Clients Server, So for Monitor, the IP, and Its Port We have created (Vbs Scripts) which use PortQryV2 App,

Set WshShell = WScript.CreateObject("WScript.Shell")
Return = WshShell.Run("C:\PortQryV2\PortQry.exe -n XXX.XX.XXX.XX -p tcp -e 21 -q", 1, true)
if Return = 0 then
WScript.Echo "0:Success"
else
WScript.Echo "1:Failed"
end if

This scripts is located in C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXE

But after we configure the scripts and try to add in EXE\Scripts sensor on the client's Device we are getting a failed value as per the in the scripts.

Please Help me on this

Thanks & Regards Sawan Patel

Created on Feb 14, 2023 11:24:41 AM

Last change on Feb 15, 2023 6:52:02 AM by  Felix Wiesneth [Paessler Support]



Votes:

0

Hi Paessler...

With the "new" 'PowerShellScriptRunner.exe', which security context(Set-ExecutionPolicy) has to be updated ?

Thanks JR

Created on Feb 15, 2023 5:59:20 PM by  JR Andreassen (10) 2



Votes:

0

Hello Sawan Patel, could you directly reach out to us via mail at [email protected], so we can take a closer look? Log files oft the affected sensor (For this please go to the settings of the sensor and activate the "Store Result" option. Log files are then stored on the corresponding probe under "C:\ProgramData\Paessler\PRTG Network Monitor\Logs\sensors"), Screenshots of the issue you are facing, as well as screenshots of the manual script execution might help to analyze this issue further.

Hi JR, may I ask which "new" exe you are referring to exactly? As there haven't been any changes lately that I'm aware of.

Created on Feb 20, 2023 12:53:39 PM by  Timo Dambach [Paessler Support]



Votes:

0

Hi Timo...

Well, I don't know how "new" it is, but "PowershellScriptRunner.exe" is what invokes the custom powershell sensor. And the question is... Which version of poowershell and security context does it use ? I have a custom autodiscovery script that refuses to run even after setting the policy to RemoteSigned.

Thanks JR

Created on Mar 15, 2023 10:58:22 PM by  JR Andreassen (10) 2



Votes:

0

Hi JR,
Powershell version 5.1 and execution policy RemoteSigned is used. The security context is either the user account of the PRTG probe service (by default local system) or the account configured in the device depending on the sensor settings.

Created on Mar 21, 2023 12:37:00 PM by  Timo Dambach [Paessler Support]




Disclaimer: The information in the Paessler Knowledge Base comes without warranty of any kind. Use at your own risk. Before applying any instructions please exercise proper system administrator housekeeping. You must make sure that a proper backup of all your data is available.