Product documentation
Citrix DaaS
View PDF

Migrate configuration to Citrix Cloud

February 18, 2025
Contributed by: 
C

Automated Configuration Tool (ACT) allows migration of Citrix Virtual Apps and Desktops configuration (policies, applications, catalogs, admin roles, scopes, and others) from one or more on-premises sites to Citrix DaaS hosted on Citrix Cloud. It can also be used to migrate information between different Cloud regions or tenants.

This tool discovers and exports one or more on-premises sites as a collection of configuration files, which you can optionally edit. These files’ configuration can then be imported into Citrix DaaS. The migration is done in stages by running the tool multiple times, allowing you to easily achieve the desired configuration state.

ACT isn’t just a one and done migration tool. You can use it to manage your day-to-day cloud operations such as:

  • Automating the transfer from test or stage cloud accounts to production cloud accounts
  • Backing up and restoring your configuration
  • Splitting one cloud environment into multiple clouds

The following 2-minute video provides a quick tour of Automated Configuration.

For additional information on Automated Configuration, see Proof of Concept: Automated Configuration Tool on Tech Zone.

For a deeper look into moving your deployment and readying your on-premises configuration for migration, see Deployment Guide: Migrating Citrix Virtual Apps and Desktops from on-premises to Citrix Cloud on Tech Zone.

Known limitations

Prerequisites for migrating your configuration

For exporting your configuration from Citrix Virtual Apps and Desktops, you need:

  • Citrix Virtual Apps and Desktops: current release and its immediate predecessor or Citrix Virtual Apps and Desktops, XenApp and XenDesktop LTSRs: all versions
  • A domain-joined machine with .NET Framework 4.7.2 or later and the Citrix PowerShell SDK. This is automatically installed on the Delivery Controller. (To run on machine other than the on-premises Delivery Controller, Citrix Studio must be installed, as Studio installs the correct PowerShell snap-ins. The Studio installer can be found on the Citrix Virtual Apps and Desktops installation media.)

For importing your configuration into Citrix DaaS, you need:

  • A machine with access to Citrix Cloud. This does not have to be a Delivery Controller or a domain-joined machine.
  • Citrix DaaS provisioned.
  • An active resource location with Connector installed and domain-joined to the same domain as the on-premises setup.
  • Connectivity to sites accessing Citrix Cloud must be allowed and available. For more information, see System and Connectivity Requirements.

Note:

Automated Configuration cannot be installed on a Cloud Connector system.

Key steps

  1. Download the Automated Configuration Tool and review the system requirements. See Download Automated Configuration.
  2. Populate the CustomerInfo.yml file with your CustomerName, CustomerID, and SecretKey values generated from the Citrix Cloud portal. See Generate the customer ID, client ID, and secret key and Populate the customer info file.
  3. If the on-premises site contains multiple zones, update the ZoneMapping.yml file to map zones to Citrix DaaS resource locations. See Populate zone mapping file.
  4. If the site contains multiple hosting connections, update the CvadAcSecurity.yml file with the connection information for each host type migrating into Citrix DaaS. If only a single host connection, update the CvadACSecurity.yml file with the connection information for the host connection. See Update the security file for host connections.
  5. Open ACT and export your on-premises site using the Export-CvadAcToFile command. See Supported migration objects for the list of components supported for migration. For information on the steps to export, see Export on-premises configuration.
  6. Import components in stages using the Merge-CvadAcToSite command. Alternatively, migrate the entire site at once. Ensure you migrate components in the order listed in Component migration order. For information on the steps to import, see Run an import.
  7. Activate the cloud site. See Activate sites.

Download Automated Configuration

Download and install the Automated Configuration tool from Citrix Downloads.

Upgrade Automated Configuration

To prevent errors in functionality, always use the latest available version of ACT.

To know about your tool version, do the following:

  1. Double-click the Auto Config icon. A PowerShell window appears.

  2. Run the following command to check your version number.

    Get-CvadAcStatus
  3. Check your tool version against the version listed in Citrix Downloads. The latest version of the tool is located there.
  4. Download and install the latest version of the tool. You do not need to uninstall the old version to upgrade Automated Configuration.

Note:

When you run cmdlets to access the cloud in Automated Configuration, the tool alerts you when there is a newer version available for download. For more information on cmdlets, see Automated Configuration tool cmdlets.

Generate the customer ID, client ID, and secret key

To migrate the on-premises site to Citrix DaaS, populate the CustomerInfo.yml file with the customer ID, client ID, and secret key from Citrix Cloud portal.

