Updates und Upgrades

Bei einem Update auf eine höhere Major-Version müssen Sie immer direkt auf die nächste Version aktualisieren und können nicht einfach eine überspringen. Wenn Sie also beispielsweise von 2.2.0 auf 2.4.0 aktualisieren wollen, aktualisieren Sie zunächst auf die 2.3.0. Der Grund ist simpel: Zwischen zwei Major-Versionen gibt es bisweilen schlicht so viele Änderungen, dass es beim Überspringen zu Problemen kommen würde.

Der Befehl omd update ermöglicht auch die „Aktualisierung“ auf eine niedrigere Version. Diese Vorgehensweise ist nur bei Regressionen vorgesehen. Nach einem solchen Update in die Rückwärtsrichtung sind viele Anpassungen nötig, um Konfiguration und Laufzeitumgebung wieder kompatibel zu machen – insbesondere, aber nicht nur, bei einem "Update" auf eine niedrigere Major-Version. Daher raten wir von diesem Vorgehen dringend ab – und können auch bei einem Update auf eine niedrigere Version keinen Support mehr bieten.

Über die Checkmk-Erweiterungspakete (MKPs) lässt sich Ihr Monitoring-System recht einfach und bequem erweitern. Auf der einen Seite kommt es dabei vor, dass solche MKPs nicht weiter gepflegt werden und dann ggf. mit neuen Versionen von Checkmk nicht mehr kompatibel sind. Auf der anderen Seite nehmen wir immer wieder neue Plugins und Funktionserweiterungen in Checkmk auf, weshalb MKPs mitunter obsolet werden. Ihre Funktionalität wird schlicht von Checkmk selbst sichergestellt.

Falls Sie MKPs installiert haben, ist aus diesem Grund eine Prüfung dieser MKPs dringend geboten. So verhindern Sie, dass inkompatible Pakete das Update behindern oder im Anschluss an das Update doppelte oder zumindest sehr ähnliche Services entstehen.

Prüfen Sie hierzu Ihre installierten MKPs gegen unseren Katalog der Check-Plugins und entfernen Sie Pakete, welche inzwischen nativ von Checkmk bereitgestellt werden. Bei dieser Gelegenheit können Sie auch MKPs entfernen, die eventuell nur mal für einen Probelauf installiert worden sind. Eine Auflistung finden Sie im Setup-Menü unter Maintenance > Extension packages. Auf der Kommandozeile können Sie sich installierte Erweiterungen mit dem Befehl mkp list anzeigen lassen. Überprüfen Sie die Ausgabe dieses Befehls auf Erweiterungen, die nicht mehr benötigt werden oder die Sie gar nicht mehr zuordnen können.

Checkmk unterstützt zur Vorbereitung von Updates die Bereitstellung von MKPs für eine neuere als die aktuell laufende Version. Beim Update wird dann das Paket für die niedrigere Checkmk-Version deaktiviert und das für die höhere aktiviert. Details erklärt der Artikel zur Verwendung von MKPs.

Achtung: Wenn Sie an Dateien, die ursprünglich MKPs entstammen, lokal Änderungen vorgenommen haben, packen Sie das MKP nach Erhöhung der Versionsnummer neu. Während des Updates werden sonst geänderte Dateien durch die im MKP enthaltenen überschrieben.

Mit lokalen Dateien können Sie die von Checkmk bereitgestellte Funktionalität anpassen und erweitern. Diese Dateien befinden sich im lokalen Teil der Instanzverzeichnisstruktur, d. h. in ~/local. Lokale Dateien können bei einem Update Probleme bereiten, da sie eventuell nicht mehr zur neuen Checkmk-Version passen.

Da es für Checkmk bei einem Update nicht möglich ist, die lokalen Anpassungen und jede von einem Drittanbieter hergestellte Erweiterung abzufangen und zu behandeln, sollten Sie Ihre Checkmk-Instanz vor einem Update daraufhin überprüfen, ob lokale Dateien bei Ihnen verwendet werden und gegebenenfalls welche.

Verschaffen Sie sich einen Überblick über die lokalen Dateien Ihrer Checkmk-Instanz, indem Sie als Instanzbenutzer das folgende Kommando ausführen (bei dem die Option -L dafür sorgt, dass auch symbolischen Links gefolgt wird):

In einer frischen Installation von Checkmk wird Ihnen derzeit nur eine Datei namens README.TXT aufgelistet. Alles, was darüber hinaus angezeigt wird, sollte ganz oben auf Ihrer Liste zur Fehlerdiagnose stehen, falls es beim Update Probleme geben sollte.

Im Idealfall sind lokale Dateien bereits vollständig in MKPs gebündelt. Verwenden Sie mkp find um unpaketierte Dateien zu identifizieren. Die weitere Vorgehensweise der Erstellung von Paketen zeigt unser Artikel zu Checkmk-Erweiterungspaketen. Einmal zu einem Paket zusammengefasst, kann eine Erweiterung als ganzes deaktiviert oder erneut aktiviert werden.

Die Selbstverständlichkeit, ein Backup unmittelbar vor dem Update zu erstellen, um im Falle eines Fehlschlags nicht allzu viel Ihrer Monitoring-Historie zu verlieren, müssen wir Ihnen nicht erklären. An dieser Stelle relevant ist, dass ein reguläres Backup auch gute Dienste für den Probelauf eines Updates leisten kann. So können Sie das Backup unter einem anderen Namen wiederherstellen – und anschließend mit der Instanz newsite das Update testen:

Alternativ können Sie Ihre Instanz auch per omd cp kopieren. Dafür muss die produktiv genutzte Instanz allerdings kurzzeitig gestoppt werden:

Führen Sie das Update im Anschluss erst einmal auf dieser neuen, geklonten Instanz durch, um hier beispielsweise die oben angesprochenen lokalen Änderungen in der neuen Umgebung zu prüfen. Waren die Tests mit der geklonten Instanz erfolgreich, werden Sie diese aus Platz- und Performance-Gründen meist vor dem eigentlichen Update der Produktivinstanz löschen oder zumindest stoppen wollen.

Wie in der Einleitung beschrieben, ist der erste Schritt beim Update die Installation der gewünschten neuen Version von Checkmk. Dies erfolgt genau wie bei der ersten Installation  —  allerdings wird es wohl etwas schneller gehen, weil die meisten abhängigen Pakete jetzt schon installiert sind. In folgendem Beispiel installieren wir ein Paket für Ubuntu 24.04 (Noble Numbat):

Hinweis: Wenn Sie ein lokal vorliegendes Paket mit apt install installieren, müssen Sie den vollständigen Pfad zu der .deb-Datei angeben.

Die Liste der installierten Checkmk-Versionen können Sie jederzeit mit dem Befehl omd versions abrufen:

Eine dieser Versionen ist mit (default) markiert. Diese Standardversion wird automatisch beim Anlegen von neuen Instanzen verwendet, sofern Sie nicht mit omd -V myversion create mysite eine andere angeben. Die aktuelle Standardversion können Sie mit omd version abfragen und mit omd setversion ändern:

Beim Verwalten bestehender Instanzen spielt die Standardversion keine Rolle. Der omd-Befehl startet immer mit der Version, die zur Instanz passt, für die der Befehl aufgerufen wird.

Eine Auflistung der aktuellen Instanzen und welche Versionen diese verwenden liefert der Befehl omd sites:

Nachdem die gewünschte neue Version installiert ist, können Sie das Update der Instanz durchführen. Dazu sind keine root-Rechte erforderlich. Machen Sie das Update am besten als Instanzbenutzer:

Stellen Sie sicher, dass die Instanz gestoppt ist:

Das Updaten — also eigentlich das Umschalten auf eine andere Version — geschieht nun einfach mit dem Befehl omd update:

Falls es mehr als eine mögliche Zielversion gibt, bekommen Sie diese zur Auswahl:

Bestätigen Sie in der folgenden Dialogbox das gewählte Update auf die neue Version:

Wenn Sie gleichzeitig zum Versions-Update ein Editions-Upgrade von einer Checkmk Raw auf eine der kommerziellen Editionen durchführen, werden Sie sicherheitshalber noch einmal auf diesen Umstand hingewiesen:

Ein wichtiger Teil des Updates ist das Aktualisieren von mitausgelieferten Konfigurationsdateien. Dabei werden von Ihnen eventuell vorgenommene Änderungen in diesen Dateien nicht einfach verworfen, sondern zusammengeführt. Dies funktioniert sehr ähnlich zu Versionskontrollsystemen, die versuchen, gleichzeitige Änderungen mehrerer Entwickler in der gleichen Datei automatisch zusammenzuführen.

Manchmal — wenn die Änderungen die gleiche Stelle der Datei betreffen — funktioniert das nicht und es kommt zu einem Konflikt. Wie Sie diesen lösen können, zeigen wir weiter unten.

Das Update zeigt eine Liste aller angepassten Dateien und Verzeichnisse (im folgenden Beispiel gekürzt):

Wenn die in der obigen Ausgabe hervorgehobene Zeile Completed verifying site configuration angezeigt wird, ist die Instanz auf die neue Version umgeschaltet:

… und kann gestartet werden:

Software-Entwicklung bedeutet Änderung. Und da wir immer daran arbeiten, Checkmk modern zu halten, kommen wir manchmal nicht drumherum, alte Zöpfe abzuschneiden und Änderungen zu machen, die inkompatibel sind. Das bedeutet, dass Sie nach einem Update eventuell Ihre Konfiguration anpassen oder wenigstens überprüfen sollten.

Ein typisches Beispiel dafür sind neue Check-Plugins, die bestehende Plugins ersetzen. Falls Sie eines der betroffenen Plugins einsetzen, ist nach dem Update eine erneute Service-Erkennung auf den betroffenen Hosts notwendig.

Eine Übersicht über alle Änderungen in Checkmk, inklusive einer Suchfunktion, finden Sie online in unseren Werks.

Noch praktischer ist aber die in Checkmk eingebaute Funktion zur Recherche. Nachdem Sie sich an der Instanz angemeldet haben, finden Sie oben im Help-Menü einen rot hinterlegten Link mit der Zahl inkompatibler und noch nicht bestätigter Änderungen:

Checkmk verfolgt die beim Update zur aktuellen Version angefallenen inkompatiblen Änderungen und fordert Sie auf, diese zu überprüfen und dann zu bestätigen (acknowledge):

Wenn Sie diese Seite über den rot hinterlegten Link im Help-Menü öffnen, werden Ihnen nur die „Werks“ (d.h. die Änderungen) angezeigt, bei denen etwas zu tun ist, und die daher mit Incompatible - TODO gekennzeichnet sind. Sie können jedes Werk einzeln aufrufen, ansehen, per Mausklick bestätigen — und damit die Zahl der offenen, inkompatiblen Änderungen sukzessive verringern. Zusätzlich haben Sie mit dem Menüeintrag Help > Change log (Werks) Zugriff auf die komplette Historie der Änderungen in der aktuellen Major-Version.

Sind Sie neugierig, was beim Update genau „unter der Haube abläuft“? Oder haben Sie beim Durchlauf von omd update Konflikte in Dateien bekommen? Dann sollten Sie hier weiterlesen.

Bei omd update geschehen drei Dinge:

Möchten Sie das Software-Update von Checkmk automatisieren? Dann werden Sie vielleicht erstmal an den interaktiven Rückfragen von omd update gescheitert sein. Dafür gibt es eine einfache Lösung: Der Befehl kennt nämlich Optionen, die speziell für den Einsatz in Skripten gedacht sind:

Mögliche Werte für --conflict= sind:

Ein Beispiel für den kompletten Befehl für ein automatisches Update der Instanz mysite auf die Version 2.4.0p7.cre:

Durch das && vor dem omd start wird ein Starten der Instanz verhindert, falls das omd update mit einem Fehler abbricht. Ersetzen Sie das && durch ein Semikolon (;), falls Sie einen Start auch in diesem Fall unbedingt versuchen wollen.

Falls Sie sicher sind, dass Sie nur eine einzige Checkmk-Instanz auf dem Server haben, können Sie deren Namen zur Verwendung in einem Shell-Skript einfach in einer Variable einfangen:

Das ermöglicht Ihnen, obige Zeile vom Namen der Instanz unabhängig zu machen. Ein kleines Shell-Skript könnte z.B. so aussehen:

Der technische Grund für die Vorgehensweise liegt in den verwendeten Protokollen: Die Zentralinstanz greift auf die Daten der Remote-Instanzen primär lesend via Livestatus zu. Bei zentralem Setup zudem schreibend über eine nicht öffentliche HTTP-API. In beiden Fällen gilt, dass neue Versionen echte Obermengen der verwendeten Protokolle einführen. So nutzt eine ältere Zentralinstanz nur eine echte Teilmenge der Funktionalität der neueren Remote-Instanzen. Würde man die Zentralinstanz zuerst aktualisieren, würde sie bei den Remote-Instanzen möglicherweise API-Aufrufe oder Livestatus-Anfragen verwenden, welche diese noch nicht verstehen.

Der maximale Versionsunterschied einer Major-Version resultiert wiederum daraus, dass die Entfernung von Schnittstellen mit einer Schonfrist genau einer Version einhergeht.

Um die phasenweise Aktualisierung zu erleichtern, bietet Checkmk die Möglichkeit, gleichnamige Erweiterungspakete in verschiedenen Versionen – eines passend zur älteren Zentralinstanz, eines passend zu den neueren Remote-Instanzen – zu hinterlegen. Aktiviert wird das jeweils passende. Details beschreibt der Artikel zu Erweiterungspaketen (MKPs).

Bei der Verwendung von Viewer-Instanzen dürfen die Viewer-Instanzen erst nach den Instanzen aktualisiert werden, deren Daten sie anzeigen. Zeigt eine Viewer-Instanz nur Daten von Remote-Instanzen, kann deren Aktualisierung erfolgen, sobald diese aktualisiert sind. Zeigt sie dagegen auch Daten der Zentralinstanz, darf ihre Aktualisierung erst als letztes stattfinden.

