Konfiguration via Checkmk REST-API

1. Einleitung

Seit der Version 2.0.0 gibt es in Checkmk eine neue Anwendungsprogrammierschnittstelle: die Checkmk REST-API. Mit dieser API können Sie die Aufgaben, die Sie sonst in Checkmk über die GUI erledigen, per Kommando oder Skript mit HTTP-Anfragen an den Checkmk-Server übermitteln und ausführen lassen.

Eine API per HTTP nutzen? Das kommt Ihnen vielleicht bekannt vor. Denn Checkmk bietet schon seit längerem eine API, die sogenannte Web-API, mit der Sie viele Administrationsaufgaben erledigen können. Warum gibt es also jetzt eine neue API? Anders als der Name REST-API vielleicht vermuten lässt, geht es nicht darum, mit der neuen API den Rest der in der Web-API fehlenden Funktionen zu liefern. Ganz im Gegenteil soll die REST-API die komplette Funktionalität abdecken, die Checkmk über die GUI und über Kommandoschnittstelle bietet und damit die Web-API komplett ersetzen.

REST steht für REpresentational State Transfer und beschreibt eine Architektur für den Austausch von Daten auf verteilten Systemen — insbesondere für Web-Dienste. Eine API, die gemäß der REST-Architektur implementiert ist, folgt bestimmten Prinzipien, z.B. dem Client-Server-Modell, der zustandslosen Kommunikation und einer einheitlichen Schnittstelle. In der Praxis erfolgt die Umsetzung bevorzugt über das HTTP-Protokoll, wobei die Ressourcen per Uniform Resource Identifier (URI) angesprochen werden und auf diese mit HTTP-Methoden (GET, POST, PUT, DELETE) zugegriffen wird.

Soviel zu den REST-Prinzipien. Ihre Vorteile zeigen sich in den konkreten Features, die Ihnen die Checkmk REST-API bietet:

Protokoll	Das Hypertext Transfer Protocol (HTTP/1.1) wird als Transportsystem für die Kommunikation genutzt.
Kodierung	Als Datenformat wird die JavaScript Object Notation (JSON) verwendet. Die Nutzdaten (payload) der Antworten werden mit JSON serialisiert und in UTF-8 kodiert. Datums- und Zeitangaben sind im ISO-8601-Format mit gültigen Zeitzoneninformationen kodiert.
Sprache	Englisch ist die Sprache für Labels, Identifiers und die API-Dokumentation.
Authentifizierung	Der Zugriff auf die API wird einem Client nur dann gestattet, wenn er die Berechtigung mittels HTTP-Authentifizierung (z.B. „Bearer“ oder „Basic“) nachgewiesen hat.
Versionierung	Die API ist versioniert und nutzt dabei eine dreistufige Nummerierung nach dem Semantic Versioning 2.x Standard. Details finden Sie im Kapitel zur Versionierung weiter unten.
Dokumentation	Die API wird in einem maschinenlesbaren Schema und einem menschenlesbaren Format in englischer Sprache dokumentiert, mit allen Ressourcen, ihren Eingabe- und Ausgabeparametern und den zugehörigen Wertebereichen. Die API ist mit der OpenAPI Spezifikation (OAS) 3.x erstellt, einem API-Beschreibungsformat speziell für REST-APIs. Das mit dieser Spezifikation erstellte API-Dokument wird für den Benutzer mit ReDoc angezeigt, einem responsiven Web-Design für OpenAPI-Dokumente.
Beispiel-Code	Um die Verwendung zu demonstrieren, gibt es zu jeder Anfrage Beispiel-Code für verschiedene Anwendungen.
Fehleranzeige	Die API sendet im Fehlerfall numerische HTTP-Status-Codes und eine Diagnosemeldung des Problems, die bei der Suche nach möglichen Ursachen für fehlerhafte Anfragen hilft.
REST-API Klassifizierung	Die API erfüllt alle vier Ebenen (0 bis 3) des Richardson Maturity Model (RMM), mit dem beurteilt werden kann, wieviel REST in einer API steckt. In Ebene 1 wird die Einführung von Ressourcen gefordert, damit über die API statt zu einem globalen zu individuellen Endpunkten kommuniziert werden kann. Ebene 2 wird erfüllt, wenn für die Anfragen HTTP-Methoden verwendet werden. Auf der (höchsten) Ebene 3 dokumentiert sich die API quasi selbst, indem der Server mit der Antwort auf eine Anfrage die nächsten möglichen Aktionen und die dabei anzusprechenden Ressourcen mitteilt, und es dem Client so ermöglicht, die verfügbare Funktionalität selbst zu entdecken. Diese Bereitstellung von Zusatzinformationen wird auch „Hypermedia as the Engine of Application State“ (HATEOAS) genannt.

Neben diesen generellen Komfortfunktionen bietet die Checkmk REST-API bereits jetzt Zugriff zu mehr Bereichen in Checkmk als die Web-API, z.B. zu Host-Status, Service-Status, Zeitperioden, Quittierung von Problemen und der Business Intelligence (BI). Für viele Bereiche, die beide APIs unterstützen, haben Sie per REST-API zudem mehr und spezifischere Möglichkeiten.

Allerdings gibt es in der Web-API einige wenige Funktionen, die der REST-API zurzeit noch fehlen. Solange das so ist, finden Sie im letzten Kapitel eine Gegenüberstellung der Funktionalität von REST-API und Web-API. Die letzten, in der REST-API noch fehlenden Funktionen zum Zugriff auf Instanzen im verteilten Monitoring und auf Metriken und Graphen werden in Checkmk 2.1.0 Patch-Versionen nachgeliefert.

2. Die API-Dokumentation

2.1. Versionierung

Einer der Vorteile der REST-API ist, dass Software und Dokumentation aus der gleichen Quelle stammen: dem OpenAPI-Dokument. Daher passt die API-Dokumentation stets zur Software und beschreibt genau das, was die API kann. Daher ist es auch nicht nötig, den Referenzteil der verfügbaren Ressourcen, Methoden, Parameter etc. im Checkmk-Handbuch zu beschreiben: stattdessen finden Sie die API-Dokumentation außerhalb dieses Handbuchs, direkt in Ihrer Checkmk-Instanz.

Die API mit ihrer Dokumentation ist versioniert und nutzt dabei eine dreistufige Nummerierung im Format X.Y.Z, wobei X für ein Main Release steht, Y für ein Minor Release und Z für einen Patch. Ein neues Minor Release enthält neue, rückwärtskompatible Funktionen. Ein neues Main Release kann dagegen Änderungen enthalten, die die API inkompatibel mit dem vorherigen Main Release machen (sogenannte breaking changes). Die Versionsnummern der Main and Minor Releases sind Bestandteil der URL, mit dem eine Anfrage an den Server gesendet wird.

Wichtig: Beachten Sie, dass die REST-API einer anderen Versionierung folgt als die Checkmk-Software. Da ein neues Main Release der API dann notwendig ist, wenn es inkompatible API-Änderungen gibt, passt das in der Regel nicht zum Release-Zyklus der Checkmk-Software.

Trotzdem ist die Zuordnung der Versionen von API-Dokumentation und Checkmk-Software sehr einfach, wie Sie im nächsten Kapitel erfahren.

2.2. Zugriff

Die REST-API-Dokumentation steht im HTML-Format zur Ansicht im Web-Browser bereit.

In der Checkmk-GUI öffnen Sie die API-Dokumentation über die Navigationsleiste mit Help > Developer resources APIs > REST API documentation. Die API-Dokumentation wird in einem neuen Browser-Fenster (bzw. Browser-Tab) angezeigt. Wir gehen darauf im nächsten Kapitel genauer ein.

Hinweis: Sicher ist Ihnen aufgefallen, das es im Help-Menü noch weitere Einträge zur REST-API gibt. Mit REST API introduction können Sie diesen Artikel öffnen. Mit REST API interactive GUI öffnen Sie eine weitere Sicht auf die REST-API. GUI heißt dieser Eintrag, weil Ihnen nicht nur die REST-API-Funktionen angezeigt werden, sondern weil Sie aus dem Browser heraus direkt mit der API interagieren können, indem Sie z.B. Anfragen an den Server senden Wir stellen die REST-API GUI als Alternative zur Ausführung per Skript im Kapitel zur REST-API GUI später vor.

2.3. Struktur und Inhalt

Die API-Dokumentation nutzt ein responsives Web-Design mit 3 Bereichen:

API-Dokumentation im responsiven Web-Design mit drei Bereichen.

Der linke Navigationsbereich dient der Orientierung, der Suche und dem schnellen Sprung zur genauen Beschreibung der Einträge im mittleren Bereich. Das Inhaltsverzeichnis enthält für jeden API-Endpunkt einen Eintrag. Ein Endpunkt bezeichnet per URL die Ressource, die die API zur Verfügung stellt (z.B. Hosts), zusammen mit der Methode, um auf die Ressource zuzugreifen (z.B. GET zur Anzeige eines Hosts). Die Endpunkte sind in mehrere Ordner organisiert.
Der mittlere Inhaltsbereich enthält die harten Fakten der Dokumentation: alle Informationen zur Definition einer Anfrage (mit Parametern, Wertebereichen, Default-Werten und Beschreibungen) und die zugehörigen Antworten (ebenfalls mit allen Details). Die möglichen Antworten werden in unterschiedlichen Farben dargestellt, je nachdem ob der zurückgelieferte HTTP-Status-Code Erfolg oder einen Fehler signalisiert.
Der rechte Beispielbereich (Request samples) zeigt für den im Inhaltsbereich ausgewählten Endpunkt die Methode und die URL, gefolgt von mehreren Beispielen zu Anfragen: die Payload im JSON-Format (falls relevant für den Endpunkt) und Code-Beispiele z.B. für cURL, HTTPie, Python Requests und Python Urllib. Dann folgen die Antworten passend zum HTTP-Status. Alle Code-Beispiele können über den Knopf Copy in die Zwischenablage kopiert werden.

Der Navigationsbereich ist scroll-synchronisiert zu den anderen beiden Bereichen, das heißt, wenn Sie im Inhaltsbereich nach oben oder unten scrollen, scrollt der Navigationsbereich automatisch zum passenden Eintrag des Inhaltsverzeichnisses mit.

Das responsive Web-Design sorgt dafür, dass in einem Browser-Fenster mit geringer Breite der Beispielbereich verschwindet (dafür werden dann die Beispiele unterhalb der zugehörigen Methode angezeigt) und der Navigationsbereich in ein Menü umgewandelt wird.

In allen Bereichen finden Sie Inhalte, die Sie ein- und ausblenden können, zum Beispiel im Navigationsbereich die Einträge für die Endpunkte und im Inhaltsbereich verschachtelte Parameter. Durch Anklicken von > oder Expand all blenden Sie die verborgenen Inhalte ein und mit ∨ oder Collapse all wieder aus.

Wie Sie die API-Dokumentation nutzen können, um aus den Informationen konkrete Anfragen zu erstellen, an den Checkmk-Server zu senden, ausführen zu lassen und den Erfolg zu kontrollieren: all das erfahren Sie im nächsten Kapitel.

3. Die API nutzen

3.1. Authentifizierung

Um von einem Client aus die REST-API des Checkmk-Servers nutzen zu können, muss der Client seine Identität nachweisen. Die REST-API unterstützt die folgenden Methoden zur Authentifizierung: Bearer, Webserver und Cookie — in dieser Rangfolge. Das heißt zum Beispiel, dass bei einer erfolgreichen Authentifizierung mit Bearer keine der anderen Methoden mehr geprüft wird.

Bearer- oder Header-Authentifizierung

„Bearer“ bezeichnet den Träger oder Inhaber einer Identität. Der Client authentisiert sich mit den Zugangsdaten eines auf dem Checkmk-Server eingerichteten Benutzers. Idealerweise ist dies der sogenannte Automationsbenutzer, der in Checkmk für die Ausführung von Aktionen über eine API vorgesehen ist. Die Bearer-Authentifizierung wird für die Verwendung in Skripten empfohlen.

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 im Header jeder Anfrage an den Checkmk-Server übermittelt werden. Bei einer neu erstellten Instanz 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.

Für die in diesem Artikel vorgestellten Skripten wird immer der standardmäßig eingerichtete Automationsbenutzer als Beispiel genommen.

Webserver-Authentifizierung

Bei der Webserver-Authentifizierung nutzt die REST-API die HTTP-Authentifizierung, die für den Webserver konfiguriert ist („Basic“ oder „Digest“).

Diese Authentifizierungmethode ist gedacht für große Checkmk-Installationen mit speziellen Anforderungen, die durch den Einsatz und die Konfiguration von Software-Modulen für die Authentifizierung des Apache Webservers realisiert werden. Wenn Sie die die Webserver-Authentifizierung nutzen möchten, müssen Sie den Apache Webserver der Checkmk-Instanz selbst neu konfigurieren.

Cookie-Authentifizierung

Die Cookie-Authentifizierung ist ein Spezialfall der Authentifizierung per API-Schlüssel. Jeder Checkmk-Benutzer, der in Checkmk angemeldet ist und dadurch ein HTTP Cookie zugewiesen bekommen hat, kann die REST-API nutzen. Die Cookie-Authentifizierung dient zum Ausprobieren und Testen mit der REST-API GUI. Ob Anfragen ausgeführt werden können, hängt davon ab, ob Ihr Checkmk-Benutzerkonto die entsprechenden Berechtigungen besitzt.

