Citrix Provisioning

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

The Citrix Virtual Desktops Setup Wizard helps with deploying virtual desktops to virtual machines (VMs).


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 (formerly Citrix Hypervisor)
    • ESX through vCenter
    • 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. See 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 virtual disk 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 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 are aware of the new partition. For example, an RDS provisioning image using a write cache disk and BDM partition has 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 virtual disk through the SOAP server. For details, see Installation.
  • Using the Citrix Provisioning Setup Wizard to create VMs on a XenServer host while specifying 1 vCPU, creates a VM with 1 vCPU. However, the topology possesses 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. A VDA occasionally reaches a state where it fails to shut down correctly. This process occurs because the VDA is initializing while the Citrix Provisioning Device Service simultaneously finishes formatting the cache drive then shuts down the target. To resolve this issue, in the virtual disk 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.

About Citrix Studio tools

When using Citrix Studio to create provisioned catalogs, consider:

  • The Citrix Virtual Apps and Desktops Setup Wizard provisions target VMs and adds them to a broker catalog.
  • The Export Devices Wizard adds existing provisioned target VMs to a broker catalog.

With both wizards, authentication occurs to Citrix Virtual Apps and Desktops. Hosting connections are retrieved so that you can select the connection used by the broker to power manage the provisioned target VMs.


Only hosting units, not hosting connections, can be used. These hosting units are only created when you specify Studio Tools when the hosting connection is created.

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 support Provisioning Services 7.x.

Write cache considerations

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

The wizard provisions diskless VMs if the virtual disk 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 virtual disk 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 ESX and Hyper-v, 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 (,). Citrix Virtual Apps and Desktops retains names associated with storage devices 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 Citrix Hypervisors
  • “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.

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. Configure the PXE boot option in 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 Desktops Setup Wizard…menu option. The Citrix Virtual Desktops Setup Wizard appears. Note: The Citrix Virtual Apps and Desktop Setup Wizard is shown as the Citrix Virtual Desktops Setup Wizard in the provisioning console.

  2. Click Next to begin setup.

  3. On the Citrix Virtual Desktops Controller page, select the type the Delivery Controller.

    1. If you select Citrix Cloud, enter Citrix Cloud Credentials when prompted, and select the cloud customer if requested.

      Citrix Cloud DDC CVAD Setup Wizard

    2. If you select Customer-Managed Control Plane, enter the controller hostname or address. The wizard authenticates to the Delivery Controller using the current logged in user.

      Citrix Cloud DDC CVAD Setup Wizard

  4. Select a Citrix Virtual Apps and Desktops 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, user name, 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 virtual disk 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.
      • Windows Server Operating System – best for delivering hosted shared desktops for 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 menu, that catalog’s description, machine type, assignment type, and user data appear.
  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:
      • 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).
  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 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 menu 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 menu 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 and 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 might take a long time. 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 receive feedback in the form of an hour glass cursor while the import finishes.

  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
    • Create a write cache disk of the specified size
    • Create Citrix Provisioning target devices then assign the selected virtual disk 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.

To update and reassign a virtual disk, copy the target device’s currently assigned base virtual disk image. Update the image to include new Citrix Provisioning software and drivers. Reassign the updated virtual disk to the target device. To reassign the virtual disk, 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 plug-in for Citrix Provisioning. Download this plug-in from the Nutanix support site. See the Nutanix documentation portal 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 and BDM partitions 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.
  • Ideally, a snapshot does not have an attached hard disk because the Nutanix Acropolis hypervisor does not remove the hard disk during provisioning.
  • When you deploy machines that boot from BDM ISOs, the ISO is mounted in the snapshot. The provisioned VMs are set to use PXE boot. Even though PXE was selected in the Setup Wizard, the deployed VMs honor the template snapshot. These VMs boot to the BDM ISO without extra steps as long as the template snapshot contains the BDM ISO and the default boot order.
  • For PXE booting, you must use a command line option to set the VM boot order to network before imaging.
  • You can add Nutanix hosts only by using the Citrix Virtual Apps and Desktops Setup Wizard from a Citrix Virtual Apps and Desktops hosting connection.


