Checkmk
to checkmk.com

1. Warum eigene Checks?

Checkmk überwacht durch die große Anzahl an mitgelieferten Check-Plugins bereits sehr viele relevante Daten. Dennoch ist jede IT-Umgebung einzigartig, so dass sich oft sehr individuelle Anforderungen ergeben. Mit den lokalen Checks (local checks) sind Sie in der Lage, den Agenten auf dem Ziel-Host zu erweitern, indem Sie schnell und einfach eigene Services erstellen.

Diese lokalen Plugins unterscheiden sich dabei in einem wesentlichen Punkt von anderen Checks: Die Berechnung des Status erfolgt direkt auf dem Host, auf dem die Daten auch abgerufen werden. Dadurch entfällt die komplexe Erstellung von Checks in Python und Sie sind bei der Wahl der Skriptsprache völlig frei.

2. Einen einfachen lokalen Check schreiben

2.1. Skript erstellen

Sie können einen lokalen Check in jeder beliebigen Programmiersprache schreiben, die der Ziel-Host unterstützt. Das Skript muss so konstruiert sein, dass es pro Check eine Statuszeile ausgibt, die aus vier Teilen besteht. Hier ist ein Beispiel:

0 "My service" myvalue=73 My output text which may contain spaces

Die vier Teile sind durch Leerzeichen getrennt und haben folgende Bedeutung:

Beispielwert Bedeutung Beschreibung

0

Status

Der Zustand des Services wird als Ziffer angegeben: 0 für OK, 1 für WARN, 2 für CRIT und 3 für UNKNOWN. Alternativ ist es möglich, den Status dynamisch berechnen zu lassen: dann wird die Ziffer durch ein P ersetzt.

"My service"

Service-Name

Der Name des Services, wie er in Checkmk angezeigt wird, in der Ausgabe des Checks in doppelten Anführungszeichen.

myvalue=73;65;75

Wert und Metriken

Metrikwerte zu den Daten. Sie finden im Kapitel zu den Metriken näheres zum Aufbau. Alternativ können Sie ein Minuszeichen setzen, wenn der Check keine Metriken ausgibt.

My output text which may contain spaces

Statusdetail

Details zum Status, wie sie in Checkmk angezeigt werden. Dieser Teil kann auch Leerzeichen enthalten.

Zwischen den vier Teilen dieser Ausgabe muss immer genau ein Leerzeichen (ASCII 0x20) stehen. Innerhalb der Statusdetails können beliebige Leerzeichen in beliebiger Reihenfolge verwendet werden.

Important

Abweichungen von der soeben beschriebenen Spezifikation können funktionieren, müssen es aber nicht. Künftige Versionen von Checkmk werden dieses Ausgabeformat möglicherweise erzwingen und abweichende lokale Checks ignorieren.

Wenn Sie wegen einer möglichen Ausgabe unsicher sind, können Sie diese einfach testen, indem Sie ein kleines Skript mit dem Kommando echo schreiben. Fügen Sie in das echo-Kommando Ihre Ausgabe ein, die Sie testen möchten. Unser Beispiel verwendet außen die doppelten Anführungszeichen, da innerhalb stehende Variablen (Umgebungsvariablen und im Skript gesetzte) ausgewertet werden. Das hat zur Folge, dass Sie die Anführungszeichen für den Service-Namen mit \ maskieren müssen, damit diese Zeichen nicht von der Shell als Ende und Anfang eines Strings interpretiert (und damit aus der Ausgabe entfernt) werden:

mylocalcheck
#!/bin/bash
echo "0 \"My 1st service\" - This static service is always OK"

Für Windows-Hosts sieht so ein Testskript sehr ähnlich aus:

mylocalcheck.bat
@echo off
echo 0 "My 1st service" - This static service is always OK

Beide Skripte führen in der Ausgabe zum selben Ergebnis:

0 "My 1st service" - This static service is always OK

Für Checkmk ist nur diese Ausgabe relevant, nicht wie Sie diese Ausgabe erzeugt haben.

