Product documentation
Citrix DaaS
View PDF

Manage machine catalogs

August 24, 2023
Contributed by:
C

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 followManage 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连接和资源.

Note:

MCS does not support Windows 10 IoT Core and Windows 10 IoT Enterprise. Refer to theMicrosoft sitefor more information.

About persistent instances

When updating the master image for an MCS catalog containing persistent machines, any new machines added to the catalog use the updated image. Existing machines continue to use the original master image. 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.
  • 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:

  • 确保梵tualization 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 the Citrix DaaS account used to add machines to the machine catalog has restricted AD permissions, add all cloud connectors you intend to use in theLog on to..screen.

To add machines to a catalog:

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.

  2. Select a machine catalog and then selectAdd machinesin the action bar.

  3. On theVirtual Machinespage, select the number of virtual machines to add.

  4. On theMachine Identitiespage, 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 selectImportand 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.

    • 指定一个帐户命名方案,使用散列标志来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 theDomain Credentialspage, selectEnter credentialsand 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. FromManage > Full Configuration, selectMachine Catalogsin the left pane.

  2. Select a machine catalog and then selectAdd Machinesin the action bar. TheAdd Machineswindow appears.

  3. SelectAdd CSV File. TheAdd Machines in Bulkwindow appears.

  4. SelectDownload CSV Template.

  5. Fill out the template file.

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

  7. SelectValidate来perform validation checks on your import.

  8. SelectImport来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::. Example:AzureAD:username.
  • VM names are case sensitive. When entering VM paths, make sure that you enter the VM names correctly.

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\ConnectionName\RegionName\vm.folder\VMName1.vm,Domain\ComputerName1,Domain\Username1
      • XDHyp:\Connections\ConnectionName\RegionName\vm.folder\VMName2.vm,Domain\ComputerName2,Domain\Username2

    • For VMs only:

      • XDHyp:\Connections\ConnectionName\RegionName\vm.folder\VMName1.vm,Domain\ComputerName1
      • XDHyp:\Connections\ConnectionName\RegionName\vm.folder\VMName2.vm,Domain\ComputerName2

      For example:XDHyp:\Connections\xpace-scale\East US.region\vm.folder\wsvdaV3-2.vm

      where,

      • xpace-scaleis the ConnectionName: The name of the connection that you entered inFull Configuration > Hosting > Add Connections and Resources. For more information, seeCreate a connection and resources.
      • East US.regionis the RegionName: The name of the region with.regionas extension.
      • wsvdaV3-2.vmis the VMName: The name of the virtual machine with.vmas extension.

  • 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 sameAdd Machinespage. The exported CSV of machines can then be used as a template when adding machines in bulk. To export machines:

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.

  2. Select a machine catalog and then selectAdd Machinesin the action bar. TheAdd Machineswindow appears.

  3. SelectExport 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.

Retrieve warnings and errors associated with a catalog

You can get historical errors and warnings to understand issues with your MCS machine catalog and fix those issues.

Using PowerShell commands, you can:

  • Get a list of errors or warnings
  • Change the warning state from新来Acknowledged
  • 删除the errors or warnings

To run the PowerShell commands:

  1. Open a PowerShell window.
  2. Runasnp citrix*来load the Citrix-specific PowerShell modules.

To get a list of errors and warnings:

RunGet-ProvOperationEventcommand.

  • With no parameters: Gets all errors and warnings
  • WithLinkedObjectTypeandLinkedObjectUidparameter: Gets all errors and warnings associated with a specific provisioning scheme
  • WithEventId参数:一个特定的错误或警告称,matches this event ID
  • WithFilterparameter: Gets errors or warnings by customized filter

To change the state of errors or warnings from新来Acknowledged:

RunConfirm-ProvOperationEventcommand.

  • WithEventIdparameter: Sets the state of a specific error or warning that matches this event ID. You can get theEventIdof a specific error or warning as an output fromGet-ProvOperationEventcommand
  • WithLinkedObjectTypeandLinkedObjectUidparameters: Sets the state of all the errors and warnings associated with a specific provisioning scheme
  • WithAllparameter: Sets the state of all errors and warnings asAcknowledged

To delete the errors or warnings:

RunRemove-ProvOperationEventcommand.

  • WithEventIdparameter: Removes a specific error or warning that matches this event ID. You can get theEventIdof a specific error or warning as an output fromGet-ProvOperationEventcommand
  • WithLinkedObjectTypeandLinkedObjectUidparameters: Removes all errors and warnings associated with a specific provisioning scheme
  • WithAllparameter: Removes all errors and warnings

For more information, seeCitrix PowerShell SDK.

删除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. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select a catalog and then selectView Machinesin the action bar.
  3. Select one or more machines and then select删除in the action bar.
  4. If you are deleting persistent machines from the catalog, choose whether to delete them from the hypervisor or cloud service as well. If you choose to delete them, indicate whether to retain, disable, or delete their Active Directory accounts.

When you delete persistent machines from an Azure Resource Manager catalog, the machines and associated resource groups are deleted from Azure, even if you choose to retain them.

When you delete non-persistent machines from a catalog, they are automatically deleted from the hypervisor or cloud service.

删除machines without hypervisor access

When deleting a VM or a provisioning scheme, MCS needs to remove tags from the VM, and sometimes from the base disk as well, so that the resources included in the deletion options are no longer tracked or identified by MCS. However, some of these resources are only accessible through hypervisor. Use thePurgeDBOnlyoption inRemove-ProvVMPowerShell to delete VM resource objects such as VM, base disk, image in ACG, and so on from the database even when there is no hypervisor access.

This option is enabled on:

  • all supported hypervisors
  • persistent and non-persistent VMs

Limitations

You cannot use the commands -PurgeDBOnly and -ForgetVM at the same time.

Use the PurgeDBOnly command

When running the PowerShell commandRemove-ProvVM -ProvisioningSchemeName SCVMM-MC -VMName SCVMM01 -ForgetVMthe deletion operation might fail in the following scenarios:

  • The host connection is in maintenance mode
  • Invalid credentials
  • Authentication failure
  • Unauthorized operation
  • The hypervisor is unreachable

Note:

Remove-provVM -ForgetVM targets only persistent VMs. If one of the VMs in the list is non-persistent, the operation fails.

When the operation fails because the hypervisor is unreachable, the following prompt appears:

Try to use -PurgeDBOnly option to clean DDC database.

Use the-PurgeDBOnlyoption in theRemove-ProvVMPowerShell command to delete references of a VM from MCS database. For example,

Remove-ProvVM -ProvisioningSchemeName SCVMM-MC -VMName SCVMM01 -PurgeDBOnly

Edit a catalog

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select a catalog and then selectEdit Machine Catalogin the action bar.
  3. On theScopespage, change the scopes.
  4. On theVDA Upgradepage, change or select the VDA version to upgrade to. For more information, seeVDA 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 theVirtual Machinespage, 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, selectShow only machine sizes used in other machine catalogs来filter the machine size list.

    • On theMachine Profilepage, choose whether to use or change a machine profile.

    • On theStorage and License Typespage, choose whether to change the Windows license or Linux license setting.

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

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

    • On thePower Managementpage, change the power management settings and select a power management connection.
    • On theOrganizational Unitspage, add or remove Active Directory OUs.
  6. On theDescriptionpage, change the catalog description.
  7. ClickApply来apply the changes you made and clickSave来exit.

Rename a catalog

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select a catalog and then selectRename Machine Catalogin the action bar.
  3. Enter the new name.

删除a catalog

Before deleting a catalog, ensure that:

  • All users are logged off and 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 with a delivery group. In other words, the delivery group does not contain machines from the catalog.

To delete a catalog:

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select a catalog and then select删除Machine Catalogin the action bar.
  3. If the catalog contains persistent machines, indicate whether to delete those machines from the hypervisor or cloud service as well. If you choose to do so, choose whether to retain, disable, or delete their Active Directory computer accounts.
  4. If necessary, selectHide progress来run the deletion in the background.

When you delete an Azure Resource Manager catalog, the associated machines and resource groups are deleted from Azure, even if you choose to retain them.

When you delete a catalog containing non-persistent machines, those machines are deleted from the hypervisor or cloud service.

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. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select a catalog and then selectManage AD accountsin 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.

Change the master image for a catalog

We recommend that you save copies or snapshots of images before you change the master image for a catalog. The database keeps a historical record of the images used with each machine catalog. If users encounter problems with the new image you deployed to their desktops, you can roll it back to the previous version, minimizing user downtime. Do not delete, move, or rename images. Otherwise, you cannot roll back the master image.

Important:

When changing the master image for 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 new image to existing machines in the catalog.

After a machine is updated, it restarts automatically.

Update or create an image

Before you change the master image for a catalog, prepare a new image on your host hypervisor by either updating an existing image or creating one.

  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 roll back the master image.
  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 you change the master image.

Note:

虽然您可以创建一个快照使用等内容ement interface, we recommend 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.

Change the master image

To roll out a new master image to all machines in a catalog:

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select a catalog and then selectChange Master Imagein the action bar.

  3. On theMaster Imagepage, 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 change the master image, 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, clickTemplate Propertiesin the low pane, and then clickView note history.

  4. On theRollout Strategypage, choose when the machines in the machine catalog are changed with the new image: on the next shutdown or immediately.

    Note:

    TheRollout Strategypage is not available for persistent VMs because rollout is only applicable to non-persistent VMs.

  5. Verify the information on theSummarypage and then selectFinish. Each machine restarts automatically after it is updated.

    To track the progress of the update, locate the catalog inMachine Catalogs来view the inline progress bar and the step-by-step progress graph. For a non-persistent catalog, you can track its image update statuses through theImage Updatecolumn, includingFully updated,Partially updated, andPending update.

    Tip:

    To show theImage Updatecolumn, select theColumns to Displayicon in the action bar, selectMachine Catalog > Image Status, and then clickSave.

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:

在接下来的关闭将我改变形象iately 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.

Note:

Rollout strategy is only applicable to non-persistent VMs.

Consider the following:

  • 不能启动,直到你新会话pdate has completed on applicable machines.
  • 对于单一会话的机器,机器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 want to enable one-time restart schedule using PowerShell, use the followingBrokerCatalogRebootSchedulePowerShell commands to create, modify, and delete a restart schedule:

  • Get-BrokerCatalogRebootSchedule
  • 新-BrokerCatalogRebootSchedule
  • Set-BrokerCatalogRebootSchedule
  • Remove-BrokerCatalogRebootSchedule
  • Rename-BrokerCatalogRebootSchedule

Example:

  • To create a restart schedule of the VMs in the catalog namedBankTellers来begin on Feb 3, 2022, between 2 AM and 4 AM.

    新-BrokerCatalogRebootSchedule -Name BankTellers -CatalogName BankTellers -StartDate "2022-02-03" -StartTime "02:00" -Enabled $true -RebootDuration 120

  • To create a restart schedule of the VMs in the catalog having UID 17 to begin on Feb 3, 2022, between 1 AM and 5 AM. Ten minutes before the restart, each VM is set to display a message box with the title:WARNING: Reboot pending, and the message:Save your work, in every user session.

    新-BrokerCatalogRebootSchedule -Name 'Update reboot' -CatalogUid 17 -StartDate "2022-02-03" -StartTime "01:00" -Enabled $true -RebootDuration 240 -WarningTitle "WARNING: Reboot pending" -WarningMessage "Save your work" -WarningDuration 10

  • To rename the catalog restart schedule namedOld Name来新Name.

    Rename-BrokerCatalogRebootSchedule -Name "Old Name" -NewName "New Name"

  • To display all catalog restart schedules with UID 1, and then rename the catalog reboot schedule with the UID 1 to新Name.

    Get-BrokerCatalogRebootSchedule -Uid 1 | Rename-BrokerCatalogRebootSchedule -NewName "New Name" -PassThru

  • To set the catalog restart schedule namedAccounting来display a message with the title,WARNING: Reboot pending, and the message, Save your work, ten minutes before the restart of each VM. The message appears in every user session on that VM.

    Set-BrokerCatalogRebootSchedule -Name Accounting -WarningMessage "Save your work" -WarningDuration 10 -WarningTitle "WARNING: Reboot pending"

  • To display all restart schedules that are disabled, and then enable all disabled restart schedules.

    Get-BrokerCatalogRebootSchedule -Enabled $false | Set-BrokerCatalogRebootSchedule -Enabled $true

  • To set the catalog restart schedule with UID 17 to display the message:Rebooting in %m% minutesin fifteen, ten, and five minutes before the restart of each VM.

    Set-BrokerCatalogRebootSchedule 17 -WarningMessage "Rebooting in %m% minutes." -WarningDuration 15 -WarningRepeatInterval 5

  • To configure the time zone for the catalog namedMyCatalog.

    Set-BrokerCatalog -Name "MyCatalog" -TimeZone

