Citrix Virtual Apps and Desktops

Manage machine catalogs

November 15, 2024

Contributed by:

C C

Note:

You can manage your Citrix Virtual Apps and Desktops deployment using two management consoles: Web Studio (web-based) and Citrix Studio (Windows-based). This article covers only Web Studio. For information about Citrix Studio, see the equivalent article in Citrix Virtual Apps and Desktops 7 2212 or earlier.

Introduction

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

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

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

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

Note:

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

About persistent instances

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

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

Manage machine catalogs

You can manage a machine catalog in two ways:

Using Web Studio
Using PowerShell

Use Web Studio

This section details how you can manage catalogs using Web Studio:

View catalog details

Use the search function to locate a specific machine catalog. Refer to Search for instances for instructions.
From the search results, select a catalog as necessary.
Refer to the following table for descriptions of the catalog columns.
Click a tab in the bottom details pane for more information about this catalog.

Column	Description
Machine Catalog	The name and the allocation type of the catalog. Allocation types include: Random: Machines in the catalog are allocated to a user randomly. Permanent: Machines in the catalog are allocated to a user permanently.


Machine Type	The supported session type of the machines in the catalog. Possible values include: OS type: Multi-session OS (Virtual); User data: Discard. OS type: Multi-session OS (Virtual); User data: On local disk OS type: Single-session OS (Remote PC Access) OS type: Single-session OS (Virtual); User data: Discard OS type: Single-session OS (Virtual); User data: On local disk





Machine Count	The machine count in the catalog and the provisioning method. Possible provisioning methods include: Machine creation services (MCS machine), Manual, and Citrix provisioning services.
Allocated Count	The number of machines in the catalog assigned to a delivery group.
Folder	The location of the catalog within the Machine Catalogs tree. It displays the name of the folder that the catalog is in (including the trailing backslash), or `-` if the catalog is at the root level.
VDA Upgrade	VDA Upgrade State. Possible values include: Not configured, Scheduled, Available, and Up to date.
Image Status	The image update status of the catalog. Applicable only to non-persistent machine catalogs. Possible values include: Fully updated, Partially updated, Pending updates, Preparing

Add machines to a catalog

Before you start:

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

To add machines to a catalog:

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select a machine catalog and then select Add machines in the action bar.
Select the number of virtual machines to add.
If there are insufficient existing Active Directory accounts for the number of VMs you are adding, select the domain and location where the accounts are created. Specify an account naming scheme, using hash marks to indicate where sequential numbers or letters appear. Do not use a forward slash (/) in an OU name. A name cannot begin with a number. For example, a naming scheme of PC-Sales-## (with 0-9 selected) results in computer accounts named PC-Sales-01, PC-Sales-02, PC-Sales-03, and so on.
If you use existing Active Directory accounts, either browse to the accounts or click Import and specify a .csv file containing account names. Make sure that there are enough accounts for all the machines you’re adding. Web Studio manages these accounts. Either allow Web Studio to reset the passwords for all the accounts, or specify the account password, which must be the same for all accounts.

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

Delete machines from a catalog

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

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

To delete machines from a catalog:

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select a catalog and then select View Machines in the action bar.
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 if the Active Directory accounts for those machines are kept, disabled, or deleted.

Edit a catalog

On the Description page, change the catalog description.
Select Machine Catalogs in the left pane.
Select a catalog and then select Edit Machine Catalog in the action bar.
On the Scopes page, change the scopes.
You might see other 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 the 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.
- (Visible only when the catalog is configured with a dedicated group host) On the Dedicated host group page, choose whether to change a host group.
- On the Storage and License Types page, choose whether to change the storage type, license type, and Azure Computer Gallery settings (available only when Place prepared image in Azure Gallery is in use).
Note:

If the newly selected setting doesn’t support the current machine size, a warning dialog box appears, informing you that changing the setting resets the machine size setting. If you choose to continue, a red dot appears next to the Virtual Machines menu, prompting you to select a new machine size.
- On the License Type page, choose whether to change the Windows license or Linux license setting.
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.
Click Apply to apply the changes you made and click Save to exit.

Rename a catalog

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select a catalog and then select Rename Machine Catalog in the action bar.
Enter the new name.

Move a catalog to a different zone

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

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

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select a catalog and then select Move in the action bar.
Select the zone where you want to move the catalog.

Delete a catalog

Before deleting a catalog, ensure that:

All users are logged off and you don’t run any disconnected sessions.
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:

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select a catalog and then select Delete Machine Catalog in the action bar.
Indicate whether the machines in the catalog are deleted. If you choose to delete the machines, indicate whether the Active Directory computer accounts for those machines are retained, disabled, or deleted.

Manage Active Directory computer accounts in a catalog

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

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

To manage Active Directory accounts:

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select a catalog and then select Manage AD accounts in the action bar.
Choose whether to add or delete computer accounts. If you add accounts, specify what to do with the account passwords: either reset them all or enter a password that applies to all accounts.

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

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

Update a catalog

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

After a machine is updated, it restarts automatically.

Update or create a master image

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

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

Change the master image

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

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select a catalog and then select Change Master Image in the action bar.
On the 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 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, click Template Properties in the low pane, and then click View note history.
On the Rollout Strategy page, choose when the machines in the machine catalog are updated with the new master image: on the next shutdown or immediately.

Note:

The Rollout Strategy page is not available for persistent VMs because rollout is only applicable to non-persistent VMs.
Verify the information on the Summary page and then click Finish. Each machine restarts automatically after it is updated.

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

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

Rollout strategy:

Updating images 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 OS machines, machines are immediately updated when the machine is not in use, or when users are not logged in.
For a multi-session OS with child machines, restarts don’t occur automatically. To apply the updated master image, restart the machines using Studio, PowerShell, or Workspace. Restarting from the machines or the hypervisor doesn’t apply the update.

Tip:

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

Roll back the master image

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

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select the catalog and then select Roll Back Master Image in the action bar.
Specify when to apply the earlier master image to machines, as described in the preceding section for the rollout operation.

The rollback is applied only to machines that need to be reverted. Machines that are not updated with the new or updated master image 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.

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. Citrix recommends 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 the Controller. This process lets Web Studio determine that the machines in the catalog need upgrading.

To change the functional level for a catalog:

Sign in to Web Studio.
Select Machine Catalogs in the left pane.
Select the catalog. The Details tab in the lower pane displays version information.
Select Change Functional Level. If Web Studio detects that the catalog needs upgrading, it displays a message. Follow the prompts. If one or more machines cannot be upgraded, a message explains why. To ensure that all machines function properly, Citrix recommends you resolve machine issues before clicking Change to proceed.

After the catalog change completes, you can revert the machines to their previous VDA versions by selecting the catalog and then selecting Undo Functional Level Change 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. If necessary, select Hide progress to run the cloning in the background.
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.

