I am managing 14,500 devices spread across 180 locations ( schools ) and I want to be able to set up reports for each of the locations. The devices are wireless access points and I want the IT person at the school to get reports on downtime, client number and bandwidth usage on the access points.
I have done some research today on what I can do with the API and also what I could do using a program to drive the normal user interface ( web scraping and automation ). So this is a post about my findings and an invitation to anybody who may have looked at this to chime in with more information. I just want to share my findings because a fair bit of what I found isn't that well documented:
Article Comments
The API for reports is limited. You can do the following:
- Pull a list of reports
- Delete a report
- Clone and rename a report
- Set the sensors for a report ( add additionals but not remove )
What you cannot do is manipulate report settings through the API but this should be possible through web scraping of the main Settings page web form but this would require a sophisticated python script and couldn't be done with a simple shell script. In terms of automating reports for schools the options might be:
- Create template reports with everything set except:
- recipient email
- Report name
- Root device group for sensor selection
- Clone and rename the reports using API call
- Set device group with API call
- Set email address for recipients with web scraper script
I would potentially be cloning each report 180 times. If I decided to change something in the report such as:
- Sensor filter tag
- Day of report generation
- Inclusion of data files
- Beginning and end text
my choices would be:
- Modify base report, delete all clones reports and regenerate
- Use webscraper approach to modify all cloned reports individually ( would need to be able to identify them, probably based on a key value in the report name )
Report API Examples
Pulling a List of Reports
So the only thing I can find that you can do with reports is list them. You don't seem to be able to manipulate the node on the device tree to which a run will apply
curl --noproxy mydom.com https://prtgaero.mydom.com/api/table.xml?content=reports\&output=xml\&columns=objid,name,template,\
period,schedule,email,lastrun,nextrun\&username=RESTFOOL\&passhash=1234567890
<?xml version="1.0" encoding="UTF-8"?>
<reports totalcount="13" listend="1">
<prtg-version>18.3.42.1748</prtg-version>
<item>
<objid>400</objid>
<name>Summary report for all sensors</name>
<template>List of sensors (with 1h graph)</template>
<period>Day</period>
<period_raw>0</period_raw>
<schedule>None</schedule>
<schedule_raw>0</schedule_raw>
<email/>
<lastrun>-</lastrun>
<nextrun>-</nextrun>
</item>
<item>
:
<item>
<objid>4787</objid>
<name>Santaluces Top 100 Client Counts - 1min Avgs</name>
<template>Highest and lowest 1 minute averages</template>
<period>Day</period>
<period_raw>0</period_raw>
<schedule>None</schedule>
<schedule_raw>0</schedule_raw>
<email/>
<lastrun>8/29/2018 2:03:59 PM (176 Sensors)</lastrun>
<lastrun_raw>43341.7527726157</lastrun_raw>
<nextrun>-</nextrun>
</item>
<item>
<objid>4788</objid>
<name>Santaluces Top 100 Client Counts - 5min Avgs</name>
<template>Highest and lowest 5 minute averages</template>
<period>Day</period>
<period_raw>0</period_raw>
<schedule>None</schedule>
<schedule_raw>0</schedule_raw>
<email/>
<lastrun>8/29/2018 2:04:30 PM (176 Sensors)</lastrun>
<lastrun_raw>43341.7531268750</lastrun_raw>
<nextrun>-</nextrun>
</item>
Rename a Report
You can rename a report:
curl --noproxy mydom.com https://prtgaero.mydom.com/api/rename.htm?id=4788\&value=Silly%20New%20Report%20Name\&username=RESTFOOL\&passhash=1234567890
<HTML><BODY class="no-content"><B class="no-content">OK</B></BODY></HTML>
Set Sensors for a Report
So contrary to my belief, there is an API call to add a group, device or sensor.
curl --noproxy mydom.com https://prtgaero.mydom.com/api/reportaddsensor.htm?id=4785\&addid=2934\&username=RESTFOOL\&passhash=1234567890
The problem is that there is no way to retrieve the set of assigned sensors or groups or to delete objects. The only option would be to clone a report, set the report name and sensors and email. We would want to be able to delete a report as well if we needed to rebuild a set of reports.
Clone a Report
A report can be cloned and the clone renamed:
curl --noproxy mydom.com https://prtgaero.mydom.com/api/duplicateobject.htm?id=4784\&name=TestNewReport\&username=RESTFOOL\&passhash=1234567890
Note that this does not provide us with the ID of the new object. A better way to use curl is:
curl -Ls -o /dev/null -w %{url_effective} --noproxy mydom.com https://prtgaero.mydom.com/api/duplicateobject.htm?id=4784\&name=TestNewReport\&username=RESTFOOL\&passhash=1234567890
https://prtgaero.mydom.com/public/login.htm?loginurl=%2Freport.htm%3Fid%3D4792%26tabid%3D3&errormsg=
- -L option: "If the server reports that the requested page has moved to a different location (indicated with a Location: header and a 3XX response code), this option will make curl redo the request on the new place."
- -o /dev/null sends normal output to oblivion
- -w %{url_effective} causes the redirect URL to be written to stdout
- -s is silent
So we get the redirect URL back and in there is the ID of the new object:
https://prtgaero.mydom.com/public/login.htm?loginurl=%2Freport.htm%3Fid%3D4792%26tabid%3D3&errormsg=
In our script we pull this ID out by piping the output through sed:
| sed -e 's/^https.*id%3D\([0-9]\+\).*$/\1/'
The response when creating a report is the following ( used the -v option to get this ):
< HTTP/1.1 302 Moved Temporarily
< Connection: close
< Content-Type: text/html; charset=UTF-8
< Content-Length: 0
< Date: Thu, 30 Aug 2018 17:37:27 GMT
< Expires: 0
< Cache-Control: no-cache
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
< Server: PRTG/18.3.42.1748
< Location: /report.htm?id=4793&tabid=3
The returned URL /report.htm?id=4793&tabid=3 would actually take you to the Settings tab for the newly created report.
Delete a Report
In the event that there was some kind of change to the master report, there would be a requirement to delete any reports cloned from the master and then recreate them.
curl --noproxy mydom.com https://prtgaero.mydom.com/api/deleteobject.htm?id=4791\&approve=1\&username=RESTFOOL\&passhash=1234567890
Scheduling or Customizing a Report
Once a report has been cloned, assuming it has no scheduling, it is then possible to set it up on a schedule to be emailed out. I found reference to what looks like an API call "genreport" with the following parameters:
Parameter Description
id Report ID
report_period Must be set to "manual"
manual_period_start Start date in format 2010-01-01
manual_period_end End date in format 2010-03-31
report_processing Set to "report_pdfandmail"
report_emailaddress Target Email Address for the report
This was pulled from a forum post detailing a specific use of those parameters and the API call is not documented by Paessler. The problem this one is that it is a one time invocation
Looking at what happens when the settings are changed and saved through the web interface:
#593016 2018-08-30 15:09:53 10.254.20.208 "user2917" prtgaero.mydom.com 443 POST /editsettings
"name_=Weekly Daily Downtime"
&tags_=
&"template_=T2 Top10 Uptime time.htm"
&"ownerid_=2917|Ed McGuigan|"
&"timezone_=Eastern Standard Time|(UTC-05:00) Eastern Time (US & Canada)"
&papersize_=letter
&orientation_=0
&comments=
&sensorlist=2945
&tagfilter_=
&filtertag_=pingsensor
&scheduletype_=3
&specifichour_=0
&dayweek_=7
&daymonth_=1
&date_=
&maildisk_=2
&emailaddress_=ed.mcguigan@gmail.com,sillybilly@bobo.com
&emailgroup_=-1
&usecompression_=0
&dataperiod_=1
&reporttype_=1
&reportday_=0
&reportweek_=1
&reportmonth_=1
&reportyear_=1
&schedule_=-1|None|
&percentileshow_=0
&percentile_=95
&percentileaverage_=300
&percentilemode_=1
&savedatafiles_=nofiles
&"reportheader_=Bing bong boolabongbing"
&"reportfooter_=Ding dang gillyfangs"
&accessrights_=1
&accessrights_=1
&accessrights_201=100
&id=4790
It would be possible for me to build up a web form and do a POST to simulate this. I would need to pull the report with a webscraper and then read every form field and it's value to recreate the form, change the email address to what I wanted and then post the form. Fairly doable from python.
Aug, 2018 - Permalink
The API for reports is limited. You can do the following:
What you cannot do is manipulate report settings through the API but this should be possible through web scraping of the main Settings page web form but this would require a sophisticated python script and couldn't be done with a simple shell script. In terms of automating reports for schools the options might be:
I would potentially be cloning each report 180 times. If I decided to change something in the report such as:
my choices would be:
Report API Examples
Pulling a List of Reports
So the only thing I can find that you can do with reports is list them. You don't seem to be able to manipulate the node on the device tree to which a run will apply
curl --noproxy mydom.com https://prtgaero.mydom.com/api/table.xml?content=reports\&output=xml\&columns=objid,name,template,\ period,schedule,email,lastrun,nextrun\&username=RESTFOOL\&passhash=1234567890 <?xml version="1.0" encoding="UTF-8"?> <reports totalcount="13" listend="1"> <prtg-version>18.3.42.1748</prtg-version> <item> <objid>400</objid> <name>Summary report for all sensors</name> <template>List of sensors (with 1h graph)</template> <period>Day</period> <period_raw>0</period_raw> <schedule>None</schedule> <schedule_raw>0</schedule_raw> <email/> <lastrun>-</lastrun> <nextrun>-</nextrun> </item> <item> : <item> <objid>4787</objid> <name>Santaluces Top 100 Client Counts - 1min Avgs</name> <template>Highest and lowest 1 minute averages</template> <period>Day</period> <period_raw>0</period_raw> <schedule>None</schedule> <schedule_raw>0</schedule_raw> <email/> <lastrun>8/29/2018 2:03:59 PM (176 Sensors)</lastrun> <lastrun_raw>43341.7527726157</lastrun_raw> <nextrun>-</nextrun> </item> <item> <objid>4788</objid> <name>Santaluces Top 100 Client Counts - 5min Avgs</name> <template>Highest and lowest 5 minute averages</template> <period>Day</period> <period_raw>0</period_raw> <schedule>None</schedule> <schedule_raw>0</schedule_raw> <email/> <lastrun>8/29/2018 2:04:30 PM (176 Sensors)</lastrun> <lastrun_raw>43341.7531268750</lastrun_raw> <nextrun>-</nextrun> </item>Rename a Report
You can rename a report:
Set Sensors for a Report
So contrary to my belief, there is an API call to add a group, device or sensor.
curl --noproxy mydom.com https://prtgaero.mydom.com/api/reportaddsensor.htm?id=4785\&addid=2934\&username=RESTFOOL\&passhash=1234567890The problem is that there is no way to retrieve the set of assigned sensors or groups or to delete objects. The only option would be to clone a report, set the report name and sensors and email. We would want to be able to delete a report as well if we needed to rebuild a set of reports.Clone a Report
A report can be cloned and the clone renamed:
Note that this does not provide us with the ID of the new object. A better way to use curl is:
curl -Ls -o /dev/null -w %{url_effective} --noproxy mydom.com https://prtgaero.mydom.com/api/duplicateobject.htm?id=4784\&name=TestNewReport\&username=RESTFOOL\&passhash=1234567890 https://prtgaero.mydom.com/public/login.htm?loginurl=%2Freport.htm%3Fid%3D4792%26tabid%3D3&errormsg=So we get the redirect URL back and in there is the ID of the new object:
In our script we pull this ID out by piping the output through sed:
| sed -e 's/^https.*id%3D\([0-9]\+\).*$/\1/'The response when creating a report is the following ( used the -v option to get this ):
The returned URL /report.htm?id=4793&tabid=3 would actually take you to the Settings tab for the newly created report. Delete a Report In the event that there was some kind of change to the master report, there would be a requirement to delete any reports cloned from the master and then recreate them.
Scheduling or Customizing a Report
Once a report has been cloned, assuming it has no scheduling, it is then possible to set it up on a schedule to be emailed out. I found reference to what looks like an API call "genreport" with the following parameters:
Parameter Description id Report ID report_period Must be set to "manual" manual_period_start Start date in format 2010-01-01 manual_period_end End date in format 2010-03-31 report_processing Set to "report_pdfandmail" report_emailaddress Target Email Address for the report
This was pulled from a forum post detailing a specific use of those parameters and the API call is not documented by Paessler. The problem this one is that it is a one time invocation
Looking at what happens when the settings are changed and saved through the web interface:
It would be possible for me to build up a web form and do a POST to simulate this. I would need to pull the report with a webscraper and then read every form field and it's value to recreate the form, change the email address to what I wanted and then post the form. Fairly doable from python.
Aug, 2018 - Permalink