Roll back the master image

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. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select the catalog and then selectRoll Back Master Imagein 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 changed to the new or 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 inMachine Catalogs来view the inline progress bar and the step-by-step progress graph.

You cannot roll back in certain scenarios, including the following. (TheRoll Back Master Imageoption 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.

Change the functional level or undo the change

Change the functional level for the machine catalog after you upgrade the VDAs on the machines to a newer version. We recommend upgrading all VDAs to the latest version to enable access to all the newest features.

Before changing the functional level for a machine catalog:

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

To change the functional level for a catalog:

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select the catalog. TheDetailstab in the lower pane displays version information.
  3. SelectChange Functional Level. If the management interface detects that the catalog needs to change the functional level, it displays a message. Follow the prompts. If one or more machines cannot be changed, a message explains why. To ensure that all machines function properly, We recommend you resolve those issues before clickingChange.

After the catalog upgrade completes, you can revert the machines to their previous VDA versions by selecting the catalog and then selectingUndo Functional Level Changein the action bar.

Clone a catalog

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

  • You cannot change settings associated withoperating systemandmachine management. The cloned catalog inherits those settings from the original.
  • Cloning a catalog can take some time to complete. If necessary, selectHide progress来run the cloning in the background.
  • The cloned catalog inherits the name of the original and has a suffixCopy. You can change the name. SeeRename a catalog.
  • After cloning completes, be sure to assign the cloned catalog to a delivery group.
  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select a catalog and then selectClonein the action bar.
  3. In theClone Selected Machine Catalogwindow, view the settings for the cloned catalog and configure settings as applicable. SelectNext来proceed to the next page.
  4. On theSummarypage, view a summary of the settings and selectFinish来start cloning.
  5. If necessary, selectHide progress来run the cloning in the background.

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

By default, you need to have the following built-in role to create and manage catalog folders: Cloud Administrator, Full Administrator, or Machine Catalog Administrator. If necessary, you can customize roles for creating and managing catalog folders. For more information, seeRequired 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 inFull Configuration(such as theMachine Catalogsand theApplicationsnodes) 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. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. In the folder hierarchy, select a folder and then selectCreate Folderin theActionbar.
  3. Enter a name for the new folder, and then clickDone.

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. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. View catalogs by folder. You can also turn onView allabove the folder hierarchy to view all catalogs at a time.
  3. Right-click a catalog and then selectMove Machine Catalog.
  4. Select the folder to which you want to move the catalog, and then clickDone.

Tip:

You can drag a catalog to a folder.

Manage catalog folders

You can delete, rename, and move catalog folders.

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

To manage a folder, follow these steps:

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.

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

    • To rename the folder, selectRename Folder.
    • To delete the folder, select删除Folder.
    • To move the folder, selectMove 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
删除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 Properties

Configure auto-upgrade for VDAs

Important:

  • To ensure a smooth upgrade, make sure that you meet the prerequisites and review known issues before upgrading VDAs to CR or LTSR CU versions. SeeUpgrade VDAs using the Full Configuration interface.
  • When upgrading LTSR VDAs to LTSR Cumulative Update (CU) versions, make sure that the version of the VDA Upgrade Agents running on the VDAs is 7.36.0.7 or later. For more information, seeUpgrade VDAs using the Full Configuration interface.
  • You can switch between the CR VDA and the LTSR VDA as long as you switch from an earlier version to a later version. You cannot switch from a later version to an earlier version because that is considered a downgrade. For example, you cannot downgrade from 2212 CR to 2203 LTSR (any CU) but you can upgrade from 2112 CR to 2203 LTSR (any CU).
  • You can also upgrade VDAs using PowerShell. SeeUpgrade VDAs using PowerShell.

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.

Supported machine types

This feature applies to the following machine types:

For more information about theCitrix Machine Creation ServicesandOther service or technologyoptions, seeMachine management.

Note:

For MCS-provisioned machines, only static persistent machines are supported. Random machines are not supported even if they are persistent.

Upgrade VDAs on a per-catalog basis

Note:

When scheduling VDA upgrades for a catalog, be aware that all machines in the catalog will be included in the upgrade scope. Therefore, we recommend backing up those machines before initiating the upgrade.

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. FromManage > Full Configuration, selectMachine Catalogs.

  2. Select the catalog and thenUpgrade VDAsfrom the contextual menu or action bar. (Right-click to display the contextual menu.) The VDA Upgrade window appears.

    VDA upgrade

  3. Choose whether to upgrade additional components in your deployment. You can also choose to install certain components in addition to the upgrade. If a component requires configuration, you must click theConfigurebutton and configure the component’s settings to continue. After configuring, you can clickEdit来change the configuration.

    Important:

    • To use the additional components feature, make sure that your VDA Upgrade Agent is version 7.34 or later, which is included in the VDA installer version 2206 or later.

    Note:

    • If you choose not to upgrade a component, the component remains intact in your deployment.
    • For a complete list of additional components, seeInstall VDAs.

    Additional components

  4. ClickNext.

  5. Choose whether to enable any of the listed features. ClickNext.

    Note:

    By default, theEnable restore cleanupcheck box is selected. We recommend enabling the restore feature. With the feature enabled, a system restore point is created before the upgrade starts. The restore point is deleted after the successful installation of the VDA. For more information, seeRestore on install or upgrade failure.

    Features

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

    • To upgrade the VDAs immediately, selectUpgrade nowand then specify a duration.

      A duration is the amount of time, in hours, after which the VDA Upgrade Service stops initiating additional upgrades. Upgrades in progress will run to completion. During that time, DaaS starts to upgrade the VDAs when they become eligible (for example, no active sessions anymore).

      The more VDAs that need to be upgraded, the longer this duration is. We recommend selecting a large value (for example, 12 hours). Otherwise, depending on the number of the VDAs, there might still be VDAs that DaaS is unable to upgrade within this window.

    • To schedule the upgrades, selectUpgrade laterand then specify when you want the upgrades to occur.

      你可以安排升级只对下一个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.

    Schedule VDA upgrades

  7. ClickNext.

  8. Review your choices on theSummarypage, then clickFinish来apply your settings and exit the window.

Note:

  • TheUpgrade VDAsoption 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 theMachine Catalogsnode, theVDA Upgradecolumn provides VDA upgrade information for the catalog. The following information can appear:

Tip:

To show theVDA Upgradecolumn, selectColumns to Displayin the action bar, selectMachine Catalog > VDA Upgrade, and then clickSave.

  • 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: Unable to get information necessary for VDA upgrade. There are multiple possible reasons:
    • The VDA was in use during the upgrade window.
    • The number of upgrades in progress reached the maximum limit of 500.
    • TheVDA Upgrade Agent升级期间反应迟钝的窗口。确保that the agent is running on the VDA and can communicate with Citrix DaaS.
    • Unable to perform upgrade validation checks. SeeVDA upgrade requirement.

You can also view the status of VDA upgrades for a catalog. To do that, click the catalog and then check theVDA Upgrade Stateinformation on theDetailstab. 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 at09:00 PM, December 14, 2030, information appears as follows: Scheduled forDecember 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 theTroubleshoottab.

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

Be aware of the following considerations:

  • TheVDA UpgradeorVDA Upgrade Statefilter is available for use only with the following filters:NameandMachine Catalog.
  • When you use theVDA Upgradeor theVDA Upgrade Statefilter,ErrorsandWarningsin 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. FromManage > Full Configuration, selectMachine Catalogs.
  2. Select the catalog and thenEdit Scheduled VDA Upgradein 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, clickCancel scheduled upgrade. Remember: Canceling the scheduled upgrade does not force the upgrade in progress to stop.
  4. ClickDone来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 selectLatest 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. FromManage > Full Configuration, selectSearch.

  2. Select one or more machines and thenUpgrade VDAfrom the contextual menu or action bar. (Right-click to display the contextual menu.)

    VDA upgrade

    Note:

    • For theUpgrade VDAoption 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.
    • 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 theSearchnode, you can add theVDA Upgradecolumn. For information about how to add a custom column, seeCustomize 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 theVDA Upgrade Stateinformation on theDetailstab. The following information can appear:

  • Unknown: Unable to get information necessary for VDA upgrade. There are multiple possible reasons:
    • The VDA was in use during the upgrade window.
    • The number of upgrades in progress reached the maximum limit of 500.
    • TheVDA Upgrade Agent升级期间反应迟钝的窗口。确保that the agent is running on the VDA and can communicate with Citrix DaaS.
    • Unable to perform upgrade validation checks. SeeVDA upgrade requirement.
  • Scheduled: You have set up an upgrade schedule. For example, if you set the schedule to start at09:00 PM, December 14, 2030, information appears as follows: Scheduled forDecember 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 theTroubleshoottab.

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

  • TheVDA UpgradeorVDA Upgrade Statefilter is available for use only with the following filters:NameandMachine Catalog.
  • When you use theVDA Upgradeor theVDA Upgrade Statefilter,ErrorsandWarningsin the upper right corner become unavailable.

Use PowerShell to check VDA upgrade status and VDA version

Use theGet-VusCatalogPowerShell command to check the VDA upgrade status. Suppose that the catalog name iswuhanTestMC1. You can type the following in the command prompt:

  • PS C:\> Get-VusCatalog -Name wuhanTestMC1

VDA upg PowerShell命令来检查rade status

In this example,UpgradeStateisUpgradeAvailable, meaning that VDA upgrade is enabled for the catalog.StateIdisUpgradeSuccessful, meaning that the catalog has been successfully upgraded to 2112.0.0.32068 (UpgradeVersion).

Use theGet-BrokerMachinePowerShell command to get the current VDA version.

PowerShell command to get current VDA version

Use theGet-VusAvailableVdaVersionPowerShell command to get the latest VDA version.

PowerShell command to get latest VDA version

Reset OS disk

Use the PowerShell commandReset-ProvVMDisk来reset the OS disk of a persistent VM in an MCS created machine catalog. Currently, this feature is applicable to Azure, Citrix Hypervisor, Google Cloud, SCVMM, and VMware virtualization environments.

To successfully run the PowerShell command, make sure that:

  • The target VMs are in a persistent MCS catalog.
  • The MCS machine catalog is functioning properly. This implies that the provisioning scheme and host exist, and the provisioning scheme has correct entries.
  • Hypervisor is not in maintenance mode.
  • Target VMs are powered-off and in maintenance mode.

Perform the following steps to reset the OS disk:

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

  3. Run the PowerShell commandReset-ProvVMDiskin any one of the following ways:

    • Specify the list of VMs as a comma-separated list, and perform the reset on each VM:

      Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName ("abc","def") -OS

    • Specify the list of VMs as an output fromGet-ProvVMcommand, and perform the reset on each VM:

      (Get-ProvVM -ProvisioningSchemeName "xxx") | Reset-ProvVMDisk "abc" -OS

    • Specify a single VM by name:

      Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS

    • Create separate reset tasks for each of the VMs returned by theGet-ProvVMcommand. This is less efficient because each task will perform the same redundant checks, such as hypervisor capability check, connection check for each VM.

      Get-ProvVM -ProvisioningSchemeName "xxx" | Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -OS

  4. A confirmation prompt appears that lists the VMs to be reset along with a warning message that it is an unrecoverable operation. If you do not provide an answer and pressEnter, no further action takes place.

    You can run the PowerShell command-WhatIf来print the action it would take and exit without performing the action.

    You can also bypass the confirmation prompt using one of the following methods:

    • Provide the-Forceparameter:

      Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS -Force

    • Provide the-Confirm:$falseparameter:

      Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS -Confirm:$false

    • Before running theReset-ProvVMDisk, change$ConfirmPreference来‘None’:

      PS C:\Windows\system32> $ConfirmPreference='None' PS C:\Windows\system32> $ConfirmPreference None PS C:\Windows\system32> Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS

    Note:

    Do not take VMs out of the maintenance mode or power them on until the completion of the reset process.

  5. RunGet-ProvTask来get the status of the tasks returned byReset-ProvVMDiskcommand.

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-NetworkMappingin theSet-ProvSchemecommand 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 commandasnp citrix*来load the PowerShell modules.
  2. Run(Get-Provscheme -ProvisioningSchemeName "name").NetworkMaps来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"}
  4. RunSet-ProvScheme -ProvisioningSchemeName "name" -NetworkMapping $NewNetworkMap.
  5. Run(Get-Provscheme -ProvisioningSchemeName "name").NetworkMaps来verify the new network setting for the existing provisioning scheme.

Manage configuration set for a catalog

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

Note:

By default, if you have the Cloud Administrator, Full Access Administrator, or Machine Catalog Administrator role, you can manage configuration sets for catalogs. If necessary, you can allow roles to manage configuration sets by granting them theManage configuration setspermission.

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. FromManage > Full Configuration, selectMachine Catalogs.

  2. Select the machine catalog and thenManage configuration setin the action bar. TheManage configuration setwindow 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, theApply basic settings to configuration setoption appears. We recommend that you select the option to apply basic settings to the configuration set.

  4. ClickSave来save your change.

Switch to a different configuration set

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

  1. FromManage > Full Configuration, selectMachine Catalogs.
  2. Select the machine catalog and thenManage configuration setin the action bar. TheManage configuration setwindow appears.
  3. Select a different WEM configuration set to which you want to bind the catalog.
  4. ClickSave来save your change.

Unbind a catalog from the configuration set

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

  1. FromManage > Full Configuration, selectMachine Catalogs.
  2. Select the machine catalog and thenManage configuration setin the action bar. TheManage configuration setwindow appears.
  3. Click the X icon on the right-hand side of the selected configuration set.
  4. ClickSave来save your change.

Add 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:

  • 新ProvScheme. A new parameter,masterImageNoteenables 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"
  • 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"
  • 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

Retry catalog creation

Note:

This feature applies only to MCS catalogs.

Failed catalogs are marked with an error icon. To see the details, go to theTroubleshoottab of each catalog. Before retrying catalog creation, be aware of the following considerations:

  • Check the troubleshooting information first and resolve the issues. The information describes the issues found and provides recommendations for resolving them.
  • You cannot change settings associated withOperating systemandmachine management. The catalog inherits those settings from the original.
  • The creation can take some time to complete. If necessary, selectHide progress来run the creation in the background.

To retry creating a catalog, do the following:

  1. FromManage > Full Configuration, selectMachine Catalogsin the left pane.
  2. Select the catalog and then go to itsTroubleshoottab.
  3. Click the retry hyperlink to retry creating the catalog.
  4. In the wizard that appears, change settings where necessary. If there is no need to make changes, you can go to theSummarypage directly.
  5. After you finish, selectFinish来start the creation.

Troubleshoot

  • For machines withPower State Unknownstatus, seeCTX131267for guidance.
  • To fix VMs that continuously show an unknown power state, see如何解决虚拟机持续显示未知power state.
  • 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.

Where to go next

For information on managing specific hypervisor catalogs, see:

Manage machine catalogs
August 24, 2023
Contributed by:
C
August 24, 2023
Contributed by:
C

In this article

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