VDA upgrades (preview)
Introduction
Previously, upgrading VDAs required full manual intervention. Version 2503 simplifies VDA upgrades for DaaS deployments by introducing the VDA Upgrade Agent. Upgrades from version 2503 onward can later be performed directly from a shared or local file path.
The VDA Upgrade Agent ctxvua is responsible for communicating with the VDA Upgrade Service and performing the following functions:
- Scheduled checks: The VDA Upgrade Agent queries the VDA Upgrade Service for scheduled upgrade information every 15 minutes.
- Automated upgrades: Upon receiving upgrade instructions, the VDA Upgrade Agent automatically upgrades the VDA.
- Status reporting: The VDA Upgrade Agent reports the upgrade result (success or failure) back to the VDA Upgrade Service.
To learn more about the VDA Upgrade service, see Tech Brief: Citrix VDA Upgrade service. There, you can find an overview of the service, detailed information on how it works, and other useful resources.
Considerations
-
Linux VDAs are upgraded using underlying package management commands (like rpm or apt), mirroring the manual upgrade process, configuration files are automatically handled during the command-line upgrade.
-
Unlike Windows, the Linux VDA includes a built-in VDA Upgrade Agent. This simplifies the upgrade process as the agent is already present. The VDA Upgrade Agent’s version is tied to the VDA version.
-
By default, the VDA Upgrade Agent is disabled. To enable the agent, run the following commands:
/opt/Citrix/VDA/bin/ctxreg create -k "HKLM\Software\Citrix\UpdateServices\UpdateAgent" -t "REG_DWORD" -v "fEnabled" -d "0x00000001" --force systemctl start ctxvua.service <!--NeedCopy--> -
The VDA Upgrade Agent service (ctxvua) is disabled by default. You can use systemctl to enable and start this service.
-
As a best practice, we recommend that you test VDA upgrades thoroughly before moving into production.
-
Unlike Windows, Linux VDA upgrades are only supported from a file path. This means you cannot directly use Azure CDN URLs or other online repositories. You must manage the VDA packages yourself. This applies to both major and minor version upgrades.
-
Ignore “Latest VDA Version” and “Upgrade State” in the VDA Upgrade Service. Only the “VDA Upgrade State” is relevant for Linux.
-
The file path for the VDA package can be local to the VDA machine or a shared location (for example, a network share mounted on the VDA). The system is not designed to download the package automatically. You must provide the complete package file.
-
Specify the path in the Windows UNC path format (starting with \\) to pass the path validation when using Studio or Citrix DaaS Remote PowerShell SDK. For example, /mnt/pkg\/<package-name> must be entered as \\mnt\pkg\<package-name>.
-
The distinction between “server” and “workstation” VDAs does not apply to Linux. You can use either option in Studio or PowerShell without affecting the upgrade.
-
Downgrading VDAs is not supported.
Prerequisites
- Control plane: Citrix DaaS
-
VDA version: 2503 or later
Note:
We recommend using the latest CR VDA.
- The VDAs must have the VDA Upgrade Agent installed and the service must be running.
- You have permissions to upgrade VDAs.
- The VDA upgrade is configured with the proper CR or LTSR track in Studio.
- The VDAs are not in use. (Users must sign off from them.)
- The VDAs are not in maintenance mode. (A VDA can be put into maintenance mode by an administrator. A VDA can also be automatically put into maintenance mode if it has exceeded the maximum allowed registration attempts.)
- The VDAs must belong to a delivery group and be registered with DaaS.
- The destination VDA supports the operating system of the current VDA.
Upgrade VDAs using Studio
General workflow
A general workflow to upgrade VDAs using Studio is as follows:
-
Enable VDA upgrade for a catalog.
- You can enable VDA upgrade when creating a catalog.
- You can enable VDA upgrade when editing a catalog.
-
Upgrade VDAs on a per-catalog basis. Per-machine VDA upgrades are not currently available. For more information, see Configure auto-upgrade for VDAs.
Note:
When scheduling VDA upgrades for a catalog, all machines in the catalog are included in the upgrade scope. Therefore, we recommend backing up those machines before initiating the upgrade.
-
The VDA upgrade process does not support upgrading additional components or using features like restore. Skip these two steps.
-
Configure the scheduling options, including the upgrade time and the upgrade failure threshold. The failure threshold likely determines how many failed upgrades are tolerated before the process is stopped or alerts are triggered.
-
Select “Use local file share” for the VDA installer location. Provide the path in the Windows UNC format (for example, \\server\share\path).
-
The “Force logoff sessions” option controls how user sessions are handled during VDA upgrades. While the Studio UI only allows logging off disconnected sessions, PowerShell can log off all sessions (connected and disconnected). Logoff is not immediate. The VDA Upgrade Service initiates the logoff after the VDA Upgrade Agent attempts to query the upgrade schedule and finds disconnected sessions. The agent then waits 15 minutes before retrying the query.
Upgrade VDAs using PowerShell
You can configure VDA upgrades using the Remote PowerShell SDK on Windows. For more information about the Remote PowerShell SDK, see Citrix DaaS Remote PowerShell SDK.
The following are the PowerShell cmdlets:
-
Get-VusCatalog
Use this cmdlet to get details of a catalog such as Name, Uid, Uuid, UpgradeState (Available, UpToDate, Scheduled, Unknown), Upgrade scheduled, and StateId (status of Upgrade scheduled).
-
Get-VusMachine
Use this cmdlet to get details of a machine such as MachineName, Uid, Uuid, UpgradeState (Available, UpToDate, Scheduled, Unknown), and StateId (status of Upgrade scheduled).
-
Get-VusComponentVersion
Use this cmdlet to check if VDAs have reported the component versions. Use the MachineId to filter the VDAs. MachineId is the UUID from Get-BrokerMachine.
-
New-VusMachineUpgrade
Use this cmdlet to configure VDA upgrades at the machine level.
-
New-VusCatalogSchedule
Use this cmdlet to schedule VDA upgrades at the machine catalog level.
Example:
Get-BrokerMachine -DNSName 'u22-test*'
New-VusCatalogSchedule -CatalogName "test-catalog" -UpgradeNow -DurationInHours 2 -LogoffOption ActiveAndDisconnectedSessions -VdaServerPackageUri "\\root\xendesktopvda_24.11.0.1-1.ubuntu22.04_amd64.deb"
Get-VusComponent -CatalogName 'test-catalog'
Get-VusCatalog -Name 'test-catalog'
<!--NeedCopy-->
Troubleshooting
The core of the upgrade process revolves around the VDA Upgrade Agent service (ctxvua). It acts as the intermediary, communicating with the VDA Upgrade Service and executing the /opt/Citrix/VDA/sbin/update_helper.sh script for OS-related operations. During the upgrade, information about the process is stored in the registry.
Registry
| Use the command **/opt/Citrix/VDA/bin/ctxreg dump | grep -i UpdateAgent** to examine the registry settings related to the VDA Upgrade Agent. This can reveal configuration issues or problems with the upgrade process itself. |
- Check Configuration: The configuration file for the ctxvua service is located at /etc/xdl/updateagent.conf. Reviewing this file can help identify misconfigurations.
Logs
The following log files are crucial for troubleshooting:
-
/var/log/xdl/vua.log: Log file for the ctxvua service. This is the primary log to check for issues related to the upgrade agent’s operation. The configuration file for the ctxvua service is located at /etc/xdl/updateagent.conf. Reviewing this file can help identify misconfigurations.
-
/var/log/xdl/update_helper.log: Log file for the update_helper.sh script. This log is essential for diagnosing problems related to OS-level tasks during the upgrade.
Common issues
This section addresses common issues encountered during VDA upgrades, specifically focusing on disabled options in Studio and the “Upgrade Unknown” state.
Common issue 1: Disabled upgrade options
Symptom: The options to “Set Upgrade Type” and “Upgrade VDAs” are disabled (grayed out) in Studio for a given catalog.
Solution: Check whether the VDA Upgrade Service is supported for the catalog type you are using. If it’s not, you are unable to use these automated upgrade features and need to manage upgrades manually.
Common issue 2: “Upgrade Unknown” state
Symptom: After enabling the VDA Upgrade Service for a machine catalog, the “Upgrade State” remains “Unknown” instead of changing to “Available” or “UpToDate” as expected. “Upgrade Unknown” is a transient state. It should eventually update to either “Available” or “UpToDate”.
Troubleshooting steps for “Upgrade Unknown”:
-
Verify that the VDA Upgrade Agent is reporting versions.
-
Step 1a: Get the machine’s UUID:
Get-BrokerMachine -DNSName '<hostname>' <!--NeedCopy--> -
Step 1b: Check the component version reported by the agent:
Get-VusComponentVersion -MachineId "<UUID>" <!--NeedCopy-->If the Get-VusComponentVersion command returns blank, it means that the VDA Upgrade Agent hasn’t reported its version. This could indicate that the VDA is “hard registered” (check both the machine catalog and delivery group settings). It also indicates that the VDA Upgrade Agent might not be installed or running on the target VDA.
-
-
Verify the VDA Upgrade Service synchronization.
Step 2a: Check whether the VDA Upgrade Service has synced the machine from the Broker database:
``` Get-VusEntityUnit -EntityUUID "" <!--NeedCopy--> ```Replace
""with the actual EntityUUID if known, or run without to get all. If you observe that this is blank, it can indicate that the machine has not synced with the VDA Upgrade Service server.Step 2b: If the machine has not synced, allow some time for the VDA Upgrade Service to sync. Then, confirm that the “Upgrade Type” has been set.