Checkmk auf der Befehlszeile

Bei der Administration von Checkmk müssen Sie mit wenigen Ausnahmen niemals als root-Benutzer arbeiten. In diesem Artikel gehen wir grundsätzlich davon aus, dass Sie als Instanzbenutzer angemeldet sind. Das geht z.B. mit:

Auch ein direkter SSH-Login in eine Instanz ohne den Umweg über root ist möglich. Da der Instanzbenutzer ein „ganz normaler“ Linux-Benutzer ist, müssen Sie dazu lediglich ein Passwort vergeben (was ein letztes Mal root-Rechte erfordert):

Danach sollte ein SSH-Login von einem anderen Rechner aus direkt möglich sein (Windows-Benutzer verwenden am besten PuTTY dafür). Von Linux aus geht das einfach mit dem Befehl ssh:

Beim ersten Login bekommen Sie wahrscheinlich eine Warnung wegen eines unbekannten Host-Schlüssels. Wenn Sie sicher sind, dass kein Angreifer in diesem Augenblick die IP-Adresse Ihres Monitoring-Systems übernommen hat, können Sie diese einfach mit yes bestätigen.

Auch bei der Checkmk Appliance können Sie auf die Befehlszeile zugreifen. Wie das geht, erklärt ein eigener Artikel.

Damit es zu möglichst wenig Problemen aufgrund von Besonderheiten einzelner Distributionen oder unterschiedlicher Betriebssystemkonfigurationen kommt, sorgt das Checkmk-System dafür, dass Instanzbenutzer — und gleichzeitig alle Prozesse des Monitorings — immer eine klar definierte Umgebung haben. Neben dem Home-Verzeichnis und den Berechtigungen, spielen hier die Umgebungsvariablen (environment variables) eine wichtige Rolle.

Unter anderem werden beim Login als Instanzbenutzer folgende Variablen gesetzt bzw. modifiziert. Sie stehen in allen Prozessen zur Verfügung, welche innerhalb der Instanz laufen. Das betrifft auch Skripte, die indirekt von diesen aufgerufen werden (z.B. eigene Benachrichtigungsskripte).

Mit dem Befehl env können Sie sich alle Umgebungsvariablen ausgeben lassen. Ein kleines, hübsches | sort dahinter macht das Ganze etwas übersichtlicher:

Unter Linux ist das Environment eine Eigenschaft eines Prozesses. Jeder Prozess hat seine eigenen Variablen, welche er an Unterprozesse automatisch vererbt. Dieser startet zwar dann erst einmal mit den gleichen Variablen, kann diese aber verändern.

Mit dem Befehl env können Sie immer nur die Umgebung der aktuellen Shell ansehen. Wenn Sie einen Fehler in der Umgebung eines bestimmten Prozesses vermuten, können Sie diese mit einem kleinen Trick ausgeben lassen. Dazu brauchen Sie nur die Prozess-ID (PID). Diese können Sie z.B. mit ps ax, pstree -p oder top ermitteln. Damit greifen Sie dann über das /proc-Dateisystem direkt auf die Datei environ des Prozesses zu. Hier ist ein passender Befehl für die Beispiel-PID 13222:

Wenn Sie für eigene Skripten oder andere Software, die in der Instanz laufen soll, eigene Variablen benötigen, so legen Sie diese in der Datei ~/etc/environment an, welche extra dafür vorgesehen ist. Alle hier definierten Variablen werden überall in der Instanz bereitgestellt:

Wenn Sie Ihre Shell anpassen möchten (Prompt oder andere Dinge), können Sie das wie gewohnt in der Datei .bashrc tun. Umgebungsvariablen gehören trotzdem nach ~/etc/environment, damit diese auch sicher in allen Prozessen vorhanden sind.

Es spricht auch nichts gegen eine eigene .vimrc, falls Sie gerne mit Vim arbeiten.

Folgendes Schaubild zeigt die wichtigsten Verzeichnisse einer Checkmk-Installation mit einer Instanz namens mysite und einer <version>, die zum Beispiel 2.4.0p11.cee heißt:

Die Basis bildet das Verzeichnis /omd. Alle Dateien von Checkmk befinden sich ohne Ausnahme hier Zwar ist /omd ein symbolischer Link auf /opt/omd, womit die Daten physikalisch eigentlich unterhalb von /opt liegen. Aber alle Pfadangaben in Checkmk verwenden immer /omd.

Wichtig ist die Aufteilung in Daten (gelb dargestellt) und Software (blau). Die Daten der Instanzen liegen unterhalb von /omd/sites/, die installierte Software unter /omd/versions/.

