Wir nutzen Cookies, um Ihnen eine optimale Nutzung dieser Webseite zu ermöglichen. Mehr Informationen finden Sie im Datenschutzhinweis. Wir nehmen an, dass Sie damit einverstanden sind, falls Sie diese Webseite weiter besuchen.

Ihre Cookie-Einstellungen
Ihre Einstellungen wurden aktualisiert.
Damit die Änderungen wirksam werden, löschen Sie bitte Ihre Browser-Cookies und den Cache und laden dann die Seite neu.

Konfiguration via HTTP-API

1. Einleitung

Die Web-API ermöglicht Ihnen, Konfigurationsaufgaben, die Sie normalerweise manuell in der Weboberfläche von WATO durchführen, über HTTP-Aufrufe zu automatisieren. Zwar ist nicht die komplette Funktionalität von WATO via API verfügbar, doch die wichtigsten Dinge, wie die Verwaltung von Hosts, Ordnern, Instanzen, Benutzern, Gruppen und etlichem mehr ist möglich. Eine vollständige Liste aller API-Funktionen finden Sie hier.

Die meisten Anwender verwenden die Web-API zur Anbindung von bestehenden Configuration Management Databases (CMDB) oder zur Aufnahme von Hosts, die in einer dynamischen Umgebung automatisch entstehen.

Beim Lesen dieses Artikels sind grundlegende Kenntnisse in Python und dessen Datenstrukturen nötig. Natürlich ist der Artikel dennoch so einfach wie möglich geschrieben, um das Thema auch Einsteigern verständlich zu beschreiben.

Hinweis: Ab der Version 2.0 gibt es in Checkmk eine neue API, die REST-API, die die Web-API ablösen soll.

2. Grundlagen und Voraussetzungen

2.1. Der Automationsbenutzer

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 WATO ➳ 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.

2.2. Der Aufbau der URL

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:

Parameter Bedeutung
_username Der Anmeldename des Automationsbenutzers.
_secret Das Automatisierungspasswort.
action Legt fest, was durchgeführt werden soll.
request_format Die Syntax der request-Daten. Möglich sind python und json.
output_format Die Syntax der Antwort. Auch hier sind python und json möglich.
request Die zu übertragenden Daten, falls die action welche benötigt.

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:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_all_hosts&_username=automation&_secret=mysecret&request_format=python&output_format=python"
{'result': {'myserver123': {'attributes': {'ipaddress': '192.168.0.42'}, 'hostname': 'myserver123', 'path': ''}, 'myserver456': {'attributes': {'ipaddress': '192.168.0.73'}, 'hostname': 'myserver456', 'path': 'windows'}}, 'result_code': 0}

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:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_host&_username=automation&_secret=mysecret&request_format=python&output_format=python" -d 'request={'hostname':'myserver123'}'
{'result': {'myserver123': {'attributes': {'ipaddress': '192.168.0.42'}, 'hostname': 'myserver123', 'path': ''}}, 'result_code': 0}

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.

2.3. Datenformat der Eingabe und Antwort

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:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=get_host&_username=automation&_secret=myautomationsecret&output_format=python" -d 'request={"hostname":"myserver123"}'
{'result': {'myserver123': {'attributes': {'ipaddress': '192.168.0.42', 'management_snmp_community': ('authPriv', 'md5', 'myuser', 'mypassword', 'DES', 'myprivacypassword')}, 'hostname': 'myserver123', 'path': ''}}, 'result_code': 0}

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

  • Der Nullwert ist bei JSON null und bei Python None.
  • Tupel gibt es, wie bereits erwähnt, bei JSON nicht. Sie werden bei einigen Befehlen der API genutzt und unter JSON in einfache Listen umgewandelt. Wenn aber bei der Weiterverarbeitung eine Liste statt eines Tupels übergeben wird, ist die Datenintegrität in Checkmk nicht mehr gewährleistet und die Übergabe einer Konfiguration wird mit einer Fehlermeldung abgebrochen.
  • JSON akzeptiert ausschließlich doppelte Anführungszeichen, während bei Python lediglich die zusammenhängenden Anführungszeichen gleich sein müssen.
  • Boolsche Werte (True und False) werden unter Python groß und unter JSON klein geschrieben.

2.4. Die API lokal testen

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:

OMD[mysite]:~$ curl "http://localhost/$OMD_SITE/check_mk/webapi.py?action=get_all_hosts&_username=automation&_secret=$(cat $OMD_ROOT/var/check_mk/web/automation/automation.secret)"

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.

3. Befehle verwenden

3.1. Einleitung

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 auch im WATO von Checkmk:

  • Erstellen Sie einen Host.
  • Führen Sie eine Serviceerkennung auf dem Host durch.
  • Aktivieren Sie die Änderungen.

3.2. Einen Host erstellen

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:

{'hostname': 'myserver123',
 'folder': '',
 'attributes': {'ipaddress': '192.168.0.42',
                'site': 'mysite',
                'tag_agent': 'cmk-agent'}}

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:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=add_host&_username=automation&_secret=myautomationsecret" -d 'request={"hostname":"myserver123","folder":"","attributes":{"ipaddress":"192.168.0.42","site":"mysite","tag_agent":"cmk-agent"}}'

