Skip to content

Administrative Tools

Jump to bottom
lordmilko edited this page Jan 3, 2019 · 14 revisions

PrtgAPI supports executing a number of administrative operations pertaining to the PRTG Core Server and its associated probes. The following methods and cmdlets generally correspond with the items found under Setup -> System Administration -> Administrative Tools in the PRTG UI.

Contents

C#

Restart Core Service

PrtgAPI is capable of restarting the PRTG Core Service and PRTG Probe Services of any server connected to a PRTG installation.

The PRTG Core Service can be restarted with the RestartCore method.

// Restart the PRTG Core Service. WARNING: this will cause PRTG to
// become unavailable for a potentially length period of time
client.RestartCore();

Depending on the size of your PRTG install, it can take some time for the PRTG Core Service to both shut down as well as start back up and fully initialize. As such the RestartCore method should be used with caution. If PRTG is part of a cluster, this will only restart the server specified by the current PrtgClient.

Restart Probe Service

The PRTG Probe Service can be restarted with the RestartProbe method. RestartProbe allows specifying the ID of the probe whose service should be restarted. If null is specified, the PRTG Probe Service will be restarted on all probes currently connected to PRTG.

// Restart the probe with ID 3005
client.RestartProbe(3005);
// Restart the probe service of all probes currently
// connected to PRTG
client.RestartProbe(null);

Backup Config Database

PRTG periodically creates backups of the PRTG Configuration Database (PRTG Configuration.dat) under the Configuration Auto-Backups folder (default path: C:\ProgramData\Paessler\PRTG Network Monitor\Configuration Auto-Backups).

A configuration backup can be manually generated with the BackupConfigDatabase method.

client.BackupConfigDatabase();

When BackupConfigDatabase executes, PRTG queues the backup request and returns a response immediately. When the backup request begins executing, PRTG will first write the current running configuration to disk and then backup the config to the Configuration Auto-Backups folder. Depending on the size of your PRTG installation, this may take several seconds to complete.

As requests to perform backups return immediately, it is not possible with PrtgAPI to detect that a backup has fully completed. This can be determined with physical access to the PRTG Core Server however by inspecting the contents of the Configuration Auto-Backups folder before and after the method is executed. When the backup successfully completes, a file PRTG Configuration (Snapshot yyyy-MM-dd HH-mm-ss).zip will be created.

Load Config Files

PRTG supports installing a number of custom files for customizing your PRTG install, including custom sensor lookups, device icons, report templates and language files. While these file types are typically reloaded whenever the PRTG Core Service is restarted, they can also be restarted while PRTG is running via the LoadConfigFiles method.

PRTG separates config files into two types

  • General - includes device icons, report templates and language files
  • Lookups - include value lookups used for customizing the display of channel values
// Reload all custom value lookups on your PRTG Core Server
client.LoadConfigFiles(ConfigFileType.Lookups);

Clear System Caches

PRTG stores several internal caches for optimizing performance, including caches for Geo Map data, Active Directory authentication and Graph Data. If you are experiencing any issues relating to these areas, clearing these caches can potentially help to resolve these issues.

PRTG Cache Data can be cleared with the ClearSystemCache method. PRTG separates cache data into two types

  • General - includes Geo Map and Active Directory authentication info
  • GraphData - includes only graph data info. NOTE: clearing this cache type will restart PRTG 
// Clear PRTG's Geo Map and Active Directory authentication caches
client.ClearSystemCache(SystemCacheType.General);

While General cache data can be cleared without issue, attempting to clear GraphData will cause the PRTG Core Service to completely restart. As such, great care should be used when specifying the cache type to clear.

Approve/Deny Probes

When the PRTG Probe Service is installed on a new system, the probe must first be approved within PRTG before the probe may begin reporting data back to the core server. Probe approval methods can be specified with the ApproveProbe method

client.ApproveProbe(1001, ProbeApproval.Allow);

Probes can be approved, approved with auto-discovery, or denied, causing their GID to be blacklisted. Attempting to modify the probe approval of a probe that has already been approved will generate an InvalidOperationException. You can check whether a probe has already been approved by checking the ProbeApproved property returned from GetProbeProperties.

// Approve all probes that are unapproved
var probes = client.GetProbes();

foreach (var probe in probes)
{
    if (!client.GetProbeProperties(probe.Id).ProbeApproved)
        client.ApproveProbe(probe.Id, ProbeApproval.Allow);
}

PowerShell

Restart Core Service

PrtgAPI is capable of restarting the PRTG Core Service and PRTG Probe Services of any server connected to a PRTG installation.

The PRTG Core Service can be restarted with the Restart-PrtgCore cmdlet.

Restart-PrtgCore

When Restart-PrtgCore is executed, it will prompt you to confirm you wish to restart the PRTG Core Service. To override this prompt the -Force parameter can be specified.

# WARNING: this will cease all monitoring and disconnect all users 
# from PRTG for a potentially lengthy period of time.
Restart-PrtgCore -Force

By default, Restart-PrtgCore will attempt to wait up to one hour for the PRTG Core Service to come back online before completing. If you do not wish the Restart-PrtgCore cmdlet to wait for the PRTG to reinitialize, -Wait:$false can be specified to override this behavior.

# Restart the PRTG Core Service without waiting for it to come back online.
Restart-PrtgCore -Wait:$false

