From 7a74042394c867af9e31fef8dcd96ef31976e21f Mon Sep 17 00:00:00 2001
From: duffyduck <info@hacker-net.de>
Date: Sun, 20 Sep 2026 18:49:27 +0200
Subject: [PATCH] Fehlendes Tag in der Registry: auf den Tarball verweisen

Die Diagnose auf dem Zielsystem zeigte: enterprise/check-mk-enterprise
fuehrt im Zweig 2.4.0 nur p31 aufwaerts, dazu -latest und die taeglichen
Bauten. 2.4.0p9 ist dort herausgerollt - die Registry haelt nur die
juengsten Patchstaende vor.

Nachgemessen, dass das Downloadportal die Version weiterhin hat:
    .../2.4.0p9/check-mk-enterprise-docker-2.4.0p9.tar.gz   HTTP 401
also vorhanden, nur geschuetzt. Auch das oeffentliche Versionsarchiv
listet sie mit genau diesem Dateinamen.

Das ist kein Randfall, sondern der Normalfall bei einer Migration:
"omd restore" verlangt exakt die Version der Quell-Site, und die ist in
aller Regel aelter als das, was die Registry noch vorhaelt.

image_diagnose_ref sieht deshalb bei einem fehlenden Tag im Archiv nach
und nennt, wenn die Version dort liegt, den Tarball-Weg samt fertigem
Kommando - statt den Benutzer zwischen Registry und Portal suchen zu
lassen. Mit dem Unterschied zwischen beiden Quellen ist das jetzt auch
in beiden Sprachfassungen erklaert.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md             | 13 +++++++++++++
 README_en.md          | 13 +++++++++++++
 scripts/cmk-manage.sh | 33 ++++++++++++++++++++++++++++++---
 3 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5cf3209..afe4abb 100644
--- a/README.md
+++ b/README.md
@@ -795,6 +795,19 @@ Abgefragt werden bis zu drei Quellen:
 | Registry (Docker Hub bzw. registry.checkmk.com) | `registry` | nur für Enterprise |
 | Downloadportal (Verzeichnis-Listing) | `download` | ja |
 
+> **Registry und Downloadportal führen nicht dasselbe.** Die Registry hält in
+> der Regel nur die **jüngsten** Patchstände vor – bei `2.4.0` etwa `p31`
+> aufwärts, dazu `2.4.0-latest` und die täglichen Bauten. Ältere Stände sind
+> dort herausgerollt. Das Downloadportal ist dagegen ein **Archiv** und hat sie
+> weiterhin.
+>
+> Das ist genau dann entscheidend, wenn eine **bestimmte** Version gebraucht
+> wird – bei einer Migration nämlich, weil `omd restore` exakt die Version der
+> Quell-Site verlangt ([Kapitel 17.4](#174-schritt-3--zielsystem-auf-die-richtige-version-bringen)).
+> Für solche Fälle ist der Tarball der richtige Weg, nicht die Registry.
+> `image why` weist von sich aus darauf hin, wenn ein Tag in der Registry
+> fehlt, die Version im Archiv aber vorhanden ist.
+
 Ohne `--source` werden alle drei versucht – so kommt auch ohne hinterlegte
 Zugangsdaten eine brauchbare Liste zustande:
 
diff --git a/README_en.md b/README_en.md
index e142d45..2638c9b 100644
--- a/README_en.md
+++ b/README_en.md
@@ -801,6 +801,19 @@ Up to three sources are queried:
 | registry (Docker Hub or registry.checkmk.com) | `registry` | only for Enterprise |
 | download portal (directory listing) | `download` | yes |
 
+> **The registry and the download portal do not carry the same thing.** The
+> registry usually keeps only the **most recent** patch levels – for `2.4.0`
+> roughly `p31` upwards, plus `2.4.0-latest` and the daily builds. Older levels
+> have rolled out of it. The download portal, by contrast, is an **archive** and
+> still has them.
+>
+> This matters precisely when a **specific** version is required – during a
+> migration, because `omd restore` demands exactly the version of the source
+> site ([chapter 17.4](#174-step-3--bring-the-target-system-to-the-right-version)).
+> For those cases the tarball is the right route, not the registry. `image why`
+> points this out by itself when a tag is missing from the registry but the
+> version exists in the archive.
+
 Without `--source` all three are tried – so even without stored credentials you
 get a usable list:
 
diff --git a/scripts/cmk-manage.sh b/scripts/cmk-manage.sh
index fbc41ee..5636fcd 100755
--- a/scripts/cmk-manage.sh
+++ b/scripts/cmk-manage.sh
@@ -1294,9 +1294,36 @@ image_diagnose_ref() {   # ref
         printf '  %sVorhanden (neueste)%s\n' "$C_BLD" "$C_RST"
     fi
     printf '    %s\n' "${near[@]}"
-    printf '\n  Uebernehmen mit:\n'
-    printf '    %s image use %s/%s:<tag> --remember\n' "$SELF" "$reg" "$repo"
-    printf '    %s up\n' "$SELF"
+
+    # Registries halten meist nur die juengsten Patchstaende vor. Aeltere
+    # Versionen liegen weiterhin im Downloadportal - und genau die braucht
+    # man bei einer Migration, weil "omd restore" die exakte Version
+    # verlangt. Deshalb hier nachsehen, statt den Benutzer suchen zu lassen.
+    local tarball=""
+    if [ -n "$tag" ]; then
+        tarball="$(archive_docker_file "${CMK_EDITION:-enterprise}" "$tag" 2>/dev/null || true)"
+    fi
+    if [ -n "$tarball" ]; then
+        cat <<EOF
+
+  ${C_BLD}Diese Version gibt es aber als Tarball${C_RST}
+  Registries halten in der Regel nur die juengsten Patchstaende vor;
+  das Downloadportal ist ein Archiv. Dort liegt:
+      $tarball
+
+  Holen und einspielen:
+      $SELF image download --edition ${CMK_EDITION:-enterprise} --version $tag
+      $SELF up
+
+  Das ist der richtige Weg, wenn eine BESTIMMTE Version gebraucht wird -
+  etwa bei einer Migration, weil "omd restore" genau die Version der
+  Quell-Site verlangt.
+EOF
+    else
+        printf '\n  Uebernehmen mit:\n'
+        printf '    %s image use %s/%s:<tag> --remember\n' "$SELF" "$reg" "$repo"
+        printf '    %s up\n' "$SELF"
+    fi
     printf '\n  Alle Tags:  %s image versions --source registry --edition %s --all\n\n' \
            "$SELF" "${CMK_EDITION:-enterprise}"
     return 1