Create machine catalogs

Important:

As of Citrix Virtual Apps and Desktops 7 2006, if your current deployment uses any of the following technologies, you can upgrade your deployment to the current release only after removing End of Life (EOL) items that use those technologies.

• Personal vDisks (PvDs)
• AppDisks
• Public cloud host types: Citrix CloudPlatform, Microsoft Azure Classic

For details, see Remove PVD, AppDisks, and unsupported hosts.

If you want to use public cloud host connections to your deployment, you need Hybrid Rights License to complete your fresh installation or upgrade to the current release.

When the installer detects one or more of the unsupported technologies or host connections without Hybrid Rights License, the upgrade pauses or stops. An explanatory message appears. The installer logs contain details. For more information, see Upgrade a deployment.

Effect of Hybrid Rights License on host connections

There are three scenarios where the host connection to the public cloud hosts is affected based on Hybrid Rights License entitlement:

• To create a host connection to the public cloud hosts, you must have Hybrid Rights License.

• If you have Hybrid Rights License but the license has expired, then the existing connections to public cloud hosts are marked as not entitled and enter into maintenance mode. When existing host connections are in maintenance mode, you cannot do the following:

  • Add or modify host connections
  • Create catalogs and update images
  • Perform power actions

• When not entitled host connections change to entitled, existing hosting connections are re-enabled.

Introduction

Collections of physical or virtual machines are managed as a single entity called a machine catalog. Machines in a catalog have the same type of operating system: multi-session OS or single-session OS. A catalog containing multi-session OS machines can contain either Windows or Linux machines, not both.

Citrix Studio guides you to create the first machine catalog after you create the site. After you create the first catalog, Studio guides you to create the first delivery group. Later, you can change the catalog you created, and create more catalogs.

Tip:

Upgrading an existing deployment enables the Machine Creation Services (MCS) storage optimization (MCS I/O) feature, no additional configuration is required. The Virtual Delivery Agent (VDA) and the Delivery Controller upgrade handle the MCS I/O upgrade.

Overview

When you create a catalog of VMs, you specify how to provision those VMs. You can use Citrix tools such as Machine Creation Services (MCS) or Citrix Provisioning (formerly Provisioning Services). Or, you can use your own tools to provide machines.

Consider:

• MCS supports a single system disk from the virtual machine image. It ignores the rest of the data disks attached to that image.
• If you use Citrix Provisioning to create machines, see the Citrix Provisioning documentation for instructions.
• If you use MCS to provision VMs, you provide a master image (or snapshot of an image) to create identical VMs in the catalog. Before you create the catalog, you first use the tools to create and configure the master image. This process includes installing a Virtual Delivery Agent (VDA) on the image. Then you create the machine catalog in Studio. You select that image (or snapshot), specify the number of VMs to create in the catalog, and configure additional information.
• If your machines are already available, you must still create one or more machine catalogs for those machines.
• If you are creating a catalog using the PowerShell SDK directly, you can specify a hypervisor template (VMTemplates), rather than an image or a snapshot.
• Using a template to provision a catalog is considered an experimental feature. When using this method, virtual machine preparation might fail. As a result, the catalog cannot be published using the template.

When using MCS or Citrix Provisioning to create the first catalog, you use the host connection that you configured when you created the site. Later (after you create your first catalog and delivery group), you can change information about that connection or create more connections.

After you complete the catalog creation wizard, tests run automatically to ensure that it is configured correctly. When the tests complete, you can view a test report. Run the tests at any time from Studio.

Note:

MCS does not support Windows 10 IoT Core and Windows 10 IoT Enterprise. Refer to the Microsoft site for more information.

For technical details about the Citrix Provisioning tools, see Citrix Virtual Apps and Desktops Image Management.

RDS license check

Citrix Studio currently does not perform the check for valid Microsoft RDS licenses while creating a machine catalog that contains Windows multi-session OS machines. To view the status of the Microsoft RDS license for a Windows multi-session OS machine, go to Citrix Director. View the status of the Microsoft RDS license in the Machine Details panel. This panel is located in the Machine Details and the User Details page. For more information, see Microsoft RDS license health.

VDA registration

A VDA must be registered with a Delivery Controller when launching brokered sessions. Unregistered VDAs can result in underutilization of otherwise available resources. There are various reasons a VDA might not be registered, many of which an administrator can troubleshoot. Studio provides troubleshooting information in the catalog creation wizard, and after you add machines from a catalog to a delivery group.

After you add existing machines using the wizard, the list of computer account names indicates whether each machine is suitable for adding to the catalog. Hover over the icon next to each machine to display an informative message about that machine.

If the message identifies a problematic machine, either remove that machine, or add the machine. For example, if a message indicates that information might not be obtained about a machine, add the machine anyway.

For more information, see:

• CTX136668 for VDA registration troubleshooting guidance
• VDA versions and functional levels
• VDA registration methods

MCS catalog creation summary

Here’s a brief overview of default MCS actions after you provide information in the catalog creation wizard.

