This article applies to PRTG Network Monitor 19 or later
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?
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 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:
| Setting | Description |
|---|---|
| Restricted | No scripts can directly be executed, only within an interactive session. |
| AllSigned | Only scripts from a trusted author can be executed. |
| RemoteSigned | Downloaded scripts have to be signed prior to execution. |
| Unrestricted | There 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 PRTG probe is a 32-bit application), we need to use the 32-bit PowerShell:
- Open Windows PowerShell (x86), respectively Windows PowerShell (32-bit) as Administrator.
- 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 system where the remote probe is installed, 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 line | EXE/Script | <PRTG Application Directory>\Custom Sensors\EXE\ |
|---|---|---|
| XML | EXE/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:
- Open the script and search for something like Write-Host or Out-Host
- 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.
| Parameter | Description |
|---|---|
| EXE/Script | Select the script you have just installed. |
| Parameters | Enter the parameters. Remember that you can use placeholders here. |
| Security Context | Choose if you want PRTG to run the script using the user account of the probe service or the account configured in the device. |
| Mutex Name | If you have many sensors that run concurrently, you can configure different mutex names so that they do not hinder each other. |
First aid
| Problem | Response 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. |
|---|---|
| Solution1 | The execution policy is not correctly configured on the host. Go through Step 1 of this tutorial to resolve this. |
| Solution2 | Double-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. |
| Problem | The sensor shows the message UnauthorizedAccess. |
|---|---|
| Solution | This is probably because of the user account that is configured in the 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. |
| Problem | The 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. |
|---|---|
| Solution | This 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 server. Most likely, the latter is the case. Make sure that you are running the latest Windows Management Framework. |
| Problem | The 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) |
|---|---|
| Solution | Keep 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. |
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.