To retrieve the Customer ID:

  1. Sign into your Citrix Cloud account and select the customer.
  2. Click the grid icon and select Identity and Access Management.
  3. Navigate to API access > Secure clients. The customer Id is displayed on the page.

To retrieve the Client ID and Secret Key:

  1. On the Secure clients page, enter a name in the box. This name is used to differentiate between multiple client IDs and secret keys.
  2. Click Create Client to create the client ID and the secret key.
  3. Copy the client ID and secret key to a secure location and download the .csv file containing this information. Use the .csv file to populate the CustomerInfo.yml file.

Note:

  • The client ID and secret key do not expire. If they are compromised, immediately remove them by using the Trash icon and create new ones.
  • The secret key cannot be retrieved if it is lost or forgotten; a new client ID and secret key must be created.

Populate customer info file

The CustomerInfo.yml file eliminates the need to provide customer information parameters every time while running the cmdlet. Any of the customer information can be overridden by using cmdlet parameters.

Use New-CvadAcCustomerInfoFile cmdlet to create the CustomerInfo.yml file.

Important:

Do not manually edit the CustomerInfo.yml file. Doing so can cause inadvertent formatting errors.

The New-CvadAcCustomerInfoFile cmdlet has the following required parameters.

  • CustomerId – customer’s ID.
  • ClientId – customer’s client ID created on Citrix Cloud.
  • Secret – customer’s secret created on Citrix Cloud.

Example:

New-CvadAcCustomerInfoFile -CustomerId markhof123 -ClientId 6813EEA6-46CC-4F8A-BC71-539F2DAC5984 -Secret TwBLaaaaaaaaaaaaaaaaaw==

You can also create the CustomerInfo.yml using the SecurityCsvFileSpec parameter that points to the downloaded security.csv file. You must also specify the CustomerId.

New-CvadAcCustomerInfoFile -SecurityCsvFileSpec C:\Users\my_user_name\downloads/security.csv -CustomerId markhof123

Use Set-CvadAcCustomerInfoFile cmdlet to update the CustomerInfo.yml file. This cmdlet only changes the Client ID.

Set-CvadAcCustomerInfoFile -ClientId C80487EE-7113-49F8-85DD-2CFE30CC398E

The following is a sample CustomerInfo.yml file.

            # Created/Updated on 2020/01/29 16:46:47
            CustomerId: ‘markhof123’
            ClientId: ‘6713FEA6-46CC-4F8A-BC71-539F2DDK5384’
            Secret: ‘TwBLaaabbbaaaaaaaaaaw==’
            Environment: Production
            AltRootUrl: ‘’
            StopOnError: False
            AlternateFolder: ‘’
            Locale: ‘en-us’
            Editor: ‘C:\Program Files\Notepad++\notepad++.exe’
            Confirm: True
            DisplayLog: True

Populate zone mapping file

An on-premises zone is the equivalent of the cloud resource location. Unlike other site components, you cannot import the on-premises zone to the cloud automatically. Instead, it must be manually mapped using the ZoneMapping.yml file. Import failures can occur if the zone name is not associated with an existing resource location name.

If the on-premises sites have only one zone and cloud sites have only one resource location, the Automated Configuration tool makes the correct association, eliminating the need to manually manage the ZoneMapping.yml file.

However, if the on-premises sites have multiple zones or cloud sites have multiple resource locations, then manually update the ZoneMapping.yml file to reflect the correct mapping of on-premises zones to cloud resource locations.

The ZoneMapping.yml file is located in %HOMEPATH%\Documents\Citrix\AutoConfig. The content of the .yml file is a dictionary with the zone name as the key and the resource location name as the value.

For example, an on-premises Citrix Virtual Apps and Desktops site with a primary zone called “Zone-1” and a secondary zone called “Zone-2” is migrated to a Citrix DaaS deployment with two newly created cloud resource locations called “Cloud-RL-1” and “Cloud-RL-2”. In this instance, the ZoneMapping.yml would be configured as follows:

            Zone-1: Cloud-RL-1

            Zone-2: Cloud-RL-2

Note:

Add a space between the colon and resource location name. If spaces are used in the zone or resource location name, enclose the name with quotes.

Update the security file for host connections

Host connections and their associated hypervisors can be exported and imported using ACT.

Adding a hypervisor to a host connection requires security information specific to the type of hypervisor. This information cannot be exported from the on-premises site for security considerations. You must manually provide the information so that Automated Configuration can successfully import host connections and hypervisors to the cloud site.

