Citrix DaaS

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 continue using that interface to manage the catalog, then follow 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 the 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.

Tip:

If Citrix DaaS account used to add machines to the machine catalog has restricted AD permissions, add all cloud connectors you intend to use in the Log on to.. screen.

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. On the Virtual Machines page, select the number of virtual machines to add.

  4. On the Machine Identities page, configure settings as follows:

    • Select an identity from the list.

    • If applicable, indicate whether to create accounts or use existing ones, and the location (domain) for those accounts.

      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.

      If you use existing Active Directory accounts, 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. Allow that interface to reset the passwords for all the accounts, or specify the account password, which must be the same for all accounts.

    • Specify an account naming scheme, using hash marks to indicate where sequential numbers or letters appear. 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.

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

      When specifying what the account names start with, be aware of the following scenario: If the starting numbers or letters are already in use, the first account created is named using the nearest unused numbers or letters thereafter.

  5. On the Domain Credentials page, select Enter credentials and enter user credentials with sufficient permissions to create machine 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

You can bulk add machines by using CSV files. The feature is available for all catalogs except catalogs provisioned 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

Note:

For non-Active Directory users, you must type their names in this format: <identity provider>:<user name>. Example: AzureAD:username.

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
      • Domain\ComputerName3, AzureAD:username
    • 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.

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

  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 Export to CSV file. A CSV file containing a list of the machines is downloaded.

  4. 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, Use CSV files to bulk add machines to a catalog.

Note:

  • This feature is not available for Remote PC Access and MCS-provisioned catalogs.

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

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.

Edit a catalog

  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. On the Scopes page, change the scopes.
  4. On the VDA Upgrade page, change or select the VDA version to upgrade to. For more information, see VDA upgrade.
  5. You might see additional pages depending on the catalog type.

    For catalogs created using an Azure Resource Manager image, the following pages are visible. Keep in mind that changes you make apply only to machines you add to the catalog later. Existing machines remain unchanged.

    • On the Virtual Machines page, change the machine size and availability zones where you want to create machines.

      Note:

      • Only machine sizes that the catalog supports are shown.
      • If necessary, select Show only machine sizes used in other machine catalogs to filter the machine size list.
    • On the Machine Profile page, choose whether to use or change a machine profile.

    • On the Storage and License Types page, choose whether to change the Windows license or Linux license setting.

    For more information about settings available on the pages, see Create a machine catalog using an Azure Resource Manager image.

    For Remote PC Access catalogs, the following pages are visible:

    • On the Power Management page, change the power management settings and select a power management connection.
    • On the Organizational Units page, add or remove Active Directory OUs.
  6. On the Description page, change the catalog description.
  7. Click Apply to apply the changes you made and click Save to exit.

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.

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 an 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 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.

To track the progress of the update, locate the catalog in Machine Catalogs to view the inline progress bar and the step-by-step progress graph.

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 the 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 or 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 are no longer 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.

To track the rollback progress, locate the catalog in Machine Catalogs to view the inline progress bar and the step-by-step progress graph.

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

  • You do not have permission to roll back.
  • 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.

Organize catalogs using folders

You can create folders to organize catalogs for easy access. For example, you can organize catalogs by image type or by organization structure.

Required roles

To create and manage catalog folders, you need to have one of the following built-in roles: Cloud Administrator, Full Administrator, or Machine Catalog Administrator. For more information, see Required permissions.

Create a catalog folder

Before you start, first plan how to organize your catalogs. Consider the following:

  • You can nest folders up to five levels deep (excluding the default root folder).
  • A catalog folder can contain catalogs and subfolders.
  • All nodes in Full Configuration (such as the Machine Catalogs and the Applications nodes) share a folder tree in the backend. To avoid name conflicts with other nodes when renaming or moving folders, we recommend you give different names to first-level folders in different nodes.

To create a catalog folder, follow these steps:

  1. From Manage > Full Configuration, select Machine Catalogs in the left pane.
  2. In the folder hierarchy, select a folder and then select Create Folder in the Action bar.
  3. Enter a name for the new folder, and then click Done.

Tip:

If you create a folder in an unintended location, you can drag it to the correct location.

Move a catalog