Wie jeder Linux-Benutzer hat auch der Instanzbenutzer ein Home-Verzeichnis, welches wir als Instanzverzeichnis bezeichnen. Wenn Ihre Instanz mysite heißt, so liegt dieses unter /omd/sites/mysite/. Wie bei Linux üblich kürzt die Shell das eigene Home-Verzeichnis mit einer Tilde (~) ab. Da Sie sich nach einem Login direkt in diesem Verzeichnis befinden, erscheint die Tilde im Eingabeprompt:

Unterverzeichnisse des Instanzverzeichnisses werden relativ zur Tilde dargestellt:

Direkt im Instanzverzeichnis befinden sich etliche Unterverzeichnisse, die Sie mit ll (Alias für ls -l) auflisten können:

Wie Sie sehen können, sind die Verzeichnisse bin, include, lib, share und version symbolische Links. Beim Rest handelt es sich um „normale“ Verzeichnisse. Dies spiegelt die oben genannte Trennung von Software und Daten wider. Die Verzeichnisse zur Software müssen zwar in der Instanz als Unterverzeichnisse verfügbar sein, liegen aber physikalisch unterhalb von /omd/versions/ und werden dort eventuell noch von weiteren Instanzen genutzt.

Die Verzeichnisse der Software gehören wie unter Linux üblich root und sind daher vor Veränderungen durch den Instanzbenutzer geschützt. Es gibt folgende Unterverzeichnisse, welche hier im Beispiel physikalisch unterhalb von /omd/versions/2.4.0p11.cee/ liegen und über symbolische Links vom Instanzverzeichnis aus erreichbar sind:

Der symbolische Link version ist ein „Zwischenstopp“ und dient als zentrale Umschaltstelle für die von der Instanz verwendete Version. Bei einem Software-Update wird dieser symbolische Link von der alten auf die neue Version umgebogen. Versuchen Sie trotzdem nicht, ein Update von Hand durch Ändern des Links durchzuführen, denn beim Update sind noch einige weitere Schritte notwendig, die dann fehlen würden.

Die eigentlichen Daten einer Instanz liegen in den restlichen Unterverzeichnissen des Instanzverzeichnisses. Diese gehören ohne Ausnahme dem Instanzbenutzer. Auch das Instanzverzeichnis selbst gehört dazu. Checkmk legt dort außer den hier gezeigten Verzeichnissen keine Dinge ab. Sie können hier aber problemlos eigene Dateien und Verzeichnisse anlegen, in denen Sie Tests, heruntergeladene Dateien, Kopien von Log-Dateien oder was auch immer ablegen möchten.

Es gibt folgende vordefinierte Verzeichnisse:

Wie gerade in der obigen Tabelle gezeigt, ist das Verzeichnis ~/local/ mit seinen zahlreichen Unterverzeichnissen für Ihre eigenen Erweiterungen vorgesehen. In einer neuen Instanz sind alle Verzeichnisse unter ~/local/ zunächst leer.

Mit dem praktischen Befehl tree können Sie sich schnell einen Überblick über die Struktur unter ~/local/ verschaffen. Die Option -L 3 begrenzt hier die Tiefe auf 3:

Alle Verzeichnisse der untersten Ebene sind aktiv in die Software eingebunden. Legen Sie hier eine Datei ab, so wird diese genauso behandelt, als läge sie im gleichnamigen Verzeichnis unterhalb von /omd/versions/…​ bzw. im logischen Pfad von der Instanz aus unter ~/bin/, ~/lib/ oder ~/share/).

Beispiel: In der Instanz werden ausführbare Programme in ~/bin/ und in ~/local/bin/ gesucht.

Dabei gilt, dass bei einer exakten Namensgleichheit die Datei unter ~/local/ immer Vorrang hat. Das ermöglicht Ihnen, Dateien der Software zu modifizieren, ohne Installationsdateien unterhalb von /omd/versions/ ändern zu müssen. Das Vorgehen ist einfach:

Falls Sie beim dritten Punkt nicht genau wissen, welche Dienste das sind, so können Sie einfach mit omd restart die ganze Instanz neu starten.

Die Log-Dateien werden bei Checkmk unterhalb des bereits erwähnten Datenverzeichnisses var/ abgelegt. Hier finden Sie zu den Komponenten die zugehörigen Log-Dateien. Die folgende Ausgabe für eine der kommerziellen Editionen ist gekürzt:

Auf der Weboberfläche können Sie bequem konfigurieren, in welchem Umfang Daten in die Log-Dateien geschrieben werden sollen, indem Sie in Setup > General > Global settings nach allen Einträgen mit logging suchen:

