Über die Checkmk-REST-API lässt sich die Konfiguration des Monitorings abfragen und bearbeiten. Über die Livestatus-API gibt es Informationen über den Status des Monitorings. Für die REST-API kommen meist die üblichen HTTP-Tools wie Curl, Httpie oder Python zum Einsatz, für Livestatus gibt es die Checkmk-interne Livestatus Query Language und das Tool lq. Aber man kann auch kombinieren!
Ein typischer Fall für die REST-API: Welche Hosts sind konfiguriert? Eine simple curl-Abfrage kann alle Hosts ausgeben. Oder auch alle Konfigurationsdaten eines einzelnen Hosts.
Ein typischer Fall für Livestatus: Welche Hosts sind gerade in einer Wartungszeit? Eine lq-Abfrage kann entsprechend filtern.
Ein simpler Fall für die Kombination aus REST-API + Livestatus: Zeige alle Hosts, die "localhost" im Namen beinhalten.
Die automatische REST-API-Doku beschränkt sich leider auf folgenden Hinweis: "The endpoints in the category "Monitoring" support arbitrary Livestatus expressions (including And, Or combinators) and all columns of some specific tables can be queried."
Soll heißen: Die REST-API-Endpunkte in der Kategorie "Monitoring", also zum Beispiel "Host status" oder "Metrics", vertragen Livestatus-Ausdrücke, die etwa zum Filtern genutzt werden können. Anders ausgedrückt: Normalerweise nutzt man Livestatus-Abfragen im Terminal über das jq-Werkzeug - man kann sie aber auch in HTTP-Abfragen per zum Beispiel Curl integrieren.
Die Frage ist: Wie genau wird ein Livestatus- in den REST-API-Ausdruck integriert?
Livestatus-Filter in REST-API-Abfragen
Der eigentliche Livestatus-Filter für Hostnamen, die "localhost" (unabhängig von Groß-/Kleinschreibung) beinhalten:
query={"op":"~~","left":"name","right":"Localhost"}
- op ist der Operator "~~" für den Groß-/Kleinschreibungs-unabhängigen Vergleich per regulärem Ausdruck.
- left meint den Namen einer Livestatus-Spalte, hier "name" für Hostnamen.
- right setzt entsprechend den Wert für die Spalte.
Da der Wert in diesem Fall ein regulärer Ausdruck ist, würde zum Beispiel "Localhost$" nur Hosts ausgeben, die auf "Localhost" (oder localhost, localHost etc.) enden.
Eine komplette curl-Abfrage könnte dann inklusive zugehöriger Variablen so aussehen:
HOST_NAME="cmkserver"
SITE_NAME="mysite_24"
API_URL="http://$HOST_NAME/$SITE_NAME/check_mk/api/1.0"
USERNAME="myuser"
PASSWORD="mypassword"
curl -G \
--request GET \
-u "$USERNAME:$PASSWORD" \
--header "Accept: application/json" \
--data-urlencode 'query={"op":"~~","left":"name","right":"Localhost$"}' \
"$API_URL/domain-types/host/collections/all" \
| jq
Die Ausgabe wird der Lesbarkeit halber am Ende noch an jq weitergeleitet - mehr zum Aufhübschen von JSON-Ausgaben haben wir hier.
Hier noch ein Beispiel für die Abfrage aller Hosts, die OK sind - per grep reduziert auf die Namen:
curl --request POST \
--silent \
--header "Authorization: Bearer $USERNAME $PASSWORD" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @- "$API_URL/domain-types/host/collections/all" <<EOF | jq | grep -i name
{
"columns": [
"name"
],
"query": "{\"op\": \"and\", \"expr\": [{\"op\": \"=\", \"left\": \"state\", \"right\": \"0\"}]}",
"sites": [
"${SITE_NAME}"
]
}
EOF
Ergebnis (Auszug):
"name": "tutonaut"
"name": "gizlog"
"name": "localhost"
"name": "localhost_testing"
Wieso dieses Beispiel? Der ganze Kram mit dem Here-Dokument/EOF und den vielen Anführungszeichen soll einfach zeigen, dass es bisweilen etwas frickelig werden kann - und die Beispiele aus der offiziellen, automatischen ReDoc-Doku nicht immer wirklich gut per Copy & Paste funktionieren 😉
Apropos: Wenn die Beispiele oben per Copy & Paste Probleme bereiten, könnte es an Wordpress liegen - dieses elende Teil neigt dazu, Code/Anführungszeichen zu verhunzen ... Hier funktioniert's aber.
Mehr zu Checkmk.
