on 14-Nov-2012 08:35
Articles in this series:
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 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:
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
The Live Data APIs are used to query the objects in the system. The table.xml function is used to access data in tables.
Possible values for content are:
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).
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: ..
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.
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"
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"
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.
Dirk Paessler
CEO Paessler AG
-Joe