Citrix Virtual Apps and Desktops service

Manage machine catalogs

Note:

This article describes how to manage catalogs using the Full Configuration interface. If you created the catalog using the Quick Deploy interface, and want to continue using that interface to manage the catalog follow the guidance in Manage catalogs in Quick Deploy.

Introduction

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

Catalog maintenance can also include the tasks of making sure that each machine has the latest OS updates, antivirus software updates, operating system upgrades, or configuration changes.

  • Catalogs containing pooled random machines created using Machine Creation Services (MCS) maintain machines by updating the image used in the catalog and then updating the machines. This method lets you update large numbers of user machines efficiently.
  • For catalogs containing static, permanently assigned machines, you can manage the image or template that those catalogs currently use but only machines you add to the catalogs later are created using the new image or template.
  • For Remote PC Access catalogs, you manage updates to users’ machines outside of the Full Configuration management interface. Perform this task individually or collectively using third-party software distribution tools.

For information about creating and managing connections to host hypervisors and cloud services, 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 only if the machine is restarted within Studio or PowerShell. If the machine is restarted from the hypervisor outside of Studio, the disk is not 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 (hypervisor or cloud service provider) 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 the Full Configuration management interface to create Active Directory computer accounts for the additional machines, you must have appropriate domain administrator permission.

To add machines to a catalog:

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a machine catalog and then select Add machines in the action bar.
  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 select Import and specify a .csv file containing account names. Make sure that there are enough accounts for all the machines you are adding. The Full Configuration interface manages these accounts. 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.

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

Use CSV files to bulk add machines to a catalog

Important:

This feature is available only in the Full Configuration management interface.

You can bulk add machines by using CSV files. The feature is available to all catalogs except catalogs created through MCS.

To bulk add machines to a catalog, complete the following steps:

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.

  2. Select a machine catalog and then select Add Machines in the action bar. The Add Machines window appears.

  3. Select Add CSV File. The Add Machines in Bulk window appears.

  4. Select Download CSV Template.

  5. Fill out the template file.

  6. Drag or browse to the file to upload it.

  7. Select Validate to perform validation checks on your import.

  8. Select Import to complete the process.

Considerations when using CSV files to add machines

When editing the CSV template file, keep the following in mind:

  • The feature gives you more flexibility to bulk add machines through a CSV file. In the file, you can add only machines (for use with user auto-assignments) or add machines along with user assignments. Type your data in the following format:

    • For machine account and user name (samName) pairs:

      • Domain\ComputerName1,Domain\Username1
      • Domain\ComputerName2,Domain\Username1;Domain\Username2
    • For machine accounts only:

      • Domain\ComputerName1
      • Domain\ComputerName2
    • For VM and user name pairs:

      • XDHyp:\Connections\ConnectioName\Region\vm.folder\VMName1.vm,Domain\ComputerName1,Domain\Username1
      • XDHyp:\Connections\ConnectioName\Region\vm.folder\VMName2.vm,Domain\ComputerName2,Domain\Username2
    • For VMs only:

      • XDHyp:\Connections\ConnectioName\Region\vm.folder\VMName1.vm,Domain\ComputerName1
      • XDHyp:\Connections\ConnectioName\Region\vm.folder\VMName2.vm,Domain\ComputerName2
  • The maximum number of machines that a file can contain is 1,000. To import more than 1,000 machines, spread them across different files and then import those files one by one. We recommend that you import no more than 1,000 machines. Otherwise, catalog creation can take a long time to complete.

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. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a catalog and then select View Machines in the action bar.
  3. Select one or more machines and then select Delete in the action bar.

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

When you delete an Azure Resource Manager machine catalog, the associated machines and resource groups are deleted from Azure, even if you indicate that they are to be retained.

Change a catalog description or change Remote PC Access settings

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a catalog and then select Edit Machine Catalog in the action bar.
  3. (Remote PC Access catalogs only) On the Power Management page, you can 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. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a catalog and then select Rename Machine Catalog in the action bar.
  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.

Keep in mind that moving a catalog to a different zone than the hypervisor or cloud service containing the VMs in that catalog can affect performance.

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a catalog and then select Move in the action bar.
  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. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a catalog and then select Delete Machine Catalog in the action bar.
  3. Indicate whether the machines in the catalog are to be deleted. If you choose to delete the machines, indicate whether the Active Directory computer accounts for those machines are to be 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 and multi-session 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. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a catalog and then select Manage AD accounts in the action bar.
  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. If you enter a password, the password is changed on the accounts as they are imported. If you delete an account, choose whether the account in Active Directory is to be kept, disabled, or deleted.

You can also indicate whether Active Directory accounts are to be retained, disabled, or deleted when you remove machines from a catalog or delete a catalog.

Update a catalog

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

Important:

When updating a persistent catalog, consider the following: Only machines you add to the catalog later are created using the new image. We do not roll out the update to existing machines in the catalog.

After a machine is updated, it restarts automatically.

Update or create an image

Before you update the Machine Catalog, either update an existing image or create one on your host hypervisor.

  1. On your hypervisor or cloud service provider, 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 image, and log on.
  3. Install updates or make any required changes to the image.
  4. If the image uses a Personal vDisk, update the inventory.
  5. Power off the VM.
  6. Take a snapshot of the VM, and give the snapshot a meaningful name that is recognized when the catalog is updated. Although the management interface can create a snapshot, Citrix recommends that you create a snapshot using the hypervisor management console, and then select that snapshot in the Full Configuration management interface. This enables you to provide a meaningful name and description rather than an automatically generated name. For GPU images, you can change the image only through the XenServer XenCenter console.

Update the catalog

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

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a catalog and then select Update Machines in the action bar.
  3. On the Master Image page, select the host and the image you want to roll out.

    Tip:

    For an MCS-created catalog, you can annotate its image by adding a note for the image. A note can contain up to 500 characters. Each time you update the catalog, a note-related entry is created whether or not you add a note. If you update a catalog without adding a note, the entry appears as null (-). To view note history for the image, select the catalog, click Template Properties in the low pane, and then click View note history.

  4. On the Rollout Strategy page, choose when the machines in the machine catalog are updated with the new image: on the next shutdown or immediately.
  5. Verify the information on the Summary page and then select Finish. Each machine restarts automatically after it is updated.

If you are updating a catalog using the PowerShell SDK, you can specify a hypervisor template (VMTemplates), 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 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.

If you choose to update the image immediately, configure a distribution time and notifications.

  • Distribution time: You can choose to update all machines at the same time, or specify the total length of time it is expected to take to begin updating all machines in the catalog. An internal algorithm determines when each machine is updated and restarted during that interval.
  • Notification: In the left notification list, choose whether to display a notification message on the machines before an update begins. By default, no message is displayed.

    If you choose to display a message 15 minutes before the update begins, you can choose (in the right list) to repeat the message every five minutes after the initial message. By default, the message is not repeated.

    Unless you choose to update all machines at the same time, the notification message displays on each machine at the appropriate time before the update begins, calculated by an internal algorithm.

Roll back an update

After you roll out an updated/new image, you can roll it back. This 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 will no longer be available. As with the rollout, rolling back a machine includes a restart.

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select the catalog and then select Rollback machine update in the action bar.
  3. Specify when to apply the earlier image to machines, as described for the rollout operation.

The rollback is applied only to machines that need to be reverted. For machines that have not been updated with the new/updated image (for example, machines with users who have not logged off), users do not receive notification messages and are not forced to log off.

You cannot roll back in certain scenarios, including the following. (The Rollback Machine Update option is not visible).

  • You do not have permission to do that.
  • The catalog was not created using MCS.
  • The catalog was created using an image of the OS disk.
  • The snapshot used to create the catalog has become corrupted.
  • User changes to the machines in the catalog do not persist.
  • Machines in the catalog are running.

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:

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

To upgrade a catalog:

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select the catalog. The Details tab in the lower pane displays version information.
  3. Select Upgrade Catalog. If the management interface 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 action bar.

Clone a catalog

Before cloning a catalog, be aware of the following considerations:

  • You cannot change settings associated with operating system and machine management. The cloned catalog inherits those settings from the original.
  • Cloning a catalog can take some time to complete. Select Hide progress to run the cloning in the background if needed.
  • The cloned catalog inherits the name of the original and has a suffix Copy. You can change the name. See Rename a catalog.
  • After cloning completes, be sure to assign the cloned catalog to a delivery group.
  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.

  2. Select a catalog and then select Clone in the action bar.

  3. In the Clone Selected Machine Catalog window, view the settings for the cloned catalog and configure settings as applicable. Select Next to proceed to the next page.

  4. On the Summary page, view a summary of the settings and select Finish to start cloning.

  5. Select Hide progress to run the cloning in the background if needed.

Manage tags

You can use the Full Configuration management interface to apply or remove a tag to or from a catalog.

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. Select a machine catalog and then select More.
  3. Select Manage Tags from the menu. The Manage Tags window appears.
  4. If a tag exists, select the check box next to its name. Otherwise, select Create and then specify a name for the tag. After the tag is created, you automatically return to the Manage Tags window, with the check box next to its name selected.
  5. In the Manage Tags window, select Save to apply your changes and to exit the window.

Manage configuration set for a catalog

Before you start, make sure that you have set up your WEM service deployment. For more information, see Get started with Workspace Environment Management service.

Bind a catalog to a configuration set

Important:

If your Virtual Apps and Desktops and WEM service instances do not reside in the same region, you cannot bind a catalog to a configuration set. In that case, migrate your WEM service to the same region as the Virtual Apps and Desktops service.

To bind a catalog to a configuration set, follow these steps:

  1. In the Manage > Full Configuration interface, select Machine Catalogs.

  2. Select the machine catalog and then Manage configuration set in the action bar. The Manage configuration set window appears.

  3. Select a WEM configuration set to which you want to bind the catalog.

    Note:

    If the selected configuration set does not contain settings relating to the basic configuration of WEM, the Apply basic settings to configuration set option appears. We recommend that you select the option to apply basic settings to the configuration set.

  4. Click Save to save your change.

Switch to a different configuration set

To switch to a different configuration set for a catalog, follow these steps:

  1. In the Manage > Full Configuration interface, select Machine Catalogs.

  2. Select the machine catalog and then Manage configuration set in the action bar. The Manage configuration set window appears.

  3. Select a different WEM configuration set to which you want to bind the catalog.

  4. Click Save to save your change.

Unbind a catalog from the configuration set

To unbind a catalog from the configuration set, follow these steps:

  1. In the Manage > Full Configuration interface, select Machine Catalogs.

  2. Select the machine catalog and then Manage configuration set in the action bar. The Manage configuration set window appears.

  3. Click the X icon on the right-hand side of the selected configuration set.

  4. Click Save to save your change.

Configure support for non-domain joined catalogs

Using the Citrix Virtual Apps and Desktops service, you can create catalogs based on workgroup, or, non-domain joined machines. Creating non-domain joined machines depends on how the account identity pool is created. The account identity pool is the mechanism used by MCS to create and track machine names during catalog provisioning.

For example, in past releases all Active Directory fields were supplied in a single instance:

New-AcctIdentityPool AllowUnicode -Domain "awsdevexample.local" -IdentityPoolName "DedicatedHostCatalog" -NamingScheme "MH-DHost##" -NamingSchemeType "Numeric" *-OU "CN=Computers,DC= awsdevexample,DC=local"* -Scope @() -ZoneUid "81291221-d2f2-49d2-ab12-bae5bbd0df05"
<!--NeedCopy-->

MCS uses a new PoSH parameter, WorkgroupMachine, to create a workgroup catalog. Using the same example, noted above, this parameter removes the requirement to specify all the AD-specific parameters, including domain administrator credentials:

New-AcctIdentityPool AllowUnicode -WorkgroupMachine -IdentityPoolName "DedicatedHostCatalog" -NamingScheme "MH-DHOst##" -NamingSchemeType "Numeric" -Scope @() -ZoneUid "81291221-d2f2-49d2-ab12-bae5bbd0df05"
<!--NeedCopy-->

Note:

When using the WorkgroupMachine parameter, consider that non-domain joined machine catalogs are only supported through PowerShell for all catalog lifecycle events including provisioning, adding/removing machines from the catalog, updating, and power management.

Adding descriptions to an image

You can add informative descriptions about changes related to image updates for machine catalogs. Use this feature to add a description when creating a catalog, or when you update an existing master image for a catalog. You can also display information for each master image in the catalog. This functionality is useful for administrators who want to add descriptive labels when updating a master image used by a catalog, for example, Office 365 installed. Use the following commands to add or view image descriptions:

  • NewProvScheme. A new parameter, masterImageNote enables you to add a note to an image. For exmaple:
C:\PS>New-ProvScheme -ProvisioningSchemeName XenPS -HostingUnitName XenHu -IdentityPoolName idPool1 -MasterImageVM XDHyp:\HostingUnits\XenHU\Base.vm\Base.snapshot -MasterImageNote "Office365 installed"
<!--NeedCopy-->
  • Publish-ProvMasterVMImage. Use this parameter to publish the note. For example:
C:\PS>Publish-ProvMasterVMImage -ProvisioningSchemeName MyScheme -MasterImageVM XDHyp:\HostingUnits\HostUnit1\RhoneCC_baseXP.vm\base.snapshot -MasterImageNote "Visual Studio 2019 installed"
<!--NeedCopy-->
  • Get-ProvSchemeMasterVMImageHistory. Display information for each image. For example:
C:\PS>Get-ProvSchemeMasterVMImageHistory -ProvisioningSchemeName MyScheme -Showall

VMImageHistoryUid : 3cba3a75-89cd-4868-989b-27feb378fec5

ProvisioningSchemeUid : 7585f0de-192e-4847-a6d8-22713c3a2f42

ProvisioningSchemeName : MyScheme

MasterImageVM : /Base.vm/base.snapshot

Date : 17/05/2021 09:27:50

MasterImageNote : Office365 installed
<!--NeedCopy-->

Troubleshoot

  • For machines with Power State Unknown status, see CTX131267 for guidance.

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