Checkmk
English
masterlatest (2.3.0)2.2.02.0.01.6.0
to checkmk.com

1. Einleitung

Der Checkmk-Server erreicht Hosts im Monitoring üblicherweise über eine TCP-Verbindung auf Port 6556. Seit Version 2.1.0 lauscht auf diesem Port in den meisten Fällen der Agent Controller, welcher die Agentenausgabe über eine TLS verschlüsselte Verbindung weiterleitet. Es gibt jedoch Umgebungen — zum Beispiel bei sehr schlanken Containern, Legacy- oder Embedded-Systemen — , in der der Agent Controller nicht verwendet werden kann. Im Legacy-Modus kommt hier (x)inetd zum Einsatz, der bei jeder Anfrage das Agentenskript ausführt, die Ausgabe im Klartext überträgt und dann die Verbindung wieder schließt.

In vielen Fällen verlangen Richtlinien, dass Sicherheitsaspekte wie der Verzicht auf die Übertragung von Daten im Klartext berücksichtigt werden müssen. So kann ein Angreifer zwar mit den Füllständen von Dateisystemen meist wenig anfangen, aber Prozesstabellen und Listen von anstehenden Sicherheitsupdates können helfen, Angriffe zielgerichtet vorzubereiten. Darüber hinaus sollen oft keine zusätzlichen Ports geöffnet und stattdessen vorhandene Kommunikationskanäle genutzt werden.

Die universelle Methode, um solche Transportwege an Checkmk anzudocken, sind die Datenquellenprogramme (datasource programs). Die Idee ist sehr einfach: Sie geben Checkmk die Kommandozeile eines Befehls. Anstelle der Verbindung auf Port 6556 führt Checkmk diesen Befehl aus. Dieser produziert die Agentendaten auf der Standardausgabe, welche dann von Checkmk genauso verarbeitet werden, als kämen sie von einem „normalen“ Agenten. Da Änderungen der Datenquellen meist Transportwege betreffen, ist es wichtig, dass Sie den Host in der Setup-GUI auf der Einstellung API integrations if configured, else Checkmk agent belassen.

Die Modularität von Checkmk hilft, diese Anforderungen zu erfüllen. Letztlich kann die Klartextausgabe des Agentenskriptes über beliebige Wege transportiert werden. Hier sind einige Beispiele, mit denen Checkmk-Anwender Daten vom Agenten zum Checkmk-Server bekommen:

  • per E-Mail

  • per HTTP-Zugriff vom Server aus

  • per HTTP-Upload vom Agenten aus

  • per Zugriff auf eine Datei, die per rsync zum Server kopiert wurde

  • per Skript, welches die Daten per HTTP von einem Webdienst abholt

Ein weiterer Anwendungsbereich für Datenquellenprogramme sind Systeme, die keine Agenten-Installation zulassen, aber Zustandsdaten per REST-API oder über eine Telnet-Schnittstelle herausgeben. In solchen Fällen können Sie ein Datenquellenprogramm schreiben, das die vorhandene Schnittstelle abfragt und aus den gewonnenen Daten Agenten-Output generiert.

2. Schreiben von Datenquellenprogrammen

2.1. Das einfachst mögliche Programm

Das Schreiben und Einbinden eines eigenen Datenquellenprogramms ist nicht schwer. Sie können jede von Linux unterstützte Skript- und Programmiersprache verwenden. Legen Sie das Programm am besten im Verzeichnis ~/local/bin an, dann wird es immer automatisch ohne Pfadangabe gefunden.

Folgendes erstes minimale Beispiel heißt myds und erzeugt einfache fiktive Monitoring-Daten. Anstatt einen neuen Transportweg zu integrieren, erzeugt es Monitoring-Daten selbst. Diese enthalten als einzige Sektion <<<df>>>. mit der Information zu einem einzigen Dateisystem der Größe 100kB und dem Namen My_Disk. Das Ganze ist ein Shell-Skript mit drei Zeilen:

~/local/bin/myds
#!/bin/sh
echo '<<<df>>>'
echo 'My_Disk  foobar  100 70 30  70% /my_disk'

Vergessen Sie nicht, Ihr Programm ausführbar zu machen:

OMD[mysite]:~$ chmod +x local/bin/myds

Legen Sie nun im Setup zum Test einen Host an — z.B. myserver125. Dieser benötigt keine IP-Adresse. Um zu verhindern, dass Checkmk den Namen myserver125 per DNS aufzulösen versucht, tragen Sie diesen Namen als explizite „IP-Adresse“ ein.

Legen Sie dann eine Regel im Regelsatz Setup > Agents > Other integrations > Individual program call instead of agent access an, welche für diesen Host gilt und tragen Sie myds als aufzurufendes Programm ein:

Eingabemaske für einen individuellen Befehl.

Wenn Sie jetzt in der Setup-GUI zur Service-Konfiguration des Hosts wechseln, sollten Sie genau einen Service sehen, der für die Überwachung bereitsteht:

Der neue Service wurde erkannt.

