PRTG API

Sie haben sicher schon gesehen, dass es hier viele Skripte für PRTG gibt. Paessler hat dankenswerterweise viele Funktionen über APIs zugänglich gemacht. Hier beschreiben ich die wesentlichen Dinge in Kurzform.

Dokumentation

Die Dokumentation ist auf jedem PRTG-Server immer mit installiert. Sie finden den Einstiegspunkt direkt auf der Webseite unter "Setup - PRTG API":

Der Link verweist dann auf die URL https://<ipr-prtg-server/api.htm?tabid=1. Sie benötigen also schon eine installierte PRTG-Installation oder sie schauen einfach auf der Demo-Umgebung von Paessler auf https://prtg.paessler.com/api.htm?tabid=1 nach.

Die Anmeldung erfolgt mit "demo" und dem Kennwort "demodemo".

Fast alle APIs basiere auf HTTP nutzen XML oder JSON-Formate. Sie sind daher von quasi jedem System nutzbar.

Authentifizierung

Da eine anonyme Nutzung nicht möglich ist, müssen sich die Prozesse an der API entsprechend anmelden. Anders als bei der Webseite mit der formularbasierten Anmeldung hat Paessler bei der API die Authentifizierung per URL-Parameter gewählt. Das macht es sehr einfach aber ohne HTTPS sind die die Daten natürlich auch einfach mitzulauschen.

Die Anmeldung erfolgt per Benutzername und Kennwort oder einem PassHash. Man muss bei der API, anders als bei der Webseite, nicht das Kennwort übertragen. Mit dem Passhash ist nur eine Nutzung der API möglich. Allerdings ist auch die API sehr leistungsfähig und erlaubt Änderungen. Insofern ist auch der Passhash als sensibel zu betrachten

Über die API kann der dann angemeldete Benutzer natürlich nur das lesen und machen, was er anhand seiner Berechtigungen auch sonst ausüben könnte. Für erste Gehversuche bietet es sich daher an, ein eigenes Konto in PRTG anzulegen, welches bezüglich der Konfiguration "ReadOnly" arbeitet.

Eigene Sensoren

Ich habe zuerst damit angefangen, eigene Sensoren zu schreiben. Es gab immer was zu messen und zu prüfen, wozu es von Paessler noch keinen passenden Sensor gab. Dennoch sollten Sie einmal genau schauen, welche Sensoren es schon gibt denn auch hier ist Paessler sehr umtriebig und addiert neue interessante Sensoren sehr schnell. Nehmen wir aber an, dass es keinen passenden Sensor gibt, dann müssen wir selbst einen Sensor entwickeln. Hier gibt es mehrere Varianten. Zuerst sollte man unterscheiden, wo der Sensor läuft. Da gibt es mehrere Optionen:

  • Sensor auf der Probe
    Die PRTG Probe kann Programme und Skript auf dem Probe-System direkt starten. Diese Skripte liefern dann über STDOUT entweder einen einzelnen Wert mit Status oder eine XML-Struktur mit mehreren Kanälen zurück. Solche Sensoren brauchen in PRTG keine gesonderten Rechtem da Sie von der Probe gestartet werden.
  • HTTP-Push-Sensoren
    Interessant ist auch der Weg die Daten per HTTP-Request an eine PRTG-Probe zu übermitteln. Auch diese API ist sehr einfach nutzbar. So kann jedes Gerät aktiv Werte an PRTG senden. Die Authentifizierung erfolgt dabei über einen String, den nur der Sender selbst und der dazu konfigurierte Sensor kennt.
  • Mini-Probe
    Eine Besonderheit ist diese Probe, die keine vollständige auf Windows basierende Probe ist, sondern eine "Light"-Version, die z.B. auf Linux oder Android zu laufen kommen. Dabei startet aber eine PRTG-Probe auf diesen Miniprobes die entsprechenden Aktionen an, die aber vom Umfang geringer sind.

