diff --git a/docs/guides/guest-UEFI-Secure-Boot.md b/docs/guides/guest-UEFI-Secure-Boot.md index 0aae7bbc..1fbec37a 100644 --- a/docs/guides/guest-UEFI-Secure-Boot.md +++ b/docs/guides/guest-UEFI-Secure-Boot.md @@ -4,6 +4,30 @@ How to configure UEFI Secure boot? Enabling UEFI Secure Boot for guests ensures that XCP-ng VMs will only execute trusted binaries at boot. In practice, these are the binaries released by the operating system (OS) vendor for the OS running in the VM (Microsoft Windows, Debian, RHEL, Alpine, etc.). +## Upcoming changes in Secure Boot + +The default Secure Boot keys in XCP-ng are changing. + +Previously, XCP-ng only shipped with the PK included by default; Secure Boot databases had to be installed using `secureboot-certs`. + +New versions of XCP-ng `varstored` (from version **TODO** and newer) now comes with a complete set of Secure Boot databases (PK/KEK/db/dbx) by default, meaning that guest Secure Boot will now work without needing further pool configuration. + +### What this change means for you + +You will not be affected in most cases. + +* Existing VMs will not be affected unless you use the ["Propagate certificates"](#propagate-pool-certificates-to-a-vm) feature in Xen Orchestra (which has always had the effect of resetting VM Secure Boot variables to that of the pool). +* If you followed our previous guides and used `secureboot-certs install` to install the default Secure Boot databases into your pool, these databases will not be changed. + +The only VMs affected by these changes are those with Secure Boot enabled but without custom Secure Boot databases. Previously, these VMs will execute all UEFI binaries even with Secure Boot enabled (due to an empty dbx variable); however, going forward, revoked UEFI binaries (e.g. from an outdated media) will no longer boot on such VMs with Secure Boot enabled. + +To continue booting outdated media on these VMs, you can either: + +- Disable Secure Boot; +- Or erase the VM's dbx variable with the command `varstore-rm d719b2cb-3d3a-4596-a3bc-dad00e67656f dbx` + +Once your VM has completed installing, it should be able to manage its own Secure Boot variables (db/dbx) via its update mechanism. + ## Requirements * XCP-ng >= 8.2.1. @@ -17,7 +41,7 @@ Until we can re-sign XCP-ng's PV drivers for Windows, you will need the PV drive Note: it's not necessary that the XCP-ng host boots in UEFI mode for Secure Boot to be enabled on VMs. -## Quick Start +## Quick Start (8.2.1 and 8.3 with varstored < **TODO**) We believe that reading this guide will provide you with useful knowledge about the way Guest Secure Boot is handled in XCP-ng, and let you avoid mistakes. @@ -91,6 +115,10 @@ For custom certificates (advanced use), see [Install Custom UEFI Certificates](# ### Install the Default UEFI Certificates +:::info +This procedure is not necessary if you're using varstored **TODO** and newer. +::: + `secureboot-certs` supports installing a default set of certificates across the pool. Except the `PK` key which is already provided by XCP-ng, all certificates are downloaded from official sources (`microsoft.com` and `uefi.org`). diff --git a/docs/troubleshooting/windows-pv-tools.md b/docs/troubleshooting/windows-pv-tools.md index 62af7d2a..8a8f0dca 100644 --- a/docs/troubleshooting/windows-pv-tools.md +++ b/docs/troubleshooting/windows-pv-tools.md @@ -1,4 +1,4 @@ -# Windows Agent / PV-Tools +# Windows PV Tools Common issues with Windows PV tools. @@ -21,19 +21,8 @@ If despite running the Windows tools installer, there's no devices visible in th ### Solutions #### Leftovers from old Citrix XenServer Client Tools. -1. remove any xen*.* files from `C:\Windows\system32` like - * xenbus_coinst_7_2_0_51.dll - * xenvbd_coinst_7_2_0_40.dll - * xenbus_monitor_8_2_1_5.exe - * and similiar `xen*_coinst` and `xen*_monitor` files -2. remove any leftover `XenServer` devices from device manager, also display hidden `XenServer` devices and remove them! - * To show hidden devices in Device Manager: `View -> Show Hidden Devices` -#### There was an issue with the installing of the drivers certificate, so the drivers did not load silently - -Resolved with version 8.2.2.200-RC1 and newer. - -*** +See the [XenClean guide](#completely-removing-existing-xen-pv-drivers-with-xenclean) below for instructions. ## Network PV drivers aren't working. @@ -48,7 +37,7 @@ If the tools are installed, while XCP-ng Center says that I/O is optimized, but * Clean your system from `Citrix Client Tools` _AND_ `XCP-ng Client Tools` to create a clean state. * Then install the Client Tools from scratch. -[This Guide](../../vms#%EF%B8%8F-guest-tools) may help you through the process. +See the [XenClean guide](#completely-removing-existing-xen-pv-drivers-with-xenclean) below for instructions. ## Not all PV drivers are correctly installed @@ -80,6 +69,85 @@ Consult your motherboard manual for details; for example, on Dell systems with i ![](../../static/img/performance-setting.png) +## Completely removing existing Xen PV drivers with XenClean + +XenClean is an utility for cleanly removing Xen PV drivers and management agents of the following products: + +* XCP-ng Windows PV Tools, versions 8.2 and 9.1 +* XenServer VM Tools for Windows, versions 9.3 and 9.4 +* Other Xen drivers + +It is included in the installation package of XCP-ng Windows PV Tools 9.1 and above. +[See the newest releases here.](https://github.com/xcp-ng/win-pv-drivers/releases) + +:::note +Before running XenClean: + +* Take a snapshot of your VM. +* You should always use the latest version of XenClean regardless of your Windows PV driver version. The same applies to XenBootFix. +* You should disable the "Manage Citrix PV drivers via Windows Update" option on your VM. Otherwise, Windows may reinstall PV drivers from Windows Update after rebooting. +* If you downloaded XenClean from the internet, you may need to unblock the script file before running it. This can be done by right-clicking the file, then choosing **Properties** - **Unblock** - **OK**. +::: + +To use XenClean, simply run the `Invoke-XenClean.ps1` script **as Administrator**. Your system will automatically reboot. + +:::tip +XenClean leaves its log files at the current directory and at `%TEMP%\xenclean-