Sign in to Web Studio, and then select Machine Catalogs in the left pane.
Select a catalog and then select Clone in the action bar.
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.
On the Summary page, view a summary of the settings and select Finish to start cloning.
If necessary, select Hide progress to 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.

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 Web Studio (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:

Select Machine Catalogs in the left pane.
In the folder hierarchy, select a folder and then select Create Folder in the Action bar.
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:

Select Machine Catalogs in the left pane.
View catalogs by folder. You can also turn on View all above the folder hierarchy to view all catalogs at a time.
Right-click a catalog and then select Move Machine Catalog.
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.

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

To manage a folder, follow the below steps:

Select Machine Catalogs in the left pane.
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.
Follow onscreen instructions to complete the remaining steps.

Use PowerShell

This section details how you can manage catalogs using PowerShell:

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 New to Acknowledged
Delete the errors or warnings

To run the PowerShell commands:

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

To get a list of errors and warnings:

Run Get-ProvOperationEvent command.

With no parameters: Gets all errors and warnings
With LinkedObjectType and LinkedObjectUid parameter: Gets all errors and warnings associated with a specific provisioning scheme
With EventId parameter: Gets a specific error or warning that matches this event ID
With Filter parameter: Gets errors or warnings by customized filter

To change the state of errors or warnings from New to Acknowledged:

Run Confirm-ProvOperationEvent command.

With EventId parameter: Sets the state of a specific error or warning that matches this event ID. You can get the EventId of a specific error or warning as an output from Get-ProvOperationEvent command
With LinkedObjectType and LinkedObjectUid parameters: Sets the state of all the errors and warnings associated with a specific provisioning scheme
With All parameter: Sets the state of all errors and warnings as Acknowledged

To delete the errors or warnings:

Run Remove-ProvOperationEvent command.

With EventId parameter: Removes a specific error or warning that matches this event ID. You can get the EventId of a specific error or warning as an output from Get-ProvOperationEvent command
With LinkedObjectType and LinkedObjectUid parameters: Removes all errors and warnings associated with a specific provisioning scheme
With All parameter: Removes all errors and warnings

For more information, see Citrix PowerShell SDK.

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. Use the following commands to add or view image descriptions:

To add a note while creating a machine catalog with a master image, use the parameter MasterImageNote in the NewProvScheme command. For example:

 C:\PS>New-ProvScheme -ProvisioningSchemeName <name> -HostingUnitName <name> -IdentityPoolName <name> -MasterImageVM
 XDHyp:\HostingUnits\<hosting unit name>\<vm name>.vm\Base.snapshot -MasterImageNote "Note"
 <!--NeedCopy-->

To update the master image associated with a machine catalog, use the parameter MasterImageNote in the Publish-ProvMasterVMImage command. For example:

 C:\PS>Publish-ProvMasterVMImage -ProvisioningSchemeName <name> -MasterImageVM XDHyp:\HostingUnits\<hosting unit name>\<vm name>.vm\base.snapshot -MasterImageNote "Note"
 <!--NeedCopy-->

To display the information for each image, use the Get-ProvSchemeMasterVMImageHistory command. For example:
```
 C:\PS>Get-ProvSchemeMasterVMImageHistory -ProvisioningSchemeName MyScheme -Showall
 
```

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 Roll Back Master Image 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.

Reset OS disk

Use the PowerShell command Reset-ProvVMDisk to reset the OS disk of a persistent VM in an MCS created machine catalog. Currently, this feature is applicable to AWS, Azure, XenServer, 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:

Open a PowerShell window.
Run asnp citrix* to load the Citrix-specific PowerShell modules.
Run the PowerShell command Reset-ProvVMDisk in 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 from Get-ProvVM command, 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 the Get-ProvVM command. 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
 
```
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 press Enter, no further action takes place.

Note:

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

You can run the PowerShell command -WhatIf to 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 -Force parameter:
```
 Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS -Force
 
```
- Provide the -Confirm:$false parameter:
```
 Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS -Confirm:$false
 
```
- Before running the Reset-ProvVMDisk, change $ConfirmPreference to None:
```
 PS C:\Windows\system32> $ConfirmPreference='None'
 PS C:\Windows\system32> $ConfirmPreference
 None
 PS C:\Windows\system32> Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS
 
```
Run Get-ProvTask to get the status of the tasks returned by Reset-ProvVMDisk command.

Change the network setting for an existing provisioning scheme

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

Note:

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

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

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

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

$NewNetworkMap = @{"0"= "XDHYP:\HostingUnits\MyNetworks\Network 0.network"}
<!--NeedCopy-->

Run Set-ProvScheme -ProvisioningSchemeName "name" -NetworkMapping $NewNetworkMap.
Run (Get-Provscheme -ProvisioningSchemeName "name").NetworkMaps to verify the new network setting for the existing provisioning scheme.

Manage versions of a machine catalog

When an MCS machine catalog is updated with the Set-ProvScheme command, the current configuration is saved as a version. You can then manage the various versions of the machine catalog using PowerShell commands. You can:

See the list of versions of a machine catalog
Use any previous version to update the machine catalog
Manually delete a version if it is not used by a VM of that machine catalog
Change the maximum number of versions to be retained by the machine catalog (default is 99)

A version includes the following information of a machine catalog:

VMCpuCount
VMMemoryMB
CustomProperties
ServiceOffering
MachineProfile
NetworkMapping
SecurityGroup

Run the following commands (provided as examples) to manage the various versions of a machine catalog.

To see the configuration details of the various versions of a machine catalog:

 Get-ProvSchemeVersion -ProvisioningSchemeName AzureCatalog
 <!--NeedCopy-->

To see the configuration details of a particular version of a machine catalog:

 Get-ProvSchemeVersion -ProvisioningSchemeName AzureCatalog -Version 2
 <!--NeedCopy-->

To see the total number of versions associated with a machine catalog:

``` (Get-ProvSchemeVersion -ProvisioningSchemeName AzureCatalog).Count

To use any previous version to update the machine catalog:

 Set-ProvScheme -ProvisioningSchemeName AzureCatalog -Version 2

To manually delete a version if it is not used by a VM of that machine catalog:
```
 Remove-ProvSchemeVersion -ProvisioningSchemeName AzureCatalog -Version 3
```
To set the maximum number of versions to be retained by the machine catalog (default is 99). This setting is applied across all the catalogs. For example, in this case, a maximum of 15 versions will be retained for all the MCS provisioned catalogs.
```
 Set-ProvServiceConfigurationData -Name "MaxProvSchemeVersions" -Value 15
```

If the number of versions reaches the maximum number of versions, then a new version cannot be created if older versions are in use by any of the VMs in the machine catalog. In that case, do one of the following:

Increase the limit of the maximum number of versions to be retained by the machine catalog.
Update some VMs that are on older versions so that those older versions are no longer referenced by any VMs, and can be deleted.

Convert a non-machine profile-based machine catalog to machine profile-based machine catalog

You can use a VM, template spec (in case of Azure), or launch template (in case of AWS) as a machine profile input to convert a non-machine profile-based machine catalog to machine profile-based machine catalog. New VMs added to the catalog take property values from the machine profile unless overwritten by explicit custom property.

Note:

An existing machine profile-based machine catalog cannot be changed to a non-machine profile-based machine catalog.

To do this:

Create a persistent or non-persistent machine catalog with VMs and without a machine profile.
Open the PowerShell window.

Run the Set-ProvScheme command to apply the property values from the machine profile to the new VMs added to the machine catalog. For example:

In the case of Azure:

 Set-ProvScheme = Set-ProvScheme -ProvisioningSchemeName xxxx -MachineProfile XDHyp:\HostingUnits\<HostingUnitName>\machineprofile.folder\<ResourceGroupName>\<TemplateSpecName>\<VersionName>

In the case of AWS:

 Set-ProvScheme = Set-ProvScheme -ProvisioningSchemeName xxxx -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\<launch-template>.launchtemplate\<launch-template-version>.launchtemplateversion"

Repair the identity information of active computer accounts

You can reset the identity information of active computer accounts that have identity-related problems. You can choose to reset only the machine password and trust keys, or reset all configuration of the identity disk. This implementation is applicable to both persistent and non-persistent MCS machine catalogs.

Note:

Currently, the feature is supported only for Azure and VMware virtualization environments.

Conditions

Ensure the following to successfully reset the identity disk:

Turn off and set the VM to maintenance mode
Do not include the parameter -OS in the PowerShell command

Reset identity disk

To reset identity disk:

Open the PowerShell window.
Run asnp citrix* to load the Citrix-specific PowerShell modules.
Reset the identity information.
- To reset only the machine password and trust keys, run the following command:
```
 Repair-AcctIdentity -IdentityAccountName TEST\VM1 -PrivilegedUserName TEST\admin1 -PrivilegedUserPassword $password -Target IdentityInfo
```
  The description of the parameters used in the command are as follows:
  - IdentityAccountName: The name of the identity account that must be repaired.
  - PrivilegedUserName: User account that has write permission on identity provider (AD or AzureAD).
  - PrivilegedUserPassword: Password for PrivilegedUserName.
  - Target: Target for the repair action. It can be IdentityInfo to repair account password/trust key, and UserCertificate to repair user certificate attributes of Hybrid AzureAD joined machine identities.
- To reset all configuration of the identity disk, run the following commands in the following order:
```
 Repair-AcctIdentity -IdentityAccountName TEST\VM1 -PrivilegedUserName TEST\admin1 -PrivilegedUserPassword $password -Target IdentityInfo
```
```
 Reset-ProvVMDisk ProvisioningSchemeName <name> -VMName <name>  -Identity
```
- To completely recreate the identity disk:
```
 Reset-ProvVMDisk -ProvisioningSchemeName <name> -VMname <name> -Identity -Recreate
```
Type y to confirm the action. You can also skip the confirmation prompt using the -Force parameter. For example:
```
Reset-ProvVMDisk -ProvisioningSchemeName <name> -VMName <name> -Identity -Force
```
Run Get-ProvVM -ProvisioningSchemeName <name -VMName <name> to check the updated identity disk setting. The attributes of the identity disk (for example, IdentityDiskId) must be updated. The StorageId and IdentityDiskIndex must not change.

Change cache configuration on an existing machine catalog

After creating a non-persistent catalog with MCSIO enabled, you can use the Set-ProvScheme command to modify the following parameters:

WriteBackCacheMemorySize
WriteBackCacheDiskSize

This feature is currently applicable to:

GCP and Microsoft Azure environments, and
a non-persistent catalog with MCSIO enabled

Requirements

The requirements to modify the cache configuration are:

Update to the latest version of VDA (2308 or later).

Enable the parameter UseWriteBackCache for the existing machine catalog. Use New-ProvScheme to create a machine catalog with UseWriteBackCache enabled. For example:

 New-ProvScheme -ProvisioningSchemeName $CatalogName -HostingUnitUid $HostingUnitUid `
 -IdentityPoolUid $acctPool.IdentityPoolUid -CleanOnBoot `
 -MasterImageVM $MasterImage `
 -ServiceOffering $ServiceOffering `
 -NetworkMap $NetworkMap `
 -SecurityGroup $SecurityGroup `
 -UseWriteBackCache -WriteBackCacheDiskSize 8

Change the cache configuration

Run the Set-ProvScheme command. For example:

Set-ProvScheme -ProvisioningSchemeName $provScheme.ProvisioningSchemeName -WriteBackCacheDisk32 -WriteBackCacheMemorySize 128

Note:

The value of WriteBackCacheDiskSize must be more than zero because at least 1 GB of cache disk storage is required.

The value of WriteBackCacheMemorySize must be less than the machine catalog memory size.

These changes only affect new VMs added to the catalog after the change is made. Existing VMs are not affected by these changes.

Specify the VDA installer location through PowerShell cmdlets which reduces your effort from providing network rules to allow each VDA to go and fetch the new VDA installer from the Citrix Managed Azure CDN.

PowerShell cmdlets

Two new optional parameters added to New-VusCatalogSchedule and New-VusMachineUpgrade cmdlets that allow you to use installers from a local file share

VdaWorkstationPackageUri - to specify the UNC path to the workstation OS VDA installer
VdaServerPackageUri - to specify the UNC path to the server OS VDA installer

Prerequisites

VUS Agent Installer that comes with VDA 2311
VDA Upgrade Agent to version 7.40.0.35 or later (using the VDA installer version 2311 or later)
Virtual Apps and Desktops Remote PowerShell SDK version 7.40 or newer (released on Jan 10, 2024 or later)

The network shares containing VDA installer packages must have read access for the VDA Upgrade Agent service which runs as Local System (NT AUTHORITY\SYSTEM principal).

Domain-Joined file share permission

When the VDA machine is domain-joined, then the Local System account (VUA runs as Local System), uses computer credentials when accessing network shares.

The least privilege permission can be set by granting the Read access to Domain Computers.
1. Choose people on your network who you want to share the file with.
2. Click Advanced Sharing Settings and turn on File and Printer Sharing.
Non-Domain Joined file share permission

When the VDA machine is non-domain joined, then the Local System account (VUA runs as Local System), uses ANONYMOUS LOGON when accessing network shares.
1. Select a shared folder.
2. Disable the password protection.
  1. Go to Folder Properties.
  2. Select Network and Sharing Center.
  3. Turn off Password Protected Sharing.
3. Click Advanced Sharing to grant a share permission.
  1. Select Permissions.
  2. Grant a Read share permission to ANONYMOUS LOGON.
4. Select the Security Tab to grant folder permissions
  1. Click Edit to add permissions to the shared folder
  2. Select the shared folder to grant folder permissions to ANONYMOUS LOGON.
5. Click Advanced to turn on File and Printer Sharing.
6. Add the shared folder name to Network Access Security Policy.
Note:

Restart your machine for the change to take effect immediately.

Download the VDA installer and place it in the shared file.

Note:

With Virtual Upgrade Service, you can select from either the Current Release track or the LTSR track.

For Example: If the machine catalog is set to Current Release that is 2311, and the VDA version is 2305, you must upgrade the VDA to version 2311.
1. Navigate to the Downloads page on our website.
2. Select Citrix Virtual Apps and Desktops as the product.
3. Select Citrix Virtual Apps and Desktops 7 2311, All Editions.
4. Select the VDA installer from the Components that are on product ISO but also packaged separately expandable.
Select the relevant VDA installer based on the catalog type.
- Download the Multi-session OS VDA installer if the catalog type is multi session
- Download the Single-session OS VDA installer if the catalog type is single session
- Download the Single-session OS Core Services VDA installer if the catalog type is Remote PC Access

Note:

The version of the file share installer has to exactly match the version of the latest installer version published by VUS to the cloud.

Troubleshoot

For machines with “Power State Unknown” status, see CTX131267 for guidance.
To fix VMs that continuously show an unknown power state, see How to fix VMs that continuously show an unknown power state.

Where to go next

For information on managing specific cloud services catalogs, see:

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Manage machine catalogs

November 15, 2024

Contributed by:

C C

November 15, 2024

Contributed by:

C C

Introduction
Manage machine catalogs
Use Web Studio
View catalog details
Add machines to a catalog
Delete machines from a catalog
Edit a catalog
Rename a catalog
Move a catalog to a different zone
Delete a catalog
Manage Active Directory computer accounts in a catalog
Update a catalog
Change the functional level or undo the change
Clone a catalog
Organize catalogs using folders
Use PowerShell
Retrieve warnings and errors associated with a catalog
Add descriptions to an image
Reset OS disk
Change the network setting for an existing provisioning scheme
Manage versions of a machine catalog
Convert a non-machine profile-based machine catalog to machine profile-based machine catalog
Repair the identity information of active computer accounts
Change cache configuration on an existing machine catalog
VDA Update Support via Local File Share Access
Troubleshoot
Where to go next

Was this helpful

Manage machine catalogs

Introduction

About persistent instances

Manage machine catalogs

Use Web Studio

View catalog details

Add machines to a catalog

Delete machines from a catalog

Edit a catalog

Rename a catalog

Move a catalog to a different zone

Delete a catalog

Manage Active Directory computer accounts in a catalog

Update a catalog

Update or create a master image

Change the master image

Roll back the master image

Change the functional level or undo the change

Clone a catalog

Organize catalogs using folders

Create a catalog folder

Move a catalog

Manage catalog folders

Use PowerShell

Retrieve warnings and errors associated with a catalog

Add descriptions to an image

Reset OS disk

Change the network setting for an existing provisioning scheme

Manage versions of a machine catalog

Convert a non-machine profile-based machine catalog to machine profile-based machine catalog

Repair the identity information of active computer accounts

Conditions

Reset identity disk

Change cache configuration on an existing machine catalog

Requirements

Change the cache configuration

VDA Update Support via Local File Share Access

PowerShell cmdlets

Prerequisites

How to Set File Share Permissions

VDA Updates from a Local File Share

Troubleshoot

Where to go next

In this article