Konfiguration via HTTP-API

Um von einem Client aus die Web-API nutzen zu können, muss auf dem Checkmk-Server ein Automationsbenutzer eingerichtet sein. Nur dieser ist berechtigt, Aktionen über die API auszuführen.

Für die Authentifizierung benötigen Sie den Benutzernamen und das zugehörige sogenannte "automation secret for machine accounts", das heißt das Passwort des Automationsbenutzers. Beide Informationen müssen in jedem Kommando an den Checkmk-Server übermittelt werden.

Bei einer neu erstellten Instanz (site) ist der Benutzer automation bereits angelegt. Sie finden ihn, wie andere Benutzer auch, unter Setup > Users > Users. Achten Sie darauf, dass die Rollen und die damit verbundenen Berechtigungen für den Automationsbenutzer so gesetzt sind, dass Sie die Ausführung Ihrer Anfragen erlauben.

In diesem Artikel wird immer der standardmäßig eingerichtete Automationsbenutzer als Beispiel genommen.

Die folgenden Beispiele beziehen sich immer auf das Kommandozeilenprogramm curl, um die generelle Syntax der Aufrufe zu verdeutlichen. Sofern Sie andere Technologien nutzen, passen Sie die Aufrufe entsprechend an.

Zu der eigentlichen URL http://myserver/mysite/check_mk/webapi.py benötigen Sie noch verschiedene Parameter. Diese enthalten die Zugangsdaten für den Automationsbenutzer und die Information darüber, was getan werden soll. Falls sich der Aufruf auf ein bestimmtes Element in Checkmk beziehen soll, werden zusätzlich noch folgende Daten als payload übergeben:

Die ersten fünf Parameter können bei curl direkt in der URL übergeben werden. Sie werden mit einem ? eingeleitet und mit einem & verknüpft. Die Reihenfolge ist dabei egal:

In der Antwort bekommen Sie zum einen den result_code, welcher angibt, ob ein Fehler bei der Abfrage aufgetreten ist. War die Abfrage erfolgreich, bekommen sie den Wert 0 zurück, bei einem Fehler den Wert 1. Zum anderen gibt es das Resultat (result) selbst, in dem die Antwort der Instanz steht. Diese Antwort kann eine Fehlermeldung sein, wenn die Abfrage fehlgeschlagen ist, oder die gewünschten Daten enthalten, wenn die Abfrage erfolgreich war. Haben Sie ein Kommando an den Checkmk-Server geleitet, so bleibt das result-Feld unter Umständen leer beziehungsweise gibt den Wert None zurück.

Manche Befehle benötigen den Parameter request. Dieser enthält die benötigten Daten, um z.B. die Konfiguration eines bestimmten Hosts abzurufen. Um diese Daten zu übergeben, wird bei der Schalter -d benutzt:

Wichtig: In den folgenden Beispielen und der Befehlsreferenz werden Eingabe und Antwort oft noch einmal über mehrere Zeilen dargestellt, um Lesbarkeit und Übersicht zu verbessern. In der Praxis wird es sowohl in der Eingabe als auch in der Antwort keine Zeilenumbrüche geben.

Die API kennt zwei Parameter, um das Datenformat der Eingabe oder Antwort festzulegen. Mit request_format wird das Eingabeformat bestimmt, während output_format das Format der Antwort festlegt. Werden diese Parameter nicht benutzt, so nimmt die API an, dass es sich bei den Formaten um JSON handelt.

Die Unterstützung von JSON ist in Checkmk inzwischen aber generell experimentell/veraltet. Auch wenn es bei der Verwendung von JSON bei vielen Befehlen keine Fehlermeldung gibt, sollten Sie das Eingabe- und Antwortformat immer auf Python setzen. Nachfolgend ein praktisches Beispiel, in dem z.B. Tupel in der Antwort verwendet werden:

JSON und Python haben aber noch weitere Unterschiede in ihren Datenformaten. Diese sind:

