Articles in this series:
- Monitoring Your Network with PRTG - Overview, Installation, and Configuration
- Monitoring Your Network with PRTG - Custom Sensors Part 1
- Monitoring Your Network with PRTG - Custom Sensors Part 2
- Monitoring Your Network with PRTG - Custom Notifications
In the previous articles in this series, I’ve talked about the PRTG Network Monitor and how you can customize it by building your own sensors and notifications. In this article, I’m going to look at the API that you can use to automate some of the manual tasks you would likely have to do on a day to day basis.
The API
The API documentation is available within the product. By clicking on the “Setup” menu and then clicking on “PRTG API”, you’ll see get to the API overview. If you don’t have the product installed, you can get to it through the demo site setup by PRTG.
PRTG exposes a RESTful interface that enables you to access and manipulate information from the monitoring database inside of PRTG. The API covers the following functional areas:
- Live Data - You can get properties, settings, and status information of an object.
- Live Graphs - Graphs are rendered as PNG files and can be used in other webpages.
- Historic Data - You can download the historic monitoring data for one sensor in XML or CSV format.
- Object Manipulation - Manipulate existing objects in the system.
How Are Calls Made?
The interface is HTTP/HTTPs based, and since it only utilizes GET requests, all you need is a browser to be able to make method calls. But, for the sake of automation, I’ll use the command line web client cURL in the examples below.
The format of the URL to the API is the following:
http(s)://prtg_server_address/api/function?username=uid&passhash=hash¶ms
- http(s) - In most cases, http will work. But, if you have configured it outside your DMZ, then you’ll want to setup SSL.
- prtg_server_address - the address and port of your PRTG instance. We have ours running on port 8080.
- function - the function you are trying to access. I’ll discuss some of them below:
- uid - The PRTG User account to authenticate the request
- hash - The Password Hash is shown on the user account settings page in the PRTG Administration settings.
- params - for methods passing in data, you will have to append query string parameters for those settings.
Querying Objects
The Live Data APIs are used to query the objects in the system. The table.xml function is used to access data in tables.
/api/table.xml?content=xxx&columns=y,y,y
Possible values for content are:
- sensortree - A Tree-like structure of groups, devices, and sensors
- groups - A list of all groups
- devices - A list of all devices
- sensors - A list of all sensors
- values - A list of most recent results of a sensor (sensor ID parameter required)
- channels - A list of the channels of a sensor (sensor ID parameter required)
- reports - A list of reports
- storedreports - A list of most recent PDF reports (report ID required)
- todos - A list of most recent todo notification items.
There are a LOT of column types, and the values you pass in are dependent on the what you select as your content. I’ll leave it as an exercise of the reader to review all those values either in your own PRTG instance (or at the online reference).
Example: Querying sensors
1: PS> $host = "xx.xx.xx.xx:8080"
2: PS> $columns = "objid,group,device,host,status,status_raw"
3: PS> curl "http://$host/api/table.xml?content=sensors&columns=$columns&username=prtgadmin&passhash=NNNNNNNN"
4: <?xml version="1.0" encoding="UTF-8"?>
5: <sensors> 6: <prtg-version>12.2.2.2211</prtg-version> 7: <item> 8: <objid>1001</objid> 9: <group>Local probe</group> 10: <device>server-01</device> 11: <host/> 12: <status>Up </status> 13: <status_raw>3</status_raw> 14: <status>Up </status> 15: <status_raw>3</status_raw> 16: </item> 17: <item> 18: <objid>1002</objid> 19: <group>Local probe</group> 20: <device>server-01</device> 21: <host/> 22: <status>Up </status> 23: <status_raw>3</status_raw> 24: <status>Up </status> 25: <status_raw>3</status_raw> 26: </item> 27: ..Example: Pausing a Sensor
To control the enabled state of a sensor, you’ll want to look at the “pause.htm” function. It takes as input a sensor id, and an action.
/api/pause.htm?id=objectid&action=action
- objectid - the id (objid) returned in the sensor list query.
- action - 0 for disabled, 1 for enabled
In the call below, I’m looking at sensor id 2330 which is a PING for our DC1-PRD-APP-01 server. Making this request will cause the sensor to go into a paused state.
1: PS> $host = "xx.xx.xx.xx:8080";
2: PS> $objid = "2330";
3: PS> $action = "0"
4: PS> curl "http://$host/api/pause.htm?id=$objid&action=$action&username=prtgadmin&passhash=NNNNNNNN"
Example: Resuming a Sensor
To Resume a sensor, just pass in a value of 1 for the action parameter.
1: PS> $host = "xx.xx.xx.xx:8080";
2: PS> $objid = "2330";
3: PS> $action = "1";
4: PS> curl "http://$host/api/pause.htm?id=$objid&action=$action&username=prtgadmin&passhash=NNNNNNNN"
Conclusion
Armed with a handy command line, you can easily build a procedure to automate control of your PRTG configuration. There is a lot more functionality exposed in the PRTG API than I was able to cover in this article. I’m working on a PowerShell wrapper library for their entire API set so be on the look out in the next few weeks for it’s public appearance.
