Saltar al contenido

xcp-ng-ce-iso

Proceso de ensamblado de la ISO: toma los RPM comunitarios y publica una ISO arrancable de XCP-hl.

Repositorio: Vagrantin/xcp-ng-ce-iso · Lenguaje: Bash / YAML · Licencia: AGPL-3.0

Objetivo

Este repositorio toma el RPM firmado xo-lite-ce de xolite-ce y el RPM firmado xoa-proxy de xoa-proxy, los incorpora a una base XCP-ng 8.3 original mediante las herramientas oficiales create-install-image y publica la ISO resultante como versión de GitHub.


Herramientas, create-install-image

La ISO oficial del instalador de XCP-ng se ensambla con las herramientas create-install-image. XCP-hl las utiliza directamente en lugar de mantener una bifurcación.

Las herramientas proporcionan dos scripts:

ScriptSe ejecuta comoGenera
create-installimg.shrootinstall.img (ramdisk SquashFS)
create-iso.shUsuario sin privilegios rootArchivo .iso final

Deben ejecutarse por separado y en ese orden. create-iso.sh acepta el argumento --sign-script para insertar la huella MD5.


Estructura del repositorio

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

La plantilla de definición del repositorio comunitario debe copiarse de configs/base/ a configs/8.3/ antes de ejecutar la compilación:

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

Este archivo indica al instalador dónde está el repositorio RPM comunitario. La opción --define-repo lo pasa a ambos scripts de compilación.

Distribución del repositorio RPM comunitario

yum añade automáticamente la arquitectura del host (x86_64/) a la URL base configurada en el archivo de repositorio. Por ello, el repositorio comunitario debe tener repodata/ bajo el subdirectorio de arquitectura:

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

Genera los metadatos del repositorio sobre el subdirectorio de arquitectura:

createrepo_c community-repo/x86_64/

Cómo llegan los paquetes al host instalado

install.img es el ramdisk del propio instalador, no el sistema de archivos del host instalado. Añadir un paquete a packages.lst lo coloca en el entorno del instalador y en ningún otro sitio.

host-installer construye el host instalado desde el directorio Packages/ de la ISO e instala xcp-ng-deps y todas sus dependencias transitivas. Por tanto, dejar un RPM en el medio no basta: si nada entre esas dependencias lo necesita, permanecerá sin utilizar en el repositorio de la ISO.

Los paquetes comunitarios llegan mediante esta cadena:

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

Ese Requires: es la única vía de entrada. Antes también se preparaba xcp-hl-release por nombre con --extra-packages, pero esa opción solo coloca el paquete en el repositorio de la ISO sin seleccionarlo para su instalación; una vez añadida la dependencia, era redundante y ocultaba el mecanismo real de distribución.

Conviene conocer una consecuencia: fijar una versión de xolite-ce anterior a la incorporación de Requires: genera una ISO sin xcp-hl-release. La verificación de la compilación lo detecta para impedir su publicación.

Verifica en un host instalado desde la ISO:

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

Entorno de compilación Docker

La compilación se ejecuta dentro de xcp-ng-build-env:8.3, guardado como xcp-ng-build-ready tras la preparación inicial:

# 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

Proceso de compilación, paso a paso

1. Preparar el repositorio comunitario

# 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. Inyectar la clave pública comunitaria en el chroot del instalador

La subclave de firma ISO (GPG_PRIVATE_KEY en este repositorio) se importa al llavero del ejecutor al principio del proceso. Después, se exporta la parte pública de ese llavero y se inyecta en las plantillas del chroot del instalador, para que este pueda verificar los RPM comunitarios durante la instalación sin que el usuario final tenga que importar claves manualmente.

rpm --import dentro de un contenedor escribe en la base de datos RPM del contenedor, no en el installroot del chroot que acaba en install.img. Pasa siempre --root para apuntar a la ubicación correcta.
# 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. Ejecutar create-installimg.sh (root)

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

La opción --define-repo debe enumerar los tres repositorios: base, updates y community.

4. Grabar el número de compilación de la ISO

host-installer lee [build] number del .treeinfo del medio y lo escribe en BUILD_NUMBER de /etc/xensource-inventory en el host instalado. El proyecto original distribuye el marcador cloud, y nada más en un host instalado registra el medio del que procede: la etiqueta del volumen no sobrevive a la instalación y los registros conservados en /var/log/installer/ no la mencionan.

Graba el contador ce en la plantilla antes de que create-iso.sh la copie en la ISO. Solo se sustituyen los tokens @@...@@, por lo que un valor literal se conserva intacto:

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

En un host instalado desde la ISO resultante:

$ 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. Ejecutar create-iso.sh (sin root)

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

6. Posprocesado isohybrid

Este paso es obligatorio para arrancar la ISO en hardware físico que no admite UEFI.
isohybrid --uefi output.iso

Verifica el resultado con:

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

7. Suma de comprobación y firma

Cada publicación distribuye tres archivos junto con la ISO. El archivo de suma de comprobación toma el nombre de la ISO correspondiente:

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

El archivo de suma de comprobación contiene el hash SHA256 de la ISO. El archivo .asc es una firma GPG separada del archivo de suma de comprobación, creada con la subclave de firma ISO. Juntos forman una cadena de verificación en dos pasos:

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. Verificar una publicación (procedimiento del usuario final)