• If you selected a master image (rather than a snapshot), MCS creates a snapshot.
• MCS creates a full copy of the snapshot and places the copy on each storage location defined in the host connection.
• MCS adds the machines to Active Directory, which creates unique identities.
• MCS creates the number of VMs specified in the wizard, with two disks defined for each VM. In addition to the two disks per VM, a master is also stored in the same storage location. If you have multiple storage locations defined, each gets the following disk types:
  • The full copy of the snapshot which is read-only and shared across the just-created VMs.
  • A unique 16 MB identity disk that gives each VM a unique identity. Each VM gets an identity disk.
  • A unique difference disk to store writes made to the VM. This disk is thin provisioned (if supported by the host storage) and increases to the maximum size of the master image, if necessary. Each VM gets a difference disk. The difference disk holds changes made during sessions. It is permanent for dedicated desktops. For pooled desktops, it is deleted and a new one created after each restart via the delivery controller.

Alternatively, when creating VMs to deliver static desktops, you can specify (on the Machines page of the catalog creation wizard) thick (full copy) VM clones. Full clones do not require retention of the master image on every data store. Each VM has its own file.

MCS storage considerations

There are many factors when deciding on storage solutions, configurations, and capacities for MCS. The following information provides proper considerations for storage capacity:

Capacity considerations:

• Disks

  The Delta or Differencing (Diff) Disks consume the largest amount of space in most MCS deployments for each VM. Each VM created by MCS is given at minimum 2 disks upon creation.

  • Disk0 = Diff Disk: contains the OS when copied from the Master Base Image.
  • Disk1 = Identity Disk: 16 MB - contains Active Directory data for each VM.

  As the product evolves, you might have to add more disks to satisfy certain use cases and feature consumption. For example:

  • MCS Storage Optimization creates a write cache style disk for each VM.
  • MCS added the ability to use full clones as opposed to the Delta disk scenario described in the previous section.

  Hypervisor features might also enter into the equation. For example:

  • Citrix Hypervisor IntelliCache creates a Read Disk on local storage for each Citrix Hypervisor. This option saves on IOPS against the master image which might be held on the shared storage location.

• Hypervisor overhead

  Different hypervisors use specific files that create overhead for VMs. Hypervisors also use storage for management and general logging operations. Calculate space to include overhead for:

  • Log files
  • Hypervisor specific files. For example:
    • VMware adds more files to the VM storage folder. See VMware Best Practices.
    • Calculate your total virtual machine size requirements. Consider a virtual machine containing 20 GB for the virtual disk, 16 GB for the swap file, and 100 MB for log files consuming 36.1 GB total.
  • Snapshots for XenServer; Snapshots for VMware.

• Process overhead

  Creating a catalog, adding a machine, and updating a catalog have unique storage implications. For example:

  • Initial catalog creation requires a copy of the base disk to be copied to each storage location.
    • It also requires you to create a Preparation VM temporarily.
  • Adding a machine to a catalog does not require copying of the base disk to each storage location. Catalog creation varies based on the features selected.
  • Updating the catalog to create an extra base disk on each storage location. Catalog updates also experience a temporary storage peak where each VM in the catalog has 2 Diff disks for a certain amount of time.

More considerations:

• RAM sizing: Affects the size of certain hypervisor files and disks, including I/O optimization disks, write cache, and snapshot files.
• Thin / Thick provisioning: NFS storage is preferred due to the thin provisioning capabilities.

Machine Creation Services (MCS) storage optimization

With the Machine Creation Services (MCS) storage optimization feature, referred to as MCS I/O:

• The write cache container is file-based, the same functionality found in Citrix Provisioning. For example, the Citrix Provisioning write cache file name is D:\vdiskdif.vhdx and the MCS I/O write cache file name is D:\mcsdif.vhdx.
• Achieve diagnostic improvements by including support for a Windows crash dump file written to the write cache disk.
• MCS I/O retains the technology cache in RAM with overflow to hard disk to provide the most optimal multi-tier write cache solution. This functionality allows an administrator to balance between the cost in each tier, RAM and disk, and performance to meet the desired workload expectation.

Updating the write cache method from disk-based to file-based requires the following changes:

1. MCS I/O no longer supports RAM only cache. Specify a disk size in Citrix Studio during machine catalog creation.
2. The VM write cache disk is created and formatted automatically when booting a VM for the first time. Once the VM is up, the write cache file mcsdif.vhdx is written into the formatted volume MCSWCDisk.
3. The pagefile is redirected to this formatted volume, MCSWCDisk. As a result, this disk size considers the total amount of disk space. It includes the delta between the disk size and the generated workload plus the pagefile size. This is typically associated with VM RAM size.

Enabling MCS storage optimization updates

To enable MCS I/O storage optimization functionality, upgrade the Delivery Controller and the VDA to the latest version of Citrix Virtual Apps and Desktops.

Note:

If you upgrade an existing deployment which has MCS I/O enabled, no additional configuration is required. The VDA and the Delivery Controller upgrade handle the MCS I/O upgrade.