You can move a catalog between folders. Detailed steps are as follows:

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

  2. View catalogs by folder. You can also turn on View all above the folder hierarchy to view all catalogs at a time.

  3. Right-click a catalog and then select Move Machine Catalog.

  4. Select the folder to which you want to move the catalog, and then click Done.

Tip:

You can drag a catalog to a folder.

Manage catalog folders

You can delete, rename, and move catalog folders.

Note that you can delete a folder only if it and its subfolders don’t contain catalogs.

To manage a folder, follow these steps:

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

  2. In the folder hierarchy, select a folder, and then select an action in the Action bar as needed:

    • To rename the folder, select Rename Folder.
    • To delete the folder, select Delete Folder.
    • To move the folder, select Move Folder.
  3. Follow onscreen instructions to complete the remaining steps.

Required permissions

The following table lists the permissions required to perform actions on catalog folders.

Action Required permissions
Create catalog folders Create Machine Catalog Folder
Delete catalog folders Remove Machine Catalog Folder
Move catalog folders Move Machine Catalog Folder
Rename catalog folders Edit Machine Catalog Folder
Move catalogs to folders Edit Machine Catalog Folder and Edit Machine Catalog

Upgrade VDAs

Important:

  • This feature is available as a preview.
  • This feature requires VDA version 2109 or later, or VDA version 2203 LTSR or later.

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.

With the feature, you can do the following:

  • Upgrade VDAs on a per-catalog basis
  • Edit or cancel a scheduled VDA upgrade
  • Configure VDA upgrade settings after catalog creation
  • Upgrade VDAs on a per-machine basis

Note:

  • When you schedule VDA upgrades for a catalog, only VDAs in the catalog that have the VDA Upgrade Agent installed can be upgraded.
  • Upgrading a VDA fails when the machine is in maintenance mode or when a session is running on the machine.

Prerequisites:

  • Verify that you have permissions to upgrade VDAs.
  • Verify that the version of the VDA meets the requirement (VDA version 2109 or later, or VDA version 2203 LTSR or later).

Upgrade VDAs on a per-catalog basis

After enabling VDA upgrade for a catalog, you can upgrade VDAs in the catalog immediately or schedule upgrades for the catalog. To do that, follow these steps:

  1. From Manage > Full Configuration, select Machine Catalogs.

  2. Select the catalog and then Upgrade VDAs in the action bar. The VDA Upgrade window appears.

  3. Choose whether to upgrade the VDAs immediately or at a scheduled time.

    • To upgrade the VDAs immediately, select Upgrade now and then specify a duration.

      A duration is the amount of time, in hours, after which the VDA Upgrade Service stops rolling out upgrades. For a VDA whose upgrade is in progress, the upgrade continues. To ensure that all VDAs can be upgraded, we recommend selecting a large value (for example, 8 hours).

    • To schedule the upgrades, select Upgrade later and then specify when you want the upgrades to occur.

      You can schedule the upgrades only for the next seven days. Upgrades you schedule apply only to the machines that are currently in the catalog. If you add machines to the catalog later but want to upgrade them as well, cancel the scheduled upgrade and then recreate a schedule.

  4. Click Done to apply your settings and to exit the window.

Note:

  • The Upgrade VDAs option is available only after you enable VDA upgrade for the catalog. To enable VDA upgrade, edit the catalog.
  • All machines in the catalog are placed in maintenance mode while upgrades are rolled out. Upgrades can take up to 30 minutes to begin and will be performed only during the specified time period.

On the Machine Catalogs node, the VDA Upgrade column provides VDA upgrade information for the catalog. The following information can appear:

Tip:

To show the VDA Upgrade column, select Columns to Display in the action bar, select Machine Catalog > VDA Upgrade, and then click Save.

  • Available: A new VDA version is available.
  • Scheduled: The VDA upgrade has been scheduled.
  • Not configured: Appears when you have not enabled VDA upgrade for the catalog.
  • Up to date: The catalog’s VDAs are up to date.
  • Unknown: Information about the VDA upgrade is not yet available.

You can also view the status of VDA upgrades for a catalog. To do that, click the catalog and then check the VDA Upgrade State information on the Details tab. The following information can appear:

  • Not scheduled: You have enabled VDA upgrade for the catalog but have not set up an upgrade schedule.
  • Scheduled: You have created an upgrade schedule for the catalog. For example, if you set the schedule to start at 09:00 PM, December 14, 2030, information appears as follows: Scheduled for December 14, 2030 09:00 PM UTC.
  • In progress: VDA upgrades have started.
  • Canceled: You have canceled the scheduled upgrade.
  • Failed: The catalog contains one or more machines whose VDA upgrades were not successful.
  • Successful: All VDAs in the catalog were upgraded successfully.