3.3. Eine Serviceerkennung durchführen

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:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?action=discover_services&_username=automation&_secret=myautomationsecret" -d 'request={"hostname":"myserver123"}'

3.4. Änderungen aktivieren

Zuletzt werden die Änderungen, wie im WATO auch, aktiviert:

root@linux# curl "http://myserver/mysite/check_mk/webapi.py?_secret=myautomationsecret&_username=automation&action=activate_changes" -d 'request={"sites":["mysite"]}'

4. Die API absichern

Da beim Zugriff über die Web-API sensible Daten übertragen und – je nach Berechtigung des Automationsbenutzers – umfassende Änderungen an Checkmk durchgeführt werden können, sollten Sie den Zugriff entsprechend absichern. Hier finden Sie einige der Möglichkeiten:

  • Checkmk über HTTPS: Nutzen Sie die API ausschließlich über das Hypertext Transfer Protocol Secure (HTTPS), da Benutzername, Passwort und auch Konfigurationsdaten sonst im Klartext im Netz übertragen werden.
  • Geben Sie dem Automationsbenutzer ein Passwort mit einer ausreichenden Länge. Da das Passwort in der Regel nur in einem Skript hinterlegt wird, können Sie problemlos ein sehr langes vergeben.
  • Achten Sie auf das Berechtigungskonzept zu den Skripten, mit denen Sie die Anfragen an die API stellen. In den Skripten können sensible Daten, wie Konfigurationsdaten, Passwörter usw. enthalten sein. Stellen Sie daher sicher, dass ausschließlich berechtigte Benutzer und Gruppen diese Skripten lesen können.

5. Fehlerbehandlung

5.1. Übersicht

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:

  • Der Automationsbenutzer hat die nötigen Berechtigungen, um Konfigurationsdaten zu lesen und zu setzen.
  • Die einzelnen Parameter wurden mit einem ? eingeleitet und mit einem & verknpüft. Beachten Sie auch, dass _username und _secret mit einem Unterstrich anfangen.
  • Die Syntax des request-Teils ist korrekt.

5.2. Berechtigungen

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.

5.3. Syntax in Befehlen

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:

~/home/myuser/pattern.txt
{"users": {"myuser": {"alias": "My User",
                      "email": "myuser@mycompany.org",
                      "language": None,
                      "pager": "01374-12233456",
                      "password": "mypassword"}}}

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

root@linux# python
>>> print {"users": {"myuser": {"alias": "My User",
...                       "email": "myuser@mycompany.org",
...                       "language": None,
...                       "pager": "01374-12233456",
...                       "password": "mypassword"}}}
{'users': {'myuser': {'alias': 'My User', 'password': 'mypassword', 'pager': '01374-12233456', 'email': 'myuser@mycompany.org', 'language': None}}}

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

OMD[mysite]:~$ curl "http://localhost/$OMD_SITE/check_mk/webapi.py?action=add_users&_username=automation&_secret=$(cat $OMD_ROOT/var/check_mk/web/automation/automation.secret)&output_format=python&request_format=python" -d "request={'users': {'myuser': {'alias': 'My User', 'password': 'mypassword', 'pager': '01374-12233456', 'email': 'myuser@mycompany.org', 'language': None}}}"
{'result': None, 'result_code': 0}

6. Dateien und Verzeichnisse

Pfad Bedeutung
etc/check_mk/conf.d/wato/ Alle hier angelegten Verzeichnisse stellen die im WATO sichtbaren Verzeichnisse dar.
etc/check_mk/conf.d/wato/.wato Attribute und Titel eines Verzeichnisses werden in dieser Datei festgelegt. Sie befindet sich in jedem Verzeichnis unterhalb von wato.
etc/check_mk/conf.d/wato/hosts.mk Hier wird die Konfiguration der Hosts festgelegt, welche dem entsprechenden Verzeichnis zugeordnet wurden. Auch diese Datei gibt es in jedem Verzeichnis unterhalb von wato.
etc/check_mk/conf.d/wato/group.mk Alle definierten Gruppen befinden sich hier. Dazu gehören Kontakt-, Service- und Hostgruppen. Diese Datei gibt es nur einmal.
etc/check_mk/multisite.d/wato/users.mk Benutzereinstellungen in Checkmk werden in dieser Datei definiert.
etc/check_mk/conf.d/wato/rules.mk In dieser Datei werden zu jedem Verzeichnis unterhalb von wato die definierten Regeln festgehalten.
etc/check_mk/multisite.d/wato/hosttags.mk Alle Hosttags und Auxiliarytags sind hier definiert.
etc/check_mk/multisite.d/sites.mk Hier werden alle Instanzen mit ihren Eigenschaften eingetragen. Auch die lokale Instanz wird hier festgehalten.
var/check_mk/agents/ Erstellte/gebackene Agenten werden hier abgelegt. Für jeden Host ist ein Link zu dem Agenten angelegt, welcher auf sein Installationspaket verweist.
var/check_mk/web/myuser/user_custom_graphs.mk Selbst erstellte Graphen werden bei dem jeweiligen Benutzer abgelegt. In dem Beispiel ist das der Benutzer „myuser“.