From ece634aecc72e6ff7ad666bbee6def74c2a41af1 Mon Sep 17 00:00:00 2001 From: Yann Dirson Date: Tue, 18 Nov 2025 15:21:29 +0100 Subject: [PATCH 1/2] troubleshooting/upgrade: leave some place for other cases Signed-off-by: Yann Dirson --- docs/troubleshooting/installation-upgrade.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/troubleshooting/installation-upgrade.md b/docs/troubleshooting/installation-upgrade.md index a76f2e69..2d24e331 100644 --- a/docs/troubleshooting/installation-upgrade.md +++ b/docs/troubleshooting/installation-upgrade.md @@ -32,9 +32,11 @@ The target installation partition is mounted in `/tmp/root`. ## The ISO installer does not offer to upgrade the existing install (XCP-ng or XenServer) :::note -This section details how to deal with the most frequent cause for the installer not detecting your current installation. There can be other, rarer cases which are not detailed here. +This section details how to deal with the most frequent causes for the installer not detecting your current installation. There can be other, rarer cases which are not detailed here. ::: +### UEFI/BIOS mismatch + For the installer to detect your current install (XCP-ng or XenServer), the ISO must be booted in the same firmware context. The difference is how you pick the drive at boot. This applies to physical and virtual CD/DVD/USB drives. @@ -55,7 +57,7 @@ Virtual CDROM Device <<<<<< This one is the same device, in legacy BIOS --------------------------------- ``` -### How to check if a running install is using UEFI or legacy BIOS? +#### How to check if a running install is using UEFI or legacy BIOS? On the host, run `efibootmgr`. @@ -70,4 +72,4 @@ The main log file is `/var/log/installer/install-log`. ## Debugging the installer -You can [build your own installer](../../project/development-process/ISO-modification). \ No newline at end of file +You can [build your own installer](../../project/development-process/ISO-modification). From c2d18d27d66a294652e0219b44be8eef8bcc7649 Mon Sep 17 00:00:00 2001 From: Yann Dirson Date: Tue, 18 Nov 2025 15:58:49 +0100 Subject: [PATCH 2/2] troubleshooting/upgrade: describe first-boot service never completing Signed-off-by: Yann Dirson --- docs/troubleshooting/installation-upgrade.md | 27 ++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/troubleshooting/installation-upgrade.md b/docs/troubleshooting/installation-upgrade.md index 2d24e331..b0178a2f 100644 --- a/docs/troubleshooting/installation-upgrade.md +++ b/docs/troubleshooting/installation-upgrade.md @@ -64,6 +64,33 @@ On the host, run `efibootmgr`. - If you see `EFI variables are not supported on this system.` you're running on legacy BIOS. - If you see some EFI boot entries, you’re running on UEFI. +### First-boot service won't complete + +During the first boot, several tasks finalize the installation. Each task logs a "done" stamp upon completion, and if any critical task fails, the system will block future upgrades. + +This can happen if the host was never fully booted after installation or upgrade, or if a specific first-boot service failed to execute properly. + +To diagnose, check the installation log. See [During installation or upgrade](#during-installation-or-upgrade) to access the log file. + +In this case, you would see one or two log lines like the ones below. If the system never booted, both messages typically appear: + +``` +Cannot upgrade nvme0n1, expected file missing: var/lib/misc/ran-storage-init (installation never booted?) +Cannot upgrade nvme0n1, expected file missing: var/lib/misc/ran-network-init (installation never booted?) +``` + +If you only see the "storage-init" line, error line, check the logs of `storage-init.service` in `/var/log/daemon.log` on the host (after rebooting into the original XCP-ng version you’re upgrading from). + +If upgrading from an older release, you may instead get logs showing: + +``` +Upgradeability test failed: + Firstboot: ... + Missing state: ... +``` + +The "Missing state" line indicates which required first-boot service failed to complete. + ## Installation logs The installer writes in `/var/log/installer/`.