Probe

Contents

• Overview
  • Server
  • Probe

Probe

After cloning the PrtgDocker repo to your computer and placing an installer under the repo path, PRTG Remote Probes can be created by simply invoking New-PrtgBuild and New-PrtgContainer with the additional -Probe parameter from the build.cmd PowerShell prompt. In practice however, there are a number of additional parameters you may wish to take into account (in particular when instantiating containers).

Note: there are a number of important considerations to take into account when using Docker Probes. For more information please see Migrating to Docker Probes.

Image Creation

PRTG Probe images can be created by specifying the -Probe parameter to New-PrtgBuild. When building PRTG Probes, simply place a single PRTG Probe installer in the PrtgDocker folder, then run

# Build a Server 2019 image
New-PrtgBuild -Probe

The following table describes the parameters that can be specified to New-PrtgBuild when creating a probe

Parameter	Default	Description
-Probe	False	Specifies that a PRTG Remote Probe image should be built
-BaseImage	ltsc2019	Specifies the base image to use for the image (ltsc2016, ltsc2019, etc)
-AdditionalArgs	null	Specifies additional args to be added to the call to docker build
-Force	False	Specifies to force rebuild Docker images without using the build cache
-HyperV	False	Specifies that the image should be built using Hyper-V isolation
-Repository	prtgprobe	Repository to use for the image
-Server	False	Specifies that large files should be passed to the build over a web server (reducing the size of the image)
-AdditionalInstallerArgs	null	Specifies additional arguments to be specified to the probe installer when it is executed during the build process. Arguments may not contain spaces

For most users, only the parameters -Probe, -BaseImage and -AdditionalArgs will be of interest. For a stock build on Windows Server 2019 however, simply specifying the -Probe parameter will suffice.

Container Creation

In theory, a new PRTG Probe container can be created as simply as follows

# Don't do this
New-PrtgContainer -Probe

In reality, while this will technically create you a working container with a running probe, it won't know what PRTG Server to connect to, and even if it did it would lose all of its configuration when the container shuts down.

The following illustrates the typical command I use when creating a probe

New-PrtgContainer -Probe -Name "New York 1" -Server prtg.example.com -Volume -CredentialSpec -CredentialSpecAccount container_gmsa -CustomSensorsPath "\\fs-1.contoso.local\CustomSensors"

The following table describes the parameters that can be specified to New-PrtgContainer when creating a probe

Parameter	Default	Description
-Probe	False	Specifies that a PRTG Remote Probe container should be built
-Name	null	Specifies the name to assign both the container and the probe itself within PRTG
-ServerUrl	null	Specifies the URL of the PRTG Network Monitor server the probe should connect to (this should always be the same server you downloaded the PRTG Probe Installer from)
-Volume	False	Specifies that a volume should be created for the container
-CustomSensorsPath	null	Specifies a custom UNC path to redirect the Custom Sensors folder to
-CredentialSpec	False	Specifies that a Credential Spec should be used for Active Directory authentication within the container
-CredentialSpecAccount	null	Specifies the account to use for creating a credential spec if one doesn't already exist
-AdditionalArgs	null	Specifies additional args to be added to the call to docker run
-RestartPolicy	Always	Specifies the circumstances under which the container should automatically be restarted. Possible values: Always, OnFailure, UnlessStopped, None
-Tag	*	Specifies the tag of the PRTG Probe -Repository to create a container for.
-Repository	prtgprobe	Specifies the repository containing the -Tag to create a container for
-Interactive	False	Specifies that the container should be launched in interactive mode, allowing you to see the console
-HyperV	False	Specifies that the container should run using Hyper-V isolation

Unlike with New-PrtgBuild, most of the parameters that can be specified to New-PrtgContainer when creating a probe are very important; I would strongly recommend using all of -Probe, -Name, -ServerUrl, -Volume, -CustomSensorsPath, -CredentialSpec and -CredentialSpecAccount whenever you create a probe.

• -Probe specifies that we're creating a probe`
• -Name and -ServerUrl inform the PRTG Probe of both the name it should give itself, and the address of the PRTG Server it should connect to. While the value of the server URL is actually embedded in the name of the PRTG Probe installer you download from PRTG, however New-PrtgBuild wipes this information out to prevent the probe that starts up at the end of the build from registering itself with PRTG
• -Volume ensures that your PRTG Probe config is saved, and that your PRTG Core Server recognizes it as an existing probe when the container is ever recreated
• -CustomSensorsPath allows you to redirect the Custom Sensors folder in Program Files to a common network location. If you plan on using any Custom Sensors, this is highly recommended to eliminate the need to copy and paste multiple copies of your sensors everywhere
• -CredentialSpec and -CredentialSpecAccount allow your container to use Active Directory authentication, which is required when using a -CustomSensorsPath

Once you plug in your -ServerUrl, -CredentialSpecAccount and -CustomSensorsPath, the only variable every time you create a new probe is going to be the -Name. For convenience, you may wish to wrap this up in a function of your own, that you can potentially add to the copy of PrtgDocker.ps1 that you use in your environment.

function New-PrtgContainerEx($name)
{
    New-PrtgContainer -Probe -Name $name -Server prtg.example.com -Volume -CredentialSpec -CredentialSpecAccount container_gmsa -CustomSensorsPath "\\fs-1.contoso.local\CustomSensors"
}

Note: there are a number of important considerations to take into account when using Docker Probes. For more information please see Migrating to Docker Probes.

Config Management

To prevent the probe that is instantiated the build process from connecting to your PRTG Server, PrtgDocker automatically renames the PRTG Probe installer from PRTG_Remote_Probe_Installer_for_prtg.example.com_with_key_{12345678}.exe to PRTG_Remote_Probe_Installer_for_localhost_with_key_{12345678}.exe and then removes all identifying attributes of this probe (excluding the Access Key) from the registry, providing you with a template that is ready to be duplicated for use with your PRTG Server.

As containerized PRTG Probes store their entire config in the registry (which would be lost upon the container being recreated) and do not provide access to the GUI based PRTG Administration Tool, PrtgDocker PRTG Probes automatically backup and restore their registry config the container volume (assuming the container was created with the -Volume parameter specified), by default located at C:\ProgramData\docker\volumes\<containerName>\_data\config.reg. If this file is modified while its probe is running, the probe will automatically stop the probe service, import the config, then restart the service so your changes can be applied.

Like PRTG Core Server containers, PRTG Probe containers automatically stop when the PRTG Probe.exe process is terminated and remains terminated after a 10 second delay. When the PRTG Probe container finally exits, it will export its current registry config to disk so it is ready to be re-imported the next time the container starts up.

When -Volume is specified, PrtgDocker also automatically redirects your Custom Sensors folder to your volume (C:\ProgramData\docker\volumes\<containerName>\_data) to allow adding and persisting files from within the Docker host's filesystem. To avoid duplicating your custom sensors between probes, it is recommended to redirect your Custom Sensors folder to a common network share. For more information on redirecting the Custom Sensors folder, please see Custom Sensors Redirection.