The export process creates the CvadAcSecurity.yml file in %HOMEPATH%\Documents\Citrix\AutoConfig containing placeholders for each security item needed for the specific hypervisor type. You must update the CvadAcSecurity.yml file before importing into the cloud site. Administrator updates are retained over multiple exports with new security placeholders added as needed. Security items are never removed. For more information, see Manually update the CvadAcSecurity.yml file

            HostConn1:
            ConnectionType: XenServer
            UserName: root
            PasswordKey: rootPassword
            HostCon2:
            ConnectionType: AWS
            ApiKey: 78AB6083-EF60-4D26-B2L5-BZ35X00DA5CH
            SecretKey: TwBLaaaaaaaaaaaaaaaaaw==
            Region: East

Per-hypervisor security information

The following lists the security information required for each hypervisor type.

  • XenServer, Hyper-V, VMware
    • User Name
    • Clear-text Password
  • Microsoft Azure
    • Subscription ID
    • Application ID
    • Application Secret
  • AWS
    • Service Account ID
    • Application Secret
    • Region

Special security considerations

All security information is entered as clear text. If clear text is not recommended, the host connections and associated hypervisors can be manually created using Studio. The host connections and hypervisor names must match their on-premises counterparts exactly so that machine catalogs that use the host connections can be successfully imported.

Export your Citrix Virtual Apps and Desktops on-premises configuration

Using an export PowerShell command, you can export your existing on-premises configuration and obtain the necessary .yml files. These files are used to import your desired configuration into Citrix Cloud.

Supported migration objects

Automated Configuration supports moving the configuration of the following components:

  • Tags
  • Delegated Admin
    • Scopes
    • Roles
  • Host Connections
    • A Single Resource Pool
    • Admin Scopes
  • Machine Catalogs
    • Admin Scopes
    • Machines
    • Remote PC Access, Physical, Pooled, Provisioned, MCS, Assigned
  • StoreFront
  • Delivery Groups
    • Access Policy
    • Admin Scope Association
    • Application Access Policy
    • Assignment Policy
    • Entitlement/Desktop Policy
    • Power Schedules
    • Session Lingering
    • Session Prelaunch
    • Reboot Schedules
    • Tags
  • Application Groups
    • Admin Scope Association
    • Delivery Groups
    • Users and Groups
  • Applications
    • Application Folders
    • Icons
    • Applications
    • Broker Configured FTAs
    • Tags
  • Group Policies
  • User Zone Preferences

Export on-premises configuration

  1. Double-click the Auto Config icon. A PowerShell window appears.

  2. Run the following command to export all components. Exporting your on-premises configuration does not change it in any way.

    Export-CvadAcToFile

After you run any cmdlet for the first time, an export folder with the .yml configuration files and logs is created. The folder is at %HOMEPATH%\Documents\Citrix\AutoConfig. Each successive export creates a subfolder. The parent folder %HOMEPATH%\Documents\Citrix\AutoConfig always contains the exported files from the most recent export.

Note:

If Automated Configuration is not installed on the Delivery Controller, run import-module Citrix.AutoConfig.Commands before using the tool through PowerShell. This step is not needed if you open Automated Configuration using the Auto Config icon.

If you encounter any errors or exceptions, see the Fixups section in the log file.

Import your configuration to Citrix DaaS

Important:

  • When migrating an on-premises deployment to cloud, make sure that the domain and OU GPOs that contain the Citrix settings are migrated to cloud. Citrix Web Studio does not support GPMC and hence, the domain and OU GPOs are not visible in the Web Studio. The Citrix policy engine enforces the domain and OU GPOs on VDAs and users that are in the domains and OUs. Post log in to a VDA, a user might see that the policies from the domain and OU GPOs are applied to their session. However, administrators cannot see these policies and settings which might lead to confusions.

Component migration order

The components and their dependencies are listed here. A component’s dependencies must be in place before it can be imported or merged. If a dependency is missing, it can cause the import or merge command to fail. The Fixups section of the log file shows missing dependencies if an import or merge fails.

  1. Tags
    • No pre-dependencies
  2. Delegated Admin
    • No pre-dependencies
  3. Host Connections
    • Security Information in CvadAcSecurity.yml
  4. Machine Catalogs
    • Machines present in Active Directory
    • Host Connections
    • Tags
  5. StoreFront
  6. Delivery Groups
    • Machines present in Active Directory
    • Users present in Active Directory
    • Machine Catalogs
    • Tags
  7. Application Groups
    • Delivery Groups
    • Tags
  8. Applications
    • Delivery Groups
    • Application Groups
    • Tags
  9. Group Policies
    • Delivery Groups
    • Tags
  10. User Zone Preferences

Run an import

  1. Double-click the Auto Config icon. A PowerShell window appears.

  2. Run the following command to import all components.

    Merge-CvadAcToSite

Verify the expected state with the new current state. Various import options control whether the import results are identical or a subset of the on-premises site.

After you run the cmdlet, an export folder with the .yml configuration files and logs is created. The folder is at %HOMEPATH%\Documents\Citrix\AutoConfig.

If you encounter any errors or exceptions, see the Fixups section in the log file.

Note:

If Automated Configuration is not installed on the Delivery Controller, run import-module Citrix.AutoConfig.Commands before using the tool through PowerShell. This step is not needed if you open Automated Configuration using the Auto Config icon.

To revert to your original Citrix DaaS configuration, see Backing up your Citrix DaaS configuration.

Understand import operation

The import process is designed to accurately perform updates, only perform needed updates and verify that all updates have been correctly made. The steps are followed in all import operations:

  1. Read the exported .yml file (expected state).
  2. Read the cloud (current state).
  3. Back up the pre-import cloud state to .yml files (pre-backup can be restored if necessary).
  4. Evaluate the differences between the expected and current state. This determines which updates to make.
  5. Make the updates.
  6. Reread the cloud (new current state).
  7. Back up the post-import cloud state to .yml files (post-backup can be restored if necessary).
  8. Compare the new current state with the expected state.
  9. Report the results of the comparison.

Granular migration

Important:

For more information on component migration order, see Component migration order.

You can selectively migrate components only or even component names only.

  • Component parameters supported include MachineCatalogs, Tags, and more.
  • Component name parameters supported include IncludeByName and ExcludeByName parameters, and others.

For more information on parameters and how to use them, see Granular migration parameters.

Activate sites

The delivery controller in both on-premises and cloud sites controls resources such as brokering desktops, applications, and rebooting machines. Problems occur when a common set of resources is controlled by two or more sites. Such a situation can occur when migrating from an on-premises site to a cloud site. It is possible for both the on-premises and cloud delivery controllers to manage the same set of resources. Such dual management can lead to resources becoming unavailable and unmanageable, and can be difficult to diagnose.

Site activation allows you to control where the active site is controlled.

Site activation is managed using the delivery group maintenance mode. Delivery groups are placed in maintenance mode when the site is inactive. Maintenance mode is removed from delivery groups for sites that are active.

Site activation does not affect or manage VDA registration or machine catalogs.

  • Set-CvadAcSiteActiveStateCloud
  • Set-CvadAcSiteActiveStateOnPrem

All cmdlets support the IncludeByName and ExcludeByName filtering. This parameter allows you to select which delivery groups can have their maintenance mode changed. Delivery groups can be selectively changed as needed.

Import and transferring control to the cloud

The following is a high-level description on how to import and transfer control from the on-prem site to the cloud site.

  1. Export and import the on-premises site to the cloud. Make sure the –SiteActive parameter is not present on any of the import cmdlets. The on-premises site is active and the cloud site inactive. By default, cloud site delivery groups are in maintenance mode.
  2. Verify the cloud content and configuration.
  3. During off hours, set the on-premises site to inactive. The –SiteActive parameter must be absent. All on-premises site delivery groups are in maintenance mode.
    • Set-CvadAcSiteActiveStateOnPrem
  4. Set the cloud site to active. The –SiteActive parameter must be present. No cloud site delivery groups are in maintenance mode.
    • Set-CvadAcSiteActiveStateCloud –SiteActive
  5. Verify that the cloud site is active and the on-premises site is inactive.

Transfer control back to the on-premises site

To transfer control from the cloud site to the on-premises site:

  1. During off hours, set the cloud site to inactive. All cloud site delivery groups are in maintenance mode.
    • Set-CvadAcSiteActiveStateCloud
  2. Set the on-premises site to active. No on-prem site delivery groups are in maintenance mode.
    • Set-CvadAcSiteActiveStateOnPrem -SiteActive

Additional site activation information

  • If no machines are power managed and there are no reboot schedules (which usually means there are no host connections either) all cloud delivery groups can be imported as active. Add -SiteActive to Merge-CvadAcToSite/Import-CvadAcToSite or run Set-CvadAcSiteActiveStateCloud -SiteActive after importing.
  • If machines are power managed or there are reboot schedules, a different process is needed. For example, when switching from on-premises to cloud in this situation, set the on-premises site to inactive using Set-CvadAcSiteActiveStateOnPrem. Then, set the cloud site to active using Set-CvadAcSiteActiveStateCloud -SiteActive.
  • The Set-CvadAcSiteActiveStateCloud and Set-CvadAcSiteActiveStateOnPrem cmdlets are also used to reverse the process. For example, run Set-CvadAcSiteActiveStateCloud without the -SiteActive parameter, then run Set-CvadAcSiteActiveStateOnPrem with the -SiteActive parameter.

Understand migrating Machine Creation Services provisioned catalogs

Note:

This feature is available only on versions 3.0 and later. Check your version by using Get-CvadAcStatus within Automated Configuration.

Machine Creation Services (MCS) catalogs create two different types of catalogs:

  • When changes made to a machine are lost or reversed (Commonly Server OS, where applications are published) – this is a pooled VDI / multi-session use case
  • When changes made to a machine are preserved across reboot (Commonly client OS with a dedicated user) – this is a static VDI use case

The type of catalog can be confirmed in the catalog node in Citrix Studio and looking at the “User data:” value of the catalog.

Note:

MCS cannot be backed up from the cloud using Automated Configuration.

Pooled VDI / multi-session catalogs

Catalogs with “User data: Discard” are pooled VDI catalogs and can only migrate the main image and configuration. Any virtual machines in these catalogs are not migrated. This is because the life cycle of the virtual machine is maintained by the site you are importing from, which means every time the machines are turned on, its state might change. This makes import impossible as the import data for the virtual machines quickly gets of out of sync.

When you are migrating these catalogs using the tool, it creates catalog metadata and initiates main image creation, but no machines are imported.

Since this process can take some time to be created based on the size of the main image, the import command within the tool only starts the MCS catalog creation and does not wait for it to finish. After the import has completed, monitor the catalog creation progress using Studio in the cloud deployment.

Once the main image is created, you can provision machines. Consider the capacity considerations because you would have capacity consumed from your on-premises usage.

All other objects (delivery groups, applications, policies, and so forth) that use that catalog can be imported and do not have to wait for the main image creation. When the catalog has finished creating, machines can be added to the imported catalog and then users can launch their resources.

Note:

Use the same commands available within the tool to migrate catalogs and all other objects.

Static VDI catalogs

Note:

Since this operation imports low-level details that are stored in the database, this process must be run from a machine with database access.

The static VDI catalogs migrate the main image, configurations, and all virtual machines. Unlike the pooled VDI use case, no images need to be created.

The VDAs must be pointed to the connector for them to register with the cloud.

Refer to the Activating sites section to make the cloud site active, so that the reboot schedule, power management, and other items are controlled by the cloud.

Once the migration is completed, if you want to delete this catalog from your on-premises site, you must select leave VM and AD account. Otherwise, they are deleted and the cloud site would be left pointing to the deleted VM.

Update MCS tags to detect orphaned resources after migration

After you migrate from on-premises configuration to a cloud site, or from your cloud configuration to another cloud site, you must update the MCS site id tags in case of persistent VMs so that orphaned resources can be detected correctly. To do this, use the PowerShell command Set-ProvResourceTags. Currently, this feature is applicable to Azure.

The detailed steps are as follows:

  1. Update the MCS site id tags from the new Citrix site using the PowerShell command Set-ProvResourceTags. For example:

    Set-ProvResourceTags -ProvisioningSchemeUid xxxxx  [-VMName <String>] [-VMBatchSize XX] [-ResourceType XX]

    Or,

    Set-ProvResourceTags -ProvisioningSchemeName xxxxx  [-VMName <String>] [-VMBatchSize XX] [-ResourceType XX]

The parameter details are as follows:

  • ProvisioningSchemeUid or ProvisioningSchemeName is a mandatory parameter.
  • VMName is an optional parameter. If no VMName is specified, tags of all the VMs of this machine catalog are updated.
  • VMBatchSize is an optional parameter to divide all VMs into batches. If no VMBatchSize is specified, the default value (10) is applied. The range is from 1 through 60.

  • ResourceType can be one of the following:

    • MachineCatalog: For updating tags of machine catalog resources.
    • VirtualMachine: For updating tags of VM related resources.
    • All: (default ResourceType): For updating tags of both machine catalog and VM related resources.
Migrate configuration to Citrix Cloud
February 18, 2025
Contributed by: 
C

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999-2025 Cloud Software Group, Inc. All rights reserved.