Der Befehl cmk ist eigentlich eine Abkürzung für check_mk, die eingeführt wurde, damit man den Befehl schneller tippen kann. Der Befehl verfügt über eine eingebaute, sehr ausführliche Onlinehilfe, die Sie mit der Option --help aufrufen können:

Wie Sie im obigen Befehl sehen, haben wir die Hilfe statt mit --help mit der Option -h aufgerufen. Denn was für den Befehl selbst gilt, stimmt auch für seine Optionen: Je weniger zu tippen ist, um so schneller geht es. Nicht für alle, aber für die oft benötigten Optionen, gibt es daher neben der Lang- auch eine Kurzform. Auch wenn die Langform, gerade für Einsteiger, intuitiver ist (check_mk --list-hosts) als die Kurzform (cmk -l) werden wir im Handbuch die Kurzform verwenden. Im Zweifel können Sie immer in der Hilfe zum Befehl nachschlagen. Ein längerer Blick in die Befehlshilfe ist auf jeden Fall eine gute Idee, da wir im Handbuch nicht alle Optionen vorstellen werden.

Durch die Eingabe einer Option starten Sie den Befehl cmk in einem bestimmten Modus. Hier folgt die Übersicht der Optionen, die wir in diesem Kapitel, aber auch an anderen Stellen des Handbuchs, vorstellen werden:

In einigen Modi stehen Ihnen weitere, spezifische Optionen zur Verfügung, z.B. können Sie die Service-Erkennung auf bestimmte Checks einschränken, z.B. mit dem Befehl cmk -I --detect-plugins=df myserver123 auf den Check df.

Einige Optionen funktionieren immer — egal mit welchem Modus Sie den Befehl aufrufen:

Im Folgenden zeigen wir, wie Sie die Befehle verwenden können. Die Beispielausgaben sind meist gekürzt dargestellt.

Die kommerziellen Editionen verwenden als Monitoring-Kern den Checkmk Micro Core (CMC), bei der Checkmk Raw kommt Nagios zum Einsatz. Eine wichtige Aufgabe von cmk ist es, eine für den Kern lesbare Konfigurationsdatei zu erzeugen, welche alle konfigurierten Hosts, Services, Kontakte, Kontaktgruppen, Zeitperioden usw. enthält. Anhand dieser weiß der Kern, welche Checks er ausführen muss und welche Objekte er per Livestatus der GUI bereitstellen soll.

Grundsätzlich gilt sowohl für Nagios also auch für den CMC, dass die Menge der Hosts, Services und anderen Objekte zur Laufzeit immer statisch ist und sich nur durch das Erstellen einer neuen Konfiguration ändern kann, welche der Kern anschließend neu laden muss. Bei Nagios ist dazu ein Neustart des Kerns nötig. Der CMC beherrscht ein sehr effizientes Neuladen der Konfiguration im laufenden Betrieb.

Folgende Tabelle zeigt wichtige Unterschiede bei der Konfiguration der beiden Kerne:

Das Neuerzeugen der Konfiguration ist immer dann notwendig, wenn sich Inhalte der Konfigurationsdateien unterhalb von ~/etc/check_mk/conf.d oder automatisch erkannte Services unter ~/var/check_mk/autochecks geändert haben. Das Setup führt Buch über solche Änderungen und zeigt diese in der GUI als zu aktivierende Änderungen an. Für das Aktivieren über die Befehlszeile gibt es die folgenden Befehle:

Ein zweiter Modus von Checkmk befasst sich mit der Ausführung von Checkmk-basierten Checks eines Hosts. Damit können Sie alle automatisch erkannten und auch manuell hinzu konfigurierten Services sofort checken lassen, ohne dass Sie dafür den Monitoring-Kern oder die GUI bemühen müssen.

Geben Sie dazu cmk --check gefolgt vom Namen eines im Monitoring konfigurierten Hosts ein. Da die Option --check die Standardoption von cmk ist, können Sie diese auch weglassen. Außerdem sollten Sie immer die beiden Optionen -n (Ergebnisse nicht an den Kern übermitteln) und -v (alle Ergebnisse ausgeben) hinzufügen. Dazu mehr bei der Beschreibung der Optionen weiter unten.

Hinweise dazu:

Folgende Optionen beeinflussen den Befehl:

cmk -d holt die Ausgabe des Checkmk-Agenten eines Hosts und zeigt sie an. Die Agentendaten werden bei cmk -d auf dem gleichen Weg geholt wie während des Monitorings und weder geprüft noch aufbereitet. Damit entsprechen die angezeigten Daten den Daten, die bei aktivierter TLS-Verschlüsselung dem Agent Controller oder bei Verwendung eines Datenquellprogramms dem übertragenden Programm übergeben werden.

Sie können cmk -d sogar mit dem Namen oder der IP-Adresse eines Hosts aufrufen, der nicht im Monitoring angelegt ist. In diesem Fall werden für den Host Legacy-Einstellungen angenommen (TCP-Verbindung zu Port 6556, kein Agent Controller, keine Verschlüsselung, kein Datenquellprogramm).

In den kommerziellen Editionen können Sie die Agenten auch von der Befehlszeile backen, so wie Sie es sonst über die Weboberfläche tun würden. Damit haben Sie z.B. die Möglichkeit, die Agenten regelmäßig zu aktualisieren, etwa über einen Cronjob.

Zum Backen der Agenten dient die Option -A, gefolgt vom Namen eines Hosts (oder auch von mehreren):

Die Ausgabe zeigt, dass die für den Host myserver123 verfügbaren Agentenpakete erfolgreich gebacken wurden. Wenn Sie keinen Host angeben, werden die Pakete für alle Hosts gebacken.

Der Befehl backt nur dann, wenn es notwendig ist. Falls die Pakete noch aktuell sind, sieht die Ausgabe etwa so aus:

Mit der Option -f (force) können Sie das Backen trotzdem erzwingen.

Der Befehl cmk -l listet einfach die Namen aller im Setup eingerichteten Hosts auf:

Da die Daten „nackt“ und ohne Verzierungen ausgegeben werden, können Sie sie leicht in Skripten nutzen. Zum Beispiel können Sie damit eine Schleife über alle Host-Namen bauen:

Wenn Sie jetzt anstelle des echo einen Befehl einsetzen, der etwas Sinnvolles macht, kann das wirklich nützlich sein.

Der Aufruf cmk --list-tag gibt ebenfalls Host-Namen aus, bietet dabei aber die Möglichkeit, nach Host-Merkmalen zu filtern. Geben Sie einfach ein Host-Merkmal an und Sie erhalten alle Hosts, die dieses Merkmal besitzen. Folgendes Beispiel listet alle Host auf, die per SNMP überwacht werden:

Geben Sie mehrere Merkmale an, so werden diese per UND verknüpft. Folgender Befehl liefert alle Hosts, die gleichzeitig per SNMP und Checkmk-Agent überwacht werden. Da keine Hosts diese Bedingung erfüllen, bleibt die Ausgabe leer:

cmk -D zeigt für einen oder mehrere Hosts die konfigurierten Services, Host-Merkmale, Labels und andere Attribute. Da die Liste der Services sehr breit ist, kann das Ganze im Terminal etwas unübersichtlich aussehen. Schicken Sie die Ausgabe durch less -S um einen Umbruch zu vermeiden:

Checkmk liefert eine große Zahl von fertigen Check-Plugins mit aus. In jeder Version kommen etliche dazu und Version 2.4.0 umfasst bereits über 2.000 Plugins. Drei Optionen des Befehls cmk bieten Ihnen Zugriff auf Informationen zu diesen Plugins.

cmk -L gibt in einer Tabelle alle Plugins mit Namen, Typ und Beschreibung aus. Dabei werden auch solche aufgelistet, welche Sie eventuell per Hand unterhalb von ~/local/ nachinstalliert haben.

Beim Typ gibt es die folgenden Werte:

Natürlich können Sie in der Liste einfach mit grep filtern, wenn Sie nach etwas Bestimmten suchen:

Wenn Sie zu einem der Plugins mehr Information möchten, können Sie dessen Dokumentation als Handbuchseite (manual page) mit cmk -M aufrufen:

Das ergibt dann folgende Ausgabe:

Mit einem cmk -m ohne weitere Angaben kommen Sie in den kompletten Katalog aller Check-Plugin Handbuchseiten:

Hier können Sie interaktiv navigieren:

Nicht hier. Die Spezifikation von Konfigurationsdateien erfolgt mit der Spezifikation der Komponenten, die diese schreiben und wieder einlesen. Letztlich kann nur ein Blick in den Quellcode und zugehörige Tests die Struktur der im Dateisystem gespeicherten Konfiguration offen legen.

Beachten Sie zudem, dass sich Formate von Konfigurationsdateien auch zwischen Patch-Versionen ändern können. In diesem Fall sorgen Migrationsroutinen für die Konvertierung geänderter Datenformate.

Ferner können verwendete Einheiten zwischen Anzeige im Setup und Speicherung in der Konfigurationsdatei abweichen. Das betrifft beispielsweise die Darstellung von Zeitspannen oder Temperaturen.

