Jump to content
Updated Privacy Statement

PoC Guide: Automated Configuration Tool - On-Premises to On-Premises Migration

  • Contributed By: Arnaud Pain Special Thanks To: Steve Beals, Jake Ledner, Steven Gallagher


The Automated Configuration Tool facilitates migrating and exporting configurations to Citrix DaaS. However, Citrix Virtual Apps and Desktops site configurations can also be migrated and exported from one on-premises environment to another using the ACT on-premises. This POC Guide guides you to migrate an on-premises Citrix Virtual Apps and Desktops site to another Citrix Virtual Apps and Desktops on-premises site using the Citrix Automated Configuration Tool. Consider moving a tested and validated DEV/UAT configurations to Production as a potential use case for the Automated Configuration Tool on-premises to on-premises migration.

Source Deployment:


Target Deployment:


Configuration with source and target:



Web Studio must be installed on the Target site, requiring, at minimum, Citrix Virtual Apps and Desktops Current Release 2212. Web Studio is necessary to use the orchestration APIs locally on the DDC.


On-Premises environment

  • Citrix Virtual Apps and Desktops On-Premises environment with at least one registered VDA.
  • Source: Citrix Virtual Apps and Desktops On-Premises environment running on one of the following versions:
    • Any Long Term Service Release (LTSR) versions with their latest CU (1912, 2203)
    • Or one of the corresponding latest two Current Releases (CR) versions (for example, 2112, 2206).
  • Destination: Citrix Virtual Apps and Desktops On-Premises environment running at minimum the latest Current Releases (CR) version 2212.
  • The domain-joined machine where you plan to run the Automated Configuration tool commands must run a .NET 4.7.2 version or higher.
  • A machine with the Citrix PowerShell SDK, which automatically installs on the DDC.


If running the tool on a different machine, it must be domain-joined, and Studio requires the correct PowerShell snap-ins installed. The installer can be found on your corresponding versions Product ISO installation media, obtained from the Citrix Virtual Apps and Desktops downloads website.

  • Download the Automated Configuration tool MSI from here.

This proof of concept guide demonstrates how to

  1. Deploy a new Delivery Controller.
  2. Configure the new Delivery Controller.
  3. Export configuration from source DDC.
  4. Prepare the import.
  5. Import configuration on target DDC.

Deploy a new Delivery Controller

For this POC Guide, the new server is named UAT-DDC-01.


The new Delivery Controller Server requires at least 5 GB of memory.

  1. Use a newly deployed Windows Server domain joined server.

  2. Download Citrix Virtual Apps and Desktops 2212 or later.

  3. Mount the ISO file.

  4. Run AutoSelect as an Administrator.


  5. Click Start.


  6. Click Delivery Controller.


  7. Accept the license and click Next.


  8. Clear License Server and click Next.


  9. Click Next.


  10. Clear Install Microsoft SQL Server 2019 Express CU15 to use your current Database server and click Next.


  11. Click Next.


  12. Click Install.


  13. Click Connect or clear the box and click Next.


  14. Click Finish.


Configure the new Delivery Controller

Initial configuration

  1. Click Deliver applications and desktops to your users.


  2. Provide a Site Name and Click Next.


  3. Provide Database information and Click Next.


  4. Provide the name of your Citrix License Server and Click Connect.


  5. Select Connect me and Click Confirm.


  6. Click Next.


  7. Click Finish.


Log on to Web Studio

Browse the Web Studio website at https://<servername>/Citrix/WebStudio.

  1. Connect to Web Studio from the Start Menu and select Citrix Web Studio.


  2. Provide credentials and Click Sign In.


  3. Upon the first launch, the console is empty

Export configuration from source DDC

  1. Connect to the Source Delivery Controller.
  2. Download the latest version of the Citrix Automated Configuration tool from here
  3. Install AutoConfig_Powershell_x64.msi.
  4. Open Auto Config from the icon on your desktop.
  5. Run Export-CvadAcToFile.


Prepare the import

  1. Connect to the Destination Delivery Controller.

  2. Download the latest version of the Citrix Automated Configuration tool from here

  3. Install AutoConfig_Powershell_x64.msi.

  4. Open Auto Config from the icon on your desktop (this creates the Citrix folder under C:\Users\%username%\Documents).

  5. Copy the folder C:\Users\%username%\Documents\Citrix on the Source Delivery Controller and paste it to C:\Users\%username%\Documents\Citrix on the Destination Server. Accept the merge option.


  6. Edit CvadAcSecurity.yml using notepad.


  7. Provide the correct Hypervisor password and save the file.


  8. Edit CustomerInfo.yml using notepad.


  9. Update the environment from Production to OnPrem and save the file.


