Product Documentation

Updating vDisks

It is often necessary to update an existing vDisk so that the image contains the most current software and patches. Each time the vDisk is to be updated, a new version of that vDisk is created (VHDX file) to capture the changes without changing the base vDisk image.

Updating a vDisk involves the following:

  • Create a new version of the vDisk, manually or automatically.
  • Boot the newly created version from a device (Maintenance device or Update device), make and save any changes to the vDisk, then shut-down the device.
  • Promote the new version to Production.

The following illustrates the general promotion of a vDisk update:

Image of the vDisk update

The availability of the updated version depends on the current promotion of that version (Maintenance, Test, or Production), and the type of device attempting to access it (Maintenance Device, Update Device, Test Device, or Production Device).

If updating a device that uses a personal vDisk image, ensure compatibility in your production environment using this procedure:

Note: Updating images for devices that use a personal vDisk, must be done on a virtual machine that does not have a personal vDisk attached. Otherwise, updates are saved to the personal vDisk image rather than the virtual machine image.

  1. Create a new maintenance version of the vDisk.
  2. Make any necessary updates to the maintenance version.
  3. Promote the new maintenance version to test.
  4. Boot the PvD test device, and then verify updates were made.
  5. Promote the test version to production.

Update Scenarios

The following vDisk update scenarios are supported:

  • Manual Update – An administrator may choose to update a vDisk manually by creating a new version of that vDisk, and then using a Maintenance device to capture updates to that version. Manual updates are initiated by selecting the New button on the vDisk Versions dialog. The Access column on the vDisk Versioning dialog displays that the newly created version is currently under maintenance. While under maintenance, this version can only be accessed and updated by a single Maintenance device. Multiple Maintenance devices can be assigned to a vDisk. However, only one device can boot and access that version of the vDisk at any given time. During that time that Maintenance device will have exclusive read/write access.
  • Automated Update – Creating automated updates saves administration time and physical resources. Updates are initiated on-demand or from a schedule and are configured using vDisk Update Management. If updating automatically, the Access column on the vDisk Versioning dialog displays that the newly created version is currently under maintenance. While under maintenance, this version can only be accessed and updated by the one Update device to which it is assigned (only one Update Device exists per vDisk). For details, refer to Automating vDisk Updates.


    vDisk Update Management is intended for use with Standard Image Mode vDisks only. Private Image Mode vDisks can be updated using normal software distribution tool procedures. Attempting to register a Private Image Mode vDisk for vDisk Update Management, or switching a vdisk that is already registered, will cause errors to occur.

  • Merge – Merging VHDX differencing disk files can save disk space and increase performance, depending on the merge option selected. A merge update is initiated manually by selecting the Merge button on the vDisk Versions dialog, or automatically when the maximum vDisk versions count is reached.

VHDX chain of differencing disks

Versioning simplifies vDisk update and management tasks, providing a more flexible and robust approach to managing vDisks.

A vDisk consists of a VHDX base image file, any associated side-car files, and if applicable, a chain of referenced VHDX differencing disks. Differencing disks are created to capture the changes made to the base disk image, leaving the original base disk unchanged. Each differencing disk that is associated with a base disk represents a different version.

The following illustrates the file naming convention used and the relationship between a a base disk and all versions referencing that base disk.

VHDX Chain


vDisk versions are created and managed using the vDisk Versions dialog and by performing common vDisk versioning tasks.

Each time a vDisk is put into Maintenance Mode a new version of the VHDX differencing disk is created and the file name is numerically incremented, as captured in the table that follows.

  VHDX Filename Properties Filename Lock File Filename
Base Image win7dev.vhdx win7dev.pvp win7dev.lok
Version 1 win7dev.1.vhdx win7dev.1.pvp win7dev.1.lok
Version 2 win7dev.2.vhdx win7dev.2.pvp win7dev.2.lok
Version N win7dev.N.vhdx win7dev.N.pvp win7dev.N.lok

Manually updating a vDisk image

The vDisk Versions dialog allows you to manually create a new version of the vDisk’s base image.


To automate an update process, configure for vDisk Update Management (refer to Automating vDisk Updates).

This procedure requires that:

  • A Maintenance device has been assigned to the vDisk being updated.
  • No version of this vDisk is currently under maintenance.


Updating images for devices that use a personal vDisk, must be done on a virtual machine that does not have a personal vDisk attached. Otherwise, updates are saved to the personal vDisk image rather than the virtual machine image.

To create a new version

  1. In the Console, right-click on a vDisk to version within a device collection or vDisk pool, then select Versions from the context menu. The vDisk Versions dialog appears.


    Verify that the vDisk is currently not in Private Image mode.

  2. Click New. The new version displays in the dialog with Access set to Maintenance and the update Type method set to Manual.
  3. Boot the vDisk from a Maintenance device, install or remove applications, add patches, and complete any other necessary updates, then shutdown the Maintenance device. Optionally, test that changes were made successfully.


    If booting a Test or Maintenance device, a boot menu displays that allows the user to select from which vDisk, or version of that vDisk, to boot from unless the device is a PvD Test device.

  4. Right-click on the vDisk, then select the Promote… menu option from the context menu that appears (for more details on promoting versions refer to Promoting Updated Versions.
  5. Select to promote this maintenance version into test or directly into production. If Production is selected, set the availability of this version in production to be either immediate or scheduled.
  6. Click OK to promote this version and end maintenance.

Merging VHDX differencing disks

Merging VHDX differencing disk files can save disk space and increase performance, depending on the merge method selected.

Once a virtual disk reaches five versions, Citrix recommends merging the versions either to a new base image or to a consolidated differencing disk.

Merge methods include:

  • Merging to a new base image
  • Merging to a consolidated differencing disk


A merged virtual disk only ocurs when a Maintenance version is not defined, or when it is in Private Image mode. A merged virtual disk starts from the top of the chain down to the base disk image. A starting disk cannot be specified for the merged virtual disk.

Merging to a New Base Image

A full merge to a new base image combines a chain of differencing disks and base image disks into a new single base disk. This new disk is the next version in the chain, which is given the file extension of .VHDX. This method allows for the fastest disk access to the base image and is recommended when performance is more important than disk space (a new base disk is created for every merge performed).


After performing a merged base operation on a vDisk that is utilizing the VHDX file format, the resultant merged base VHDX file may be smaller than the original base VHDX file. This behavior can occur in situations where files are deleted in a particular vDisk version, and these files are no longer available in the merged base VHDX. For more information, refer to the Citrix Knowledge Center.

Merging to a Consolidated Differencing Disk

A partial merge combines a chain of VHDX differencing disks up to, but not including, the base disk into a new differencing disk. The new differencing disk has the same parent base disk image and is given the extension .avhdx. This method consumes less disk space than the full merge and the merge process is quicker than performing a full merge.

An automatic consolidation of differencing disks can be configured from the Farm Properties dialog’s virtual disk Version tab. On this tab, select a maximum virtual disk number. When that number is reached, a merge is automatically performed and the availability of that virtual disk depends on the mode selected on the tab (Production, Maintenance, or Test).


A consolidated differencing disk merge is recommended when disk storage is limited or when the bandwidth between remote locations is limited, which makes copying large images impractical.

Merging Differencing Disks

  1. Right-click on a virtual disk in the Console, then select the Versions menu option. The virtual disk Versions dialog appears.
  2. Click the Merge button. The Merge dialog appears.
  3. Select to perform a Merged Updates or Merged Base merge.
    • To merge all differencing disks to a single differencing disk (not to the base disk image), select the Merged Updates option.
    • To fully merge all differencing disks into a new base disk, select the Merged Base option.
  4. Select the access mode (Production, Maintenance, or Test) for this version after the merge completes. If an access mode is not selected, the virtual disk mode defaults to automatic range, specified in the Farm Properties virtual disk Version tab.
  5. Click OK to begin the merge process.

The time it takes to complete the merge process varies based on the merge method selected and the number of differencing disks to merge. After the merge successfully completes, the new version displays in the virtual disk Versions dialog. The Type column displays either Merge Base if a full merge was selected, or Merge if a partial merge was selected.

Promoting updated versions

An updated version of the vDisk is not available to Production devices until it is promoted to Production. The update promotion stages include:

  • Maintenance
  • Test
  • Production

Each time a new version is created, the Access setting is automatically set to Maintenance to allow maintenance devices to make updates (read/write). After updates are complete, this version can be promoted from Maintenance to Test (read-only) to allow for testing by test devices, or directly to Production, for use by all target devices.

After completing an update using the manual method, the new version can be promoted to Test or Production from the vDisk Version dialog’s Promote button. If Production is selected, a release date and time can be set, or the default (Immediate) can be accepted.

After completing an update using the automated update method, vDisk Update Management, the new version is promoted according to the Post Update setting selected when the Update Task Wizard is run. After the automatic update completes, promotion can also be set using the vDisk Version dialog’s Promote button.

If issues exist, the new version can be reverted back from Test to Maintenance (if no active sessions exist), or from Production to either Test or Maintenance (any booted device must be shut down prior to reverting).

In order for Production devices to access the new version after it is promoted to Production, the following also applies:

  • Access setting must be either Default or Override.
  • If the update was scheduled for release, the date and time must be reached.
  • The updated version must be available to all servers in the site.
  • Boot production devices from version is set to Newest released (status is Default) on the vDisk Versions dialog.


If Access displays as blank, this version is considered released to production but is not the version currently selected from which devices should boot.

Updating vDisks on target devices

This document describes how to change a vDisk on multiple target devices without having to manually reconfigure them. It provides some general information about the process, then sets out a step-by-step procedure.

Setting vDisk Class and Type Properties

For an automatic update to take place, the Class of the target device and vDisk must match. For a newer vDisk to replace an older vDisk within a target device, the vDisk Class and Type of both vDisks must match. Because multiple, duplicate vDisk instances can exist within your implementation, and those vDisks can be assigned to one or more target devices (in the case of Provisioning Server Least Busy and First Available boot behaviors), you must further qualify the old vDisk that will be replaced by the new vDisk. This is the reason for using the Type property of the vDisk. If you want to use the Automatic Disk Image Update feature, you should never assign more than one vDisk with the same Type from the same Provisioning Server to the same target device.

Scheduling vDisk updates

To schedule when automatic updates can be applied, use the Apply vDisk updates as soon as they are detected by the server or Schedule the next vDisk update to occur on radio buttons on the Auto Update tab of the vDisk. If you select Schedule the next vDisk update to occur on, you must specify the current date or a later date, otherwise the vDisk will not be updated.

Timed update of vDisks

You can set a timer to update vDisks. This means that the vDisk will be assigned to all the devices with a matching Class at a specified time, for example when devices are less active.

To do this, on one of the servers from each site create a Windows timer that calls the PowerShell Mcli-Run ApplyAutoUpdate command or the Mcli Run ApplyAutoUpdate command (see the PowerShell Administrator’s Guide or the MCLI Programmer’s Guide for details). The command scans the site and updates all eligible vDisks that are configured to be updated. Because the command updates only those vDisks that need to be updated, the timer can execute every day and the updates are automatically made whenever new versions of vDisks are added.

Automatically adding a replacement vDisk

To automatically add a replacement vDisk to a site, place it in the store directory of the vDisk it replaces. When the update process is done, each store for the site is scanned for vDisks that are not defined in the site. If a vDisk is found that has the same Class and Type as an existing vDisk in the store directory, and its major, minor and build number is higher than the existing vDisk, it is automatically added to the site and assigned to target devices with matching Class.

The replacement vDisk must include all versions since and including the last merged base, or if no merged base exists, the base. All the VHDX, AVHDX, and the PVP files for the versions included need to be placed into the store directory.

If the replacement vDisk has multiple versions, the manifest (XML) file needs to be included with the vDisk. To create the manifest file, perform a vDisk Export. To reduce the number of files that need to be delivered, delete obsolete versions in the vDisk Versions dialog before performing the vDisk Export.

To automatically update a vDisk

  1. For the original vDisk, select the Auto Update tab, then set the following vDisk properties:

    a. Enable automatic updates.

    b. Select whether the update will be applied immediately or on a scheduled date when the check for updates is done or the Run ApplyAutoUpdate command is run.

    c. Enter a Class and Type for the vDisk.

    d. Enter a Major, Minor and Build number for the vDisk.


    The Serial Number field is set to a random Globally Unique Identifier (GUID) when the vDisk is created. It is for information only and you can edit it. It is not used for processing the Automatic Update.

  2. For target devices that use the vDisk to be updated, select the General tab, then in the Target Devices Properties set the Class equal to the Class value of the original vDisk.

  3. Ensure that the replacement vDisk is in the same store as the original vDisk.

  4. For the replacement disk, select the Auto Update tab, then set the following vDisk properties:

    a. Only enable automatic updates if this vDisk may later be replaced with another vDisk.

    b. If automatic updates are enabled, select whether the update will be applied immediately or on a scheduled date when the check for updates is done or the Run ApplyAutoUpdate command is run.

    c. Enter the same Class and Type that you entered for the original vDisk.

    d. Enter a Major, Minor and Build number for the vDisk that is higher than the original vDisk.

  5. If the vDisk update needs to be done in other farm sites, you can deliver and place the replacement vDisk setup described in step 4 in the same store as the original vDisk of the other farm site. This is described earlier in this document in ‘Automatically adding a replacement vDisk’.

  6. Configure the update check. This will update any vDisks found with a higher Major, Minor, and Build number that are eligible to be updated. You can do this in either of the following ways:

    • Right-click on the vDisk Pool, select the Check for Automatic Updates menu option, then click OK on the confirmation dialog.


    • Set a timer as described earlier in this document.