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 1 commit 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
1 commit
Select commit
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
14 changes: 1 addition & 13 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
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.