Sie können übrigens beliebig viele Ausgaben in einem Skript erzeugen. Für jede ausgegebene Zeile wird dann ein eigener Service in Checkmk erstellt. Daher sind in der Ausgabe auch keine Zeilenumbruchzeichen erlaubt — es sei denn, sie sind maskiert, zum Beispiel für eine mehrzeilige Ausgabe in Checkmk.

Wie Sie prüfen, ob das lokale Skript vom Agenten richtig aufgerufen wird, sehen Sie in der Fehleranalyse.

2.2. Skript verteilen

Nachdem das Skript geschrieben ist, können Sie es an die entsprechenden Hosts verteilen. Der Pfad unterscheidet sich je nach Betriebssystem. Eine Liste der Pfade finden Sie in Dateien und Verzeichnisse weiter unten.

Vergessen Sie nicht, das Skript auf Unix-artigen Systemen ausführbar zu machen. Der Pfad in dem Beispiel bezieht sich auf Linux:

root@linux# chmod +x /usr/lib/check_mk_agent/local/mylocalcheck

Wenn Sie die Agentenbäckerei nutzen, können Sie das Skript auch regelbasiert verteilen. Mehr zur Regelerstellung erfahren Sie im Kapitel Verteilung über die Agentenbäckerei.

2.3. Den Service ins Monitoring aufnehmen

Bei jedem Aufruf des Checkmk-Agenten wird auch der im Skript enthaltene lokale Check ausgeführt und an die Ausgabe des Agenten angehängt. Die Service-Erkennung funktioniert also wie bei anderen Services auch automatisch:

localchecks services

Nachdem Sie den Service ins Monitoring übernommen und die Änderungen aktiviert haben, ist die Einrichtung eines selbst erstellten Services mit Hilfe eines lokalen Checks bereits abgeschlossen. Falls es bei der Service-Erkennung zu Problemen kommen sollte, kann Ihnen die Fehleranalyse weiterhelfen.

3. Erweiterte Funktionen

3.1. Metriken

Sie können in einem lokalen Check auch Metriken festlegen. Damit diese ausgewertet werden, muss der zurückgelieferte Status P sein. Die Berechnung des Zustands erfolgt dann durch Checkmk.

Die allgemeine Syntax für Metrikdaten ist:

metricname=value;warn;crit;min;max

wobei value der aktuelle Wert ist, warn und crit die (oberen) Schwellwerte festlegen sowie min und max den Wertebereich fixieren — zum Beispiel so:

count=73;80;90;0;100

Die Werte werden mit Semikolon getrennt. Alle Werte mit Ausnahme von value sind optional. Wird ein Wert nicht benötigt, so bleibt das Feld leer bzw. wird am Ende weggelassen, wie im Folgenden für warn, crit und max:

count=42;;;0

Hinweis: In den kommerziellen Editionen können die Werte für min und max zwar gesetzt werden — aber nur aus Kompatibilitätsgründen. Die Begrenzung des zugehörigen Graphen auf einen bestimmten Wertebereich hat in den kommerziellen Editionen keine Auswirkungen.

3.2. Metriknamen

Bei der Wahl des - hier im Beispiel metricname genannten - Bezeichners dieser Metrik sollten Sie besondere Vorsicht walten lassen. Wir empfehlen, die Bezeichner mit einem Präfix zu versehen, um Überschneidungen mit bereits in Checkmk vorhandenen Metriken zu verhindern.

Statt also beispielsweise eine Metrik, die die Zahl von derzeit wartenden Anfragen in einer von Ihnen überwachten Queue angibt, einfach 'current' zu nennen, empfehlen wir hier einen klareren Bezeichner mit einem Präfix - etwa: mycompany_current_requests.

Sollten Sie hier nämlich einen Bezeichner wählen, der bereits in Checkmk vorhanden ist, würde die Darstellung Ihrer Metriken in Graphen mit den bereits vorliegenden Definitionen überschrieben.

Natürlich können Sie auch absichtlich eine bereits vorhandene Metrik aus Checkmk wiederverwenden. Eine Metrik für eine elektrische Spannung könnten Sie also bspw. durch die Verwendung des Bezeichners current ohne weiteres in Ihrem lokalen Check nutzen. Im Zweifelsfall müssen Sie sich die aktuelle Definition dieser Metrik aber in ~/lib/python3/cmk/gui/plugins/metric selbsttätig heraussuchen.

OMD[mysite]:~$ grep -r -A 4 'metric_info\["current"\]' ./lib/python3/cmk/gui/plugins/metrics/

3.3. Mehrere Metriken

Sie können auch mehrere Metriken ausgeben lassen. Diese werden dann durch das "Pipe"-Zeichen | getrennt, zum Beispiel so:

count1=42|count2=23

Achtung: Auf Windows-Hosts müssen Sie diesen Pipes im Skript noch einen Zirkumflex (^) voranstellen, damit diese Pipes auch in der Ausgabe ankommen.

mylocalcheck.bat
@echo off
echo 0 "My 2nd service" count1=42^|count2=23 A service with 2 graphs

Eine komplette Ausgabe mit zwei Metriken sieht dann etwa so aus:

root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
0 "My 2nd service" count1=42|count2=23 A service with 2 graphs

Nachdem Sie auch den neuen Service ins Monitoring aufgenommen haben, sehen Sie in der Service-Liste im Feld Summary den Text zum Statusdetail. Nach Anklicken des Services wird die Seite mit den Service-Details gezeigt. Die Metriken zeigt das Feld Details, und darunter sehen Sie die von Checkmk automatisch erzeugten Service-Graphen:

localchecks graphs2

3.4. Status dynamisch berechnen lassen

In den vorherigen Kapiteln haben Sie erfahren, wie man für Metriken Schwellwerte festlegen und diese auch in den Graphen anzeigen lassen kann. Der nächste naheliegende Schritt ist es nun, diese Schwellwerte für eine dynamische Berechnung des Service-Zustands zu nutzen. Checkmk bietet genau diese Möglichkeit, um einen lokalen Check auszubauen.

Wenn Sie im ersten Feld der Ausgabe, das den Status bestimmt, statt einer Ziffer den Buchstaben P übergeben, wird der Service-Zustand anhand der übergebenen Schwellwerte berechnet.

Eine Ausgabe würde dann so aussehen:

root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My 1st dynamic service" count=40;30;50 Result is computed from two threshold values
P "My 2nd dynamic service" - Result is computed with no values

… und die Anzeige in einer Service-Ansicht so:

localchecks dynsrv

Die Anzeige unterscheidet sich in zwei Punkten von derjenigen, die bisher zu sehen war:

  • Für Services im Zustand WARN oder CRIT zeigt die Summary des Services alle wichtigen Informationen der Metriken (Name, Wert, Schwellwerte). So können Sie immer nachvollziehen, wie dieser Zustand aus einem Wert berechnet wurde. Für alle anderen Zustände werden die Metrikinformationen nur im Feld Details angezeigt.

  • Wenn keine Metriken übergeben werden, ist der Service-Zustand immer OK.

3.5. Obere und untere Schwellwerte

Manche Parameter haben nicht nur obere, sondern auch untere Schwellwerte. Ein Beispiel dafür ist die Luftfeuchtigkeit. Für solche Fälle bietet der lokale Check die Möglichkeit, jeweils zwei Schwellwerte für die Zustände WARN und CRIT zu übergeben. Sie werden durch einen Doppelpunkt getrennt und stellen jeweils den unteren und den oberen Schwellwert dar.

In der allgemeinen Syntax sieht das so aus:

metricname=value;warn_lower:warn_upper;crit_lower:crit_upper

… im Beispiel so:

root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My 3rd service" humidity=37;40:60;30:70 A service with lower and upper thresholds

… und in der Anzeige einer Service-Ansicht so:

localchecks lower

Falls es Ihnen nur um untere Schwellwerte geht, lassen Sie die Felder der oberen Schwellwerte weg:

root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My 4th dynamic service" count_lower=37;40:;30: A service with lower thresholds only

Mit dieser Ausgabe legen Sie fest, dass der Service bei einem Wert kleiner 40 WARN und kleiner 30 CRIT werden soll: beim festgelegten Wert 37 wird der Service also den WARN-Zustand erhalten.

3.6. Mehrzeilige Ausgaben

Auch die Option, die Ausgabe über mehrere Zeilen zu verteilen, steht Ihnen zur Verfügung. Da Checkmk unter Linux läuft, können Sie mit der Escape-Sequenz \n arbeiten, um einen Zeilenumbruch zu erzwingen. Auch wenn Sie, bedingt durch die Skriptsprache, den Backslash selbst maskieren müssen, wird das von Checkmk korrekt interpretiert:

root@linux# /usr/lib/check_mk_agent/local/mylocalcheck
P "My service" humidity=37;40:60;30:70 My service output\nA line with details\nAnother line with details

In den Details des Services können Sie dann diese zusätzlichen Zeilen unter der Summary sehen:

localchecks srv details

3.7. Asynchron ausführen und Ausgabe zwischenspeichern

Die Ausgabe lokaler Checks kann, wie auch die von Agenten-Plugins, zwischengespeichert werden (caching). Das kann nützlich sein, wenn Skripte längere Zeit zur Ausführung benötigen. Ein solches Skript wird dann asynchron und nur in einem definierten Zeitintervall ausgeführt und die letzte Ausgabe zwischengespeichert. Wird der Agent vor Ablauf der Zeit erneut abgefragt, verwendet er für den lokalen Check diesen Cache und liefert ihn in der Agentenausgabe zurück.

Hinweis: Das Caching steht nur für AIX, FreeBSD, Linux, OpenWrt und Windows zur Verfügung.

Konfiguration unter Linux

Unter Linux oder einem anderen Unix-artigen Betriebssystem kann jedes Plugin asynchron ausgeführt werden. Für einen lokalen Check ist die notwendige Konfiguration sehr ähnlich zu der eines Plugins. Legen Sie dazu ein Unterverzeichnis an, das so heißt, wie die Anzahl der Sekunden, die die Ausgabe zwischengespeichert werden soll und legen Sie Ihr Skript in diesem Unterverzeichnis ab.

In folgenden Beispiel wird der lokale Check nur alle 10 Minuten (600 Sekunden) ausgeführt:

root@linux# /usr/lib/check_mk_agent/local/600/mylocalcheck
2 "My cached service" count=4 Some output of a long running script

Die zwischengespeicherten Daten werden in ein Cache-Verzeichnis geschrieben.

Für einen Service, der zwischengespeicherte Daten liefert, werden die Cache-spezifischen Informationen in der Service-Ansicht hinzugefügt:

localchecks srv cached

Konfiguration unter Windows

Unter Windows erfolgt die Konfiguration ebenfalls analog zu der eines Plugins. Statt mit einem speziellen Unterverzeichnis wie bei Linux & Co werden die Optionen in einer Konfigurationsdatei gesetzt:

C:\ProgramData\checkmk\agent\check_mk.user.yml
local:
    enabled: yes
    execution:
        - pattern     : $CUSTOM_LOCAL_PATH$\mylocalcheck.bat
          async       : yes
          run         : yes
          cache_age   : 600

Wie Sie oben sehen, können Sie unter Windows die asynchrone Ausführung (mit async) und das Zeitintervall (mit cache_age) getrennt konfigurieren.

Alternativ können Sie die Konfiguration unter Windows auch in der Agentenbäckerei durchführen.

4. Verteilung über die Agentenbäckerei

CEE Wenn Sie die Agentenbäckerei bereits nutzen, können Sie die Skripte mit lokalen Checks auch über diesen Weg an mehrere Hosts verteilen.

Erstellen Sie dazu auf dem Checkmk-Server als Instanzbenutzer unterhalb von ~/local/share/check_mk/agents/ zuerst das Verzeichnis custom und darin für jedes Paket von lokalen Checks einen Unterverzeichnisbaum:

OMD[mysite]:~$ cd ~/local/share/check_mk/agents
OMD[mysite]:~$ ~/local/share/check_mk/agents$ mkdir -p custom/mycustompackage/lib/local/

Das Paketverzeichnis im obigen Beispiel ist mycustompackage. Darunter markiert das lib-Verzeichnis das Skript als Plugin oder lokalen Check. Das nachfolgende Verzeichnis local ordnet die Datei dann eindeutig zu. Legen Sie in diesem Verzeichnis das Skript mit dem lokalen Check ab.

