Hacker-Software/docker-podman-installation-with-nginx-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
docker-podman-installation-…/README.md
T
duffyduck 75fba0229a first commit
2026-08-20 10:33:59 +02:00

33 KiB
Raw Permalink Blame History

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

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

  1. Überblick & Architektur
  2. Verzeichnisstruktur
  3. Voraussetzungen & Ports
  4. Installation auf Debian/Ubuntu (Docker)
  5. Installation auf RHEL/Rocky/Alma/Fedora (Podman)
  6. Autostart nach einem Neustart des Hosts (Podman)
  7. Konfiguration (.env)
  8. Erststart
  9. HTTPS einrichten – Let's Encrypt oder selbstsigniert
  10. Firewall
  11. Verwaltung: cmk-manage.sh (CLI und ncurses-Oberfläche)
  12. Backup
  13. Restore
  14. Migration einer Direktinstallation (migrate_creator.sh)
  15. Mehrere Sites in einem Container
  16. Checkmk aktualisieren
  17. Fehlersuche
  18. Sicherheitshinweise
  19. 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:

  1. Docker-Repository von download.docker.com einbinden (GPG-Key + Sources-Liste)
  2. docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, docker-compose-plugin installieren
  3. dialog, openssl, tar, curl installieren (für die ncurses-Oberfläche)
  4. systemctl enable --now docker
  5. Verzeichnisse unter data/ und backups/ anlegen, .env aus .env.example erzeugen
  6. 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:

  1. podman, tar, dialog, openssl
  2. podman-compose – in dieser Reihenfolge versucht: Distributions-Repository → EPEL → pip3 install podman-compose
  3. 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

  1. http://<server>:81 aufrufen
  2. Erstanmeldung: admin@example.com / changeme
  3. 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:

  1. SSL Certificates → Add SSL Certificate → Custom
  2. Name vergeben, privkey.pem als Certificate Key, fullchain.pem als Certificate hochladen
  3. 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:

  1. Archivstruktur und SHA256-Prüfsumme kontrollieren
  2. prüfen, ob die Checkmk-Version des Backups im Container vorhanden ist
  3. bei vorhandener Site Rückfrage/--reuse, Site stoppen
  4. Archiv in den Container kopieren und omd restore ausführen
  5. TMPFS der Site abschalten (im Container nicht nutzbar)
  6. 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

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

Reference in New Issue View Git Blame Copy Permalink