You can also troubleshoot VDA upgrade issues with recommended actions for a catalog. To do that, click the catalog and then go to the Troubleshoot tab.

To quickly drill down to catalogs that have a specific VDA upgrade state, you can use filters. For more information, see Use Search in the Full Configuration management interface.

Be aware of the following considerations:

  • The VDA Upgrade or VDA Upgrade State filter is available for use only with the following filters: Name and Machine Catalog.
  • When you use the VDA Upgrade or the VDA Upgrade State filter, Errors and Warnings in the upper right corner become unavailable.

Edit or cancel a scheduled VDA upgrade

After you schedule the upgrades for a catalog, you might want to edit or cancel the scheduled upgrade. To do that, follow these steps:

  1. From Manage > Full Configuration, select Machine Catalogs.

  2. Select the catalog and then Edit Scheduled VDA Upgrade in the action bar. The Edit VDA Upgrade window appears, showing information about installed VDA version and VDA version to upgrade to.

  3. Choose whether to edit or cancel the scheduled upgrade.

    • To cancel the upgrade, click Cancel scheduled upgrade. Remember: Canceling the scheduled upgrade does not force the upgrade in progress to stop.
  4. Click Done to exit the window.

Configure VDA upgrade settings by editing a catalog

After catalog creation, you can configure VDA upgrade settings by editing the catalog. Before you start editing, consider the following:

  • Verify that all machines in the catalog are on the same VDA (CR or LTSR) track. Otherwise, certain VDA upgrades will fail. For example, if you select Latest LTSR VDA, CR VDA upgrades will fail.

  • Upgrades to some of the machines in the catalog might have started. You cannot modify upgrades that are already in progress. Upgrades in progress continue. Those that have not yet started will upgrade to the specified version.

Upgrade VDAs on a per-machine basis

After enabling VDA upgrade for a catalog, you can upgrade the catalog’s VDAs one by one or in batches. To do that, follow these steps:

  1. From Manage > Full Configuration, select Search.

  2. Select one or more machines and then Upgrade VDA in the action bar.

Note:

  • For the Upgrade VDA option to be available, make sure that you have enabled VDA upgrade for the catalog where the selected machines reside and that those machines have the VDA Upgrade Agent installed. To enable VDA upgrade for it, edit the catalog.
  • The Upgrade VDA option is not available when you upgrade VDAs for more than 50 machines at a time.
  • Machines will be placed in maintenance mode while upgrades are rolled out. Upgrades can take up to 30 minutes to begin.
  • If your selection contains machines for which VDA upgrades are not available or whose upgrades are pending (scheduled, in progress, or awaiting upgrades), we will skip upgrades for those machines.

On the Search node, you can add the VDA Upgrade column. For information about how to add a custom column, see Customize columns to display. The column is useful. It provides VDA upgrade information for the machine. The following information can appear:

  • Available: A new VDA version is available.
  • Scheduled: The VDA upgrade has been scheduled.
  • Not configured: Appears when you have not enabled VDA upgrade for the machine.
  • Up to date: The VDA is up to date.
  • Unknown: Information about the VDA upgrade is not yet available.

You can also view the status of the VDA upgrade for a machine. To do that, click the machine and then check the VDA Upgrade State information on the Details tab. The following information can appear:

  • Unknown: Information about the VDA upgrade state is not yet available.
  • Scheduled: You have set up an upgrade schedule. For example, if you set the schedule to start at 09:00 PM, December 14, 2030, information appears as follows: Scheduled for December 14, 2030 09:00 PM UTC.
  • Awaiting upgrade: The machine is placed in maintenance mode, awaiting the upgrade. (Make sure that users have logged out of their session so that the upgrade can proceed.)
  • In progress: The VDA upgrade has started.
  • Upgrade failed: Attempts to upgrade the VDA failed.
  • Validation failed: Attempts to validate VDA upgrade settings failed.
  • Canceled: The upgrade for the machine has been canceled.
  • Successful: The VDA was upgraded successfully.

You can also troubleshoot VDA upgrade issues with recommended actions for a machine. To do that, click the machine and then go to the Troubleshoot tab.

To quickly drill down to machines that have a specific VDA upgrade state, you can use filters. For more information, see Use Search in the Full Configuration management interface. Be aware of the following considerations:

  • The VDA Upgrade or VDA Upgrade State filter is available for use only with the following filters: Name and Machine Catalog.
  • When you use the VDA Upgrade or the VDA Upgrade State filter, Errors and Warnings in the upper right corner become unavailable.

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.

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. Run Set-HypAdminConnection to set the default controller address to be used by the commands to communicate with the controller.
  4. Assign a variable to the new network setting. For example:

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

Update provisioned machines to current provisioning scheme state

Set-ProvScheme changes the provisioning scheme. However, it does not affect existing machines. Using Request-ProvVMUpdate command, you can now apply the current provisioning scheme to an existing persistent or non-persistent machine or set of machines. Currently, the property update supported by this feature is ServiceOffering.

You can update:

  • A single VM.
  • A list of specific VMs or all exisiting VMs associated with a provisioning scheme ID.
  • A list of specific VMs or all exisiting VMs associated with a provisioning scheme name.

To update the existing VMs:

  1. Check the configuration of the existing machines. For example,

    ProvScheme | select ProvisioningSchemeName, ProvisioningSchemeVersion
    <!--NeedCopy-->
    
  2. Update the provisioning scheme. For example,

    ProvisioningSchemeName “my-catalog” –ServiceOffering “Standard_D16_v3”
    <!--NeedCopy-->
    
  3. Request update for exisiting machines. For example:

    • To update all the exisiting machines:

       Request-ProvVMUpdate –ProvisioningSchemeName “my-catalog”
       Get-ProvVM | select VMName,
       ProvisioningSchemeUpdateRequested, ProvisioningSchemeVersion
       <!--NeedCopy-->
      
    • To update a list of specific machines:

       Request-ProvVMUpdate -ProvisioningSchemeName "my-catalog" -VMName "vm1","vm2"
       Get-ProvVM | select VMName,
       ProvisioningSchemeVersion
       <!--NeedCopy-->
      
    • To update machines based on the input from Get-ProvVM:

       Get-ProvVM -ProvisioningSchemeName "my-catalog" | Request-ProvVMUpdate
       Get-ProvVM | select VMName,
       ProvisioningSchemeVersion
       <!--NeedCopy-->
      
  4. Restart the machines. At the next power up, the ProvisioningSchemeVersion on the machines will be updated to match the current provisioning scheme version and the ProvisioningSchemeUpdateRequested field will be cleared.

Resources created by MCS on Citrix Hypervisor

The following table shows the list of resources created by MCS on Citrix Hypervisor.

DDC process Resources on DDC Resources on Citrix Hypervisor
Creating connection and hosting unit Connection and hosting unit -
Creating machines catalog Machines catalog Copy of master image (deletes after process is completed), preparation VM with base and identity disks (deletes after process is completed), master image base disk, and VMs with base and identity disks.
Adding machines to machine catalog VMs added to catalog New VMs with base and identity disks.
Deleting machines from machine catalog VMs removed from catalog VMs with base and identity disks are removed from hypervisor inventory and storage.
Updating machine catalog Updated catalog New master image base disk. Replace VMs base disks with new base disks.
Rollback catalog Catalog returns to original state Replace VMs base disks with original base disks.
Deleting machines catalog Machines catalog removed VMs with base and identity disks are removed from hypervisor inventory and storage. All master image base disks are removed after some time. Delete hosting only after all disks are removed.
Deleting connection and hosting unit Connection and hosting unit removed -

Usage scenarios

The following table shows the list of possible actions to manage resources if you use Citrix Hypervisor to provide virtual machines and their corresponding expected results.

