VMware virtualization environments
Follow this guidance if you use VMware to provide virtual machines.
Install vCenter Server and the appropriate management tools. (No support is provided for vSphere vCenter Linked Mode operation.)
If you plan to use MCS, do not disable the Datastore Browser feature in vCenter Server (described in https://kb.vmware.com/s/article/2101567). When you disable this feature, MCS does not work correctly.
You can use Citrix Provisioning (formerly Provisioning Services) and Machine Creation Services to provision:
- legacy BIOS for supported Desktop or Server OS VMs.
- UEFI for supported Desktop or Server OS VMs, including Secure Boot.
Required privileges
Create a VMware user account and one or more VMware roles with a set or all permissions listed in this article. Base the roles’ creation on the specific level of granularity required over the user’s permissions to request the various Citrix DaaS operations at any time. To grant the user-specific permissions at any point, associate them with the respective role, at the data center level at a minimum, with the Propagate to children option selected. However, for StorageProfile
permissions and a specific Tags
permission, apply the permissions at the Root vCenter Server level, without Propagate to Children. See the notes in each of those tables.
The following tables show the mappings between Citrix Virtual Apps and Desktops operations and the minimum required VMware privileges.
Note:
The permissions list display name, specifically the User Interface, is different for some vSphere versions. For example, in vSphere 6.7 the User Interface permission is Change Memory and Change Settings, rather than Settings and Memory as described in the required privileges noted on this page.
Add connections and resources
SDK | User interface |
---|---|
System.Anonymous, System.Read, and System.View | Added automatically. Can use the built-in read-only role. |
Power management
SDK | User interface |
---|---|
VirtualMachine.Interact.PowerOff | Virtual machine > Interaction > Power Off |
VirtualMachine.Interact.PowerOn | Virtual machine > Interaction > Power On |
VirtualMachine.Interact.Reset | Virtual machine > Interaction > Reset |
VirtualMachine.Interact.Suspend | Virtual machine > Interaction > Suspend |
Datastore.Browse | Datastore > Browse datastore |
Provision machines (Machine Creation Services)
To provision machines using MCS, the following permissions are mandatory:
SDK | User interface |
---|---|
Datastore.AllocateSpace | Datastore > Allocate space |
Datastore.Browse | Datastore > Browse datastore |
Datastore.FileManagement | Datastore > Low level file operations |
Network.Assign | Network > Assign network |
Resource.AssignVMToPool | Resource > Assign virtual machine to resource pool |
VirtualMachine.Config.AddExistingDisk | Virtual machine > Configuration > Add existing disk |
VirtualMachine.Config.AddNewDisk | Virtual machine > Configuration > Add new disk |
Virtual machine.Config.Add or remove device | Virtual machine > Configuration > Add or remove device |
VirtualMachine.Config.AdvancedConfig | Virtual machine > Configuration > Advanced |
VirtualMachine.Config.RemoveDisk | Virtual machine > Configuration > Remove disk |
VirtualMachine.Config.CPUCount | Virtual machine > Configuration > Change CPU count |
VirtualMachine.Config.Memory | Virtual machine > Configuration > Change memory |
VirtualMachine.Config.Settings | Virtual machine > Configuration > Change settings |
VirtualMachine.Interact.PowerOff | Virtual machine > Interaction > Power Off |
VirtualMachine.Interact.PowerOn | Virtual machine > Interaction > Power On |
VirtualMachine.Interact.Reset | Virtual machine > Interaction > Reset |
VirtualMachine.Interact.Suspend | Virtual machine > Interaction > Suspend |
VirtualMachine.Inventory.CreateFromExisting | Virtual machine > Inventory > Create from existing |
VirtualMachine.Inventory.Create | Virtual machine > Inventory > Create new |
VirtualMachine.Inventory.Delete | Virtual machine > Inventory > Remove |
VirtualMachine.Provisioning.Clone | Virtual machine > Provisioning > Clone virtual machine |
VirtualMachine.State.CreateSnapshot | vSphere 5.0, Update 2, vSphere 5.1, Update 1, and vSphere 6.x, Update 1: Virtual machine > State > Create snapshot; vSphere 5.5: Virtual machine > Snapshot management > Create snapshot |
Image update and rollback
SDK | User interface |
---|---|
Datastore.AllocateSpace | Datastore > Allocate space |
Datastore.Browse | Datastore > Browse datastore |
Datastore.FileManagement | Datastore > Low level file operations |
Network.Assign | Network > Assign network |
Resource.AssignVMToPool | Resource > Assign virtual machine to resource pool |
VirtualMachine.Config.AddExistingDisk | Virtual machine > Configuration > Add existing disk |
VirtualMachine.Config.AddNewDisk | Virtual machine > Configuration > Add new disk |
VirtualMachine.Config.AdvancedConfig | Virtual machine > Configuration > Advanced |
VirtualMachine.Config.RemoveDisk | Virtual machine > Configuration > Remove disk |
VirtualMachine.Interact.PowerOff | Virtual machine > Interaction > Power Off |
VirtualMachine.Interact.PowerOn | Virtual machine > Interaction > Power On |
VirtualMachine.Interact.Reset | Virtual machine > Interaction > Reset |
VirtualMachine.Inventory.CreateFromExisting | Virtual machine > Inventory > Create from existing |
VirtualMachine.Inventory.Create | Virtual machine > Inventory > Create new |
VirtualMachine.Inventory.Delete | Virtual machine > Inventory > Remove |
VirtualMachine.Provisioning.Clone | Virtual machine > Provisioning > Clone virtual machine |
Delete provisioned machines
SDK | User interface |
---|---|
Datastore.Browse | Datastore > Browse datastore |
Datastore.FileManagement | Datastore > Low level file operations |
VirtualMachine.Config.RemoveDisk | Virtual machine > Configuration > Remove disk |
VirtualMachine.Interact.PowerOff | Virtual machine > Interaction > Power Off |
VirtualMachine.Inventory.Delete | Virtual machine > Inventory > Remove |
Storage Profile (vSAN)
To view, create, or delete storage policies during catalog creations on a vSAN datastore, the following permissions are mandatory:
SDK | User interface |
---|---|
StorageProfile.Update | PROFILE-DRIVEN STORAGE > Profile-driven storage update. For vSphere 8: VM storage policies > Update VM storage policies |
StorageProfile.View | PROFILE-DRIVEN STORAGE > Profile-driven storage view. For vSphere 8: VM storage policies > View VM storage policies |
Note:
Apply the storage profile permissions at the Root vCenter Server level, without Propagate to Children.
Tags and Custom Attributes
Tags and custom attributes allow you to attach metadata to the VMs created in vSphere inventory and make it easier to search and filter these objects. To create, edit, assign, and delete tags or categories, the following permissions are mandatory:
SDK | User interface |
---|---|
InventoryService.Tagging.CreateTag | vSphere Tagging > Create vSphere Tag |
InventoryService.Tagging.CreateCategory | vSphere Tagging > Create vSphere Tag Category |
InventoryService.Tagging.EditTag | vSphere Tagging > Edit vSphere Tag |
InventoryService.Tagging.EditCategory | vSphere Tagging > Edit vSphere Tag Category |
InventoryService.Tagging.DeleteTag | vSphere Tagging > Delete vSphere Tag |
InventoryService.Tagging.DeleteCategory | vSphere Tagging > Delete vSphere Tag Category |
InventoryService.Tagging.AttachTag | vSphere Tagging > Assign or Unassign vSphere Tag |
InventoryService.Tagging.ObjectAttachable | vSphere Tagging > Assign or Unassign vSphere Tag on Object |
Global.ManageCustomFields | Global > Manage custom attributes |
Global.SetCustomField | Global > Set custom attribute |
Note:
- When MCS creates a machine catalog, it tags the target VMs with special name tags. These tags differentiate the master image from MCS created VMs and prevent using MCS created VMs for image preparation. You can identify the difference by the value of
XdProvisioned
attribute in vCenter. The attribute is set to True if MCS creates VMs.- Apply the
InventoryService.Tagging.AttachTag
permission at the Root vCenter Server level, without Propagate to Children.
Cryptographic operations
Cryptographic operations privileges control who can perform which type of cryptographic operation on which type of object. vSphere Native Key Provider uses the Cryptographer.*
privileges. The following minimum permissions are required for cryptographic operations:
Note:
These permissions are required for creating MCS machine catalogs with vTPM equipped VM.
SDK | User interface |
---|---|
Cryptographer.Access | Privileges > All Privileges > Cryptographic operations > Direct Access |
Cryptographer.AddDisk | Privileges > All Privileges > Cryptographic operations > Add disk |
Cryptographer.Clone | Privileges > All Privileges > Cryptographic operations > Clone |
Cryptographer.Encrypt | Privileges > All Privileges > Cryptographic operations > Encrypt |
Cryptographer.EncryptNew | Privileges > All Privileges > Cryptographic operations > Encrypt new |
Cryptographer.Decrypt | Privileges > All Privileges > Cryptographic operations > Decrypt |
Cryptographer.Migrate | Privileges > All Privileges > Cryptographic operations > Migrate |
Cryptographer.ReadKeyServersInfo | Privileges > All Privileges > Cryptographic operations > Read KMS information |
Provision machines (Citrix Provisioning)
These permissions to clone and deploy a template are required to provision VMs using Citrix Virtual Apps and Desktops Setup Wizard and Export Devices Wizard through the Citrix Provisioning console. Set the permissions while creating a hosting connection. You need all the permissions from Provision machines (Machine Creation Services) and the following.
SDK | User interface |
---|---|
VirtualMachine.Config.AddRemoveDevice | Virtual machine > Configuration > Add or remove device |
VirtualMachine.Config.CPUCount | Virtual machine > Configuration > Change CPU Count |
VirtualMachine.Config.Memory | Virtual machine > Configuration > Memory |
VirtualMachine.Config.Settings | Virtual machine > Configuration > Settings |
VirtualMachine.Provisioning.CloneTemplate | Virtual machine > Provisioning > Clone template |
VirtualMachine.Provisioning.DeployTemplate | Virtual machine > Provisioning > Deploy template |
VApp.Export | vApp > Export |
Note:
The
VApp.Expor
is required for creating MCS machine catalogs using machine profile.
Obtain and import a certificate
To protect vSphere communications, Citrix recommends that you use HTTPS rather than HTTP.
HTTPS requires digital certificates. Use a digital certificate issued from a certificate authority that meets your organization’s security policy.
If you are unable to use a digital certificate issued from a certificate authority, you can use the VMware-installed self-signed certificate. Only use this method if your organization’s security policy permits it. Add the VMware vCenter certificate to each Delivery Controller.
-
Add the fully qualified domain name (FQDN) of the computer running vCenter Server to the hosts file on that server, at
%SystemRoot%/WINDOWS/system32/Drivers/etc/
. This step is required only if the FQDN of the computer running vCenter Server is not already present in the domain name system. -
Obtain the vCenter certificate using any of the following three methods:
From the vCenter server.
- Copy the file rui.crt from the vCenter server to a location accessible on your Delivery Controllers.
- On the Controller, navigate to the location of the exported certificate and open the rui.crt file.
Download the certificate using a web browser. If you are using Internet Explorer, right-click on Internet Explorer and choose Run as Administrator to download or install the certificate.
- Open your web browser and make a secure web connection to the vCenter server (for example https://server1.domain1.com).
- Accept the security warnings.
- Click the address bar displaying the certificate error.
- View the certificate and click the Details tab.
- Select Copy to file and export in .CER format, providing a name when prompted to do so.
- Save the exported certificate.
- Navigate to the location of the exported certificate and open the .CER file.
Import directly from Internet Explorer running as an administrator.
- Open your web browser and make a secure web connection to the vCenter server (for example https://server1.domain1.com).
- Accept the security warnings.
- Click the address bar displaying the certificate error.
- View the certificate.
-
Import the certificate into the certificate store on each of your Controllers.
- Click the Install certificate option, select Local Machine, and then click Next.
- Select Place all certificates in the following store, and then click Browse. Select Trusted People and then click OK. Click Next and then click Finish.
If you change the name of the vSphere server after installation, you must generate a new self-signed certificate on that server before importing the new certificate.
Configuration considerations
Create a master VM:
Use a master VM to provide user desktops and applications in a machine catalog. On your hypervisor:
- Install a VDA on the master VM, selecting the option to optimize the desktop, which improves performance.
- Take a snapshot of the master VM to use as a back-up.
Create a connection:
In the connection creation wizard:
- Select the VMware connection type.
- Specify the address of the access point for the vCenter SDK.
- Specify the credentials for a VMware user account you set up earlier that has permissions to create VMs. Specify the user name in the form domain/username.
VMware SSL thumbprint
The VMware SSL thumbprint feature eliminates the need to manually create a host connection to a VMware vSphere hypervisor. It is no longer required to manually create a trust relationship between the Delivery Controllers in the Site and the hypervisor’s certificate before creating a connection.
The VMware SSL thumbprint feature stores the untrusted certificate’s thumbprint on the Site database. This configuration ensures that the hypervisor can be continuously identified as trusted by Citrix Virtual Apps and Desktops, even if not by the Controllers.
When creating a vSphere host connection in Studio, a dialog box allows you to view the certificate of the machine you are connecting to. You can then choose whether to trust it.
Reset OS disk
Use the PowerShell command Reset-ProvVMDisk
to reset the OS disk of a persistent VM in an MCS created machine catalog.
To successfully run the PowerShell command, make sure that:
- The target VMs are in a persistent MCS catalog.
- The MCS machine catalog is functioning properly.
- This implies that the provisioning scheme and host exist, and the provisioning scheme has correct entries.
- VMware vCenter is not in maintenance mode.
- Target VMs are powered-off and in maintenance mode.
Perform the following steps to reset the OS disk:
- Open a PowerShell window.
- Run asnp citrix* to load the Citrix-specific PowerShell modules.
-
Run the PowerShell command
Reset-ProvVMDisk
in any one of the following ways:-
Specify the list of VMs as a comma-separated list, and perform the reset on each VM:
Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName ("abc","def") -OS <!--NeedCopy-->
-
Specify the list of VMs as an output from
Get-ProvVM
command, and perform the reset on each VM:(Get-ProvVM -ProvisioningSchemeName "xxx") | Reset-ProvVMDisk "abc" -OS <!--NeedCopy-->
-
Specify a single VM by name:
Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS <!--NeedCopy-->
-
Create separate reset tasks for each of the VMs returned by the
Get-ProvVM
command. This is less efficient because each task will perform the same redundant checks, such as hypervisor capability check, connection check for each VM.Get-ProvVM -ProvisioningSchemeName "xxx" | Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -OS <!--NeedCopy-->
-
-
A confirmation prompt appears that lists the VMs to be reset along with a warning message that it is an unrecoverable operation. If you do not provide an answer and press Enter, no further action takes place.
Note:
Do not take VMs out the of the maintenance mode or power them on until the completion of the reset process.
You can run the PowerShell command
-WhatIf
to print the action it would take and exit without performing the action.You can also bypass the confirmation prompt using one of the following methods:
-
Provide the
-Force
parameter:Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS -Force <!--NeedCopy-->
-
Provide the
-Confirm:$false
parameter:Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS -Confirm:$false <!--NeedCopy-->
-
Before running the
Reset-ProvVMDisk
, change$ConfirmPreference
to None:PS C:\Windows\system32> $ConfirmPreference='None' PS C:\Windows\system32> $ConfirmPreference None PS C:\Windows\system32> Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS <!--NeedCopy-->
-
- Run
Get-ProvTask
to get the status of the tasks returned byReset-ProvVMDisk
command.
Update the folder ID of a machine catalog
You can update the folder ID of an MCS machine catalog by specifying the FolderId
in the custom properties of Set-ProvScheme
command. The VMs created after updating the folder ID are created under this new folder ID. If this property is not specified in CustomProperties
, then VMs are created under the folder where the master image is located.
Perform the following steps to update the folder ID of a machine catalog.
-
Open a Web browser and enter the URL for the vSphere Web Client.
-
Enter the credentials and click Login.
-
Create a VM placement folder in vSphere Web Client.
-
Open a PowerShell window.
-
Run asnp citrix* to load the Citrix-specific PowerShell modules.
-
Specify the
FolderID
in theCustomProperties
ofSet-ProvScheme
. In this example, the folder ID value isgroup-v2406
.Set-ProvScheme -ProvisioningSchemeUid "50bb319c-2e83-4a37-9ea1-94f630687372" -CustomProperties "<CustomProperties xmlns=""http://schemas.citrix.com/2014/xd/machinecreation"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""><Property xsi:type=""StringProperty"" Name=""FolderId"" Value=""group-v2406"" /></CustomProperties>" <!--NeedCopy-->
- Add a VM to the machine catalog using Studio.
- Check the new VM on vSphere Web Client. The new VM is created under the new folder.
Find the folder ID in vSphere
Access Managed Object Browser (MOB) on any ESXi or vCenter server system to find the folder ID of the VMs.
The MOB is a web-based server application available inbuilt in all ESX/ESXi and vCenter server systems. This vSphere utility allows you to view detailed information about objects like VMs, datastores, and resource pools.
- Open a web browser and enter
http://x.x.x.x/mob
, where x.x.x.x is the IP address of the vCenter Server or ESX/ESXi host. For example, https://10.60.4.70/mob. - On the Home page of MOB, click the value of the property content.
- Click the value of the rootFolder.
- Click the value of the childEntity.
- Click the value of the vmFolder.
- You can find the folder ID in the value of the childEntity.
Troubleshooting
If the catalog fails to create, see CTX294978.