Für Daten, die von einer PRTG-Probe selbst erreicht werden können, nutze ich gerne entsprechende PowerShell-Skripte auf der Probe. Die kann ich zentral pflegen und aktualisieren.

Auf der anderen Seite sind die HTTP-Push-Sensoren ideal um Daten durch eigene Skripte oder "IoT-Geräte an PRTG zu senden. Die Syntax und Funktion ist so einfach, dass das sogar ein ESP8266 und andere Systeme können. HTTPPush ist aber auch interessant, wen ich in einem Skript eine umfangreiche Auswertung mache und die Daten in mehrere Sensoren aufteilen will.

Datenzugriff

Alle Daten, die durch Sensoren in die PRTG-Datenbank gespült werden, können über eine API auch wieder ausgelesen werden. Anwendungsfällt hierfür gibt es viele. Oft steht PRTG nicht alleine und man möchte gewisse Daten einfach aus einem anderen System für weitere Auswertungen abgreifen. Ich selbst nutzt die Funktion um z.B. Daten einer PRTG-Kundeninstallation in meine eigene PRTG-Installation zu übertragen.

Interessant ist natürlich auf der Weg direkt die Bilder und Grafiken per API zu erhalten. Das eröffnet ganz neue Wege diese Informationen z.B. in andere Webseiten und Tools zu integrieren.

Auch der Zugriff auf historische Daten als Tabelle ist einfach möglich. Wobei der Begriff "Historisch" etwas übertrieben scheint. PRTG speichert die Daten nur 365 Tage. Über diese Funktion können Sie die Daten in ein Datenarchiv übertragen, welche die Werte für länger also die 12 Monate (PRTG Default) speichert.

Konfiguration und Manipulation

Der dritte Baustein ist die Konfiguration von PRTG über eine API. Sie können über die API z.B. eine Liste der Sensoren und Kanäle auslesen. Sie können damit aber auch Sensoren anlegen, bestehende Sensoren ändern u.a. Diese Funktion nutze ich selbst aktuell aber auch noch nicht, da ich solche Massensensoren noch nicht anzulegen habe und viele Kanäle allein durch die "AutoScan"-Funktion der vordefinierten Sensoren gefunden werden. Aber es ist gut zu wissen, dass es diese API gibt. Ich kann mir vorstellen, dass PRTG auch intern selbst mit der API arbeitet.

Die API erlaubt auch eine Automatisierung von bestimmten Funktionen. Sie können damit z.B. einen "ReScan" starten oder einen Sensor pausieren und wieder starten. Sie können diese Funktion damit problemlos in ihre eigene Managementlösung integrieren.

Eigentlich fehlt mir hier nun nur noch ein PowerShell-Modul, welches all diese Aktionen per Commandlet bereitstellt. Allerdings ist ein "Invoke-RestMethod" auch nicht wirklich schwer zu programmieren.

Benachrichtigung

Über Ausfälle und Probleme will man als Administrator natürlich benachrichtig werden. PRTG stellt dazu von Hause aus schon sehr umfangreiche Möglichkeiten bereit. Wem das aber nicht reicht, kann auf zwei Wege eigene Aktionen einbinden:

  • EXE Aufruf
    Sie entwickeln ein Programm oder Skript, welches von PRTG mit entsprechenden Parametern aufgerufen werden kann und die von ihnen gewünschte Aktion ausführt
  • WebService
    Der PRTG-Service kann seinerseits eine hinterlegte URL mit entsprechenden Parametern aufrufen. So können Sie z.B. WebServices bei anderen Diensten oder Produkten nutzen.

Wenn ihre eigenes "Störungsmanagement" also keinen zu PRTG kompatiblen WebService bereitstellt, dann bauten Sie sich einfach eine PowerShell o.ä. die anstatt aufgerufen wird. Ich bin mal gespannt, ab wann ich die ersten Links finde, die ein Blaulicht im Serverraum anwerfen :-).

Weitere Links

PRTG API nutzen mit PowerSHELL | PowerSHELL 5.1 deutsch german
https://www.youtube.com/watch?v=_wml87ALbng