Um Befehle der Web-API direkt vom Checkmk-Server aus zu testen, bietet es sich an, als Instanzbenutzer zu arbeiten. Sie können dann auf lokale Variablen zurückgreifen und auch das Passwort des Automationsbenutzers direkt auslesen. In dem folgenden Beispiel werden die Variablen $OMD_SITE und $OMD_ROOT benutzt, welche auf den Namen der Instanz und ihr Homeverzeichnis verweisen. Das Passwort wird dann mittels cat direkt ausgelesen:

Sofern der Benutzer automation vorhanden ist, wird dieser Aufruf auf jeder Instanz funktionieren. Sie können das Beispiel einfach kopieren und bei sich ausprobieren. Das funktioniert natürlich nur, wenn der Befehl auf dem Checkmk-Server als Instanzbenutzer ausgeführt wird.

Checkmk verfügt über einige Befehle, um die Konfiguration von Hosts, Regeln und vielem mehr zu steuern. Schauen Sie in die Befehlsreferenz, um eine Beschreibung zu allen Befehlen zu erhalten.

Den Umgang mit der API zeigt ein einfaches Beispiel: Sie erstellen einen Host mit seinen Services über die Web-API mit nur drei Befehlen. Prinzipiell gehen Sie dabei genauso vor, wie im Checkmk Setup:

Mit dem Befehl add_host können Sie einen Host in Checkmk erstellen. Sie geben dabei mindestens den Hostnamen und das Verzeichnis, in dem er abgelegt werden soll, an. Zusätzlich können Sie auch die verfügbaren Attribute, wie z.B. die IP-Adresse eines Hosts, explizit setzen. Der request-Teil sieht dann z.B. so aus:

In dem Beispiel wird der Host myserver123 im Hauptverzeichnis angelegt. Diesem wird dabei eine IP-Adresse zugewiesen und weiter definiert, dass es sich hierbei um einen Host handelt, welcher seine Daten über einen Checkmk-Agenten bekommt und der Instanz mysite zugeordnet ist. Zum Testen auf der Kommandozeile kann man den Host nun folgendermaßen anlegen — tauschen Sie die Platzhalter entsprechend durch Ihre echten Daten aus:

Nachdem der Host erstellt wurde, können die Services hinzugefügt werden. Hier geben Sie den Hostnamen an und bestimmen bei Bedarf die Art der Serviceerkennung. Wenn Sie nichts angeben, werden lediglich die neu erkannten Services hinzugefügt:

Zuletzt werden die Änderungen, wie im Checkmk Setup auch, aktiviert:

Wie bereits weiter oben beschrieben, gibt die Anfrage einen Fehlercode zurück, wenn sie nicht erfolgreich war. Dieser ist in dem result_code hinterlegt. Eine Beschreibung des Fehlers ist dann in dem result selbst enthalten. Sie ist ein guter ein Einstieg in die Analyse des Problems.

Prüfen Sie zusätzlich, ob die folgenden Bedingungen erfüllt sind:

Wie bereits erwähnt, ist die Berechtigung des Automationsbenutzers eine Fehlerquelle, wenn z.B. Konfigurationsdaten abgerufen werden sollen. Der von Checkmk mitgelieferte Benutzer automation hat die Rolle Administrator und darf somit alles sehen und bearbeiten. Da Sie dem Automationsbenutzer aber prinzipiell jede verfügbare Rolle zuweisen können, müssen gegebenenfalls auch die Kontaktgruppen angepasst werden, um bestimmte Hosts abrufen oder bearbeiten zu können. Prüfen Sie im Fehlerfall, ob diese Berechtigungen für den entsprechenden Automationsbenutzer passen.

Beim Testen mit curl wird es in dem request-Teil schnell unübersichtlich. Prüfen Sie daher immer (auch, wenn Sie nicht curl verwenden), ob die Syntax korrekt ist.

Eine gute Methode kann es sein, sich den request-Teil in eine Datei zu schreiben und damit zu visualisieren:

Sie können diese Zeilen auch in einen Python-Prompt kopieren und mit dem Befehl print in einer Zeile ausgeben lassen:

Die Leerzeichen können Sie in dem curl-Befehl übrigens behalten: