931 lines
33 KiB
Markdown
931 lines
33 KiB
Markdown
# 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.
|