Deploying virtual desktops to VMs using the Citrix Virtual Apps and Desktops Setup Wizard

The Citrix Virtual Apps and Desktops Setup Wizard (XDSW) helps with deploying virtual desktops to virtual machines (VMs) as well as to devices that use personal vDisks.


The Citrix Provisioning server must have direct access to the storage device to facilitate communication. The provisioning user must have read\write access to the storage device to ensure successful provisioning with the HDD BDM.

The wizard:

  • Creates VMs on a Citrix Virtual Apps and Desktops-hosted hypervisor using an existing machine template:
    • XenServer
    • ESX via V-Center
    • Hyper-V using SCVMM. When provisioning to an SCVMM server, the wizard automatically changes the network configuration of both the first legacy NIC and the second synthetic NIC for Gen 1 VMs. Refer to the SCVMM section for more information.
    • Nutanix Acropolis (from snapshots). See Nutanix Acropolis requirements for more information.
  • Creates Citrix Provisioning target devices within a new or existing provisioning device collection matching the Citrix Virtual Apps and Desktops catalog name.
  • Assigns a Standard Image vDisk to VMs within the device collection.
  • Adds the target to the selected Active Directory OU.
  • Adds virtual desktops to a Citrix Virtual Apps and Desktops catalog.

Important considerations

Consider the following when using the Citrix Virtual Apps and Desktops Setup Wizard:

  • For Citrix Virtual Apps and Desktops SetUp Wizard provisioned Gen 2 VMs, the BDM partition is FAT formatted with a drive letter. As a result, Windows in a Citrix Provisioning private image should be aware of the new partition. For example, an RDS provisioning image using a write cache disk and BDM partition should see 2 partitions in private image mode.
  • When using the Linux streaming feature, consider that a new step was added to the Citrix Virtual Apps and Desktops Setup Wizard. Add the SOAP SSL certificate to ensure that the Linux target can image the vDisk through the SOAP server. For details, see Installation.
  • When using the Citrix Provisioning Setup Wizard to create VMs on a XenServer host while specifying 1 VCPU, the VM is created with 1 VCPU and a topology of 2 cores per socket. Creating VMs in this fashion prevents the VM from booting, while displaying the following error message in XenCenter: “The value ‘VCPU_max must be a multiple of this field’ is invalid for field ‘platforms:cores-per-socket’. As a result, XenCenter fails to boot the VM because the topology and VCPU configuration are incompatible.
  • The Citrix Virtual Apps and Desktop Setup Wizard creates targets then boots them to format the cache drive. This process occurs quickly. Sometimes, a VDA reaches a state where it fails to shut down correctly because it’s initializing while the Citrix Provisioning Device Service simultaneously finishes formatting the cache drive then shuts down the target. To resolve this issue, in the vDisk registry key, HKEY_LOCAL_MACHINE\SOFTWARE\Citrix\CitrixProvisioning, create a DWORD called “RebootDelaySec”. Set an arbitrary value, delay-to-shutdown, in seconds using a decimal value.
  • When using the Citrix Virtual Apps and Desktops Setup Wizard, the default VDA level is 7_9 even though there is a 7_20 VDA level. This behavior is the same in the Machine Creation Wizard in Studio. Also, the VDA level 7_20 in Citrix Virtual Apps and Desktops Setup Wizard is the same as the VDA level in Studio version 1811.

ESX permissions

For ESX 5.5, the minimum permissions include the following:

  • Datastore Permissions
    • Allocate space
    • Browse datastore
    • Low level file operations
  • Network Permissions
    • Assign network
  • Resource Permissions
    • Assign virtual machine to resource pool
  • System Permissions - These permissions are automatically added when you create a role in vCenter.
    • Anonymous
    • Read
    • View
  • Task Permissions
    • Create Task
  • Virtual Machine/Configuration Permissions
    • Add existing disk
    • Add new disk
    • Advanced
    • Change CPU count
    • Change resource
    • Memory
    • Modify device settings
    • Remove disk
    • Settings
  • Virtual Machine/Interaction
    • Power Off
    • Power On
    • Reset
    • Suspend
  • Virtual Machine/Inventory
    • Create New
    • Create from existing
    • Remove
    • Register
  • Virtual Machine/Provisioning
    • Clone virtual machine
    • Clone template
    • Allow disk access
    • Allow virtual machine download
    • Allow virtual machine files upload
    • Deploy template
  • Global
    • Manager custom attributes
    • Set custom attribute


Other previously supported versions of ESX require the same permissions to work with Provisioning Services 7.x.

Write cache considerations

The Citrix Virtual Apps and Desktops Set Up Wizard discards any hard disks that are attached to a template. This process minimizes provisioning time.

The wizard provisions diskless VMs if the vDisk is in Standard Image mode and cache is set as cache on the server. If the cache is server-side, Citrix Provisioning does not automatically boot the provisioned VMs.

The wizard provisions VMs with write cache drives (the default size is 6 GB and the default type is dynamic). If the vDisk is in Standard Image mode and cache is set as cache on the local hard disk. To format the write cache drive, the wizard automatically boots the VMs in Standard Image mode with the cache on the server. After formatting completes, VMs are automatically shut down, then Citrix Virtual Apps and Desktops can boot the VMs as necessary.

If the write cache is stored on hypervisor local storage, configuring deployment through the Citrix Virtual Apps and Desktops Setup wizard varies depending on your hypervisor:

  • On XenServer, VMs are spread across multiple local storage resources. Create the template without storage (network boot).
  • On Hyper-V, VMs are spread across multiple local storage resources. The configuration file follows the write cache, but it is a small file.
  • On ESX, you cannot use the Citrix Virtual Apps and Desktops Setup Wizard to provision VMs if you are using hypervisor local storage.


When specifying names associated with storage devices, do not use a comma (,). Names associated with storage devices are retained by Citrix Virtual Apps and Desktops and separated by commas. For example, Storage 1, Storage 2, Storage 3. If a storage name includes a comma (for instance, ‘Storage1,East’) Citrix Provisioning erroneously recognizes this format as two separate storage devices.

Virtual disk types

VMs provisioned through the Citrix Virtual Apps and Desktops Setup Wizard have new disks created and attached for local provisioning write cache use. The default virtual disk types created are:

  • “Fixed” or “dynamic” depending upon the storage repository used in XenServer
  • “Dynamic” for SCVMM 2012 SP1
  • “Fixed” for SCVMM 2012
  • “Thin-provisioned” for ESX

There is a registry key to override the default types of write cache disks created by provisioning deployments on SCVMM and ESX. This registry key does not apply to XenServer. To force “fixed” (or “eager-zeroed thick” for ESX):



Setting this same key to “false” overrides to the dynamic setting. Remove the key to return to default behavior.

Run the wizard

Run the wizard directly from the Citrix Provisioning console or from a remote console.

In the console, the Citrix Virtual Apps and Desktops Setup Wizard cannot be used to connect twice in a row. Once the Wizard tries to connect to the Citrix Cloud Delivery controller once, regardless of connection success or failure, you must exit and close the console.