Nehmen Sie diesen in die Überwachung auf, aktivieren Sie die Änderungen und Ihr erstes Datenquellenprogramm läuft. Sobald Sie jetzt testweise die Daten ändern, die das Programm auswirft, wird das der nächste Check des Dateisystems My_Disk sofort anzeigen.

2.2. Fehlerdiagnose

Wenn etwas nicht funktioniert, können Sie auf der Kommandozeile mit cmk -D die Konfiguration des Hosts überprüfen und feststellen, ob Ihre Regel greift:

OMD[mysite]:~$ cmk -D myserver125

myserver125
Addresses:              myserver125
Tags:                   [address_family:ip-v4-only], [agent:cmk-agent], [criticality:prod], [ip-v4:ip-v4], [networking:lan], [piggyback:auto-piggyback], [site:mysite], [snmp_ds:no-snmp], [tcp:tcp]
Host groups:            check_mk
Agent mode:             Normal Checkmk agent, or special agent if configured
Type of agent:
Program: myds

Mit einem cmk -d können Sie den Abruf der Agentendaten — und damit das Ausführen Ihres Programms — auslösen:

OMD[mysite]:~$ cmk -d myserver125
<<<df>>>
My_Disk  foobar  100 70 30  70% /my_disk

Ein doppeltes -v sollte eine Meldung erzeugen, dass Ihr Programm aufgerufen wird:

OMD[mysite]:~$ cmk -vvd myserver125
Calling: myds
<<<df>>>
My_Disk  foobar  100 70 30  70% /my_disk

2.3. Übergeben des Host-Namens

Das Programm aus dem ersten Beispiel funktioniert zwar, ist aber nicht sehr praxistauglich, denn es gibt immer die gleichen Daten aus, egal für welchen Host es aufgerufen wird.

Ein echtes Programm, dass z.B. per HTTP von irgendwoher Daten holt, benötigt dazu zumindest den Namen des Hosts, für den Daten geholt werden sollen. Sie können diesen in der Kommandozeile mit dem Platzhalter $HOSTNAME$ übergeben lassen:

Übergabe des Host-Namens mit dem Makro $HOSTNAME$.

In diesem Beispiel bekommt das Programm myds den Host-Namen als erstes Argument geliefert. Folgendes Beispielprogramm gibt diesen zum Testen in Form eines lokalen Checks aus. Es greift per $1 auf das erste Argument zu und speichert es zum Zwecke der Übersicht in der Variable $HOST_NAME. Diese wird dann in die Plugin-Ausgabe des lokalen Checks eingesetzt:

~/local/bin/myds
#!/bin/sh
HOST_NAME="$1"

echo '<<<local>>>'
echo "0 Hostname - My name is ${HOST_NAME}"

Die Service-Erkennung wird jetzt einen neuen Service vom Typ local finden, in dessen Ausgabe der Host-Name zu sehen ist:

Die Service-Erkennung findet den neuen Service, der nun den übergebenen Host-Namen als Information ausgibt.

Der Schritt zu einem echten Datenquellenprogramm, das z.B. Daten per HTTP mit dem Befehl curl holt, ist jetzt nicht mehr weit. Folgende Platzhalter sind in der Befehlszeile der Datenquellenprogramme erlaubt:

$HOSTNAME$

Der Host-Name, wie er im Setup konfiguriert ist.

$HOSTADDRESS$

Diejenige IP-Adresse des Hosts, über die er überwacht wird.

$_HOSTTAGS$

Die Liste aller Host-Merkmale durch Leerzeichen getrennt. Setzen Sie dieses Argument auf jeden Fall in Anführungszeichen, um es vor einem Aufteilen durch die Shell zu schützen.

Falls Sie den Host dual per IPv4 und IPv6 überwachen, sind unter Umständen noch folgende Makros für Sie interessant:

$_HOSTADDRESS_4$

Die IPv4-Adresse des Hosts

$_HOSTADDRESS_6$

Die IPv6-Adresse des Hosts

$_HOSTADDRESS_FAMILY$

Die Ziffer 4, wenn die zur Überwachung genutzte Adresse die IPv4-Adresse ist, ansonsten 6.

2.4. Fehlerbehandlung

Egal, welchen Beruf Sie in der IT ausüben — den meisten Teil Ihrer Zeit werden Sie sich mit Fehlern und Problemen befassen. Und auch Datenquellenprogramme bleiben davon nicht verschont. Vor allem bei Programmen, die per Netzwerk Daten beschaffen, ist ein Fehler keineswegs unrealistisch.

Damit Ihr Programm Checkmk so einen Fehler sauber mitteilen kann, gilt Folgendes:

  1. Jeder Exit Code außer 0 wird als Fehler gewertet.

  2. Fehlermeldungen werden auf dem Standardfehlerkanal (stderr) erwartet.

Falls ein Datenquellenprogramm scheitert,

  • verwirft Checkmk die kompletten Nutzdaten der Ausgabe,

  • setzt den Checkmk-Service auf CRIT und zeigt dort die Daten von stderr als Fehler an,

  • bleiben die eigentlichen Services auf dem alten Stand (und werden mit der Zeit veralten).

