Tech Brief: Citrix Automated Configuration Tool

Overview

Migrating on-premises Citrix Virtual Apps and Desktops environments to Citrix DaaS or migrating information between different cloud regions or tenants has been tedious and daunting for many Citrix Administrators over the years. Many migrations tend to be case-specific, so Citrix administrators must write their automation scripts or tools to accomplish their migration. Citrix developed the Citrix Automated Configuration Tool, which was designed to ease this process by providing a tool that allows administrators to perform migrations either all at once or in stages and runs the tool multiple times so that the desired configuration state of your Citrix DaaS environment is achieved. The Citrix Automated Configuration Tool can also migrate information between public cloud regions or tenants.

What is the Automated Configuration tool for Citrix Virtual Apps and Desktops?

This tool is designed to help automate the migration of CVAD configuration (policies, applications, catalogs, admin roles, scopes and others) from one or more On-Premises site(s) to Citrix DaaS hosted on Citrix Cloud. It can also be used to migrate information between different Cloud regions or tenants.

The migration can be performed in stages by running the tool multiple times, allowing administrators to easily achieve the desired configuration state. There is a 2-minute video that provides a quick tour of the Automated Configuration tool:

Why use this tool?

IT Administrators in charge of large or complex environments often find migrations to be a tedious process. They frequently end up writing their own tools to accomplish this task successfully since it tends to be specific to their use cases.

Citrix wants to help ease this process by providing a tool that addresses use cases through automation. Administrators can easily test current configurations in Citrix Cloud and take advantage of the benefits offered by Citrix DaaS while keeping their current environments intact. Such benefits include reduced administrative overload when Citrix manages part of the back-end and control plane, automatic and customizable Citrix Cloud component updates, and others.

How is this tool implemented?

Citrix uses industry standard configuration as code to provide a mechanism to help automate migration processes. This tool discovers and exports one or more on-premises sites as a collection of configuration files, which administrators can optionally edit. These files' configuration can then be imported into Citrix DaaS.

This code is not limited to migrations, it is the future for creating configuration for Citrix sites, and as such, applicable for many different use cases. Disaster recovery, Development/Testing/Staging to Production site synchronization, Geographic (GEO) moves, and several other scenarios are supported. For administrators using public cloud providers, this can help create a combination of objects automatically (parallel to Microsoft Azure ARM templates and AWS CloudFormation).

The tool also allows administrators to merge multiple on-premises sites into a single site, while avoiding name collisions. Administrators can control whether the On-Premises or Cloud controls resources. Files can now be placed in a secure network file share that requires authentication when using the SecurityFileFolder parameter which points to the CvadAcSecurity.yml file.

Technical Details

The Citrix Automated Configuration tool aims to automate the migration process. Supported Citrix Studio nodes for migration include application settings, application groups, icons, machine catalogs, delivery groups, Citrix policies, tags, and host connections. The Citrix Automated Configuration Tool uses the Citrix PowerShell SDX for exporting and REST APIs for importing the information into the cloud.

Automated Configuration Tool Commands

The Citrix Automated Configuration Tool uses PowerShell cmdlets and the existing Citrix PowerShell SDK. The following table provides details of the primary commands and their functions. The Automated Configuration Tool product documentation contains full details of the cmdlets for your reference.

|Role| Command | Description | | Migration | Export-CvadAcToFile | Exports configuration from your on-premises setup. This command is the default export operation for Automated Configuration. No modifications are made to the on-premises site configuration. Exported files are placed in the directory "%HOMEPATH%\Documents\Citrix\AutoConfig" in a named Export subfolder.| | Migration | Import-CvadAcToSite | Imports all the on-premises files to the cloud. This command ensures that the cloud end state is identical to the on-premises state. This option deletes any changes that exist in the cloud. Imported site configuration files are sourced from "%HOMEPATH%\Documents\Citrix\AutoConfig".| | Migration | Merge-CvadAcToSite | Merges the on-premises files to the cloud but does not delete any components in the cloud. This preserves changes already made in the cloud. If a component exists in Citrix Cloud with the same name, this command can modify that component. This is the default import operation for Automated Configuration. Merged site configuration files are sourced from "%HOMEPATH%\Documents\Citrix\AutoConfig". | | Migration | New-CvadAcToSite | Imports on-premises site configuration to the cloud but only adds new components. Existing cloud site components are neither updated nor deleted. Use this command if your existing cloud site components must remain unchanged. | | Backup and Restore | Restore-CvadAcToSite | Restores the cloud site to the previous configuration. Imported files are sourced from the folder specified in the -RestoreFolder parameter. This can be used for reverting to your previous configuration or for disaster recovery of your cloud site. | | Backup and Restore | Backup-CvadAcToSite | Backs up all the configuration from your cloud site. | | Other | Compare-CvadAcToSite | Compares the on-premises .yml files with the cloud configuration, producing a report of changes made by an Import, Merge, or Restore. | | Other | Remove-CvadAcFromSite | Can reset the entire site or remove member items from a component (for example, removing one machine catalog from the list of catalogs). This can be used when coupled with the IncludeByName parameter to remove specific members selectively. |

