Die Checkmk REST-API

1. Einleitung

Seit der Version 2.0.0 gibt es als 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.

Hinweis: Beginnend mit der Version 2.2.0 ersetzt die REST-API komplett die alte Web-API, die manchmal auch als HTTP-API bezeichnet wurde. Die Web-API wurde mit Version 2.2.0 aus Checkmk entfernt. Im letzten Kapitel finden Sie noch eine Gegenüberstellung der Funktionalität von REST-API und Web-API. Aus der Tabelle wird deutlich, dass die Checkmk REST-API die Web-API nicht nur ersetzt, sondern auch Zugriff auf sehr viel mehr Bereiche mit spezifischeren Möglichkeiten bietet.

Das REST im Namen der REST-API 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“) nachgewiesen hat.

Versionierung

Die API ist versioniert und nutzt dabei eine dreistufige Nummerierung nach dem Semantic Versioning 2.x Standard. Details finden Sie im Abschnitt 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 (z.B. für cURL und HTTPie).

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, wie viel REST in einer API steckt. In Ebene 1 wird die Einführung von Ressourcen gefordert, damit über die API statt zu einem globalen Endpunkt 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 soll die REST-API die komplette Funktionalität abdecken, die Checkmk über die GUI und über Kommandoschnittstelle bietet.

Für Funktionen, die es nur in den kommerziellen Editionen gibt, wie z.B. Service Level Agreement (SLA) oder Agentenbäckerei, werden die zugehörigen Methoden der REST-API auch nur in diesen Editionen angeboten.

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, zum Beispiel neue Endpunkte. 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 > 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 Authentifizierungsmethode 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 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 Kommandozeilenprogramm cURL, das es ermöglicht, ohne Benutzerinteraktion Daten von oder zu einem Server zum Beispiel per HTTP zu übertragen.

Hinweis: Insbesondere bei komplexen Anfragen kann es vorkommen, dass die cURL-Beispiele Inkonsistenzen enthalten und daher nicht immer verlässlich sind. Wir empfehlen daher grundsätzlich HTTPie, das konsistenter, leichter zu verstehen und besser für die Verwendung in Skripten geeignet ist.

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 GitHub 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  3480  100  3329  100   151  38222   1733 --:--:-- --:--:-- --:--:-- 40465
{
  "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": "2023-02-23T10:42:31.218567+00:00",
        "updated_at": "2023-02-23T10:42:31.248058+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.

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

Für die Ausführung einer Service-Erkennung via REST-API wählen Sie in der API-Dokumentation den entsprechenden Eintrag 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   1188 --:--:-- --:--:-- --:--:--  1190
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  1094  100   962  100   132   8149   1118 --:--:-- --:--:-- --:--:--  9350
{
  "links": [
    {
      "domainType": "link",
      "rel": "self",
      "href": "http://myserver/mysite/check_mk/api/1.0/objects/activation_run/7ed6a562-79a4-41ff-a2a3-77938243d965",
      "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/7ed6a562-79a4-41ff-a2a3-77938243d965/actions/wait-for-completion/invoke",
      "method": "GET",
      "type": "application/json"
    }
  ],
  "domainType": "activation_run",
  "id": "7ed6a562-79a4-41ff-a2a3-77938243d965",
  "title": "Activation status: In progress.",
  "members": {},
  "extensions": {
    "sites": [
      "mysite"
    ],
    "is_running": true,
    "force_foreign_changes": false,
    "time_started": "2023-02-23T12:07:54.796169+00:00",
    "changes": [
      {
        "id": "28c84ac9-aacb-4a4c-a929-6f4395c2b178",
        "user_id": "automation",
        "action_name": "create-host",
        "text": "Created new host myhost123.",
        "time": "2023-02-23T12:05:47.846263+00:00"
      }
    ]
  }
}
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, diese 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 Skripte 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 aufgelaufenen Ä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. Die REST-API Funktionen

In diesem Kapitel erhalten Sie einen Überblick, welche Funktionen Ihnen über die REST-API zur Verfügung stehen. Die folgenden Tabellen sind 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). Die letzte Spalte enthält die entsprechenden Befehle der bis zur Version 2.1.0 in Checkmk enthaltenen Web-API.

6.1. Endpunkte für das Monitoring

Endpunkt Methode REST-API Web-API (bis Version 2.1.0)