Sie können das Beispiel von oben so modifizieren, dass es einen Fehler simuliert. Mit der Umleitung >&2 wird der Text auf stderr gelenkt. Und exit 1 setzt den Exit Code des Programms auf 1:

~/local/bin/myds
#!/bin/sh
HOST_NAME=$1

echo "<<<local>>>"
echo "0 Hostname - My name is $HOST_NAME"

echo "This didn't work out" >&2
exit 1

Im Checkmk-Service sieht dies dann so aus:

Wenn ein Skript von 0 verschiedene Exit Codes liefert, wird der Dienst sofort CRIT (rot).

Falls Sie Ihr Programm als Shell-Skript schreiben, können Sie gleich am Anfang die Option set -e verwenden:

~/local/bin/myds
#!/bin/sh
set -e

Sobald ein Befehl fehlschlägt (Exit Code ungleich 0), bricht die Shell sofort ab und beendet das Skript mit dem Exit Code 1. Damit haben Sie eine generische Fehlerbehandlung und müssen nicht bei jedem einzelnen Befehl auf Erfolg prüfen.

3. Spezialagenten

Einige häufig benötigte Datenquellenprogramme werden von Checkmk mitgeliefert. Diese erzeugen Agentenausgaben nicht durch den Abruf eines normalen Checkmk-Agenten auf irgendwelchen krummen Wegen, sondern sind für die Abfrage von bestimmter Hardware oder Software konzipiert.

Weil diese Programme teilweise recht komplexe Parameter benötigen, haben wir dafür spezielle Regelsätze in der Setup-GUI definiert, mit denen Sie diese direkt konfigurieren können. Diese Regelsätze finden Sie gruppiert nach Anwendungsfällen unter Setup > Agents > Other integrations und Setup > Agents > VM, Cloud, Container.

Wer von älteren Checkmk Versionen umgestiegen ist, wird sich möglicherweise über die neue Gruppierung wundern: Seit 2.0.0 gruppiert Checkmk nicht mehr nach Zugriffstechnik, sondern nach Art des überwachten Objektes. Dies ist insbesondere deshalb sinnvoll, weil es in vielen Fällen den Anwender nicht interessiert, mit welcher Technik Daten eingeholt werden und zudem oft Datenquellen und Piggyback miteinander kombiniert werden, hier also keine klare Abgrenzung möglich ist.

Regelsätze für die Überwachung von Anwendungen per Datenquelle und Piggyback.

Diese Programme heißen auch „Spezialagenten“, weil sie eben ein spezieller Ersatz für den normalen Checkmk-Agenten sind. Nehmen Sie als Beispiel die Überwachung von NetApp-Filern. Diese lassen die Installation eines Checkmk-Agenten nicht zu. Die SNMP-Schnittstelle ist langsam, fehlerhaft und unvollständig. Aber es gibt eine spezielle HTTP-Schnittstelle, welche Zugriff auf alle Überwachungsdaten liefert.

Der Spezialagent agent_netapp greift über diese Schnittstelle zu und wird über den Regelsatz NetApp via WebAPI als Datenquellenprogramm eingerichtet. Wichtig ist, dass Sie den Host in der Setup-GUI auf der Einstellung API integrations if configured, else Checkmk agent belassen.

Im Inhalt der Regel können Sie dann die Daten eingeben, die der Spezialagent braucht. Fast immer sind das irgendwelche Zugangsdaten. Beim NetApp-Agenten gibt es noch eine zusätzliche Checkbox für das Erfassen von Metriken (die hier recht umfangreich werden können):

Eingabemaske der Zugangsdaten für die Netapp-Überwachung.

Es gibt seltene Situationen, in denen Sie sowohl einen Spezialagenten als auch den normalen Agenten abfragen möchten. Ein Beispiel dafür ist die Überwachung von VMWare ESXi über das vCenter. Letzteres ist auf einer (meist virtuellen) Windows-Maschine installiert, auf welcher sinnvollerweise auch ein Checkmk-Agent läuft.

Auswahlmöglichkeiten 'host system' vs. 'vCenter' in der VMware ESXi Konfiguration.

Die Spezialagenten sind unter ~/share/check_mk/agents/special installiert. Wenn Sie eine Modifikation an einem solchen Agenten machen möchten, dann kopieren Sie die Datei mit dem gleichen Namen nach ~/local/share/check_mk/agents/special und ändern Sie sie dort.

4. Dateien und Verzeichnisse

Pfad Bedeutung

~/local/bin/

Ablage von eigenen Programmen oder Skripten, die im Suchpfad sein sollen und ohne Pfadangabe direkt ausgeführt werden können. Ist ein Programm sowohl in ~/bin/ als auch in ~/local/bin/, hat letzteres Vorrang.

~/share/check_mk/agents/special

Hier sind die mitgelieferten Spezialagenten installiert.

~/local/share/check_mk/agents/special

Ablage der von Ihnen modifizierten Spezialagenten.
Auf dieser Seite