For information about 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 is 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 <VM_NAME> 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, virtual disk, and other elements. Select 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 command string 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 <VM_NAME> mac_addr=<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 virtual disk 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 virtual disk 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 wizard prompts you to create a cache disk.
  15. Use the Citrix Virtual Apps and Desktops setup Wizard to provision UEFI provisioning target devices using the created virtual disk.

SCVMM requirements

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


HyperV Gen1 VMs provisioned using Citrix Virtual Apps and Desktops Setup Wizard always have the operating system set to unknown instead of the operating system of the template.

Provision VDAs on an opaque Network

To provision a VDA on an opaque network, use the Citrix Virtual Apps and Desktops Setup Wizard.

Create the hosting unit and associate the opaque network to it using Citrix Studio. See Connections and resources for more information.

Use Citrix Studio to select an opaque network

In Citrix Studio, access the Add Connection and Resources page. In the Network section, select the resource representing the opaque network, then click Next:

Studio add connection and resources


After creating a hosting unit with the opaque network, use it in the Citrix Virtual Apps and Desktops Wizard in the provisioning console.

Provision VDAs to a specific resource pool

Citrix Provisioning 1912 supports provisioning VDAs at a specific resource pool in an on-premises ESX hypervisor. You can provision this VDA using the Citrix Virtual Apps and Desktops Setup Wizard in the Citrix Provisioning console.


Create a hosting unit with the resource pool using Citrix Studio before using the Setup Wizard in the provisioning console.

  • The provisioned target device installer registers the WMI and performance counter providers. No additional installation options require configuration on the provisioned target device.
  • The current CVhdMp performance counter provider only supports VHDX for target devices using Cache in device RAM with overflow on hard drive. Configure the resource pool. In Citrix Studio, launch the Add Connection and Resources Wizard. From the Add Connection and Resources page, select Storage Management. In the Select a cluster field, click Browse:

Studio storage management

Select the appropriate cluster, and click Next. Select the Compute-ResourcePool or any of the child resource pool options under Compute-ResourcePool.

Studio storage management

Use the Citrix Virtual Apps and Desktops Setup Wizard in the provisioning console to select the hosting unit with the resource pool. Click Next:

Studio storage management


To provision at the root cluster level, select the Ignore resource pool info, create VM at cluster level check box.

The cluster and the resource pool info appear in the Summary page of the Citrix Virtual Apps and Setup Wizard:

Studio storage management

Using PowerShell to provision VDAs at the resource pool level

Citrix Provisioning 1912 includes a new switch parameter, UseResourcePool, added to StartPvsProvisionXdMachines in the Citrix.ProvisioningServices PowerShell cmdlet.

To provision machines at the resource pool level, use the Start-ProvisionXdMachines with the -UseResourcePool switch parameter.

For example:

Start-PvsProvisionXdMachines -DdcAddress <ddcAddress> -BootType <bootType> -CatalogName <catalogName> -CatalogDescription <catalogDescription> -SessionSupport <sessionSupport> -AllocationType <allocationType> -PersistUserChanges <persistUserChanges> -Scope <scope> -VdaLevel <vdaLevel> -XenDesktopHostResource <hostname> -HostResourcePassword <hostPassword> -TemplateName <templateName> -NetworkPath <networkPath> -StoreId <storeId> -SiteId <siteId> -DiskLocatorId <diskLocatorId> -Domain <domain> -OrganizationalUnit <organizationalUnit> -NamingScheme <namingScheme> -VmCount <vmCount> -DeviceMemory <deviceMemory> -DeviceCpu <deviceCPU> -DeviceWriteCacheSize <deviceWriteCacheSize> -NameSuffixType <nameSuffixType> -VmPvdSize <vmPvdSize> -VmPvdDrive <vmPvdDrive> -UseResourcePool


If the parameter -UseResourcePool is not included, the VDA is provisioned at the root cluster level.

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