Los tres archivos deben descargarse al mismo directorio antes de verificar. sha256sum -c busca la ISO por nombre en el directorio actual.
# 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

Paso 3: verificar que el proyecto firmó el archivo de suma de comprobación:

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

Salida esperada (la línea importante es Good signature):

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

Si aparece BAD signature, el archivo de suma de comprobación ha sido alterado. No continúes.

Paso 4: verificar que la ISO coincide con la suma de comprobación firmada:

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

Salida esperada:

xcp-ng-ce-8.3.iso: OK

Si aparece FAILED, la ISO está dañada o fue sustituida. Bórrala y vuelve a descargarla.


Estructura interna de install.img

install.img es un archivo cpio (newc) comprimido con bzip2, no SquashFS. create-installimg.sh lo construye con find . | cpio -o -H newc | bzip2, por lo que unsquashfs/mksquashfs no son aplicables.

Contiene el ramdisk del instalador, no el sistema de archivos del host instalado; consulta Cómo llegan los paquetes al host instalado.

Desempaquetar y volver a empaquetar

# 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

Lista el contenido sin desempaquetarlo:

bzip2 -dc install.img | cpio -it

Parches de host-installer para la partición de almacenamiento ISO

XCP-hl reserva una partición ISO de 20 GB durante la instalación, lo que requiere modificar el propio host-installer. Se hace parcheando sus archivos dentro de install.img durante la compilación, no distribuyendo un RPM bifurcado de host-installer.

El motivo es que xo-lite-ce puede ganar la resolución de dependencias proporcionando una capacidad virtual (Provides: xo-lite), pero host-installer es un paquete real que ya existe en los repositorios base/updates de XCP-ng. Publicar un sustituto con el mismo nombre requeriría aumentar el epoch en un canal destinado a hosts en producción, y no hay ningún lugar seguro donde hacerlo. Parchear el ramdisk limita el cambio al entorno del instalador, que se descarta al terminar la instalación.

Dos parches en xcp-ng-ce-iso/patches/, aplicados por el paso CI Patch toolchain with git, realizan el cambio:

ParcheDestinoObjetivo
installer-iso-sr-hook.patchscripts/create-installimg.shAñade un paso patch -p1 -d "$ROOTFS/opt/xensource/installer" después de yum install, junto al bloque de personalización del instalador existente
host-installer-iso-sr.patch$ROOTFS/opt/xensource/installer/El cambio: particionado, mkfs, fstab, inventario y el script y la unidad de primer arranque

El segundo parche se genera desde la bifurcación de host-installer (rama feat/xcp-hl-iso-storage), donde el cambio se mantiene como commits reales sobre el proyecto original y puede ejecutarse contra su propia batería test/:

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

Vuelve a generarlo cuando se rebase esa rama sobre una etiqueta original más reciente. Un parche que ya no se aplica hace fallar la compilación claramente en lugar de distribuir silenciosamente un instalador sin modificar; además, un paso CI posterior desempaqueta el install.img generado y busca en backend.py para confirmar que el cambio se aplicó.

Qué hace el parche. constants.py incorpora iso_size (20480 MB) y min_primary_disk_size_with_iso (100 GB); backend.py añade una entrada ISO a la tabla de particiones que crea, con el tamaño indicado e inmediatamente antes de la partición LVM para que el SR local siga ocupando el final del disco. La formatea en ext4 con la etiqueta fija xcphl-iso, escribe una entrada fstab y una clave de inventario ISO_PARTITION, y deja un script de primer arranque y una unidad systemd en la raíz de destino.

Registrar el SR requiere XAPI, que solo se ejecuta en el host instalado, por lo que esa parte se realiza en el primer arranque, siguiendo el modelo de storage-init.service, que crea el SR local principal del mismo modo. Volver a conectar el SR en reinicios posteriores no requiere ayuda adicional: XAPI conecta todos los PBD desconectados al arrancar (Create_storage.plug_unplugged_pbds), normalmente unos 10 segundos después de que su API esté disponible.

Inyección de answerfile.xml (opcional)

Un answerfile.xml referenciado mediante file:/// en el instalador se resuelve en la raíz del ramdisk (de install.img), no en la raíz del CD-ROM ISO. Para inyectar un archivo de respuestas para instalaciones desatendidas, colócalo dentro de install.img mediante el proceso de reempaquetado anterior.

Desactiva las comprobaciones relacionadas con GPG mediante los atributos del archivo de respuestas:

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

Flujo CI (GitHub Actions)

El flujo se ejecuta solo por despacho. iso-agent sube la etiqueta de publicación y despacha después el flujo sobre esa referencia, pasando las etiquetas exactas de publicación de los componentes que se incluirán. Subir una etiqueta por sí solo ya no activa una compilación: resolver componentes mediante releases/latest podía competir con publicaciones recién creadas e incluir un RPM obsoleto.

Requisitos principales del entorno:

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

Pasos principales:

- 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
El montaje de volumen Docker debe referenciar create-install-image. Verifica que el destino del montaje coincida con el nombre real del directorio clonado.

Contribuciones

Para informar de un problema o proponer un cambio, abre una incidencia en Vagrantin/xcp-hl.