Updating XCP-ng HomeLab Edition
XCP-HL components are shipped as signed RPMs from yum repositories hosted on GitHub Pages, so a running host updates in place. There is no need to reinstall from the ISO to pick up a new XO Lite or xoa-proxy build.
- Where updates appear
- Installing updates
- Repository configuration
- First-time setup on an existing host
- Rolling back
- Verification and trust
- Known limitations
Where updates appear
Available XCP-HL updates show up in Xen Orchestra, in the same place as stock XCP-ng updates:
Home > Hosts > <your host> > Patches
The tab lists each available package with its name, description, version, release and download size, and a red badge shows the count. Selecting Show changelog eye icon on a row opens the RPM changelog entry. The pool-level view at Home > Pools > <pool> > Patches and the dashboard summary show the same data.
XCP-ng ships an XAPI plugin, updater.py, that Xen Orchestra queries for available updates, and XOA-HL is patched to include the XCP-HL repositories in that query.
Installing updates
Install all patches in the Patches tab applies everything the list shows.
This is all or nothing. XCP-ng’s updater plugin runs a single yum update across the stock XCP-ng repositories and the XCP-HL ones together, so pressing the button also applies any pending XCP-ng OS updates. There is no way to select individual packages from this view. If you want only the XCP-HL packages, run yum update xo-lite-ce xoa-proxy on the host instead.
From the host command line, the equivalents are:
yum check-update # what is available
yum update xcp-hl-release # repository configuration itself
yum update xo-lite-ce # XO Lite (HomeLab Edition)
yum update xoa-proxy # XVA deploy proxy
Repository configuration
Configuration lives in a single file, /etc/yum.repos.d/xcp-hl.repo, owned by the xcp-hl-release package. It defines three repositories:
| Repository ID | Contents | Published from |
|---|---|---|
xcp-hl-base | xcp-hl-release | xcp-hl |
xcp-hl-xolite | xo-lite-ce | xolite-ce |
xcp-hl-xoa-proxy | xoa-proxy | xoa-proxy |
Do not rename the sections in that file. The repository IDs are passed by Xen Orchestra to the updater.py plugin, which lists updates only for repositories it was told about. A renamed section does not raise an error, it silently removes those packages from the Patches tab.
Because yum never re-reads a .repo file it already has, repository settings are delivered as a package rather than as a file you copy once. A change to the configuration reaches your host through yum update xcp-hl-release.
The file is marked %config(noreplace), so if you have edited it locally your version is kept and the new one is written alongside as xcp-hl.repo.rpmnew.
First-time setup on an existing host
Hosts installed from an ISO that predates the xcp-hl-release package need a one-time bootstrap. Afterwards, configuration is managed by yum.
curl -L -o /etc/yum.repos.d/xcp-hl.repo \
https://vagrantin.github.io/xcp-hl/xcp-hl.repo
rpm --import https://vagrantin.github.io/xcp-hl/xcp-ng-ce-public.asc
yum clean all
yum install xcp-hl-release
Installing the package replaces the file you just downloaded with the packaged copy, keeping yours as xcp-hl.repo.rpmorig. The two differ only in where they read the signing key from: the downloaded copy fetches it over HTTPS, while the packaged copy uses the local key the package installs.
Newer ISOs carry xcp-hl-release already, so this section does not apply to them.
Rolling back
Each repository publishes only its most recent releases, which bounds the rollback window. To move back to an earlier build:
yum --showduplicates list xo-lite-ce
yum downgrade xo-lite-ce-<version>
Verification and trust
Packages and repository metadata are signed with the XCP-ng HomeLab Edition GPG key. The client configuration sets repo_gpgcheck=1 with gpgcheck=0.
The RPMs are signed by a GPG signing subkey. On XCP-ng 8.3 dom0, rpm 4.11 registers only the primary key when a key is imported, so it reports NOKEY for any signature made by a subkey and cannot verify the packages directly. Trust therefore runs through the repository metadata: repomd.xml is signed and verified by GPG proper, which is subkey aware; it records a SHA-256 of primary.xml, which in turn records a SHA-256 of every package.
The signing subkeys expire 2027-05-10. After that date verification fails until they are extended, the published key is refreshed, and it is re-imported on each host.
Known limitations
XOA-HL itself has no yum repository yet, so the appliance cannot update itself in place. Updating XOA-HL currently means deploying a newer image. This is tracked in issue #14.
Remember that this distribution is in alpha. Read the release notes before updating: breaking changes are expected at every release, and an update may need manual intervention on the host.