Command Parameters

All cmdlets ending in ToSite, ToFile, and FromSite allows the selection of one or more components to act upon. These parameters give further granularity only to migrate selective components. The following parameters are available for use:

-All -Tags -MachineCatalogs -DeliveryGroups -ApplicationGroups -Applications -GroupPolicies -IncludeByName and ExcludeByName

Filtering

Include and Exclude

The IncludeByName and ExcludeByName parameters enable including and excluding component members in cmdlets by name. Only one component (delivery groups) can be chosen in any supported cmdlets. Cmdlets supported, including and excluding are:

• Export-CvadAcToFile
• Import-CvadAcToSite
• Merge-CvadAcToSite
• New-CvadAcToSite
• Restore-CvadAcToSite
• Sync-CvadAcSiteToSite
• Compare-CvadAcToSite
• Remove-CvadAcFromSite

IncludeByName and ExcludeByName take a list of component member names. Any name can contain one or more wildcards. Two types of wildcards are supported.

• Matches any number of characters
• Matches a single character

IncludeByName and ExcludeByName can also take a file containing a list of members where each member can be explicit or contain wildcards. Each line in the file can have one member. Leading and trailing spaces are trimmed from the member name. The file name must be preceded by the @ sign and be surrounded by single quotes (a PowerShell requirement so the @ is not reinterpreted). Multiple files can be listed in addition to being mixed with member names.

By Delivery Group Name

ByDeliveryGroupName filters by the Delivery Group name for Applications and Application Groups. This parameter is always an inclusion list identifying members to include based on their Delivery Group association. Cmdlets supported by ByDeliveryGroupName:

• Export-CvadAcToFile
• Import-CvadAcToSite
• Merge-CvadAcToSite
• New-CvadAcToSite
• Restore-CvadAcToSite
• Sync-CvadAcSiteToSite
• Compare-CvadAcToSite

ByDeliveryGroupName takes a list of Delivery Group names. Any name can contain one or more wildcards. Two types of wildcards are supported.

• Matches any number of characters
• Matches a single character

The following example merges all applications that reference all Delivery Group names beginning with EastDg:

Merge-CvadAcToSite –Applications $true –ByDeliveryGroupName EastDg*

Migration modes parameters

Cmdlets modifying the cloud site configuration (Import, Restore, Merge, New, and Sync) supports the following extra parameters to provide further flexibility.

Cloud-accessing parameters

All cmdlets accessing the cloud, which ends with ToSite or FromSite'andGet-CvadAcStatus`, support the following extra parameters.

Note

These parameters are unnecessary if they are added to the CustomerInfo.yml file. If these parameters are absent and CustomerInfo.yml file is not updated, authentication is still possible interactively by providing Citrix Cloud crednetials through the PowerShell SDK.

Folders and Logging

Automated Configuration initializes, updates, and backs up a cloud site configuration. Many configurations can change on the cloud site when used over time. To facilitate long-term use and preserve history changes, Automated Configuration uses a preservation scheme to save this history of changes and provide a method to restore earlier states.

Folders

All Automated Configuration operations occur in the root folder or subfolders inside it. The root folder is located in "%HOMEPATH%\Documents\Citrix\AutoConfig".

Export All exported files are placed in two folder locations, providing ease of use and a history of exports. Exports are always placed in the root folder. Copies are placed in a subfolder named 'Export' with the date and time of the export. The root folder always contains the most current exported on-premises site configuration. Each 'Export' subfolder includes the export done on the indicated date and time, which maintains a history of exports. You can use any 'Export' subfolder to configure the cloud site. Automated Configuration does not delete or modify existing 'Export' subfolders.

Import/Merge/Sync/Compare Import, Merge, and Compare operations are always sourced from files in the root folder. Each operation creates a subfolder to which files in the root folder are copied, providing a history of cloud site changing source files. Any subfolder can be used to configure the cloud site. Automated Configuration does not delete or modify existing export subfolders.

Restore The Restore operation uses an existing subfolder to configure the cloud site. The source folder is specified on the required -RestoreFolder parameter. Unlike other commands, no new subfolder is created because the Restore operation uses an existing subfolder. The restore folder can be the root folder but still must be specified on the -RestoreFolder parameter.

Backup Cloud site configuration backups are always made to a subfolder named 'Backup' with the data and time of the backup. Automated Configuration does not delete or modify existing export subfolders. You can use the backups to restore specific components or your entire configuration. To restore the entire Delivery Group and Machine Catalog components, use the cmdlet: Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss -GroupPolicies -IncludeByName Policy1,Policy2 -DeliveryGroups -MachineCatalogs

Note

The backup file information in the preceding cmdlet is based on your backups.

To restore the entire cloud site configuration, use the cmdlet: Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

Note

The backup file information in the preceding cmdlet is based on your backups.

Logging

Running any Automated Configuration Tool cmdlet results in a created log file and an entry in the master history log file. 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. The master history log is located in "%HOMEPATH%\Documents\Citrix\AutoConfig", in the file named 'History.Log'. Each cmdlet execution results in a master log entry containing the execution's date, operation, result, backup, and log file locations.