The timeout duration can also be adjusted by specifying a custom value to the -Timeout parameter (in seconds)

# Restart the PRTG Core Service, giving it 10 minutes to
# restart before throwing an exception
Restart-PrtgCore -Timeout 600

If the PRTG Core Service does not restart within the specified timeout period, a TimeoutException will be thrown.

Restart Probe Service

The PRTG Probe Service a specified probe can be restarted with the Restart-Probe cmdlet.

# Restart the PRTG Probe Service of all probes whose name contains "contoso"
Get-Probe *contoso* | Restart-Probe

If no probe is specified, Restart-Probe will restart the PRTG Probe Service of all probes currently connected to your PRTG server.

# Restart the PRTG Probe Service on all currently connected PRTG Probes
Restart-Probe

When Restart-Probe is executed, it will prompt you to confirm you wish to restart the PRTG Probe Service. To override this prompt the -Force parameter can be specified.

# WARNING: this will cease on each probe as it is restarted without
# requiring any confirmation
Restart-Probe -Force

By default, Restart-Probe will attempt to wait up to one hour for all PRTG Probe Services to come back online before completing. If you do not wish the Restart-Probe cmdlet to wait for all services to restart and reconnect to PRTG, -Wait:$false can be specified to override this behavior.

# Restart the probe with ID 2004 without waiting for it to restart
Get-Probe -Id 2004 | Restart-Probe -Wait:$false

The timeout duration can also be adjusted by specifying a custom value to the -Timeout parameter (in seconds)

# Restart the PRTG Probe Service of the probe with ID 2004, giving
# it 10 minutes to restart before throwing an exception
Get-Probe -Id 2004 | Restart-Probe -Timeout 600

The Restart-Probe cmdlet is capable of executing in PassThru Mode. For more information on PassThru Mode, see PassThru Requests.

Backup Config Database

PRTG periodically creates backups of the PRTG Configuration Database (PRTG Configuration.dat) under the Configuration Auto-Backups folder (default path: C:\ProgramData\Paessler\PRTG Network Monitor\Configuration Auto-Backups).

A configuration backup can be manually generated with the Backup-PrtgConfig cmdlet.

Backup-PrtgConfig

When Backup-PrtgConfig executes, PRTG queues the backup request and returns a response immediately. When the backup request begins executing, PRTG will first write the current running configuration to disk and then backup the config to the Configuration Auto-Backups folder. Depending on the size of your PRTG installation, this may take several seconds to complete.

As requests to perform backups return immediately, it is not possible with PrtgAPI to detect that a backup has fully completed. This can be determined with physical access to the PRTG Core Server however by inspecting the contents of the Configuration Auto-Backups folder before and after the cmdlet is executed. When the backup successfully completes, a file PRTG Configuration (Snapshot yyyy-MM-dd HH-mm-ss).zip will be created.

Load Config Files

PRTG supports installing a number of custom files for customizing your PRTG install, including custom sensor lookups, device icons, report templates and language files. While these file types are typically reloaded whenever the PRTG Core Service is restarted, they can also be restarted while PRTG is running via the Load-PrtgConfigFile cmdlet.

PRTG separates config files into two types

  • General - includes device icons, report templates and language files
  • Lookups - include value lookups used for customizing the display of channel values
# Reload all custom value lookups on your PRTG Core Server
Load-PrtgConfigFile Lookups

Clear System Caches

PRTG stores several internal caches for optimizing performance, including caches for Geo Map data, Active Directory authentication and Graph Data. If you are experiencing any issues relating to these areas, clearing these caches can potentially help to resolve these issues.

PRTG Cache Data can be cleared with the Clear-PrtgCache cmdlet. PRTG separates cache data into two types

  • General - includes Geo Map and Active Directory authentication info
  • GraphData - includes only graph data info. NOTE: clearing this cache type will restart PRTG 
# Clear PRTG's Geo Map and Active Directory authentication caches
Clear-PrtgCache

While General cache data can be cleared without issue, clearing GraphData will cause the PRTG Core Service to completely restart. As such, if you attempt to clear Graph Data, Clear-PrtgCache will display a prompt to confirm you wish to proceed. If you wish to bypass this prompt, the -Force parameter can be specified.

# Clear PRTG's Graph Data cache without displaying a confirmation prompt
# that this will cause the PRTG Core Service to restart
Clear-PrtgCache GraphData -Force

Approve/Deny Probes

When the PRTG Probe Service is installed on a new system, the probe must first be approved within PRTG before the probe may begin reporting data back to the core server. Probe approval methods can be specified with the Approve-Probe cmdlet

Approve-Probe -Id 1001

Probes can be approved, approved with auto-discovery, or denied, causing their GID to be blacklisted. Attempting to modify the probe approval of a probe that has already been approved will generate a warning without modifying the probe. You can check whether a probe has already been approved by checking the ProbeApproved property returned from Get-ObjectProperty.

# Approve all probes. A warning will be emitted if a probe has already been approved
Get-Probe | Approve-Probe
# Deny all probes that have not yet been approved, ensuring no warnings are emitted
Get-Probe | where { ($_ | Get-ObjectProperty).ProbeApproved -eq $false } | Approve-Probe -Deny

See Also

Project Overview

User Guide

Utilities

Clone this wiki locally