Monitor and Troubleshoot VUS
Monitoring Scheduled VDA Upgrades
VDAs and machine catalogs have two attributes to help monitor the readiness and current status of VDA upgrades that are visible as columns that can be used to filter in Studio or in the details pane of the VDAs or catalogs.
-
VDA Upgrade
-
VDA Upgrade State
VDA Upgrade
VDA Upgrade provides information on whether the VDA or machine catalog has the VDA upgrade agent configured and if VDAs are up to date or if an upgrade is available. The available statuses are as follows:
| VDA Upgrade (Studio) | VDA Upgrade (Powershell) | Description |
|---|---|---|
| Catalog Level | ||
| Not configured | MissingUpgradeType | An upgrade track (CR, LTSR, CR EAR, or LTSR EAR) has not been selected for the machine catalog. |
| Scheduled | UpgradeScheduled | An upgrade is scheduled for the machine catalog. |
| Available | UpgradeAvailable | VDAs in the catalog are not on the latest version of the upgrade track. An upgrade is recommended. |
| Up to date | UpToDate | VDAs in the catalog are on the latest version of the upgrade track. No action is required, or there is no available upgrade target that supports the VDA's current operating system. |
| Unknown | Unknown | Retrieving the latest VDA Upgrade state. |
| Machine Level | ||
| Not configured | MissingUpgradeType | An upgrade track (CR, LTSR, CR EAR, or LTSR EAR) has not been selected for the machine catalog of the VDA. |
| Scheduled | UpgradeScheduled | An upgrade is scheduled for the VDA. |
| Available | UpgradeAvailable | The VDA is not on the latest version of the upgrade track. An upgrade is recommended. |
| Up to date | UpToDate | The VDA is on the latest version of the upgrade track. No action is required, or there is no available upgrade target that supports the VDA's current operating system. |
| Checking state | Unknown | Retrieving the latest VDA Upgrade state. |
Note:
-
For VDAs using the LTSR track, a catalog will only show as Up to date if the VDAs are on the latest cumulative update (CU) of the latest long term service (LTSR) version. If the VDA is on the latest CU of a previous LTSR version, VDA Upgrade will still show as Available.
-
A VDA also shows Up to date when no available upgrade target supports its current operating system (for example, Windows Server 2016 from CVAD 2407 onward). The Upgrade VDAs wizard then offers no target for the VDA. To upgrade it, re-image the machine to a supported operating system, then schedule the upgrade. See the System requirements for the target version and CTX224843.
VDA Upgrade State
VDA Upgrade State provides information on the status of a scheduled upgrade. The VDA Upgrade State statuses are as follows:
| VDA Upgrade State (Studio) | VDA Upgrade State (PowerShell) | Description |
|---|---|---|
| Catalog Level | ||
| Not scheduled | NotScheduled | No upgrade is scheduled for the catalog. |
| Scheduled | UpgradeScheduled | An upgrade is scheduled for the catalog. |
| In progress | UpgradeInProgress | An upgrade is in progress for the catalog. |
| Canceled | UpgradeCancelled | An upgrade was cancelled for the catalog. This can be due to a manual cancellation or the failure threshold being reached. |
| Failed | UpgradeFailed | A scheduled upgrade for the catalog failed. |
| Successful | UpgradeSuccessful | A scheduled upgrade for the catalog completed successfully. Note: A successful upgrade does not mean all VDAs in the catalog upgraded successfully. |
| - | Empty | No upgrade scheduled for the catalog. |
| Machine Level | ||
| Scheduled | UpgradeScheduled | An upgrade is scheduled for the VDA. |
| Awaiting upgrade | UpgradeInUpgradeWindow | A scheduled upgrade is active, but the VDA has not started to upgrade yet. See “Concurrency” for more information on how VDA upgrades are load-balanced. |
| In progress | UpgradeInProgress | The VDA is currently upgrading. |
| Canceled | UpgradeCancelled | A scheduled upgrade has been cancelled for the VDA before the upgrade began. |
| Upgrade failed | UpgradeFailed | The VDA began to upgrade but the upgrade failed to complete successfully. See “troubleshooting” for more information. |
| Succesful | UpgradeSuccess | The VDA upgraded successfully. |
| Validation failed | UpgradeValidationFailed | Certificate validation failed while downloading the metadata for the VDA installer. |
| - | Empty | No upgrade is scheduled for the VDA. |
Troubleshooting Scheduled VDA Upgrades
If you encounter upgrade failures, the following logs can help you identify and troubleshoot the issues. You can also share these logs with Citrix Technical Support to expedite the assistance process.
VDA Installation Logs
When troubleshooting upgrade failures, gather and review the logs for both the initial installation of the VDA and the failed upgrade. Logs for installation and upgrades can be found in the following locations.
-
Installation logs for VDA installations are placed in:
-
%temp%/Citrix/XenDesktop Installer
-
-
Upgrade logs for VDA installations are placed either in:
-
C:\Windows\Temp\Citrix\XenDesktop Installer or
-
C:\Windows\SystemTemp\Citrix\XenDesktop Installer
-
VDA Upgrade Agent Version
When gathering data to troubleshoot upgrade failures through VUS, it is important to know the version of the upgrade agent on the VDAs. To check VDA Upgrade Agent versions, use the following cmdlet:
Get-VusComponentVersion -ComponentType VUS. It lists all VDAs and their VDA Upgrade Agent versions.
To check VDA Upgrade Agent versions at a catalog level, you can use the following script:
Note:
The script is intended as an example and might need to be adapted to suit your specific environment. We recommend that you test the script thoroughly before using it in a production environment.
Param( [Parameter (Mandatory=$true)] [string] $CatalogName ) try { $Uuids = Get-BrokerMachine -CatalogName $CatalogName | Select-Object -Property UUID
if($Uuids -eq $null) { throw "Cannot find CatalogName " +$CatalogName } Write-Output("Catalog Name passed is "+$CatalogName)
foreach($Uuid in $Uuids) { $compVersion = Get-VusComponentVersion -MachineId $machine.UUID -ComponentType VUS $Machine = Get-BrokerMachine -UUID $compVersion.MachineId Write-Output(“MachineName: “+$Machine.MachineName+”, Machine UUID:”+$machine.MachineId+”, VUA Version:”+$compVersion.Version) } } catch { Write-Output(“Exception Occured”) Write-Host $_ }
Troubleshoot VDA upgrade download failures
Follow the steps below to troubleshoot and resolve download failures related to the VDA upgrade feature:
-
Make sure that relevant URLs have been added to the allow list if URL filtering is in place. See Connectivity.
-
After adding the necessary URLs to the allow list, try rescheduling the VDA upgrade.
You can enable CDF tracing or set
LogToFile to 1 to capture detailed logs for analysis. If the download failure issue persists, check the errors. If you see the following error message “Download Failed: This access control list is not in canonical form and therefore cannot be modified,” it indicates that the permissions on the folder C:\ProgramData\Citrix\UpgradeServices\Downloads\VDA are incorrect.
To address the issue, do either of the following:
-
Option 1: Reset access control lists (ACLs) on the folder using the following command. (The command reset the ACLs with default inherited ACLs for all matching files.)
-
icacls.exe "C:\ProgramData\Citrix\UpgradeServices\Downloads\VDA" /reset /T /C /L /Q
-
-
Option 2: Delete the VDA folder under Downloads and then schedule the VDA upgrade.
Troubleshoot VDA upgrade validation failures
Follow the steps below to troubleshoot and resolve download failures related to the VDA upgrade feature:
-
Make sure that relevant URLs have been added to the allow list if URL filtering is in place, especially the Certificate Revocation List (CRL) or Online Certificate Status Protocol (OCSP) URLs needed for the revocation check. See VDA upgrade requirement.
-
After adding the necessary URLs to the allow list, try rescheduling the VDA upgrade.
We suggest enabling CDF tracing or setting
LogToFile to 1 to capture detailed logs for analysis. The logs can include the following errors:
-
RevocationStatusUnknown
-
The revocation function was unable to check the revocation status for the certificate.
-
The revocation function was unable to check revocation because the revocation server was offline.
The VDA Upgrade Agent relies on Windows system calls to validate certificates and perform revocation checks. The errors above indicate that the agent is unable to establish a connection to the CRL or OCSP URLs.
The Windows CryptoAPI does not currently support proxy settings. Review the VDAs with Proxy configurations section for configuring your VDA proxies to facilitate outbound CRL calls.