Dieses Kapitel deckt primär das Upgrade zu Checkmk Enterprise ab. Sie können in einem Schritt auch zu Checkmk Cloud upgraden, beachten Sie in diesem Fall jedoch auch die Hinweise im folgenden Abschnitt.

Da die kommerziellen Editionen etliche zusätzliche Module und Features haben, gibt es nach der Umstellung ein paar Dinge zu beachten. Der entscheidende Punkt ist, dass beim Anlegen von neuen Instanzen der Checkmk Raw bzw. der kommerziellen Editionen unterschiedliche Standardeinstellungen gesetzt werden.

Am Monitoring-Kern und dem Benachrichtigungssystem gibt es keine Unterschiede zwischen Checkmk Enterprise und Checkmk Cloud. Je nach Schwerpunkt des Einsatzes werden Sie den größeren Funktionsumfang oft erst beim Hinzufügen neuer Hosts nutzen. An einigen Stellen ist dennoch die Überprüfung der vorhandenen Einstellungen angeraten.

Eine vollständige Übersicht der zusätzlichen Funktionalität bietet der Artikel zu Checkmk Cloud (Self-hosted).

Beachten Sie, dass in verteilten Umgebungen immer zuerst das Update der Version durchgeführt werden muss, bevor das Upgrade der Edition folgen kann. Eine andere Reihenfolge oder ein Crossgrade (Update der Version und Upgrade der Edition in einem Schritt) ist nicht vorgesehen. Als generelles Vorgehen empfehlen wir das Offline-Upgrade, bei dem von einer beliebigen niedrigeren Edition auf eine beliebige höhere Edition gesprungen werden kann.

Bei zwei häufig nachgefragten Upgrade-Szenarien (Checkmk Raw nach Checkmk Enterprise und Checkmk Enterprise nach Checkmk Cloud) ist ein Mischbetrieb für einen eingeschränkten Zeitraum möglich.

Als Vorbereitung für das Downgrade von Checkmk Cloud nach Checkmk Enterprise müssen Sie mindestens die folgenden Änderungen vornehmen:

Ferner stehen nicht mehr alle Cloud-Services und weniger Dashboards zur Verfügung. Als Folge werden Sie verschwundene Services aufräumen müssen.

Falls Sie unter Checkmk Cloud das Grafana-Plugin aus dem „Grafana Store“ genutzt haben, müssen Sie dieses durch ein aus dem Zip-Archiv installiertes ersetzen.

Eine Übersicht der Unterschiede zwischen Checkmk Cloud und Checkmk Enterprise liefert der Artikel zu Checkmk Cloud (Self-hosted).

Als Vorbereitung für das Downgrade von Checkmk Enterprise nach Checkmk Raw müssen Sie mindestens die folgenden Änderungen vornehmen:

Daneben sind nicht mehr alle Dashboards, Graphen-Einstellungen, Benachrichtigungs-Plugins und Spezialagenten verfügbar. Im Artikel zu Checkmk Enterprise können Sie ermitteln, wie viel Checkmk Enterprise-Funktionalität im Falle des Downgrades nach Checkmk Raw wegfällt und wo Sie gegebenenfalls weitere Anpassungen vornehmen müssen.

Die in den beiden vorherigen Abschnitten vorgestellten Downgrade-Szenarien können auch in verteilten Umgebungen durchgeführt werden. Beachten Sie, dass in verteilten Umgebungen immer zuerst das Update der Version durchgeführt werden muss, bevor das Downgrade der Edition folgen kann. Eine andere Reihenfolge oder ein Crossgrade (Update der Version und Downgrade der Edition in einem Schritt) ist nicht vorgesehen.

In keinem Downgrade-Szenario unterstützt Checkmk den Mischbetrieb zwischen unterschiedlichen Editionen. Aus diesem Grund empfehlen wir dringend, das Downgrade der Edition offline durchzuführen. Gehen Sie dafür wie folgt vor:

Selbstverständlich können Sie mit dem Start warten, bis alle Instanzen das Downgrade erhalten haben, was die Zahl von Benachrichtigungen etwas reduziert.

Das Deinstallieren von nicht mehr benötigten Checkmk-Versionen geschieht mit dem Paketmanager des Betriebssystems. Geben Sie hier den Namen des installierten Pakets an, nicht den Dateinamen der ursprünglichen RPM/DEB-Datei. Wichtig: Löschen Sie nur solche Checkmk-Versionen, die von keiner Instanz mehr verwendet werden!

Nicht mehr benötigte Checkmk-Instanzen können Sie einfach mit omd rm entfernen (und dabei alle Daten löschen!):

So finden Sie heraus, welche Pakete installiert sind:

Die Deinstallation geschieht mit dpkg --purge:

So finden Sie bei RPM-basierten Systemen heraus, welche Checkmk-Pakete installiert sind:

Das Löschen geschieht mit rpm -e: