Citrix DaaS

Create machine catalogs

November 4, 2024

Contributed by:

C C

Note:

This article describes how to create catalogs using Studio. If you’re using Quick Deploy to create Azure resources, follow the guidance in Create catalogs using Quick Deploy.

Collections of physical or virtual machines are managed as a single entity called a machine catalog. Within a machine catalog, all machines share a common operating system type, which can be either multi-session OS or single-session OS, such as Windows or Linux-based systems.

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

Overview

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

If you use MCS to provision VMs, you provide an image (or snapshot) to create identical VMs in the catalog. Before you create the catalog, you must set up a hosting connection for the first time to the hypervisor or cloud service of choice and then you must create and configure the master image on the same. Configuring the master image requires tasks such as domain joining when necessary, installing required drivers, applications to be published, and deploying the Virtual Delivery Agent (VDA) on the image.
After you create the master image, you then create the machine catalog in Studio. You select that image (or a snapshot of an image), 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 to import these VMs into the catalog.

When using MCS to create the first catalog, you specify a hosting unit that you created previously. Hosting unit provide resource configuration for you to create virtual machine. Later (after you create your first catalog and delivery group), you can change information about that hosting unit or its parent host connection or create more connections and hosting units.

If a Cloud Connector is not operating properly, MCS provisioning operations (such as catalog updates) take longer than usual, and the management interface’s performance degrades significantly.

RDS license check

Creation of a machine catalog containing Windows multi-session OS machines includes an automatic check for valid Microsoft RDS licenses. The catalog is searched for a powered-on and registered machine to do the check on.

If a powered-on and registered machine cannot be found, a warning is displayed, explaining that the RDS licensing check cannot be performed.
If a machine is found and an error is detected, Studio displays a warning message for the catalog containing the detected issue. To remove an RDS license warning from a catalog (so that it no longer appears in the display), select the catalog. Select Remove RDS license warning. When prompted, confirm the action.

VDA registration

A VDA must be registered with a Cloud Connector to be considered when launching brokered sessions. Unregistered VDAs can result in underutilization of otherwise available resources. There are various reasons that a VDA might not be registered, many of which you can troubleshoot. Troubleshooting information is provided in the catalog creation wizard, and after you add a catalog to a delivery group.

In the catalog creation wizard, after you add existing machines, 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, you can either remove that machine (using the Remove button), or add the machine. For example, if a message indicates that information cannot be obtained about a machine (perhaps because it was never registered), you might choose to add the machine anyway.

For more information about VDA registration troubleshooting, see CTX136668.

MCS catalog creation summary

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

If you select an 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, full copy of the snapshot or master image 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 (noted before), 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 differencing 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.

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 base master 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. In XenServer, VMware, and SCVMM virtualization environments, MCS places Write-back cache (WBC) disk on the same storage location as OS disk if you configure the available OS storage list the same as the available temporary storage list while creating a host connection.
- 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:
- XenServer IntelliCache creates a Read Disk on local storage for each XenServer. This option saves on IOPS against the 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 the 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

The Machine Creation Services (MCS) storage optimization feature is also known as MCS I/O. This feature is only available on Azure, GCP, XenServer, VMware, and SCVMM.

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:

MCS I/O no longer supports RAM only cache. Specify a disk size during machine catalog creation.
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.
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.

Enable MCS storage optimization updates

To enable the MCS I/O storage optimization feature, upgrade the Delivery Controller and the VDA to the latest version of Citrix DaaS.

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.

For information on assigning a drive letter to write-back cache disk, see Assign a specific drive letter to MCS I/O write-back cache disk.

Prepare a master image on the hypervisor or cloud service

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 and cloud service providers might use different terms.
Ensure that the hypervisor or cloud service 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 of VDA 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 MCS, do not run Sysprep on master images.

To prepare a master image:

Using your hypervisor’s management tool, create a master image and then install the operating system, and 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 from Studio. Configure the amount of hard disk space needed for desktops and applications. That value cannot be changed later or in the catalog.
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.
Install and configure the software listed above on the master image.
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.
Citrix recommends that you create and name a snapshot of your master image so that it can be identified later. If you specify a master image rather than a snapshot when creating a catalog, the management interface creates a snapshot, but you cannot name it.

Volume licensing activation

MCS supports volume licensing activation to automate and manage the activation of Windows operating systems and Microsoft Office. The three models that MCS supports for volume licensing activation are:

Key Management Service (KMS)
Active Directory-based activation (ADBA)
Multiple Activation Key (MAK)

You can change the activation setting after you create the machine catalog.

Key Management Service (KMS)

The KMS is a lightweight service that does not require a dedicated system and can easily be co-hosted on a system that provides other services. This functionality is supported on all Citrix supported Windows versions. During image preparation, MCS does the Microsoft Windows and Microsoft Office KMS rearm. You can skip rearm by running the command Set-Provserviceconfigurationdata. For more information on Microsoft Windows KMS Rearm and Microsoft Office KMS Rearm during image preparation, see Machine Creation Services: Image Preparation Overview and Fault-Finding. For more information on KMS activation, see Activate using Key Management Service.

Note:

All machine catalogs created after running the command Set-Provserviceconfigurationdata have the same setting as provided in the command.

Active Directory-based activation (ADBA)

ADBA enables you to activate machines through their domain connections. Machines are immediately activated when they join the domain. These machines remain activated as long as they remain joined to the domain and in contact with it. This functionality is supported on all Citrix supported Windows versions. For more information on Active directory-based activation, see Activate using Active Directory-based activation.

Multiple Activation Key (MAK)

MAK is a way of activating volume and authenticating the Windows system with the help of the Microsoft server. You must buy the MAK key from Microsoft which is assigned with a fixed number of activation counts. Every time a Windows system is activated, the activation count reduces. There are two ways of activating the system:

Online Activation: If the Windows system that you want to activate has internet access, the system automatically activates the Windows on installing the product key. This process reduces the activation count by 1 for the corresponding MAK.
Offline Activation: If the Windows system is not able to connect to the internet to do the online activation, MCS gets a confirmation id and an installation id from the Microsoft server to get the Windows system activated. This way of activation is useful for non-persistent machine catalogs.

Note:

MCS doesn’t support Microsoft Office activation using MAK.

The minimum VDA version required is 2303.

Key requirements

The Delivery Controller must have internet access.
Create a new catalog if the new image to be updated has a different MAK Key from the original.
Install the MAK key on the master image. See Deploy MAK Activation for the steps to install MAK Key on a Windows System.
If you are not using image preparation:
1. Add the registry DWORD value Manual under Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\SoftwareProtectionPlatform\Activation.
2. Set the value to 1.

Activation Counts

To view the number of activations remaining for MAK Key or to check if a VM is consuming two or more activations, use the Volume Activation Management Tool (VAMT). See Install VAMT.

Activate the Windows system using MAK

To activate the Windows system using MAK:

Install the product key on the master image. This step consumes one activation count.
Create an MCS machine catalog.
If you aren’t using image preparation:
1. Add the registry DWORD value Manual under Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\SoftwareProtectionPlatform\Activation.
2. Set the value to 1.
This method disables the option of online activation.
Add VMs to the machine catalog.
Power on the VMs.
Depending on whether it’s online or offline activation, the Windows system is activated.
- If the activation is online, the Windows system is activated after the product key is installed.
- If the activation is offline, MCS communicates with provisioned VMs to get the activation status of the Windows system. MCS then retrieves a confirmation id and an installed id from the Microsoft server. These IDs are used to activate the Windows system.

Troubleshooting

If the provisioned VM is not activated with the installed MAK Key, run Get-ProvVM or Get-ProvScheme command on a PowerShell window.

The Get-ProvScheme command: See the parameter WindowsActivationType associated with the MCS machine catalog from the latest master image.
The Get-ProvVM command. See the parameters WindowsActivationType, WindowsActivationStatus, WindowsActivationStatusErrorCode, and WindowsActivationStatusError.

You can check the error and verify the steps to resolve the issue.

Create a machine catalog using Studio

Before creating a catalog:

Ensure that you have created a connection to the hypervisor, cloud service, other resource that hosts your machines.
If you have created a master image to provision machines. Ensure that you have installed a VDA on that master image.

Note:

When you are using a cloud service or hypervisor to host VMs, the catalog creation wizard might contain extra pages specific to that host. For example, when using an Azure Resource Manager master image, the catalog creation wizard contains a Storage and License Types page. For host-specific information, see the specific articles as mentioned in Where to go next.

Launch the catalog creation wizard

Sign in to Citrix Cloud.
In the DaaS tile, click Manage to open Studio.
Select Machine Catalogs in the left pane.
If this is the first catalog being created, you are guided to the correct selection (such as “Set up the machines and create machine catalogs to run apps and desktops”). The catalog creation wizard opens.
If you already created a catalog and want to create another, follow these steps:
1. To organize catalogs using folders, create folders under the default Machine Catalogs folder. For more information, see Create a catalog folder.
2. Select the folder where you want to create the catalog, and then click Create Machine Catalog. The catalog creation wizard opens.

The wizard walks you through the pages described in the following sections. The pages you see may differ, depending on the selections you make, and the connection (to a host) you use. Hosts / virtualization resources lists information sources for the supported host types.

Select a machine type

Each catalog must contain machines of only one OS type. Select one of the following on the Machine Type page:

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 Windows and Linux operating systems.
Single-session OS: A single-session OS catalog provides VDI desktops that you can assign to 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.

Select machine management options

Note:

The page Machine Management does not appear if you select Remote PC Access on the Machine Type page.

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

Select one of the options to indicate how machines must be power managed:

Machines that are power managed (for example, virtual machines or blade PCs): This option is available only if you already configured a connection to a hypervisor or cloud service.
Machines are not power managed (for example, physical machines)

If you select the option Machines that are power managed (for example, virtual machines or blade PCs), then select a tool to create VMs:

Citrix Provisioning Technology
- Citrix Machine Creation Services (MCS) Creates a catalog of VMs provisioned and imaged using MCS. MCS copies images cloned from a master image to those VMs.
- Citrix Provisioning Services (PVS) Creates a catalog of VMs provisioned using MCS and imaged using PVS. Those VMs serve as PVS target devices and the PVS server can stream a single shared disk image to them.
  Note:
  - This option is available only for PVS sites registered with Citrix Cloud and is currently limited to Azure resources.
  - While you create a Citrix Provisioning catalog on the Target Device page, you might see that in the drop-down menu to select the farm and site for the machines to be provisioned, there are farms and sites listed that no longer exist. As a workaround, you can run the PowerShell command Unregister-HypPvsSite to remove the farms and sites from the database. For information on the PowerShell command, see Unregister-HypPvsSite.
Other service or technology 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.

Note:

For Linux OS machines, see Create Linux VDAs using Machine Creation Services (MCS).

Select a desktop experience

Note:

The options on the Desktop Experience page varies according to the machine type that you select on the Machine Type page.

For Multi-session OS machines, users are assigned a random desktop each time they log in. You get the following options on the Desktop Experience page:
- Save changes on the local disk of the machine hosting virtual desktops: Persistent
- Discard all changes and clear virtual desktops when the user logs off: Non-persistent
Note:

For persistent multi-session machines, changes users make to the desktops will be saved and accessible to all authorized users.
For single-session OS machines, you get the following options on the Desktop Experience page:
- Connect to a new (random) desktop each time the users log in.
- Connect to the same (static) desktop each time the users log in.
You can further decide whether changes made by users will be saved or discarded after they log off.

Select an image and a machine profile

Note:

This page appears only if you select Citrix Machine Creation Services (MCS) on the Machine Management page.

The options available on this page vary according to the hypervisor or cloud service.

Follow these steps to complete the settings on the page:

Select an image type for the machine catalog, and then select an image. Two types of images are available:
- Master image: A snapshot or VM created as the master image. It undergoes automatic image preparation at the start of catalog creation. If needed, you can add a note for the selected image.
  Note:
  - When you are using MCS, do not run Sysprep on master images.
  - If you specify a master image rather than a snapshot, the management interface creates a snapshot, but you cannot name it.
  - 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.
  - To update images within an image node, select it in the tree, and then click the Refresh option at the top right corner. If you don’t select any image node, clicking Refresh updates all images in the tree. To clear a selected node in the tree, hold CTRL and then click the node.
- Prepared image: An image that has undergone image preparation, ready for direct use in VM creation. Opting for prepared images rather than master images for catalog creation ensures faster and more reliable machine catalog creation, along with streamlined image lifecycle management.
  Note:
  - VMs created using prepared images don’t support hibernation.
  - Currently, creating catalogs using prepared images are available only in Azure and VMware environments.
  For more information about how to create prepared images, see Image management (Preview).
For more information on image preparation, see Machine Creation Service: Image Preparation Overview and Fault-Finding.
To inherit VM settings from a machine profile, select Use a machine profile, and then select a VM or ARM template spec (specific to Azure) to use as the machine profile.

Note:

Currently, using machine profiles is restricted to Azure, AWS, and GCP VMs.
For AWS deployments, you can select a launch template as the machine profile.
Select the minimum functional level for the catalog. To enable the use of the latest product features, ensure that the master image has the latest VDA version installed.

Configure the machines

Note:

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

This page does not appear if you select Remote PC Access on the Machine Type page.

You can create an empty catalog, which means the catalog contains no machines.

When using MCS to create machines:
- Specify how many virtual machines to create. Enter 0 (zero) if you do not want to create any. Later, to create VMs for an empty catalog, you can perform Add machines.
- Choose the amount of memory (in MB) each VM has.
  
  Important:
  
  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 you indicate on the Desktop Experience page that user changes to static desktops should be saved on a separate Personal vDisk, then specify the virtual disk size in GB and the drive letter.