Wichtig: Unter Linux können Sie die asynchrone Ausführung analog konfigurieren wie im vorherigen Kapitel beschrieben, indem Sie nun unter custom/mycustompackage/lib/local/ ein Verzeichnis mit der Sekundenzahl des Ausführungsintervalls erzeugen und dort das Skript ablegen. Unter Windows können Sie dafür die Regelsätze Set execution mode for plugins and local checks und Set cache age for plugins and local checks nutzen. Diese und weitere Regelsätze für lokale Checks unter Windows finden Sie in der Agentenbäckerei unter Agent rules > Windows Agent.

In der Konfigurationsumgebung von Checkmk wird dann das Paketverzeichnis mycustompackage als neue Option angezeigt: Öffnen Sie Setup > Agents > Windows, Linux, Solaris, AIX, erstellen Sie eine neue Regel mit Agents > Agent rules > Generic options > Deploy custom files with agent und wählen Sie das eben erstellte Paket aus:

localchecks custom

Checkmk wird nun selbstständig den lokalen Check im Installationspaket der jeweiligen Betriebssysteme richtig einordnen. Nachdem Sie die Änderungen aktiviert und die Agenten gebacken haben, sind Sie mit der Konfiguration auch schon fertig. Die Agenten müssen nun nur noch neu verteilt werden.

5. Fehleranalyse

5.1. Skript testen

Wenn Sie bei einem selbst geschriebenen Skript auf Probleme stoßen, sollten Sie die folgenden potentiellen Fehlerquellen prüfen:

  • Liegt das Skript im richtigen Verzeichnis?

  • Ist das Skript ausführbar und stimmen die Zugriffsberechtigungen? Das ist vor allem relevant, wenn Sie den Agenten oder das Skript nicht unter root oder dem LocalSystem-Konto ausführen.

  • Ist die Ausgabe konform zur vorgegebenen Syntax? Die Ausgabe des lokalen Checks muss der Syntax entsprechen, wie sie in den Kapiteln Skript erstellen und Erweiterte Funktionen beschrieben ist. Andernfalls kann die fehlerfreie Ausführung nicht garantiert werden.

    Probleme und Fehler können insbesondere dann entstehen, wenn ein lokaler Check eine Aufgabe erfüllen soll, die ein vollwertiges Check-Plugin erfordert, beispielsweise, wenn die Ausgabe des lokalen Checks selbst einen Sektions-Header (section header) enthält oder die Definition eines Host-Namens, wie er beim Transport von Piggyback-Daten verwendet wird.

Tip

Beim direkten Aufruf des Agentenskripts oder des Plugins in einer Shell unter Linux stehen möglicherweise andere Umgebungsvariablen zur Verfügung als beim Aufruf durch den Agent Controller des Checkmk-Agenten. Unter Windows kommt hinzu, dass der Agent Controller unter dem LocalSystem-Konto läuft, der Aufruf im Terminal aber unter einem normalen Benutzer oder Administrator erfolgt. Zusätzlich zur anderen Umgebung kann dies fehlende Berechtigungen bedeuten. Um die Ausgabe des Agentenskripts möglichst nahe an den Bedingungen zu analysieren, unter denen der Checkmk-Agent aufgerufen wird, sollten Sie daher nach Möglichkeit den Agent Controller im Dump-Modus verwenden.

5.2. Agentenausgabe auf dem Ziel-Host testen

Wenn das Skript selbst korrekt ist, können Sie den Agenten auf dem Host ausführen. Bei Unix-artigen Betriebssystemen, wie Linux, BSD und so weiter, bietet sich der Befehl grep an, um nach einem bestimmten Textmuster zu suchen. Mit der Option -A bestimmen Sie die Anzahl der zusätzlichen Zeilen, die nach einem Treffer angezeigt werden sollen. Sie können diese Zahl entsprechend der Anzahl der erwarteten Ausgabezeilen anpassen:

root@linux# cmk-agent-ctl dump | grep -v grep | grep -A2 "<<<local"
<<<local:sep(0)>>>
P "My service" humidity=37;40:60;30:70 My service output\nA line with details\nAnother line with details
cached(1618580356,600) 2 "My cached service" count=4 Some output of a long running script

