Product documentation
Citrix DaaS
View PDF

Create a VMware catalog

May 2, 2025
Contributed by: 
C

Create machine catalogs describes the wizards that create a machine catalog.

Note:

Before creating a VMware catalog, you need to finish creating a connection to VMware. See Connection to VMware.

Create a machine catalog using a machine profile

You can create an MCS machine catalog using a machine profile. The source of the machine profile input is a VMware template. The machine profile captures the hardware properties from a VMware template and applies them to the newly provisioned VMs in the catalog.

Note:

  • Master image input (snapshot) and machine profile input (VMware template) must either be both vTPM enabled or both vTPM disabled. This rule applies to both New-ProvScheme and Set-ProvScheme.
  • If the master image is vTPM enabled, then the VMware template can only come from the same VM source as the master image.
  • Encrypted storage policy only supports full clone.

The VMware template in the machine profile must exist during the catalog life cycle to allow provisioning of VMs to the catalog. Without a VMware template, you cannot provision new VMs. When a VMware template gets deleted, you must supply a new template using the Set-ProvScheme command.

  • MCS captures the properties of a VMware template. You can create a new VMware template referencing stored properties of the VMware template using the Get-Provscheme command.
  • Alternatively, if the machine catalog and provisioned VMs exist, then an MCS provisioned machine can also be used to create a new VMware template.
  • When MCSIO is enabled, you can update the memory and disk cache sizes after creating the MCS catalogs.

Based on different OS, you can create a machine catalog with different configurations:

  • If Windows 11 is installed on the master image, then it is a requirement to have vTPM enabled for the master image. Therefore, the VMware template, which is a source of machine profile, must have vTPM attached to it.
  • If Windows 10 is installed on the master image with no vTPM attached, then you can create a machine catalog with non-vTPM VMware template as source for machine profile.

There is another configuration where you can create a machine catalog using full copy disk mode with machine profile template applied with encrypted storage policy.

To create a machine catalog using PowerShell commands with machine profile as input:

  1. Open a PowerShell window.
  2. Run asnp citrix* to load the Citrix-specific PowerShell modules.

  3. Run the following commands:

    • To create a machine catalog with vTPM attached VMware template as a source for machine profile input and windows11 installed master image:

       $identityPool = New-AcctIdentityPool
 -IdentityPoolName "<string>"
 -NamingScheme "<string>-###"
 -NamingSchemeType Numeric
 -Domain "<domain name"
 -ZoneUid "<Uid>"  -Scope @()
 <!--NeedCopy-->

       $provScheme =New-ProvScheme  -CleanOnBoot
 -HostingUnitName "vSanRg"
 -IdentityPoolName "<string>"
 -InitialBatchSizeHint 1
 -MasterImageVM "XDHyp:\HostingUnits\<hosting unit name>\<snapshot name>.snapshot"
 -NetworkMapping @{"0"="XDHyp:\HostingUnits\<hosting unit name>\\<network name>.network"}
 -ProvisioningSchemeName "<string>"
 -Scope @() -VMCpuCount 4  -VMMemoryMB 6144
 -MachineProfile "XDHyp:\HostingUnits\<hosting unit name>\<template name>.template"
 -TenancyType Shared
 -FunctionalLevel "L7_20"
 <!--NeedCopy-->

       $catalog = New-BrokerCatalog
 -AllocationType "Static"
 -PersistUserChanges  "OnLocal"
 -Description "<string>"  -IsRemotePC $False
 -MinimumFunctionalLevel 'L7_9' -Name "<catalog name>" -ProvisioningType 'MCS'
 -Scope @()  -SessionSupport "SingleSession"
 -ZoneUid "<Uid>"
 <!--NeedCopy-->

       Set-BrokerCatalog -Name "<string>"
 -ProvisioningSchemeId $provScheme.ProvisioningSchemeUid.Guid
 <!--NeedCopy-->

    • To create a machine catalog with non-vTPM VMware template as source for machine profile and Windows10 installed master image:

       $identityPool = New-AcctIdentityPool
 -IdentityPoolName "<string>"
 -NamingScheme "<string>-###"
 -NamingSchemeType Numeric
 -Domain "<domain name>"
 -ZoneUid "<Uid>"  -Scope @()
 <!--NeedCopy-->

       $provScheme =New-ProvScheme  -CleanOnBoot
 -HostingUnitName "<string>"
 -IdentityPoolName "<string>"
 -InitialBatchSizeHint 1
 -MasterImageVM "XDHyp:\HostingUnits\<hosting unit name>\<snapshot name>.snapshot"
 -NetworkMapping @{"0"="XDHyp:\HostingUnits\<hosting unit name>\\<string>.network"}
 -ProvisioningSchemeName "<string>"  -Scope @() -VMCpuCount 4  -VMMemoryMB 8192
 -MachineProfile "XDHyp:\HostingUnits\<hosting unit name>\<template name>.template"
 -TenancyType Shared  -FunctionalLevel "L7_20"
 <!--NeedCopy-->

       $catalog = New-BrokerCatalog
 -AllocationType "Static"
 -PersistUserChanges  "OnLocal"  -Description "<string>"  -IsRemotePC $False
 -MinimumFunctionalLevel 'L7_9' -Name "<string>" -ProvisioningType 'MCS' -Scope @()  -SessionSupport "SingleSession" -ZoneUid "<Uid"
 <!--NeedCopy-->

       Set-BrokerCatalog -Name "<string>"
 -ProvisioningSchemeId $provScheme.ProvisioningSchemeUid.Guid
 <!--NeedCopy-->

    • To create a machine catalog using Full copy disk mode with machine profile template applied with encrypted storage policy:

       $identityPool = New-AcctIdentityPool
 -IdentityPoolName "<string>"
 -NamingScheme "<string>-###"
 -NamingSchemeType Numeric
 -Domain "<domain name>"
 -ZoneUid "<Uid>"  -Scope @()
 <!--NeedCopy-->

       $provScheme =New-ProvScheme
 -HostingUnitName "<string>"
 -IdentityPoolName "<string>" -InitialBatchSizeHint 1
 -MasterImageVM "XDHyp:\HostingUnits\<hosting unit name>\<snapshot name>.snapshot"
 -NetworkMapping @{"0"="XDHyp:\HostingUnits\<hosting unit name>\\<string>.network"}
 -ProvisioningSchemeName "<string>"  -Scope @() -VMCpuCount 4  -VMMemoryMB 8192
 -MachineProfile "XDHyp:\HostingUnits\<hosting unit name>\<template name>.template"
 -TenancyType Shared  -FunctionalLevel "L7_20"
 -UseFullDiskCloneProvisioning
 <!--NeedCopy-->

       $catalog = New-BrokerCatalog
 -AllocationType "Static"
 -PersistUserChanges  "OnLocal"
 -Description "<string>"
 -IsRemotePC $False
 -MinimumFunctionalLevel 'L7_9' -Name "<string>" -ProvisioningType 'MCS' -Scope @()
 -SessionSupport "SingleSession" -ZoneUid "<Uid>"
 <!--NeedCopy-->

       Set-BrokerCatalog -Name "<string>"
 -ProvisioningSchemeId $provScheme.ProvisioningSchemeUid.Guid
 <!--NeedCopy-->

    • To update a machine profile, use the Set-ProvScheme command. For example:

       Set-ProvScheme -ProvisioningSchemeName 'name' -IdentityPoolName 'name' -MachineProfile 'XDHyp:\HostingUnits\<hosting unit name>\<template name>.template
 <!--NeedCopy-->

Check for multiple NICs

You get various error messages during the pre-flight checks for multiple NICs when using a machine profile and the NetworkMapping parameter in the New-ProvScheme and Set-ProvScheme commands.

The pre-flight checklist for multiple NICs is as follows:

  • Only NIC count from the machine profile template is used and validated. The network to which these NICs point towards, is not used or validated against the hosting unit networks.
  • If the NIC count in the machine profile template is greater than the number of networks in the hosting unit, you get an error message.

  • If the NIC count in the machine profile template is zero, you get an error message. When the NIC count in the machine profile template is one, then:

    • If no network mapping is specified in the New-ProvScheme or Set-ProvScheme command, and the hosting unit network is one, then the hosting unit network is used.
    • If a network mapping is specified, then the specified network mapping is used if it is valid.

  • When the NIC count in the machine profile template is greater than 1, or the hosting unit network count is greater than 1, then:

    • Valid network mapping is required in the command, and it should provide mapping for each NIC (that is, the NetworkMapping count must be the same as the machine profile NIC count).
    • Multiple NICs cannot be mapped to the same network in the hosting unit.
    • NetworkMapping count and machine profile NIC count must be less than or equal to the hosting unit network count.
    • NetworkMapping must be provided for each id from 0 to n-1, where n is the number of network adapters in the machine profile template.

Provision a Data disk on MCS created VM

A Data disk allows storage of persistent data like event logs, security traces, and application data. You can create and assign a persistent or non-persistent Data disk to an MCS created persistent or non-persistent VM of an MCS machine catalog in VMware.

Provision the Data disk from the master image. The prepared master image Data disk is stored in <Prov Scheme Name>-dataDisk-<datastoreId> folder.

You can create both machine profile and non-machine profile-based MCS catalog. For machine profile-based MCS catalog, you can use the same master image VM as the Data disk source for the machine profile.

The provisioned VM’s Data disk derives properties like storage policy and size from the master image. For machine profile based catalog, it can optionally use the VM template’s Data disk for deriving the properties. If the VM template doesn’t have a data disk, then Storage’s default policy is used.

The Data disk of the provisioned VM is created in the same directory as the OS and Identity disk.

Supported Data disk scenarios

Following are the supported OS disk and Data disk scenarios:

  • Persistent OS disk with persistent Data disk
  • Non-persistent OS Disk with persistent Data disk
  • Non-persistent OS Disk with non-persistent Data disk

Note:

A persistent machine catalog cannot have a non-persistent Data disk.

Limitations

The following operations are currently not supported:

  • Provisioning of more than one Data disk.
  • Resetting the Data disk.
  • Updating an MCS catalog with a Data disk to a non-Data disk MCS catalog. Similarly, updating an MCS catalog without a Data disk to a Data disk MCS catalog.

Key steps

  1. Create a master image VM with a Data disk in VMware. For a machine profile-based MCS catalog, you can use the same master image VM as the Data disk source for the machine profile.
  2. Create an MCS machine catalog with Data disk provisioned VMs using the New-ProvScheme PowerShell command. See Create a catalog with Data disk provisioned VMs.
  3. Add VMs to the catalog using the New-ProvVM PowerShell command.
  4. Log in to the VM to see if the Data disk is formatted correctly. If there is content on the Data disk referenced in the master image VM, then that content is also on the Data disk.

Create a master image VM with Data disk in VMware

  1. Create a VM with two hard disks. One is the OS disk and second is the Data disk. Follow this guide to add a New Hard Disk (Data disk) to an existing VM.
  2. Log in to the VM to initialize the disk, set the desired drive letter, and add the content.

Create a catalog with Data disk provisioned VMs

Include the following parameters in the New-ProvScheme PowerShell command to provision an MCS machine catalog with Data disk.

  • DataDisk: To Specify the path of the Data disk specified.

  • DataDiskPersistence: To indicate whether the DataDisk is persistent or non-persistent.

    The Data disk cannot be non-persistent if CleanOnBoot is false. You cannot change the value of DataDiskPersistence for a machine catalog once configured.

After you create the catalog, add VMs using the New-ProvVM command.

Image update

Run Publish-ProvMasterVMImage command to update the source of the OS and Data disk. After running the Publish-ProvMasterVMImage command:

  • The new VMs are created with the updated OS and Data disks.
  • The existing VMs’ non-persistent disks are updated on the next power cycle.
  • The existing VMs’ persistent disks are not updated on the next power cycle.

Delete the Data disk

If you delete the catalog, the Data disk is deleted unless you use forgetVM or purgeDBOnly option. If you delete the VM, the Data disk is deleted unless you use the forgetVM or purgeDBOnly option. These conditions are applicable to only persistent MCS machine catalogs.

Troubleshooting

If the catalog fails to create, see CTX294978.

Where to go next

More information

Create a VMware catalog
May 2, 2025
Contributed by: 
C
May 2, 2025
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.