custom checks checkmk

Custom Checks in Checkmk: eigene Scripte sauber integrieren und als Local Check ausrollen

von

Standard-Checks decken viel ab, aber in der Praxis bleibt fast immer etwas übrig: ein proprietärer Dienst, ein Lizenzzähler, ein Business-KPI aus einer Datenbank oder ein „läuft der Job wirklich?“ auf einem Fileshare. Genau hier lohnt sich Personalisierung in Checkmk. Wenn Sie eigene Scripts in die Überwachung bringen, gewinnen Sie Kontrolle über Metriken, Schwellenwerte und Fehlermeldungen – und Sie können diese Checks perfekt für die IT-Sicherheitsrichtlinien in Ihrem Betrieb anpassen.

In diesem Beitrag zeigen wir Ihnen, wie Local Checks in Checkmk auf der Kommandozeile funktionieren, wo Sie Ihre Skripte im Dateisystem einer Checkmk-Site ablegen, wie Sie diese per Agent Bakery („Deploy custom files with agent“) ausrollen und wie Sie das Ganze über Host-Tags sauber steuerbar machen. Dazu gibt es typische Stolpersteine und Troubleshootingtips.

Da dieser Beitrag einige Konfigurationspunkte beinhaltet, werden wir nicht auf alle näher eingehen können. Wenn Sie dazu Fragen haben oder Unterstützung bei der Konfiguration von Checkmk brauchen, dann besuchen Sie den Infobereich auf unserer Webseite oder kontaktieren Sie unsere kompetenten Admins.

Falls Sie noch keinerlei Basiswissen im Bereich Checkmk Enterprise – und on-Premise Monitoring haben, schauen Sie sich unseren Blogbeitrag ‚Was ist Checkmk‚ an.

Wofür sind eigene Checks in Checkmk gut?

Eigene Checks sind dann sinnvoll, wenn Sie etwas überwachen möchten, das Checkmk (oder ein vorhandenes Plugin) nicht abdeckt, oder wenn Sie eine spezielle Logik brauchen:

  • Eigenentwicklungen / Legacy-Dienste: „Ist Prozess X aktiv?“, reicht oft nicht; Sie wollen Version, Queue-Länge, Fehlerraten oder Antwortzeiten.
  • Jobs & Scheduler: Backup, ETL, Cronjobs, ERP-Schnittstellen. Ein „OK“ ist nur dann OK, wenn der letzte Lauf wirklich erfolgreich war.
  • Security-nahe Prüfungen: Zertifikatszustand auf internen Appliances, Policy-Compliance, Status von Agenten/EDR-Diensten oder „hat sich eine Konfiguration ungewollt verändert?“. (Achten Sie dabei darauf, keine sensiblen Daten in Klartext an den Agenten zurückzugeben.)
  • Kostenkontrolle/Capacity: Eigene Metriken aus APIs (z. B. Objektanzahl, Request-Fehler, Quotas) helfen bei vorausschauendem Monitoring.

Technisch attraktiv: Local Checks laufen agentseitig. Sie benötigen dafür keine Spezialrechte auf dem Checkmk-Server und Sie minimieren Netzwerkabhängigkeiten, weil die Logik direkt am Zielsystem ausgeführt wird.

Wie Local Checks in Checkmk auf der Kommandozeile aufgebaut sind

Local Checks sind ausführbare Dateien, die auf dem überwachten Host im Local-Check-Verzeichnis liegen. Beim Agentenlauf ruft der Checkmk-Agent diese Skripte auf und gibt deren Ausgabe im Abschnitt <<<local>>> zurück.

Das Ausgabeformat: Status, Item, Werte, Text

Ein Local Check liefert pro Zeile ein Ergebnis zurück. Das grundlegende Format ist:

<state> <item> <perfdata> <text>
  • state: 0=OK, 1=WARN, 2=CRIT, 3=UNKNOWN
  • item: Der Servicename (ohne Leerzeichen oder mit Escaping/Quoting je nach Script; in der Praxis sind einfache, kurze Namen am stabilsten)
  • perfdata: Performance-Daten im Nagios-Format, z. B. value=42;warn;crit;min;max (kann auch leer sein)
  • text: Status-Text, der im Service angezeigt wird

Ein sehr kleiner Beispielcheck (Bash), der eine Queue-Länge aus einer Datei liest:

#!/usr/bin/env bash
set -euo pipefail

ITEM="my_queue"
FILE="/var/lib/myapp/queue_length"

if [[ ! -r "$FILE" ]]; then
  echo "3 $ITEM - Datei nicht lesbar: $FILE"
  exit 0
fi

value=$(cat "$FILE" | tr -dc '0-9')
warn=50
crit=100

state=0
if (( value >= crit )); then
  state=2
elif (( value >= warn )); then
  state=1
fi

echo "$state $ITEM value=$value;$warn;$crit;0; $value Elemente in Queue"

Warum exit 0 am Ende? Der Agent sammelt die Ausgabe. Selbst wenn Ihr Script „CRIT“ meldet, soll der Agentlauf als solcher nicht abbrechen.

Wo landen die Scripts auf dem Host?

Das genaue Local-Check-Verzeichnis hängt vom Betriebssystem und Agentenpaket ab. Checkmk dokumentiert es als „local checks directory“ des Agenten. Da wir in diesem Artikel vor allem das Ausrollen über die Agent Bakery betrachten, ist für Sie vor allem relevant, dass Ihre Datei nach dem Bake/Deploy im richtigen Local-Check-Pfad des Zielsystems ankommt.

Wenn Sie tiefer in die Grundlagen einsteigen möchten, lesen Sie auch unseren Überblick: Was ist Checkmk?

Script in der Checkmk-Instanz ablegen: der Pfad für „Deploy custom files with agent“

Damit Checkmk Ihre eigene Datei in der Agent Bakery anbietet, legen Sie sie innerhalb der Site in einem „custom files“-Verzeichnis ab.

Der vorgegebene Pfad ist:

/omd/sites/<site>/local/share/check_mk/agents/custom/myset/lib/local/my_local_check

Wichtig dabei:

  • Ersetzen Sie <site> durch den Site-Namen (z. B. checkmk).
  • myset ist ein frei wählbarer Ordnername für Ihr „Set“ an Custom Files.
  • lib/local/ ist (in dieser Struktur) der Zielpfad relativ zum Agenten-Verzeichnis, also dort, wo der Agent Local Checks erwartet.
  • Achten Sie auf Ausführbarkeit:
chmod 755 /omd/sites/<site>/local/share/check_mk/agents/custom/myset/lib/local/my_local_check
  • Nutzen Sie einen passenden Shebang (#!/usr/bin/env bash, python3 etc.) und testen Sie das Script lokal auf dem Zielsystem.

Hinweis zur Verifizierung: In Checkmk existieren je nach Version und Plattform mehrere Wege, Custom Files zu verteilen. Den oben genannten Pfad verwenden wir hier exakt so, wie er im Quellmaterial vorgegeben ist. Bitte prüfen Sie in Ihrer Checkmk-Version in der offiziellen Checkmk-Dokumentation, ob sich die erwartete Verzeichnisstruktur oder der Zielpfad für Local Checks in der Agent Bakery in Details unterscheidet (z. B. Windows vs. Linux).

Agent Bakery: Custom Files ausrollen und damit Checkmk konfigurieren

Sobald das Script im Custom-File-Verzeichnis liegt, können Sie es über die Regeln der Agent Bakery auf Hosts verteilen.

In der Weboberfläche finden Sie (je nach Edition/Version) in etwa:

  • Setup → Agents → Windows, Linux, Solaris, AIX (Agent Bakery)
  • Regel: Deploy custom files with agent

Dort wählen Sie Ihr „Set“ (myset) bzw. die Datei aus. Danach:

  1. Regel speichern
  2. Agenten backen (Bake)
  3. Agentenpaket/Updater an die Zielhosts ausrollen oder aktualisieren

Dieser Schritt ist die eigentliche „Anpassung“: Sie bringen Ihre Logik reproduzierbar auf viele Systeme und vermeiden Snowflake-Server.

Wenn Sie bereits Agent Bakery nutzen, passen auch Themen wie Ausschlussregeln oder sauberes Rollout gut dazu. Dazu haben wir einen passenden Praxisbezug: Hosts von globalen Services und Checks ausschließen.

Host-Tags nutzen: Scripts gezielt aktivieren und Checkmk personalisieren

„Ein Script für alle“ ist selten sinnvoll. Häufig wollen Sie den Check nur auf Hosts mit einer bestimmten Rolle ausrollen, etwa:

  • role:db
  • role:web
  • app:erp
  • env:prod

Schritt 1: Tag-Gruppe anlegen

In Checkmk legen Sie unter den Host-Tag-Einstellungen eine Tag-Gruppe an, z. B.:

  • Tag-Gruppe: Application
  • Tags: ERP, CRM, Fileservice

Um so ein Tag anzulegen, gehen Sie auf ‚Setup‘ in der linken, vertikalen Aktionsleiste, suchen dort nach dem Wort ‚Tags‘ und klicken auf den Menüpunkt ‚Tag‘ unter der Überschrift ‚Setup‘.

Custom Scripte in Checkmk deployen

Eine genauere Beschreibung des erstellen von Tags würde hier leider den Rahmen sprengen jedoch werden wir in Zukunft einen Beitrag verfassen, der dieses Thema etwas genauer behandelt.

Schritt 2: Tags am Host setzen

In der Host-Konfiguration wählen Sie dann z. B. Application: ERP aus.

Schritt 3: Regel auf Tag matchen

Ein Tag ist nur hilfreich, wenn diesem auch eine Funktion zugeordnet wird. Das tun Sie, indem Sie Ihr vorhin hochgeladenes Script, diesem Tag zuordnen. So wird Ihr Script dann auf alle Hosts angewendet, die dieses Tag ausgewählt haben.

So bleibt Ihre Personalisierung kontrollierbar: Sie können Checkmk personalisieren, ohne bei jedem neuen Host händisch nachzuarbeiten. Nebenbei hilft das auch bei der IT-Sicherheit, weil Sie Überwachung und Code-Verteilung sauber segmentieren.

Um Ihr Script dem Tag zuzuweisen, öffnen Sie nochmal Ihr Script in der Checkmk Weboberfläche. Dazu gehen Sie zunächst auf ‚Setup‘ >> unter der Überschrift ‚Agents‘ auf ‚Windows,Linux,Solaris,…‘.

Custom Scripte in Checkmk übernehmen

Hier gehen Sie dann auf den Knopf ‚Agent rules‘.

deploying Custom Scripts in Checkmk

In dieser Maske scrollen Sie nun runter, bis Sie die Überschrift ‚Agent rules > Generic agent options‘ sehen. Diesen wählen Sie aus und öffnen dann dort Ihr Script um dieses zu konfigurieren.

Eigene Scripte in Checkmk einfügen

Innerhalb der Konfigurationsmaske dieses Scriptes, gehen Sie nun zu dem Bereich ‚Host Tags‘, ziemlich weit unten in der Maske. Hier suchen Sie nun nach Ihrem Tag und wählen es aus, damit es dem Script zugewiesen wird.

Eigene Monitoring-Scripte in Checkmk einfügen: Checkmk personalisieren

Haben Sie das erledigt, gehen Sie oben links auf den Knopf speichern und dann aktivieren Sie die Änderungen über das gelbe Ausrufezeichen oben rechts.

Wenn Sie nun einen Host erstellen, dann können Sie dieses Tag auswählen und Ihr selbst erstelltes Script wird auf diesem Host installiert und angewendet.

Ein vollständiges Mini-Beispiel: Local Check für „letzter erfolgreicher Backup-Lauf“

Typischer Use Case: Ein Backup-Job schreibt nach Erfolg eine Timestamp-Datei. Ihr Check soll warnen, wenn der letzte Erfolg zu lange her ist.

#!/usr/bin/env bash
set -euo pipefail

ITEM="backup_last_success"
STAMP_FILE="/var/lib/backup/last_success.timestamp"
WARN_HOURS=26
CRIT_HOURS=50

if [[ ! -r "$STAMP_FILE" ]]; then
  echo "2 $ITEM - Statusdatei fehlt: $STAMP_FILE"
  exit 0
fi

last=$(cat "$STAMP_FILE")
now=$(date +%s)

# Erwartet Unix-Timestamp in der Datei
if ! [[ "$last" =~ ^[0-9]+$ ]]; then
  echo "3 $ITEM - Ungültiger Timestamp in $STAMP_FILE: $last"
  exit 0
fi

age_sec=$(( now - last ))
age_hours=$(( age_sec / 3600 ))

state=0
if (( age_hours >= CRIT_HOURS )); then
  state=2
elif (( age_hours >= WARN_HOURS )); then
  state=1
fi

echo "$state $ITEM age_hours=$age_hours;$WARN_HOURS;$CRIT_HOURS;0; Letzter erfolgreicher Lauf vor ${age_hours}h"

Vorteil: Sie bekommen eine eindeutige Serviceanzeige mit Perfdata, die Sie trendfähig graphen können.

Troubleshooting: wenn der Local Check nicht auftaucht

Wenn der Service in Checkmk nicht erscheint oder immer UNKNOWN bleibt, kommen die Ursachen meist aus wenigen Kategorien.

Prüfen, ob das Script überhaupt auf dem Host liegt

  • Wurde der Agent neu gebacken und verteilt?
  • Liegt die Datei im Local-Check-Verzeichnis des Hosts?
  • Ist sie ausführbar?

Auf Linux:

ls -l /usr/lib/check_mk_agent/local/
# oder je nach Installation der Agent-Pfad

(Der Pfad kann je nach Distribution/Installationsart abweichen. Entscheidend ist: Die Datei muss dort landen, wo der Agent die Local Checks ausführt.)

Script läuft, aber liefert keine Ausgabe

  • Testen Sie auf dem Host direkt:
/usr/lib/check_mk_agent/local/my_local_check
  • Prüfen Sie, ob Ihr Script bei Fehlern versehentlich mit exit 1/exit 2 aussteigt, bevor es eine Zeile ausgibt.
  • Schreiben Sie Debug-Ausgaben nicht auf STDOUT, sonst zerstören Sie das Format. Nutzen Sie für Debugging STDERR und fangen Sie es beim Test ab.

Rechte, Pfade, Abhängigkeiten

Local Checks laufen in der Regel in einer eingeschränkten Umgebung:

  • Pfade wie /usr/sbin fehlen manchmal in PATH
  • Tools wie jq, curl, python3 sind nicht überall installiert
  • Zugriff auf Dateien/APIs scheitert an Rechten

Praxis-Tipp: Verwenden Sie absolute Pfade (/usr/bin/curl) und prüfen Sie benötigte Pakete. Für Security-nahe Checks vermeiden Sie, dass Credentials im Script hartcodiert sind; nutzen Sie stattdessen Root-only Dateien mit restriktiven Rechten.

Service wird in Checkmk nicht erkannt

  • Führen Sie eine Service-Erkennung auf dem Host aus (Discovery) und übernehmen Sie die Services.
  • Prüfen Sie, ob der Host durch Regeln (z. B. Ausschlüsse) betroffen ist.

„Falsche Positives“ und flackernde Checks

Gerade bei selbstgeschriebenen Checks passieren leicht Schwellwertfehler oder instabile Datenquellen. Wenn Sie das sauber in den Griff bekommen wollen, hilft unser Beitrag zu False Positives in Checkmk vermeiden.

Betrieb & Qualität: so bleiben eigene Checks wartbar

Eigene Checks sind Code im Betrieb. Ein paar Regeln sparen später Zeit:

  • Versionieren Sie Scripts (Git) und dokumentieren Sie Eingaben/Ausgaben.
  • Stabile Servicenamen: Ändern Sie item nicht leichtfertig, sonst erzeugen Sie neue Services.
  • Timeouts: API-Checks ohne Timeout blockieren den Agentenlauf. Setzen Sie bei curl immer --max-time.
  • Fehlertexte für Menschen: Ein CRIT „exit code 1“ hilft niemandem. Schreiben Sie in den Text, was fehlt und wo.
  • Security: Geben Sie keine Secrets als Perfdata/Text aus. Wenn Sie Tokens brauchen, lesen Sie sie aus Root-only Dateien.

Wenn Sie Checkmk generell stärker an Ihre Umgebung anpassen möchten, lohnt sich ein Blick in unseren Artikel über Erweiterungen und Praxisnutzen: Effizientes IT Monitoring: Einblick und Erweiterungen für Checkmk.

Eigene Checks erstellen oder lieber Plugin nutzen?

Bevor Sie selbst entwickeln, prüfen Sie:

  • Gibt es bereits ein offizielles Checkmk-Plugin oder ein bewährtes Community-Plugin?
  • Passt ein vorhandener Check mit Regeln/Parametern?

Ein guter Mittelweg: Starten Sie als Local Check, und wenn das Thema größer wird, migrieren Sie später auf einen Agenten-Plugin-Ansatz mit eigener Check-Logik serverseitig. Für viele interne Use Cases reicht ein sauber gebauter Local Check aber dauerhaft.

Wenn Sie Checkmk in Ihrer Umgebung professionell aufsetzen oder Ihre bestehende Überwachung konsolidieren möchten, finden Sie auf unserer Leistungsseite Checkmk bei ADMIN INTELLIGENCE praxisnahe Unterstützung rund um Checkmk konfigurieren, Checkmk personalisieren und sichere Betriebsprozesse.

Weitere praktische Anleitungen rund um Monitoring, Anpassung und Überwachung finden Sie auf https://blog.admin-intelligence.de/. Wenn Sie bei Custom Checks, Agent Bakery oder einer sauberen Einbindung in Ihre IT-Sicherheit Unterstützung brauchen, erreichen Sie uns auch direkt über https://www.admin-intelligence.de/kontakt/.