Skip to content

Commit 393dfb0

Browse files
Update documentation for new Windows PV tools (#398)
* Add documentation for new Windows PV tools. Also remove outdated WPV 8.2 instructions. * Remove tools mention from guest Secure Boot page. * Settle on "XCP-ng Windows Guest Tools". * Update repo links. Co-authored-by: Thomas Moraine <thomas.moraine@vates.tech> Signed-off-by: Tu Dinh <ngoc-tu.dinh@vates.tech>
1 parent 5944f96 commit 393dfb0

File tree

4 files changed

+67
-115
lines changed

4 files changed

+67
-115
lines changed

docs/guides/guest-UEFI-Secure-Boot.md

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,6 @@ Enabling UEFI Secure Boot for guests ensures that XCP-ng VMs will only execute t
1111
* A UEFI guest VM.
1212
* For Windows, ensure the VM has at least 2 vCPUs.
1313

14-
:::warning
15-
Until we can re-sign XCP-ng's PV drivers for Windows, you will need the PV drivers from XenServer before enabling Secure Boot for a Windows VM. See [Setup Secure Boot for Windows VMs](#setup-secure-boot-for-windows-vms).
16-
:::
17-
1814
Note: it's not necessary that the XCP-ng host boots in UEFI mode for Secure Boot to be enabled on VMs.
1915

2016
## Quick Start

docs/project/gitrepo.md

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,6 @@ Here is a complete list of repositories used by this project.
1414

1515
* [https://github.com/xcp-ng/xenadmin](https://github.com/xcp-ng/xenadmin)
1616

17-
## 🪟 Windows Client Tools
18-
19-
* [https://github.com/xcp-ng/win-pv-drivers](https://github.com/xcp-ng/win-pv-drivers) - Windows Client Tools Releases and little helpers for Windows PV-driver development
20-
* [https://github.com/xcp-ng/win-xenbus](https://github.com/xcp-ng/win-xenbus) - Windows PV Bus Driver
21-
* [https://github.com/xcp-ng/win-xeniface](https://github.com/xcp-ng/win-xeniface) - Windows PV Interface Driver
22-
* [https://github.com/xcp-ng/win-xenvbd](https://github.com/xcp-ng/win-xenvbd) - Windows PV Storage Host Adapter Driver
23-
* [https://github.com/xcp-ng/win-xenvif](https://github.com/xcp-ng/win-xenvif) - Windows PV Network Class Driver
24-
* [https://github.com/xcp-ng/win-xennet](https://github.com/xcp-ng/win-xennet) - Windows PV Network Device Driver
25-
* [https://github.com/xcp-ng/win-xenguestagent](https://github.com/xcp-ng/win-xenguestagent) - Windows Management Agent
26-
* [https://github.com/xcp-ng/win-xenvss](https://github.com/xcp-ng/win-xenvss) - VSS Driver
27-
* [https://github.com/xcp-ng/win-installer](https://github.com/xcp-ng/win-installer) - Installer
28-
* [https://github.com/xcp-ng/win-installer-ng](https://github.com/xcp-ng/win-installer-ng) - New installer with better problem solving
17+
## 🪟 Windows Guest Tools
18+
19+
* [https://github.com/xcp-ng/win-pv-drivers](https://github.com/xcp-ng/win-pv-drivers) - Windows Guest Tools installer and releases

docs/troubleshooting/windows-pv-tools.md

Lines changed: 10 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,6 @@
1-
# Windows PV Tools
1+
# Windows Guest Tools
22

3-
Common issues with Windows PV tools.
4-
5-
## PV-Drivers missing in the Device Manager
6-
7-
### Cause
8-
9-
If despite running the Windows tools installer, there's no devices visible in the device manager, it's likely because there's some leftovers from old Citrix XenServer Client Tools.
10-
11-
### Solutions
12-
13-
#### Leftovers from old Citrix XenServer Client Tools.
14-
15-
See the [XenClean guide](/vms/#fully-removing-xen-pv-drivers-with-xenclean) for instructions.
16-
17-
## Network PV drivers aren't working.
18-
19-
### Cause
20-
21-
If the tools are installed, while XCP-ng Center says that I/O is optimized, but the network card is not correctly installed and the Management Agent is also not working. There was an issue with the installing of the drivers certificate, so the drivers did not load silently.
22-
23-
### Possible Solutions
24-
25-
* Clean your system from `Citrix Client Tools` _AND_ `XCP-ng Client Tools` to create a clean state.
26-
* Then install the Client Tools from scratch.
27-
28-
See the [XenClean guide](/vms/#fully-removing-xen-pv-drivers-with-xenclean) for instructions.
3+
Common issues and topics related to Windows Guest Tools.
294

305
## Not all PV drivers are correctly installed
316

@@ -58,10 +33,10 @@ Consult your motherboard manual for details; for example, on Dell systems with i
5833
</div>
5934

6035

61-
## Windows fails to boot (hanging at boot or BSOD with Stop code `INACCESSIBLE_BOOT_DEVICE`)
36+
## Windows fails to boot (hangs, `INACCESSIBLE_BOOT_DEVICE`)
6237

6338
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`).
64-
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.
39+
The XenBootFix utility included with XCP-ng Windows Guest Tools 9.0 and above helps you disable any active Xen PV drivers and get your system to a bootable state before running XenClean.
6540

6641
:::note
6742
The utility only runs in Windows Preinstallation Environment (PE) or Windows Recovery Environment (RE). It will not run from Safe Mode.
@@ -84,8 +59,8 @@ Below is a procedure for using XenBootFix to recover a non-booting VM:
8459
* 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:`.
8560
* Finally, at the `DISKPART>` prompt, type `exit` to exit Diskpart.
8661
5. Obtain XenBootFix.
87-
* 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`.
88-
* 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.
62+
* 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 Guest Tools, which includes a copy of XenBootFix at `package\XenBootFix\XenBootFix.exe`.
63+
* If you're using XCP-ng Windows Guest 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.
8964
* **Note**: If using Windows PE, do not remove its CD image when it's running. You may encounter unexpected errors otherwise.
9065
6. Run the command `<path to XenBootFix.exe> W:\Windows` where `W:` is your Windows drive letter.
9166
* **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:**.
@@ -110,7 +85,7 @@ You can use the following procedure:
11085
Connect using [WinDbg](https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/) using the `Attach to kernel` option with a connection string: `com:ipport=7001,port=<host IP>`
11186
* To undo the changes and remove the serial setting, use `xe vm-param-remove uuid=<uuid> param-name=platform param-key=hvm_serial`
11287

113-
## Windows bug check 0x3B (SYSTEM_SERVICE_EXCEPTION) on systems with newer Intel CPUs
88+
## BSOD 0x3B (SYSTEM_SERVICE_EXCEPTION) on newer Intel CPUs
11489

11590
### Cause
11691

@@ -125,7 +100,7 @@ Stop the VM, run the following command on the host then restart the VM:
125100
xe vm-param-add uuid=<VM's UUID> param-name=platform msr-relaxed=true
126101
```
127102

128-
## Windows fails to boot, keeps exiting to Startup Repair/recovery menu after updating
103+
## Windows fails to boot after updating
129104

130105
### Cause
131106

@@ -141,7 +116,7 @@ bcdboot C:\Windows
141116

142117
After exiting to Windows, your system should boot successfully.
143118

144-
## Windows Server 2019 crashes on AMD Zen hosts without showing a BSOD
119+
## Windows Server 2019 crashes on AMD Zen without BSOD
145120

146121
First, try disabling Viridian from Xen Orchestra. Note that this value may reset itself after reboot.
147122

@@ -182,7 +157,7 @@ If this feature is enabled, XenServer VM Tools will automatically uncheck the "I
182157

183158
Make sure to either check this checkbox, specify `ALLOWDRIVERINSTALL=YES` on the Msiexec command line (if installing via command line) or install driver updates via Windows Update.
184159

185-
## PV devices not getting updates with the "Manage Citrix PV drivers via Windows Update" option enabled
160+
## XenServer drivers not receiving updates via Windows Update
186161

187162
### Cause
188163

0 commit comments

Comments
 (0)