Logging Details Each log file includes the following: -The name of the operation and whether the check mode is enabled -The start and end date and time -Multiple entries for each component's actions and success/failure notifications -Summary of actions taken, including various counts of created objects -Suggested fixes where applicable-Backup folder location is located -Master log location -Duration

Diagnostic Files Diagnostic files assist you in determining and resolving problems. The following files are created when their operation is run. They are located in the action-specific subfolder under '%HOMEPATH%\Documents\Citrix\AutoConfig'. Include these files when providing information for problem-resolution support.

Export PoshSdk_yyyy_mm_dd_hh_mm_ss.ps1 This file enumerates all Broker PowerShell SDK calls to export the site configuration to files.

Import, Merge, Restore, Sync, Backup, Compare Transaction_yyyy_mm_dd_hh_mm_ss.txt This file documents each REST API call and related information. RestApiContent_yyyy_mm_dd_hh_mm_ss.txt This file contains all the Add, Update, and Delete REST API content.

Migration Scenarios

On-premises Citrix Virtual Apps and Desktops to Citrix DaaS migrations can range from simple to complex, depending on whether the on-premises site has multiple host connections or multiple zones.

Simple Migration

In the simple migration scenario, the on-premises site contains a single zone and one or more host connections to migrate to Citrix DaaS, as shown in the following diagram:

Complex Migration

In the complex migration scenario, the on-premises site contains multiple zones and multiple host connections, as shown in the following diagram:

Depending on your migration scenario, your workflow interaction with the Automated Configuration Tool may differ, as detailed in the next section.

Automated Configuration Workflow

When using the Automated Configuration Tool, a typical workflow is followed. During this workflow, there are multiple decision points that administrators may encounter. The following diagram depicts the workflow:

Note:

Check mode works best when migrating granularly component-by-component.

1. Download the Automated Configuration Tool and review the system requirements and prerequisites to use the tool successfully.

2. Open the Automated Configuration tool and export your on-premises site by running the Export-CvadAcToFile command.

   The following are supported for migration:

   • Tags
   • Hosting Connections
   • Machine Catalogs
   • Delivery Groups
   • Application Groups
   • Applications
   • Group Policies
   • Admin Scopes and Roles

   The following are unsupported for migration:

   • AppDisks
   • AppDNA
   • App-V Publishing
   • Delegated Admin Function

3. To migrate the on-premises site to Citrix DaaS, the CustomerInfo.yml file must be manually updated. Open the 'CustomerInfo.yml' file with Notepad and add the corresponding CustomerName, CustomerID, and SecretKey values. These values are obtained and generated from the Citrix Cloud portal.

4. Once the CustomerInfo.yml file is updated, the first decision point has been reached. If the site contains multiple zones, the ZoneMapping.yml file must be updated to map all zones to Citrix DaaS Resource Locations. Note: A zone in your on-premises Citrix environment is an equivalent concept to a resource location in Citrix DaaS. If the on-premises site contains only a single zone, move on to the next step.

5. If the on-premises site contains multiple hosting connections, update the CvadAcSecurity.yml with the connection information for each host type migrating into Citrix DaaS. If the on-premises site contains only a single host connection, update the CvadACSecurity.yml file with the connection information for the host connection.

6. Citrix recommends migrating your environment in stages. Run Merge-CvadAcToSite -<ComponentName> (that is, DeliveryGroup, MachineCatalogs, and so forth) to migrate components one-by-one. Ensure you migrate components in the order listed here:. Use check mode by appending the -CheckMode parameter to verify if the component migrates successfully. If all looks good, remove the -CheckMode parameter and rerun the Merge-CvadAcToSite -<ComponentName>. Once you have completed all the components, your DaaS site is ready! Alternatively, migrate the entire site all at once by running Merge-CvadAcToSite with no components names appended as parameters.

Note:

Check mode will not check for interdependencies between components unless components are migrated one-by-one.

1. At this point your on-premises Citrix site is still active. Citrix DaaS Delivery Groups are in maintenance mode. All sessions are still brokered by your on-premises Virtual Apps & Desktops environment. Start using DaaS to broker sessions by running the following commands:

• Set-CvadAcSiteActiveStateCloudOnPrem (This command toggles your on-premises delivery groups and puts them into maintenance mode)

• Set-CvadAcSiteActiveStateCloud -SiteActive (This command activates your Cloud delivery groups and takes them out of maintenance mode, thus activating the site.)

  Note:

  These commands support filtering, IncludeByName, and Check Mode

1. Refer to the troubleshooting guide for the reported errors. The troubleshooting guide provides suggestions for your error type. Implement the suggested actions to rerun the Automated Configuration Tool check mode.
2. If the troubleshooting guide cannot resolve the issue, follow the troubleshooting instructions to package the files into zip format and open a support ticket for assistance.

Reference

Citrix Automated Configuration Tool Product Documentation

Citrix Automated Configuration Tool Troubleshooting Guide and FAQ

Citrix Automated Configuration Tool POC Guide