If you are using ISO BDM boot, ensure that the template has the BDM ISO attached to it. The PXE boot option should be configured as the Boot mode in the Virtual Machines page of the Citrix Virtual Apps and Desktops Setup Wizard.

  1. Right-click on any Site icon in the Console tree panel, then select the Citrix Virtual Apps and Desktops Setup Wizard…menu option. The Citrix Virtual Apps and Desktops Setup Wizard appears.

  2. Click Next to begin setup.

  3. On the Citrix Virtual Apps and Desktops Host page, enter the location of the Citrix Virtual Apps and Desktops Host address to connect to and to configure. The most recently used Citrix Virtual Apps and Desktops Controller (name or IP) is cached in the registry of the local machine running this instance of the Console.

  4. Select a XenDesktop host. If you choose a cluster, machines are evenly distributed across the hosts cluster.


    XenServer 5.5 Update 2 virtualization settings do not display. These settings are added in Citrix Virtual Apps and Desktops as host connections using the Manually create VMs option. As a result, you cannot specify a network or storage location for them, therefore it is not listed in the Citrix Virtual Apps and Desktops Setup Wizard.

  5. Supply the host credentials (Username and Password).

  6. From the list of available templates, select the template to use for the host you chose. If using a previous version of the VDA or if the template is built using Windows Vista, select the check box. Valid templates must have a dynamic MAC address or a static address with a value (00:00:00:00:00:00 is not a valid MAC address).

  7. If there is more than one network available for the Virtualizations Settings, a page displays so you can select the appropriate network.

  8. Select a single Standard Image mode vDisk to assign to the collection of VMs.

  9. Create a catalog or use an existing catalog from a previous release (Vista or Windows 7 with VDA 5.6). The options available depend on which catalog option you select:

    • If you chose to create a catalog, provide a name and description for that catalog. Appropriate machine types include:
      • Windows Client Operating System – best for delivering personalized desktops to users, or delivering applications to users from desktop operating systems. Provides the option to save a user’s changes to a Personal vDisk.
      • Windows Server Operating System – best for delivering hosted shared desktops for a large-scale deployment of standardized machines or applications, or both.
      • The vGPU option is only supported on desktop operating systems.
    • If you select an existing catalog using the drop-down menu, that catalog’s description, machine type, assignment type, and user data (if applicable) display.
  10. Select VM preferences. Preferences vary depending on the machine OS type and if assigned user changes are discarded after the session ends.

    1. For Windows Client or Windows Server machines that are randomly assigned to users who do not require a personal vDisk:
      • Number of VMs to create (default is 1)
      • vCPUs (default is based on the previously selected template)
      • If the template has dynamic memory configured, two extra configuration settings are required (minimum and maximum memory).
      • Local write cache disk (default is 6 GB)
      • Boot mode. PXE boot (requires a running PXE service). BDM disk (creates a partition for the Boot Device Manager file).
    2. For Windows Client machines that are either randomly assigned or statically assigned to users who can save their changes to their personal vDisk, in addition to the preferences listed above, the following preferences display:
      • Personal vDisk size (default is 10 GB). When booting a target device from a personal vDisk, the vDisk’s OS partition, C:\ by default, only shows the amount of space allocated to the personal vDisk. It does not display the true size of the personal vDisk.
      • Personal vDisk drive letter (default is P). The drive letter the target device uses for the personal vDisk. The range allowed is between E: to U: and W: to Z:.
  11. Choose the appropriate method for adding Active Directory computer accounts:

    • Create accounts
    • Import existing accounts

    The page that displays depends on which Active Directory method you select.

  12. To create new accounts: Delegate rights to the provisioning console user to allow Active Directory account creation or modification to manage computer account passwords.

    • Select the appropriate domain from the Domain drop-down box, then select from the OUs listed for that domain. The domain and OU default to rights of the current user.
    • Select the machine-naming option from the Account naming scheme drop-down text box. Enter a valid naming scheme consisting of at least one hash symbol (#) that is 15 characters or less. Also, select a number/character fill option that dynamically replaces the hash symbols in the specified naming scheme, incrementing by one for each VM as they are created.
  13. To Import existing accounts:

    • Click Browse to browse for the appropriate OU to import, or click Import to import an existing .csv file in the following format:



      The Required count displays the number of VMs previously specified. The Added count displays the number of entries in the list. If you import machine account names that exist in any of the following locations, they are not valid. They do not display in the list. Citrix Virtual Apps and Desktops (as a machine), Citrix Provisioning (as a device), and on the hypervisor (as a VM). If the AD structure contains many objects or containers, or if you are importing many machine accounts, the import may take a while. It must validate that each imported account does not exist in Citrix Provisioning, Citrix Virtual Apps and Desktops, and the destination hypervisor. If so, you should receive feedback in the form of an hour glass cursor while the import completes.

  14. Review all configuration settings. After confirming, the following actions take place one at a time across all hosts until configurations are complete:

    • If applicable, create a Citrix Virtual Apps and Desktops catalog
    • Create VMs on a host’s hypervisor using the machine template
    • Create BDM partitions, if specified
    • If using a Streamed with personal vDisk Catalog, create a personal vDisk, then attach the personal vDisk to the VM
    • Create a write cache disk of the specified size
    • Create Citrix Provisioning target devices then assign the selected vDisk to those devices
    • Add the target devices to the selected provisioning collection
    • Add the VMs to the Citrix Virtual Apps and Desktops catalog
    • Boot each VM to format the newly created write cache disk

If you cancel during the configuration, you must manually remove the following:

  • Citrix Virtual Apps and Desktops machines from the assigned catalog
  • Active Directory computer accounts that were created.
  • Newly created Citrix Virtual Apps and Desktops catalogs.
  • Citrix Provisioning target devices created in the selected device collection.
  • VMs created on any of the selected host hypervisors.

vDisks can be updated and reassigned to a target device that uses personal vDisks. However, the base disk must be of the same operating system and must have the machine SID. To update and reassign a vDisk, copy the target device’s currently assigned base vDisk image. Update the image to include new Citrix Provisioning software and drivers. Reassign the updated vDisk to the target device. To reassign the vDisk, use the vDisk Properties Assign vDisk dialog on the console.

Nutanix Acropolis requirements

The following are required when using Citrix Provisioning with Nutanix Acropolis:

  • An installed Nutanix Acropolis hypervisor plugin for Citrix Provisioning. Download this plugin from the Nutanix support site. Refer to the Nutanix documentation site for installation information.
  • A Citrix Virtual Apps and Desktops host connection to AHV.
  • Nutanix Acropolis platform version 5.1.1 or greater.


Unique to AHV provisioning is the requirement to choose a container.

Important considerations when using Nutanix Acropolis hypervisors

When using Nutanix, consider the following:

  • Do not delete the NIC of a provisioned VM and then readd them.
  • Linux VMs, BDM partitions, and UEFI are not supported.
  • Only the Citrix Virtual Apps and Desktops Setup Wizard is supported, not the Streamed VM Wizard.
  • Acropolis hypervisors use snapshots and not templates for VMs.
  • It’s considered best practice that a snapshot does not have an attached hard disk because the Nutanix Acropolis hypervisor does not remove the hard disk during provisioning.
  • To deploy machines that boot from BDM ISOs, the ISO should be mounted in the snapshot. The provisioned VMs are set to use PXE boot and must be manually changed to boot from virtual optical drive.
  • For PXE booting, you must use a command line option to set the VM boot order to network before imaging.
  • When manually adding a Nutanix AHV host using the Virtual Host Connection Wizard, not enough information exists to effectively communicate with the Nutanix AHV hosting unit. This information, provided by the Citrix Virtual Apps and Desktops DDC, is not shared with the Virtual Host Connection Wizard. As a result, this information is not used to verify credentials. Therefore, the Verify Connection button in the Virtual Host Connection Wizard is disabled for Nutanix AHV hosts.

Image of the virtual host connection wizard credentials dialog box


For information related to the configuration and use of Nutanix Acropolis hypervisors, see the Nutanix documentation portal.

Implementing UEFI guest VMs for Nutanix AHV hosts

Citrix Provisioning allows you to implement a UEFI guest VM for Nutanix AHV hosts. The following prerequisites exist:

  • The Citrix Virtual Apps and Desktops DDC are installed, along with the Nutanix plug-in.
  • The Nutanix plug-in is installed in the provisioning server and provisioning console.


The VM should be set to UEFI before installing the OS.

To implement a UEFI guest VM for Nutanix AHV:

  1. Create a master VM.
  2. SSH into Nutanix Acropolis and run the following command: **acli vm.update uefi_boot=True**.
  3. Mount the Windows and virtual ISOs and install the OS.
  4. Install all Windows updates on the OS.
  5. Join the OS to Active Directory.
  6. Install Citrix Provisioning on the target device.
  7. Run the Citrix Provisioning Imaging Wizard to create the target device record, vDisk, and other elements. Choose No to shut down the target device, rather than rebooting it at the conclusion.
  8. Set the VM to boot from the ISO boot and PXE boot the VM. Select one of the following boot options:
    • ISO boot – mount a BDM ISO created from the provisioning console. SSH into Nutanix Acropolis and run the following command: acli vm.update_boot_device VM NAME disk_addr=CDROM BUS. For example, acli vm.update_boot_device testVM disk_addr=ide.0; this example assumes that the CDROM is bus IDE 0.
    • Network boot - SSH into Nutanix Acropolis and run the following command: **acli vm.update_boot_device mac_addr=, acli vm.update_boot_device testVM mac_addr=52:54:00:2c:ff:03**.
  9. Start the VM and log into Windows to start the second stage of Imaging Wizard, imaging.
  10. Create a VM. As in the master VM, repeat steps 2 and 7.
  11. In the provisioning console, create a VM record for the snapshot VM using the VM’s MAC address. Assign the vDisk created in step 7 to this device record.
  12. Boot the VM. Install the VDA, and restart if prompted. Shutdown when the installation finishes.
  13. Create a snapshot of this VM.
  14. In the provisioning console, set the vDisk to standard image mode. If the cache mode is Cache on device hard disk or Cache in device RAM with overflow to hard disk, the Citrix Virtual Apps and Desktops Setup Wizard prompts you to create a cache disk.
  15. Use the Citrix Virtual Apps and Desktops Set Up Wizard to provision UEFI provisioning target devices using the created vDisk.

SCVMM requirements

You cannot provision vGPU-enabled VMs on Hyper-V.