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:
| Skript | Ausführung als | Ergebnis |
|---|---|---|
create-installimg.sh | root | install.img (SquashFS-Ramdisk) |
create-iso.sh | Nicht-root | endgü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.ymlCUSTOMREPO.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.tmplDiese 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-releaseDieses 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.repoDocker-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-readyBuildprozess 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-ce3. 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/.treeinfoAuf 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
isohybrid --uefi output.isoPrüfen Sie das Ergebnis mit:
fdisk -l output.iso
xorriso -report_el_torito output.iso7. 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.ascDie 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.asc8. Veröffentlichung prüfen (Verfahren für Endbenutzer)
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 2F591DB9D2C128C4C3D963F46DA00DCA5BBA215ASchritt 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.sha256Erwartete 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.sha256Erwartete Ausgabe:
xcp-ng-ce-8.3.iso: OKBei 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.newInhalt ohne Entpacken auflisten:
bzip2 -dc install.img | cpio -ithost-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:
| Patch | Ziel | Zweck |
|---|---|---|
installer-iso-sr-hook.patch | scripts/create-installimg.sh | Fü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.patchErzeugen 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 stepWichtige 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 || truecreate-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.