When enabling the MCS storage optimization update, consider the following:

• When creating a machine catalog, the administrator can configure the RAM and disk size.

  

• Updating an existing machine catalog to a new VM snapshot containing a VDA configured for version 1903 results in the following behavior: the new snapshot continues to use the existing catalog’s MCS I/O setting for RAM and disk size. The existing raw disk is formatted.

Important:

MCS storage optimization changed with Citrix Virtual Apps and Desktops version 1903. This release supports file-based write cache technology, providing better performance and stability. The new functionality provided by MCS I/O might require a higher write cache storage requirement compared to previous Citrix Virtual Apps and Desktops releases. Citrix recommends that you reevaluate the disk size to ensure that it has sufficient disk space for the allocated workflow and extra pagefile size. The pagefile size is typically related to the amount of system RAM. If the existing catalog disk size is insufficient, create a machine catalog and allocate a larger write cache disk.

Using PowerShell to create a catalog with persistent write-back cache disk

To configure a catalog with persistent write-back cache disk, use the PowerShell parameter New-ProvScheme CustomProperties. This parameter supports an extra property, PersistWBC, used to determine how the write-back cache disk persists for MCS provisioned machines. The PersistWBC property is only used when the UseWriteBackCache parameter is specified, and when the WriteBackCacheDiskSize parameter is set to indicate that a disk is created.

Examples of properties found in the CustomProperties parameter before supporting PersistWBC include:

<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="benvaldev5RG3" />
</CustomProperties>
<!--NeedCopy-->

When using these properties, consider that they contain default values if the properties are omitted from the CustomProperties parameter. The PersistWBC property has two possible values: true or false.

Setting the PersistWBC property to true does not delete the write-back cache disk when the Citrix Virtual Apps and Desktops administrator shuts down the machine using Citrix Studio.

Setting the PersistWBC property to false deletes the write-back cache disk when the Citrix Virtual Apps and Desktops administrator shuts down the machine using Citrix Studio.

Note:

If the PersistWBC property is omitted, the property defaults to false and the write-back cache is deleted when the machine is shutdown using Citrix Studio.

For example, using the CustomProperties parameter to set PersistWBC to true:

<CustomProperties xmlns="http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Property xsi:type="StringProperty" Name="UseManagedDisks" Value="true" />
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="benvaldev5RG3" />
<Property xsi:type="StringProperty" Name="PersistWBC" Value="true" />
</CustomProperties>
<!--NeedCopy-->

Important:

The PersistWBC property can only be set using the New-ProvScheme PowerShell cmdlet. Attempting to alter the CustomProperties of a provisioning scheme after creation has no impact on the machine catalog and the persistence of the write-back cache disk when a machine is shut down.

For example, set New-ProvSchemeto use the write-back cache while setting the PersistWBC property to true:

New-ProvScheme
-CleanOnBoot
-CustomProperties "<CustomProperties xmlns=`"http://schemas.citrix.com/2014/xd/machinecreation`" xmlns:xsi=`"http://www.w3.org/2001/XMLSchema-instance`"><Property xsi:type=`"StringProperty`" Name=`"UseManagedDisks`" Value=`"true`" /><Property xsi:type=`"StringProperty`" Name=`"StorageAccountType`" Value=`"Premium_LRS`" /><Property xsi:type=`"StringProperty`" Name=`"ResourceGroups`" Value=`"benvaldev5RG3`" /><Property xsi:type=`"StringProperty`" Name=`"PersistWBC`" Value=`"true`" /></CustomProperties>"
-HostingUnitName "adSubnetScale1"
-IdentityPoolName "BV-WBC1-CAT1"
-MasterImageVM "XDHyp:\HostingUnits\adSubnetScale1\image.folder\GoldImages.resourcegroup\W10MCSIO-01_OsDisk_1_a940e6f5bab349019d57ccef65d2c7e3.manageddisk"
-NetworkMapping @{"0"="XDHyp:\HostingUnits\adSubnetScale1\\virtualprivatecloud.folder\CloudScale02.resourcegroup\adVNET.virtualprivatecloud\adSubnetScale1.network"}
-ProvisioningSchemeName "BV-WBC1-CAT1"
-ServiceOffering "XDHyp:\HostingUnits\adSubnetScale1\serviceoffering.folder\Standard_D2s_v3.serviceoffering"
-UseWriteBackCache
-WriteBackCacheDiskSize 127
-WriteBackCacheMemorySize 256
<!--NeedCopy-->

Prepare a master image

For information about creating connections hosts, see Connections and resources.

The master image contains the operating system, non-virtualized applications, VDA, and other software.

Good to know:

• A master image might also be known as a clone image, golden image, base VM, or base image. Host vendors use different terms.
• When using Citrix Provisioning, you can use a master image or a physical computer as the master target device. Citrix Provisioning uses different terminology than MCS to refer to images. See the Citrix Provisioning documentation for details.
• Ensure that the host has enough processors, memory, and storage to accommodate the number of machines created.
• Configure the correct amount of hard disk space needed for desktops and applications. That value cannot be changed later or in the machine catalog.
• Remote PC Access machine catalogs do not use master images.
• Microsoft KMS activation considerations when using MCS: If your deployment includes 7.x VDAs with a XenServer 6.1 or 6.2, vSphere, or Microsoft System Center Virtual Machine Manager host, you do not need to manually rearm Microsoft Windows or Microsoft Office.

Install and configure the following software on the master image:

• Integration tools for your hypervisor (such as Citrix VM Tools, Hyper-V Integration Services, or VMware tools). If you omit this step, applications and desktops might not function correctly.
• A VDA. Citrix recommends installing the latest version to allow access to the newest features. Failure to install a VDA on the master image causes the catalog creation to fail.
• Third-party tools as needed, such as antivirus software or electronic software distribution agents. Configure services with settings that are appropriate for users and the machine type (such as updating features).
• Third-party applications that you are not virtualizing. Citrix recommends virtualizing applications. Virtualizing reduces costs by eliminating having to update the master image after adding or reconfiguring an application. Also, fewer installed applications reduce the size of the master image hard disks, which saves storage costs.
• App-V clients with the recommended settings, if you plan to publish App-V applications. The App-V client is available from Microsoft.
• When using MCS, if you localize Microsoft Windows, install the locales and language packs. During provisioning, when a snapshot is created, the provisioned VMs use the installed locales and language packs.

Important:

If you are using Citrix Provisioning or MCS, do not run Sysprep on master images.

To prepare a master image:

1. Using your hypervisor’s management tool, create a master image and then install the operating system, plus all service packs and updates. Specify the number of vCPUs. You can also specify the vCPU value if you create the machine catalog using PowerShell. You cannot specify the number of vCPUs when creating a catalog using Studio. Configure the amount of hard disk space needed for desktops and applications. That value cannot be changed later or in the catalog.
2. Ensure that the hard disk is attached at device location 0. Most standard master image templates configure this location by default, but some custom templates might not.
3. Install and configure the software listed above on the master image.
4. When using Citrix Provisioning, create a VHD file for the virtual disk from your master target device before you join the master target device to a domain. See the Citrix Provisioning documentation for details.
5. If you are not using MCS, join the master image to the domain where applications and desktops are members. Ensure that the master image is available on the host where the machines are created. If you are using MCS, joining the master image to a domain is not required. The provisioned machines are joined to the domain specified in the catalog creation wizard.
6. Citrix recommends that you create and name a snapshot of your master image. If you specify a master image rather than a snapshot when creating a catalog, Studio creates a snapshot. You cannot name it.

Create a machine catalog using Studio

Before starting the catalog creation wizard, review this section.

If you are using a master image, ensure that you have installed a VDA on the image before creating the catalog.

From Studio:

• If you already created a site but haven’t yet created a machine catalog, Studio guides you to the correct starting place to create a catalog.
• If you already created a catalog and want to create another, select Machine Catalogs in the Studio navigation pane. Then select Create Machine Catalog in the Actions pane.

The wizard walks you through the following items. The wizard pages you see differ, depending on the selections you make.

Page file location

In Azure environments, the page file is set up to an appropriate location when the VM is first created. The paging file setting is configured in the format <page file location>[min size] [max size] (the size is in MB). For more information, see the Microsoft document How to determine the appropriate page file.

When you create ProvScheme during image preparation, MCS determines the page file location based on certain rules. After you create ProvScheme:

• VM size change is blocked if the incoming VM size causes the page file setting to be different.
• Machine profile update is blocked if the service offering is changed because of the machine profile update causing page file setting to be different.
• Ephemeral OS disk (EOS) and MCSIO properties cannot be changed.

Page file location determination

The features like EOS and MCSIO have their own expected page file location and are exclusive to each other. The table shows the expected page file location for each feature:

Note:

Even if image preparation is decoupled from the provisioning scheme creation, MCS correctly determines the page file location. The default page file location is on OS disk.

Page file setting scenarios

The table describes some possible scenarios of page file setting during image preparation and provisioning scheme update:

Update page file setting

You can also specify the page file setting, including the location and size, explicitly using the PoSH command. This overrides the value determined by MCS. You can do this by running the New-ProvScheme command and including the following custom properties:

• PageFileDiskDriveLetterOverride: Page file location disk drive letter
• InitialPageFileSizeInMB: Initial page file size in MB
• MaxPageFileSizeInMB: Maximum page file size in MB

Example of using the custom properties:

-CustomProperties '<CustomProperties xmlns=" http://schemas.citrix.com/2014/xd/machinecreation" xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance"> `
<Property xsi:type="StringProperty" Name="PersistOsDisk" Value="false"/> `
<Property xsi:type="StringProperty" Name="PersistVm" Value="false"/> `
<Property xsi:type="StringProperty" Name="PageFileDiskDriveLetterOverride" Value="d"/> `
<Property xsi:type="StringProperty" Name="InitialPageFileSizeInMB" Value="2048"/> `
<Property xsi:type="StringProperty" Name="MaxPageFileSizeInMB" Value="8196"/> `
<Property xsi:type="StringProperty" Name="StorageAccountType" Value="Premium_LRS"/> `
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client"/> `
</CustomProperties>'
<!--NeedCopy-->

Constraints:

• You can update the page file setting only when creating provisioning scheme by running the New-ProvScheme command and the page file setting cannot be changed later.
• Provide all the page file setting relative properties (PageFileDiskDriveLetterOverride, InitialPageFileSizeInMB, and MaxPageFileSizeInMB) in the custom properties or do not provide any of them.
• The initial page file size must be between 16 MB and 16777216 MB.
• The maximum page file size must be greater than or equal to the initial page file size and less than 16777216 MB.
• This feature is not supported in Citrix Studio.

Operating system

Each catalog contains machines of only one type. Select one.

• Multi-session OS: A multi-session OS catalog provides hosted shared desktops. The machines can be running supported versions of the Windows or Linux operating systems, but the catalog cannot contain both. (See the Linux VDA documentation for details about that OS.)
• Single-session OS: A single-session OS catalog provides VDI desktops that you can assign to various different users.
• Remote PC Access: A Remote PC Access catalog provides users with remote access to their physical office desktop machines. Remote PC Access does not require a VPN to provide security.

Machine management

This page does not appear when you are creating Remote PC Access catalogs.

The Machine Management page indicates how machines are managed and which tool you use to deploy machines.

Choose whether machines in the catalog are power managed through Studio.

• Machines are power managed through Studio, for example, VMs or blade PCs. This option is available only if you already configured a connection to a host.
• Machines are not power managed through Studio, for example, physical machines.

If you indicated that machines are power managed through Studio, choose which tool to use to create VMs.

• Citrix Machine Creation Services (MCS): Uses a master image to create and manage virtual machines. MCS is not available for physical machines.

• Citrix Provisioning: (Formerly Provisioning Services.) Manages target devices as a device collection. A Citrix Provisioning virtual disk imaged from a master target device delivers desktops and applications.

  Note:

  This option is no longer supported. To import a Citrix Provisioning target device into a Citrix Virtual Apps and Desktops catalog, use the Citrix Provisioning Export Devices Wizard.

• Other: A tool that manages machines already in the data center. Citrix recommends that you use Microsoft System Center Configuration Manager or another third-party application to ensure that the machines in the catalog are consistent.

Desktop types (desktop experience)

This page appears only when you are creating a catalog containing single-session OS machines.

The Desktop Experience page determines what occurs each time a user logs on. Select one of:

• Users connect to a new (random) desktop each time they log on.
• Users connect to the same (static) desktop each time they log on.

If you choose the second option and are using MCS to provision the machines, you can configure how user changes to the desktop are handled:

• Save user changes to the desktop on the local disk.
• Discard user changes and clear the virtual desktop when the user logs off. Select this option if you are using user personalization layer.

Master image

This page appears only when you are using MCS to create VMs.

On the Master image page, select the connection to the host, and then select the snapshot or VM created earlier. If you are creating the first catalog, the only available connection is the one you configured when you created the site.

Remember:

• When you are using MCS or Citrix Provisioning, do not run Sysprep on master images.
• If you specify a master image rather than a snapshot, Studio creates a snapshot, but you cannot name it.

To enable use of the latest product features, ensure that the master image has the latest VDA version installed. Do not change the default minimum VDA selection. However, if you must use an earlier VDA version, see VDA versions and functional levels.

An error message appears if you select a snapshot or VM that is not compatible with the machine management technology you selected earlier in the wizard.

Device Collection

This page appears only when using Citrix Provisioning to create VMs.

On the Device Collection page:

• Enter a Citrix Provisioning server address you want to connect to.
• Select the desired domain. If the domain is not shown in the list, you can do the following:
  • Search for it using an exact match.
  • Browse all domains to find it.
• Select the device collections to use. (The device collections and the devices that have not already been added to catalogs are shown in the list.)

Machines

This page does not appear when you are creating Remote PC Access catalogs.

The title of this page depends on what you selected on the Machine Management page: Machines, Virtual Machines, or VMs and users.

When using MCS:

• Specify how many virtual machines to create.
• Choose the amount of memory (in MB) each VM has.
• Each created VM has a hard disk. Its size is set in the master image. You cannot change the hard disk size in the catalog.
• If your deployment contains more than one zone, you can select a zone for the catalog.
• If you are creating static desktop VMs, select a virtual machine copy mode. See Virtual machine copy mode.
• If you are creating random desktop VMs that do not use vDisks, you can configure a cache to be used for temporary data on each machine. See Configure cache for temporary data.

When using Citrix Provisioning:

The Devices page lists the machines in the device collection that you selected on the previous wizard page. You cannot add or remove machines on this page.

When using other tools:

Add (or import a list of) Active Directory machine account names. You can change the Active Directory account name for a VM after you add/import it. If you specified static machines on the Desktop Experience page, you can optionally specify the Active Directory user name for each VM you add.

After you add or import names, you can use the Remove button to delete names from the list, while you are still on this page.

When using Citrix Provisioning or other tools (but not MCS):

An icon and tooltip for each machine added (or imported, or from a Citrix Provisioning device collection) help identify machines that might not be eligible to add to the catalog, or be unable to register with a Delivery Controller. For details, see VDA versions and functional levels.

Virtual machine copy mode

The copy mode you specify on the Machines page determines whether MCS creates thin (fast copy) or thick (full copy) clones from the master image. (Default = thin clones)

• Use fast copy clones for more efficient storage use and faster machine creation.
• Use full copy clones for better data recovery and migration support, with potentially reduced IOPS after the machines are created.

VDA versions and functional levels

A catalog’s functional level controls which product features are available to machines in the catalog. Using features introduced in new product versions require a new VDA. Setting a functional level makes all features introduced in that version (and later, if the functional level does not change) available to machines in the catalog. However, machines in that catalog with an earlier VDA version cannot register.

A menu near the bottom of the Machines (or Devices) page allows you to select the minimum VDA level. This sets the catalog’s minimum functional level. By default, the most current functional level is selected for on-premises deployments. If you follow the Citrix recommendation to always install and upgrade VDAs and core components to the latest version, you don’t need to change this selection. However, if you must continue using older VDA versions, select the correct value.

A Citrix Virtual Apps and Desktops release might not include a new VDA version, or the new VDA does not impact the functional level. In such cases, the functional level might indicate a VDA version that is earlier than the installed or upgraded components. For example, although version 7.17 contains a 7.17 VDA, the default functional level (“7.9 or later”) remains the most current. Therefore, after installing or upgrading components 7.9–7.16 to 7.17, you do not need to change the default functional level. Each release’s What’s new article indicates any change in the default functional level.

The selected functional level affects the list of machines above it. In the list, a tooltip next to each entry indicates whether the machine’s VDA is compatible with the catalog at that functional level.

Messages are posted on the page if the VDA on each machine does not meet or exceed the minimum functional level selected. You can continue with the wizard. Those machines will likely not be able to register with a Controller later. Alternatively, you can:

• Remove the machines containing older VDAs from the list, upgrade their VDAs and then add them back to the catalog.
• Choose a lower functional level that prevents access to the latest product features.

A message is also posted if a machine was not be added to the catalog because it is the wrong machine type. Examples include attempting to add a server to a single-session OS catalog, or adding a single-session OS machine originally created for random allocation to a catalog of static machines.

Important:

At release 1811, an extra functional level was added: 1811 (or newer). That level is intended for use with future Citrix Virtual Apps and Desktops features. The 7.9 (or newer) selection remains the default. That default is valid for all deployments now.

If you select 1811 (or newer), any earlier VDA versions in that catalog are unable to register with a Controller. However, if the catalog contains only VDAs at version 1811 or later supported versions, they are all eligible to register. This includes catalogs containing VDAs configured for later Citrix Virtual Apps and Desktops releases, including version 1903 and other 19XX releases prior to the current release.

Configure cache for temporary data

Caching temporary data locally on the VM is optional. You can enable use of the temporary data cache on the machine when you use MCS to manage pooled (not dedicated) machines in a catalog. If the catalog uses a connection that specifies storage for temporary data, you can enable and configure the temporary data cache information when you create the catalog.

Important:

This feature requires a current MCS I/O driver. Installing this driver is an option when you install or upgrade a VDA. By default, that driver is not installed.

You specify whether temporary data uses shared or local storage when you create the connection that the catalog uses. For more information, see Connections and resources. To configure a cache for temporary data on each machine, you can use the following two options: Memory allocated to cache (MB) and Disk cache size (GB). By default, the two options are cleared. To enable the Memory allocated to cache (MB) option, select the Disk cache size (GB) check box. If the Disk cache size check box is not selected, the Memory allocated to cache option is grayed out. Depending on the connection type, the default values for these options might differ. Generally, the default values are sufficient for most cases. However, take into account the space needed for:

• Temporary data files created by Windows itself, including the Windows page file.
• User profile data.
• ShareFile data that is synced to users’ sessions.
• Data that might be created or copied by a session user or any applications users might install inside the session.

To configure a cache for temporary data on each machine, be aware of the following three scenarios:

• If you don’t select the Disk cache size check box and the Memory allocated to cache check box, temporary data is not cached. It is directly written to the difference disk (located in the OS storage) for each VM. (This is the provisioning action in version 7.8 and earlier.)
• If you select the Disk cache size check box and don’t select the Memory allocated to cache check box, temporary data is directly written to the cache disk, using a minimal amount of memory cache.
• If you select the Disk cache size check box and the Memory allocated to cache check box, temporary data is initially written to the memory cache. When the memory cache reaches its configured limit (the Memory allocated to cache value), the oldest data is moved to the temporary data cache disk.

