Manage machine catalogs
Note:
This article describes how to manage catalogs using Studio and PowerShell commands. If you created the catalog using the Quick Deploy node, and continue using that node to manage the catalog, then follow Manage catalogs in Quick Deploy.
Introduction
You can add or remove machines from a machine catalog, and rename, change the description, or manage a catalog’s Active Directory computer accounts.
Catalog maintenance can also include the tasks of making sure that each machine has the latest OS updates, antivirus software updates, operating system upgrades, or configuration changes.
- Catalogs containing pooled random machines created using Machine Creation Services (MCS) maintain machines by updating the image used in the catalog and then updating the machines. This method lets you update large numbers of user machines efficiently.
- For catalogs containing static, permanently assigned machines, you can manage the image or template that those catalogs currently use but only the machines you add to the catalogs later are created using the new image or template.
- For Remote PC Access catalogs, you manage updates to users’ machines outside of Studio. 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 Create and manage 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 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.
Manage machine catalogs
You can manage a machine catalog in two ways:
Use Studio
This section details how you can manage catalogs using Studio:
- View catalog details
- Add machines to a catalog
- Delete machines from a catalog
- Edit a catalog
- Rename a catalog
- Delete a catalog
- Manage Active Directory computer accounts in a catalog
- Change the master image for a catalog
- Change the functional level or undo the change
- Clone a catalog
- Organize catalogs using folders
- Configure auto-upgrade for VDAs
- Manage configuration set for a catalog
- Retry catalog creation
- (Non-Citrix provisioned VDAs only) Generate and manage enrollment tokens
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:
|
Machine Type
|
The supported session type of the machines in the catalog. Possible values include:
|
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 status of the image update 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 the virtualization host (hypervisor or cloud service provider) has sufficient processors, memory, and storage to accommodate the additional machines.
- Make sure that you have enough unused Active Directory computer accounts. If you are using existing accounts, the number of machines you can add is limited by the number of accounts available.
- If you use Studio 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 the Log on to.. screen.
To add machines to a catalog:
- From Studio, select Machine Catalogs in the left pane.
- Select a machine catalog and then select Add machines in the action bar.
- On the Virtual Machines page, select the number of virtual machines to add.
-
On the Machine Identities page, configure the settings as follows:
-
Select an identity from the list.
-
If applicable, indicate whether to create accounts or use existing ones, and the location (domain) for those accounts.
If there are insufficient existing Active Directory accounts for the number of VMs you are adding, select the domain and location where the accounts are created.
If you use existing Active Directory accounts, browse to the accounts or select Import and specify a
.csv
file containing account names. Make sure that there are enough accounts for all the machines you are adding. Studio 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. -
If this identity pool is used by other catalogs, you can’t change it to a different pool using Studio. Instead, use the Set-ProvScheme PowerShell cmdlet. For more information, see the Citrix Virtual Apps and Desktops SDK Documentation.
-
Specify an account naming scheme, using hash marks to indicate where sequential numbers or letters appear. For example, a naming scheme of PC-Sales-## (with 0-9 selected) results in computer accounts named PC-Sales-01, PC-Sales-02, PC-Sales-03, and so on.
-
Optionally, you can specify what the account names start with.
When specifying what the account names start with, be aware of the following scenario: If the starting numbers or letters are already in use, the first account created is named using the nearest unused numbers or letters thereafter.
See Manage the sequence number of the machine name to customize the sequence number of machines, which are deployed using MCS, through PowerShell commands.
-
- On the Domain Credentials page, select Enter credentials and enter user credentials with sufficient permissions to create machine accounts.
The machines are created as a background process, and can take much time when creating many machines. Machine creation continues even if you close the Studio.
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:
- From Studio, select Machine Catalogs in the left pane.
- Select a machine catalog and then select Add Machines in the action bar. The Add Machines window appears.
- Select Add CSV File. The Add Machines in Bulk window appears.
- Select Download CSV Template.
- Fill out the template file.
- Drag or browse to the file to upload it.
- Select Validate to perform validation checks on your import.
- Select Import to complete the process.
Considerations when using CSV files to add machines
Note:
- For non-Active Directory users, you must type their names in this format:
<identity provider>:<user name>
. Example:AzureAD:username
.- 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-scale
is the ConnectionName: The name of the connection that you entered in Hosting > Add Connections and Resources. For more information, see Create a connection and resources. -
East US.region
is the RegionName: The name of the region with.region
as extension. -
wsvdaV3-2.vm
is the VMName: The name of the virtual machine with.vm
as 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 same Add Machines page. The exported CSV of machines can then be used as a template when adding machines in bulk. To export machines:
- From Studio, select Machine Catalogs in the left pane.
- Select a machine catalog and then select Add Machines in the action bar. The Add Machines window appears.
- Select Export to CSV file. A CSV file containing a list of the machines is downloaded.
- 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.
Enroll machines to catalogs using the WebSocket VDA enrollment tool
The WebSocket VDA enrollment tool facilitates token-based enrollment for VDA machines. This tool helps you convert a connection to a WebSocket connection by adding the VDA to the machine catalog using the enrollment token.
Note:
This tool is designed to enroll VDA machines that haven’t been enrolled in any machine catalog.
Follow the instructions to run the enrollment tool:
- Log in to the VDA.
- Locate the tool
EnrollMachine.exe
, inC:\Program Files\Citrix\Virtual Desktop Agent\Web Socket Vda Enrollment Tool
. - Run the tool with the appropriate input parameters. For example,
EnrollMachine.exe -websocket_token_string:xxxxxxxxx
The following table describes the input parameters of the enrollment tool:
Parameter Name | Required | Description | Example |
---|---|---|---|
-websocket_token_stdin |
Yes
|
Reads the enrollment token. | .\EnrollMachine.exe -websocket_token_stdin |
-websocket_token_string |
Reads the enrollment token directly from the command line parameter. | .\EnrollMachine.exe -websocket_token_string:<token> |
|
-websocket_token_file:[token-file-path] |
Reads the enrollment token from the path provided. | .\EnrollMachine.exe -websocket_token_file:C:\token\test2.txt |
|
log:[log-file-path] |
No | Shows the Enrollment tool logs. | .\EnrollMachine.exe log:[C:\ProgramData\Citrix\EnrollMachine\EnrollMachine.txt] |
-help |
No | Shows a brief help text. | .\EnrollMachine.exe -help |
After successful enrollment, you will receive a success message on the tool and in the logs. Ensure to sign in to Studio to verify that the VDA machine is added to the catalog and that the status of the machine is registered.
Troubleshooting
By default, you can find the logs of the enrollment tool at:
C:\ProgramData\Citrix\EnrollMachine\EnrollMachine.txt
If you have specified a different path for the logs, you can use log:[log-file-path]
to retrieve your logs.
The following table lists the codes returned by the enrollment tool:
Code | String | Description |
---|---|---|
0 | Success | VDA is successfully added to the machine catalog. |
-1 | InvalidArgument | The input parameter in the enrollment token is invalid. |
-2 | BrokerAgentNotFound | The broker agent service is not found. |
-3 | TokenInvalid | The token entered is invalid. |
-4 | TokenMissingRequiredClaims | The required claims for the token are missing, for example, CustomerId, or Enrollment URIs. |
-5 | InternalError | A general error has occurred. |
-6 | TimedOut | The task has timed out. |
-7 | FailedToDetermineMachineADJoinedStatus | The service that returns the machine AD joined status failed. |
-8 | ADMachineFailedToFindSid | The service that returns the AD machine Sid failed. |
-9 | EnrollRequestFailed | The request failed due to an HTTP error. |
-10 | EnrollResponseMissingRequiredFields | The enrollment tool response is missing the parameter VirtualSiteId . |
-11 | InsufficientPermission | You do not have the required permission to run the task. |
-12 | FailedToDetermineMachineAadJoinedStatus | The service that checks the machine AD join status throws an error. |
-13 | AadMachineFailedToFindDeviceId | The additional parameter AAD device id added by the system is empty. |
-14 | AadDeviceIdNotValid | The additional parameter AAD device id added by the system is not a valid guid. |
-15 | NoValidMacAddress | Invalid MAC address. |
-16 | FailedToGetComputerHostNameForVdaInstanceName | Failed to get the computer host name to set the additional parameter VdaInstanceName . |
-17 | VirtualDesktopAgentRegistryKeyFailedToOpen | Failed to open the VDA registry key to write the list of Delivery controllers. |
-18 | Failed Token reached the max count | Failed Token reached the max count. |
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:
- From 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.
- 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.
Edit a catalog
- From Studio, 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.
-
On the NIC page, perform the following actions:
- To change the subnet mapping of an NIC, select a network from the Associated Network field.
- To add a subnet mapping, select Add NIC, select a network from the Associated Network field, and click Save.
Only those subnets present in the host associated with the catalog appear in the Associated Network field.
You can only add NIC to Azure machine catalogs without machine profiles.
Note:
- For AWS machine catalogs, you cannot map the same subnet to more than one NIC.
- For machine catalogs with machine profiles, the number of NICs on the catalog must be equal to the number of NICs on the machine profile.
- This feature is not supported for IBM Cloud hypervisors.
- This feature is supported only for Nutanix Prism Element in Nutanix hypervisors.
- On the VDA Upgrade page, change or select the VDA version to upgrade to. For more information, see VDA upgrade.
-
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 the 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.
-
(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.
For more information about settings available on the pages, see Create a machine catalog using an Azure Resource Manager image.
For Remote PC Access catalogs, the following pages are visible:
- On the Power Management page, change the power management settings and select a power management connection.
- On the Organizational Units page, add or remove Active Directory OUs.
-
- On the Description page, change the catalog description.
- Click Apply to apply the changes you made and click Save to exit.
Rename a catalog
- From 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.
Delete 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:
- From Studio, select Machine Catalogs in the left pane.
- Select a catalog and then select Delete Machine Catalog in the action bar.
- 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.
- If necessary, select Hide progress to run the deletion in the background.
Note:
- 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.
- When the hypervisor or cloud service is unreachable during catalog deletion, both catalog and VM deletion fail. If needed, you can choose to delete the VM records only from your Citrix site database. To do so, select the machine catalog in the Machine Catalogs node, and then perform the deletion shown on the Troubleshoot tab. Keep in mind that this action leaves the VMs intact on the host.
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:
- From 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. 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.
- 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.
- If necessary, power on the image, and log on.
- Install updates or make any required changes to the image.
- If the image uses a Personal vDisk, update the inventory.
- Power off the VM.
- Take a snapshot of the VM, and give the snapshot a meaningful name that is recognized when you change the master image.
Note:
Although you can create a snapshot using the management interface, we recommend that you create a snapshot using the hypervisor management console, and then select that snapshot in Studio. 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:
- From 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 changed with the new 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 select Finish. Each machine restarts automatically after it is updated.
To track the progress of the update, locate the catalog in Machine Catalogs to view the inline progress bar and the step-by-step progress graph. For a non-persistent catalog, you can track its image update statuses through the Image Update column, including Fully updated, Partially updated, Pending update, and Preparing image.
Tip:
To show the Image Update column, select the Columns to Display icon in the action bar, select Machine Catalog > Image Status, and then click Save.
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
Changing the image on the next shutdown will immediately affect any machines not currently in use, that is, machines that do not have an active user session. A system that is in use receives the update when the current active session ends.
Note:
Rollout strategy is only applicable to non-persistent VMs.
Consider the following:
- New sessions cannot be launched until the update has completed on applicable machines.
- For single-session machines, machines are immediately updated when the machine is not in use, or when users are not logged in.
- For a multi-session OS with child machines, reboots do not occur automatically. They must be manually shut down and restarted.
Tip:
Limit the number of machines being rebooted by using the advanced settings for a host connection. Use these settings to modify the actions taken for a given catalog; advanced settings vary depending on the hypervisor.
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.
- From 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 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 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.
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:
- From 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 the management interface detects that the catalog must 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 clicking Change.
After the catalog upgrade 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.
- You can create an empty catalog by cloning. During catalog cloning, you can set the number of machines to zero for MCS-provisioned catalogs and add no machines for non-MCS-provisioned catalogs.
- From Studio, 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.
Tip:
You can set your preferred default view (folder or list view) for the Machine Catalogs node by clicking the Folder icon on the top right of the action bar.
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, see Required permissions.
Create a catalog folder
Before you start, first plan how to organize your catalogs. Consider the following:
- You can nest folders up to five levels deep (excluding the default root folder).
- A catalog folder can contain catalogs and subfolders.
- All nodes in 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:
- From Studio, 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:
- From Studio, 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 these steps:
- From Studio, 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 the onscreen instructions to complete the remaining steps.
Required permissions
The following table lists the permissions required to do actions on catalog folders.
Action | Required permissions |
---|---|
Create catalog folders | Create Machine Catalog Folder |
Delete catalog folders | Remove Machine Catalog Folder |
Move catalog folders | Move Machine Catalog Folder |
Rename catalog folders | Edit Machine Catalog Folder |
Move catalogs to folders | Edit Machine Catalog Folder and Edit Machine Catalog 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. See Upgrade VDAs using Studio.
- 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, see Upgrade VDAs using Studio.
- 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. See Upgrade 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:
- MCS-provisioned persistent machines (AD joined, Azure AD joined, and non-domain-joined). You deploy them using Citrix Machine Creation Services on the Machine Management page during catalog creation.
- Remote PC Access machines
- Citrix HDX Plus for Windows 365 machines
- Other persistent machines provisioned using non-Citrix provisioning services or technologies. You add those machines into DaaS for management by using Other service or technology on the Machine Management page during catalog creation.
For more information about the Citrix Machine Creation Services and Other service or technology options, see Machine 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, ensure all machines in the catalog are 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:
- From Studio, select Machine Catalogs.
-
Select the catalog and then Upgrade VDAs from the contextual menu or action bar. (Right-click to display the contextual menu.) The VDA Upgrade window appears.
-
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 the Configure button and configure the component’s settings to continue. After configuring, you can click Edit to 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, see Install VDAs.
- Click Next.
-
Choose whether to enable any of the listed features. Click Next.
Note:
By default, the Enable restore cleanup checkbox 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, see Restore on install or upgrade failure.
-
Choose whether to upgrade the VDAs immediately or at a scheduled time.
-
To upgrade the VDAs immediately, select Upgrade now and then specify a duration.
A duration is the amount of time, in hours, after which the VDA Upgrade Service stops 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 must 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, select Upgrade later and then specify when you want the upgrades to occur.
You can schedule the upgrades only for the next seven days. Upgrades you schedule apply only to the machines that are currently in the catalog. If you add machines to the catalog later but want to upgrade them as well, cancel the scheduled upgrade and then recreate a schedule.
-
-
Select the Stop upgrade after the failure limit (Tech Preview) option.
Behaviour illustration
-
Failure Threshold and Concurrency Level must be greater than Zero.
-
Failure Threshold and Concurrency Level must be lesser than or equal to the Total Number of machines being scheduled for Upgrade
Failure Threshold Concurrency Level Behavior Provided Not Provided or input 0 FailureThreshold is applied and ConcucrrencyLevel is decided by the load balancer as before. Not Provided or input 0 Provided FailureThreshold defaults to 10000 (Max Machines Per catalog) and ConcucrrencyLevel is used for batching. Not Provided or input 0 Not Provided or input 0 The Default behavior is applicable with concurrency levels updated by the load balancer. -
-
Enter the FailureThreshold.
Note:
Failure Threshold is the number of failures after which the VUS halts any pending upgrade installation from subsequent batches that are not picked up by the upgrade agent.
-
Enter the Concurrency.
Note:
Concurrent Upgrade is the number of VMs that can concurrently upgrade at any point within the upgrade window.
-
Click Next.
Note:
ExitOnError is incompatible with Enable Restore or Enable Restore and Cleanup and may not work as intended.
- Review your choices on the Summary page, then click Finish to apply your settings and exit the window.
Note:
- The Upgrade VDAs option is available only after you enable VDA upgrade for the catalog. To enable VDA upgrade, edit the catalog.
- All machines in the catalog are placed in maintenance mode while upgrades are rolled out. Upgrades can take up to 30 minutes to begin and will be performed only during the specified time period.
On the Machine Catalogs node, the VDA Upgrade column provides VDA upgrade information for the catalog. The following information can appear:
Tip:
To show the VDA Upgrade column, select Columns to Display in the action bar, select Machine Catalog > VDA Upgrade, and then click Save.
- Available: A new VDA version is available.
- Scheduled: The VDA upgrade has been scheduled.
- Not configured: Appears when you have not enabled VDA upgrade for the catalog.
- Up to date: The catalog’s VDAs are up to date.
-
Unknown: 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.
- The VDA Upgrade Agent was unresponsive during the upgrade window. Ensure that the agent is running on the VDA and can communicate with Citrix DaaS.
- Unable to perform upgrade validation checks. See VDA upgrade requirement.
You can also view the status of VDA upgrades for a catalog. To do that, click the catalog and then check the VDA Upgrade State information on the Details tab. The following information can appear:
- Not scheduled: You have enabled VDA upgrade for the catalog but have not set up an upgrade schedule.
-
Scheduled: You have created an upgrade schedule for the catalog. For example, if you set the schedule to start at
09:00 PM, December 14, 2030
, information appears as follows: Scheduled 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 the Troubleshoot tab.
To quickly drill down to catalogs that have a specific VDA upgrade state, you can use filters. For more information, see Use Search in Studio.
Be aware of the following considerations:
- The VDA Upgrade or VDA Upgrade State filter is available for use only with the following filters: Name and Machine Catalog.
- When you use the VDA Upgrade or the VDA Upgrade State filter, Errors and Warnings in the upper right corner become unavailable.
Edit or cancel a scheduled VDA upgrade
After you schedule the upgrades for a catalog, you might want to edit or cancel the scheduled upgrade. To do that, follow these steps:
- From Studio, select Machine Catalogs.
- Select the catalog and then Edit Scheduled VDA Upgrade in the action bar. The Edit VDA Upgrade window appears, showing information about the installed VDA version and VDA version to upgrade to.
-
Choose whether to edit or cancel the scheduled upgrade.
- To cancel the upgrade, click Cancel scheduled upgrade. Remember: Canceling the scheduled upgrade does not force the upgrade in progress to stop.
- Click Done to exit the window.
Configure VDA upgrade settings by editing a catalog
After catalog creation, you can configure VDA upgrade settings by editing the catalog. Before you start editing, consider the following:
-
Verify that all machines in the catalog are on the same VDA (CR or LTSR) track. Otherwise, certain VDA upgrades will fail. For example, if you select Latest LTSR VDA, CR VDA upgrades will fail.
-
Upgrades to some of the machines in the catalog might have started. You cannot modify upgrades that are already in progress. Upgrades in progress continue. Those that have not yet started will upgrade to the specified version.
Upgrade VDAs on a per-machine basis
After enabling VDA upgrade for a catalog, you can upgrade the catalog’s VDAs one by one or in batches. To do that, follow these steps:
- From Studio, select Search.
-
Select one or more machines and then Upgrade VDA from the contextual menu or action bar. (Right-click to display the contextual menu.)
Note:
- For the Upgrade VDA option to be available, make sure that you have enabled VDA upgrade for the catalog where the selected machines reside and that those machines have the VDA Upgrade Agent installed. To enable VDA upgrade for it, edit the catalog.
- Machines will be placed in maintenance mode while upgrades are rolled out. Upgrades can take up to 30 minutes to begin.
- If your selection contains machines for which VDA upgrades are not available or whose upgrades are pending (scheduled, in progress, or awaiting upgrades), we will skip upgrades for those machines.
On the Search node, you can add the VDA Upgrade column. For information about how to add a custom column, see Customize columns to display. The column is useful. It provides VDA upgrade information for the machine. The following information can appear:
- Available: A new VDA version is available.
- Scheduled: The VDA upgrade has been scheduled.
- Not configured: Appears when you have not enabled VDA upgrade for the machine.
- Up to date: The VDA is up to date.
- Unknown: Information about the VDA upgrade is not yet available.
You can also view the status of the VDA upgrade for a machine. To do that, click the machine and then check the VDA Upgrade State information on the Details tab. The following information can appear:
-
Unknown: 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.
- The VDA Upgrade Agent was unresponsive during the upgrade window. Ensure that the agent is running on the VDA and can communicate with Citrix DaaS.
- Unable to perform upgrade validation checks. See VDA upgrade requirement.
-
Scheduled: You have set up an upgrade schedule. For example, if you set the schedule to start at
09:00 PM, December 14, 2030
, information appears as follows: Scheduled 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 the Troubleshoot tab.
To quickly drill down to machines that have a specific VDA upgrade state, you can use filters. For more information, see Use Search in Studio. Be aware of the following considerations:
- The VDA Upgrade or VDA Upgrade State filter is available for use only with the following filters: Name and Machine Catalog.
- When you use the VDA Upgrade or the VDA Upgrade State filter, Errors and Warnings in the upper right corner become unavailable.
Manage configuration set for a catalog
Before you start, make sure that you have set up your WEM service deployment. For more information, see Get started with Workspace Environment Management service.
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 the Manage configuration sets permission.
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:
-
From Studio, select Machine Catalogs.
-
Select the machine catalog and then Manage configuration set in the action bar. The Manage configuration set window appears.
-
Select a WEM configuration set to which you want to bind the catalog.
Note:
If the selected configuration set does not contain settings relating to the basic configuration of WEM, the Apply basic settings to configuration set option appears. We recommend that you select the option to apply basic settings to the configuration set.
-
Click Save to save your change.
Switch to a different configuration set
To switch to a different configuration set for a catalog, follow these steps:
- From Studio, select Machine Catalogs.
- Select the machine catalog and then Manage configuration set in the action bar. The Manage configuration set window appears.
- Select a different WEM configuration set to which you want to bind the catalog.
- Click Save to save your change.
Unbind a catalog from the configuration set
To unbind a catalog from the configuration set, follow these steps:
- From Studio, select Machine Catalogs.
- Select the machine catalog and then Manage configuration set in the action bar. The Manage configuration set window appears.
- Click the X icon on the right-hand side of the selected configuration set.
- Click Save to save your change.
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 the Troubleshoot tab 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 with Operating system and machine management. The catalog inherits those settings from the original.
- The creation can take some time to complete. If necessary, select Hide progress to run the creation in the background.
To retry creating a catalog, do the following:
- From Studio, select Machine Catalogs in the left pane.
- Select the catalog and then go to its Troubleshoot tab.
- Click the retry hyperlink to retry creating the catalog.
- In the wizard that appears, change settings where necessary. If there is no need to make changes, you can go to the Summary page directly.
- After you finish, select Finish to start the creation.
(Non-Citrix provisioned VDAs only) Generate and manage enrollment tokens
After you decide to adopt token-based enrollment for non-Citrix provisioned machines, generate tokens on a per-machine catalog basis, and then share them with VDA installation administrators.
An enrollment token features:
- Registration range: 1 to 100 VDA machines
- Validity period: up to 14 days
To generate a token for a catalog using Studio, follow these steps:
- In Machine Catalogs, locate a non-MCS-provisioned catalog, which has Provisioning method: Manual displayed in the Machine Count column.
- Right-click the catalog, and then select Manage Enrollment Tokens.
- On the Generate enrollment token page that appears, provide the following token information:
- Type a name for the token.
- Enter its validity period. The period must be no more than 14 days. The token is valid only for the specified period.
- (Optional) Select a host connection for power management of VDAs enrolled with the token. Options include all host connections under this catalog’s zone.
- Enter the token usage limits (between 1–100).
- Click Generate.
-
In the Token successfully generated window that appears, copy the token and save it in a safe place, or click Download to download it to the Downloads folder.
A token record appears in the token list.
-
Share the token with VDA installation administrators.
For more information about how to install VDA and a token on machines, see Install VDAs.
Manage tokens
You have two options to revoke a token and make it unavailable for VDA enrollment:
- Revoke: Revoke the token but retain it in the list for logging purposes.
- Delete: Revoke the token and delete it from the list.
Note:
Expired tokens are automatically deleted in 14 days.
Use PowerShell
This section details how you can manage catalogs using PowerShell:
- Use PowerShell to check VDA upgrade status and VDA version
- Manage the sequence number of the machine name
- Add descriptions to an image
- Reset OS disk
- Repair the identity information of active computer accounts
- Change the network setting for an existing machine catalog
- Manage versions of a machine catalog
- Change cache configuration of an existing machine catalog
- Convert a non-machine profile-based machine catalog to machine profile-based machine catalog
- Retrieve warnings and errors associated with a catalog
- Delete machines without hypervisor access
- Update properties of individual VMs
- VDA update support via local file share access
Use PowerShell to check VDA upgrade status and VDA version
Use the Get-VusCatalog
PowerShell command to check the VDA upgrade status. Suppose that the catalog name is wuhanTestMC1
. You can type the following in the command prompt:
PS C:\> Get-VusCatalog -Name wuhanTestMC1
In this example, UpgradeState
is UpgradeAvailable
, meaning that VDA upgrade is enabled for the catalog. The StateId
is UpgradeSuccessful
, meaning that the catalog has been successfully upgraded to 2112.0.0.32068 (UpgradeVersion
).
Use the Get-BrokerMachine
PowerShell command to get the current VDA version.
Use the Get-VusAvailableVdaVersion
PowerShell command to get the latest VDA version.
Manage the sequence number of the machine name
To customize the sequence number of machines, which are deployed using MCS, through PowerShell commands, do the following:
- Open PowerShell as an administrator on the Delivery Controller.
- Run the command
asnp citrix*
to load the Citrix modules. -
Run the following command to check the start count for the identity pool of the catalog:
Get-AcctIdentityPool -IdentityPoolName xxx <!--NeedCopy-->
The
IdentityPoolName
is the name of the catalog. -
If you want to set this count to a different value, run the following command and specify the StartCount as X:
Set-AcctIdentityPool -IdentityPoolName xxx -StartCount X <!--NeedCopy-->
- Add the machines to the catalog so that the machines are created with the required count.
-
After creating the machines, run the following command to set it back to the original value Y:
Set-AcctIdentityPool -IdentityPoolName xxx -StartCount Y <!--NeedCopy-->
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:
-
NewProvScheme
. A new parameter,masterImageNote
enables you to add a note to an image. For example:
C:\PS>New-ProvScheme -ProvisioningSchemeName XenPS -HostingUnitName XenHu -IdentityPoolName idPool1 -MasterImageVM XDHyp:\HostingUnits\XenHU\Base.vm\Base.snapshot -MasterImageNote "Office365 installed"
<!--NeedCopy-->
-
Publish-ProvMasterVMImage
. Use this parameter to publish the note. For example:
C:\PS>Publish-ProvMasterVMImage -ProvisioningSchemeName MyScheme -MasterImageVM XDHyp:\HostingUnits\HostUnit1\RhoneCC_baseXP.vm\base.snapshot -MasterImageNote "Visual Studio 2019 installed"
<!--NeedCopy-->
-
Get-ProvSchemeMasterVMImageHistory
. Display information for each image. For example:
C:\PS>Get-ProvSchemeMasterVMImageHistory -ProvisioningSchemeName MyScheme -Showall
VMImageHistoryUid : 3cba3a75-89cd-4868-989b-27feb378fec5
ProvisioningSchemeUid : 7585f0de-192e-4847-a6d8-22713c3a2f42
ProvisioningSchemeName : MyScheme
MasterImageVM : /Base.vm/base.snapshot
Date : 17/05/2021 09:27:50
MasterImageNote : Office365 installed
<!--NeedCopy-->
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, Google Cloud, SCVMM, VMware, and XenServer 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 <!--NeedCopy-->
-
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 <!--NeedCopy-->
-
Specify a single VM by name:
Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS <!--NeedCopy-->
-
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 <!--NeedCopy-->
-
-
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.
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 <!--NeedCopy-->
-
Provide the
-Confirm:$false
parameter:Reset-ProvVMDisk -ProvisioningSchemeName "xxx" -VMName "abc" -OS -Confirm:$false <!--NeedCopy-->
-
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 <!--NeedCopy-->
Note:
Do not take VMs out of the maintenance mode or power them on until the completion of the reset process.
-
- Run
Get-ProvTask
to get the status of the tasks returned byReset-ProvVMDisk
command.
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 AWS, Azure, GCP, SCVMM, VMware, and XenServer 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 information
To reset identity information:
- 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 <!--NeedCopy-->
The description of the parameters used in the command is 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 Azure AD). -
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 Azure AD 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 <!--NeedCopy-->
Reset-ProvVMDisk ProvisioningSchemeName <name> -VMName <name> -Identity <!--NeedCopy-->
-
To completely recreate the identity disk:
Reset-ProvVMDisk -ProvisioningSchemeName <name> -VMname <name> -Identity -Recreate <!--NeedCopy-->
-
-
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 <!--NeedCopy-->
- 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. TheStorageId
andIdentityDiskIndex
must not change.
Change the network setting for an existing machine catalog
You can change the network setting for an existing machine catalog so that the new VMs are created on the new subnetwork. Use the parameter -NetworkMapping
in the Set-ProvScheme
command to change the network setting.
To change the network setting for an existing provisioning scheme, do the following:
- 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 (the 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 <!--NeedCopy-->
-
To use any previous version to update the machine catalog:
Set-ProvScheme -ProvisioningSchemeName AzureCatalog -Version 2 <!--NeedCopy-->
-
To manually delete a version if it is not used by a VM of that machine catalog:
Remove-ProvSchemeVersion -ProvisioningSchemeName AzureCatalog -Version 3 <!--NeedCopy-->
-
To set the maximum number of versions to be retained by the machine catalog (the 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 <!--NeedCopy-->
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.
Change cache configuration of 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. UseNew-ProvScheme
to create a machine catalog withUseWriteBackCache
enabled. For example:New-ProvScheme -ProvisioningSchemeName $CatalogName -HostingUnitUid $HostingUnitUid ` -IdentityPoolUid $acctPool.IdentityPoolUid -CleanOnBoot ` -MasterImageVM $MasterImage ` -ServiceOffering $ServiceOffering ` -NetworkMap $NetworkMap ` -SecurityGroup $SecurityGroup ` -UseWriteBackCache -WriteBackCacheDiskSize 8 <!--NeedCopy-->
Change the cache configuration
Run the Set-ProvScheme
command. For example:
Set-ProvScheme -ProvisioningSchemeName $provScheme.ProvisioningSchemeName -WriteBackCacheDisk32 -WriteBackCacheMemorySize 128
<!--NeedCopy-->
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.
Convert a non-machine profile-based machine catalog to a 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.
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> <!--NeedCopy-->
-
In the case of AWS:
Set-ProvScheme = Set-ProvScheme -ProvisioningSchemeName xxxx -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\<launch-template>.launchtemplate\<launch-template-version>.launchtemplateversion" <!--NeedCopy-->
-
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
andLinkedObjectUid
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 a 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 theEventId
of a specific error or warning as an output fromGet-ProvOperationEvent
command - With
LinkedObjectType
andLinkedObjectUid
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 theEventId
of a specific error or warning as an output fromGet-ProvOperationEvent
command - With
LinkedObjectType
andLinkedObjectUid
parameters: Removes all errors and warnings associated with a specific provisioning scheme - With
All
parameter: Removes all errors and warnings
For more information, see the Citrix PowerShell SDK.
Delete 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 the PurgeDBOnly
option in Remove-ProvVM
PowerShell 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 command Remove-ProvVM -ProvisioningSchemeName SCVMM-MC -VMName SCVMM01 -ForgetVM
the 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 -PurgeDBOnly
option in the Remove-ProvVM
PowerShell command to delete references of a VM from MCS database. For example,
Remove-ProvVM -ProvisioningSchemeName SCVMM-MC -VMName SCVMM01 -PurgeDBOnly
Update properties of individual VMs
You can update properties of individual VMs in a persistent MCS machine catalog using the PowerShell command Set-ProvVM
. However, the updates are not applied immediately. You must set the time window using the PowerShell command Set-ProvVMUpdateTimeWindow
for the updates to apply.
This implementation helps you to manage individual VMs efficiently without updating the entire machine catalog. Currently, this feature is applicable only to the Azure environment.
Currently, the properties that you can update are:
CustomProperties
ServiceOffering
MachineProfile
Using this feature, you can:
- Update the properties of a VM
- Retain the properties updated on a VM after the machine catalog is updated
- Revert the configuration updates applied to a VM
Before updating properties of a VM:
- Open a PowerShell window.
- Run
asnp citrix*
to load the Citrix-specific PowerShell modules. -
Check the configuration of the existing machine catalog. For example:
Get-ProvScheme -ProvisioningSchemeName AzureCatalog <!--NeedCopy-->
-
Check the configuration of the VM on which you want to apply the updates. For example:
Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
Update properties of a VM
Do the following to update the properties on a VM:
- Turn off the VM on which you want to apply the updates.
-
Update the properties of the VM. For example, if you want to update storage type (
StorageType
) custom property of the VM, run the following:Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 -CustomProperties "...<Property Name='StorageType' Value='Premium_LRS' />..." <!--NeedCopy-->
You can update properties of two VMs in a machine catalog simultaneously. For example:
Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 -CustomProperties "...<Property Name='StorageType' Value='Premium_LRS' />..." <!--NeedCopy-->
Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine2 -CustomProperties "...<Property Name='StorageType' Value='StandardSSD_LRS' />..." <!--NeedCopy-->
Note:
The updates are not applied immediately.
-
Get the list of properties that are specified to be updated and the configuration version. For example:
Get-ProvVMConfiguration -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
Check the property value of
Version
and the properties to be updated (in this case,StorageType
). -
Check the configuration version. For example:
Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
Check the property value of
ProvVMConfigurationVersion
. The update is not yet applied. The VM is still in the old configuration. -
Request scheduled update. For example:
Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
For more information on scheduled updates, see Update provisioned machines to current provisioning scheme state.
Note:
Any pending provisioning scheme update is also applied.
-
Restart the VM. For example:
New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn <!--NeedCopy-->
-
Check the configuration version. For example:
Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
Check the property value of
ProvVMConfigurationVersion
. The update is now applied. The VM now has the new configuration. - To apply further configuration updates on the VM, turn off the VM, and repeat the steps.
Retain the properties updated on a VM after the machine catalog is updated
Do the following to retain the properties updated on a VM:
- Turn off the VM on which you want to apply the updates.
-
Update the machine catalog. For example, if you want to change the VM size (
ServiceOffering
) and storage type (StorageType
), run the following:Set-ProvScheme -ProvisioningSchemeName AzureCatalog -ServiceOffering Standard_E4_v3 -CustomProperties "...<Property Name='StorageType' Value='StandardSSD_LRS' />..." <!--NeedCopy-->
-
Get the configuration details of the machine catalog. For example:
Get-ProvScheme -ProvisioningSchemeName AzureCatalog <!--NeedCopy-->
The
ProvisioningSchemeVersion
is now incremented by one. The VM size and storage type are also updated. -
Update the properties of the VM. For example, provide a machine profile to the VM.
Set-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 -MachineProfile "XDHyp:\HostingUnits\<hosting-unit>\machineprofile.folder\<resource-group>.resourcegroup\<template-spec>.templatespec\<template-spec-version>.templatespecversion" <!--NeedCopy-->
Note:
The machine profile input has a tag and a different VM size (
ServiceOffering
) specified. -
Get the list of properties that the VM will have after merging the configuration updates on the VM with the machine catalog updates. For example:
Get-ProvVMConfigurationResultantSet -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
Note:
Any updates on the VM will override the updates done on the machine catalog.
-
Request scheduled update for the VM. For example:
Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -VMName machine1 -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
-
Restart the VM. For example:
New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn <!--NeedCopy-->
The VM keeps its updated VM size as derived from the machine profile. The tag values as specified in the machine profile are also applied to the VM. However, the storage type is derived from the latest provisioning scheme.
-
Get the configuration version of the VM. For example:
Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
The
ProvisioningSchemeVersion
andProvVMConfigurationVersion
now shows the latest version.
Revert the configuration updates applied to a VM
- After applying the updates to a VM, turn off the VM.
-
Run the following command to remove the updates that are applied on the VM. For example:
Set-ProvVM -RevertToProvSchemeConfiguration -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
-
Request scheduled update for the VM. For example:
Set-ProvVMUpdateTimeWindow -ProvisioningSchemeName AzureCatalog -VMName machine1 -StartsNow -DurationInMinutes -1 <!--NeedCopy-->
-
Restart the VM. For example:
New-BrokerHostingPowerAction -MachineName machine1 -Action TurnOn <!--NeedCopy-->
-
Check the configuration version of the VM. For example:
Get-ProvVM -ProvisioningSchemeName AzureCatalog -VMName machine1 <!--NeedCopy-->
The
ProvVMConfigurationVersion
value is now the configuration version of the machine catalog.
VDA Update Support via Local File Share Access (Tech Preview)
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
- 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)
- Remote PowerShell SDK version 7.42 or later (released after Feb 16, 2024)
How to Set File Share Permissions
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.
- Choose people on your network who you want to share the file with.
- 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.
- Select a shared folder.
- Disable the password protection.
- Go to Folder Properties.
- Select Network and Sharing Center.
- Turn off Password Protected Sharing.
- Click Advanced Sharing to grant a share permission.
- Select Permissions.
- Grant a Read share permission to ANONYMOUS LOGON.
- Select the Security Tab to grant folder permissions
- Click Edit to add permissions to the shared folder
- Select the shared folder to grant folder permissions to ANONYMOUS LOGON.
- Click Advanced to turn on File and Printer Sharing.
- Add the shared folder name to Network Access Security Policy.
Note:
Restart your machine for the change to take effect immediately.
VDA Updates from a Local File Share
-
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.
- Navigate to the Downloads page on our website.
- Select Citrix Virtual Apps and Desktops as the product.
- Select Citrix Virtual Apps and Desktops 7 2311, All Editions.
- 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.
- If a Cloud Connector is not operating properly, MCS provisioning operations (such as catalog updates) take longer than usual and the management console performance degrades significantly.
Where to go next
For information on managing specific hypervisor catalogs, see:
In this article
- Introduction
- About persistent instances
- Manage machine catalogs
- Use Studio
- View catalog details
- Add machines to a catalog
- Delete machines from a catalog
- Edit a catalog
- Rename a catalog
- Delete a catalog
- Manage Active Directory computer accounts in a catalog
- Change the master image for a catalog
- Change the functional level or undo the change
- Clone a catalog
- Organize catalogs using folders
- Configure auto-upgrade for VDAs
- Manage configuration set for a catalog
- Retry catalog creation
- (Non-Citrix provisioned VDAs only) Generate and manage enrollment tokens
- Use PowerShell
- Manage the sequence number of the machine name
- Add descriptions to an image
- Reset OS disk
- Repair the identity information of active computer accounts
- Change the network setting for an existing machine catalog
- Manage versions of a machine catalog
- Change cache configuration of an existing machine catalog
- Convert a non-machine profile-based machine catalog to a machine profile-based machine catalog
- Retrieve warnings and errors associated with a catalog
- Delete machines without hypervisor access
- Update properties of individual VMs
- VDA Update Support via Local File Share Access (Tech Preview)
- Troubleshoot
- Where to go next