Zum Inhalt springen

xcp-ng-ce-iso

Pipeline zur ISO-Zusammenstellung: übernimmt die Community-RPM-Builds und veröffentlicht ein bootfähiges XCP-hl-ISO.

Repository: Vagrantin/xcp-ng-ce-iso · Sprache: Bash / YAML · Lizenz: AGPL-3.0

Zweck

Dieses Repository übernimmt das signierte xo-lite-ce-RPM von xolite-ce und das signierte xoa-proxy-RPM von xoa-proxy, ergänzt damit eine unveränderte XCP-ng-8.3-Basis mithilfe der offiziellen Toolchain create-install-image und veröffentlicht das resultierende ISO als GitHub-Release.


Toolchain create-install-image

Das offizielle Installations-ISO von XCP-ng wird mit der Toolchain create-install-image zusammengestellt. XCP-hl verwendet sie direkt, statt einen Fork zu pflegen.

Die Toolchain stellt zwei Skripte bereit:

SkriptAusführung alsErgebnis
create-installimg.shrootinstall.img (SquashFS-Ramdisk)
create-iso.shNicht-rootendgültige .iso-Datei

Sie müssen getrennt und in dieser Reihenfolge ausgeführt werden. create-iso.sh akzeptiert das Argument --sign-script zum Einprägen einer MD5-Prüfsumme.


Repository-Struktur

xcp-ng-ce-iso/
├── configs/
│   ├── base/
│   │   └── CUSTOMREPO.tmpl     ← community repo template
│   └── 8.3/                    ← XCP-ng 8.3 config (target)
├── community-repo/
│   └── x86_64/
│       └── repodata/           ← generated by createrepo_c
├── scripts/
│   └── debug/                  ← debug helper scripts (overlaid in CI)
├── Dockerfile.build             ← build environment
└── .github/workflows/
    └── build-iso.yml

CUSTOMREPO.tmpl

Die Definitionsvorlage des Community-Repositorys muss vor dem Build von configs/base/ nach configs/8.3/ kopiert werden:

cp configs/base/CUSTOMREPO.tmpl configs/8.3/CUSTOMREPO.tmpl

Diese Datei teilt dem Installer mit, wo das Community-RPM-Repository liegt. Die Option --define-repo übergibt sie an beide Buildskripte.

Aufbau des Community-RPM-Repositorys

yum hängt die Hostarchitektur (x86_64/) automatisch an die in einer Repository-Datei konfigurierte Basis-URL an. Deshalb muss das Community-Repository repodata/ unterhalb des Architektur-Unterverzeichnisses enthalten:

community-repo/
└── x86_64/
    ├── xo-lite-ce-*.rpm
    ├── xoa-proxy-*.rpm
    ├── xcp-hl-release-*.rpm
    └── repodata/
        ├── repomd.xml
        └── ...

Erzeugen Sie die Repository-Metadaten für das Architektur-Unterverzeichnis:

createrepo_c community-repo/x86_64/

Wie Pakete den installierten Host erreichen

install.img ist die eigene Ramdisk des Installers, nicht das Dateisystem des installierten Hosts. Ein Paket in packages.lst landet ausschließlich in der Installer-Umgebung.

Der installierte Host wird von host-installer aus dem Verzeichnis Packages/ des ISOs aufgebaut. Es installiert xcp-ng-deps samt dessen vollständiger Abhängigkeitsmenge. Ein RPM nur auf dem Medium abzulegen genügt daher nicht: Wenn keine Abhängigkeit es verlangt, bleibt es ungenutzt im ISO-Repository.

Die Community-Pakete gelangen über diese Kette hinein:

xcp-ng-deps
    └── requires xo-lite ──► provided by xo-lite-ce
                                 ├── requires xoa-proxy
                                 └── requires xcp-hl-release

Dieses Requires: ist der einzige Zugangsweg. Früher wurde xcp-hl-release zusätzlich per --extra-packages namentlich bereitgestellt. Diese Option legt ein Paket jedoch nur im ISO-Repository ab, ohne es zur Installation auszuwählen. Sobald die Abhängigkeit existierte, war sie daher redundant und verschleierte nur, welcher Mechanismus das Paket tatsächlich ausliefert.

Eine wichtige Folge: Wird eine xolite-ce-Veröffentlichung von vor dem Hinzufügen des Requires: festgelegt, entsteht ein ISO ohne xcp-hl-release. Die Buildprüfung fängt dies ab, statt ein solches ISO auszuliefern.

Prüfen Sie auf einem vom ISO installierten Host:

rpm -q xcp-hl-release
ls /etc/yum.repos.d/xcp-hl.repo

Docker-Buildumgebung

Der Build läuft in xcp-ng-build-env:8.3, das nach der Ersteinrichtung als xcp-ng-build-ready gespeichert wird:

# First run: commit the prepared image
docker run --name xcpng-build xcp-ng/xcp-ng-build-env:8.3 /bin/true
docker commit xcpng-build xcp-ng-build-ready

Buildprozess Schritt für Schritt

1. Community-Repository vorbereiten

# Download signed RPM from xolite-ce latest release
gh release download --repo Vagrantin/xolite-ce \
    --pattern "xo-lite-ce-*.rpm" \
    --dir community-repo/x86_64/

# Download signed RPM from xoa-proxy latest release
gh release download --repo Vagrantin/xoa-proxy \
    --pattern "xoa-proxy-*.rpm" \
    --dir community-repo/x86_64/

# Generate repo metadata
createrepo_c community-repo/x86_64/

2. Öffentlichen Community-Schlüssel in die Installer-chroot einfügen

Der ISO-Signatur-Unterschlüssel (GPG_PRIVATE_KEY in diesem Repository) wird zu Beginn der Pipeline in den Schlüsselbund des Runners importiert. Anschließend wird der öffentliche Teil aus diesem Schlüsselbund exportiert und in die Vorlagen der Installer-chroot eingefügt. So kann der Installer die Community-RPMs während der Installation prüfen, ohne dass der Endbenutzer manuell einen Schlüssel importiert.

rpm --import innerhalb eines Containers schreibt in die RPM-Datenbank des Containers, nicht in das chroot-installroot, das später in install.img landet. Geben Sie immer --root an, um das richtige Ziel zu verwenden.
# Export the public key from the runner keyring
gpg --armor --export "${GPG_KEY_ID}" > /tmp/RPM-GPG-KEY-xcp-ng-ce

# Copy into the toolchain's installroot template
mkdir -p create-install-image/templates/installimg/base/etc/pki/rpm-gpg/
cp /tmp/RPM-GPG-KEY-xcp-ng-ce \
   create-install-image/templates/installimg/base/etc/pki/rpm-gpg/

# Import into the installer chroot at build time
rpm --root="${ROOTFS}" --import /etc/pki/rpm-gpg/RPM-GPG-KEY-xcp-ng-ce

3. create-installimg.sh ausführen (root)

# Must run as root inside the build container
sudo ./create-installimg.sh \
    --define-repo base \
    --define-repo updates \
    --define-repo community \
    [other options]

Die Option --define-repo muss alle drei Repositorys aufführen: base, updates und community.

4. ISO-Buildnummer eintragen

host-installer liest [build] number aus .treeinfo des Mediums und schreibt sie als BUILD_NUMBER in /etc/xensource-inventory auf dem installierten Host. Upstream liefert den Platzhalter cloud. Auf einem installierten Host wird sonst nirgends erfasst, von welchem Medium er stammt: Die Datenträgerbezeichnung übersteht die Installation nicht, und die unter /var/log/installer/ aufbewahrten Protokolle erwähnen sie nicht.

Tragen Sie den ce-Zähler in die Vorlage ein, bevor create-iso.sh sie ins ISO kopiert. Nur Tokens der Form @@...@@ werden ersetzt; ein Literalwert wird unverändert übernommen:

sed -i "s/^number = .*/number = ${CE_COUNTER}/" \
    create-install-image/templates/iso/8.3/.treeinfo

Auf einem Host, der vom resultierenden ISO installiert wurde:

$ grep BUILD_NUMBER /etc/xensource-inventory
BUILD_NUMBER='ce23'

# xapi reads that inventory, so it is visible remotely too
$ xe host-param-get uuid=<host-uuid> param-name=software-version
... build_number: ce23; ...

5. create-iso.sh ausführen (Nicht-root)

./create-iso.sh \
    --sign-script implantisomd5 \
    --define-repo base \
    --define-repo updates \
    --define-repo community \
    [other options]

6. Nachbearbeitung mit isohybrid

Dieser Schritt ist erforderlich, damit das ISO auf physischer Hardware ohne UEFI-Unterstützung startet.
isohybrid --uefi output.iso

Prüfen Sie das Ergebnis mit:

fdisk -l output.iso
xorriso -report_el_torito output.iso

7. Prüfsumme erzeugen und signieren

Jede Veröffentlichung liefert neben dem ISO drei Dateien. Die Prüfsummendatei ist nach dem zugehörigen ISO benannt:

xcp-ng-ce-8.3.iso
xcp-ng-ce-8.3.iso.sha256
xcp-ng-ce-8.3.iso.sha256.asc

Die Prüfsummendatei enthält den SHA256-Hash des ISOs. Die .asc-Datei ist eine mit dem ISO-Signatur-Unterschlüssel erstellte abgetrennte GPG-Signatur der Prüfsummendatei. Zusammen bilden sie eine zweistufige Prüfkette:

ISO signing subkey
    └── signs ──► xcp-ng-ce-8.3.iso.sha256   (contains hash of the ISO)
                      └── hash matches ──► xcp-ng-ce-8.3.iso
# Produce the checksum file
sha256sum xcp-ng-ce-8.3.iso > xcp-ng-ce-8.3.iso.sha256

# Sign it with the ISO signing subkey
gpg --batch --pinentry-mode loopback \
    --detach-sign --armor \
    xcp-ng-ce-8.3.iso.sha256
# → produces xcp-ng-ce-8.3.iso.sha256.asc

8. Veröffentlichung prüfen (Verfahren für Endbenutzer)

Alle drei Dateien müssen vor dem Prüfen im selben Verzeichnis liegen. sha256sum -c sucht das ISO anhand seines Dateinamens im aktuellen Verzeichnis.
# 1. Download all three files into the same directory
cd ~/Downloads
# download xcp-ng-ce-8.3.iso, xcp-ng-ce-8.3.iso.sha256,
#          xcp-ng-ce-8.3.iso.sha256.asc from the GitHub release page

# 2. Import the community GPG key (one-time setup)
gpg --keyserver keys.openpgp.org \
    --recv-keys 2F591DB9D2C128C4C3D963F46DA00DCA5BBA215A

Schritt 3: Prüfen, dass die Prüfsummendatei von diesem Projekt signiert wurde:

gpg --verify xcp-ng-ce-8.3.iso.sha256.asc \
             xcp-ng-ce-8.3.iso.sha256

Erwartete Ausgabe (entscheidend ist die Zeile Good signature):

gpg: Signature made ...
gpg: Good signature from "XCP-ng home lab Edition <xcp-ng-ce.lid530@passmail.com>"

Bei BAD signature wurde die Prüfsummendatei manipuliert. Fahren Sie nicht fort.

Schritt 4: Prüfen, dass das ISO zur signierten Prüfsumme passt:

sha256sum -c xcp-ng-ce-8.3.iso.sha256

Erwartete Ausgabe:

xcp-ng-ce-8.3.iso: OK

Bei FAILED ist die ISO-Datei beschädigt oder wurde ersetzt. Löschen Sie sie und laden Sie sie erneut herunter.


Interna von install.img

install.img ist ein bzip2-komprimiertes cpio-Archiv (newc), kein SquashFS. create-installimg.sh erzeugt es mit find . | cpio -o -H newc | bzip2; unsquashfs/mksquashfs sind daher nicht anwendbar.

Es enthält die Ramdisk des Installers, nicht das Dateisystem des installierten Hosts. Siehe Wie Pakete den installierten Host erreichen.

Entpacken und erneut verpacken

# Unpack
mkdir installimg-root
bzip2 -dc install.img | (cd installimg-root && cpio -idm)

# Make changes inside installimg-root/
# ...

# Repack (matching upstream: cpio newc, bzip2)
(cd installimg-root && find . | cpio -o -H newc) | bzip2 > install.img.new

Inhalt ohne Entpacken auflisten:

bzip2 -dc install.img | cpio -it

host-installer für die ISO-Speicherpartition patchen

XCP-hl reserviert bei der Installation eine ISO-Partition mit 20 GB. Dafür muss host-installer selbst geändert werden. Dies erfolgt durch Patchen seiner Dateien innerhalb von install.img beim Build, nicht durch Ausliefern eines geforkten host-installer-RPMs.

Der Grund: xo-lite-ce kann die Abhängigkeitsauflösung mit einer virtuellen Fähigkeit (Provides: xo-lite) gewinnen. host-installer ist hingegen ein reales Paket, das bereits in den XCP-ng-Repositorys base/updates existiert. Ein gleichnamiger Ersatz würde eine höhere Epoch in einem auch laufende Hosts betreffenden Kanal verlangen; dafür gibt es keinen sicheren Ablageort. Durch das Patchen der Ramdisk bleibt die Änderung auf die nach Installationsende verworfene Installer-Umgebung begrenzt.

Zwei Patches unter xcp-ng-ce-iso/patches/ setzen dies um. Sie werden vom CI-Schritt Patch toolchain with git angewendet:

PatchZielZweck
installer-iso-sr-hook.patchscripts/create-installimg.shFügt nach der yum-Installation neben dem vorhandenen Installer-Branding-Block einen Schritt patch -p1 -d "$ROOTFS/opt/xensource/installer" ein
host-installer-iso-sr.patch$ROOTFS/opt/xensource/installer/Die eigentliche Änderung: Partitionierung, mkfs, fstab, Inventar sowie Erststartskript und Unit

Der zweite Patch wird aus dem host-installer-Fork (Branch feat/xcp-hl-iso-storage) erzeugt. Dort wird die Änderung als echte Commits gegen Upstream gepflegt und kann mit dessen eigener test/-Suite geprüft werden:

cd host-installer
git diff 10.10.38-8.3..feat/xcp-hl-iso-storage \
    -- backend.py constants.py answerfile.py xcp-hl/ \
    > ../xcp-ng-ce-iso/patches/host-installer-iso-sr.patch

Erzeugen Sie ihn neu, wenn dieser Branch auf ein neueres Upstream-Tag umgebased wird. Ein nicht mehr anwendbarer Patch lässt den Build deutlich fehlschlagen, statt stillschweigend einen ungepatchten Installer auszuliefern. Ein späterer CI-Schritt entpackt das gebaute install.img und durchsucht backend.py, um die tatsächliche Übernahme der Änderung zu bestätigen.

Was der Patch tut. constants.py erhält iso_size (20480 MB) und min_primary_disk_size_with_iso (100 GB). backend.py ergänzt einen ISO-Eintrag in der Partitionstabelle, bemessen und unmittelbar vor der LVM-Partition erstellt, damit das lokale SR weiterhin den Rest des Datenträgers erhält. Es formatiert ihn mit ext4 und festem Label xcphl-iso, schreibt einen fstab-Eintrag und den Inventarschlüssel ISO_PARTITION und legt ein Erststartskript samt systemd-Unit im Ziel-Root-Dateisystem ab.

Die SR-Registrierung benötigt XAPI, das erst auf dem installierten Host läuft. Dieser Teil erfolgt deshalb beim ersten Start, nach dem Vorbild von storage-init.service, das das primäre lokale SR genauso erstellt. Bei späteren Neustarts benötigt die Wiederanbindung keine zusätzliche Unterstützung: XAPI verbindet beim Start jedes getrennte PBD (Create_storage.plug_unplugged_pbds), gewöhnlich etwa 10 Sekunden nach dem Start seiner API.

answerfile.xml einfügen (optional)

Eine im Installer über file:/// referenzierte answerfile.xml wird relativ zum Wurzelverzeichnis der Ramdisk (aus install.img) aufgelöst, nicht zum Wurzelverzeichnis der ISO-CD-ROM. Legen Sie eine Antwortdatei für unbeaufsichtigte Installationen mit dem obigen Verfahren zum erneuten Verpacken in install.img ab.

GPG-Prüfungen über Attribute der Antwortdatei deaktivieren:

<installation gpgcheck="false" repo-gpgcheck="false">
  ...
</installation>

CI-Workflow (GitHub Actions)

Der Workflow wird ausschließlich per Dispatch gestartet. Der iso-agent pusht das Release-Tag und startet dann den Workflow auf diesem Tag-Ref mit den exakt zu integrierenden Komponenten-Release-Tags. Ein reiner Tag-Push löst keinen Build mehr aus: Das Ermitteln der Komponenten über releases/latest konkurrierte mit frisch veröffentlichten Komponenten und konnte ein veraltetes RPM integrieren.

Wichtige Umgebungsanforderungen:

env:
  TMPDIR: /tmp       # Must be set here AND in Dockerfile
  HOME: /tmp         # Required for non-root create-iso.sh step

Wichtige Schritte:

- name: Derive versions from tag
  run: |
    TAG="${{ github.ref_name }}"                            # e.g. v8.3-ce4
    XCPNG_VER=$(echo "${TAG}" | sed 's/^v//;s/-ce.*//')    # → 8.3
    echo "XCPNG_VER=${XCPNG_VER}" >> $GITHUB_ENV

- name: Import ISO signing key
  # GPG_PRIVATE_KEY in this repo holds the ISO signing subkey,
  # different key material from GPG_PRIVATE_KEY in xolite-ce / xoa-proxy
  run: |
    echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --batch \
      --pinentry-mode loopback \
      --passphrase "${{ secrets.GPG_PASSPHRASE }}" --import

- name: Export public key for installer chroot
  run: |
    gpg --armor --export "${GPG_KEY_ID}" > /tmp/RPM-GPG-KEY-xcp-ng-ce
    cp /tmp/RPM-GPG-KEY-xcp-ng-ce \
       create-install-image/templates/installimg/base/etc/pki/rpm-gpg/

- name: Set up Docker build environment
  run: docker build -t xcp-ng-build-ready -f Dockerfile.build .

- name: Download xolite-ce RPM
  run: |
    gh release download --repo Vagrantin/xolite-ce \
      --pattern "xo-lite-ce-*.rpm" \
      --dir community-repo/x86_64/

- name: Download xoa-proxy RPM
  run: |
    gh release download --repo Vagrantin/xoa-proxy \
      --pattern "xoa-proxy-*.rpm" \
      --dir community-repo/x86_64/

- name: Prepare community repo
  run: createrepo_c community-repo/x86_64/

- name: Copy CUSTOMREPO.tmpl
  run: cp configs/base/CUSTOMREPO.tmpl configs/8.3/

- name: Run create-installimg.sh (root)
  run: |
    docker run --rm --privileged \
      -v $PWD:/build \
      -v $PWD/create-install-image:/create-install-image \
      xcp-ng-build-ready \
      bash -c "cd /create-install-image && sudo ./create-installimg.sh ..."

- name: Run create-iso.sh (non-root)
  run: |
    docker run --rm \
      -e HOME=/tmp \
      -v $PWD:/build \
      xcp-ng-build-ready \
      bash -c "cd /create-install-image && ./create-iso.sh ..."

- name: Restore working directory ownership
  run: sudo chown -R $(id -u):$(id -g) .

- name: isohybrid post-processing
  run: isohybrid --uefi output.iso

- name: implantisomd5
  run: implantisomd5 output.iso

- name: Generate and sign checksum
  run: |
    CHECKSUM_FILE="${OUTPUT}.sha256"
    sha256sum "${OUTPUT}" > "${CHECKSUM_FILE}"
    echo "CHECKSUM_FILE=${CHECKSUM_FILE}" >> $GITHUB_ENV
    gpg --batch --pinentry-mode loopback \
      --detach-sign --armor "${CHECKSUM_FILE}"
    gpg --verify "${CHECKSUM_FILE}.asc" "${CHECKSUM_FILE}"

- name: Publish GitHub Release
  uses: softprops/action-gh-release@v2
  with:
    tag_name: ${{ github.ref_name }}
    files: |
      ${{ env.OUTPUT }}
      ${{ env.CHECKSUM_FILE }}
      ${{ env.CHECKSUM_FILE }}.asc

- name: Remove GPG private key
  if: always()
  run: shred -u /tmp/community-signing.key || true
Der Docker-Volume-Mount muss create-install-image referenzieren. Prüfen Sie, dass das Mount-Ziel dem tatsächlichen Namen des geklonten Verzeichnisses entspricht.

Mitarbeit

Um ein Problem zu melden oder eine Änderung vorzuschlagen, erstellen Sie ein Issue unter Vagrantin/xcp-hl.