Important:

• If the disk cache runs out of space, the user’s session becomes unusable.
• This feature is not available when using a Nutanix host connection.
• You cannot change the cache values in a machine catalog after the machine is created.

Note:

• The memory cache is part of the total amount of memory on each machine. Therefore, if you enable the Memory allocated to cache option, consider increasing the total amount of memory on each machine.
• Changing the Disk cache size from its default value can affect performance. The size must match user requirements and the load placed on the machine.

NIC

This page does not appear when you are creating Remote PC Access catalogs.

On the Network Interface Cards page, if you plan to use multiple NICs, associate a virtual network with each card. For example, you can assign one card to access a specific secure network, and another card to access a more commonly used network. You can also add or remove NICs from this page.

Machine accounts

This page appears only when creating Remote PC Access catalogs.

On the Machine Accounts page, specify the Active Directory machine accounts or Organizational Units (OUs) to add that correspond to users or user groups. Do not use a forward slash (/) in an OU name.

When adding OUs, you can do the following if the domain is not shown in the list:

• Search for it using an exact match.
• Browse all domains to find it.

You can choose a previously configured power management connection or elect not to use power management. If you want to use power management but a suitable connection hasn’t been configured yet, you can create that connection later and then edit the machine catalog to update the power management settings.

Computer accounts

This page appears only when using MCS to create VMs.

Each machine in the catalog must have a corresponding Active Directory computer account. On the Computer Accounts page, indicate whether to create accounts or use existing accounts, and the location for those accounts.

• If you create accounts, you must have permission to create computer accounts in the OU where the machines reside.

  Select a domain for those accounts. If the domain is not shown in the list, you can do the following:

  • Search for it using an exact match.
  • Browse all domains to find it.

  Specify the account naming scheme for the machine, using hash marks to indicate where sequential numbers or letters appear. Do not use a forward slash (/) in an OU name. A name cannot begin with a number. For example, a naming scheme of PC-Sales-## (with 0-9 selected) results in computer accounts named PC-Sales-01, PC-Sales-02, PC-Sales-03, and so on.

• If you use existing accounts, either browse to the accounts or click Import and specify a .csv file containing account names. The imported file content must use the format:

[ADComputerAccount]
ADcomputeraccountname.domain
...
<!--NeedCopy-->

Ensure that there are enough accounts for all the machines you’re adding. Studio manages these accounts, so either allow Studio to reset the passwords for all the accounts or specify the account password, which must be the same for all accounts.

For catalogs containing physical machines or existing machines, select or import existing accounts. Assign each machine to both an Active Directory computer account and to a user account.

For machines created with Citrix Provisioning, computer accounts for target devices are managed differently; see the Citrix Provisioning documentation.

Summary, name, and description

On the Summary page, review the settings you specified. Enter a name and description for the catalog. This information appears in Studio.

When you’re done, click Finish to start the catalog creation.

Troubleshoot

Important:

After creating the machine catalog using Citrix Studio, you can no longer use the Get-ProvTask PowerShell command to retrieve the tasks associated with machine catalog creation. This restriction is a result of Studio deleting those tasks after machine catalog creation regardless of whether the catalog is created successfully.

Citrix recommends collecting logs to help the Support team provide solutions. When using Citrix Provisioning, use the following procedure to generate log files:

1. On the master image, create the following registry key with the value of 1 (as a DWORD (32-bit) value): HKLM\Software\Citrix\MachineIdentityServiceAgent\LOGGING.

2. Shut down the master image and create a snapshot.

3. On the Delivery Controller, run the following PowerShell command: Set-ProvServiceConfigurationData -Name ImageManagementPrep_NoAutoShutdown -Value $True.

4. Create a catalog based on that snapshot.
5. When the preparation VM is created on the hypervisor, log in and extract the following files from the root of C:\: Image-prep.log and PvsVmAgentLog.txt.
6. Shut down the machine, at which point it reports the failure.
7. Run the following PowerShell command to re-enable auto shutdown of the image preparation machines: Remove-ProvServiceConfigurationData -Name ImageManagementPrep_NoAutoShutdown.

Image preparation issues

Because MCS creates many machines from a single image, some steps are performed to ensure that all machines are unique and correctly licensed. Image preparation is a part of the catalog creation process. This preparation ensures that all provisioned machines have unique IP addresses and correctly announce themselves to the KMS server as unique instances. Within MCS, image preparation occurs after selecting the master image snapshot. A copy is made to enable the catalog to isolate itself from the selected machine. A preparation VM is created, based on the original VM, but with the network connection disconnected. Disconnecting the network connection prevents conflicts with other machines, while ensuring that prepared VM is only attached to the newly copied disk.

A small instruction disk, containing the steps required to run the image preparation, is attached to the prepared VM. This prepared VM starts and the image preparation process begins. Image preparation includes the following processes:

• Enable DHCP. Enabling DHCP ensures that provisioned machines don’t cause IP address conflicts. DHCP is enabled on all network cards.
• Microsoft Windows KMS Rearm. Rearming KMS ensures that Microsoft Windows is correctly licensed. The rearmed OS is invoked so it is correctly reported as a new instance to the KMS license server.
• Microsoft Office KMS Rearm (if Microsoft Office is installed). Rearming Microsoft Office ensures that any version of Microsoft Office (2010+) is registered correctly with their KMS server. Once Microsoft Office rearm is invoked, it reports as a new instance to the KMS license server.

Tip:

When the image preparation process finishes, the instruction disk is obtained from the hypervisor. The hypervisor contains the information gleaned from the image preparation process.

There are various reasons that the image preparation stage can fail. A failure message similar to the following appears:

These failures are discussed below.

Enable DHCP

These failure cases are caused by network cards that do not support static IP addresses. For example, earlier versions of Dell SonicWall network cards. The operation failed as a SonicWall card is a firewall network card, so setting the card to DHCP makes no sense as that only supports DHCP. This was fixed later versions of Citrix Virtual Apps and Desktops. However, if it is seen on other types of network cards it should be reported to Citrix via the forums or your support contact.

Note:

This PowerShell setting in the following examples is applied to the Citrix Virtual Apps and Desktops site, so it affects all new catalogs and image updates performed to existing catalogs.

If you encounter this issue with other network cards, you can resolve it by running a PowerShell command on the Delivery Controller:

Set-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps -Value EnableDHCP

Microsoft Office Rearm

There are various KMS rearm failures that can happen during the Microsoft Office rearm stage. The main failures are:

• Some Microsoft Office runtimes, for example, Access Runtime, can invoke the Office rearm, causing it to fail.
• A KMS version of Microsoft Office is not installed.
• Rearm count exceeded.

If the error is a false positive, you can resolve it by running the following PowerShell command on the Delivery Controller:

Set-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps -Value OfficeRearm

Microsoft Windows Rearm

Various KMS failures can happen during the Microsoft Windows rearm stage. The main failures are:

• The version of Windows installed is not activated using KMS. For example, it is using a Multiple Activation Key (MAK).
• Rearm count exceeded.

If the version of Microsoft Windows is correctly licensed, you can clear OS rearm by running the following PowerShell command on the Delivery Controller:

Set-ProvServiceConfigurationData -Name ImageManagementPrep_Excluded_Steps -Value OsRearm

Instances of complete failure

The image preparation machine is not connected to the network by design, this means that sometimes the image preparation stage can only report a complete failure. An example of this failure type resembles:

The main reasons for a complete failure are:

Virtual Delivery Agent (VDA) is not installed, or VDA version 5.x is installed

If the VDA 7.x is not installed on the master image, then image preparation times out after 20 minutes and report the above error. This is because there is no software installed on the master image to run the image preparation stage and report success or failure. To resolve this, make sure the VDA (minimum version 7) is installed on the snapshot selected as the master image.

DISKPART SAN Policy

The whole image preparation stage can fail due to the DISKPART SAN policy set on the master image. If it is not set to bring the image preparation instructions disk online, the machine is shut down and Image preparation reports a failure after 20 minutes. To check this on the master image run the following commands:

C:\>; Diskpart.exe
DISKPART>; San
<!--NeedCopy-->

This command returns the current policy. If it is not Online All, change it by running the following command:

DISKPART>; San policy=OnlineAll

Shut down the master image, create a snapshot of that machine and then use that as the base MCS image.

If image preparation fails for another reason

If image preparation is failing and there is no clear reason for failure, you can bypass the image preparation process when creating an MCS catalog. However, bypassing this process can cause issues with KMS licensing and networking (DHCP) on your site. Use the following PowerShell command:

Set-ProvServiceConfigurationData -Name ImageManagementPrep_DoImagePreparation -Value $false
<!--NeedCopy-->

Whenever possible, collect logs for the Citrix Support team Either report the issue to Citrix via the forums or via your support contact. To collect logs:

1. On the master image create the following registry key with the value of 1 (as a “DWORD (32-bit) value”): HKLM\Software\Citrix\MachineIdentityServiceAgent\LOGGING.
2. Shut down the master image and create a snapshot. On the Delivery Controller, start PowerShell, with the Citrix PowerShell snap-ins loaded, and run Set-ProvServiceConfigurationData -Name ImageManagementPrep_NoAutoShutdown -Value $True.
3. Create a catalog based on that snapshot.
4. When the preparation VM is created on the hypervisor, log in and extract from the root of C::

Image-prep.log
PvsVmAgentLog.txt
<!--NeedCopy-->

Shut the machine down. At this point it reports the failure.

Run from following PowerShell command to re-enable auto shutdown of the image preparation machines:

Remove-ProvServiceConfigurationData -Name ImageManagementPrep_NoAutoShutdown

Where to go next

If this is the first catalog created, Studio guides you to create a delivery group.