Action Result
Rename resources on DDC and hypervisor: Hosting; hosting unit; machine catalog on DDC, or VMs name; VMs disk name; storage name. MCS uses objects by ID. Therefore, you can rename any resources except snapshots.
Delete or rename original snapshot and try to rollback machine update. A message to select a different snapshot appears. The snapshot is a template for the machines in the catalog.
Delete VM from hypervisor inventory without deleting disks from local storage, and then start this VM from DDC. VM fails to start.
Move a machine from one host to another. You can do this only if VM has never been started. MCS blocks this operation and an appropriate message appears on the hypervisor console.
Delete VM base disk from hypervisor storage, and then start this VM from DDC. Base disk is recreated from the master image base disk and VM is registered after turning on the power.
Delete Write-Back Cache disk (Temporary Storage disk), and then start this VM from DDC. VM starts and passes registration but Write-Back Cache disk is not recreated.
Delete VM base disk and master image base disk from hypervisor storage and start this VM from DDC. Base disk is not recreated and VM is not registered.
Delete VM identity disk from hypervisor storage and start this VM from DDC. Identity disk is not recreated and VM is not registered.
Delete master image base disk from hypervisor storage and try to add machine. VM is not added.

Resources created by MCS on VMware hypervisor

DDC process Resources on DDC Resources on VMware Hypervisor
Creating connection and hosting unit Connection and hosting unit -
Creating machines catalog Machines catalog XD-Temp VM (deletes after process is completed), preparation VM (deletes after process is completed), folder with master image base disk, and VMs folders with Virtual Machine files.
Adding machines to machine catalog VMs added to catalog New VMs folders with Virtual Machine files.
Deleting machines from machine catalog VMs removed from catalog VMs folders with Virtual Machine files are removed from hypervisor inventory and storage.
Updating machine catalog Updated catalog New folder with master image base disk.
Rollback catalog Catalog returns to original state Replace VMs base disks with original base disks.
Deleting machines catalog Machines catalog removed VMs folders with Virtual Machine files are removed from hypervisor inventory and storage. Manually delete all folders with master image base disks on hypervisor storage.
Deleting connection and hosting unit Connection and hosting unit removed -

Virtual Machine Files

File Usage Description
.vmx vmname.vmx Virtual machine configuration file
.vmxf vmname.vmxf Additional Virtual machine configuration files
.vmdk Vmname-xd-delta.vmdk Delta virtual disk
.vmdk Vmname_IdentityDisk.vmdk Identity virtual disk
.vmdk Vmname_TemporaryStorage.vmdk WBC disk
.vmdk Vmname-xd-copy.vmdk Virtual disk (full clone copy mode)
.nvram vmname.nvram or nvram Virtual machine BIOS or EFI configuration
.vmsd vmname.vmsd Virtual machine snapshots
.log vmware.log Current virtual machine log file
-#.log vmware-#.log (where # is a number starting with 1) Old virtual machine log files
.hlog vmname.hlog Log file that is used by vCenter server to track virtual machine files must be removed after a certain operation is completed.

Following are the additional files created when virtual machine goes to power on state and are deleted after shut down:

  • vmname.vswp
  • Vmname-xd-delta.vmdk-sesparse.REDO_xxxxxx
  • Vmname-xd-delta.vmdk.REDO_xxxxxx
  • vmname.vmx.lck
  • vmname.vmx~
  • vmx-vmname.vswp

Usage scenarios

The following table shows the list of possible actions to manage resources if you use VMware to provide virtual machines and their corresponding expected results.

Action Result
Rename resources on DDC and hypervisor: Hosting; hosting unit; machine catalog on DDC, or VMs inventory name. VM starts and passes registration.
Delete or rename original snapshot and try to rollback machine update. A message to select a different snapshot appears. The snapshot is a template for the machines in the catalog.
Delete VM from hypervisor inventory without deleting disks from local storage, and then start this VM from DDC. VM fails to start.
Move (migrate with VMotion) a machine from one host to another (compute resource and storage options only). VM starts and passes registration.
Rename or delete datastore and start this VM from DDC. A file not found error message appears and VM fails to start.
Rename or delete VM folder and start this VM from DDC. A file not found error message appears and VM fails to start.
Rename or delete Virtual Machine files in VM folder and start this VM from DDC. A file not found error message appears and VM fails to start.
Rename or delete base disk folder and start this VM from DDC. A file not found error message appears and VM fails to start.
Rename or delete base disk from base disk folder and start this VM from DDC. A file not found error message appears and VM fails to start.

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.

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”

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”

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”

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 Citrix DaaS 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 Citrix DaaS.

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

  1. From Manage > Full Configuration, 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. From Manage > Full Configuration, 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. From Manage > Full Configuration, 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.

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 example:
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.