Skip to content

UEFI vs BIOS warning in upgrade documentation and troubleshooting guide #405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

UEFI vs BIOS warning in upgrade documentation and troubleshooting guide #405

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6c8cabf
upgrade.md : Warning on ISO boot mode for XenServer ugrade
yblatti Oct 30, 2025
9c537cc
upgrade.md : Upgrade via installation ISO : redirect to "installation…
yblatti Oct 30, 2025
4dfbb88
upgrade.md : Warning on ISO boot mode for ISO ugrade
yblatti Oct 30, 2025
e0f085a
installation-upgrade.md : Add a troubleshooting entry for upgrade not…
yblatti Oct 30, 2025
c44b1af
Apply suggestions from code review (@thomas-dkmt)
yblatti Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion docs/installation/upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,12 @@ Steps:
Then, for every host of the pool, starting with the pool master:

3. Move all VMs off the host if your setup allows it, or turn them off.
4. Follow the installation procedure on the [download page](https://xcp-ng.org/download/).
4. Follow the installation procedure on the [installation page](../install-xcp-ng#start-the-host).

:::warning
You must boot the ISO in the firmware mode that was used for initial installation: UEFI or BIOS. Otherwise, the installer won't detect the existing installation and offer to upgrade.
:::

5. When offered the choice, choose to upgrade your existing XCP-ng installation.
6. After the upgrade completed, reboot your host.
7. [Install the updates](../../management/updates) that have been released after the installation ISO was created. They can fix bugs and/or security issues.
Expand Down Expand Up @@ -252,6 +257,10 @@ XCP-NG installation follows roughly the same workflow as a XenServer installatio

Then boot on the ISO!

:::warning
You must boot the ISO in the firmware mode that was used for initial installation: UEFI or BIOS. Otherwise, the installer won't detect the existing XenServer installation and offer to upgrade.
:::

![](https://xcp-ng.org/assets/img/screenshots/install1bis.png)

Eventually, you will reach a screen offering to upgrade your XenServer to XCP-ng:
Expand Down
29 changes: 29 additions & 0 deletions docs/troubleshooting/installation-upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,35 @@ When asking for help about installation errors, providing this file increases yo

The target installation partition is mounted in `/tmp/root`.

## The ISO installer does not offer to upgrade the existing install (XCP-ng or XenServer)

For the installer to detect your current install (XCP-ng or XenServer), the ISO must be booted in the same firmware context.\
Copy link
Member

@stormi stormi Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a trailing \.

But that's not the comment I wanted to make initially: mismatching firmware mode is not the only reason why the installer will not offer to upgrade in some cases.

For example, in some cases, the firstboot script in the previous installation never completed, which prevents the installer from detecting the existing installation.

@ydirson can likely tell more about it.

Copy link
Author

@yblatti yblatti Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your feedback !

[...] mismatching firmware mode is not the only reason why the installer will not offer to upgrade in some cases.
For example, in some cases, the firstboot script in the previous installation never completed, which prevents the installer from detecting the existing installation.

TBH, this is out of my league. Feel free to add any relevant information in this section. We could also change the title to a more specific one.

There's a trailing \.

The new line was added for readability. Should I remove it ?

The difference is how you pick the drive at boot. This applies to physical and virtual CD/DVD/USB drives.

If your existing installation is in legacy BIOS mode, boot the ISO in BIOS mode.

If your existing installation is in UEFI mode, boot the ISO in UEFI mode.

In your server boot menu, you might see something like this:

```
Please select boot device:
---------------------------------
UEFI: Virtual CDROM Device <<<<<< This one is in UEFI mode
Virtual CDROM Device <<<<<< This one is the same device, in legacy BIOS mode
...
other boot entries
...
---------------------------------
```

### How to check if a running install is using UEFI or legacy BIOS?

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.

## Installation logs

The installer writes in `/var/log/installer/`.
Expand Down