Folgendes Beispiel zeigt einen komplett ausgefüllten Parametersatz für das Check-Plugin, welches in Checkmk (hier in einer älteren Version) Dateisysteme überwacht. Wegen der vielen Parameter ist der Screenshot in zwei Teile zerlegt und in kleiner Schrift gesetzt:

Die entsprechende Passage dazu in der Konfigurationsdatei sieht (etwas hübscher formatiert) so aus:

Wie Sie sehen, gibt es hier mehr als 10 verschiedene Parameter, die jeweils einer ganz eigenen Logik folgen. Einige werden über Fließkommazahlen (0.8), andere über Ganzzahlen (24), manche über Schlüsselworte ('onlow'), wieder andere über boolesche Werte (True) und schließlich welche über Tupel aus solchen Typen konfiguriert ((5.0, 10.0)).

Dieses Beispiel zeigt nur eines von über 2.000 Plugins. Zudem kennt Checkmk ja noch andere Konfigurationen als Check-Parameter: Denken Sie nur an Zeitspannen, Regeln der Event Console, Benutzerprofile und vieles mehr.

Um herauszufinden, welche Datei Setup gerade verändert hat, gibt es einen praktischen Befehl: find. Mit folgenden Parametern aufgerufen, finden Sie alle Dateien (-type f) in ~/etc/, welche innerhalb der letzten Minute (-mmin -1) geändert wurden:

Die Basis der Konfiguration ist immer das Verzeichnis ~/etc/check_mk/. Darunter gibt es eine Aufteilung in verschiedene Domänen, welche meist eine bestimmte Funktionalität betreffen. Hier existiert jeweils ein Verzeichnis mit der Endung .d, unterhalb dessen alle Dateien mit der Endung .mk automatisch und in alphanumerischer Reihenfolge eingelesen werden.

Unterhalb der .d/-Konfigurationsverzeichnisse gibt es immer das Unterverzeichnis wato, z.B. ~/etc/check_mk/conf.d/wato/. Das Setup liest und schreibt in der Regel nur dort. Der für das Konfigurationsverzeichnis zuständige Dienst liest aber auch die übrigen Dateien in „seinem“ .d-Verzeichnis.

Wenn Dateien außerhalb des Verzeichnisses wato/ liegen, wurden diese entweder irgendwann früher manuell erstellt mit dem Ziel, Änderungen vorzunehmen, die zwar effektiv, aber im Setup nicht sichtbar sind, oder sie wurden von anderen Komponenten in Checkmk angelegt.

Konfigurationsdateien können Textdateien sein, die Sie in jedem beliebigen Editor betrachten können oder Binärdateien, die spezielle Werkzeuge erfordern. Textdateien folgen der Syntax von Python, im Detail gibt es Unterschiede bei der Handhabung durch Checkmk:

Als Zeichenkodierung wird immer UTF-8 verwendet. Sollten Sie aus irgendwelchen Gründen Anpassungen vornehmen müssen, achten Sie darauf, dass die modifizierte Datei immer noch von Python geparst werden kann.

Binärdateien tragen die Endung .pb, was für Protocol Buffers steht und manchmal auch Protobuf genannt wird. Dieses bei Google entwickelte Format zur Serialisierung von Konfiguration und Nachrichten kann mit geringem Overhead geschrieben und eingelesen werden. Allerdings sind zur Betrachtung spezielle Werkzeuge notwendig. Im Lieferumfang von Checkmk befindet sich protoc, das viele einfache Aufgaben erledigt. Einen „rohen“ Einblick in den letzten Status eines gestoppten CMC liefert beispielsweise:

Für umfangreichere Untersuchungen von Protobuf-Dateien können Sie protoscope verwenden.

Haben Sie den Verdacht, dass Konfigurationsdateien beschädigt sein könnten (beispielsweise durch einen defekten Datenträger), können Sie diese prüfen lassen. Checkmk liefert hierfür das Programm cmk-validate-config, welches im Gegensatz zu dem bei einem Software-Update aufgerufenen cmk-update-config keine Änderungen wie Migrationen von Datenformaten durchführt. cmk-validate-config prüft sowohl Syntax (Klammersetzung, korrekte Zuweisungen, etc.) als auch partiell Semantik (verwendete Datentypen und Vorhandensein bestimmter Schlüssel). Stößt das Programm auf Syntaxfehler, wird die erste beschädigte Datei angezeigt:

Sind die geprüften Dateien in Ordnung, wird eine Auflistung aller untersuchten Dateien angezeigt: