first commit

2026-08-20 10:33:59 +02:00
commit 75fba0229a
14 changed files with 3076 additions and 0 deletions
@@ -0,0 +1,930 @@
+# 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](#1-überblick--architektur)
+2. [Verzeichnisstruktur](#2-verzeichnisstruktur)
+3. [Voraussetzungen & Ports](#3-voraussetzungen--ports)
+4. [Installation auf Debian/Ubuntu (Docker)](#4-installation-auf-debianubuntu-docker)
+5. [Installation auf RHEL/Rocky/Alma/Fedora (Podman)](#5-installation-auf-rhelrockyalmafedora-podman)
+6. [Autostart nach einem Neustart des Hosts (Podman)](#6-autostart-nach-einem-neustart-des-hosts-podman)
+7. [Konfiguration (`.env`)](#7-konfiguration-env)
+8. [Erststart](#8-erststart)
+9. [HTTPS einrichten – Let's Encrypt oder selbstsigniert](#9-https-einrichten--lets-encrypt-oder-selbstsigniert)
+10. [Firewall](#10-firewall)
+11. [Verwaltung: `cmk-manage.sh` (CLI und ncurses-Oberfläche)](#11-verwaltung-cmk-managesh)
+12. [Backup](#12-backup)
+13. [Restore](#13-restore)
+14. [Migration einer Direktinstallation (`migrate_creator.sh`)](#14-migration-einer-direktinstallation-migrate_creatorsh)
+15. [Mehrere Sites in einem Container](#15-mehrere-sites-in-einem-container)
+16. [Checkmk aktualisieren](#16-checkmk-aktualisieren)
+17. [Fehlersuche](#17-fehlersuche)
+18. [Sicherheitshinweise](#18-sicherheitshinweise)
+19. [Deinstallation](#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)
+
+```bash
+# 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:
+
+```bash
+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](#15-mehrere-sites-in-einem-container)).
+
+---
+
+## 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.
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+sudo ./install.sh --quadlet
+```
+
+Das schreibt (mit den Werten aus der `.env`) nach `/etc/containers/systemd/`:
+
+* `checkmk.container`
+* `nginx-proxy-manager.container`
+
+Danach:
+
+```bash
+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/](systemd/quadlet/).
+
+### Variante C – rootless Podman (optional, erhöhter Aufwand)
+
+```bash
+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`)
+
+```bash
+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
+
+```bash
+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):
+
+```nginx
+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:
+
+```bash
+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):**
+
+```bash
+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):**
+
+```bash
+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)
+
+```bash
+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
+
+```bash
+./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.
+
+```bash
+# 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:
+
+```bash
+./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
+
+```bash
+sudo crontab -e
+```
+
+```cron
+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
+
+```bash
+# 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
+
+```bash
+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:
+
+```bash
+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):
+
+```bash
+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:**
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+sudo ./scripts/cmk-manage.sh gui      # -> "import"
+```
+
+Mit Parametern:
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+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`.
+
+```bash
+# 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:
+
+```bash
+./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
+
+```bash
+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.