Checkmk auf der Kommandozeile

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 dem 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 Kommandozeilenbefehl 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 Kommandozeile 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 Skripten, 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, welcher 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 bitte 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.0.0p8.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 ist, 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 -alF) 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 wieder. 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.0.0p8.cee liegen und über symbolische Links vom Instanzverzeichnis aus erreichbar sind:

Der symbolische Link version/ ist ein „Zwischenstop“ 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. Bitte versuchen Sie trotzdem nicht, ein Update von Hand durch Ändern des Links zu 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 Logdateien oder was auch immer ablegen möchten.

Es gibt folgende vordefinierte Verzeichnisse:

Wie gerade in der 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 Logdateien werden bei Checkmk unterhalb des bereits erwähnten Datenverzeichnisses var/ abgelegt. Hier finden Sie zu allen Komponenten die zugehörigen Logdateien:

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

Alternativ können Sie die Log Level auch auf der Kommandozeile in Konfigurationsdateien anpassen. Die Dateien heißen jeweils global.mk, befinden sich aber in unterschiedlichen Verzeichnissen. Setzen Sie die Einträge, wenn Sie noch nicht vorhanden sind, was dann der Fall ist, wenn ein Standardwert (Factory setting) noch nicht verändert wurde.

In dieser Datei werden die Einträge für Monitoring Core, Notifications und Alert Handlers gesetzt:

In dieser Datei können Sie das User Interface Logging festlegen.

Der Umfang der geloggten Daten steigt, je kleiner die Zahl ist. Das geringste Log Level ist somit 50 (Critical), während 10 dem höchsten (Debug) entspricht.

Diese Datei dient dem Livestatus Proxy logging. Die möglichen Werte hier entsprechen denen beim User Interface Logging.

Wichtig: Logdateien können schnell sehr groß werden, wenn ein hohes Level eingestellt ist. Es eignet sich daher vor allem zur temporären Anpassung, um Probleme besser identifizieren zu können.

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 Kommando 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 Kommando nachschlagen. Ein längerer Blick in die Kommandohilfe 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 Kommando 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 Checkmk Enterprise Editions verwenden als Monitoring-Kern den Checkmk Micro Core (CMC), bei der Checkmk Raw Edition 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ötigt. 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. Falls Sie die Konfiguration manuell oder durch Skripte „am Setup vorbei“ modifizieren, müssen Sie sich selbst um das Aktivieren kümmern. Dazu dienen folgende Befehle:

Zusammengefasst bedeutet das: Wenn Sie von Hand die Checkmk-Konfiguration anpassen und die Änderungen aktivieren möchten, benötigen Sie anschließend bei Nagios:

Und beim CMC:

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 Defaultoption 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 Datenquellenprogramms 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 Datenquellenprogramm).

In den Checkmk Enterprise Editions können Sie die Agenten auch von der Kommandozeile 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.

Das Kommando 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 Hostnamen 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 Hostnamen 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. Folgendes Kommando liefert alle Hosts, die gleichzeitig per SNMP und Checkmk-Agenten ü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:

Wenn Sie von Hand Konfigurationsdateien in etc/check_mk/ editieren, ist der Konfigurationscheck durch ein cmk -X praktisch. Er zeigt nicht nur Fehler in der Python-Syntax, sondern auch falsch geschriebene oder nicht definierte Variablen:

Der Befehl cmk --paths zeigt Ihnen, in welchen Verzeichnissen Checkmk welche Dinge erwartet. Diese Liste umfasst nicht das komplette Checkmk-System, sondern nur Dinge, mit denen das Kommandozeilentool cmk selbst arbeitet. Trotzdem hilft es manchmal, Dinge schneller zu finden:

