Skip to content

Add documentation for new Windows PV tools #306

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

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Add documentation for new Windows PV tools #306

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
188b336
Update XenClean and XenBootFix instructions
dinhngtu Apr 18, 2025
140ced4
Add documentation for new Windows PV tools
dinhngtu Jan 2, 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
27 changes: 7 additions & 20 deletions docs/troubleshooting/windows-pv-tools.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,6 @@
# Windows PV Tools

Common issues with Windows PV tools.

## Windows Management Agent failed to install

### Cause
There was an issue with the installing of the drivers certificate, so the drivers did not load silently.

### Solution
Resolved with version 8.2.2.200-RC1 and newer.

***
Common issues and topics related to Windows PV tools.

## PV-Drivers missing in the Device Manager

Expand All @@ -32,8 +22,6 @@ If the tools are installed, while XCP-ng Center says that I/O is optimized, but

### Possible Solutions

* Resolved with version 8.2.2.200-RC1 and newer.

* Clean your system from `Citrix Client Tools` _AND_ `XCP-ng Client Tools` to create a clean state.
* Then install the Client Tools from scratch.

Expand Down Expand Up @@ -73,11 +61,11 @@ Consult your motherboard manual for details; for example, on Dell systems with i

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
* XCP-ng Windows PV Tools, versions 8.2 to 9.1
* XenServer VM Tools for Windows, versions 7.1 to 9.4
* Other Xen drivers

It is included in the installation package of XCP-ng Windows PV Tools 9.1 and above.
It is included in the installation package of XCP-ng Windows PV Tools 9.0 and above.
[See the newest releases here.](https://github.com/xcp-ng/win-pv-drivers/releases)

:::note
Expand All @@ -98,7 +86,7 @@ XenClean leaves its log files at the current directory and at `%TEMP%\xenclean-<
## Windows fails to boot (hanging at boot or BSOD with Stop code `INACCESSIBLE_BOOT_DEVICE`)

In some situations (failed uninstallation, major Windows version upgrades), Xen PV drivers (whether Citrix or XCP-ng) may cause Windows to fail to start (hanging at boot, BSOD with Stop code `INACCESSIBLE_BOOT_DEVICE`).
The XenBootFix utility included with XCP-ng Windows PV Tools 9.1 and above helps you disable any active Xen PV drivers and get your system to a bootable state before running XenClean.
The XenBootFix utility included with XCP-ng Windows PV Tools 9.0 and above helps you disable any active Xen PV drivers and get your system to a bootable state before running XenClean.

:::note
The utility only runs in Windows Preinstallation Environment (PE) or Windows Recovery Environment (RE). It will not run from Safe Mode.
Expand All @@ -121,9 +109,8 @@ Below is a procedure for using XenBootFix to recover a non-booting VM:
* If your Windows partition does not have a drive letter, type `sel vol N` where `N` is the volume number shown in Diskpart, then type `assign letter=W`. Your Windows partition will be assigned the drive letter `W:`.
* Finally, at the `DISKPART>` prompt, type `exit` to exit Diskpart.
5. Obtain XenBootFix.
* If you're using XCP-ng Windows PV Tools 9.1 or later, it is located at `W:\Program Files\XCP-ng\Windows PV Drivers\XenBootFix\XenBootFix.exe` where `W:` is your Windows drive letter.
* If you have PowerShell, run the following command: `Invoke-WebRequest https://<download path of XenBootFix.exe> -OutFile XenBootFix.exe`
* Failing all that, you can create a new ISO image containing XenBootFix using WinCDEmu, ImgBurn or a similar tool, then attach it to your VM.
* The easiest way is to download and use the [latest release ISO](https://github.com/xcp-ng/win-pv-drivers/releases) of XCP-ng Windows PV Tools, which includes a copy of XenBootFix at `package\XenBootFix\XenBootFix.exe`.
* If you're using XCP-ng Windows PV Tools 9.0 or later, it is also located at `W:\Program Files\XCP-ng\Windows PV Drivers\XenBootFix\XenBootFix.exe` where `W:` is your Windows drive letter.
* **Note**: If using Windows PE, do not remove its CD image when it's running. You may encounter unexpected errors otherwise.
6. Run the command `<path to XenBootFix.exe> W:\Windows` where `W:` is your Windows drive letter.
* **Note**: Make sure the drive letter belongs to your actual Windows installation and not Windows PE/RE. By default, Windows PE/RE use the drive letter **X:**.
Expand Down
29 changes: 14 additions & 15 deletions docs/vms/vms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -370,9 +370,6 @@ Citrix tools:
XCP-ng tools:
* :heavy_plus_sign: Fully open-source.
* :heavy_plus_sign: Maintained by the XCP-ng project.
* :heavy_minus_sign: The drivers are not signed with a key recognized by Microsoft, so Secure Boot can't be enabled with them.
* :heavy_minus_sign: The sources for the management agent are older than that of Citrix (they have stopped updating GitHub a while ago).
* :heavy_minus_sign: Have not been updated in a long time, due to difficulties finding skilled developers to work on them. Being actively worked on.
* :heavy_minus_sign: Won't transparently replace existing Citrix tools. You need to remove Citrix tools first if they are present, in order to install XCP-ng tools.

It's now up to you to choose.
Expand Down Expand Up @@ -403,7 +400,7 @@ If you are using Xen Orchestra, you can switch the "Windows Update tools" advanc
If your VM already has XCP-ng tools and you wish to switch to Citrix tools, then you need to do the same kind of clean-up as described farther in this document for the opposite situation.

#### XCP-ng Windows Guest Tools
Drivers built by the XCP-ng community.
Drivers built and signed by Vates.

**Download**: [https://github.com/xcp-ng/win-pv-drivers/releases](https://github.com/xcp-ng/win-pv-drivers/releases)

Expand Down Expand Up @@ -445,24 +442,26 @@ xe vm-param-get param-name=has-vendor-device uuid={VM-UUID}
`True` means that it's active, `False` that it isn't. It needs to be `False`.

###### Install the XCP-ng drivers
0. snapshot before just in case
1. unpack the ZIP file
2. start setup.exe
3. follow the install wizard
0. Snapshot your VM before installing (just in case)
1. Unpack the ZIP file
2. Start the installation MSI
3. Follow the install wizard

**Note**: Restart can take a while if your windows is currently updating. Restart only occurs after windows has the updates finished.
##### Upgrade from XCP-ng Windows PV Tools (8.2 or earlier) or XenServer VM Tools

4. after restart one of two messages should pop up
* request for restart \<- just restart!
* Management Agent installed successfully \<- enjoy :-)
Our installer will block installation when these tools are already present. These tools must be cleanly uninstalled before continuing with the installation.

##### Upgrade from Citrix :registered: XenServer :registered: client tools
:::warning
If you're using XCP-ng Windows PV Tools 8.2 or earlier, it must be uninstalled using XenClean to avoid encountering BSODs. Follow the procedure in our [Troubleshooting Guide - Windows PV Tools](../troubleshooting/windows-pv-tools.md).
:::

Our installer is not able currently to cleanly uninstall Citrix tools. Citrix tools' uninstaller itself isn't either: it leaves various things behind.
:::warning
In any case, first disable "Windows Update tools" for the VM (Xen Orchestra, advanced tab) and reboot it.
:::

#### Contributing
##### Linux / xBSD
If you would like to contribute improvements to the `install.sh` script so that it supports your distro, create a pull request against: https://github.com/xcp-ng/xe-guest-utilities/tree/master/mk. Relevant files are usually `xe-linux-distribution` and `install.sh`.

##### Windows
The XCP-ng team is looking for help in improving the guest tools installer, build process, and clean-up tools.
The XCP-ng team is looking for help in improving the guest tools installer, build process, and clean-up tools. For more details, see the [win-pv-drivers](https://github.com/xcp-ng/win-pv-drivers) repository.