- If your deployment uses more than one zone (resource location), you can select a zone for the catalog.
- If you’re creating static desktop VMs, select a virtual machine copy mode. See Virtual machine copy mode.
- If you’re creating random non-persistent desktop VMs, you can enable and configure the write-back cache for temporary data on machines to improve I/O performance. For more information, see Configure cache for temporary data.
When using other tools to provide machines:

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

Tip:

To add users, you can browse to the users or enter a semicolon-separated list of user names manually. If the users are in Active Directory, enter the names directly. If not, enter the names in this format: <identity provider>:<user name>. Example: AzureAD:username.

After you add or import names, you can use the Remove button to delete names from the list while you are still on this wizard page.
When using other tools (not MCS):

An icon and tooltip for each machine added (or imported) help identify machines that might not be eligible to add to the catalog, or be unable to register with a Cloud Connector.

Virtual machine copy mode

The copy mode that 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.

Configure cache for temporary data

When using MCS to manage random non-persistent machines in a catalog, you can enable write-back cache for machines to improve I/O performance.

Write-back cache is referred to as MCSIO. For more information, see this blog article.

Prerequisites

To enable write-back cache, the catalog must meet these requirements:

Uses a connection that specifies storage for temporary data. For more information, see Connections and resources.
VDAs must be at least version 7.9 and installed with a current MCSIO driver.

Note:

You can install this driver when you install or upgrade a VDA. By default, that driver isn’t installed.
To enable drive letter assignment for disk caches, VMs must meet the following more requirements:
- Operating System: Windows
- VDA version: 2305 or later

Considerations

Write-back caches come in Memory cache and Disk cache. By default, their default values differ according to the connection type. Generally, the default values are sufficient for most cases; however, consider 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 may install inside the session.
Configuring the write-back cache with only a disk cache and no memory cache has been deprecated. To enable a cache for temporary data, we recommend selecting Disk cache size (GB) and Memory allocated to cache (MB) and specifying a size greater than 0 for the memory cache. Temporary data is initially written to the memory cache. When the memory cache reaches its configured limit, the oldest data is moved to the temporary data cache disk.
The memory cache is part of the total amount of memory on each machine. Therefore, if you enable the Memory cache size (MB) (recommended) checkbox, consider increasing the total amount of memory on each machine.
Changing Disk cache size (GB) from its default value can affect performance. The size must match user requirements and the load placed on the machine.

Important:

If the disk cache runs out of space, the user’s session becomes unusable.
If you clear the Disk cache size checkbox, no cache disk is created. In this case, specify a Memory allocated to cache value that is large enough to hold all of the temporary data. This is feasible only if large amounts of RAM are available for allocation to each VM.
If you clear both checkboxes, temporary data is not cached. It is written to the difference disk (located in the OS storage) for each VM. (This is the provisioning action in releases earlier than 7.9.)
Do not enable caching if you intend to use this catalog to create AppDisks.
You cannot change the cache values in a machine catalog after it is created.

Using CSV files to bulk add machines

If you use Studio, you can bulk add machines by using CSV files. The feature is available to all catalogs except catalogs created through MCS.

A general workflow to use CSV files to bulk add machines is as follows:

On the Machines page, select Add CSV File. The Add Machines in Bulk window appears.
Select Download CSV Template.
Fill out the template file.
Drag or browse to the file to upload it.
Select Validate to do validation checks on your import.
Select Import to complete.

For information about CSV file considerations, see Considerations when using CSV files to add machines.

You can also export machines from a catalog on the same Machines page. The exported CSV of machines can then be used as a template when adding machines in bulk. To export machines:

On the Machines page, select Export to CSV file. A CSV file containing a list of the machines is downloaded.
Open the CSV file to add or edit machines as needed. To add machines in bulk using the saved CSV file, see the previous section, Using CSV files to bulk add machines.

Note:

This feature is not available for Remote PC Access catalogs.

Export and import of machines in CSV files is only supported between catalogs of the same type.

Configure NICs for the machines

The page NICs does not appear if you select Remote PC Access on the Machine Type 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.

Note:

For VMWare deployments, when creating a machine catalog using a machine profile, the catalog inherits the NIC configurations from the machine profile. In such cases, if the machine profile has multiple NICs with the same network, then Studio uses the network from the hosting unit for NIC configurations.

Add machine accounts

Note:

This page Machine Accounts appears only when you select Remote PC Access on the Machine Type page.

Add the Active Directory machine accounts or Organizational Units (OUs). Do not use a forward slash (/) in an OU name.

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

You can also bulk add machines by using CSV files. A general workflow to do that is as follows:

On the Machine Accounts page, select Add CSV File. The Add Machines in Bulk window appears.
Select Download CSV Template.
Fill out the template file.
Drag or browse to the file to upload it.
Select Validate to do validation checks on your import.
Select Import to complete.

For information about CSV file considerations, see Considerations when using CSV files to add machines.

Configure identities for machines in the catalog

Note:

The page Machine Identities appears only when you do not select Remote PC Access on the Machine Type page and select Citrix Machine Creation Services (MCS) on the Machine Management page.

Each machine in the catalog must have a unique identity. This page lets you configure identities for machines in the catalog. The machines are joined to the identity after they are provisioned. You cannot change the identity type after you create the catalog.

A general workflow to configure settings on this page is as follows:

Select an identity from the list.
Indicate whether to create accounts or use existing ones, and the location (domain) for those accounts.

You can select one of the following options:

On-premises Active Directory: Machines owned by an organization and signed into with an Active Directory account that belongs to that organization. They exist on-premises.

Note:

By default, the domain where the resource (connection) resides is selected.
Azure AD joined: Machines owned by an organization and signed into with an Azure Active Directory account that belongs to that organization. They exist only in the cloud. For information about the requirements, limitations, and considerations, see Azure Active Directory joined.
Note:
- This option requires that the master image meets the operating system prerequisite. For more information, see the Microsoft documentation Microsoft Entra joined devices.
Hybrid Azure Active Directory joined. Machines owned by an organization and signed into with an Active Directory Domain Services account that belongs to that organization. They exist in the cloud and on-premises. For information about the requirements, limitations, and considerations, see Hybrid Azure Active Directory joined.
Note:
- Before you can use hybrid Azure Active Directory join, make sure that your Azure environment meets the prerequisites. See Configure Microsoft Entra hybrid join.
- This option requires that the master image meets the operating system prerequisite. For more information, see Microsoft Entra hybrid joined devices.
Non-domain-joined. Machines not joined to any domain. For information about the requirements and limitations, see Non-domain-joined.

Important:

If you select On-premises Active Directory or Hybrid Azure Active Directory joined as the identity type, each machine in the catalog must have a corresponding Active Directory computer account.

The Non-domain-joined identity type requires version 1811 or later of the VDA as the minimum functional level for the catalog. To make it available, update the minimum functional level.

The Azure Active Directory joined and Hybrid Azure Active Directory joined identity types require version 2203 or later of the VDA as the minimum functional level for the catalog. To make them available, update the minimum functional level.

An Azure AD service account is mandatory when creating Azure AD only or Azure AD catalogs enrolled in Microsoft Intune for persistent and non-persistent VMs.

If you create accounts, you must have permission to create computer accounts in the OU where the machines reside. Each machine in the catalog must have a unique name. Specify the account naming scheme for the machines that you want to create. For more information, see Machine account naming scheme.

Note:

Make sure that OU names do not use forward slashes (/).

If you use existing accounts, 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

Ensure that there are enough accounts for all the machines you are adding. Studio manages those accounts. Therefore, either allow that interface 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 or existing machines, select or import existing accounts and assign each machine to both an Active Directory computer account and to a user account.

Machine account naming scheme

Each machine in a catalog must have a unique name. You must specify a machine account naming scheme when creating a catalog. Use wildcards (hash marks) as placeholders for sequential numbers or letters that appear in the name.

When specifying a naming scheme, consider the following:

The maximum number of characters allowed is 15.
The naming scheme must contain at least one wildcard character. You must put all wildcards together.
The entire name, including wildcards, must contain at least 2 but no more than 15 characters. It must include at least one non-numeric and one # (wildcard) character.
The name must not include spaces or any of the following characters: ,~!@'$%^&.()}{\/*?"<>|=+[];:_"..
The name cannot end with a hyphen (-).
The number of characters increases with the increase in the number of machine accounts. For example, if you create 1,000 machine accounts with the scheme “veryverylong#”, the last account name created (veryverylong1000) contains 16 characters that exceed the number of maximum characters allowed.

You can indicate whether the sequential values are numbers (0-9) or letters (A-Z):

0-9. If selected, the specified wildcards resolve to sequential numbers.

Note:

If there is only one wildcard (#), the account names start with 1. If there are two, the account names start with 01. If there are three, the account names start with 001, and so on.
A-Z. If selected, the specified wildcards resolve to sequential letters.

For example, a naming scheme of PC-Sales-## (with 0-9 selected) results in accounts named PC-Sales-01, PC-Sales-02, PC-Sales-03, and so on.

Optionally, you can specify what the account names start with.

If you select 0-9, accounts are named sequentially, starting with the specified numbers. Enter one or more digits, depending on how many wildcards you use in the preceding field. For example, if you use two wildcards, enter two digits or more.
If you select A-Z, accounts are named sequentially, starting with the specified letters. Enter one or more letters, depending on how many wildcards you use in the preceding field. For example, if you use two wildcards, enter two letters or more.

Add domain credentials

Enter the credentials of an administrator who has permission to perform account operations. Detailed steps are as follows:

Click Enter credentials. The Windows Security page appears.
In the User name field, enter the administrator’s SamName, user name, or user SID. Depending on your input:
- If you enter a SamName, the Domain field populates automatically.
- If you enter a user name or SID, you can limit the user search to a specific domain by entering the domain name or SID in the Domain field.
Click Check name to check whether the user name is valid or unique.
In the Password field, enter the domain password of the administrator.
Click Done.

Note:

If the identity type you selected in Machine Identities is Hybrid Azure Active Directory joined, the credentials you enter must have been granted the Write userCertificate permission.

Select a Workspace Environment Management configuration set (optional)

The page WEM appears only when you use the Advanced or Premium edition of Citrix DaaS.

Select a Workspace Environment Management (WEM) configuration set to which you want to bind the catalog. A configuration set is a logical container used to organize a set of WEM configurations. Binding a catalog to a configuration set lets you use WEM to deliver the best possible workspace experience to your users.

Important:

Before you can bind a catalog to a configuration set, you must set up your WEM service deployment. Sign in to Citrix Cloud and then launch the WEM service. For more information, see Get started with Workspace Environment Management service.

If you already use WEM, the machines in the catalog that you are about to provision might already be present in a configuration set. For example, through Active Directory. In that case, we recommend that you use Active Directory consistently to perform the configuration and skip this configuration.

If the selected configuration set does not contain settings relating to the basic configuration of WEM, the following option appears:

Apply basic settings to configuration set. The option lets you quickly get started with WEM by applying basic settings to the configuration set. Basic settings include CPU spike protection, auto-preventing CPU spikes, and intelligent CPU optimization. To view the basic settings, click the here link. To modify them, use the WEM console.

Upgrade VDA (optional)

Important:

To ensure a smooth upgrade, make sure that you meet the prerequisites and review known issues before upgrading VDAs to CR or LTSR CU versions. See Upgrade VDAs using Studio.

When upgrading LTSR VDAs to LTSR Cumulative Update (CU) versions, make sure that the version of the VDA Upgrade Agents running on the VDAs is 7.36.0.7 or later. For more information, see Upgrade VDAs using Studio.

This feature applies to the following machine types:

MCS-provisioned persistent machines. You deploy them using Citrix Machine Creation Services on the Machine Management page during catalog creation.
Machines that are not created using MCS (for example, physical machines). You deploy them using Other service or technology on the Machine Management page during catalog creation.

For more information about the two options, see Machine management

On the VDA Upgrade page, select the VDA version to upgrade to. If specified, the VDAs in the catalog that have the VDA Upgrade Agent installed can upgrade to the selected version — immediately or at a scheduled time.

Note:

This feature supports upgrading only to the latest VDA. The time at which you create a VDA upgrade schedule or upgrade a VDA determines the latest version of the VDA.

After you configure VDA upgrade settings, it might take up to 15 minutes for the VDA Upgrade field to reflect the latest status. To show the VDA Upgrade column, click the Columns to display icon in the upper right corner, select Machine Catalog > VDA Upgrade, and click Save.

Choose a VDA track that suits your deployment:

Important:

You can switch between the CR VDA and the LTSR VDA as long as you switch from an earlier version to a later version. You cannot switch from a later version to an earlier version because that is considered a downgrade. For example, you cannot downgrade from 2212 CR to 2203 LTSR (any CU) but you can upgrade from 2112 CR to 2203 LTSR (any CU).

Latest CR VDA. Current Releases (CRs) deliver the latest and most innovative app, desktop, and server virtualization features and functionality.
Latest LTSR VDA. Long Term Service Releases (LTSRs) are recommended for large enterprise production environments that prefer to keep the same base version for an extended period.

After catalog creation, you can upgrade VDAs as needed. For more information, see Upgrade VDAs.

If you want to enable VDA upgrade later, you can return to this page by editing the catalog after catalog creation. For more information, see Configure VDA upgrade settings by editing a catalog.

Review the settings

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, select Finish to start the catalog creation.

In Machine Catalogs, the new catalog appears with an inline progress bar.

To view details of the creation progress:

Hover the mouse over the machine catalog.
In the tooltip that appears, click View details.

A step-by-step progress graph appears where you can see the following:
- History of steps
- Progress and running time of the current step
- Remaining steps

Create an MCS machine catalog using PowerShell commands

You can also create an MCS machine catalog using PowerShell commands. For more information, see:

Assign a specific drive letter to an MCS I/O write-back cache disk

You can assign a specific drive letter to an MCS I/O write-back cache disk. This implementation helps you to avoid conflicts between the drive letter of any applications that you use and the drive letter of MCS I/O write-back cache disk. To do this, you can use PowerShell commands. The supported hypervisors are Azure, GCP, VMware, SCVMM, and XenServer.

Note:

This feature requires VDA version 2305 or later.

Limitations

Applicable to only Windows operating system
Applicable drive letter for write-back cache disk: E to Z
Not applicable when Azure temporary disk is used as a write-back cache disk
Applicable only when you create a new machine catalog

Assign a drive letter to a write-back cache disk

To assign a drive letter to a write-back cache disk:

Open the PowerShell window.
Run asnp citrix*.
Create an identity pool if not already created. For information, see Creating a Catalog.

Create a provisioning scheme using the New-ProvScheme command with the property WriteBackCacheDriveLetter. For example:

New-ProvScheme -CleanOnBoot `
-HostingUnitName "<name>" `
-IdentityPoolName $schemeName `
-ProvisioningSchemeName $schemeName `
-InitialBatchSizeHint 1 `
-UseWriteBackCache -WriteBackCacheDiskSize 127 -WriteBackCacheMemorySize 256 -WriteBackCacheDriveLetter E `
-MasterImageVM "XDHyp:\HostingUnits\<name>\image.folder\abcd-resources.resourcegroup\MCSIOMasterVm_OsDisk_1_d3e2d6352xxxxxxxxx2130aa145ec77.manageddisk" `
-NetworkMapping @{"0"="XDHyp:\\HostingUnits\\name\\virtualprivatecloud.folder\\East US.region\\virtualprivatecloud.folder\\abcd-resources.resourcegroup\\abcd-resources-vnet.virtualprivatecloud\\default.network"} `
-ServiceOffering "XDHyp:\\HostingUnits\\<name>\\serviceoffering.folder\\Standard_D2s_v5.serviceoffering" `
-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="OsType" Value="Windows" />
<Property xsi:type="StringProperty" Name="StorageType" Value="Premium_LRS"/>
<Property xsi:type="StringProperty" Name="PersistWBC" Value="false" />
<Property xsi:type="StringProperty" Name="PersistOsDisk" Value="false" />
<Property xsi:type="StringProperty" Name="PersistVm" Value="false" />
<Property xsi:type="StringProperty" Name="WBCDiskStorageType" Value="Premium_LRS" />
<Property xsi:type="StringProperty" Name="UseTempDiskForWBC" Value="false" />
<Property xsi:type="StringProperty" Name="ResourceGroups" Value="abcd-group1" />
<Property xsi:type="StringProperty" Name="LicenseType" Value="Windows_Client" />
<Property xsi:type="StringProperty" Name="SchemaVersion" Value="2" />
</CustomProperties>'
<!--NeedCopy-->

Finish creating the catalog.

Important consideration about setting custom properties

Custom properties must be set correctly at New-ProvScheme and Set-ProvScheme in GCP and Azure environments. If you specify a non-existing custom property or properties, you get the following error message, and the commands fail to run.

Invalid property found: <invalid property>. Ensure that the CustomProperties parameter supports the property.

Important consideration about setting ProvScheme parameters

When you use MCS to create a catalog, you get an error if you:

Set the following New-ProvScheme parameters in unsupported hypervisors when you create a machine catalog:

Parameter	Supported hypervisor
`UseWriteBackCache`	VMware
	Hyper-V
	XenServer
	Azure
	GCP
`DedicatedTenancy`	Azure
	GCP
	AWS
`TenancyType`	Azure
	GCP
	AWS
`UseFullDiskCloneProvisioning`	VMware
	Hyper-V
	XenServer

Update the following Set-ProvScheme parameters after you create the machine catalog:
- CleanOnBoot
- UseWriteBackCache
- DedicatedTenancy
- TenancyType
- UseFullDiskCloneProvisioning

Add SIDs while creating virtual machines

You can add the parameter ADAccountSid to uniquely identify the machines while creating new virtual machines.

To do this:

Create a catalog with the supported identity type.

Add machines to the catalog using NewProvVM. For example:

New-ProvVM  -ProvisioningSchemeName "name"  -ADAccountSid @("SID ")  -RunAsynchronously
<!--NeedCopy-->

However, you cannot provision a machine with:

An AD account that is not in the catalog identity pool
An AD account that is not in available state

Validate configuration before creating an MCS machine catalog

You can validate configuration settings before creating an MCS machine catalog using the parameter -validate in New-ProvScheme command. After you run this PowerShell command with the parameter, you get an appropriate error message if there is an incorrect parameter used or a parameter has conflict with another parameter. You can then use the error message to resolve the issue and successfully create an MCS machine catalog using PowerShell. Currently, this feature is applicable to AWS, Azure, GCP, and VMware virtualization environments.

Note:

While validating, you must not create an actual MCS machine catalog. You must use the result of the command to fix the errors, and then create a successful catalog. Therefore, while running the New-ProvScheme command, use a fake identity pool name.

To validate the configuration, do the following steps:

Open a PowerShell window from the Delivery Controller host.
Run asnp citrix* to load the Citrix-specific PowerShell modules.

Run New-ProvScheme command and use the parameter -validate. Provide a fake identity pool name for the command to work. For example,

$result =New-ProvScheme  -CleanOnBoot -HostingUnitName "vSanRg" -IdentityPoolName "mptmpcatalogdemo" -InitialBatchSizeHint 1  -MasterImageVM "XDHyp:\HostingUnits\vSanRg\Windows19MasterImage.vm\Citrix_XD_NonMachineProfileWin19Machines.snapshot" -NetworkMapping @{"0"="XDHyp:\HostingUnits\vSanRg\\VM Network.network"} -ProvisioningSchemeName "MachineProfileW10Machines"  -Scope @()
-VMCpuCount 2  -VM
MemoryMB 6143 -MachineProfile "XDHyp:\HostingUnits\vSanRg\TRW-Win11-tpm-BL-TEMPLATE.template" -TenancyType Shared  -FunctionalLevel "L7_20" -Validate
$result.TerminatingError | Format-List -Property *
<!--NeedCopy-->

Error message:

ErrorData    : {[[ValidationFailureCount, xxx], [InvalidMemoryValue, The memory size provided 6143 must be a multiple of 4 MB and must be greater than or equal to 4 MB.], [InconsistentGuestOsSetting, The GuestOs setting - windows9_64Guest of the selected machine profile does not match with the setting - windows2019srv_64Guest of master image. Please select a machine profile that matches the GuestOs setting of the master image.], [InconsistentVtpmSetting, The vTPM setting of the selected machine profile does not match with the selected master image. Please select a machine profile that matches the vTPM setting of the master image.], [InconsistentFirmwareSetting, The firmware setting - efi of the selected machine profile does not match with the setting - bios of master image. Please select a machine profile that matches the firmware setting of the master image ErrorId      : ValidationFailure
ErrorMessage : ValidationFailure
Operation    : ValidatingInputs
<!--NeedCopy-->

After validating the configuration setting, you can create an MCS machine catalog with a real identity pool name and correct parameters.

Where to go next

For information on creating specific hypervisor catalogs, see:

If this is the first catalog created, you are guided to create a delivery group.

To review the entire configuration process, see Plan and build a deployment.

You can create a Citrix Provisioning catalog using Studio and PowerShell. This implementation provides you the following advantages:

A single unified console to manage both MCS and Citrix Provisioning catalogs.
Have new features for Citrix Provisioning catalogs, such as, identity management solution, on-demand provisioning and so on.

Currently, this feature is available only for Azure and VMware workloads. However, in VMware and XenServer environments, you can currently create the catalogs using only PowerShell commands. For more information, see Create Citrix Provisioning catalogs in Citrix Studio.

More information

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Create machine catalogs

November 4, 2024

Contributed by:

C C

November 4, 2024

Contributed by:

C C

Overview
MCS catalog creation summary
MCS storage considerations
Prepare a master image on the hypervisor or cloud service
Volume licensing activation
Create a machine catalog using Studio
Create an MCS machine catalog using PowerShell commands
Validate configuration before creating an MCS machine catalog
Where to go next
More information

Was this helpful

Create machine catalogs

Overview

RDS license check

VDA registration

MCS catalog creation summary

MCS storage considerations

Machine Creation Services (MCS) storage optimization

Enable MCS storage optimization updates

Prepare a master image on the hypervisor or cloud service

Volume licensing activation

Key Management Service (KMS)

Active Directory-based activation (ADBA)

Multiple Activation Key (MAK)

Key requirements

Activation Counts

Activate the Windows system using MAK

Troubleshooting

Create a machine catalog using Studio

Launch the catalog creation wizard

Select a machine type

Select machine management options

Select a desktop experience

Select an image and a machine profile

Configure the machines

Virtual machine copy mode

Configure cache for temporary data

Prerequisites

Considerations

Using CSV files to bulk add machines

Configure NICs for the machines

Add machine accounts

Configure identities for machines in the catalog

Machine account naming scheme

Add domain credentials

Select a Workspace Environment Management configuration set (optional)

Upgrade VDA (optional)

Review the settings

Create an MCS machine catalog using PowerShell commands

Assign a specific drive letter to an MCS I/O write-back cache disk

Limitations

Assign a drive letter to a write-back cache disk

Important consideration about setting custom properties

Important consideration about setting ProvScheme parameters

Add SIDs while creating virtual machines

Validate configuration before creating an MCS machine catalog

Where to go next

More information

In this article