Vollständige, produktionstaugliche Container-Installation von Checkmk mit NGINX Proxy Manager als HTTPS-Terminierung (Let's Encrypt oder selbstsigniert), inklusive Werkzeugen für Backup, Restore und die Migration bestehender Sites von einer Direktinstallation – ohne dass die Agents neu eingerichtet werden müssen.

Inhaltsverzeichnis

Überblick & Architektur
Verzeichnisstruktur
Voraussetzungen & Ports
Installation auf Debian/Ubuntu (Docker)
Installation auf RHEL/Rocky/Alma/Fedora (Podman)
Autostart nach einem Neustart des Hosts (Podman)
Konfiguration (.env)
Erststart
HTTPS einrichten – Let's Encrypt oder selbstsigniert
Firewall
Verwaltung: cmk-manage.sh (CLI und ncurses-Oberfläche)
Backup
Restore
Migration einer Direktinstallation (migrate_creator.sh)
Mehrere Sites in einem Container
Checkmk aktualisieren
Fehlersuche
Sicherheitshinweise
Deinstallation

1. Überblick & Architektur

                    Internet / LAN
                          |
                     :80  :443  :81
                          |
        +-----------------------------------+
        |  NGINX Proxy Manager (Container)  |   network_mode: host
        |  - Let's Encrypt ODER self-signed |
        |  - Weboberfläche auf Port 81      |
        +-----------------------------------+
                          |  http://127.0.0.1:5000
                          v
        +-----------------------------------+
        |  Checkmk / OMD (Container)        |   network_mode: host
        |  :5000  Web-GUI (Apache)          |
        |  :8000  Agent-Receiver            |   <-- Agents (cmk-agent-ctl)
        |  :6557  Livestatus (optional)     |
        +-----------------------------------+
                          |
             Bind-Mount: ./data/checkmk/sites  ->  /omd/sites

Bewusste Entwurfsentscheidungen

Punkt	Umsetzung	Grund
Checkmk im Host-Netzwerk	`network_mode: host`, keine `ports:`-Angaben	Agents, SNMP-Traps, ICMP und der Agent-Receiver arbeiten ohne NAT; die Quell-IP der überwachten Hosts bleibt erhalten
NGINX Proxy Manager ebenfalls im Host-Netzwerk	`network_mode: host`	erreicht das Checkmk-Backend direkt über `127.0.0.1:5000`; kein Bridge-Netz, keine `host-gateway`-Tricks nötig – funktioniert unter Docker und Podman identisch
Keine Named Volumes	ausschließlich Bind-Mounts nach `./data/`	alle Daten liegen sichtbar im Projektverzeichnis, einfach zu sichern, zu kopieren und zu prüfen
Eine Compose-Datei für beides	`docker compose` und `podman-compose`	identische Bedienung auf Debian und RHEL
`:Z` an den Bind-Mounts	SELinux-Relabeling	nötig unter RHEL; unter Debian/Docker wirkungslos (kein Fehler)

2. Verzeichnisstruktur

.
├── README.md
├── docker-compose.yml               # für Docker UND Podman
├── .env.example                     # Vorlage -> .env
├── install.sh                       # Installation Docker (Debian) / Podman (RHEL)
│
├── scripts/
│   ├── cmk-manage.sh                # Stack, Backup, Restore, Import + ncurses-GUI
│   ├── migrate_creator.sh           # -> auf den QUELLSERVER kopieren
│   └── lib/
│       └── common.sh                # gemeinsame Funktionen + TUI-Helfer
│
├── systemd/
│   ├── checkmk-stack.service.example # Compose-basierte Unit (Autostart)
│   └── quadlet/
│       ├── checkmk.container         # Podman-Quadlet (Alternative)
│       └── nginx-proxy-manager.container
│
├── data/                            # ALLE Nutzdaten (Bind-Mounts)
│   ├── checkmk/sites/               # -> /omd/sites   (komplette OMD-Sites)
│   └── npm/
│       ├── data/                    # -> /data            (NPM-Konfiguration/DB)
│       ├── letsencrypt/             # -> /etc/letsencrypt (Zertifikate)
│       └── custom-certs/            # selbstsignierte Zertifikate zum Hochladen
│
└── backups/                         # Backups und Migrations-Bundles (*.tar.gz)

3. Voraussetzungen & Ports

64-Bit-Linux, mind. 2 CPU-Kerne, 4 GB RAM (Empfehlung: 4 Kerne, 8 GB)
Plattenplatz: Faustregel 1 GB je 100 überwachte Hosts und Jahr, plus Backups
root-Rechte
Ausgehender Internetzugang für den Image-Download

Belegte Ports (Host-Netzwerk!)

Port	Dienst	Erreichbar von
80/tcp	NGINX Proxy Manager – HTTP, Let's-Encrypt-Challenge	Internet/LAN
443/tcp	NGINX Proxy Manager – HTTPS	Internet/LAN
81/tcp	NGINX Proxy Manager – Adminoberfläche	nur Admin-Netz!
5000/tcp	Checkmk Apache (Backend)	nur localhost – nicht freigeben
8000/tcp	Checkmk Agent-Receiver (TLS-registrierte Agents)	überwachte Hosts
6557/tcp	Livestatus (nur bei `CMK_LIVESTATUS_TCP=on`)	verteilte Sites

Wichtig: Da beide Container im Host-Netzwerk laufen, dürfen die Ports 80, 443 und 81 auf dem Host nicht bereits belegt sein (z. B. durch einen installierten Apache/NGINX). Prüfen mit ss -tlnp | grep -E ':(80|81|443|5000)\b'.

4. Installation auf Debian/Ubuntu (Docker)

# Projekt an den gewünschten Ort legen
sudo mkdir -p /opt/checkmk-stack
sudo cp -r ./* ./.env.example /opt/checkmk-stack/
cd /opt/checkmk-stack

# Docker CE + Compose-Plugin installieren, Projekt vorbereiten
sudo ./install.sh --with-systemd

install.sh erledigt dabei:

Docker-Repository von download.docker.com einbinden (GPG-Key + Sources-Liste)
docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, docker-compose-plugin installieren
dialog, openssl, tar, curl installieren (für die ncurses-Oberfläche)
systemctl enable --now docker
Verzeichnisse unter data/ und backups/ anlegen, .env aus .env.example erzeugen
optional die systemd-Unit checkmk-stack.service einrichten

Anschließend:

sudo $EDITOR /opt/checkmk-stack/.env     # mindestens CMK_PASSWORD und CMK_SITE_ID
sudo ./scripts/cmk-manage.sh up
sudo ./scripts/cmk-manage.sh status

Unter Docker sorgt bereits restart: unless-stopped dafür, dass die Container nach einem Reboot wieder starten (der Docker-Daemon startet sie). Die systemd-Unit ist trotzdem sinnvoll, weil sie zusätzlich alle Sites startet (siehe Kapitel 15).

5. Installation auf RHEL/Rocky/Alma/Fedora (Podman)

Auf Red-Hat-Systemen steht Docker nicht zur Verfügung – hier wird Podman verwendet. Die Compose-Datei ist dieselbe.

sudo mkdir -p /opt/checkmk-stack
sudo cp -r ./* ./.env.example /opt/checkmk-stack/
cd /opt/checkmk-stack

sudo ./install.sh --with-systemd

install.sh installiert dabei:

podman, tar, dialog, openssl
podman-compose – in dieser Reihenfolge versucht: Distributions-Repository → EPEL → pip3 install podman-compose
richtet die systemd-Unit ein (bei Podman immer, siehe nächstes Kapitel)

Manuell entspricht das:

sudo dnf install -y podman podman-compose tar dialog openssl
# Falls podman-compose nicht im Repo ist:
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
sudo dnf install -y podman-compose

Starten:

sudo $EDITOR /opt/checkmk-stack/.env
sudo ./scripts/cmk-manage.sh up          # nutzt automatisch podman-compose
sudo ./scripts/cmk-manage.sh status

SELinux

Die Bind-Mounts sind in docker-compose.yml mit :Z versehen, Podman setzt dadurch automatisch den Kontext container_file_t. Falls Zugriffe dennoch scheitern:

sudo semanage fcontext -a -t container_file_t "/opt/checkmk-stack/data(/.*)?"
sudo restorecon -Rv /opt/checkmk-stack/data
sudo ausearch -m avc -ts recent          # AVC-Meldungen prüfen

6. Autostart nach einem Neustart des Hosts (Podman)

Das ist bei Podman der wichtigste Unterschied zu Docker: Podman hat keinen Daemon. Die Angabe restart: unless-stopped in der Compose-Datei wirkt deshalb nicht über einen Reboot hinweg. Der Autostart muss über systemd erfolgen. Es gibt zwei erprobte Wege.

Variante A – Compose-basierte systemd-Unit (empfohlen, identisch zu Docker)

Wird von ./install.sh --with-systemd automatisch erzeugt und aktiviert. Manuell:

sudo tee /etc/systemd/system/checkmk-stack.service >/dev/null <<'EOF'
[Unit]
Description=Checkmk + NGINX Proxy Manager (Container-Stack)
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/checkmk-stack
EnvironmentFile=/opt/checkmk-stack/.env
TimeoutStartSec=0
ExecStart=/bin/sh -c '/usr/bin/podman-compose up -d'
ExecStartPost=/opt/checkmk-stack/scripts/cmk-manage.sh start-all-sites
ExecStop=/bin/sh -c '/usr/bin/podman-compose down'

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now checkmk-stack.service
sudo systemctl status checkmk-stack.service

Prüfen, dass es einen Reboot übersteht:

sudo systemctl is-enabled checkmk-stack     # -> enabled
sudo reboot
# nach dem Neustart:
sudo podman ps
sudo /opt/checkmk-stack/scripts/cmk-manage.sh status

ExecStartPost ruft start-all-sites auf. Das ist nötig, weil der Checkmk-Entrypoint nur die in CMK_SITE_ID eingetragene Site startet – bei mehreren Sites blieben die übrigen sonst gestoppt.

Variante B – Podman-Quadlet (ab Podman 4.4, ohne Compose)

Quadlet erzeugt aus einfachen Beschreibungsdateien echte systemd-Units. Vorteil: kein podman-compose nötig, saubere Abhängigkeiten, natives Podman.

sudo ./install.sh --quadlet

Das schreibt (mit den Werten aus der .env) nach /etc/containers/systemd/:

checkmk.container
nginx-proxy-manager.container

Danach:

sudo systemctl daemon-reload
sudo systemctl start checkmk nginx-proxy-manager
sudo systemctl status checkmk

Die Units werden durch WantedBy=multi-user.target default.target beim Systemstart automatisch aktiviert – ein separates systemctl enable ist bei Quadlet nicht nötig (und auch nicht möglich, da die Units generiert werden).

Vorlagen liegen unter systemd/quadlet/.

Variante C – rootless Podman (optional, erhöhter Aufwand)

sudo ./install.sh --rootless
sudo loginctl enable-linger checkmk           # Dienstbenutzer
# Unit als Benutzer-Unit:
mkdir -p ~/.config/systemd/user
cp systemd/checkmk-stack.service.example ~/.config/systemd/user/checkmk-stack.service
systemctl --user daemon-reload
systemctl --user enable --now checkmk-stack

--rootless setzt net.ipv4.ip_unprivileged_port_start=80, damit die Ports 80/443 ohne root gebunden werden dürfen. loginctl enable-linger sorgt dafür, dass die Benutzer-Units auch ohne Anmeldung nach einem Reboot starten.

Hinweis: Im rootless-Betrieb werden die UIDs der Site-Benutzer über User-Namespaces abgebildet. Die Dateien unter data/checkmk/sites gehören dann Subordinate-UIDs (z. B. 165536). Das ist normal, erschwert aber die Arbeit mit den Dateien vom Host aus. Für Migrationen wird der rootful Betrieb empfohlen.

7. Konfiguration (`.env`)

cp .env.example .env
chmod 600 .env
$EDITOR .env

Die wichtigsten Schalter:

Variable	Bedeutung
`CMK_RUNTIME`	leer = automatische Erkennung, sonst `docker` oder `podman`
`CMK_IMAGE_REPO`	`checkmk/check-mk-raw` (frei) oder `checkmk/check-mk-enterprise`
`CMK_IMAGE_TAG`	Version – bei einer Migration muss sie zur Quell-Site passen!
`CMK_SITE_ID`	Site, die der Container anlegt bzw. beim Start hochfährt
`CMK_PASSWORD`	Startpasswort für den Benutzer `cmkadmin` (nur bei Neuanlage)
`CMK_LIVESTATUS_TCP`	`on` öffnet Port 6557 für verteilte Überwachung
`MAIL_RELAY_HOST`	SMTP-Relay für Benachrichtigungen
`TZ`	Zeitzone, z. B. `Europe/Berlin`
`BACKUP_DIR`	Ablage für Backups/Bundles (Vorgabe `./backups`)
`CERT_DOMAIN`, `CERT_DAYS`	Vorgaben für selbstsignierte Zertifikate

8. Erststart

sudo ./scripts/cmk-manage.sh up
sudo ./scripts/cmk-manage.sh status

Ausgabe (Beispiel):

Container
  checkmk                  läuft
  nginx-proxy-manager      läuft

Sites im Container
  SITE                 VERSION            STATUS
  cmk                  2.3.0p23.cre       läuft

Zugang
  Checkmk (direkt)        : http://10.0.0.5:5000/cmk/
  Checkmk (über Proxy)    : https://<FQDN>/cmk/
  Agent-Receiver          : 10.0.0.5:8000
  NGINX Proxy Manager     : http://10.0.0.5:81/  (Erstlogin: admin@example.com / changeme)

Anmeldung an Checkmk: Benutzer cmkadmin, Passwort aus CMK_PASSWORD.

9. HTTPS einrichten – Let's Encrypt oder selbstsigniert

9.1 NGINX Proxy Manager vorbereiten

http://<server>:81 aufrufen
Erstanmeldung: admin@example.com / changeme
Sofort E-Mail-Adresse und Passwort ändern (wird beim ersten Login erzwungen)

9.2 Proxy-Host für Checkmk anlegen

Hosts → Proxy Hosts → Add Proxy Host

Feld	Wert
Domain Names	`checkmk.example.com` (bzw. der interne Name)
Scheme	`http`
Forward Hostname / IP	`127.0.0.1`
Forward Port	`5000`
Block Common Exploits	ein
Websockets Support	ein (für die Livedaten der Oberfläche)

Reiter Advanced (empfohlen, damit Checkmk die echte Client-IP sieht und große Agent-Uploads funktionieren):

client_max_body_size 0;
proxy_read_timeout 300s;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

9.3 Variante A – Let's Encrypt (öffentlich erreichbarer Server)

Voraussetzungen: der DNS-Name zeigt öffentlich auf diesen Server und Port 80 ist aus dem Internet erreichbar (HTTP-01-Challenge).

Im Proxy-Host, Reiter SSL:

SSL Certificate → Request a new SSL Certificate
Force SSL ein
HTTP/2 Support ein
HSTS Enabled nach Bedarf
E-Mail-Adresse angeben, Nutzungsbedingungen bestätigen → Save

Die Erneuerung übernimmt der Proxy Manager automatisch; die Zertifikate liegen im Bind-Mount data/npm/letsencrypt/ und sind damit im Projektverzeichnis gesichert.

Bei interner DNS-Zone ohne öffentlichen Zugang: DNS-Challenge verwenden (SSL → Use a DNS Challenge → Provider auswählen, API-Token hinterlegen).

9.4 Variante B – Selbstsigniertes Zertifikat (interne Umgebung)

Erzeugen:

sudo ./scripts/cmk-manage.sh cert \
     --domain checkmk.intern.example \
     --alt 10.0.0.5 --alt checkmk \
     --days 3650

Ergebnis in data/npm/custom-certs/checkmk.intern.example/:

privkey.pem – privater Schlüssel
fullchain.pem – Zertifikat (mit SAN für alle angegebenen Namen/IPs)

Einbinden:

SSL Certificates → Add SSL Certificate → Custom
Name vergeben, privkey.pem als Certificate Key, fullchain.pem als Certificate hochladen
Im Proxy-Host unter SSL dieses Zertifikat auswählen, Force SSL und HTTP/2 aktivieren

Damit die Checkmk-Agents und Browser dem Zertifikat vertrauen, muss fullchain.pem auf den Clients als vertrauenswürdiges Zertifikat installiert werden (Windows: Computerzertifikate → Vertrauenswürdige Stammzertifizierungsstellen; Linux: /usr/local/share/ca-certificates/ + update-ca-certificates). Für die reine Agent-Kommunikation über Port 8000 ist das nicht nötig – dort verwendet Checkmk eine eigene, site-interne CA.

Die ncurses-Oberfläche bietet denselben Ablauf unter „Selbstsigniertes Zertifikat erzeugen“.

10. Firewall

firewalld (RHEL/Rocky/Alma):

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-port=8000/tcp          # Agent-Receiver
sudo firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=10.0.0.0/24 port port=81 protocol=tcp accept'
sudo firewall-cmd --reload

ufw (Debian/Ubuntu):

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8000/tcp
sudo ufw allow from 10.0.0.0/24 to any port 81 proto tcp
sudo ufw enable

Port 5000 bleibt geschlossen – der Zugriff erfolgt ausschließlich über den Proxy. Port 81 nur aus dem Administrationsnetz freigeben.

11. Verwaltung: `cmk-manage.sh`

Das Skript ist gleichzeitig Kommandozeilenwerkzeug und ncurses-Oberfläche.

11.1 ncurses-Oberfläche (wie im Midnight Commander)

sudo ./scripts/cmk-manage.sh gui

 ┌──────────────── Checkmk Stack Manager ─────────────────┐
 │ Projekt : /opt/checkmk-stack                           │
 │ Runtime : podman     Standard-Site: cmk                │
 │ Backups : /opt/checkmk-stack/backups                   │
 │                                                        │
 │   status    Status von Containern und Sites            │
 │   stack     Stack steuern (Start/Stop/Logs/Update)     │
 │   backup    Backup erstellen                           │
 │   restore   Backup wiederherstellen                    │
 │   import    Site von Direktinstallation importieren    │
 │   manage    Backups verwalten (Liste/Details/Löschen)  │
 │   sites     Sites im Container verwalten               │
 │   cert      Selbstsigniertes Zertifikat erzeugen       │
 │   env       Konfiguration (.env) ansehen/bearbeiten    │
 │   shell     Root-Shell im Checkmk-Container            │
 │   quit      Beenden                                    │
 │                  <  OK  >   <Cancel>                   │
 └────────────────────────────────────────────────────────┘

Bedienung: Pfeiltasten, Leertaste markiert in Auswahllisten (z. B. mehrere Sites für ein Backup), Enter bestätigt, ESC/Cancel geht zurück. Es wird dialog bevorzugt; ist nur whiptail vorhanden, wird dieses genutzt. Eine Dateiauswahl mit Verzeichnisnavigation ist eingebaut.

11.2 Kommandozeile

./scripts/cmk-manage.sh --help

Kommando	Wirkung
`up` / `down` / `restart` / `pull`	Stack steuern
`status`	Container, Sites, Zugangsadressen
`logs [-f]`	Container-Logs
`sites`	Sites im Container auflisten
`site-start SITE` / `site-stop SITE`	einzelne Site steuern
`start-all-sites`	alle Sites starten (wird von systemd aufgerufen)
`backup …`	Backup als `.tar.gz`-Bundle
`list` / `verify` / `prune --keep N`	Backups verwalten
`restore …`	Backup zurückspielen
`import …`	Migrations-Bundle einspielen
`cert …`	selbstsigniertes Zertifikat erzeugen
`shell`	Root-Shell im Checkmk-Container
`omd …`	beliebiges `omd`-Kommando im Container

Globale Optionen: --env-file DATEI, -y/--yes (keine Rückfragen, z. B. für Cronjobs), -v/--verbose.

12. Backup

Backups werden mit omd backup erstellt und als Bundle verpackt:

cmkbackup_<site>_<version>_<zeitstempel>.tar.gz
└── cmkbundle/
    ├── MANIFEST              Site, Version, Quelle, Prüfsumme …
    ├── INFO.txt              lesbare Zusammenfassung
    ├── site.tar.gz           das eigentliche omd-Backup
    └── site.tar.gz.sha256

Dadurch weiß das Restore-/Import-Werkzeug immer, welche Site und welche Checkmk-Version im Archiv steckt, und kann die Integrität prüfen.

# eine Site
sudo ./scripts/cmk-manage.sh backup --site cmk

# alle Sites, ohne Logdateien, mit Kennzeichnung
sudo ./scripts/cmk-manage.sh backup --all --no-logs --label vor-update

# konsistentestes Backup: Site wird kurz gestoppt
sudo ./scripts/cmk-manage.sh backup --site cmk --stop

# ohne Performance-Daten (deutlich kleiner)
sudo ./scripts/cmk-manage.sh backup --site cmk --no-rrds --dir /mnt/nas/checkmk

Auflisten und prüfen:

./scripts/cmk-manage.sh list
./scripts/cmk-manage.sh verify --file backups/cmkbackup_cmk_2.3.0p23.cre_20260820-030000.tar.gz
./scripts/cmk-manage.sh prune --keep 7

Nächtliches Backup per Cron

sudo crontab -e

15 2 * * * /opt/checkmk-stack/scripts/cmk-manage.sh -y backup --all --no-logs >>/var/log/cmk-backup.log 2>&1
30 3 * * 0 /opt/checkmk-stack/scripts/cmk-manage.sh -y prune --keep 14   >>/var/log/cmk-backup.log 2>&1

13. Restore

# Einfachster Fall: Site existiert nicht mehr
sudo ./scripts/cmk-manage.sh restore --file backups/cmkbackup_cmk_2.3.0p23.cre_20260820-030000.tar.gz

# Vorhandene Site überschreiben (laufende Prozesse beenden)
sudo ./scripts/cmk-manage.sh restore --file backups/… --reuse --kill

# Unter anderem Namen zurückspielen (z. B. für einen Test)
sudo ./scripts/cmk-manage.sh restore --file backups/… --as-site test

Ablauf des Skripts:

Archivstruktur und SHA256-Prüfsumme kontrollieren
prüfen, ob die Checkmk-Version des Backups im Container vorhanden ist
bei vorhandener Site Rückfrage/--reuse, Site stoppen
Archiv in den Container kopieren und omd restore ausführen
TMPFS der Site abschalten (im Container nicht nutzbar)
Site starten und Hinweise ausgeben

--as-site ändert den Site-Namen – registrierte Agents zeigen dann ins Leere und müssten neu registriert werden. Für eine Migration also nicht verwenden.

Ein rohes omd backup-Archiv (ohne Bundle-Hülle) wird ebenfalls akzeptiert; der Site-Name wird dann aus dem Archiv gelesen.

14. Migration einer Direktinstallation (`migrate_creator.sh`)

Ziel: eine bestehende Checkmk-Installation auf Blech/VM in den Container übernehmen – ohne die Agents anzufassen.

14.1 Warum die Agents weiterlaufen

Ein omd backup enthält die komplette Site inklusive etc/ssl (site-eigene CA und Zertifikate der registrierten Agents), etc/check_mk (Regeln, Hosts, Passwörter) und der Monitoring-Historie. Wird die Site unter demselben Namen wiederhergestellt und ist der Server unter derselben IP-Adresse erreichbar, dann

finden Push-/Pull-Agents (cmk-agent-ctl) ihre Registrierung wieder,
bleibt die TLS-Verbindung zum Agent-Receiver auf Port 8000 gültig,
stimmen alle URLs (https://<ip>/<site>/check_mk/…) weiterhin,
bleiben Performance-Daten und Historie erhalten.

Voraussetzung ist deshalb, dass das Zielsystem die IP des Quellservers übernimmt (bzw. der DNS-Name darauf umgestellt wird) – das ist im geplanten Vorgehen ohnehin so.

14.2 Schritt 1 – Skript auf den Quellserver kopieren

scp scripts/migrate_creator.sh root@alt-server:/root/
ssh root@alt-server 'chmod +x /root/migrate_creator.sh'

Das Skript ist eigenständig – es braucht auf dem Quellserver nur bash, tar und omd (für die Oberfläche zusätzlich dialog oder whiptail).

14.3 Schritt 2 – Bundle auf dem Quellserver erzeugen

Vorhandene Sites anzeigen:

sudo ./migrate_creator.sh --list

SITE                 VERSION            STATUS       GROESSE
prod                 2.3.0p23.cre       laeuft       4.7 GiB
test                 2.3.0p23.cre       gestoppt     318.2 MiB

Mit Oberfläche (Sites per Leertaste auswählen):

sudo ./migrate_creator.sh --gui

Der Dialog fragt nacheinander ab: Sites → Optionen (Site stoppen, RRDs/Logs auslassen) → Zielverzeichnis → Kennzeichnung → optionale Übertragung per scp.

Mit Parametern:

# eine Site, Site während des Backups stoppen (konsistenteste Variante)
sudo ./migrate_creator.sh --site prod --stop --out /var/tmp

# alle Sites, ohne Logs, direkt auf das Zielsystem übertragen
sudo ./migrate_creator.sh --all --no-logs \
     --scp root@10.0.0.5:/opt/checkmk-stack/backups/

Ergebnis:

/var/tmp/cmkmigrate_prod_2.3.0p23.cre_20260820-101500.tar.gz

Das Bundle enthält zusätzlich zum omd-Backup ein MANIFEST mit Site-Name, Checkmk-Version, Quell-Hostname, Quell-IP-Adressen, Quell-Betriebssystem und SHA256-Prüfsumme sowie ein Verzeichnis siteinfo/ mit omd config show, omd status und der IP-Konfiguration des Altsystems zur späteren Kontrolle.

14.4 Schritt 3 – Zielsystem auf die richtige Version bringen

omd restore kann eine Site nur wiederherstellen, wenn genau deren Checkmk-Version im Zielsystem installiert ist. Im Container kommt die Version aus dem Image – also muss der Image-Tag passen:

grep CMK_VERSION <(tar -xzOf backups/cmkmigrate_prod_*.tar.gz cmkbundle/MANIFEST)
# CMK_VERSION=2.3.0p23.cre        ->  Image-Tag: 2.3.0p23

sudo $EDITOR .env
#   CMK_IMAGE_TAG=2.3.0p23
sudo ./scripts/cmk-manage.sh up

Das Import-Skript prüft das selbst und bricht mit einer entsprechenden Meldung ab, wenn die Version fehlt.

Edition beachten: .cre = Raw Edition → checkmk/check-mk-raw. Bei .cee / .cce / .cme wird das entsprechende Enterprise-/Cloud-Image benötigt (CMK_IMAGE_REPO=checkmk/check-mk-enterprise, Zugang über die Checkmk-Subskription).

14.5 Schritt 4 – Bundle importieren

Mit Oberfläche:

sudo ./scripts/cmk-manage.sh gui      # -> "import"

Mit Parametern:

sudo ./scripts/cmk-manage.sh import \
     --file backups/cmkmigrate_prod_2.3.0p23.cre_20260820-101500.tar.gz \
     --set-default-site

Das Skript

erkennt das Migrations-Bundle und zeigt Quell-Host und Quell-IP an,
warnt, wenn die IP dieses Hosts von der Quell-IP abweicht (dann müssten die Agents nachgeführt werden),
prüft Prüfsumme, Version und Edition,
fragt bei bereits vorhandener Site nach (--reuse überschreibt),
führt omd restore unter dem unveränderten Site-Namen aus,
setzt auf Wunsch CMK_SITE_ID in der .env (--set-default-site), damit der Container die Site auch nach einem Reboot automatisch startet,
startet die Site und gibt die nächsten Schritte aus.

14.6 Schritt 5 – Umschalten und kontrollieren

# 1) Alten Server abschalten bzw. dessen Site stoppen (kein Doppel-Monitoring!)
ssh root@alt-server 'omd stop prod'

# 2) Zielsystem auf die IP/den DNS-Namen des Altsystems umstellen
#    (statische IP übernehmen oder DNS-Eintrag umbiegen)

# 3) Container neu erstellen, falls CMK_SITE_ID geändert wurde
sudo ./scripts/cmk-manage.sh up
sudo ./scripts/cmk-manage.sh status

# 4) Kontrolle in Checkmk
sudo ./scripts/cmk-manage.sh omd su prod
   OMD[prod]:~$ cmk -O                # Konfiguration aktivieren
   OMD[prod]:~$ omd status
   OMD[prod]:~$ exit

Danach in der Oberfläche prüfen:

Monitor → All hosts – melden sich die Agents wieder?
Bei TLS-Agents: der Service „Check_MK Agent“ darf keine Registrierungsfehler melden.
Ein Agent lässt sich vom überwachten Host aus testen mit cmk-agent-ctl status – dort muss die Site prod mit dem Zielserver und „Connection: TLS“ erscheinen.

14.7 Checkliste Migration

migrate_creator.sh auf den Quellserver kopiert
Bundle erzeugt (möglichst mit --stop)
Bundle auf das Zielsystem kopiert (backups/)
CMK_IMAGE_TAG auf die Quellversion gesetzt, Stack neu erstellt
import --set-default-site ausgeführt, Site läuft
Alte Site gestoppt / alter Server abgeschaltet
IP bzw. DNS auf das Zielsystem umgestellt
Ports 80/443/8000 in der Firewall offen
Proxy-Host im NGINX Proxy Manager mit Zertifikat eingerichtet
Agents melden sich, cmk -O ausgeführt
Backup des neuen Systems eingerichtet (Cron)

15. Mehrere Sites in einem Container

Der Checkmk-Entrypoint legt beim Start nur die Site aus CMK_SITE_ID an und startet auch nur diese. Weitere Sites (z. B. mehrere importierte) existieren im Bind-Mount, werden aber nach einem Neustart nicht automatisch hochgefahren.

Deshalb:

sudo ./scripts/cmk-manage.sh start-all-sites

Dieses Kommando wird von der systemd-Unit (ExecStartPost) bzw. der Quadlet-Unit automatisch nach dem Containerstart ausgeführt und startet alle vorhandenen Sites.

Empfehlung: Für sauber getrennte Umgebungen lieber je Site ein eigenes Projektverzeichnis mit eigener .env betreiben. Da beide Container im Host-Netzwerk laufen, kann pro Host allerdings nur ein Checkmk-Container die Ports 5000/8000 belegen – für echte Mehrfachinstanzen dann getrennte Hosts oder eine Bridge-Netzwerk-Variante verwenden.

16. Checkmk aktualisieren

Da /omd/sites ein Bind-Mount ist, überleben die Daten den Austausch des Images. Die Checkmk-Software selbst steckt im Image unter /omd/versions.

# 1) IMMER zuerst sichern
sudo ./scripts/cmk-manage.sh backup --all --label vor-update

# 2) neuen Tag eintragen
sudo $EDITOR .env          # z.B. CMK_IMAGE_TAG=2.3.0p28

# 3) Image holen und Container neu erstellen
sudo ./scripts/cmk-manage.sh pull
sudo ./scripts/cmk-manage.sh up

# 4) Site aktualisieren (interaktiv, Konflikte bestätigen)
sudo ./scripts/cmk-manage.sh omd stop cmk
sudo ./scripts/cmk-manage.sh omd update cmk
sudo ./scripts/cmk-manage.sh omd start cmk

Bei einem Versionssprung (z. B. 2.2 → 2.3) unbedingt vorher die Checkmk-Werksnotizen (Werks/Release Notes) lesen.

17. Fehlersuche

Symptom	Ursache / Lösung
`Port 80/443 already in use`	Auf dem Host läuft bereits ein Webserver: `ss -tlnp \| grep ':80'` → `systemctl disable --now apache2 nginx httpd`
Nach Reboot laufen die Container nicht (Podman)	systemd-Unit fehlt: `./install.sh --with-systemd` bzw. `--quadlet`, danach `systemctl is-enabled checkmk-stack`
`omd restore`: version is not installed	`CMK_IMAGE_TAG` in der `.env` auf die Version aus dem `MANIFEST` setzen und `up` ausführen
Import bricht mit Editions-Warnung ab	Enterprise-Backup benötigt das Enterprise-Image (`CMK_IMAGE_REPO`)
Proxy zeigt `502 Bad Gateway`	Checkmk-Container läuft nicht oder Weiterleitung nicht auf `127.0.0.1:5000` gesetzt: `./scripts/cmk-manage.sh status`, `curl -I http://127.0.0.1:5000/`
Let's Encrypt schlägt fehl	Port 80 aus dem Internet nicht erreichbar oder DNS falsch; Alternative: DNS-Challenge oder selbstsigniertes Zertifikat
Agents melden sich nach der Migration nicht	Site-Name geändert (`--as-site`), IP nicht übernommen oder Port 8000 blockiert; auf dem Agent prüfen: `cmk-agent-ctl status`
Permission denied auf `data/` unter RHEL	SELinux: `restorecon -Rv /opt/checkmk-stack/data`, `:Z` an den Mounts prüfen
`podman-compose` nicht gefunden	EPEL aktivieren oder auf Quadlet umstellen (`./install.sh --quadlet`)
TUI startet nicht	`dialog` installieren: `apt-get install -y dialog` bzw. `dnf install -y dialog`
Site startet nicht, `tmp`-Fehler	`./scripts/cmk-manage.sh omd config <site> set TMPFS off`, danach Site starten

Nützliche Kommandos:

./scripts/cmk-manage.sh logs -f                  # Container-Logs
./scripts/cmk-manage.sh omd status cmk           # Dienste der Site
./scripts/cmk-manage.sh shell                    # Root-Shell im Container
docker exec -it checkmk omd su cmk               # bzw. podman exec …

18. Sicherheitshinweise

CMK_PASSWORD sofort nach der Installation in der Oberfläche ändern und aus der .env entfernen (wird nur bei der Neuanlage ausgewertet); chmod 600 .env ist gesetzt.
Standardzugang des Proxy Managers (admin@example.com / changeme) beim ersten Login zwingend ändern.
Port 81 (Adminoberfläche) nur aus dem Administrationsnetz erreichbar machen, Port 5000 gar nicht nach außen öffnen.
Backups enthalten alle Passwörter und Zertifikate der Site – verschlüsselt ablegen bzw. Zugriffsrechte eng fassen (chmod 700 backups).
Regelmäßig ./scripts/cmk-manage.sh pull + up für Sicherheitsupdates der Images einplanen.
Host-Netzwerk bedeutet: der Container teilt sich den Netzwerk-Stack des Hosts. Es gibt keine zusätzliche Netzwerkisolierung – die Absicherung erfolgt über die Firewall des Hosts.

19. Deinstallation

sudo ./scripts/cmk-manage.sh down

# systemd
sudo systemctl disable --now checkmk-stack.service
sudo rm -f /etc/systemd/system/checkmk-stack.service
# bzw. Quadlet
sudo rm -f /etc/containers/systemd/checkmk.container \
           /etc/containers/systemd/nginx-proxy-manager.container
sudo systemctl daemon-reload

# Images entfernen
docker image rm checkmk/check-mk-raw:2.3.0-latest jc21/nginx-proxy-manager:2
# podman image rm …

# Daten (ACHTUNG: löscht die komplette Überwachung!)
sudo rm -rf /opt/checkmk-stack/data

Lizenz / Hinweise

Dieses Projekt enthält lediglich Konfiguration und Hilfsskripte. Checkmk (Raw Edition, GPLv2) und NGINX Proxy Manager (MIT) unterliegen den Lizenzbedingungen der jeweiligen Hersteller.

README.md Unescape Escape

Checkmk im Container – Docker (Debian) & Podman (RHEL) mit NGINX Proxy Manager