Endpunkt	Methode	REST-API	Web-API (bis Version 2.1.0)
Service Level Agreement ^[1]	SLA-Daten berechnen ^[1]	`POST`	`get_sla`
Quittierung von Problemen (Acknowledge problems)	Für Hosts quittieren	`POST host`	-
Für Services quittieren	`POST service`	-
Kommentar	Host-Kommentar erstellen	`POST host`	-
Service-Kommentar erstellen	`POST service`	-
Entfernen	`POST delete`	-
Anzeigen	`GET`	-
Mehrere anzeigen	`GET {collection_name}`	-
Wartungszeit (Downtime)	Für einen Host erstellen	`POST host`	-
Für einen Service erstellen	`POST service`	-
Entfernen	`POST delete`	-
Anzeigen	`GET`	-
Alle anzeigen	`GET all`	-
Event Console	Events archivieren	`POST delete`	-
Event-Status ändern	`POST change_state`	-
Mehrere Event-Status ändern	`POST {event_id} change_state`	-
Event anzeigen	`GET {event_id}`	-
Alle Events anzeigen	`GET all`	-
Event ändern und quittieren	`GET {event_id} update_and_acknowledge`	-
Events ändern und quittieren	`GET update_and_acknowledge`	-
Host-Status	Hosts eines Zustands anzeigen	`GET`	-
Metrik	Metriken abrufen	`POST metric`	`get_graph`
Benutzerdefinierten Graph abrufen ^[1]	`POST get_custom_graph`	`get_graph`
Service-Status	Alle Services anzeigen	`GET all`	-
Services eines Hosts anzeigen	`GET {host_name} services`	-
Service eines Hosts anzeigen	`GET {host_name} show_service`	-
Verschiedenes (Miscellaneous)	Versionsinformationen anzeigen	`GET version`	-

Service Level Agreement ^[1]

SLA-Daten berechnen ^[1]

POST

get_sla

Quittierung von Problemen (Acknowledge problems)

Für Hosts quittieren

POST host

Für Services quittieren

POST service

Kommentar

Host-Kommentar erstellen

POST host

Service-Kommentar erstellen

POST service

Entfernen

POST delete

Anzeigen

GET

Mehrere anzeigen

GET {collection_name}

Wartungszeit (Downtime)

Für einen Host erstellen

POST host

Für einen Service erstellen

POST service

Entfernen

POST delete

Anzeigen

GET

Alle anzeigen

GET all

Event Console

Events archivieren

POST delete

Event-Status ändern

POST change_state

Mehrere Event-Status ändern

POST {event_id} change_state

Event anzeigen

GET {event_id}

Alle Events anzeigen

GET all

Event ändern und quittieren

GET {event_id} update_and_acknowledge

Events ändern und quittieren

GET update_and_acknowledge

Host-Status

Hosts eines Zustands anzeigen

GET

Metrik

Metriken abrufen

POST metric

get_graph

Benutzerdefinierten Graph abrufen ^[1]

POST get_custom_graph

get_graph

Service-Status

Alle Services anzeigen

GET all

Services eines Hosts anzeigen

GET {host_name} services

Service eines Hosts anzeigen

GET {host_name} show_service

Verschiedenes (Miscellaneous)

Versionsinformationen anzeigen

GET version

6.2. Endpunkte für das Setup

Endpunkt Methode REST-API Web-API (bis Version 2.1.0)

Endpunkt	Methode	REST-API	Web-API (bis Version 2.1.0)
Agent	Zustand der automatischen Agentenverteilung anzeigen ^[1]	`GET automatic-deployment`	-
Alle Agenten backen ^[1]	`POST bake`	`bake_agents`
Alle Agenten backen und signieren ^[1]	`POST bake_and_sign`	-
Backzustand anzeigen ^[1]	`GET baking_status`	-
Agent nach Hash und Betriebssystem herunterladen ^[1]	`GET download_by_hash`	-
Agent nach Host- oder Ordnername und Betriebssystem herunterladen ^[1]	`GET download_by_host`	-
Alle Agenten anzeigen ^[1]	`GET all`	-
Konfiguration eines Agenten anzeigen ^[1]	`GET {agent_hash}`	-
Alle Agenten signieren ^[1]	`POST sign`	-
Mit Checkmk ausgelieferte Agenten herunterladen	`GET download`	-
Aktivierung von Änderungen (Activate changes)	Ausstehende Änderungen aktivieren	`POST`	`activate_changes`
Auf Abschluss einer Aktivierung warten	`GET wait-for-completion`	-
Laufende Aktivierungen anzeigen	`GET running`	-
Ausstehende Änderungen anzeigen	`GET pending_changes`	-
Zustand einer Aktivierung anzeigen	`GET {activation_id}`	-
Hilfsmerkmal (Auxiliary tag)	Erstellen	`POST`	-
Alle anzeigen	`GET all`	-
Entfernen	`POST delete`	-
Ändern	`PUT`	-
Anzeigen	`GET`	-
Business Intelligence (BI)	BI-Aggregat entfernen	`DELETE bi_aggregation`	-
BI-Aggregat anzeigen	`GET bi_aggregation`	-
BI-Aggregat erstellen	`POST bi_aggregation`	-
BI-Aggregat ändern	`PUT bi_aggregation`	-
BI-Paket entfernen	`DELETE bi_pack`	-
BI-Paket anzeigen	`GET bi_pack`	-
BI-Paket erstellen	`POST bi_pack`	-
BI-Paket ändern	`PUT bi_pack`	-
BI-Regel entfernen	`DELETE bi_rule`	-
BI-Regel anzeigen	`GET bi_rule`	-
BI-Regel erstellen	`POST bi_rule`	-
BI-Regel ändern	`PUT bi_rule`	-
Status von BI-Aggregaten anzeigen	`GET aggregation_state`	-
Alle BI-Pakete anzeigen	`GET all bi_pack`	-
Kontaktgruppe (Contact group)	Mehrere erstellen	`POST bulk-create`	-
Mehrere entfernen	`POST bulk-delete`	-
Mehrere ändern	`PUT bulk-update`	-
Erstellen	`POST`	`add_contactgroup`
Alle anzeigen	`GET all`	`get_all_contactgroups`
Entfernen	`DELETE`	`delete_contactgroup`
Anzeigen	`GET`	-
Ändern	`PUT`	`edit_contactgroup`
Ordner (Folder)	Mehrere ändern	`PUT bulk-update`	-
Erstellen	`POST`	`add_folder`
Alle anzeigen	`GET all`	`get_all_folders`
Entfernen	`DELETE`	`delete_folder`
Anzeigen	`GET`	`get_folder`
Ändern	`PUT`	`edit_folder`
Alle Hosts eines Ordners anzeigen	`GET hosts`	-
Verschieben	`POST move`	-
Host	Mehrere erstellen	`POST bulk-create`	-
Mehrere entfernen	`DELETE bulk-delete`	`delete_hosts`
Mehrere ändern	`PUT bulk-update`	-
Cluster-Host erstellen	`POST clusters`	-
Host erstellen	`POST`	`add_host`
Alle anzeigen	`GET all`	`get_all_hosts`
Entfernen	`DELETE`	`delete_host`
Anzeigen	`GET`	`get_host`
Ändern	`PUT`	`edit_host`
Verschieben	`POST move`	-
Umbenennen	`PUT rename`	-
Cluster-Knoten ändern	`PUT nodes`	-
Host-Gruppe	Mehrere erstellen	`POST bulk-create`	-
Mehrere entfernen	`POST bulk-delete`	-
Mehrere ändern	`PUT bulk-update`	-
Erstellen	`POST`	`add_hostgroup`
Alle anzeigen	`GET all`	`get_all_hostgroups`
Entfernen	`DELETE`	`delete_hostgroup`
Anzeigen	`GET`	-
Ändern	`PUT`	`edit_hostgroup`
Host-Merkmalsgruppe (Host tag group)	Erstellen	`POST`	-
Alle anzeigen	`GET all`	`get_hosttags`
Entfernen	`DELETE`	-
Anzeigen	`GET`	-
Ändern	`PUT`	`set_hosttags`
Benachrichtigungsregel (Notification rule)	Entfernen	`POST delete`	-
Erstellen	`POST`	-
Alle anzeigen	`GET all`	-
Ändern	`PUT`	-
Anzeigen	`GET`	-
Passwort (im Passwortspeicher)	Erstellen	`POST`	-
Alle anzeigen	`GET all`	-
Entfernen	`DELETE`	-
Anzeigen	`GET`	-
Ändern	`PUT`	-
Regel (Rule)	Erstellen	`POST`	`set_ruleset`
Alle anzeigen	`GET all`	-
Entfernen	`DELETE`	-
Anzeigen	`GET`	-
Verschieben	`POST move`	-
Regelsatz (Rule set)	Durchsuchen	`GET all`	`get_rulesets_info`
Anzeigen	`GET`	`get_ruleset`
Service-Erkennung (Service discovery)	Service-Erkennung auf einem Host ausführen ^[2]	`POST discover_services`	`discover_services`
Service-Erkennung auf mehreren Hosts ausführen	`POST bulk-discovery-start`	-
Service-Erkennung auf einem Host ausführen	`POST service_discovery_run`	`discover_services`
Auf Abschluss einer Service-Erkennung warten	`GET wait-for-completion`	-
Zustand eines Auftrags zur Service-Erkennung auf mehreren Hosts anzeigen	`GET discovery-run`	-
Ergebnis der aktuellen Service-Erkennung anzeigen	`GET service_discovery`	-
Den letzten Hintergrundauftrag zur Service-Erkennung anzeigen	`GET service_discovery_run`	-
Services eines Service-Erkennungszustands anzeigen ^[2]	`GET services`	-
Service-Erkennungszustand eines Services ändern	`PUT`	-
Service-Gruppe	Mehrere erstellen	`POST bulk-create`	-
Mehrere entfernen	`POST bulk-delete`	-
Mehrere ändern	`PUT bulk-update`	-
Erstellen	`POST`	`add_servicegroup`
Alle anzeigen	`GET all`	`get_all_servicegroups`
Entfernen	`DELETE`	`delete_servicegroup`
Anzeigen	`GET`	-
Ändern	`PUT`	`edit_servicegroup`
Instanz (Site)	Instanzverbindung entfernen	`POST delete`	`delete_site`
Instanzverbindung erstellen	`POST`	-
Alle Instanzverbindungen anzeigen	`GET all`	-
Instanzverbindung ändern	`PUT`	`set_site`
Instanzverbindung anzeigen	`GET`	`get_site`
An Remote-Instanz anmelden	`POST login`	`login_site`
Von Remote-Instanz abmelden	`POST logout`	`logout_site`
Zeitperiode (Time period)	Erstellen	`POST`	-
Alle anzeigen	`GET all`	-
Entfernen	`DELETE`	-
Anzeigen	`GET`	-
Ändern	`PUT`	-
Benutzer (User)	Erstellen	`POST`	`add_users`
Alle anzeigen	`GET all`	`get_all_users`
Entfernen	`DELETE`	`delete_users`
Ändern	`PUT`	`edit_users`
Anzeigen	`GET`	-
Benutzerrolle (User role)	Erstellen/Klonen	`POST`	-
Alle anzeigen	`GET all`	-
Entfernen	`DELETE`	-
Ändern	`PUT`	-
Anzeigen	`GET`	-

Agent

Zustand der automatischen Agentenverteilung anzeigen ^[1]

GET automatic-deployment

Alle Agenten backen ^[1]

POST bake

bake_agents

Alle Agenten backen und signieren ^[1]

POST bake_and_sign

Backzustand anzeigen ^[1]

GET baking_status

Agent nach Hash und Betriebssystem herunterladen ^[1]

GET download_by_hash

Agent nach Host- oder Ordnername und Betriebssystem herunterladen ^[1]

GET download_by_host

Alle Agenten anzeigen ^[1]

GET all

Konfiguration eines Agenten anzeigen ^[1]

GET {agent_hash}

Alle Agenten signieren ^[1]

POST sign

Mit Checkmk ausgelieferte Agenten herunterladen

GET download

Aktivierung von Änderungen (Activate changes)

Ausstehende Änderungen aktivieren

POST

activate_changes

Auf Abschluss einer Aktivierung warten

GET wait-for-completion

Laufende Aktivierungen anzeigen

GET running

Ausstehende Änderungen anzeigen

GET pending_changes

Zustand einer Aktivierung anzeigen

GET {activation_id}

Hilfsmerkmal (Auxiliary tag)

Erstellen

POST

Alle anzeigen

GET all

Entfernen

POST delete

Ändern

PUT

Anzeigen

GET

Business Intelligence (BI)

BI-Aggregat entfernen

DELETE bi_aggregation

BI-Aggregat anzeigen

GET bi_aggregation

BI-Aggregat erstellen

POST bi_aggregation

BI-Aggregat ändern

PUT bi_aggregation

BI-Paket entfernen

DELETE bi_pack

BI-Paket anzeigen

GET bi_pack

BI-Paket erstellen

POST bi_pack

BI-Paket ändern

PUT bi_pack

BI-Regel entfernen

DELETE bi_rule

BI-Regel anzeigen

GET bi_rule

BI-Regel erstellen

POST bi_rule

BI-Regel ändern

PUT bi_rule

Status von BI-Aggregaten anzeigen

GET aggregation_state

Alle BI-Pakete anzeigen

GET all bi_pack

Kontaktgruppe (Contact group)

Mehrere erstellen

POST bulk-create

Mehrere entfernen

POST bulk-delete

Mehrere ändern

PUT bulk-update

Erstellen

POST

add_contactgroup

Alle anzeigen

GET all

get_all_contactgroups

Entfernen

DELETE

delete_contactgroup

Anzeigen

GET

Ändern

PUT

edit_contactgroup

Ordner (Folder)

Mehrere ändern

PUT bulk-update

Erstellen

POST

add_folder

Alle anzeigen

GET all

get_all_folders

Entfernen

DELETE

delete_folder

Anzeigen

GET

get_folder

Ändern

PUT

edit_folder

Alle Hosts eines Ordners anzeigen

GET hosts

Verschieben

POST move

Host

Mehrere erstellen

POST bulk-create

Mehrere entfernen

DELETE bulk-delete

delete_hosts

Mehrere ändern

PUT bulk-update

Cluster-Host erstellen

POST clusters

Host erstellen

POST

add_host

Alle anzeigen

GET all

get_all_hosts

Entfernen

DELETE

delete_host

Anzeigen

GET

get_host

Ändern

PUT

edit_host

Verschieben

POST move

Umbenennen

PUT rename

Cluster-Knoten ändern

PUT nodes

Host-Gruppe

Mehrere erstellen

POST bulk-create

Mehrere entfernen

POST bulk-delete

Mehrere ändern

PUT bulk-update

Erstellen

POST

add_hostgroup

Alle anzeigen

GET all

get_all_hostgroups

Entfernen

DELETE

delete_hostgroup

Anzeigen

GET

Ändern

PUT

edit_hostgroup

Host-Merkmalsgruppe (Host tag group)

Erstellen

POST

Alle anzeigen

GET all

get_hosttags

Entfernen

DELETE

Anzeigen

GET

Ändern

PUT

set_hosttags

Benachrichtigungsregel (Notification rule)

Entfernen

POST delete

Erstellen

POST

Alle anzeigen

GET all

Ändern

PUT

Anzeigen

GET

Passwort (im Passwortspeicher)

Erstellen

POST

Alle anzeigen

GET all

Entfernen

DELETE

Anzeigen

GET

Ändern

PUT

Regel (Rule)

Erstellen

POST

set_ruleset

Alle anzeigen

GET all

Entfernen

DELETE

Anzeigen

GET

Verschieben

POST move

Regelsatz (Rule set)

Durchsuchen

GET all

get_rulesets_info

Anzeigen

GET

get_ruleset

Service-Erkennung (Service discovery)

Service-Erkennung auf einem Host ausführen ^[2]

POST discover_services

discover_services

Service-Erkennung auf mehreren Hosts ausführen

POST bulk-discovery-start

Service-Erkennung auf einem Host ausführen

POST service_discovery_run

discover_services

Auf Abschluss einer Service-Erkennung warten

GET wait-for-completion

Zustand eines Auftrags zur Service-Erkennung auf mehreren Hosts anzeigen

GET discovery-run

Ergebnis der aktuellen Service-Erkennung anzeigen

GET service_discovery

Den letzten Hintergrundauftrag zur Service-Erkennung anzeigen

GET service_discovery_run

Services eines Service-Erkennungszustands anzeigen ^[2]

GET services

Service-Erkennungszustand eines Services ändern

PUT

Service-Gruppe

Mehrere erstellen

POST bulk-create

Mehrere entfernen

POST bulk-delete

Mehrere ändern

PUT bulk-update

Erstellen

POST

add_servicegroup

Alle anzeigen

GET all

get_all_servicegroups

Entfernen

DELETE

delete_servicegroup

Anzeigen

GET

Ändern

PUT

edit_servicegroup

Instanz (Site)

Instanzverbindung entfernen

POST delete

delete_site

Instanzverbindung erstellen

POST

Alle Instanzverbindungen anzeigen

GET all

Instanzverbindung ändern

PUT

set_site

Instanzverbindung anzeigen

GET

get_site

An Remote-Instanz anmelden

POST login

login_site

Von Remote-Instanz abmelden

POST logout

logout_site

Zeitperiode (Time period)

Erstellen

POST

Alle anzeigen

GET all

Entfernen

DELETE

Anzeigen

GET

Ändern

PUT

Benutzer (User)

Erstellen

POST

add_users

Alle anzeigen

GET all

get_all_users

Entfernen

DELETE

delete_users

Ändern

PUT

edit_users

Anzeigen

GET

Benutzerrolle (User role)

Erstellen/Klonen

POST

Alle anzeigen

GET all

Entfernen

DELETE

Ändern

PUT

Anzeigen

GET

[1]. Dieser Eintrag ist nur in den kommerziellen Editionen vorhanden.

[2]. Dieser Endpunkt ist abgekündigt.