In der letzten Zeile erkennen Sie einen zwischengespeicherten Service an der vorangestellten cache-Information mit der aktuellen Unixzeit und dem Ausführungsintervall in Sekunden.

Unter Windows können Sie mit der PowerShell und dem „Cmdlet“ Select-String ein sehr ähnliches Resultat erreichen wie mit dem grep-Befehl unter Linux. Im folgenden Befehl bestimmen die beiden Ziffern hinter dem Parameter Context wie viele Zeilen vor und nach dem Treffer ausgegeben werden sollen:

PS C:\Program Files (x86)\checkmk\service> ./cmk-agent-ctl.exe dump | Select-String -Pattern "<<<local" -Context 0,3
> <<<local:sep(0)>>>
  0 "My 1st service" - This static service is always OK

  cached(1618580520,600) 1 "My cached service on Windows" count=4 Some output of a long running script
Tip

Je nach Umgebung, verwendeter Programmiersprache, Windows-Version und einigen weiteren Bedingungen, sind Sie oft unter Windows mit dem Zeichensatz UTF-16 konfrontiert. Zudem ist dort häufig die Kombination aus Carriage Return und Line Feed für Zeilenumbrüche anzutreffen. Checkmk als Linux-Anwendung erwartet aber ohne wenn und aber UTF-8 und einfache Line Feeds. Der Zeichensatz-bezogenen Fehlersuche widmen wir im Artikel zu Spool-Verzeichnis ein eigenes Kapitel.

5.3. Agentenausgabe auf dem Checkmk-Server testen

Zuletzt können Sie die Verarbeitung der Skriptausgaben auch auf dem Checkmk-Server mit dem Befehl cmk testen — einmal die Service-Erkennung:

OMD[mysite]:~$ cmk -IIv --detect-plugins=local mycmkserver
Discovering services and host labels on: mycmkserver
mycmkserver:
...
+ EXECUTING DISCOVERY PLUGINS (1)
  2 local
SUCCESS - Found 2 services, no host labels

… und mit einem ähnlichen Befehl auch die Verarbeitung der Serviceausgabe:

OMD[mysite]:~$ cmk -nv --detect-plugins=local mycmkserver
Checkmk version 2.0.0p2
+ FETCHING DATA
...
+ PARSE FETCHER RESULTS
Received no piggyback data
My cached service    Some output of a long running script(!!), Cache generated 6 minutes 52 seconds ago, Cache interval: 10 minutes 0 seconds, Elapsed cache lifespan: 68.71%
My service           My service output\, humidity: 37.00 (warn/crit below 40.00/30.00)(!)

Für beide Befehle haben wir die Ausgabe um für dieses Thema nicht relevante Zeilen gekürzt.

Wenn es in den lokalen Checks Fehler gibt, wird Checkmk Sie in der Serviceausgabe darauf hinweisen. Das gilt sowohl für fehlerhafte Metriken, als auch für falsche, unvollständige Informationen in der Skriptausgabe oder einen ungültigen Status. Diese Fehlermeldungen sollen Ihnen helfen, die Fehler in den Skripten schnell zu identifizieren.

6. Dateien und Verzeichnisse

6.1. Skript-Verzeichnis auf dem Ziel-Host

Pfad Betriebssystem

/usr/check_mk/lib/local/

AIX

/usr/local/lib/check_mk_agent/local/

FreeBSD

/usr/lib/check_mk_agent/local/

HP-UX, Linux, OpenBSD, OpenWrt und Solaris

%ProgramData%\checkmk\agent\local

Windows

6.2. Cache-Verzeichnis auf dem Ziel-Host

Hier werden zwischengespeicherte Daten einzelner Sektionen, u.a. der local Sektion, abgelegt und dem Agenten, solange die Daten gültig sind, bei jeder Ausführung wieder angehängt.

Pfad Betriebssystem

/tmp/check_mk/cache/

AIX

/var/run/check_mk/cache/

FreeBSD

/var/lib/check_mk_agent/cache/

Linux, OpenWrt und Solaris

Auf dieser Seite