Hacker-Software/docker-podman-installation-with-nginx-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c1371da7aaebbc68dac6b69e4abfba0f885b58ba
docker-podman-installation-…/README.md
T
duffyduckandClaude Opus 5 c1371da7aa Zugangsdaten: .netrc ersetzt - Kennwoerter mit Sonderzeichen kamen 
verstuemmelt an

Der Download schlug trotz richtiger Zugangsdaten fehl. Ursache gefunden:
die Uebergabe lief ueber eine temporaere .netrc, deren Format die Felder
durch Leerzeichen trennt. Ein Kennwort mit Leerzeichen, #, " oder
aehnlichem kam dadurch still verstuemmelt an - curl schickte etwas
anderes als hinterlegt, der Server antwortete 401, und die Meldung
lautete "Anmeldung abgelehnt", obwohl die Daten stimmten.

Gegen einen eigens gestarteten Testserver nachgemessen, Kennwort
'Pa ss#wo"rt$1':
    ohne Anmeldung            HTTP 401
    neu, curl --config -      HTTP 200
    alt, .netrc               HTTP 401

Alle dreizehn Aufrufstellen sind auf curl_auth umgestellt, das die
Angaben ueber "curl --config -" von der Standardeingabe liest und in
Anfuehrungszeichen setzt. Beliebige Zeichen sind damit moeglich, und die
Zugangsdaten stehen weiterhin nicht in der Prozessliste - geprueft.

Ausserdem sagt der Download jetzt, WORAN es liegt: vor dem Holen wird
der Status abgefragt und 401/403 (Anmeldung), 404 (Datei gibt es nicht)
und 000 (nicht erreichbar) getrennt gemeldet. Doppelte Kandidaten
werden nicht mehr zweimal probiert.

Dazu zwei Aergernisse aus der Bedienung beseitigt:
  * Der Assistent meldete nach "nur eintragen" die Abweichung als
    Problem, obwohl der Benutzer genau das gewollt hatte. Jetzt steht
    dort schlicht, dass Edition und Version gespeichert sind und kein
    Image geholt wurde.
  * Der Dialog hinter CMK_IMAGE/EDITION/VERSION war lang und erklaerte
    mehr, als er half. Er nennt jetzt in zwei Zeilen die Lage und stellt
    die Handlung voran.

Randnotiz zur Fehlersuche: die URL selbst war nie das Problem. Der
Server liefert fuer check-mk-enterprise-docker-2.4.0p9.tar.gz ein 401,
also "vorhanden, nur geschuetzt" - und fuer check-mk-pro-... ein 404,
denn "pro" heisst die Edition erst ab 2.5.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-20 18:11:19 +02:00

2383 lines
94 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Checkmk im Container – Docker (Debian) & Podman (RHEL) mit NGINX Proxy Manager
*[English version: README_en.md](README_en.md)*
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)
* [5.1 Unregistriertes RHEL: woher die Pakete kommen](#51-unregistriertes-rhel-woher-die-pakete-kommen)
6. [Autostart nach einem Neustart des Hosts (Podman)](#6-autostart-nach-einem-neustart-des-hosts-podman)
7. [Konfiguration (`.env`)](#7-konfiguration-env)
8. [Checkmk-Image beschaffen (Raw, Enterprise & Co.)](#8-checkmk-image-beschaffen-raw-enterprise--co)
9. [Erststart](#9-erststart)
10. [HTTPS einrichten – Let's Encrypt oder selbstsigniert](#10-https-einrichten--lets-encrypt-oder-selbstsigniert)
11. [Proxy Manager lokal einrichten (Terminal-Browser)](#11-proxy-manager-lokal-einrichten-terminal-browser)
12. [Adminoberfläche auf einen anderen Port legen](#12-adminoberfläche-auf-einen-anderen-port-legen)
13. [Firewall](#13-firewall)
14. [Verwaltung: `cmk-manage.sh` (CLI und ncurses-Oberfläche)](#14-verwaltung-cmk-managesh)
15. [Backup](#15-backup)
16. [Restore](#16-restore)
17. [Migration einer Direktinstallation (`migrate_creator.sh`)](#17-migration-einer-direktinstallation-migrate_creatorsh)
18. [Mehrere Sites in einem Container](#18-mehrere-sites-in-einem-container)
19. [Checkmk aktualisieren](#19-checkmk-aktualisieren)
20. [Fehlersuche](#20-fehlersuche)
21. [Sicherheitshinweise](#21-sicherheitshinweise)
22. [Deinstallation](#22-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 # deutsche Dokumentation
├── README_en.md # englische Fassung
├── 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
│
├── containers/
│ └── browser/
│ └── Containerfile # Werkzeug-Image: Textbrowser, curl, jq, openssl
│
├── 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)
└── images/ # heruntergeladene Checkmk-Image-Tarballs
```
---
## 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** (Vorgabe; per [`npm-port`](#12-adminoberfläche-auf-einen-anderen-port-legen) änderbar) | nur Admin-Netz! |
| 5000/tcp | Checkmk Apache (Backend) | **nur localhost** – nicht freigeben. Ausnahme: bei abgeschaltetem Proxy Manager ([12.4](#124-proxy-manager-ganz-abschalten-externer-nginx)) nur für die IP des externen Proxys |
| 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
# Image festlegen (Raw geht ohne Anmeldung, Enterprise siehe Kapitel 8)
sudo ./scripts/cmk-manage.sh image pull --edition raw --version 2.3.0-latest
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 18](#18-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.
> ### Schritt 0 bei RHEL: Subskription prüfen
>
> **Ein nicht registriertes RHEL installiert überhaupt keine Pakete** – weder
> `podman` noch `git`, `dialog` oder `tar`. `dnf` meldet dann nur
> *„This system is not registered with an entitlement server"*. Das ist der
> häufigste Grund, warum `install.sh` auf einem frischen RHEL nicht durchläuft.
>
> ```bash
> # Ist das System registriert?
> sudo subscription-manager status # -> "Overall Status: Current" = in Ordnung
> sudo dnf repolist # -> darf nicht leer sein
>
> # Falls nicht: kostenloses Konto auf https://developers.redhat.com anlegen
> # (Developer Subscription for Individuals, bis zu 16 Systeme) und dann:
> sudo subscription-manager register --username <benutzer>
> ```
>
> RHEL 9 nutzt *Simple Content Access*, ein `subscription-manager attach` ist
> **nicht** mehr nötig. Ohne Konto geht es auch per Installations-DVD oder durch
> den Wechsel auf Rocky/Alma – alle drei Wege stehen ausführlich in
> [Abschnitt 5.1](#51-unregistriertes-rhel-woher-die-pakete-kommen).
>
> **Rocky Linux, AlmaLinux, CentOS Stream und Fedora** brauchen nichts davon –
> dort einfach weiterlesen.
```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. prüft zuerst, ob überhaupt ein nutzbares Repository vorhanden ist, und
nennt andernfalls die drei Wege aus [Abschnitt 5.1](#51-unregistriertes-rhel-woher-die-pakete-kommen)
2. `podman`, `tar`, `openssl`
3. `dialog` für die ncurses-Oberfläche – schlägt das fehl, wird `newt`
(`whiptail`) genommen; beides unterstützen die Skripte
4. `podman-compose` – in dieser Reihenfolge versucht:
Distributions-Repository → EPEL → `pip3 install podman-compose`
5. richtet die systemd-Unit ein (bei Podman **immer**, siehe nächstes Kapitel)
Manuell entspricht das:
```bash
sudo dnf install -y podman podman-compose tar openssl
sudo dnf install -y dialog || sudo dnf install -y newt # dialog: AppStream, newt: BaseOS
# Falls podman-compose nicht im Repo ist - EPEL nachrüsten:
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
sudo dnf install -y podman-compose
```
> **EPEL setzt eine funktionierende Subskription voraus.** Das Paket
> `epel-release` konfiguriert nur die EPEL-Quelle; seine Abhängigkeiten und
> alles, was danach daraus installiert wird, kommen weiterhin aus Red Hats
> BaseOS/AppStream. Auf einem nicht registrierten System scheitert deshalb
> schon der Befehl oben – EPEL ist **kein** Ersatz für die Registrierung.
>
> Bleibt `podman-compose` deswegen unerreichbar, ist das kein Hindernis:
> mit **Quadlet** ([Kapitel 6, Variante B](#variante-b--podman-quadlet-ab-podman-44-ohne-compose))
> läuft der Stack ganz ohne Compose, direkt über systemd.
Starten:
```bash
sudo $EDITOR /opt/checkmk-stack/.env
# Image beschaffen - bei Enterprise mit Zugangsdaten, siehe Kapitel 8
sudo ./scripts/cmk-manage.sh image pull --edition enterprise --version 2.3.0p23 \
--user <benutzer> --password <kennwort>
sudo ./scripts/cmk-manage.sh up # nutzt automatisch podman-compose
sudo ./scripts/cmk-manage.sh status
```
> Auf RHEL unbedingt [Kapitel 8.2](#82-zwei-podman-fallstricke-genau-die-aus-der-praxis)
> lesen: kurze Image-Namen und `podman import` statt `podman load` sind die
> beiden Ursachen fuer „Image unbekannt“.
### 5.1 Unregistriertes RHEL: woher die Pakete kommen
Ein frisch installiertes Red Hat Enterprise Linux ohne Subskription liefert
gar nichts aus:
```
$ sudo dnf install -y podman
This system is not registered with an entitlement server.
You can use "rhc" or "subscription-manager" to register.
Error: There are no enabled repositories in "/etc/yum.repos.d".
```
Das betrifft **alle** Pakete – `podman`, `git`, `dialog`, `tar`. Es gibt drei
Wege, und `install.sh` erkennt die Lage inzwischen selbst und nennt sie.
> Nur RHEL selbst ist betroffen. **Rocky Linux, AlmaLinux, CentOS Stream und
> Fedora** brauchen keine Registrierung – dort funktioniert `dnf` sofort.
#### Weg 1 – kostenlose Developer-Subskription (empfohlen)
Red Hat vergibt die *Developer Subscription for Individuals* kostenlos. Sie
gilt für **bis zu 16 Systeme**, physisch oder virtuell, und deckt neben
Entwicklung und Test ausdrücklich auch **kleine Produktivnutzung** ab. Sie wird
an die Person vergeben, nicht an die Firma.
1. Kostenloses Konto auf <https://developers.redhat.com> anlegen
2. Auf dem Server registrieren:
```bash
sudo subscription-manager register --username <benutzer>
# Kennwort wird abgefragt; alternativ --password <kennwort>
```
RHEL 9 nutzt *Simple Content Access* – die Repositories sind damit sofort
freigeschaltet, ein `subscription-manager attach` ist **nicht** mehr nötig.
3. Kontrolle:
```bash
sudo subscription-manager status # -> Overall Status: Current
sudo dnf repolist # -> rhel-9-for-x86_64-baseos-rpms u.a.
sudo dnf install -y git podman
```
Fehlen einzelne Repositories:
```bash
sudo subscription-manager repos --list-enabled
sudo subscription-manager repos --enable=rhel-9-for-x86_64-appstream-rpms
```
Bei einem Firmenkonto mit Aktivierungsschlüssel stattdessen:
```bash
sudo subscription-manager register --org <org-id> --activationkey <schluessel>
```
#### Weg 2 – Installations-DVD als lokales Repository (ohne Konto, offline)
Funktioniert ohne jede Registrierung und ohne Internet. Voraussetzung ist die
**DVD-ISO** (`rhel-9.x-x86_64-dvd.iso`, mehrere GB) – die kleine `boot.iso`
enthält keine Pakete.
```bash
# ISO dauerhaft einhängen
sudo mkdir -p /mnt/rhel
sudo mount -o loop,ro /pfad/rhel-9.8-x86_64-dvd.iso /mnt/rhel
# beim Booten automatisch einhängen
echo '/pfad/rhel-9.8-x86_64-dvd.iso /mnt/rhel iso9660 loop,ro,nofail 0 0' \
| sudo tee -a /etc/fstab
# Repository-Datei anlegen
sudo tee /etc/yum.repos.d/rhel-local.repo >/dev/null <<'REPO'
[rhel-local-baseos]
name=RHEL local - BaseOS
baseurl=file:///mnt/rhel/BaseOS
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
[rhel-local-appstream]
name=RHEL local - AppStream
baseurl=file:///mnt/rhel/AppStream
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
REPO
sudo dnf clean all
sudo dnf repolist
sudo dnf install -y podman tar openssl dialog git
```
> **Grenze:** Das lokale Repository enthält exakt den Stand der ISO – es gibt
> **keine Sicherheitsupdates**. Für einen dauerhaft betriebenen
> Monitoring-Server ist das kein Zustand; als Überbrückung, bis die
> Registrierung steht, ist es in Ordnung.
#### Weg 3 – auf Rocky Linux oder AlmaLinux wechseln
Beide sind binärkompatible Nachbauten von RHEL, dauerhaft kostenfrei und ohne
Registrierung. Dieses Projekt läuft dort unverändert – `install.sh` erkennt sie
als RHEL-Familie.
```bash
# Rocky Linux
sudo dnf install -y git
sudo git clone https://github.com/rocky-linux/rocky-tools.git
sudo bash rocky-tools/migrate2rocky/migrate2rocky.sh -r
# AlmaLinux
curl -O https://raw.githubusercontent.com/AlmaLinux/almalinux-deploy/master/almalinux-deploy.sh
sudo bash almalinux-deploy.sh
```
> Vorher ein Backup bzw. einen Snapshot anlegen. Die Umstellung tauscht die
> Basispakete im laufenden System aus.
#### Was dieses Projekt tatsächlich braucht
| Paket | Wofür | Repository |
|---|---|---|
| `podman` | Container-Runtime | AppStream |
| `tar` | Backups und Migrations-Bundles | BaseOS |
| `openssl` | selbstsignierte Zertifikate | BaseOS |
| `dialog` | ncurses-Oberfläche | AppStream |
| `newt` (`whiptail`) | Ersatz, falls `dialog` fehlt | BaseOS |
| `curl` | Image-Download | BaseOS |
| `podman-compose` | Compose-Unterstützung | EPEL oder `pip3` |
| `git` | nur zum Klonen dieses Projekts | AppStream |
`dialog` ist **optional**: fehlt es, nutzen die Skripte automatisch `whiptail`
aus dem Paket `newt`, das in BaseOS liegt. `install.sh` versucht genau diese
Reihenfolge und bricht deswegen nicht mehr ab.
`git` wird nicht zwingend gebraucht – das Projekt lässt sich genauso als ZIP
oder per `scp` auf den Server bringen.
> **EPEL hilft hier nicht:** Das EPEL-Repository setzt die Basis-Repositories
> von Red Hat voraus. Ohne Subskription oder lokales Repository lässt sich auch
> `epel-release` nicht installieren – und damit kein `podman-compose`. In dem
> Fall ist der Quadlet-Weg aus [Kapitel 6](#6-autostart-nach-einem-neustart-des-hosts-podman)
> die Lösung: er kommt ganz ohne Compose aus.
### 5.2 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` | **das tatsaechlich verwendete Image**, immer vollqualifiziert – siehe [Kapitel 8](#8-checkmk-image-beschaffen-raw-enterprise--co) |
| `CMK_EDITION`, `CMK_VERSION` | nur Vorgaben fuer den Image-Downloader |
| `CMK_REGISTRY_USER/-PASSWORD` | Anmeldung an `registry.checkmk.com` (Enterprise) |
| `CMK_DOWNLOAD_USER/-PASSWORD` | Anmeldung am Checkmk-Downloadportal |
| `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` |
| `NPM_ENABLED` | `on`/`off` – soll der Proxy-Manager-Container überhaupt laufen? Siehe [12.4](#124-proxy-manager-ganz-abschalten-externer-nginx) |
| `NPM_ADMIN_PORT` | Port der Proxy-Manager-Oberfläche (Vorgabe 81) – nur über `npm-port` bzw. das Menü ändern |
| `NPM_ADMIN_URL` | Startseite des Terminal-Browsers; leer = automatisch aus `NPM_ADMIN_PORT` |
| `BACKUP_DIR` | Ablage für **manuelle** Backups (Vorgabe `./backups`); geplante Jobs haben eigene Pfade |
| `BACKUP_AUTO` | `on`/`off` – sollen die Backup-Jobs per cron laufen? |
| `CERT_DOMAIN`, `CERT_DAYS` | Vorgaben für selbstsignierte Zertifikate |
### 7.1 Wer liest die `.env` – und warum gibt es sie zusätzlich zum Skript?
Die `.env` ist die **einzige** Konfigurationsdatei. Es gibt bewusst keine zweite
Konfiguration im Verwaltungsskript:
```
.env (einzige Quelle der Wahrheit)
|
+---------------+----------------+------------------+
| | | |
docker-compose systemd-Unit cmk-manage.sh migrate_creator.sh
(Variablen- (EnvironmentFile) (source) (unabhaengig, laeuft
ersetzung) auf dem Quellserver)
```
* **Gelesen** wird sie von compose, von der systemd-Unit und vom Skript.
* **Geschrieben** wird sie durch das Skript – entweder gezielt
(`image …` setzt `CMK_IMAGE`, `import --set-default-site` setzt
`CMK_SITE_ID`, `npm-port` setzt `NPM_ADMIN_PORT`) oder über das
Einstellungsmenü bzw. `config set` (siehe [Kapitel 14](#14-verwaltung-cmk-managesh)).
Ein Editor ist damit nicht mehr nötig, bleibt aber als Menüpunkt erhalten.
* Das Skript selbst haelt nur **Rueckfallwerte** fuer den Fall, dass ein
Schluessel in der `.env` fehlt (in `scripts/lib/common.sh`, Funktion
`load_env`). Es ueberschreibt niemals einen gesetzten Wert.
Kurz: die `.env` sagt *was* laeuft, das Skript *macht* etwas damit. Doppelt
gepflegt werden muss nichts.
---
## 8. Checkmk-Image beschaffen (Raw, Enterprise & Co.)
### 8.1 Welche Edition liegt wo?
Das ist die haeufigste Stolperfalle: **die Enterprise-Edition liegt nicht auf
Docker Hub.** Im Namensraum `checkmk` auf Docker Hub gibt es ausschliesslich:
| Edition (`CMK_EDITION`) | Bezugsquelle | Anmeldung |
|---|---|---|
| `raw` (bis 2.4) | `docker.io/checkmk/check-mk-raw` | nein |
| `community` (ab 2.5, Nachfolger von raw) | `docker.io/checkmk/check-mk-community` | nein |
| `cloud` | `docker.io/checkmk/check-mk-cloud` | nein |
| `managed` (bis 2.4) | `docker.io/checkmk/check-mk-managed` | nein |
| `pro` (ab 2.5, Nachfolger von enterprise) | `docker.io/checkmk/check-mk-pro` | nein |
| `ultimate`, `ultimatemt` (ab 2.5) | `docker.io/checkmk/check-mk-ultimate[mt]` | nein |
| **`enterprise` (2.0 – 2.4)** | **`registry.checkmk.com/enterprise/check-mk-enterprise`** oder Image-Tarball aus dem Kundenportal | **ja** |
| `free` (historisch, bis 2.1) | `docker.io/checkmk/check-mk-free` | nein |
Ab Checkmk 2.5 wurden die Editionen umbenannt; diese Images liegen wieder offen
auf Docker Hub. Wer also eine **2.5 oder neuer** einsetzt, nimmt einfach `pro`.
Fuer **2.2/2.3/2.4-Enterprise** fuehrt nur der Weg ueber `registry.checkmk.com`
oder den Tarball.
#### Vorsicht bei den Namen
Die Umbenennung ist die zweite grosse Stolperfalle. **checkmk.com zeigt nur
noch die neuen Namen, die Dateien und Repositories tragen bis 2.4 aber die
alten.** Konkret für 2.3.0p9 – geprüft am Versionsarchiv:
| Auswahl auf checkmk.com | `--edition` hier | tatsächlicher Dateiname |
|---|---|---|
| Community | `raw` | `check-mk-raw-docker-2.3.0p9.tar.gz` |
| **Pro** | **`enterprise`** | **`check-mk-enterprise-docker-2.3.0p9.tar.gz`** |
| Ultimate | `cloud` | `check-mk-cloud-docker-2.3.0p9.tar.gz` |
| Ultimate MT | `managed` | `check-mk-managed-docker-2.3.0p9.tar.gz` |
Wer auf der Website „Pro" wählt und daraus `check-mk-pro-docker-2.3.0p9.tar.gz`
ableitet, bekommt ein **HTTP 404** – diese Datei gibt es für 2.3 nicht.
Das Skript nimmt einem das ab: es liest den echten Dateinamen aus dem
Versionsarchiv und probiert zusätzlich beide Namensvarianten durch. In der
Oberfläche steht in der Editionsauswahl jeweils beides.
> Frei herunterladbar heisst nicht lizenzfrei – der Lizenzschluessel wird
> anschliessend in Checkmk selbst hinterlegt.
### 8.2 Zwei Podman-Fallstricke (genau die aus der Praxis)
**1. Kurze Image-Namen.** Podman kennt keine Vorgabe-Registry. Kurze Namen wie
`checkmk/check-mk-enterprise:2.3.0p23` werden ueber
`unqualified-search-registries` aus `/etc/containers/registries.conf` aufgeloest
– auf RHEL steht dort `registry.access.redhat.com` an **erster** Stelle. Podman
sucht das Image also bei Red Hat, findet es nicht und meldet
`image not known` bzw. fragt interaktiv nach. Deshalb steht in `.env` und
`docker-compose.yml` konsequent der **vollqualifizierte** Name:
```
CMK_IMAGE=registry.checkmk.com/enterprise/check-mk-enterprise:2.3.0p23
```
Aktuelle Auflösungsreihenfolge ansehen:
```bash
grep -A3 unqualified-search-registries /etc/containers/registries.conf
```
**2. `import` statt `load`.** Ein heruntergeladener Image-Tarball wird mit
**`load`** eingespielt:
| Kommando | Erwartet | Ergebnis |
|---|---|---|
| `podman import datei.tar.gz` | ein **Dateisystem**-Archiv (rootfs) | Image **ohne** Entrypoint, ohne Umgebung, ohne Tag → unbrauchbar, „Image unbekannt“ |
| `podman load -i datei.tar.gz` | ein **Image**-Archiv (`docker save`/OCI) | vollstaendiges Image inkl. Metadaten und Tag ✔ |
Ein mit `import` erzeugtes Fehl-Image wieder loswerden:
```bash
podman images | grep '<none>'
podman rmi <image-id>
```
`cmk-manage.sh image load` prueft das Archiv vorher auf `manifest.json` bzw.
`oci-layout` und weist ein falsches Archiv mit genau diesem Hinweis ab.
### 8.3 Zugangsdaten in der `.env` hinterlegen
```bash
CMK_EDITION=enterprise
CMK_VERSION=2.3.0p23
# Bezugsweg 1 - private Registry
CMK_REGISTRY=registry.checkmk.com
CMK_REGISTRY_USER=<benutzer-aus-dem-kundenportal>
CMK_REGISTRY_PASSWORD=<kennwort>
# Bezugsweg 2 - Tarball vom Downloadportal
CMK_DOWNLOAD_BASEURL=https://download.checkmk.com/checkmk
CMK_DOWNLOAD_USER=<benutzer>
CMK_DOWNLOAD_PASSWORD=<kennwort>
```
Die Zugangsdaten stammen aus dem Checkmk-Kundenportal (portal.checkmk.com).
Die `.env` sollte deshalb `chmod 600` haben – `install.sh` setzt das.
### 8.4 Zugangsdaten vorab prüfen
Bevor ein mehrere Gigabyte grosser Download an einer falschen Anmeldung
scheitert, lässt sich beides in Sekunden testen:
```bash
./scripts/cmk-manage.sh image test --edition enterprise --version 2.3.0p23
```
Geprüft wird ohne jeden Download und ohne dass eine Anmeldung gespeichert wird:
| Prüfung | Was sie beantwortet |
|---|---|
| Registry erreichbar | Netzwerk, Proxy, DNS |
| Anmeldung akzeptiert | stimmen Benutzer und Kennwort? |
| Zugriff auf das Repository | hat das Konto die nötige Berechtigung (Subskription)? |
| Downloadportal | liegt der Image-Tarball dort und wird die Anmeldung akzeptiert? |
Beispiel mit korrekten Zugangsdaten aus der `.env`:
```
Registry registry.checkmk.com
[ OK ] erreichbar (HTTP 401)
[ OK ] Anmeldung akzeptiert
[ OK ] Zugriff auf 'enterprise/check-mk-enterprise' vorhanden
Downloadportal download.checkmk.com
[ OK ] Datei erreichbar (HTTP 200)
https://download.checkmk.com/checkmk/2.3.0p23/check-mk-enterprise-2.3.0p23.docker.tar.gz
[ OK ] Zugangsweg nutzbar.
```
Bei falschem Kennwort:
```
Registry registry.checkmk.com
[ OK ] erreichbar (HTTP 401)
[FEHLER] Anmeldung abgelehnt (HTTP 401)
Benutzername/Kennwort des Checkmk-Kundenportals pruefen
```
Nützliche Unterscheidungen, die der Test trifft:
* **Anmeldung akzeptiert, aber kein Zugriff auf das Repository** – die
Zugangsdaten stimmen, der Subskription fehlt aber die Berechtigung für diese
Edition.
* **Anmeldung akzeptiert, aber HTTP 404 im Downloadportal** – Benutzer und
Kennwort sind richtig, nur Version oder Dateiname passen nicht. Dann die
exakte Version angeben (kein `-latest`) oder `CMK_DOWNLOAD_URL` setzen.
* Bei den frei verfügbaren Editionen (`raw`, `pro`, `cloud` …) meldet der Test
„öffentliches Repository – keine Anmeldung nötig" und prüft trotzdem, ob das
Repository wirklich abrufbar ist.
Optionen:
```bash
# Zugangsdaten einmalig angeben, ohne sie in die .env zu schreiben
./scripts/cmk-manage.sh image test --edition enterprise --version 2.3.0p23 \
--user <benutzer> --password <kennwort>
# nur einen Bezugsweg prüfen
./scripts/cmk-manage.sh image test --only registry
./scripts/cmk-manage.sh image test --only download
```
Die Zugangsdaten werden über `curl --config -` von der Standardeingabe
übergeben und erscheinen daher **nicht** in der Prozessliste.
> **Kennwörter mit Sonderzeichen:** Bis dahin lief das über eine temporäre
> `.netrc`-Datei. Deren Format trennt die Felder durch Leerzeichen – ein
> Kennwort mit Leerzeichen, `#` oder Anführungszeichen kam dadurch still
> verstümmelt an, und die Anmeldung schlug scheinbar grundlos fehl.
> Gegen einen Testserver nachgemessen: bei einem Kennwort mit Leerzeichen,
> `#`, `"` und `$` liefert der neue Weg HTTP 200, der alte HTTP 401. Fehlt `curl`, weicht der Test
für die Registry auf `podman login` bzw. `docker login` aus – auch dann in eine
Wegwerfdatei, die gespeicherte Anmeldung des Systems bleibt unberührt.
In der ncurses-Oberfläche ist der Test an zwei Stellen erreichbar:
* **Hauptmenü → image → „Zugangsdaten prüfen"**
* **Einstellungen → „Checkmk-Image und Zugangsdaten" →
„>> Zugangsdaten jetzt prüfen"** – also direkt dort, wo Benutzer und
Kennwort eingetragen werden
Nach dem Ändern eines Zugangsdaten-Feldes fragt das Menü ausserdem von sich
aus, ob gleich geprüft werden soll.
### 8.5 Verfügbare Versionen auflisten
Statt Versionsnummern zu raten:
```bash
./scripts/cmk-manage.sh image versions --edition enterprise --filter 2.3.0p
```
Abgefragt werden bis zu drei Quellen:
| Quelle | `--source` | Zugangsdaten |
|---|---|---|
| Versionsarchiv von checkmk.com | `web` | **nein** |
| Registry (Docker Hub bzw. registry.checkmk.com) | `registry` | nur für Enterprise |
| Downloadportal (Verzeichnis-Listing) | `download` | ja |
Ohne `--source` werden alle drei versucht – so kommt auch ohne hinterlegte
Zugangsdaten eine brauchbare Liste zustande:
```
Versionsarchiv https://checkmk.com/download/archive
(oeffentlich, keine Zugangsdaten noetig)
2.3.0p50
2.3.0p49
2.3.0p48
...
Uebernehmen
aus der Registry : ./scripts/cmk-manage.sh image pull --edition enterprise --version <version>
als Tarball : ./scripts/cmk-manage.sh image download --edition enterprise --version <version>
nur eintragen : ./scripts/cmk-manage.sh config set CMK_VERSION <version>
```
Weitere Optionen: `--limit N` (Vorgabe 25), `--all`, `--filter TEXT` und
`--bare` für die nackte Liste ohne Rahmen – praktisch zum Weiterverarbeiten:
```bash
./scripts/cmk-manage.sh image versions --source web --filter 2.3.0p --bare | head -1
```
In der Oberfläche gibt es den Punkt **image → „Verfügbare Versionen
auflisten"**; beim Holen eines Images muss die Version ohnehin nicht mehr
abgetippt werden – dort erscheint eine Auswahlliste.
### 8.6 Image holen – drei Wege
> **In der Oberfläche geht das als Assistent:** **image → „Image beschaffen"**
> führt in einem Durchgang durch Edition, Version und Bezugsweg, setzt danach
> `CMK_EDITION`, `CMK_VERSION` **und** `CMK_IMAGE` und fragt **nicht** erneut
> nach Zugangsdaten, die schon in der `.env` stehen. Nur wenn sie für den
> gewählten Weg fehlen, werden sie erfragt – auf Wunsch gleich gespeichert.
> Derselbe Assistent liegt auch unter **Einstellungen → Checkmk-Image und
> Zugangsdaten → „>> Image beschaffen"**.
Auf der Kommandozeile bleiben die Einzelschritte:
**a) Aus einer Registry (empfohlen)**
Für die Enterprise-Edition entspricht das genau diesen beiden Schritten – das
Skript erledigt sie in einem Aufruf und trägt das Ergebnis in die `.env` ein:
```bash
podman login registry.checkmk.com # bzw. docker login
podman pull registry.checkmk.com/enterprise/check-mk-enterprise:2.3.0p9
```
```bash
# frei verfuegbar, ohne Anmeldung
sudo ./scripts/cmk-manage.sh image pull --edition raw --version 2.3.0-latest
# Enterprise mit Anmeldung an registry.checkmk.com
sudo ./scripts/cmk-manage.sh image pull --edition enterprise --version 2.3.0p23 \
--user <benutzer> --password <kennwort>
```
**b) Image-Tarball vom Downloadportal (mit Zugangsdaten)**
```bash
sudo ./scripts/cmk-manage.sh image download --edition enterprise --version 2.3.0p23 \
--user <benutzer> --password <kennwort>
```
Der Downloader probiert die ueblichen Dateinamen unter
`<CMK_DOWNLOAD_BASEURL>/<version>/` durch
(`check-mk-enterprise-<version>.docker.tar.gz` und
`check-mk-enterprise-docker-<version>.tar.gz`). Falls Checkmk das Schema
geaendert hat, laesst sich die vollstaendige URL direkt vorgeben:
```bash
sudo ./scripts/cmk-manage.sh image download \
--url 'https://download.checkmk.com/checkmk/2.3.0p23/check-mk-enterprise-2.3.0p23.docker.tar.gz' \
--user <benutzer> --password <kennwort>
```
Die Zugangsdaten werden über `curl --config -` übergeben und erscheinen
daher nicht in der Prozessliste.
**c) Bereits heruntergeladene Datei einspielen**
Wer die Datei im Browser aus dem Kundenportal geladen hat:
```bash
sudo ./scripts/cmk-manage.sh image load --file /root/check-mk-enterprise-2.3.0p23.docker.tar.gz
```
In allen drei Faellen ermittelt das Skript den **tatsaechlichen** Image-Namen
(bei `load` z. B. `localhost/checkmk/check-mk-enterprise:2.3.0p23`) und traegt
ihn als `CMK_IMAGE` in die `.env` ein. Danach:
```bash
sudo ./scripts/cmk-manage.sh up
```
### 8.7 `CMK_IMAGE` gegenüber `CMK_EDITION`/`CMK_VERSION`
Diese drei Werte haben unterschiedliche Aufgaben, und das ist eine häufige
Verwechslung:
| Wert | Wer liest ihn | Wozu |
|---|---|---|
| **`CMK_IMAGE`** | **compose und die systemd-Units** | das Image, das tatsächlich gestartet wird |
| `CMK_EDITION` | nur `cmk-manage.sh image …` | Vorgabe für den Downloader |
| `CMK_VERSION` | nur `cmk-manage.sh image …` | Vorgabe für den Downloader |
`CMK_IMAGE` lässt sich **nicht** aus Edition und Version ableiten – je nach
Bezugsweg sieht dieselbe Version völlig anders aus:
```
docker.io/checkmk/check-mk-raw:2.3.0-latest (Docker Hub)
registry.checkmk.com/enterprise/check-mk-enterprise:2.3.0p9 (Registry)
localhost/checkmk/check-mk-enterprise:2.3.0p9 (aus Tarball geladen)
```
Deshalb hält `CMK_IMAGE` fest, was **wirklich vorhanden ist**, und wird von
`image pull`, `image download`, `image load` und `image use` gesetzt – von Hand
muss man dort normalerweise nichts eintragen. In der Oberfläche sind die drei
Werte deshalb gar nicht einzeln editierbar: sie werden vom Assistenten
gemeinsam gesetzt, damit sie nicht auseinanderlaufen. Auf der Kommandozeile
bleiben sie einzeln setzbar (`config set …`).
Auf der Kommandozeile übernehmen `image pull` und `image download` mit
`--remember` die Edition und Version gleich mit in die `.env`:
```bash
./scripts/cmk-manage.sh image pull --edition enterprise --version 2.3.0p9 --remember
```
> **Daraus folgt:** Edition oder Version zu ändern, startet **keine** andere
> Ausgabe. Erst `image pull` (bzw. `download`/`load`) schreibt das Ergebnis
> nach `CMK_IMAGE`, und erst `up` erstellt den Container neu.
Damit das nicht unbemerkt auseinanderläuft, prüft das Skript die drei Werte
gegeneinander – in `image status`, in `status` und im Einstellungsmenü direkt
nach dem Ändern von Edition oder Version:
```
[ WARN ] CMK_IMAGE passt nicht zu den eingestellten Vorgaben.
verwendet wird : docker.io/checkmk/check-mk-raw:2.3.0-latest
Edition : eingestellt "enterprise", im Image steckt "raw"
Compose und die systemd-Units verwenden ausschliesslich CMK_IMAGE.
...
./scripts/cmk-manage.sh image pull --edition enterprise --version 2.3.0-latest
./scripts/cmk-manage.sh up
```
Aus einem Tarball geladene Images (`localhost/…`) gelten dabei als stimmig,
solange Name und Tag passen.
**Wenn das Holen fehlschlägt**, bleibt `CMK_IMAGE` unverändert – das ist
Absicht, denn das alte Image läuft ja weiter. Der Assistent sagt das dann auch
ausdrücklich („Image wurde NICHT geholt") statt nur auf die Abweichung
hinzuweisen. Es bleibt trotzdem ein Zustand, in dem Edition und Version etwas
anderes behaupten als das benutzte Image. Dafür gibt es zwei Auswege – beide
im Menü unter den drei Werten:
| Weg | Wirkung |
|---|---|
| **Assistent starten** | holt das gewünschte Image; danach passt alles |
| **Vorgaben an das verwendete Image angleichen** | schreibt Edition und Version aus `CMK_IMAGE` zurück – die Warnung verschwindet, es ändert sich nichts am Betrieb |
Auf der Kommandozeile ist das zweite:
```bash
./scripts/cmk-manage.sh image use "$CMK_IMAGE" --remember
```
### 8.8 Registry-Pfad herausfinden
„Login Succeeded" heisst noch nicht, dass der Pfad stimmt. Meldet der Pull
`unable to copy from source docker://…`, existiert das Repository unter diesem
Namen nicht oder die Subskription deckt es nicht ab:
```bash
./scripts/cmk-manage.sh image repos --edition enterprise
```
Das fragt zuerst den Katalog (`/v2/_catalog`) ab – den sperren allerdings viele
Registries – und probiert danach die üblichen Pfade durch:
```
Uebliche Pfade fuer "raw" durchprobiert
STATUS TAGS PFAD
200 = nutzbar, 404 = gibt es nicht, 401/403 = kein Zugriff
401 - raw/check-mk-raw (kein Zugriff - oder gibt es nicht)
200 2394 checkmk/check-mk-raw
...
[ OK ] Nutzbar: docker.io/checkmk/check-mk-raw
```
Scheitert ein `image pull` gegen eine private Registry, läuft diese Prüfung
automatisch an und zeigt gleich, was dort wirklich liegt.
> **401 heisst nicht zwingend „vorhanden".** Viele Registries – Docker Hub
> zum Beispiel – antworten auch auf nicht existierende Repositories mit 401,
> um deren Existenz nicht zu verraten. Verlässlich ist nur **200 = nutzbar**
> und **404 = gibt es nicht**.
Führt kein Pfad zum Ziel, bleibt der Tarball-Weg. Er ist für Enterprise
ohnehin der dokumentierte und funktioniert unabhängig von der Registry:
```bash
./scripts/cmk-manage.sh image download --edition enterprise --version 2.4.0p9
```
### 8.9 Nachsehen, was gilt
```bash
./scripts/cmk-manage.sh image status # konfiguriertes + lokale Images
./scripts/cmk-manage.sh image list # nur lokale Checkmk-Images
./scripts/cmk-manage.sh image use localhost/checkmk/check-mk-enterprise:2.3.0p23
```
`image status` warnt ausdruecklich, wenn `CMK_IMAGE` ein kurzer Name ohne
Registry ist.
In der ncurses-Oberflaeche liegt derselbe Ablauf unter dem Menuepunkt
**„Checkmk-Image beschaffen/auswaehlen“** (Edition auswaehlen → Version →
Zugangsdaten → holen).
---
## 9. 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/
```
Der Port der Adminoberfläche folgt `NPM_ADMIN_PORT` aus der `.env`; die Ausgabe
zeigt immer den tatsächlich eingestellten Wert.
Anmeldung an Checkmk: Benutzer `cmkadmin`, Passwort aus `CMK_PASSWORD`.
---
## 10. HTTPS einrichten – Let's Encrypt oder selbstsigniert
### 10.1 Das Administratorkonto
> **Die früher üblichen Standardzugangsdaten `admin@example.com` / `changeme`
> gibt es seit Version 2.15 nicht mehr.** Der Container legt das erste Konto
> nur noch an, wenn beim **ersten** Start `INITIAL_ADMIN_EMAIL` und
> `INITIAL_ADMIN_PASSWORD` gesetzt sind – sonst erscheint im Browser ein
> Einrichtungsassistent. Nachgelesen in `backend/setup.js` von v2.15.1 und am
> laufenden Container überprüft.
Deshalb stehen die Werte in der `.env` und werden von `docker-compose.yml`
durchgereicht:
```bash
NPM_ADMIN_EMAIL=admin@example.com
NPM_ADMIN_PASSWORD=ein-ordentliches-kennwort
```
Beides **vor dem ersten Start** setzen. Dann ist das Konto sofort da – und
damit auch die REST-Schnittstelle nutzbar, über die
[Kapitel 10.2](#102-proxy-host-anlegen--ohne-browser) den Proxy-Host anlegt.
Ist der Stack schon gelaufen und das Konto von Hand über den Assistenten
angelegt worden, wirken die Variablen nicht mehr (die Datenbank ist nicht mehr
leer). Dann einfach die selbst vergebenen Zugangsdaten eintragen – das Skript
meldet sich damit an.
### 10.2 Proxy-Host anlegen – ohne Browser
Die Weboberfläche lässt sich im Terminal-Browser nur mühsam bedienen; Formulare
mit Datei-Upload funktionieren dort gar nicht. Da der Proxy Manager ohnehin
lokal läuft, ist die Schnittstelle der verlässlichere Weg:
```bash
# Checkmk unter checkmk.example.com veröffentlichen, mit selbstsigniertem Zertifikat
sudo ./scripts/cmk-manage.sh proxy add --domain checkmk.example.com --cert self
# oder mit Let's Encrypt (Port 80 muss aus dem Internet erreichbar sein)
sudo ./scripts/cmk-manage.sh proxy add --domain checkmk.example.com --cert letsencrypt
# auf einen anderen Zielport statt 5000
sudo ./scripts/cmk-manage.sh proxy add --domain checkmk.example.com --forward-port 8080
```
Das Kommando erledigt in einem Zug: Zertifikat erzeugen (bzw. bei Let's
Encrypt anfordern), in den Proxy Manager hochladen, Proxy-Host anlegen, HTTPS
erzwingen, HTTP/2 und Websockets einschalten und den empfohlenen
`advanced_config`-Abschnitt setzen.
| Kommando | Wirkung |
|---|---|
| `proxy status` | Anmeldung prüfen, Anzahl Hosts und Zertifikate |
| `proxy list` | vorhandene Proxy-Hosts |
| `proxy certs` | vorhandene Zertifikate mit Ablaufdatum |
| `proxy add …` | Proxy-Host anlegen (`--update` ersetzt einen vorhandenen) |
| `proxy show --domain X` | Einzelheiten samt zusätzlicher Pfade |
| `proxy del --id N` | Proxy-Host löschen |
Optionen von `proxy add`:
| Option | Vorgabe | Bedeutung |
|---|---|---|
| `--domain FQDN` | `PROXY_DOMAIN` | öffentlicher Name |
| `--forward-host H` | `127.0.0.1` | Weiterleitungsziel |
| `--forward-port P` | `5000` | Zielport – **frei wählbar**, nicht auf Checkmk festgelegt |
| `--scheme http\|https` | `http` | Schema zum Ziel |
| `--cert self\|letsencrypt\|none` | `self` | Zertifikat |
| `--update` | – | vorhandenen Eintrag ersetzen |
| `--advanced TEXT` | siehe unten | eigener nginx-Abschnitt |
| `--location /P=HOST:PORT` | – | weiterer Dienst unter einem Pfad, mehrfach angebbar – siehe [10.3](#103-mehrere-dienste-hinter-einem-port-pfade-statt-namen) |
| `--no-force-ssl`, `--no-http2`, `--no-websockets`, `--no-block-exploits` | – | Abschalter |
#### Der `advanced_config`-Abschnitt
Ohne `--advanced` setzt `proxy add` diesen Block – dieselben vier Zeilen, die
man sonst im Reiter **Advanced** von Hand einträgt:
```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;
```
Wozu die vier:
| Zeile | Grund |
|---|---|
| `client_max_body_size 0` | hebt die Größenbegrenzung auf – sonst scheitern große Agent-Uploads und Bakery-Pakete |
| `proxy_read_timeout 300s` | lange laufende Checkmk-Ansichten laufen sonst in eine Zeitüberschreitung |
| `X-Forwarded-Proto` | Checkmk erzeugt sonst `http://`-Verweise hinter dem HTTPS-Proxy |
| `X-Forwarded-For` | im Checkmk-Zugriffsprotokoll steht sonst nur die Proxy-Adresse statt der echten Client-IP |
Ersetzen (nicht ergänzen) lässt sich der Block mit `--advanced`:
```bash
sudo ./scripts/cmk-manage.sh proxy add --domain checkmk.example.com \
--advanced 'client_max_body_size 0;
proxy_read_timeout 600s;'
```
Mit `--advanced ''` bleibt das Feld leer. Der Assistent in der Oberfläche
verwendet immer die Vorgabe oben; wer etwas anderes braucht, nimmt die
Kommandozeile oder passt den Eintrag anschließend im Proxy Manager an.
In der Oberfläche liegt derselbe Ablauf unter **proxy → „Proxy-Host anlegen"**
(Name → Zielport → Zertifikat) sowie unter **Einstellungen → NGINX Proxy
Manager → „>> Proxy-Hosts anlegen/verwalten"**.
> Ein selbstsigniertes Zertifikat wird bei wiederholtem Aufruf
> **wiederverwendet** statt jedes Mal neu angelegt – sonst sammeln sich im
> Proxy Manager Dutzende Einträge gleichen Namens an.
### 10.3 Mehrere Dienste hinter einem Port (Pfade statt Namen)
Der typische Fall: von außen ist **nur ein Port** erreichbar, auf dem Server
laufen aber mehrere Oberflächen – Checkmk, Grafana, vielleicht noch etwas. Statt
für jeden Dienst einen eigenen Namen zu brauchen, lassen sie sich über den
**Pfad** unterscheiden:
```
https://10.0.0.5/cmk/ -> Checkmk (127.0.0.1:5000)
https://10.0.0.5/grafana -> Grafana (127.0.0.1:3000)
https://10.0.0.5/sonstwas -> ein weiterer Dienst
```
Genau dafür ist der Proxy Manager da. In einem Aufruf:
```bash
sudo ./scripts/cmk-manage.sh proxy add \
--domain 10.0.0.5 \
--forward-port 5000 \
--cert self \
--location /grafana=127.0.0.1:3000 \
--location /sonstwas=127.0.0.1:8080
```
* `--domain` darf eine **IP-Adresse** sein – ein DNS-Name ist nicht nötig.
(Die Schnittstelle akzeptiert alles außer einer Handvoll Sonderzeichen.)
* `--forward-port` ist das Ziel für alles, was **nicht** von einem Pfad
abgedeckt ist – hier Checkmk.
* `--location` ist beliebig oft angebbar. Schreibweise
`/pfad=host:port`, wahlweise mit Schema (`https://host:port`) und mit einem
Pfad, der beim Ziel vorangestellt wird (`/alt=host:3000/basis`).
Anzeigen lässt sich das Ergebnis mit:
```bash
./scripts/cmk-manage.sh proxy show --domain 10.0.0.5
```
In der Oberfläche fragt der Assistent nach dem Zertifikat, ob weitere Dienste
unter demselben Namen liegen sollen, und nimmt dann Pfad und Ziel im Wechsel
auf, bis man ein Feld leer lässt.
> **Die Pfadliste ist vollständig zu verstehen.** `proxy add --update`
> ersetzt den Eintrag mitsamt allen Pfaden. Wer später einen Pfad ergänzt, gibt
> die bereits vorhandenen also wieder mit an – `proxy show` zeigt, welche das
> sind.
#### Was die Dienste selbst wissen müssen
Ein Dienst hinter einem Unterpfad erzeugt sonst Verweise auf `/`, die ins Leere
gehen. **Checkmk** ist davon nicht betroffen – es liegt ohnehin unter
`/<site>/`. Andere brauchen eine Einstellung:
**Grafana** (`/etc/grafana/grafana.ini` bzw. `GF_*`-Umgebungsvariablen):
```ini
[server]
domain = 10.0.0.5
root_url = %(protocol)s://%(domain)s/grafana/
serve_from_sub_path = true
```
Als Container:
```yaml
environment:
GF_SERVER_ROOT_URL: https://10.0.0.5/grafana/
GF_SERVER_SERVE_FROM_SUB_PATH: "true"
```
Bleibt das aus, lädt Grafana zwar, sucht sein JavaScript aber unter
`https://10.0.0.5/public/...` statt `/grafana/public/...` – die Seite bleibt
weiß. Dasselbe gilt sinngemäß für jeden anderen Dienst: er muss seinen
Basispfad kennen.
#### Warum überhaupt der Proxy Manager
Alle Container laufen im Host-Netzwerk, die Dienste hören also direkt auf ihren
Ports (Checkmk 5000, Grafana 3000, …). Nach außen geben Sie davon **keinen**
frei – nur 443. Der Proxy Manager verteilt dahinter nach Pfad und erledigt
zugleich die HTTPS-Terminierung mit einem Zertifikat für alle Dienste.
```
Internet / LAN
|
:443 (einziger offener Port)
|
NGINX Proxy Manager
| | |
/cmk/ /grafana /sonstwas
| | |
:5000 :3000 :8080 (nur auf localhost)
```
### 10.4 Wenn doch die Weboberfläche
1. `http://<server>:81` aufrufen – bzw. den in `NPM_ADMIN_PORT` gesetzten Port
(siehe [Kapitel 12](#12-adminoberfläche-auf-einen-anderen-port-legen));
ist der Port im Netz gesperrt, hilft der Terminal-Browser aus
[Kapitel 11](#11-proxy-manager-lokal-einrichten-terminal-browser)
2. Anmelden mit `NPM_ADMIN_EMAIL` / `NPM_ADMIN_PASSWORD`
### 10.5 Proxy-Host im Browser 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;
```
### 10.6 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).
### 10.7 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“*.
---
## 11. Proxy Manager lokal einrichten (Terminal-Browser)
Wenn Port 81 aus dem Netz nicht erreichbar ist, muss die Adminoberfläche des
NGINX Proxy Managers **auf der Maschine selbst** bedient werden. Dafür startet
`cmk-manage.sh browser` einen weiteren Container im Host-Netzwerk – der erreicht
`127.0.0.1:81` genauso wie der Proxy Manager selbst.
```bash
sudo ./scripts/cmk-manage.sh browser
```
Das ist bewusst **kein** Dienst in der `docker-compose.yml`: ein Browser ist ein
interaktives Programm mit Terminal, kein Hintergrunddienst. Er wird mit
`run --rm -it` gestartet und verschwindet beim Beenden wieder rückstandslos.
### 11.1 Warum kein `lynx`
Die Adminoberfläche des Proxy Managers ist eine JavaScript-Anwendung. Klassische
Textbrowser können sie **nicht** darstellen – man sieht eine leere Seite. Es
gibt deshalb zwei Engines, die einen vollwertigen Browser im Terminal rendern:
| Engine | Basis | JavaScript | Proxy Manager bedienbar |
|---|---|---|---|
| `browsh` | Firefox | ja | **ja** – Vorgabe, gepflegt |
| `carbonyl` | Chromium | ja | **ja** – schönere Darstellung, Stand 2023 |
| `links` (links2) | Textbrowser | nein | nein |
| `w3m` | Textbrowser | nein | nein |
| `lynx` | Textbrowser | nein | nein |
| `shell` | Bash + curl/jq/openssl | – | für Diagnose und die API |
Die Textbrowser sind trotzdem eingebaut, weil sie für schnelle Prüfungen
praktisch sind. Wählt man sie, warnt das Skript ausdrücklich.
### 11.2 Bedienung
```bash
# Vorgabe: browsh auf http://127.0.0.1:81
sudo ./scripts/cmk-manage.sh browser
# andere Engine oder andere Seite
sudo ./scripts/cmk-manage.sh browser --engine carbonyl
sudo ./scripts/cmk-manage.sh browser --engine links --url http://127.0.0.1:5000/cmk/
# Shell mit Netzwerkwerkzeugen im Host-Netzwerk
sudo ./scripts/cmk-manage.sh browser --engine shell
```
Tastenbelegung in **browsh**:
| Taste | Wirkung |
|---|---|
| `Strg+L` | Adresszeile |
| `Strg+T` | neuer Tab |
| `Strg+W` | Tab schließen |
| `Strg+Q` | beenden |
Beim ersten Aufruf einer Textbrowser- oder `shell`-Engine baut das Skript ein
kleines Werkzeug-Image (Debian slim mit links2, w3m, lynx, curl, jq, openssl,
rund 170 MB). Vorab bauen – auch ohne Terminal, etwa im Installationsskript:
```bash
sudo ./scripts/cmk-manage.sh browser --build-only
```
`browsh` und `carbonyl` werden dagegen als fertige Images geladen; die Namen
stehen in der `.env` (`BROWSH_IMAGE`, `CARBONYL_IMAGE`) und sind
vollqualifiziert, damit Podman sie nicht bei `registry.access.redhat.com` sucht.
In der ncurses-Oberfläche liegt alles unter **„Terminal-Browser (Proxy Manager
lokal bedienen)"**.
### 11.3 Schwarzes Fenster: die Startseite antwortet nicht
Bleibt nach `Starting Browsh …` / `Waiting for Firefox to connect…` alles
schwarz, liegt es fast immer daran, dass **auf der Startseite nichts
antwortet** – nicht am Browser. Ein Terminal-Browser zeigt in dem Fall keine
Fehlerseite, sondern gar nichts. Dass Browsh selbst läuft, merkt man daran,
dass `Strg+Q` noch ins Menü zurückführt.
Das Skript prüft die Startseite deshalb vorher und nennt die Ursache:
```
[ WARN ] Auf http://127.0.0.1:81 antwortet nichts.
Ein Terminal-Browser zeigt dann nur eine schwarze Seite.
Das ist die Oberflaeche des NGINX Proxy Managers.
Er ist abgeschaltet (NPM_ENABLED=off):
./scripts/cmk-manage.sh npm-enable on
Trotzdem starten? [j/N]
```
Unterschieden werden:
| Lage | Meldung |
|---|---|
| Proxy Manager abgeschaltet | Hinweis auf `npm-enable on` |
| Container fehlt oder gestoppt | Hinweis auf `up` |
| Container läuft, antwortet aber nicht | Hinweis auf `logs` und `npm-port` |
| Checkmk-Oberfläche (Port 5000) tot | Hinweis auf `up` bzw. `sites` |
| externe Adresse | Hinweis auf den Netzzugang des Hosts |
Mit `--no-check` lässt sich die Prüfung überspringen. In der Oberfläche
erscheint dieselbe Diagnose als Dialog mit der Wahl, trotzdem zu starten oder
im Menü eine andere Startseite einzugeben.
### 11.4 Grenze: Datei-Upload
Ein Terminal-Browser kann keinen Dateiauswahl-Dialog des Betriebssystems
öffnen. Für **Let's Encrypt** ist das egal (dort werden nur Formularfelder
ausgefüllt), aber das Hochladen eines **selbstsignierten Zertifikats**
(*SSL Certificates → Custom*) funktioniert so nicht zuverlässig.
Für genau diesen Fall führt der Weg über die REST-Schnittstelle des Proxy
Managers. Zertifikat wie in [Kapitel 10.7](#107-variante-b--selbstsigniertes-zertifikat-interne-umgebung)
erzeugen, dann:
```bash
NPM=http://127.0.0.1:81
CERTDIR=./data/npm/custom-certs/checkmk.intern.example
# 1) Anmelden und Token holen
TOKEN=$(curl -s -X POST "$NPM/api/tokens" \
-H 'Content-Type: application/json' \
-d '{"identity":"admin@example.com","secret":"<kennwort>"}' | jq -r .token)
# 2) Zertifikatseintrag anlegen (provider "other" = eigenes Zertifikat)
CERT_ID=$(curl -s -X POST "$NPM/api/nginx/certificates" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"provider":"other","nice_name":"checkmk-selfsigned","domain_names":["checkmk.intern.example"]}' \
| jq -r .id)
# 3) Schlüssel und Zertifikat hochladen
curl -s -X POST "$NPM/api/nginx/certificates/$CERT_ID/upload" \
-H "Authorization: Bearer $TOKEN" \
-F "certificate=@$CERTDIR/fullchain.pem" \
-F "certificate_key=@$CERTDIR/privkey.pem"
# 4) Proxy-Host für Checkmk anlegen
curl -s -X POST "$NPM/api/nginx/proxy-hosts" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d "{\"domain_names\":[\"checkmk.intern.example\"],
\"forward_scheme\":\"http\",
\"forward_host\":\"127.0.0.1\",
\"forward_port\":5000,
\"certificate_id\":$CERT_ID,
\"ssl_forced\":true,
\"http2_support\":true,
\"block_exploits\":true,
\"allow_websocket_upgrade\":true,
\"advanced_config\":\"client_max_body_size 0;\",
\"enabled\":true,
\"meta\":{}}"
```
`curl` und `jq` sind im Werkzeug-Image enthalten, falls der Host sie nicht hat:
```bash
sudo ./scripts/cmk-manage.sh browser --engine shell
```
> Beim allerersten Login erzwingt der Proxy Manager das Ändern von
> E-Mail-Adresse und Kennwort. Das geht am einfachsten im Browser
> (`cmk-manage.sh browser`); danach funktioniert die API mit den neuen Daten.
### 11.5 Alternative: SSH-Tunnel
Falls SSH auf die Maschine möglich ist, ist der Tunnel der bequemste Weg –
dann bedient man die Oberfläche im gewohnten Browser:
```bash
ssh -N -L 8081:127.0.0.1:81 benutzer@checkmk-server
# danach lokal: http://127.0.0.1:8081
```
Das ändert nichts an der Firewall: Port 81 bleibt von außen dicht, der Zugriff
läuft durch die bestehende SSH-Verbindung.
---
## 12. Adminoberfläche auf einen anderen Port legen
Die Weboberfläche des NGINX Proxy Managers hört im Image **fest auf Port 81**
(`listen 81 default;` in `/etc/nginx/conf.d/production.conf`). Eine
Umgebungsvariable dafür gibt es in den veröffentlichten 2.x-Versionen noch
nicht – im Entwicklungszweig ist `NPM_ADMIN_PORT` bereits vorbereitet, in
Version 2.15.1 aber noch nicht enthalten. Und weil beide Container im
Host-Netzwerk laufen, lässt sich der Port auch nicht per Port-Mapping
verschieben.
Ist Port 81 im Netz gesperrt, hilft deshalb:
```bash
sudo ./scripts/cmk-manage.sh npm-port 10443
```
### 12.1 Was dabei passiert
nginx bindet innerhalb seines `http{}`-Blocks einen offiziellen
Erweiterungspunkt ein:
```
include /data/nginx/custom/http.conf;
```
`/data` ist unser Bind-Mount `./data/npm/data`. Dort legt das Kommando einen
zusätzlichen Server an, der auf dem gewünschten Port lauscht und an die
Oberfläche auf `127.0.0.1:81` weiterreicht:
```
./data/npm/data/nginx/custom/http.conf
# >>> cmk-manage.sh: Admin-Port - nicht von Hand aendern >>>
server {
listen 10443;
listen [::]:10443;
server_name _;
client_max_body_size 0;
location / {
proxy_pass http://127.0.0.1:81;
...
}
}
# <<< cmk-manage.sh: Admin-Port <<<
```
Nur der Bereich zwischen den beiden Markierungen wird verwaltet – eigene
Ergänzungen in derselben Datei bleiben unangetastet. Anschließend startet das
Skript den Proxy-Manager-Container neu, damit nginx die Datei liest, und trägt
`NPM_ADMIN_PORT` sowie `NPM_ADMIN_URL` in die `.env` ein. Der Terminal-Browser
aus [Kapitel 11](#11-proxy-manager-lokal-einrichten-terminal-browser) startet
dann automatisch auf dem neuen Port.
### 12.2 Wichtig: Port 81 bleibt lokal bestehen
Der eingebaute Server auf Port 81 lässt sich so **nicht** abschalten – er
lauscht weiter auf allen Adressen. Das ist unkritisch, solange die Firewall ihn
sperrt, und genau so ist die Empfehlung:
```bash
# firewalld
sudo firewall-cmd --permanent --add-port=10443/tcp
sudo firewall-cmd --permanent --remove-port=81/tcp 2>/dev/null
sudo firewall-cmd --reload
# ufw
sudo ufw allow 10443/tcp
sudo ufw delete allow 81/tcp 2>/dev/null
```
### 12.3 Stand ansehen und zurücksetzen
```bash
./scripts/cmk-manage.sh npm-port # aktuellen Stand anzeigen
sudo ./scripts/cmk-manage.sh npm-port 81 # zurück auf die Vorgabe
```
Bei `81` wird der verwaltete Block wieder entfernt; ist die Datei danach leer,
verschwindet sie ganz. Es gilt dann wieder ausschließlich die Konfiguration aus
dem Image.
Das Kommando lehnt Ports ab, die im Stack schon vergeben sind (80, 443, 5000,
8000, 6557), prüft den Zahlenbereich und warnt, wenn auf dem Wunschport bereits
ein anderer Dienst lauscht.
> Sobald eine NPM-Version mit `NPM_ADMIN_PORT` erscheint, wird dieser Umweg
> überflüssig – dann genügt die Umgebungsvariable. Bis dahin ist der
> Erweiterungspunkt der Weg, der ohne Änderung am Image auskommt.
### 12.4 Proxy Manager ganz abschalten (externer NGINX)
Wer die HTTPS-Terminierung schon anderweitig löst – etwa mit einem NGINX auf
einem vorgelagerten System – braucht den Container gar nicht. Dafür gibt es
einen Schalter:
```bash
sudo ./scripts/cmk-manage.sh npm-enable off # abschalten
sudo ./scripts/cmk-manage.sh npm-enable on # wieder einschalten
./scripts/cmk-manage.sh npm-enable # Stand anzeigen
```
In der Oberfläche steht er unter **Einstellungen → NGINX Proxy Manager →
„Proxy Manager betreiben"**, in der `.env` heißt er `NPM_ENABLED`.
**Was „aus" bedeutet:** Der Container wird gestoppt und entfernt, und bei
`up` gar nicht erst angelegt – `compose` bekommt dann nur noch den
Checkmk-Dienst genannt. Es wird also weder ein Image geladen noch ein
Container gebaut:
```
NPM_ENABLED=off -> docker compose up -d checkmk
NPM_ENABLED=on -> docker compose up -d checkmk nginx-proxy-manager
```
**Die Daten bleiben.** Konfiguration, Datenbank und Zertifikate liegen in den
Bind-Mounts `./data/npm/data` und `./data/npm/letsencrypt`, nicht im Container.
Vor dem Abschalten zeigt das Kommando beides mit Größe an; beim späteren
Einschalten wird die vorhandene Konfiguration samt Zertifikaten unverändert
wieder aufgenommen.
**Was danach zu tun ist:** Der externe Proxy leitet auf Port 5000 dieses Hosts
weiter. Der war bisher nur für localhost gedacht und muss jetzt – möglichst eng
begrenzt – für den Proxy erreichbar sein:
```bash
# firewalld
sudo firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=<proxy-ip> port port=5000 protocol=tcp accept'
sudo firewall-cmd --reload
# ufw
sudo ufw allow from <proxy-ip> to any port 5000 proto tcp
```
Im externen NGINX:
```nginx
location / {
proxy_pass http://<checkmk-host>:5000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
client_max_body_size 0;
proxy_read_timeout 300s;
}
```
Das passende Kommando samt Beispielkonfiguration gibt `npm-enable off` direkt
mit aus.
> **Der Agent-Receiver bleibt davon unberührt.** Die Agents sprechen Port 8000
> dieses Hosts direkt an, nicht den Proxy – der muss also weiterhin für die
> überwachten Systeme erreichbar sein.
> **Bei Quadlet** ([Kapitel 6, Variante B](#variante-b--podman-quadlet-ab-podman-44-ohne-compose))
> entfernt `install.sh --quadlet` die Unit `nginx-proxy-manager.container`,
> solange der Schalter auf `off` steht. Schaltet man ihn später ein, genügt ein
> erneutes `sudo ./install.sh --quadlet`.
---
## 13. 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
# Bei abweichendem Admin-Port (z.B. 10443) stattdessen dessen Nummer freigeben -
# das passende Kommando gibt "cmk-manage.sh npm-port <port>" direkt aus.
```
**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.
---
## 14. Verwaltung: `cmk-manage.sh`
Das Skript ist gleichzeitig Kommandozeilenwerkzeug **und** ncurses-Oberfläche.
### 14.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 │
│ image Checkmk-Image beschaffen/auswählen │
│ browser Terminal-Browser (Proxy Manager lokal) │
│ cert Selbstsigniertes Zertifikat erzeugen │
│ config Einstellungen (.env) - menügeführt │
│ 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.
Die Fenstergröße richtet sich nach Terminalgröße, Textlänge und Anzahl der
Einträge – in einem größeren Terminal sind entsprechend mehr Einträge auf
einmal sichtbar. Das gilt für **alle** Fenster, auch in `migrate_creator.sh`:
sämtliche Dialoge laufen über drei gemeinsame Stellen in
[scripts/lib/common.sh](scripts/lib/common.sh), die die Größe selbst berechnen.
### 14.4 Selbstprüfung
```bash
./scripts/cmk-manage.sh selftest
```
Prüft die Skripte auf die Fallstricke, die sich hier als wiederkehrend
erwiesen haben:
| Prüfung | Warum |
|---|---|
| Syntax aller vier Skripte | Tippfehler fallen sofort auf |
| Dialoge gehen über die gemeinsamen Stellen | sonst hätte ein neues Fenster wieder eine feste Größe |
| keine fest eingetragenen Fenstergrößen | dito |
| kein `[ … ] && VAR=…` | liefert 1, wenn die Bedingung nicht zutrifft, und beendet unter `set -e` das Skript – dreimal die Ursache eines stillen Abbruchs |
| Einstellungstabelle vollständig | jeder Schlüssel hat sechs Felder und steht in `.env.example` |
Wer eigene Menüpunkte ergänzt, sollte den Aufruf danach einmal machen.
Es wird `dialog` bevorzugt; ist nur `whiptail` vorhanden, wird dieses genutzt.
Eine Dateiauswahl mit Verzeichnisnavigation ist eingebaut.
### 14.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 |
| `job list\|add\|set\|del\|run\|auto` | geplante Backups (eigene Zielpfade je Job) |
| `restore …` | Backup zurückspielen |
| `import …` | Migrations-Bundle einspielen |
| `image status\|list\|versions\|test\|pull\|download\|load\|use` | Checkmk-Image beschaffen und auswaehlen |
| `browser [--engine …]` | Terminal-Browser im Container – Proxy Manager lokal bedienen |
| `config list\|get\|set\|edit` | Einstellungen der `.env` anzeigen und ändern |
| `npm-port [PORT]` | Port der Proxy-Manager-Oberfläche setzen/anzeigen |
| `npm-enable [on\|off]` | Proxy Manager ein-/ausschalten (Daten bleiben erhalten) |
| `proxy status\|list\|certs\|add\|del` | Proxy-Hosts über die API anlegen und verwalten |
| `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`.
### 14.3 Einstellungen ändern – ohne Editor
Sämtliche Werte der `.env` lassen sich über das Menü pflegen. In der
Oberfläche: **Einstellungen (.env) – menügeführt**. Die Werte sind nach
Bereichen gruppiert:
```
┌──────────────────── Einstellungen ─────────────────────┐
│ Alle Werte der Datei .env - direkt hier änderbar. │
│ Datei: /opt/checkmk-stack/.env │
│ │
│ runtime Runtime und Zeitzone │
│ image Checkmk-Image und Zugangsdaten │
│ checkmk Checkmk-Site und Container │
│ npm NGINX Proxy Manager │
│ browser Terminal-Browser │
│ paths Verzeichnisse │
│ cert Selbstsignierte Zertifikate │
│ show Alle Werte auflisten │
│ editor Datei .env im Editor öffnen │
│ back zurück │
└────────────────────────────────────────────────────────┘
```
Jeder Eintrag zeigt seinen aktuellen Wert und öffnet beim Bestätigen die
passende Eingabe: Freitext, Zahl, Auswahlliste oder Kennwortfeld (Kennwörter
erscheinen in der Übersicht als `********` und bleiben unverändert, wenn man
das Feld leer lässt). Der Editor bleibt als Menüpunkt erhalten.
Dieselben Werte über die Kommandozeile:
```bash
./scripts/cmk-manage.sh config list # alles mit aktuellen Werten
./scripts/cmk-manage.sh config list --category npm # nur ein Bereich
./scripts/cmk-manage.sh config get CMK_SITE_ID
./scripts/cmk-manage.sh config set CMK_SITE_ID prod
./scripts/cmk-manage.sh config set NPM_ADMIN_PORT 10443
```
**Geprüft wird beim Setzen**, nicht erst beim nächsten Start:
| Schlüssel | Prüfung |
|---|---|
| `NPM_ADMIN_PORT` | Zahl 1–65535, nicht 80/443/5000/8000/6557, Warnung wenn belegt |
| `CMK_SITE_ID` | nur Buchstaben, Ziffern, `_`; höchstens 16 Zeichen |
| `CMK_IMAGE`, `NPM_IMAGE`, … | muss vollqualifiziert sein (Podman-Fallstrick) |
| `CMK_RUNTIME` | muss auf diesem System installiert sein |
| `CERT_DAYS` u. a. | Zahlenfelder |
| URL-Felder | müssen mit `http://` oder `https://` beginnen |
Werte mit Leerzeichen werden automatisch in Anführungszeichen gesetzt, damit
die `.env` weiterhin von compose, systemd **und** der Shell gelesen werden
kann. Ändert man `NPM_ADMIN_PORT`, zieht das Skript die nginx-Zusatzdatei
automatisch mit (siehe [Kapitel 12](#12-adminoberfläche-auf-einen-anderen-port-legen)).
Bei Werten, die erst nach dem Neuerstellen der Container greifen, weist das
Menü ausdrücklich darauf hin.
---
## 15. 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
```
### 15.1 Geplante Backups (Backup-Jobs)
Manuelle Backups gehen immer nach `BACKUP_DIR` aus der `.env`. Geplante Jobs
bringen dagegen **ihr eigenes Zielverzeichnis** mit – so lässt sich täglich auf
eine NAS-Freigabe und wöchentlich woanders hin sichern.
Im Menü: **backup → „Backup erstellen / planen"**
```
┌──────────── Backup erstellen / planen ─────────────────┐
│ Manuelle Backups gehen immer nach: │
│ /opt/checkmk-stack/backups (Einstellung BACKUP_DIR)│
│ │
│ Geplante Jobs haben ihr eigenes Zielverzeichnis. │
│ Automatische Ausfuehrung: aus │
│ │
│ manuell Backup jetzt erstellen │
│ jobs Backup-Jobs verwalten │
│ auto Automatische Ausfuehrung ein/aus │
│ status Zeitplan und Jobs anzeigen │
│ jetzt Einen Job sofort ausfuehren │
│ back zurueck │
└────────────────────────────────────────────────────────┘
```
Dieselben Jobs liegen auch in den **Einstellungen → „Backup-Jobs"**.
#### Job anlegen
Im Menü führt ein Dialog durch Sites, Zeitplan (täglich / wöchentlich /
monatlich / freier Cron-Ausdruck), Zielverzeichnis, Aufbewahrung und Optionen.
Dasselbe per Parameter:
```bash
# täglich 02:15, alle Sites, ohne Logs, 14 Backups aufbewahren
sudo ./scripts/cmk-manage.sh job add --name nachts \
--cron "15 2 * * *" --no-logs --keep 14
# sonntags 03:30, nur zwei Sites, auf die NAS, ohne RRDs, 8 aufbewahren
sudo ./scripts/cmk-manage.sh job add --name nas-woche \
--cron "30 3 * * 0" --sites prod,test \
--dir /mnt/nas/checkmk --no-rrds --no-logs --keep 8
```
Alle Kommandos:
| Kommando | Wirkung |
|---|---|
| `job list` | angelegte Jobs anzeigen |
| `job status` | Zeitplan, Cron-Datei und Schalter |
| `job add --name N --cron "…"` | Job anlegen |
| `job set NAME …` | Job ändern (nicht genannte Felder bleiben) |
| `job del NAME` | Job löschen (die Backups bleiben) |
| `job enable\|disable NAME` | Job ein-/ausschalten |
| `job run NAME` | Job sofort ausführen |
| `job run-all` | alle aktiven Jobs ausführen |
| `job auto on\|off` | automatische Ausführung ein/aus |
Optionen von `job add` / `job set`:
| Option | Bedeutung |
|---|---|
| `--sites ALL\|a,b` | zu sichernde Sites (Vorgabe `ALL`) |
| `--cron "15 2 * * *"` | Zeitplan, fünf Cron-Felder |
| `--dir VERZ` | Zielverzeichnis dieses Jobs (Vorgabe `BACKUP_DIR`) |
| `--keep N` | wie viele Backups im Ziel bleiben (`0` = alle) |
| `--no-rrds`, `--no-logs`, `--stop` | wie bei `backup` |
| `--disabled` | anlegen, aber noch nicht einplanen |
#### Automatik ein- und ausschalten
```bash
sudo ./scripts/cmk-manage.sh job auto on # einplanen
sudo ./scripts/cmk-manage.sh job auto off # Zeitplan entfernen
```
`on` schreibt aus allen **aktiven** Jobs die Datei `/etc/cron.d/checkmk-backup`
– je Job eine Zeile mit seinem eigenen Zeitplan:
```cron
15 2 * * * root /opt/checkmk-stack/scripts/cmk-manage.sh -y job run nachts >>/var/log/cmk-backup.log 2>&1
30 3 * * 0 root /opt/checkmk-stack/scripts/cmk-manage.sh -y job run nas-woche >>/var/log/cmk-backup.log 2>&1
```
Dafür werden root-Rechte gebraucht. Ohne root gibt das Kommando die Zeilen
aus, damit man sie selbst übernehmen kann. `off` entfernt die Datei wieder; die
Jobs selbst bleiben erhalten. Der Schalter steht als `BACKUP_AUTO` in der
`.env`.
Nach jedem Lauf räumt der Job sein eigenes Zielverzeichnis auf `--keep` auf –
ein separater `prune`-Eintrag ist nicht nötig.
#### Wo die Jobs liegen
In `backup-jobs.conf` im Projektverzeichnis, eine Zeile je Job:
```
name|sites|cron|verzeichnis|optionen|aufbewahren|aktiv
nachts|ALL|15 2 * * *|/opt/checkmk-stack/backups|--no-logs|14|on
nas-woche|prod,test|30 3 * * 0|/mnt/nas/checkmk|--no-rrds --no-logs|8|on
```
Die Datei ist bewusst lesbar und versionierbar, gehört aber nicht ins
Repository (sie steht in `.gitignore`, weil sie systemspezifische Pfade
enthält).
---
## 16. 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.
---
## 17. Migration einer Direktinstallation (`migrate_creator.sh`)
Ziel: eine bestehende Checkmk-Installation auf Blech/VM in den Container
übernehmen – **ohne die Agents anzufassen**.
### 17.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.
### 17.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`).
### 17.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.
### 17.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
tar -xzOf backups/cmkmigrate_prod_*.tar.gz cmkbundle/MANIFEST | grep CMK_VERSION
# CMK_VERSION=2.3.0p23.cre -> Version 2.3.0p23, Endung .cre = Raw Edition
# passendes Image holen und als CMK_IMAGE eintragen lassen
sudo ./scripts/cmk-manage.sh image pull --edition raw --version 2.3.0p23
sudo ./scripts/cmk-manage.sh up
```
Bei einer Enterprise-Quelle (`.cee`) entsprechend:
```bash
sudo ./scripts/cmk-manage.sh image pull --edition enterprise --version 2.3.0p23 \
--user <benutzer> --password <kennwort>
# oder, wenn die Registry nicht erreichbar ist:
sudo ./scripts/cmk-manage.sh image download --edition enterprise --version 2.3.0p23 \
--user <benutzer> --password <kennwort>
```
Das Import-Skript prüft das selbst und bricht mit einer entsprechenden Meldung
ab, wenn die Version fehlt.
> **Edition beachten:** die Endung der Version verrät sie –
> `.cre` = Raw, `.cee` = Enterprise, `.cce` = Cloud, `.cme` = Managed.
> Das Import-Skript liest sie aus dem Manifest und nennt im Fehlerfall direkt
> das passende `image pull`-Kommando. Enterprise-Images gibt es **nicht** auf
> Docker Hub – siehe [Kapitel 8](#8-checkmk-image-beschaffen-raw-enterprise--co).
### 17.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.
### 17.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.
### 17.7 Checkliste Migration
- [ ] `migrate_creator.sh` auf den Quellserver kopiert
- [ ] Bundle erzeugt (möglichst mit `--stop`)
- [ ] Bundle auf das Zielsystem kopiert (`backups/`)
- [ ] passendes Image geholt (`image pull`/`image download`), `CMK_IMAGE` 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)
---
## 18. 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.
---
## 19. 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) neues Image holen (traegt CMK_IMAGE automatisch in die .env ein)
sudo ./scripts/cmk-manage.sh image pull --edition raw --version 2.3.0p28
# 3) Container neu erstellen
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.
---
## 20. 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* | passendes Image holen: `cmk-manage.sh image pull --edition <ed> --version <v>`, dann `up` |
| Import bricht mit Editions-Warnung ab | Enterprise-Backup benötigt ein Enterprise-Image, siehe [Kapitel 8](#8-checkmk-image-beschaffen-raw-enterprise--co) |
| `Login Succeeded`, aber Pull scheitert mit `unable to copy from source` | Der Repository-Pfad oder das Tag stimmt nicht. `cmk-manage.sh image repos --edition enterprise` zeigt, was die Registry anbietet; sonst über den Tarball gehen |
| `image not known` / Podman sucht bei `registry.access.redhat.com` | kurzer Image-Name. `CMK_IMAGE` vollqualifiziert setzen: `cmk-manage.sh image use docker.io/…` bzw. `registry.checkmk.com/enterprise/…` |
| `checkmk/check-mk-enterprise` nicht auf Docker Hub gefunden | richtig so – Enterprise liegt nur auf `registry.checkmk.com` oder als Tarball vor; ab 2.5 heißt die Edition `pro` und liegt frei auf Docker Hub |
| Tarball mit `podman import` eingespielt, Image „unbekannt“ | `import` erzeugt ein Image ohne Metadaten. Fehl-Image mit `podman rmi <id>` entfernen und `cmk-manage.sh image load --file …` verwenden (nutzt `load`) |
| Download des Image-Tarballs schlägt fehl (401/404) | Zugangsdaten des Kundenportals prüfen, exakte Version angeben (kein `-latest`), notfalls `image download --url '<vollständige URL>'` |
| 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`) |
| `This system is not registered with an entitlement server` | RHEL ohne Subskription – `dnf` liefert dann gar keine Pakete. Registrieren, Installations-DVD als Repository einbinden oder auf Rocky/Alma wechseln: [Abschnitt 5.1](#51-unregistriertes-rhel-woher-die-pakete-kommen) |
| `epel-release` lässt sich nicht installieren | EPEL setzt Red Hats Basis-Repositories voraus und ersetzt die Registrierung nicht. Ohne Subskription führt der Quadlet-Weg ohne `podman-compose` zum Ziel: [Kapitel 6, Variante B](#variante-b--podman-quadlet-ab-podman-44-ohne-compose) |
| Proxy-Manager-Container startet nicht mehr mit | Schalter steht auf `off`: `cmk-manage.sh npm-enable on`. Prüfen mit `cmk-manage.sh npm-enable` |
| Adminoberfläche aus dem LAN nicht erreichbar | Port 81 gesperrt. Auf einen freien Port legen: `cmk-manage.sh npm-port 10443` und in der Firewall freigeben |
| Nach `npm-port` antwortet der neue Port nicht | Proxy Manager wurde nicht neu gestartet: `cmk-manage.sh restart`; Datei prüfen: `data/npm/data/nginx/custom/http.conf` |
| `cmk-manage.sh` bricht mit „CMK_RUNTIME … ist nicht installiert" ab | wird nur noch gewarnt und selbst gesucht; sauber setzen mit `config set CMK_RUNTIME auto` |
| Browser bleibt schwarz, „Waiting for Firefox to connect…" | Die Startseite antwortet nicht – meist läuft der Proxy Manager nicht. Das Skript meldet das jetzt vorab, siehe [Kapitel 11.3](#113-schwarzes-fenster-die-startseite-antwortet-nicht) |
| Proxy-Manager-Oberfläche im Browser leer / nur Textfragmente | Textbrowser ohne JavaScript verwendet. `cmk-manage.sh browser --engine browsh` (bzw. `carbonyl`) nehmen |
| Selbstsigniertes Zertifikat lässt sich im Terminal-Browser nicht hochladen | Datei-Dialoge gibt es dort nicht – Upload über die API, siehe [Kapitel 11.4](#114-grenze-datei-upload) |
| `browser` meldet „braucht ein echtes Terminal" | Aufruf aus Pipe/Skript. Direkt auf der Konsole oder per SSH aufrufen; nur der Bau geht headless mit `--build-only` |
| Menüpunkt bricht mit einer Fehlermeldung in die Shell ab | behoben: fehlende Container, Sites oder Backups werden jetzt als Dialog gemeldet, die Oberfläche bleibt offen |
| `job auto on` meldet fehlende Rechte | `/etc/cron.d/` braucht root: mit `sudo` aufrufen, oder die ausgegebenen Zeilen selbst übernehmen |
| Proxy Manager verlangt beim ersten Aufruf ein neues Konto | seit 2.15 normal. `NPM_ADMIN_EMAIL`/`NPM_ADMIN_PASSWORD` **vor** dem ersten Start setzen; ist das Konto schon angelegt, dessen Daten dort eintragen |
| Im Terminal-Browser erscheint bei Proxy-Hosts ein JSON-Fehler | Die Oberfläche ist dafür zu aufwendig. Proxy-Hosts stattdessen über `cmk-manage.sh proxy add` anlegen ([Kapitel 10.2](#102-proxy-host-anlegen--ohne-browser)) |
| 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 …
```
---
## 21. 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.
* `NPM_ADMIN_PASSWORD` vor dem ersten Start auf ein eigenes Kennwort setzen –
daraus wird das Administratorkonto des Proxy Managers erzeugt.
* 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.
---
## 22. 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 (Namen aus "cmk-manage.sh image list")
docker image rm docker.io/checkmk/check-mk-raw:2.3.0-latest docker.io/jc21/nginx-proxy-manager:2
# podman image rm …
# ggf. gespeicherte Registry-Anmeldung entfernen
podman logout registry.checkmk.com # bzw. docker logout
# 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