3.2. Die API lokal testen

Um die REST-API zu testen, bietet es sich an, die Anfragen direkt vom Checkmk-Server aus zu stellen, das heißt, in diesem Fall befinden sich Client und Server auf dem gleichen Rechner. Wenn Sie als Instanzbenutzer arbeiten, können Sie zudem lokale Variablen wie z.B. $OMD_SITE verwenden, die auf den Namen der Instanz verweist.

In den folgenden Beispielen nutzen wir den in der API-Dokumentation enthaltenen Beispiel-Code für das Kommandozeilenprogramms cURL, das es ermöglicht, ohne Benutzerinteraktion Daten von oder zu einem Server zum Beispiel per HTTP zu übertragen. Das curl-Kommando wird innerhalb eines Bash-Skripts ausgeführt.

Zur Vorbereitung erstellen Sie eine Skript-Datei, in die später der Beispiel-Code kopiert wird:

OMD[mysite]:~$ touch rest-api_test.sh
OMD[mysite]:~$ chmod +x rest-api_test.sh

Die REST-API gibt alle Antworten im JSON-Format einzeilig aus. Da eine formatierte Ausgabe die Lesbarkeit doch erheblich erleichtert, ist im cURL-Beispiel-Code die formatierte Ausgabe mit Hilfe des Kommandozeilen-JSON-Prozessor jq vorgesehen. Sie können mit dem folgenden Kommando überprüfen, ob jq installiert ist:

OMD[mysite]:~$ jq --version
jq-1.6

und — falls nicht — die Software von stedolan.github.io/jq/download/ installieren. Falls Sie jq nicht nutzen wollen, müssen Sie mit der unformatierten Ausgabe zurechtkommen.

Bevor es los geht, sammeln Sie einige grundlegenden Informationen, die spezifisch für Ihre Checkmk-Konfiguration sind:

Variable Beispielwert Bedeutung

Variable	Beispielwert	Bedeutung
`HOST_NAME`	`myserver`	Name des Checkmk-Servers
`SITE_NAME`	`mysite`	Name der Checkmk-Instanz
`USERNAME`	`automation`	Name des Automationsbenutzers
`PASSWORD`	`theautomationsecret`	Passwort des Automationsbenutzers

HOST_NAME

myserver

Name des Checkmk-Servers

SITE_NAME

mysite

Name der Checkmk-Instanz

USERNAME

automation

Name des Automationsbenutzers

PASSWORD

theautomationsecret

Passwort des Automationsbenutzers

Diese Variablen werden im Beispiel-Code verwendet und müssen von Ihnen geändert werden, bevor Sie eine Anfrage absenden. In der obigen Tabelle finden Sie auch die Beispielwerte, die im folgenden verwendet werden.

3.3. Anfragen stellen per Skript

Wir werden nun den Umgang mit der REST-API an einem übersichtlichen Beispiel demonstrieren: Sie erstellen einen Host mit seinen Services mit insgesamt drei Anfragen. Prinzipiell gehen Sie dabei genauso vor, wie Sie es auch mit der Checkmk-GUI tun würden:

Einen Host erstellen
Eine Service-Erkennung auf dem Host durchführen
Die Änderungen aktivieren

Einen Host erstellen

Öffnen Sie die API-Dokumentation und suchen Sie im linken Navigationsbereich den Eintrag zum Erstellen eines Hosts (Create a host):

Der Eintrag in der API-Dokumentation zum Erstellen eines Hosts.

Im mittleren Bereich sehen Sie die Details zur gewählten Anfrage: welche HTTP-Authentifizierung gefordert ist (diese ist identisch für alle Anfragen über die REST-API) und die notwendigen und optionalen Parameter. Notwendig (required) ist der Name des Hosts und der Ordner, in dem er angelegt werden soll. Standardmäßig wird der Host im Hauptordner (Main) angelegt. Falls Sie den Host in einem anderen Ordner anlegen wollen, müssen Sie sich eventuell zuerst über eine andere API-Anfrage (Show all folders) die existierenden Ordner anzeigen lassen, um die ID des gewünschten herauszufinden.

In unserem Beispiel wollen wir den Host myhost123 mit der IP-Adresse 192.168.0.42 im Hauptordner erstellen.

In der API-Dokumentation klicken Sie im rechten Beispielbereich auf den Knopf curl und dann auf Copy um den cURL-Beispiel-Code in die Zwischenablage zu kopieren. Öffnen Sie das vorbereitete Skript rest-api_test.sh und fügen Sie den Inhalt der Zwischenablage ein:

rest-api_test.sh

#!/bin/bash

HOST_NAME="localhost"
SITE_NAME="mysite"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

USERNAME="automation"
PASSWORD="test123"

out=$(
  curl \
    --request POST \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '{
          "attributes": {
            "ipaddress": "192.168.0.123"
          },
          "folder": "/",
          "host_name": "example.com"
        }' \
    "$API_URL/domain-types/host_config/collections/all")

resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')

# For indentation, please install 'jq' (JSON query tool)
echo "$resp" | jq
# echo "$resp"

if [[ $code -lt 400 ]]; then
    echo "OK"
    exit 0
else
    echo "Request error"
    exit 1
fi

Im ersten Teil des Beispiel-Codes finden Sie die Umgebungsvariablen, dann folgt das curl-Kommando mit der POST-Methode auf die Ressource, deren URL in der letzten Zeile steht. In der POST-Methode finden Sie nach den Header-Zeilen (eine davon definiert die HTTP-Authentifizierung) den Datenteil, in dem die Parameter für den neuen Host festgelegt werden. Die restlichen Zeilen dienen der Aufbereitung der Ausgabe.

Beachten Sie, dass der cURL-Beispiel-Code mehr Parameter enthalten kann, als Sie im konkreten Fall vielleicht benötigen. Für unser Beispiel ist dies aber nicht der Fall, und Sie müssen nur die beiden vorhandenen Parameter host_name und ipaddress ändern.

Passen Sie nun den Beispiel-Code an, so dass das Resultat ungefähr so aussieht:

rest-api_test.sh

#!/bin/bash

HOST_NAME="myserver"
SITE_NAME="mysite"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

USERNAME="automation"
PASSWORD="theautomationsecret"

out=$(
  curl \
    --request POST \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '{
          "attributes": {
            "ipaddress": "192.168.0.42"
          },
          "folder": "/",
          "host_name": "myhost123"
        }' \
    "$API_URL/domain-types/host_config/collections/all")

resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')

# For indentation, please install 'jq' (JSON query tool)
echo "$resp" | jq
# echo "$resp"

if [[ $code -lt 400 ]]; then
    echo "OK"
    exit 0
else
    echo "Request error"
    exit 1
fi

Falls der Kommandozeilen-JSON-Prozessor jq nicht installiert ist, müssen Sie im obigen Beispiel-Code die Zeile mit jq auskommentieren und die darauf folgende Zeile einkommentieren. Das Ergebnis sieht dann so aus:

rest-api_test.sh

# echo "$resp" | jq
echo "$resp"

Führen Sie das Skript aus:

OMD[mysite]:~$ ./rest-api_test.sh
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  3471  100  3319  100   152  14430    660 --:--:-- --:--:-- --:--:-- 15091
{
  "links": [
    {
      "domainType": "link",
      "rel": "self",
      "href": "http://myserver/mysite/check_mk/api/1.0/objects/host_config/myhost123",
      "method": "GET",
      "type": "application/json"
    },
    {
      "domainType": "link",
      "rel": "urn:org.restfulobjects:rels/update",
      "href": "http://myserver/mysite/check_mk/api/1.0/objects/host_config/myhost123",
      "method": "PUT",
      "type": "application/json"
    },
[...]
    {
      "domainType": "link",
      "rel": "urn:com.checkmk:rels/download",
      "href": "http://myserver/mysite/check_mk/api/1.0/domain-types/agent/actions/download/invoke?os_type=windows_msi&host_name=myhost123",
      "method": "GET",
      "type": "application/json",
      "title": "Download the windows_msi agent of the host."
    }
  ],
  "domainType": "host_config",
  "id": "myhost123",
  "title": "myhost123",
  "members": {},
  "extensions": {
    "folder": "/",
    "attributes": {
      "ipaddress": "192.168.0.42",
      "meta_data": {
        "created_at": "2022-07-20T15:06:01.316714+00:00",
        "updated_at": "2022-07-20T15:06:01.406772+00:00",
        "created_by": "automation"
      }
    },
    "effective_attributes": null,
    "is_cluster": false,
    "is_offline": false,
    "cluster_nodes": null
  }
}
OK

In der Antwort enthalten die ersten 3 Zeilen Informationen über die Datenübertragung. Dann liefert die API unter links eine Auswahl von (im obigen Beispiel stark gekürzten) Anfragen zurück, die auf den gerade erstellten Host angewendet werden können — wie es sich für eine REST-API gehört. Abschließend liefert die API ID und Namen (title) des erstellten Hosts, unter folder den Ordner (/ für den Hauptordner) und unter attributes die dem Host zugewiesenen Attribute inklusive der IP-Adresse.

Eine Service-Erkennung auf dem Host durchführen

Nachdem der Host myhost123 erstellt wurde, können die Services ermittelt werden. Wählen Sie dazu in der API-Dokumentation den Eintrag zur Ausführung einer Service-Erkennung aus (Execute a service discovery on a host), kopieren Sie den Beispiel-Code in das Skript und passen Sie es an Ihre Konfiguration an.

Den ersten Teil mit den Umgebungsvariablen können Sie 1:1 aus dem vorherigen Beispiel übernehmen. Im curl-Kommando ändern Sie den Namen des Hosts zu myhost123 und bei Bedarf mit dem Parameter mode die Art der Service-Erkennung.

rest-api_test.sh

#!/bin/bash

HOST_NAME="myserver"
SITE_NAME="mysite"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

USERNAME="automation"
PASSWORD="theautomationsecret"

out=$(
  curl \
    --request POST \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '{
          "host_name": "myhost123",
          "mode": "refresh"
        }' \
    "$API_URL/domain-types/service_discovery_run/actions/start/invoke")

resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')

# For indentation, please install 'jq' (JSON query tool)
echo "$resp" | jq
# echo "$resp"

if [[ $code -lt 400 ]]; then
    echo "OK"
    exit 0
else
    echo "Request error"
    exit 1
fi

Führen Sie auch dieses Skript aus:

OMD[mysite]:~$ ./rest-api_test.sh
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    75    0     0  100    75      0    937 --:--:-- --:--:-- --:--:--   937
OK

Der Erfolg wird am Ende der Ausgabe kurz und bündig mit OK gemeldet.

Die Änderungen aktivieren

Zum Abschluss müssen die Änderungen aktiviert werden. Die passende Anfrage heißt Activate pending changes.

Wie zuvor übernehmen Sie den ersten Teil mit den Umgebungsvariablen aus den vorherigen Beispielen. Ändern Sie im Datenteil des curl-Kommandos den Parameter sites und setzen ihn auf den Namen der Instanz - dort, wo die Änderungen aktiviert werden sollen:

rest-api_test.sh

#!/bin/bash

HOST_NAME="myserver"
SITE_NAME="mysite"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"

USERNAME="automation"
PASSWORD="theautomationsecret"

out=$(
  curl \
    --request POST \
    --write-out "\nxxx-status_code=%{http_code}\n" \
    --header "Authorization: Bearer $USERNAME $PASSWORD" \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '{
          "force_foreign_changes": false,
          "redirect": false,
          "sites": [
            "mysite"
          ]
        }' \
    "$API_URL/domain-types/activation_run/actions/activate-changes/invoke")

resp=$( echo "${out}" | grep -v "xxx-status_code" )
code=$( echo "${out}" | awk -F"=" '/^xxx-status_code/ {print $2}')

# For indentation, please install 'jq' (JSON query tool)
echo "$resp" | jq
# echo "$resp"

if [[ $code -lt 400 ]]; then
    echo "OK"
    exit 0
else
    echo "Request error"
    exit 1
fi

Führen Sie das Skript aus:

OMD[mysite]:~$ ./rest-api_test.sh
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   796  100   660  100   136   2784    573 --:--:-- --:--:-- --:--:--  3358
{
  "links": [
    {
      "domainType": "link",
      "rel": "self",
      "href": "http://myserver/mysite/check_mk/api/1.0/objects/activation_run/919c5dd4-727d-4c08-84d5-25f70ec233ac",
      "method": "GET",
      "type": "application/json"
    },
    {
      "domainType": "link",
      "rel": "urn:com.checkmk:rels/wait-for-completion",
      "href": "http://myserver/mysite/check_mk/api/1.0/objects/activation_run/919c5dd4-727d-4c08-84d5-25f70ec233ac/actions/wait-for-completion/invoke",
      "method": "GET",
      "type": "application/json"
    }
  ],
  "domainType": "activation_run",
  "id": "919c5dd4-727d-4c08-84d5-25f70ec233ac",
  "title": "Activation 919c5dd4-727d-4c08-84d5-25f70ec233ac was started.",
  "members": {},
  "extensions": {}
}
OK

Der Text im title zeigt, dass die Aktivierung gestartet wurde. Wieder schlägt die REST-API unter links zwei sinnvolle Folgeanfragen vor: um den Status dieser Aktivierung abzufragen und auf deren Abschluss zu warten.

3.4. Anfragen stellen per REST-API GUI

Mit der REST-API GUI erhalten Sie eine neue Perspektive auf die API: Sie können mit dieser GUI aus dem Browser heraus direkt mit der API interagieren, indem Sie Anfragen per cURL-Kommando an den Server senden und postwendend die Antworten sehen. Dafür müssen Sie in der API GUI auf die Code-Beispiele der REST-API-Dokumentation verzichten: beide Sichten sind eben für ihren Anwendungszweck optimiert.

Die REST-API GUI wird aus der gleichen Quelle wie die REST-API-Dokumentation generiert — dem OpenAPI-Dokument — und bietet daher stets die zur API passenden Funktionen an.

Sie öffnen die API GUI in der Checkmk-GUI über die Navigationsleiste im Menü Help > Developer resources > REST API interactive GUI. Die API GUI wird in einem neuen Browser-Fenster (bzw. Browser-Tab) angezeigt:

Der Eintrag in der REST API GUI zum Erstellen eines Hosts.

Im folgenden skizzieren wir, wie Sie die erste Anfrage aus dem obigen Beispiel (einen Host erstellen) statt per Skript auch mit der REST-API GUI ausführen können:

Authentisieren: Die REST-API GUI bietet nach dem Anklicken des Knopfs Authorize (auf der rechten Seite über dem Eintrag des ersten Endpunkt-Ordners) eine Dialogbox zur Eingabe der Authentifizierungsinformationen. Sie brauchen dort aber keine Eingaben zu machen, da Sie als angemeldeter Checkmk-Benutzer per Cookie-Authentifizierung berechtigt zur Nutzung der REST-API sind.
Endpunkt auswählen: Wählen Sie im Ordner Hosts den Endpunkt Create a host aus und klicken Sie Try it out.
Parameterwerte eingeben: Überschreiben Sie im Request body die Beispielwerte für host_name und ipaddress.
Anfrage senden: Klicken Sie Execute.
Antwort überprüfen: Unter Responses sehen Sie zunächst das gesendete cURL-Kommando und die URL des Endpunkts. Anschließend wird unter Server response die Antwort angezeigt mit HTTP-Status-Code und in Responses die (mehrzeilig formatierte) REST-API Antwort.

Die REST-API GUI bietet Ihnen also die Möglichkeit, schnell und unkompliziert die Funktionen der API auszuprobieren und sich mit den Details der Eingabewerte und mit konkreten Antworten vertraut zu machen.

3.5. Fehler korrigieren

Im Gegensatz zu den bisher gezeigten Ausgaben bei erfolgreichen Kommandos per Skript, zeigt Ihnen die REST-API Fehler in der folgenden Art an:

{
  "title": "The operation has failed.",
  "status": 401,
  "detail": "There are changes from other users and foreign changes are not allowed in this API call."
}
Request error

Je nach Fehler können die in der Ausgabe angezeigten Parameter unterschiedlich sein. Immer erhalten sie aber in status den HTTP-Status-Code und in title eine Kurzbeschreibung der Fehlerursache.

In den meisten Fällen zeigt Ihnen detail, wie der Name schon vermuten lässt, detaillierte Informationen an. Im obigen Beispiel erfahren Sie, dass es zwar ausstehende Änderungen in Checkmk gibt, die aber von einem anderen Benutzer veranlasst wurden. Über die API können standardmäßig nur Änderungen aktiviert werden, die auch über die API durchgeführt wurden.

Auch im nächsten Beispiel stecken die hilfreichen in den detaillierten Informationen:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "400 Bad Request: Failed to decode JSON object: Invalid \\escape: line 6 column 31 (char 136)"
}
Request error

Hier liegt das Problem darin, dass ein Parameterwert sich nicht an den gültigen Wertebereich hält (wegen eines Schrägstrichs im Host-Namen).

Die Anzahl der möglichen Fehler ist natürlich sehr viel länger als die beiden, die wir vorgestellt haben. An den gezeigten Beispielen sehen Sie aber, dass die REST-API in der Ausgabe meist genügend Informationen über die Ursache liefert und Ihnen so Anhaltspunkte für den Einstieg in die Analyse und die Fehlerbehebung gibt.

4. Die API absichern

Da beim Zugriff über die REST-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. Beispiele mit REST-API-Anfragen

In diesem Kapitel finden Sie Beispiele, die zeigen, wie Sie mit Hilfe der REST-API häufig benötigte Aktionen ausführen können. Die Beispiele orientieren sich erneut an dem Beispiel-Code für das Kommandozeilenprogramm cURL. Im Unterschied zum Vorgehen im Kapitel Die API nutzen werden die Anfragen jedoch nicht per Skript sondern als curl-Befehle auf der Kommandozeile abgesetzt. Dadurch können Sie die Beispiele gleich ausprobieren — nachdem Sie sie auf die bei Ihnen vorhandene Umgebung angepasst haben.

Um die Befehle noch übersichtlich darstellen zu können, haben wir aus dem Beispiel-Code nur die für die Befehlsausführung absolut notwendigen Zeilen übernommen. Für die Aufbereitung der standardmäßig unformatierten Antworten der REST-API können Sie die Ausgabe wieder in den Kommandozeilen-JSON-Prozessor jq umleiten, indem Sie am Ende eines curl-Befehls ein | jq anhängen. Mehr zu jq steht weiter oben im Kapitel Die API lokal testen.

So wie der Beispiel-Code in der API-Dokumentation enthalten auch die Beispiele in diesem Kapitel Variablen: um die Basis-URL für die REST-API auf Ihrem Checkmk-Server zusammenzubauen und die Zugangsdaten des Automationsbenutzers für die genutzte Bearer-Authentifizierung festzulegen:

Variable Beispielwert Bedeutung

Variable	Beispielwert	Bedeutung
`HOST_NAME`	`myserver`	Name des Checkmk-Servers
`SITE_NAME`	`mysite`	Name der Checkmk-Instanz
`API_URL`	`http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0`	Basis-URL der REST-API
`USERNAME`	`automation`	Name des Automationsbenutzers
`PASSWORD`	`theautomationsecret`	Passwort des Automationsbenutzers

HOST_NAME

myserver

Name des Checkmk-Servers

SITE_NAME

mysite

Name der Checkmk-Instanz

API_URL

http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0

Basis-URL der REST-API

USERNAME

automation

Name des Automationsbenutzers

PASSWORD

theautomationsecret

Passwort des Automationsbenutzers

Bevor Sie die curl-Kommandos absetzen, können Sie die Variablen mit den folgenden Kommandos in der Shell auf Ihre Umgebung anpassen:

user@host:~$ HOST_NAME="myserver"; SITE_NAME="mysite"; API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"; \
USERNAME="automation"; PASSWORD="theautomationsecret";

5.1. Hosts und Ordner

Die in diesem Kapitel beschriebenen Anfragen finden Sie in der API-Dokumentation in den Endpunktordnern Hosts und Folders. Die in der API-Dokumentation enthaltenen Titel der jeweiligen Endpunkte stehen in den folgenden Überschriften in Klammern.

Alle Ordner anzeigen (Show all folders)

Hier werden alle Ordner im Setup angezeigt — rekursiv ausgehend vom Hauptordner Main — ohne Auflistung der enthaltenen Hosts:

user@host:~$ curl -G \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--data-urlencode 'parent=~' \
--data-urlencode 'recursive=true' \
--data-urlencode 'show_hosts=false' \
"$API_URL/domain-types/folder_config/collections/all"

Alle Hosts eines Ordners anzeigen (Show all hosts in a folder)

Hier werden die Hosts im Unterordner Main > Linux angefordert:

user@host:~$ curl \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/objects/folder_config/~linux/collections/hosts"

Ordner erstellen (Create a folder)

Hier wird in Main > Linux ein Unterordner Production Hosts erstellt — im Dateisystem als Verzeichnis production_hosts. Dem neuen Ordner wird dabei das Host-Merkmal Productive system aus der vordefinierten Host-Merkmalsgruppe Criticality zugewiesen:

user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json"     \
--header "Content-Type: application/json" \
--data '{
    "attributes": {
        "tag_criticality": "prod"
    },
    "name": "production_hosts",
    "parent": "~linux",
    "title": "Production Hosts"
    }' \
"$API_URL/domain-types/folder_config/collections/all"

Host erstellen (Create a host)

Hier wird im Ordner Main > Linux > Production Hosts der Host mylinuxserver mit der IP-Adresse 192.168.0.123 und dem Host-Merkmal Use piggyback data from other hosts if present erstellt:

user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
    "attributes": {
        "ipaddress": "192.168.0.123",
        "tag_piggyback": "auto-piggyback"
    },
    "folder": "~linux~production_hosts",
    "host_name": "mylinuxserver"
    }' \
"$API_URL/domain-types/host_config/collections/all"

Host anzeigen (Show a host)

Durch die Anzeige eines Hosts erhalten Sie die Liste der ihm zugewiesenen Attribute. Zusätzlich wird dabei das HTTP ETag (entity tag) geliefert, das Sie benötigen, um einen Host zu ändern. Die Änderung eines Objekts via REST-API erfolgt nicht über die ID oder den Titel des Objekts. Stattdessen wird das generierte ETag genutzt, mit dem verhindert werden soll, dass mehrere konkurrierende Anfragen Werte desselben Objekts gegenseitig überschreiben.

Das ETag wird im Antwort-Header (response header) zurückgeliefert. Damit dieser Header angezeigt wird, rufen Sie curl mit der Option -v (für verbose) auf. Hier wird der Host mylinuxserver abgefragt — und aus der Antwort nur die Zeile mit dem ETag gezeigt:

user@host:~$ curl -vG \
--request GET \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
"$API_URL/objects/host_config/mylinuxserver"
...
< ETag: "57db3792f23bd81ca7447ba4885fa2865d0c78aed4753229b29e179e539da48b"
...

Host ändern (Update a host)

Vor der Änderung besorgen Sie sich das ETag des Hosts, wie im Abschnitt Host anzeigen (Show a host) beschrieben. Das ETag tragen Sie dann im Anfrage-Header unter If-Match ein. Hier wird das beim Erstellen des Hosts gesetzte Host-Merkmal aus der Gruppe Piggyback wieder gelöscht und stattdessen das vordefinierte Merkmal API integrations if configured, else Checkmk agent gesetzt:

user@host:~$ curl \
--request PUT \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "If-Match: "57db3792f23bd81ca7447ba4885fa2865d0c78aed4753229b29e179e539da48b"" \
--header "Content-Type: application/json" \
--data '{
    "remove_attributes": [
        "tag_piggyback"
    ],
    "update_attributes": {
        "tag_agent": "cmk-agent"
    }
    }' \
"$API_URL/objects/host_config/mylinuxserver"

Service-Erkennung auf einem Host durchführen (Execute a service discovery on a host)

Damit eine Service-Erkennung auch tatsächlich die erwarteten Services liefert, müssen Sie zuvor auf Linux- und Windows-Hosts die zugehörigen Monitoring-Agenten installieren und registrieren.

Hier wird die Service-Erkennung auf dem Host mylinuxserver durchgeführt mit der Option refresh, was in der Checkmk-GUI dem Knopf Full service scan entspricht:

user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
    "host_name": "mylinuxserver",
    "mode": "refresh"
    }' \
"$API_URL/domain-types/service_discovery_run/actions/start/invoke"

Mehrere Hosts erstellen (Bulk create hosts)

Hier werden zwei Hosts im Ordner Main > Linux > Production Hosts erstellt: der erste nur mit IP-Adresse und der zweite zusätzlich mit einem Parent-Host und mit zwei Labels:

user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
	"entries": [
	{
	"attributes": {
	    "ipaddress": "192.168.0.130"
	},
	"folder": "~linux~production_hosts",
	"host_name": "mylinuxserver02"
	},
	{
	"attributes": {
	    "ipaddress": "192.168.0.131",
	    "parents": [ "router01" ],
	    "labels": {
	    	"color": "blue-metallic",
	    	"admin": "Fozzie Bear"
	    }
	},
	"folder": "~linux~production_hosts",
	"host_name": "mylinuxserver03"
	}
	]
	}' \
"$API_URL/domain-types/host_config/actions/bulk-create/invoke"

Änderungen aktivieren (Activate pending changes)

Bevor die komplexe Aktion der Umbenennung eines Hosts in Angriff genommen werden kann, ist es nötig, alle in der Konfigurationsumgebung aufgelaufenden Änderungen zu aktivieren. Hier werden die Änderungen für die Instanz mysite gesammelt aktiviert:

user@host:~$ curl \
--request POST \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{
    "force_foreign_changes": false,
    "redirect": false,
    "sites": [
        "mysite"
     ]
     }' \
"$API_URL/domain-types/activation_run/actions/activate-changes/invoke"

Host umbenennen (Rename a host)

Auch ein neuer Name ändert den Host. Besorgen Sie sich daher zuerst das aktuelle ETag des Hosts, z.B. von mylinuxserver, wie im Abschnitt Host anzeigen (Show a host) beschrieben, und tragen es im Anfrage-Header unter If-Match ein. Hier wird der Host in mylinuxserver01 umbenannt:

user@host:~$ curl \
--request PUT \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "If-Match: "a200832df1b3c5ebe8f30809177630abbdcf8f7cbd9d0f69bd9f229b359f4d00"" \
--header "Content-Type: application/json" \
--data '{
	"new_name": "mylinuxserver01"
	}' \
"$API_URL/objects/host_config/mylinuxserver/actions/rename/invoke"

6. REST-API und Web-API im Vergleich

In diesem Kapitel erhalten Sie einen Überblick, welche Funktionen Ihnen über die REST-API und über die Web-API zur Verfügung stehen. Die folgende Tabelle ist gegliedert nach den Endpunkten, die sie im linken Navigationsbereich der REST-API-Dokumentation wiederfinden. In der Tabelle enthält die Spalte für die REST-API die HTTP-Methoden (bei Mehrdeutigkeit ergänzt um Kontextinformationen) und die Spalte für die Web-API die Befehle.

Funktion	Aktion	REST-API	Web-API
Quittierung von Problemen (Acknowledge problems)	für Hosts quittieren	POST host	-
für Services quittieren	POST service	-
Wartungszeit (Downtime)	anzeigen	GET	-
alle anzeigen	GET all	-
für einen Host erstellen	POST host	-
für einen Service erstellen	POST service	-
entfernen	POST delete	-
Host-Status	Hosts eines Zustands anzeigen	GET	-
Service-Status	Service auf einem Host anzeigen	GET show_service	-
Services auf einem Host anzeigen	GET services	-
Alle Services anzeigen	GET all	-
Verschiedenes (Miscellaneous)	Versionsinformationen anzeigen	GET version	-
Agent	alle Agenten anzeigen	GET all	-
Zustand der automatischen Agentenverteilung anzeigen	GET automatic-deployment	-
Backzustand anzeigen	GET baking_status	-
Konfiguration eines Agenten anzeigen	GET agent_hash	-
Agent nach Host-Name und Betriebssystem herunterladen	GET download_by_host	-
Agent nach Hash und Betriebssystem herunterladen	GET download_by_hash	-
alle Agenten signieren	POST sign	-
alle Agenten backen	POST bake	bake_agents
alle Agenten backen und signieren	POST bake_and_sign	-
Mit Checkmk ausgelieferte Agenten herunterladen	GET download	-
Aktivierung von Änderungen (Activate changes)	auf Abschluss einer Aktivierung warten	GET wait-for-completion	-
Zustand einer Aktivierung anzeigen	GET activation_run	-
laufende Aktivierungen anzeigen	GET collections running	-
ausstehende Änderungen aktivieren	POST	activate_changes
Business Intelligence (BI)	BI-Regel entfernen	DEL bi_rule	-
BI-Regel anzeigen	GET bi_rule	-
BI-Regel erstellen	POST bi_rule	-
BI-Regel ändern	PUT bi_rule	-
BI-Aggregat entfernen	DEL bi_aggregation	-
BI-Aggregat anzeigen	GET bi_aggregation	-
BI-Aggregat erstellen	POST bi_aggregation	-
BI-Aggregat ändern	PUT bi_aggregation	-
alle BI-Pakete anzeigen	GET all bi_pack	-
BI-Paket entfernen	DEL bi_pack	-
BI-Paket anzeigen	GET bi_pack	-
BI-Paket erstellen	POST bi_pack	-
BI-Paket ändern	PUT bi_pack	-
Status von BI-Aggregaten anzeigen	GET aggregation_state	-
Kontaktgruppe (Contact group)	alle anzeigen	GET all	get_all_contactgroups
erstellen	POST	add_contactgroup
entfernen	DEL	delete_contactgroup
anzeigen	GET	-
ändern	PUT	edit_contactgroup
mehrere ändern	PUT bulk-update	-
mehrere erstellen	POST bulk-create	-
mehrere entfernen	POST bulk-delete	-
Ordner (Folder)	alle Hosts eines Ordners anzeigen	GET collections hosts	-
alle anzeigen	GET all	get_all_folder
erstellen	POST	add_folder
entfernen	DEL	delete_folder
anzeigen	GET	get_folder
ändern	PUT	edit_folder
mehrere ändern	PUT bulk-update	-
verschieben	POST move	-
Host	alle anzeigen	GET all	get_all_hosts
erstellen	POST	add_host
entfernen	DEL	delete_host
anzeigen	GET	get_host
ändern	PUT	edit_host
Cluster-Knoten ändern	PUT nodes	-
mehrere ändern	PUT bulk-update	-
umbenennen	PUT rename	-
Cluster-Host erstellen	POST clusters	-
mehrere erstellen	POST bulk-create	-
verschieben	POST move	-
mehrere entfernen	DEL bulk-delete	delete_hosts
Host-Gruppe	alle anzeigen	GET all	get_all_hostgroups
erstellen	POST	add_hostgroup
entfernen	DEL	delete_hostgroup
anzeigen	GET	-
ändern	PUT	edit_hostgroup
mehrere ändern	PUT bulk-update	-
mehrere erstellen	POST bulk-create	-
mehrere entfernen	POST bulk-delete	delete_hosts
Host-Merkmalsgruppe (Host tag group)	entfernen	DEL	-
anzeigen	GET	-
ändern	PUT	set_hosttags
alle anzeigen	GET all	get_hosttags
erstellen	POST	-
Passwort (im Passwortspeicher)	entfernen	DEL	-
anzeigen	GET	-
ändern	PUT	-
alle anzeigen	GET all	-
erstellen	POST	-
Regel (Rule)	alle anzeigen	GET all	-
erstellen	POST	set_ruleset
entfernen	DEL	-
anzeigen	GET	-
verschieben	POST move	-
Regelsatz (Rule set)	durchsuchen	GET all	get_ruleset_info
anzeigen	GET	get_ruleset
Service-Erkennung (Service discovery)	Ergebnis der aktuellen Service-Erkennung anzeigen	GET service_discovery	-
Services eines Service-Erkennungszustands anzeigen	GET collections^[1]	-
Den letzten Hintergrundauftrag zur Service-Erkennung anzeigen	GET service_discovery_run	-
Zustand eines Auftrags zur Service-Erkennung auf mehreren Hosts anzeigen	GET discovery-run	-
Service-Erkennungszustand eines Services ändern	PUT	-
Service-Erkennung auf einem Host ausführen	POST service_discovery_run	discover_services
Service-Erkennung auf einem Host ausführen	POST discover_services^[1]	discover_services
Service-Erkennung auf mehreren Hosts ausführen	POST bulk-discovery-start	-
Service-Gruppe	alle anzeigen	GET all	get_all_servicegroups
erstellen	POST	add_servicegroup
entfernen	DEL	delete_servicegroup
anzeigen	GET	-
ändern	PUT	edit_servicegroup
mehrere ändern	PUT bulk-update	-
mehrere erstellen	POST bulk-create	-
mehrere entfernen	POST bulk-delete	-
Zeitperiode (Time period)	entfernen	DEL	-
anzeigen	GET	-
ändern	PUT	-
alle anzeigen	GET all	-
erstellen	POST	-
Benutzer (User)	entfernen	DEL	delete_users
anzeigen	GET	-
ändern	PUT	edit_users
alle anzeigen	GET all	get_all_users
erstellen	POST	add_users
Graph	abrufen	-	get_graph
Instanz (Site)	anzeigen	-	get_site
aktualisieren	-	set_site
entfernen	-	delete_site
anmelden	-	login_site
abmelden	-	logout_site

