Tips & Tricks

PrtgDocker enables sysadmins that may not have any experience with Docker to containerize their PRTG systems without necessarily having to worry about understanding the basics of the Docker CLI. A side effect of this however is that a. when something goes wrong, you have no idea what to do, which ties in with b. Docker for Windows has a lot of problems that don't exist on other platforms (which, then, reinforces the former issue). This article outlines some key troubleshooting points you may wish to be aware of when attempting to use PrtgDocker (or even Docker in general).

Migrating to Docker Probes

Because Docker Probes are not technically part of your domain, a number of challenges can present themselves when moving your existing infrastructure over from a physical probe to a containerized probe. The following is a list of challenges you may encounter, and how you can work around them

Adding Custom Sensors

Normally to install custom sensors on a PRTG Probe, you would need access to the folder C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors. When using PRTG inside a container, this is no longer as easy to do.

PrtgDocker solves this problem for you by automatically redirecting the Custom Sensors folder to either an external UNC path or a path that can be mapped to a volume. For more information please see Custom Sensors Redirection

DNS Resolution

If you have any devices on your probe that use the short NETBIOS name of a device, you will find that these names can no longer be resolved under your Docker Probe, as the Docker container is not on your domain and does not know about your network's DNS search suffix. To work around this, you'll need to modify all of your devices to use the fully qualified domain name instead of the DNS short name.

This can be done easily by using PrtgAPI

# For every device that is not using an FQDN or an IP Address, set the IPv4 Host address to <hostAddress>.<domain>
Get-Probe "New York 1" | Get-Device | where { $_.Host -notlike "*.$env:userdnsdomain" -and $_.Host -notlike "*.*.*.*" } | foreach { $_ | Set-ObjectProperty -Host "$($_.Host).$env:userdnsdomain" }

Custom Script Security Contexts

EXE/XML Advanced custom sensors have the option of running in the security context of the PRTG Probe service, or the Windows account defined on the device. As containerized probes are not on the domain however, you will get an access denied error from PRTG when it attempts to run your script, even if your container is using a gMSA.

To work around this, you can change all of the affected sensors to use the security context of the probe service. You can easily do this for multiple sensors by using PrtgAPI.

Get-Probe "New York 1" | Get-Sensor -Type exexml | Set-ObjectProperty -UseWindowsAuthentication $false

You will then need to modify your script to specify your credentials explicitly.

You can either do this in clear text

function New-Credential
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]
        $UserName,

        [string]
        $Password
    )

    $secureString = ConvertTo-SecureString $Password -AsPlainText -Force

    New-Object System.Management.Automation.PSCredential -ArgumentList $UserName, $secureString
}

$cred = New-Credential username password

Invoke-Command -ComputerName $server {
    ...
} -Credential $cred

Or with some level of obfuscation

$encryptedPassword = "76492d1116743f0423413b16050a5345MgB8..."
$key = 54,60,18,60,10,20...
$password = ConvertTo-SecureString $encryptedPassword -Key $key
$cred = New-Object PSCredential -ArgumentList @("username", $password)

Invoke-Command -ComputerName $server {
    ...
} -Credential $cred

Restart Policy

By default PrtgDocker sets the restart policy of PRTG docker containers to --restart always. This has been confirmed to work on both Server 2016 and Server 2019. In some cases however the policy will fail to work if you've installed something on your system that messed with the default networking (potentially Hyper-V?). In this case you will need to either identify and resolve the direct cause of the issue, configure automatic startup for your containers via the use of a Scheduled Task that executes a startup script (docker start <name>) or build a new server that does not have this issue

Common Commands

While PrtgDocker makes it easy to create PRTG images and containers without requiring any existing Docker CLI knowledge, once the images have been deployed you're on your own to manage your containers.

The following lists some common commands that you should be aware of when attempting to use Docker

Images

• docker image ls: List all images on your system
• docker rm <repoAndTagOrId>: Removes the container with the specified repository and tag or ID

Images can be copied between servers with the following

• docker save <repoAndTagOrId> -o <file>: exports an image to a file
• docker load -i <file>: imports an image from a file

As the Windows Base image layers take a significant time to compress/extract however, it can be often much faster to just rebuild the image on each server with New-PrtgBuild.

Containers

• docker container ls: List all running containers on your system
• docker container ls -a: List all containers on your system
• docker start <nameOrId>: Starts the container with the specified name or ID
• docker stop <nameOrId>: Stops the container with the specified name or ID
• docker rm <nameOrId>: Removes the container with the specified name or ID
• docker <command> (docker container ls -q): Performs a command for all running containers on your system
• docker <command> (docker container ls -qa): Performs a command for all containers on your system
• docker inspect <nameOrId>: inspects the configuration of the container with the specified name or ID

Troubleshooting

• docker exec -it <nameOrId> powershell: Opens a PowerShell prompt inside of a running container with a specified name or ID
• docker logs <nameOrId>: Shows the output that has been emitted from PrtgDocker to the console of the Docker container