Import configuration on target DDC

  1. Connect to the Destination Delivery Controller.

  2. Open Auto Config from the icon on your desktop.

  3. Run Import-CvadAcToSite.


  4. Enter Yes to confirm and continue with the import.


  5. The Hosting Connection is created first.


  6. Next, the Machine Catalogs are created.


  7. The Delivery Groups are created next.


  8. Next, the Applications.


  9. Lastly, the Policies are created.



Alternatively, run Merge-CvadAcToSite to ensure any existing configurations do not get overwritten. Optionally, migrate one component at a time by running Merge-CvadAcToSite -Tags, followed by Merge-CvadAcToSite -MachineCatalogs, etc. See here for more information on granular migration.


Resource creation

First, validate that the resources have been created on the Destination Delivery Controller.

  1. On Destination Delivery Controller, connect to Web Studio.


  2. Click Machine Catalogs to validate your Machine Catalogs.


    Here we can see that PVS and Static VDAs are present, and the MCS machine catalog is still running (the master image metadata has been copied)

  3. Click Delivery Groups to validate your Delivery Groups.


    Here we can see that the Delivery Groups have been created and PVS and Static VDAs added. However, the Delivery groups are in maintenance mode.

  4. Click Applications and ensure you see all your applications (and any applications folder you have set up).


  5. Click Policies and ensure you see all your Policies.


  6. Click Machine Catalog. Wait until the process of the master copy is complete.

VDA Creation

Any VDAs need to be created manually for the MCS machine catalog. We add one Windows 10 MCS and one Windows Server 2022 MCS VDA to validate.


VDA Registration

Now that we have our MCS VDAs created, we can use PVS and Static without the need to recreate them.

  1. Turn Off Maintenance Mode on the Delivery Group.

  2. Restart all your VDAs.

  3. Check the registration state.


  4. All the Windows 10 MCS VDAs are registered. They have registered because they were installed with the VDA selected to Let machine creation service do it for registration.

  5. All VDAs need to register with the new Delivery Controller to test everything. In our case, we created OU in Active Directory to place the new MCS, current PVS, and Static and create a GPO to change registration.



  6. Move the VDAs you want to test to the OU where the GPO is applied.

  7. Reboot the VDAs and check the registration status.

  8. The VDAs moved to the correct OU with GPO applied are now registered.


Troubleshooting Tips

General information for troubleshooting:

  • Refer to the Automated Configuration Tool Troubleshooting FAQ article.
  • Prior to opening support ticket with Citrix, collect all log and *.yml files into a single zip by running New-CvadAcZipInfoForSupport. No customer security information is included. Forward the zip file at the following location %HOMEPATH%\Documents\Citrix\AutoConfig\CvadAcSupport_yyyy_mm_dd_hh_mm_ss.zipNew-CvadAcZipInfoForSupport.
  • Running any cmdlet creates a log file and an entry in the master history log file. The entries contain the date, operation, result, backup, and log file locations of the execution. This log provides potential solutions and fixes to common errors.
  • The master history log is located in %HOMEPATH%\Documents\Citrix\AutoConfig, in the file named History.Log.* All operation log files are placed in a backup folder.
  • All log file names begin with CitrixLog, then show the auto-config operation and the date and timestamp of the cmdlet execution.
  • Logs do not auto-delete.
  • Console logging can be suppressed by using the -quiet parameter

For more information:

  1. You can also reach out via the Support Forum

  2. Read the Automated Configuration Tool documentation

  3. Download new versions from the direct Downloads website link

  4. Check out our On-demand August 19 webinar recording - "Why Citrix Cloud migration is easier than ever". We shared more information on the tool and hosted a Live Q&A session with a panel of Citrix experts.

  5. Refer to the Citrix DaaS Migrate to cloud section for more information and the Official Documentation.

  6. If after consulting the information listed previously you still need assistance, get in touch with your Citrix representatives, Customer Success Manager, or Support.

User Feedback

There are no comments to display.

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Create New...