Funktion

Aktion

REST-API

Web-API

Quittierung von Problemen (Acknowledge problems)

für Hosts quittieren

POST host

für Services quittieren

POST service

Wartungszeit (Downtime)

anzeigen

GET

alle anzeigen

GET all

für einen Host erstellen

POST host

für einen Service erstellen

POST service

entfernen

POST delete

Host-Status

Hosts eines Zustands anzeigen

GET

Service-Status

Service auf einem Host anzeigen

GET show_service

Services auf einem Host anzeigen

GET services

Alle Services anzeigen

GET all

Verschiedenes (Miscellaneous)

Versionsinformationen anzeigen

GET version

Agent

alle Agenten anzeigen

GET all

Zustand der automatischen Agentenverteilung anzeigen

GET automatic-deployment

Backzustand anzeigen

GET baking_status

Konfiguration eines Agenten anzeigen

GET agent_hash

Agent nach Host-Name und Betriebssystem herunterladen

GET download_by_host

Agent nach Hash und Betriebssystem herunterladen

GET download_by_hash

alle Agenten signieren

POST sign

alle Agenten backen

POST bake

bake_agents

alle Agenten backen und signieren

POST bake_and_sign

Mit Checkmk ausgelieferte Agenten herunterladen

GET download

Aktivierung von Änderungen (Activate changes)

auf Abschluss einer Aktivierung warten

GET wait-for-completion

Zustand einer Aktivierung anzeigen

GET activation_run

laufende Aktivierungen anzeigen

GET collections running

ausstehende Änderungen aktivieren

POST

activate_changes

Business Intelligence (BI)

BI-Regel entfernen

DEL bi_rule

BI-Regel anzeigen

GET bi_rule

BI-Regel erstellen

POST bi_rule

BI-Regel ändern

PUT bi_rule

BI-Aggregat entfernen

DEL bi_aggregation

BI-Aggregat anzeigen

GET bi_aggregation

BI-Aggregat erstellen

POST bi_aggregation

BI-Aggregat ändern

PUT bi_aggregation

alle BI-Pakete anzeigen

GET all bi_pack

BI-Paket entfernen

DEL bi_pack

BI-Paket anzeigen

GET bi_pack

BI-Paket erstellen

POST bi_pack

BI-Paket ändern

PUT bi_pack

Status von BI-Aggregaten anzeigen

GET aggregation_state

Kontaktgruppe (Contact group)

alle anzeigen

GET all

get_all_contactgroups

erstellen

POST

add_contactgroup

entfernen

DEL

delete_contactgroup

anzeigen

GET

ändern

PUT

edit_contactgroup

mehrere ändern

PUT bulk-update

mehrere erstellen

POST bulk-create

mehrere entfernen

POST bulk-delete

Ordner (Folder)

alle Hosts eines Ordners anzeigen

GET collections hosts

alle anzeigen

GET all

get_all_folder

erstellen

POST

add_folder

entfernen

DEL

delete_folder

anzeigen

GET

get_folder

ändern

PUT

edit_folder

mehrere ändern

PUT bulk-update

verschieben

POST move

Host

alle anzeigen

GET all

get_all_hosts

erstellen

POST

add_host

entfernen

DEL

delete_host

anzeigen

GET

get_host

ändern

PUT

edit_host

Cluster-Knoten ändern

PUT nodes

mehrere ändern

PUT bulk-update

umbenennen

PUT rename

Cluster-Host erstellen

POST clusters

mehrere erstellen

POST bulk-create

verschieben

POST move

mehrere entfernen

DEL bulk-delete

delete_hosts

Host-Gruppe

alle anzeigen

GET all

get_all_hostgroups

erstellen

POST

add_hostgroup

entfernen

DEL

delete_hostgroup

anzeigen

GET

ändern

PUT

edit_hostgroup

mehrere ändern

PUT bulk-update

mehrere erstellen

POST bulk-create

mehrere entfernen

POST bulk-delete

delete_hosts

Host-Merkmalsgruppe (Host tag group)

entfernen

DEL

anzeigen

GET

ändern

PUT

set_hosttags

alle anzeigen

GET all

get_hosttags

erstellen

POST

Passwort (im Passwortspeicher)

entfernen

DEL

anzeigen

GET

ändern

PUT

alle anzeigen

GET all

erstellen

POST

Regel (Rule)

alle anzeigen

GET all

erstellen

POST

set_ruleset

entfernen

DEL

anzeigen

GET

verschieben

POST move

Regelsatz (Rule set)

durchsuchen

GET all

get_ruleset_info

anzeigen

GET

get_ruleset

Service-Erkennung (Service discovery)

Ergebnis der aktuellen Service-Erkennung anzeigen

GET service_discovery

Services eines Service-Erkennungszustands anzeigen

GET collections^[1]

Den letzten Hintergrundauftrag zur Service-Erkennung anzeigen

GET service_discovery_run

Zustand eines Auftrags zur Service-Erkennung auf mehreren Hosts anzeigen

GET discovery-run

Service-Erkennungszustand eines Services ändern

PUT

Service-Erkennung auf einem Host ausführen

POST service_discovery_run

discover_services

Service-Erkennung auf einem Host ausführen

POST discover_services^[1]

discover_services

Service-Erkennung auf mehreren Hosts ausführen

POST bulk-discovery-start

Service-Gruppe

alle anzeigen

GET all

get_all_servicegroups

erstellen

POST

add_servicegroup

entfernen

DEL

delete_servicegroup

anzeigen

GET

ändern

PUT

edit_servicegroup

mehrere ändern

PUT bulk-update

mehrere erstellen

POST bulk-create

mehrere entfernen

POST bulk-delete

Zeitperiode (Time period)

entfernen

DEL

anzeigen

GET

ändern

PUT

alle anzeigen

GET all

erstellen

POST

Benutzer (User)

entfernen

DEL

delete_users

anzeigen

GET

ändern

PUT

edit_users

alle anzeigen

GET all

get_all_users

erstellen

POST

add_users

Graph

abrufen

get_graph

Instanz (Site)

anzeigen

get_site

aktualisieren

set_site

entfernen

delete_site

anmelden

login_site

abmelden

logout_site

[1]. Dieser Endpunkt ist abgekündigt.