Product documentation
Citrix Virtual Apps and Desktops
Service Current Release 2402 LTSR 2311 2308 2305 2303 2212 2209 2206 2203 LTSR 1912 LTSR
View PDF

Manage machine catalogs

September 23, 2024
Contributed by: 
C L

Introduction

You can add or remove machines from a machine catalog, rename, change the description, or manage a catalog’s Active Directory computer accounts.

Maintaining catalogs can also include making sure each machine has the latest OS updates. Including antivirus updates, operating system upgrades, or configuration changes.

  • Catalogs containing pooled random machines created using Machine Creation Services (MCS) maintain machines by updating the master image used in the catalog and then updating the machines. This method enables you to efficiently update large numbers of user machines.
  • For machines created using Citrix Provisioning, updates to machines are propagated through the virtual disk. See the Citrix Provisioning documentation for details.
  • For catalogs containing static, permanently assigned machines, and for Remote PC Access Machine catalogs, you manage updates to users’ machines outside of Studio. Perform this task either individually or collectively using third-party software distribution tools.

For information about creating and managing connections to host hypervisors, see Connections and resources.

Note:

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

About persistent instances

When updating an MCS catalog created using persistent, or dedicated instances, any new machines created for the catalog use the updated image. Pre-existing instances continue to use the original instance. The process of updating an image is done the same way for any other type of catalog. Consider the following:

  • With persistent disk catalogs, the pre-existing machines are not updated to the new image, but any new machines added to the catalog use the new image.
  • For non-persistent disk catalogs, the machine image is updated the next time the machine is reset.
  • With persistent machine catalogs, updating the image also updates the catalog instances that use it.
  • For catalogs that do not persist, if you want different images for different machines, the images must reside in separate catalogs.

Add machines to a catalog

Before you start:

  • Make sure the virtualization host has sufficient processors, memory, and storage to accommodate the additional machines.
  • Make sure that you have enough unused Active Directory computer accounts. If you are using existing accounts, the number of machines you can add is limited by the number of accounts available.
  • If you use Studio to create Active Directory computer accounts for the additional machines, you must have appropriate domain administrator permission.

To add machines to a catalog:

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a machine catalog and then select Add machines in the Actions pane.
  3. Select the number of virtual machines to add.
  4. If there are insufficient existing Active Directory accounts for the number of VMs you are adding, select the domain and location where the accounts are created. Specify an account naming scheme, 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.
  5. If you use existing Active Directory accounts, either browse to the accounts or click Import and specify a .csv file containing account names. Make sure that there are enough accounts for all the machines you’re adding. Studio manages these accounts. Either allow Studio to reset the passwords for all the accounts, or specify the account password, which must be the same for all accounts.

The machines are created as a background process, and can take much time when creating many machines. Machine creation continues even if you close Studio.

Delete machines from a catalog

After you delete a machine from a machine catalog, users can no longer access it, so before deleting a machine, ensure that:

  • User data is backed up or no longer required.
  • All users are logged off. Turning on maintenance mode stops new connections from being made to a machine.
  • Machines are powered off.

To delete machines from a catalog:

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select View Machines in the Actions pane.
  3. Select one or more machines and then select Delete in the Actions pane.

Choose whether to delete the machines being removed. If you choose to delete the machines, indicate if the Active Directory accounts for those machines are retained, disabled, or deleted.

Change a catalog description or change Remote PC Access settings

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select Edit Machine Catalog in the Actions pane.
  3. For Remote PC Access catalog, use the Power Management page to change the power management settings and select a power management connection. On the Organizational Units page, add or remove Active Directory OUs.
  4. On the Description page, change the catalog description.

Rename a catalog

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select Rename Machine Catalog in the Actions pane.
  3. Enter the new name.

Move a catalog to a different zone

If your deployment has more than one zone, you can move a catalog from one zone to another.

Moving a catalog to a different zone, other than the hypervisor containing the VMs in that catalog, affects performance.

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select Move in the Actions pane.
  3. Select the zone where you want to move the catalog.

Delete a catalog

Before deleting a catalog, ensure that:

  • All users are logged off and that no disconnected sessions are running.
  • Maintenance mode is turned on for all machines in the catalog so that new connections cannot be made.
  • All machines in the catalog are powered off.
  • The catalog is not associated a delivery group. In other words, the delivery group does not contain machines from the catalog.

To delete a catalog:

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select Delete Machine Catalog in the Actions pane.
  3. Indicate whether the machines in the catalog are deleted. If you choose to delete the machines, indicate whether the Active Directory computer accounts for those machines are retained, disabled, or deleted.

Manage Active Directory computer accounts in a catalog

To manage Active Directory accounts in a machine catalog, you can:

  • Free unused machine accounts by removing Active Directory computer accounts from single-session OS and multi-session OS catalogs. Those accounts can then be used for other machines.
  • Add accounts so that when more machines are added to the catalog, the computer accounts are already in place. Do not use a forward slash (/) in an OU name.

To manage Active Directory accounts:

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select Manage AD accounts in the Actions pane.

  3. Choose whether to add or delete computer accounts. If you add accounts, specify what to do with the account passwords: either reset them all or enter a password that applies to all accounts.

    You might reset passwords if you do not know the current account passwords; you must have permission to perform a password reset. When entering a password, the password is changed on the accounts as they are imported. When deleting an account, choose whether the account in Active Directory is kept, disabled, or deleted.

Indicate if Active Directory accounts are retained, disabled, or deleted when you remove machines from a catalog or delete a catalog.

Update a catalog

We recommend that you save copies or snapshots of master images before updating the machines in the catalog. The database keeps a historical record of the master images used with each machine catalog. Roll back, or revert, machines in a catalog to use the previous version of the master image. Perform this task if users encounter problems with updates you deployed to their desktops. This minimizes user downtime. Do not delete, move, or rename master images. You cannot revert a catalog to use them.

For catalogs that use Citrix Provisioning (formerly Provisioning Services), you must publish a new virtual disk to apply changes to the catalog. For details, see the Citrix Provisioning documentation.

After a machine is updated, it restarts automatically.

Update or create a master image

Before you update the machine catalog, either update an existing master image or create one on your host hypervisor.

  1. On your hypervisor, take a snapshot of the current VM and give the snapshot a meaningful name. This snapshot can be used to revert (roll back) machines in the catalog, if needed.
  2. If necessary, power on the master image, and log on.
  3. Install updates or make any required changes to the master image.
  4. Power off the VM.
  5. Take a snapshot of the VM. Give it a meaningful name that is recognized when the catalog is updated in Studio. Although Studio can create a snapshot, Citrix recommends that you create it using the hypervisor management console. Then select that snapshot in Studio. This process enables you to provide a meaningful name and description rather than an automatically generated name. For GPU master images, you can change the master image only through the Citrix Hypervisor console.

Update the catalog

To prepare and roll out the update to all machines in a catalog:

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select a catalog and then select Update Machines in the Actions pane.
  3. On the Master Image page, select the host and the image you want to roll out.
  4. On the Rollout Strategy page, choose when the machines in the machine catalog are updated with the new master image: on the next shutdown or immediately.
  5. Verify the information on the Summary page and then click Finish. Each machine restarts automatically after it is updated.

When updating a catalog using PowerShell SDK directly, rather than Studio, specify a hypervisor template (VMTemplates). Use this as an alternative to an image or a snapshot of an image.

Rollout strategy:

Updating the image on next shutdown will immediately affect any machines not currently in use, that is, machines that do not have an active user session. A system that is in use receives the update when the current active session ends. Consider the following:

  • New sessions cannot be launched until the update has completed on applicable machines.
  • For single-session OS machines, machines are immediately updated when the machine is not in use, or when users are not logged in.
  • For a multi-session OS with child machines, reboots do not occur automatically. They must be manually shut down and restarted.

Tip:

Limit the number of machines being rebooted by using the advanced settings for a host connection. Use these settings to modify the actions taken for a given catalog; advanced settings vary depending on the hypervisor.

Roll back an update

After you roll out an updated/new master image, you can roll it back. This process might be necessary if issues occur with the newly updated machines. When you roll back, machines in the catalog are rolled back to the last working image. Any new features that require the newer image are no longer available. As with the rollout, rolling back a machine includes a restart.

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select the catalog and then select Rollback machine update in the Actions pane.
  3. Specify when to apply the earlier master image to machines, as described in the preceding section for the rollout operation.

The rollback is applied only to machines that need to be reverted. Machines that have not been updated with the new/updated master image do not receive notification messages and are not forced to log off.

Upgrade a catalog or revert an upgrade

Upgrade the machine catalog after you upgrade the VDAs on the machines to a newer version. Citrix recommends upgrading all VDAs to the latest version to enable access to all the newest features.

Before upgrading a catalog:

  • If you’re using Citrix Provisioning, upgrade the VDA version. The provisioning console does not retain the VDA version. Citrix Provisioning communicates directly with the Citrix Virtual Apps and Desktops Setup Wizard to set the VDA version in the created catalog.

  • Start the upgraded machines so that they register with the Controller. This process lets Studio determine that the machines in the catalog need upgrading.

To upgrade a catalog:

  1. Select Machine Catalogs in the Studio navigation pane.
  2. Select the catalog. The Details tab in the lower pane displays version information.
  3. Select Upgrade Catalog. If Studio detects that the catalog needs upgrading, it displays a message. Follow the prompts. If one or more machines cannot be upgraded, a message explains why. Citrix recommends you resolve machine issues before upgrading the catalog to ensure that all machines function properly.

After the catalog upgrade completes, you can revert the machines to their previous VDA versions by selecting the catalog and then selecting Undo in the Actions pane.

Change the network setting for an existing provisioning scheme

You can change the network setting for an existing provisioning scheme so that the new VMs are created on the new subnetwork. Use the parameter -NetworkMapping in the Set-ProvScheme command to change the network setting.

Note:

This feature is supported on Citrix Virtual Apps and Desktops 2203 LTSR CU3 and later versions.

To change the network setting for an existing provisioning scheme, do the following:

  1. In the PowerShell window, run the command asnp citrix* to load the PowerShell modules.
  2. Run (Get-Provscheme -ProvisioningSchemeName "name").NetworkMaps to get to the network path that you want to change.

  3. Assign a variable to the new network setting. For example:

    $NewNetworkMap = @{“0”= “XDHYP:\HostingUnits\MyNetworks\Network 0.network”}
<!--NeedCopy-->
  4. Run Set-ProvScheme -ProvisioningSchemeName "name" -NetworkMapping $NewNetworkMap.
  5. Run (Get-Provscheme -ProvisioningSchemeName "name").NetworkMaps to verify the new network setting for the existing provisioning scheme.

Identify resources created by MCS

Following are the tags that MCS adds to the resources on each platform. The tags in the table are represented as “key”:”value”.

AWS

Resource name Tag
ID disk “Name”: “VMName_IdentityDisk”
  “XdConfig”: “XdProvisioned=true”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
Image “XdConfig”: “XdProvisioned=true”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
NIC “Description”: “XD Nic”
  “XdConfig”: “XdProvisioned=true”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
OS disk “Name”: “VMName_rootDisk”
  “XdConfig”: “XdProvisioned=True”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  [when AwsCaptureInstanceProperties = true] “Citrix Resource”: “”
  [when AwsCaptureInstanceProperties = true and AwsOperationalResourcesTagging = true] “CitrixOperationalResource”: “”
PrepVM “Name”: “Preparation - CatalogName - xxxxxxxxxx”
  “XdConfig”: “XdProvisioned=true”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  [when AwsCaptureInstanceProperties = true] “Citrix Resource”: “”
  [when AwsCaptureInstanceProperties = true and AwsOperationalResourcesTagging = true] “CitrixOperationalResource”: “”
Published snapshot “XdConfig”: “XdProvisioned=true”
  If not a snapshot for Volume Worker AMI, then “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
Template [when AwsCaptureInstanceProperties = true] “XdConfig”: “XdProvisioned=true”
  [when AwsCaptureInstanceProperties = true] “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  [when AwsCaptureInstanceProperties = true] “CitrixResource”: “”
  [when AwsCaptureInstanceProperties = true and AwsOperationalResourcesTagging = true] “CitrixOperationalResource”: “”
VM in catalog “XdConfig”: “XdProvisioned=true”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  [when AwsCaptureInstanceProperties = true] “CitrixResource”: “”
  [when AwsCaptureInstanceProperties = true] “aws:ec2launchtemplate:id”:“lt-xxxx”
  [when AwsCaptureInstanceProperties = true] “aws:ec2launchtemplate:version”: “n”
  [when AwsCaptureInstanceProperties = true and AwsOperationalResourcesTagging = true] “CitrixOperationalResource”: “”
Volume worker AMI “XdConfig”: “XdProvisioned=true”
Volume worker bootstraper “Name”: “XenDesktop Temp”
  “XdConfig”: “XdProvisioned=true”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  [when AwsCaptureInstanceProperties = true and AwsOperationalResourcesTagging = true] “CitrixVolumeWorkerBootstrapper”: “”
Volume worker instance “Name”: “Citrix.XD.Volumeworker-xxxx-xx-xx-xx-xxxx”
  “XdConfig”: “XdProvisioned=true”

Azure

Resource name Tag
ID disk “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
Image “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
NIC “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
OS disk “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
PrepVM “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
Published snapshot “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
Resource group “CitrixResource” : “Internal”
  CitrixSchemaVersion: 2.0
  “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
Storage account “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
VM in catalog “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”
WBC disk “CitrixProvisioningSchemeId” : “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “CitrixResource” : “Internal”

Note:

A VM is not visible in the Citrix inventory if a CitrixResource tag is added to identify it as a resource created by MCS. You can remove or rename the tag to make it visible.

Google Cloud Platform

Resource name Tag
ID disk “CitrixResource”: “internal”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
Image “CitrixResource”: “internal”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
OS disk “CitrixResource”: “internal”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
PrepVM “CitrixResource”: “internal”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
Published snapshot “CitrixResource”: “internal”
Storage bucket “Citrixresource”: “internal”
Template “CitrixResource”: “internal”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
VM in catalog “CitrixResource”: “internal”
  “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”. The plugin also adds this label for MCS provisioned VMs: “citrix-provisioning-scheme-id”: “provSchemeId”. You can use this label to filter by catalog in the GCP console.
WBC disk “CitrixResource”: “internal”
  CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”

Note:

A VM is not visible in the Citrix inventory if a CitrixResource tag is added to identify it as a resource created by MCS. You can remove or rename the tag to make it visible.

Citrix Hypervisor

Resource name Tag
Published base disk and its copy on each network or local storage “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
ID disk “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
OS disk “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
Prep VM “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
VM in catalog “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
WBC disk “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”

SCVMM

Resource name Tag
Prep VM Tag string: “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  Custom property entry: “XdConfig:“XdProvisioned=True”
VM in catalog Tag string: “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  Custom property entry: “XdConfig:“XdProvisioned=True”

VMware

Resource name Tag
Prep VM “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “XdConfig:“XdProvisioned=True”
VM in catalog “CitrixProvisioningSchemeId”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”
  “XdConfig:“XdProvisioned=True”

Troubleshoot

Manage machine catalogs
September 23, 2024
Contributed by: 
C L
September 23, 2024
Contributed by: 
C L

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.