Checkmk liefert eine große Zahl von fertigen Plugins mit aus. In jedem Release kommen etliche dazu und Version 2.0.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 Manual Page (oder Man 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 Man Pages:

Hier können Sie interaktiv navigieren:

Falls Sie jetzt allerdings ein umfassendes Kompendium über den genauen Aufbau von allen von Checkmk verwendeten Konfigurationsdateien erwarten, müssen wir Sie an dieser Stelle leider enttäuschen. Die Komplexität und Vielfalt, die in den Konfigurationsdateien steckt, ist einfach viel zu groß, um sie in diesem Handbuch komplett zu beschreiben.

Folgendes Beispiel zeigt einen komplett ausgefüllten Parametersatz für das Check-Plugin, welches in Checkmk 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 eine ganz eigene Logik haben. Manche werden über Fließkommazahlen (0.8), manche über Ganzzahlen (24), manche über Schlüsselworte ('onlow'), manche über boolesche Werte (True) und andere wieder über Tupel aus solchen Dingen konfiguriert ((5.0, 10.0)).

Dieses Beispiel ist nur eines von über 2.000 Plugins. Und dann gibt es ja auch noch andere Konfigurationen als Check-Parameter: Man denke nur an Zeitperioden, Regeln der Event Console, Benutzerprofile und vieles mehr.

Das soll natürlich nicht heißen, dass Sie auf eine Konfiguration über Textdateien verzichten müssen! Wenn Sie die genaue Syntax für die Konfigurationsaufgabe Ihrer Wahl noch nicht kennen, brauchen Sie dafür nur das richtige Werkzeug — und das heißt: Setup:

Sie müssen also nur wissen, in welche Datei das Setup was schreibt.

Hinweis: Wenn es um die Namen von Dateiverzeichnissen, Dateien oder auch um Dateiinhalte geht, werden Sie des öfteren die Bezeichnung wato finden. WATO ist die Abkürzung für Web Administration Tool: das Checkmk-Konfigurationswerkzeug bis einschließlich zur Version 1.6.0. Die Funktion von WATO hat ab der Version 2.0.0 das Setup-Menü, oder auch kurz Setup, übernommen. Obwohl WATO in der Weboberfläche (fast) vollständig durch Setup ersetzt wurde, lebt es im Dateisystem weiter.

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) unterhalb von 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 einen bestimmten Dienst betreffen. Dabei gibt es jeweils ein Verzeichnis mit der Endung .d, unterhalb dessen alle Dateien mit der Endung .mk automatisch und in alphabetischer Reihenfolge eingelesen werden. Bei manchen gibt es noch eine Hauptdatei, welche als Erstes eingelesen wird. Diese wird vom Setup nie angefasst und ist nur für manuelle Änderungen vorgesehen.

Unterhalb der .d/-Konfigurationsverzeichnisse gibt es immer das Unterverzeichnis wato, z.B. etc/check_mk/conf.d/wato. Das Setup liest und schreibt grundsätzlich nur dort. Der für das Konfigurationsverzeichnis zuständige Dienst liest aber auch die übrigen Dateien in „seinem“ .d-Verzeichnis, falls Sie dort welche von Hand anlegen. Das bedeutet:

Rein formal gilt für alle Konfigurationsdateien von Checkmk, dass diese in Python 3-Syntax geschrieben sind. Dabei gibt es zwei Arten von Dateien:

Die ausführbaren Dateien erkennen Sie daran, dass hier Variablen durch Zuweisungen (=) mit Werten belegt werden. Die anderen Dateien enthalten meist ein Python-Dictionary, welches mit einer öffnenden geschweiften Klammer beginnt. Manchmal sind es auch einfache Werte.

Falls Sie in einer Datei ein Nicht-ASCII-Zeichen benötigen (z.B. einen deutschen Umlaut) so müssen Sie in die erste oder zweite Zeile folgenden Kommentar einfügen:

Andernfalls wird es beim Einlesen zu einem Syntaxfehler kommen. Für weitere Hinweise zur Syntax von Python verweisen wir auf dafür spezialisierte Seiten, zum Beispiel auf die offizielle Referenz von Python 3.