PrtgAPI

PrtgAPI

PrtgAPI is a C#/PowerShell library for managing and maintaining PRTG Network Monitor.

PrtgAPI abstracts away the complexity of interfacing with PRTG via a collection of type safe methods and cmdlets, enabling you to develop powerful applications for managing your network.

Useful things you can do with PrtgAPI:

• Generate reports based on custom queries
• Monitor the monitoring, such as missing sensors for backup jobs or devices for new domain members!
• Create and modify sensors, devices, groups, and more! Create objects from scratch, or clone from existing!
• Generate complex sensor factory definitions
• Deploy notification triggers to individual sensors for specific clients
• Maintain standard naming/alerting/object settings across your environment
• Pause/resume items from external systems (such as pre/post event scripts and scheduled tasks)
• Batch do anything!

For information on features that are currently in the pipeline, check out the Roadmap.

Do you sometimes develop EXE/Script Advanced sensors for PRTG? Then you should also check out PrtgXml which utilizes black magic to generate the XML required by these sensors for you. Wow!

If, for some reason, you feel the need to throw money at me to show your appreciation for this project, you can do so anonymously by clicking here.

Installation

NuGet

Install-Package PrtgAPI

PrtgAPI is available on both nuget.org and PowerShell Gallery. PrtgAPI provides targets for both .NET Framework and .NET Standard and is SourceLink compatible. In order to install PrtgAPI from the PowerShell Gallery you must be running PowerShell 5.1+.

If you have both the nuget.org and PowerShell Gallery package sources installed on your machine, you will need to specify the source you wish to install from, e.g.

Install-Package PrtgAPI -Source PSGallery

If you are using Windows PowerShell, due to the PowerShell Gallery now requiring TLS 1.2 you may need to manually specify to use TLS 1.2 in order to install or update PrtgAPI

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12

Manual

1. Download the latest build
2. Right click PrtgAPI.zip -> Properties
3. On the General tab, under Security select Unblock
4. Unzip the file
5. Add a reference to PrtgAPI.dll to your project (fullclr: net452, coreclr: netstandard2.0), or import the PrtgAPI module into PowerShell via Import-Module C:\path\to\PrtgAPI. Alternatively, you can run the included PrtgAPI.cmd or PrtgAPI.sh file to open a prompt and import the PrtgAPI module for you.

Compilation

For details on compiling PrtgAPI please see the wiki

Usage

For detailed usage instructions please see the wiki.

The following provides a general overview of some of the capabilities of PrtgAPI. For more info on each section, click the appropriate link to be taken to the corresponding wiki page.

Overview (C#)

Authentication

All actions in PrtgAPI revolve around a core class: PrtgClient

var client = new PrtgClient("prtg.mycoolsite.com", "username", "password");

When a PrtgClient is created, it will immediately attempt to retrieve your account's passhash (an alternative to using a password) from your PRTG Server. For added security, your PassHash is then used for all future PRTG Requests made during the life of your program.

For further security, you are able to immediately pass your passhash to PrtgClient instead of using your password. Simply extract your passhash from your client object's PassHash property, then tell the PrtgClient constructor to use the passhash instead.

var client = new PrtgClient("prtg.mycoolsite.com", "username", "1234567890", AuthMode.PassHash);

Objects

Many types of objects can be retrieved from PRTG.

//Get all devices present in your system
var devices = client.GetDevices();

PrtgAPI defines a variety of method overloads for filtering requested objects, from simple to complex search criteria.

//List all sensors in a "down" or "down acknowledged" state.
var downSensors = client.GetSensors(Status.Down, Status.DownAcknowledged).Select(s => s.Name).ToList();

//List all devices under probes whose name contains "chicago"
var chicagoProbeDevices = client.GetDevices(Property.Probe, FilterOperator.Contains, "chicago");

Async is fine too

//List all sensors under the Device with Object ID 2000.
var childSensors = await client.GetSensorsAsync(Property.ParentId, 2000);

You can even use IQueryable!

//Get the first three Ping sensors for devices whose name contains "dc" on the Perth Office probe.

var perthDCPingSensors = client.QuerySensors(
    s => s.Type == "ping" && s.Device.Contains("dc") && s.Probe == "perth Office"
).Take(3);

Object Manipulation

PrtgAPI can manipulate objects in a variety of ways, including pausing, acknowledging and resuming, reorganizing objects as well as retrieving and modifying object properties.

//Acknowledge all down sensors for 10 minutes
var sensors = client.GetSensors(Status.Down);

foreach (var sensor in sensors)
{
    client.AcknowledgeSensor(sensor, 10, "Go away!");
}

//Standardize all "Ping" sensors to using the name "Ping", without the whole word capitalized
var sensors = client.GetSensors(Property.Name, "ping");

foreach (var sensor in sensors)
{
    client.RenameObject(sensor, "Ping");
}

//Set the upper error limit on the "Total" channel of all WMI CPU Load sensors to 90%
var sensors = client.GetSensors(Property.Tags, "wmicpuloadsensor");
var channels = sensors.SelectMany(s => client.GetChannels(s, "Total"));

foreach (var channel in channels)
{
    client.SetChannelProperty(channel, ChannelProperty.UpperErrorLimit, 90);
}

Many operations will let you specify multiple Object IDs at once, allowing you to modify potentially thousands of objects in a single request

//Acknowledge all down sensors indefinitely via a single request.
var sensors = client.GetSensors(Status.Down);

client.AcknowledgeSensor(sensors.Select(s => s.Id).ToArray());

Object Creation

You can construct an entirely new object hierarchy all within your application.

First, create a group

//Add a new group named "Servers" to the object with ID 1001
var group = client.AddGroup(1001, "Servers");

Then, add a device to it

//Add a new device named "dc-1" to the "Servers" group
var device = client.AddDevice(group, "dc-1");

We'll add a new sensor

//Create a brand new Ping sensor and add it to our device
var pingParams = client.GetDynamicSensorParameters(device, "ping");
var sensor = client.AddSensor(device, pingParams).Single();

And since we've already defined some notification triggers elsewhere, let's copy one in!

//Get the "PagerDuty" notification trigger from the object with ID 2001
var existingTrigger = client.GetNotificationTriggers(2001).First(t => t.OnNotificationAction.Name.Contains("PagerDuty"));

//Add it to our Ping sensor
var triggerParams = new StateTriggerParameters(sensor, existingTrigger);
var newTrigger = client.AddNotificationTrigger(triggerParams);

Madness!

For a comprehensive overview of the functionality of PrtgAPI and detailed usage instructions, please see the wiki

Overview (PowerShell)

To connect to your PRTG server, simply run

Connect-PrtgServer prtg.mycoolsite.com

You will then be prompted to enter your PRTG username and password. Your PassHash can also be used instead of specifying your password.

If you are scripting against PrtgAPI, you can use the included New-Credential cmdlet to bypass the authentication prompt.

Connect-PrtgServer prtg.mycoolsite.com (New-Credential prtgadmin supersecretpassword)

To avoid entering your username and password every time you use PrtgAPI, you can define GoPrtg connections in your $Profile to automatically connect for you.

If Connect-PrtgServer is executed outside of a script or the PowerShell ISE, PrtgAPI will by default display advanced progress details whenever two cmdlets are chained together. This can be overridden in a variety of ways.

PrtgAPI supports a wide variety of operations, each of which taking pipeline input from each other where applicable

…

All cmdlets include complete Get-Help documentation, including a cmdlet overview, parameter descriptions and example usages. For an overview of a cmdlet see Get-Help or Get-Help -Full for complete documentation.

Objects

Many types of objects can be retrieved from PRTG.

Get all ping sensors

C:\> Get-Sensor ping # pipe to Format-List to view all properties!

Name                Id      Device      Group           Probe           Status
----                --      ------      -----           -----           ------
PING                2010    dc1         Servers         Local Probe     Up
Ping                2011    dc2         Servers         Local Probe     Down
Ping                2012    exch1       Servers         Remote Probe    DownAcknowledged

Get all devices whose names contain "dc"

C:\> Get-Device *dc*

Name                Id      Status    Host      Group           Probe
----                --      ------    ----      -----           -----
dc1                 2001    Up        10.0.0.1  Servers         Local Probe
dc2                 2002    Down      dc-2      Servers         Local Probe

Get the channels of a sensor

C:\> Get-Sensor | Select -First 1 | Get-Channel

Name                SensorId    Id    LastValue LimitsEnabled UpperErrorLimit LowerErrorLimit ErrorLimitMessage
----                --------    --    --------- ------------- --------------- --------------- -----------------
Total               3001         0       0.32 %          True              95                 PANIC!! PANIC!!!
Processor 1         3001         1          Group -> Group -> Device -> Sensor -> Channel)

```powershell
$sensors = Get-Probe | Select -Last 1 | Get-Group | Select -Last 2 | Get-Device | Select -First 1 | Get-Sensor
$sensors | Get-Channel perc* | Set-ChannelProperty UpperErrorLimit 100

Object Creation

PowerShell makes it easy to construct complex object hierarchies

# Create a new group a