Migration and management
If you have a Citrix Virtual Apps and Desktops Service configuration and you want to move it to another Citrix Virtual Apps and Desktops Service deployment region, you want to back up and restore your configuration, or you have reached your resource limits, you can now migrate all or part of your configuration using the Automated Configuration tool.
Automated Configuration for Citrix Virtual Apps and Desktops
Automated Configuration for Citrix Virtual Apps and Desktops is a tool that allows you to automate moving your on-premises configuration to your Citrix Virtual Apps and Desktops Service deployment.
Automated Configuration also supports moving your configuration between Citrix Virtual Apps and Desktops Service deployments. You can also use Automated Configuration to manage your deployments.
Automated Configuration exports your configuration information into a collection of .yml files that can then be optionally edited (for staging your migration) and imported into your Citrix Virtual Apps and Desktops Service deployment.
Download Automated Configuration
Download the Automated Configuration tool from Citrix Downloads. For more information, see Proof of Concept: Automated Configuration Tool.
Prerequisites for migrating your configuration
For exporting your configuration from Citrix Virtual Apps and Desktops:
- Citrix Virtual Apps and Desktops: current release and its immediate predecessor or Citrix Virtual Apps and Desktops, XenApp and XenDesktop LTSRs: all versions
- An on-premises delivery controller and at least a single on-premises VDA
- A machine with .NET Framework 4.7.2 or later
- A machine with the Citrix PowerShell SDK. This is automatically installed on the delivery controller. (To run on machine other than the on-premises delivery controller, the machine must be domain joined and 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 Virtual Apps and Desktops Service:
- A machine with access to Citrix Cloud.
- Citrix Virtual Apps and Desktops Service provisioned with an active resource location with Connector installed and domain-joined to the same domain as on-premises setup.
- Sites accessing Citrix Cloud must be allowed. For more information, see System and Connectivity Requirements.
Supported objects for migration
Automated Configuration supports the following components and are moved as part of the automated process.
- Tags
- Host Connections
- A Single Resource Pool
- Admin Scopes
- Machine Catalogs
- Admin Scopes
- Machines
- Remote PC Access, Physical, Pooled, Provisioned (except MCS), Assigned
- Delivery Groups
- Access Policy
- Admin Scopes
- Application Access Policy
- Assignment Policy
- Entitlement/Desktop Policy
- Power Schedules
- Session Lingering
- Session Prelaunch
- Reboot Schedules
- Tags
- Application Groups
- Admin Scopes
- Applications
- Application Folders
- Icons
- Applications
- Broker Configured FTAs
- Tags
- Group Policies
Known limitations
- Machine catalogs provisioned through Machine Creation Services are not currently supported. You can still import other objects from your site. For more information on MCS, see Importing other objects when you have Machine Creation Services machine catalogs.
- Icons are not applied to machines or desktops.
- Access Control must be added manually using the Remote POSH SDK.
- Delegated administration. Associating administrator scopes is supported.
Migrating from on-premises to cloud
Automated Configuration allows you to automate moving your on-premises configuration to a cloud site.
Exporting your Citrix Virtual Apps and Desktops on-premises configuration
- Install Automated Configuration on your delivery controller.
- Open PowerShell as an administrator.
-
Run the following command to do a baseline export.
Export-CvadAcToFile –All $true
Note:
Other available commands are described here.
After you run any cmdlet for the first the time, 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. For more information about logs and the information provided in them, see Logging.
Importing your configuration to Citrix Virtual Apps and Desktops Service
Important:
- You must have your CustomerInfo.yml file with your customer ID, client ID, and the secret key information included. For more information on how to retrieve your customer ID, client ID and secret key, see Generating the customer ID, client ID, and secret key. For information on how to add this information to the CustomerInfo.yml file, see Populating customer info file.
- The ZoneMapping.yml file must include information that maps your on-premises zone to resource locations in the cloud. For more information on how to map your zones, see Populating zone mapping file.
- If you have a Citrix Provisioning catalog or host connections, you must input the corresponding info in the HostSecurity.yml and CvadAcSecurity.yml.
Running a baseline import
- Run PowerShell as an administrator.
-
Run the following command to do a baseline import.
Merge-CvadAcToSite -All $true
Note:
Other available commands are described here.
Verify the expected state with the new current state. When doing a Merge
import, the expected state must be a subset of the new current state for the import to succeed.
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. For more information about logs and the information provided in them, see Logging.
To revert to your original Citrix Virtual Apps and Desktops Service configuration, see Backing up your Citrix Virtual Apps and Desktops Service configuration.
Import order and component dependency
The following components are selectable in the Export
, Import
, Merge
, New
, Sync
, and Restore
commands. They are listed in their import order. Importing out of order might result in dependency failures and cause the import operation to fail.
- Tags
- Host Connections
- Machine Catalogs
- Delivery Groups
- Application Groups
- Applications
- Group Policies
Components must be imported in an order that creates dependencies in the order they are needed. Automated Configuration correctly orders components when importing, merging, or restoring multiple components in a single cmdlet execution.
When importing single components with multiple commands, it is necessary to order the components so dependencies are imported in the required order.
Individual imports can then be made for updates after a complete site configuration has been imported successfully.
Dependency details
The components and their dependencies are listed here. A component’s dependencies must be in place for 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.
- Tags
- No pre-dependencies
- Host Connections
- Security Information in CvadAcSecurity.yml
- Machine Catalogs
- Machines present in Active Directory
- Host Connections
- Tags
- Delivery Groups
- Machines present in Active Directory
- Users present in Active Directory
- Machine Catalogs
- Tags
- Application Groups
- Delivery Groups
- Tags
- Applications
- Delivery Groups
- Application Groups
- Tags
- Group Policies
- Delivery Groups
- Tags
Populating customer info file
Use of the CustomerInfo.yml file eliminates the need to add customer information as cmdlet parameters. Any of the customer information can be overridden by using cmdlet parameters.
The CustomerInfo.yml file can be created by using the New-CvadAcCustomerInfoFile
cmdlet. New-CvadAcCustomerInfoFile
has the following parameters.
- CustomerId – customer’s ID.
- ClientId – customer’s client ID created on Citrix Cloud.
- Secret – customer’s secret created on Citrix Cloud.
New-CvadAcCustomerInfoFile -CustomerId markhof123 -ClientId 6813EEA6-46CC-4F8A-BC71-539F2DAC5984 -Secret TwBLaaaaaaaaaaaaaaaaaw==
You can update the CustomerInfo.yml file by using the Set-CvadAcCustomerInfoFile
cmdlet.
Note:
The cmdlet only changes the Customer ID, Client ID, or Secret key.
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"
CustomerId: "markhof123"
ClientId: "6713FEA6-46CC-4F8A-BC71-539F2DDK5384"
Secret: "TwBLaaabbbaaaaaaaaaaw=="
LogFileName: "CitrixLog"
Environment: Production
AltRootUrl: ""
StopOnError: False
AlternateFolder: ""
Locale: "en-us"
Editor: “C:\Program Files\Notepad++\notepad++.exe”
Confirm: True
DisplayLog: True
Generating the customer ID, client ID, and secret key
The following steps allow you to create the client ID and secret key that are required to import your configuration to Citrix Cloud.
-
Sign into your Citrix Cloud account and select the customer.
-
Click the hamburger menu, then select Identity and Access Management in the drop-down menu.
-
On the Identity and Access Management page, click the API Access tab.
-
Enter a name in the box. This name is used to differentiate between multiple client IDs and secret keys. Click Create Client to create the client ID and the secret key.
-
The following dialog appears after you successfully create the client ID and the secret key. Be sure to copy both values to a secure location or download the .csv file containing this information.
-
The client ID and the secret key are successfully created.
Place these values in a secure location and share only with trusted company members who need access to the tool or access the cloud Rest APIs. 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.
Note:
The secret key cannot be retrieved if it is lost or forgotten; a new client ID and secret key must be created.
Populating zone mapping file
The on-premises zone is the equivalent of the cloud resource location. Unlike other site components, you cannot import the on-premises zone to a cloud resource location automatically. It must be mapped using the ZoneMapping.yml file. Import failures can occur if the zone name does not match an existing resource location name.
The ZoneMapping.yml file is manually created after exporting your on-premises configuration but before importing to the cloud and must reside 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.
The following is an example:
---
Primary: "My Primary Resource Location"
Zone2: "Second Resource Location"
Note:
A space must be between the colon and resource location name.
If the ZoneMapping.yml file is not found or the correct mapping is not present, and the cloud site has only one zone, that zone is automatically used to map to all on-premises zones.
Migrating from cloud to cloud
Automated Configuration allows you to automate moving your cloud configuration to another cloud site or allowing you to restore your own cloud site.
Moving your Citrix Virtual Apps and Desktops Service configuration can be beneficial for many reasons:
- Migrating from one region to another
- Syncing your site from test or stage to production
- Disaster recovery
- Reaching resource limits
Backing up your Citrix Virtual Apps and Desktops Service configuration
Note:
Before you begin, follow the Import steps in Prerequisites for migrating your configuration to migrate your configuration from one cloud to another.
Important:
- You must have your CustomerInfo.yml file with your customer ID, client ID, and the secret key information included. For more information on how to retrieve your customer ID, client ID and secret key, see Generating the customer ID, client ID, and secret key. For information on how to add this information to the CustomerInfo.yml file, see Populating customer info file.
- The ZoneMapping.yml file must include information that maps your on-premises zone to Resource Locations in the cloud. For more information on how to map your zones, see Populating zone mapping file.
- If you have a Citrix Provisioning catalog or host connections, you must input the corresponding info in the HostSecurity.yml and CvadAcSecurity.yml.
- Install Automated Configuration.
- Run PowerShell as an administrator.
-
Run the following command to do a baseline backup.
Backup-CvadAcToFile –All $true
Note:
Other available commands are described here.
After you run any cmdlet for the first the time, 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. For more information about logs and the information provided in them, see Logging.
Restoring your configuration to Citrix Virtual Apps and Desktops Service
Note:
Note: This section follows Backing up your Citrix Virtual Apps and Desktops Service configuration and the steps documented there. Follow those steps before beginning the restore.
Running a baseline restore
- Run PowerShell as an administrator.
-
Run the following command to do a baseline restore.
Restore-CvadAcToSite -All $true -RestoreFolder <folder path of the backup files>
Note:
Other available commands are described here.
Verify the expected state with the new current state.
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. For more information about logs and the information provided in them, see Logging.
Disaster recovery
The disaster recovery process protects you from unintentional cloud site configuration changes or corruption. While Automated Configuration makes backups each time a change is made, this backup reflects the state of the cloud site configuration before the changes. Protecting yourself requires that you periodically back up your cloud site configuration and saving it in a safe place. If an undesirable change or corruption takes place, the backup can be used to fix the change or corruption at either a granular or full site configuration level.
Backup
To back up, run the backup cmdlet: Backup-CvadAcToFile
While individual components can be selected when backing up, for disaster recovery, Citrix suggests backing up all components. Backups are placed in a uniquely named folder under the root folder: %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss
Restore
Restore can be done from any backup to restore either one or more component members, one or more components or the full cloud site configuration.
Restoring Component Members
Restoring one or more component members makes use of the IncludeByName
feature. The Restore
cmdlet is invoked with the RestoreFrom
parameter along with the selected single component and the inclusion list.
To restore two group policies from a backup, follow this example:
Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss
-GroupPolicies $true -IncludeByName Policy1,Policy2
Restoring Entire Components
Restoring one component involves selecting one or more component parameters.
To restore the entire delivery group and machine catalog components, follow this example:
Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss
-DeliveryGroups $true -MachineCatalogs $true
Restoring the entire cloud site configuration
Restoring the full cloud site configuration means selecting all components to restore.
To restore the entire cloud site configuration, follow this example:
Restore-CvadAcToSite -RestoreFrom %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss
Automated Configuration tool cmdlets
Site management cmdlets
-
Export-CvadAcToFile
- Exports configuration from your on-premises setup. This 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 uniquely named Export subfolder. -
Import-CvadAcToSite
- Imports all the on-premises files to the cloud. This command ensures 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. Use with caution. -
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. -
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. -
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. -
Sync-CvadAcToSite
- Sync performs both an export and import in one step. -
Backup-CvadAcToFile
- Exports your cloud configuration to .yml files. This backup can be used for reverting to a previous configuration or for disaster recovery. -
Compare-CvadAcToSite
- Compares the on-premises .yml files with the cloud configuration, producing a report of changes that are made by anImport
,Merge
, orRestore
cmdlet. -
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 theIncludeByName
parameter to selectively remove specific members.
Granular migration cmdlet parameters
All cmdlets ending in ToSite
, ToFile
, and FromSite
allow selection of one or more components to act upon. These parameters give you further granularity to migrate only selective components. Make a selection by using one or more of the following true/false options.
Note:
Selecting
All
causes the other parameters to be ignored. TheAll
option is automatically selected when no components are selected.
All
Tags
MachineCatalogs
DeliveryGroups
ApplicationGroups
Applications
GroupPolicies
-
IncludeByName
andExcludeByName
- See the following for more information on these parameters.
Filtering by object names
Include and Exclude
The IncludeByName
and ExcludeByName
parameters enable including and excluding component members in cmdlets by name. Only one component (for example, delivery groups) can be chosen at a time in any of the supported cmdlets. If a component member is in both areas, exclude overrides any other parameter and an entry is made in the log fixup list identifying the component and member name that was excluded.
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
One example of merging all delivery groups whose names begin with DgSite1
and contain Home2
would be written:
Merge-CvadAcToSite –DeliveryGroups $true –IncludeByName DgSite1*,*Home2*
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 contain 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 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*
Exclude Disabled
ExcludeDisabled
filters out from import operations all applications and application groups that are disabled. ExcludeDisabled
defaults to false
, meaning all applications and application groups are imported regardless of their enabled state.
Migration modes parameters
Cmdlets modifying the cloud site configuration (Import
, Restore
, Merge
, New
, and Sync
) support the following extra parameters to provide further flexibility.
-
CheckMode
– Performs the import operation but makes no changes. All expected changes are reported before the import completes. You can use this command to test your import before it occurs. -
Merge
– Merges the file data to the cloud but does not delete any components. This option is enabled by default in theMerge
cmdlet but is optional inImport
andSync
. -
AddOnly
– Only adds components, does not update or delete existing components.AddOnly
is optional on all cmdlets exceptNew
, where it is enabled by default. -
BackupFirst
– Backs up the cloud contents to .yml files before modifying the cloud configuration. This is enabled by default. -
Confirm
– When true, prompts users to confirm that they want to make changes to the cloud site configuration. TheRemove
cmdlet shows a prompt due to its destructive nature. Set to false if no prompt is desired, such as running inside automated scripts.Confirm
defaults to true. -
AdminAddress
- Supported for export cmdlets, allowing to target any delivery controller to export from. The appropriate Citrix PowerShell SDKs must be installed on the machine running Automated Configuration as explained in Prerequisites for migrating your configuration. Host connections cannot be exported when the tool is run on a non-delivery controller machine. -
CheckAllMachines
– Checks that all machines in machine catalogs are present in Active Directory. If a machine is not present then it is removed from the machine catalog and a note about the removal is added to the Fixups list in the log file. This has the benefit of avoiding machine catalog add failures due to non-present machines.CheckAllMachines
defaults to true.
Cloud-accessing parameters
All cmdlets accessing the cloud, which are cmdlets ending with ToSite
or FromSite
and Get-CvadAcStatus
, support the following extra parameters.
Note:
These parameters are not needed if they are added into the CustomerInfo.yml file.
-
CustomerId
– The customer ID used in the Rest APIs and is required to access all Rest APIs. Your customer ID is found in Citrix Cloud. -
ClientId
– The clientID created on the Citrix Cloud Identity and Access Management website. This is required to obtain the bearer token needed for authentication for all Rest APIs. -
Secret
– The secret key created on the Citrix Cloud Identity and Access Management website. This is required to obtain the bearer token needed for authentication for all Rest APIs. -
CustomerInfoFileSpec
– The file specification pointing to a customer information file to override the default location and name. -
SiteActive
– Determines whether the cloud site is passive or active. The cloud site is passive when set toFalse
and active when set toTrue
.SiteActive
defaults toFalse
, setting the cloud site to passive.
Support and troubleshooting cmdlets
-
New-CvadAcCustomerInfoFile
- Creates a CustomerInfo.yml file which includes the CustomerId, ClientId, and Secret parameters. -
Set-CvadAcCustomerInfoFile
- Allows you to edit the CustomerId, ClientId, and Secret parameters in a CustomerInfo.yml file. -
New-CvadAcTemplateToFile
– Creates a template file for selected components, allowing you to manually create an import file. -
Test-CvadAcConnectionWithSite
– Test the connection with the cloud site to verify the communication connection is working. This cmdlet uses the cloud accessing parameters or the CustomerInfo.yml file to specify the customer connection information. -
Find-CvadAcConnector
- Locates existing connectors and determines their running state. This cmdlet uses information from the CustomerInfo.yml file or the customer ID parameter to locate the customer’s connectors. -
Get-CvadAcCustomerSites
- Returns the list of all the customer sites. This cmdlet uses the cloud accessing parameters or the CustomerInfo.yml file to specify the customer connection information. -
Get-CvadAcStatus
- Get Status returns information about the tool and the environment it is running in, including the tool version, whether the user has site administrator privileges for exporting, whether customer information (Customer ID, Client ID, and Secret) is present, whether the site can be communicated with, and whether one or more connectors are present.
Log display parameters
The Export
, Import
, Sync
, Restore
, Backup
, Compare
, and Remove
cmdlets display the log file when the operation completes. You can suppress the display by setting the -DisplayLog
parameter to $false
. Notepad.exe is used by default to display the log file. You can specify a different editor in the CustomerInfo.yml file.
Editor: C:\Program Files\Notepad++\notepad++.exe
Derived state results by command
Derived state can result in one of the three combinations of actions on the cloud site:
- Add, Update, and Delete
- Add and Update only
- Add only
The following table shows the derived state for each cmdlet and optional parameters that can change the derived state behavior of the cmdlet.
Command | Add, Update, Delete | Add, Update | Add |
---|---|---|---|
Import | -Merge $false |
Default | -AddOnly $true |
Merge | N/A | Default | -AddOnly $true |
New | N/A | N/A | Default |
Sync | -Merge $false |
Default | -AddOnly $true |
Restore | -Merge $false |
Default | -AddOnly $true |
Cmdlet return values
ActionResult
All cmdlets return the following value.
public class ActionResult
{
public bool Overall_Success;
public Dictionary<string, string> Individual_Success;
public object CustomResult;
}
Overall_Success
returns a single boolean showing the overall success of the cmdlet across all selected components: true meaning successful and false meaning unsuccessful.
Individual_Success
returns one or three values for each main component. A component’s result can be Success, Failure, or Skipped. Skipped indicates the component was not selected for execution by the cmdlet.
CustomResult
is cmdlet specific.
CustomResult
Import
, Merge
, Restore
, Sync
, Compare
, Compare File
, and Remove
return the following custom result information to a single instance of EvaluationResultData
.
Note:
Export
andTemplate
cmdlets do not return a custom result.
public class EvaluationResultData
{
public Dictionary<string, Dictionary<string, ActionResultValues >> EvaluationResults;
public int Added;
public int Updated;
public int Deleted;
public int NoChange;
public int TotalChanged;
public EvaluationResults OverallResult;
public string CloudBackupFolder;
public string SourceBackupFolder;
}
Where:
public enum ActionResultValues
{
Add,
Update,
Delete,
Identical,
DoNothing
}
public enum EvaluationResults
{
Success,
Failure,
Skipped
}
EvaluationResults
displays a list with one entry per selected component. The key is the component name and the value is a list of each component member and the action taken on that component member. Actions can be any one of the ActionResultValues
values.
Added
, Updated
, Deleted
, and NoChange
indicate the total number of component members added, updated, deleted, or no action taken, in that order.
TotalChanged
is the sum of Added
, Updated
, and Deleted
.
OverallResult
is a single boolean indicating the result of the cmdlet. True indicates total success across all components and false indicates failure in processing one or more components.
CloudBackupFolder
is the fully qualified file specification of the cloud site configuration backup before the cmdlet performing any cloud-modifying actions.
SourceBackupFolder
is the fully qualified file specification of the source file backup made after completion of the cmdlet. By default, these files are at %HOMEPATH%\Documents\Citrix\AutoConfig.
Help
PowerShell help is available for each cmdlet. All parameters are documented with each cmdlet along with a brief explanation of the cmdlet. To access help for any cmdlet, type Get-Help
in front of the cmdlet.
Get-Help Import-CvadAcToSite
Folders, backups, and logging
Automated Configuration initializes, updates, and backs up a cloud site configuration. When used over time, many different configurations can change on the cloud site. 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
Default folder root location
All Automated Configuration tool operations occur in the root folder or in 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 recent exported on-premises site configuration. Each Export subfolder contains 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 always sourced from files located in the root folder. Each operation results in the creation of 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 with 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 -DeliveryGroups $true -MachineCatalogs $true
Note:
The backup file information in the preceding cmdlet is based on your own 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 own backups.
Changing the default root folder
The Export
, Import
, Merge
, Sync
, and Compare
operations can change the default root folder by using the –AlternateFolder
parameter. The creation and management of per-operation subfolders remains the same as previously described.
Files copied to subfolders
All files having an “.yml” extension are copied to operation subfolders except for the following:
- CustomerInfo.yml
- ZoneMapping.yml
- HostSecurity.yml
Automated fail-safe cloud site backups
A backup of the current cloud site configuration is made before running operations that change the configuration. This includes Import
, Merge
, Sync
, and Restore
parameters. The backup is always in a subfolder beneath the operational subfolder.
In the case of Restore
, the backup folder is a subfolder of the folder specified on the -RestoreFrom
parameter.
Logging
Running any 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 date, operation, result, backup, and log file locations of the execution.
Logging details
Each log file includes the following:
- The name of the operation and whether 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 where applicable
- 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 made 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 the all Add
, Update
, and Delete
Rest API content.
Additional information
Importing other objects when you have Machine Creation Services machine catalogs
Currently, Automated Configuration does not support importing MCS machine catalogs or their corresponding delivery groups in an automated way. However, you can still import other configuration options such as applications and policies using Automated Configuration. You must create the machine catalog and delivery group using the same name as the on-premises setup. Follow the steps to prepare your environment, before proceeding to import the application settings:
-
In your Citrix Cloud portal, click the hamburger menu and go to My Services > Virtual Apps and Desktops Service > Manage. Create your MCS machine catalog as you normally would. Be sure to name your catalog exactly the same way your existing on-premises catalog is named.
-
Create the corresponding delivery group for the new catalog. Be sure you name it exactly after the corresponding on-premises delivery group.
-
In your on-premises environment’s Citrix Studio, in the Applications node, confirm the applications belong to the matching delivery groups by selecting the application, right-clicking the app, and going to Properties.
-
Click Groups to confirm the groups the app belongs to:
-
In PowerShell, run the Merge command and use the
byDeliveryGroupName
flag, which filters the applications by delivery group name.Merge-CvadAcToSite –Applications $true –ByDeliveryGroupName <DG_name>
-
Type Yes to continue.
-
On your Studio console in Citrix Cloud, go to Applications and refresh to make sure the apps are listed as expected. Select the applications and go to Application Properties > Groups to check.
Importing MCS-related policies
If you need to import policies associated with your MCS catalogs or groups, follow these instructions:
-
Run the
Merge-CvadAcToSite -GroupPolicies $true
command in PowerShell and type yes to continue.Successful execution displays a similar output to the preceding screenshot (Added values). The following screenshot shows the result of a line for which there were no changes (No Change).
-
Refresh the Studio window in Citrix Cloud and click Policies on the left-hand side.
-
Check the Policies Assigned to tab and compare it with your on-premises policy assignment.
Moving to Citrix Cloud Government
The Citrix Cloud Government environment uses different access points to authenticate and allocate access tokens. This unique requirement applies to any Automated Configuration tool accessing the cloud. Perform the following steps to use Automated Configuration in Citrix Cloud Government environments.
- In the %HOMEPATH%\Documents\Citrix\AutoConfig folder, edit CustomerInfo.yml.
-
Add the following line to CustomerInfo.yml (or change it, if already present.)
Environment: "ProductionGov"
Automated Configuration is now able to be used on Citrix Cloud Government environments.
Administrator scopes
The export and import processes support administrator scopes. However, the import process can only associate the scope, not create it. Follow these steps to successfully export and import administrator scopes to the cloud site.
- Export the on-premises site.
- In the on-premises Citrix Studio, navigate to the Configuration > Adminstrators > Scopes tab and take note of all scopes that are present. There is no need to note their associations as these are created when the components are imported.
- In the Citrix Cloud console, navigate to the Configuration > Adminstrators > Scopes tab and manually create each scope recorded from the previous step.
-
Import
,Merge
,Restore
,New
, orSync
the export from Step 1. - The manually created scopes are associated with the correct components.
If the administrator scopes are not manually created first, the import operation removes the scopes from the components. After the scopes are manually created, rerunning the import operation associates the scopes with the components.
Host connections
Host connections and their associated hypervisors can be exported and imported using Automated Configuration.
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 HostSecurity.yml file in %HOMEPATH%\Documents\Citrix\AutoConfig containing placeholders for each security item needed for the specific hypervisor type. You must update the HostSecurity.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.
---
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
- Amazon Web Services
- 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 Citrix Cloud’s Studio control panel. The host connections and hypervisor names must match to their on-premises counterparts exactly so that machine catalogs that use the host connections to be successfully imported.
Automation
Automated Configuration tool cmdlets can be run in automation scripts without admin intervention by suppressing prompts and the display of the log results at cmdlet completion. You can also set parameters to do the same by using the CustomerInfo.yml file.
Add the following parameter to cloud modifying cmdlets to suppress the display of prompts.
-Confirm $false
Add the following parameter to cmdlets to suppress the display of log at the completion of the cmdlet.
-DisplayLog $false
As another method, the following parameters can be placed in the CustomerInfo.yml file.
Confirm: False
DisplayLog: False
Exporting from PCs other than the delivery controller
The Automated Configuration tool uses multiple Citrix PowerShell SDKs to export the on-premises site configuration to files. These SDKs are automatically installed on the delivery controller, enabling the tool to run on the delivery controller without extra actions. When running on non-delivery controller machines, it is necessary to install the set of Citrix PowerShell SDKs needed by the tool. This SDK set is part of Citrix Studio which can be installed from the Citrix Virtual Apps and Desktop installation media.
Note:
Host connections cannot be exported from a non-delivery controller machine.
Automated Configuration cannot be run on the Cloud Connector.
Citrix Cloud data collection
For information on what information Citrix Cloud collects, see Citrix Cloud Services Customer Content and Log Handling.
Troubleshooting and recommendations
For more detailed and up-to-date troubleshooting and support information, see Knowledge Center article CTX277730.
For quick troubleshooting, review the log file, specifically the Fixups section.
Problems resulting from dependencies
Imports and merges might fail due to missing dependencies. Some common problems are:
- Group Policies are missing delivery group filters. The usual causes are delivery groups that have not been imported.
- Applications fail to import or merge. The usual cause is missing delivery groups or application groups that have not been imported.
- Application groups are missing a RestrictToTag. The usual causes are tags that have not been imported.
- Host connections fail. The usual cause is missing security information in the CvadAcSecurity.yml file.
- Machine catalogs fail. The usual cause is host connections that were not imported.
- Machines missing from machine catalogs and delivery groups. The usual cause is machines that were not found in Active Directory.
- Users missing from delivery groups. The usual cause is users that were not found in Active Directory.
Common problems
The cloud site is empty
An empty site indicates that a successful import/merge/restore operation has not completed. If an operation was attempted, review the logs from the operation.
The cloud site has more items than expected
This can happen if enhancements were made to the cloud site configuration and a Merge
operation was run. It can also happen if the cloud site configuration had previous values and an import/merge/restore operation had issues. Try rerunning the operation.
The cloud site has fewer items than expected
This can happen if enhancements were made to the cloud site configuration and an Import
operation with the Merge
parameter set to $false
, resulting in an identical derived state. The original state is backed up in the Automated Fail-Safe Cloud Site Backup folder associated with the import operation. To correct:
-
Restore the Automated Fail-Safe Cloud Site Backup using the Restore operation setting the RestoreFolder parameter to the Automated Fail-Safe Cloud Site Backup folder.
-
Use the
Merge
operation instead of theImport
operation.
Cloud site edits after import have been lost
This can occur if an Import
operation was done with the –Merge
parameter set to $false
, resulting in an identical derived state import. The original state is backed up in the Automated Fail-Safe Cloud Site Backup folder associated with the import operation. To correct:
-
Restore the Automated Fail-Safe Cloud Site Backup using the Restore operation setting the
RestoreFolder
parameter to the Automated Fail-Safe Cloud Site Backup folder. -
Use the
Merge
operation instead of theImport
operation.
The cloud site does not match the current on-premises site
This can occur when a Merge
operation was done resulting in a merged derived state instead of an Import
with the Merge
parameter set to $false
resulting in an identical derived state. Repeat using Import
with the Merge
parameter set to $false
.
Recommendations
- Do not run more than one instance of Automated Configuration at a time. Running multiple concurrent instances produces unpredictable results in the cloud site. If this occurs, rerun one instance of Automated Configuration to bring the site to the expected state.
- Do not work in Web Studio or Full Configuration while running Automated Configuration. Making changes in Web Studio or Full Configuration while running Automated Configuration can produce unpredictable results in the cloud site. If this occurs, rerun one instance of Automated Configuration to bring the site to the expected state.
- Always visually verify the merge/import/restore results in Web Studio or Full Configuration to ensure the cloud site meets expectations.
More information
-
Visit the Citrix Discussion forum for Automated Configuration.
-
Watch Under the Hood of the Automated Configuration Tool for CVAD on YouTube.
In this article
- Automated Configuration for Citrix Virtual Apps and Desktops
- Download Automated Configuration
- Prerequisites for migrating your configuration
- Migrating from on-premises to cloud
- Migrating from cloud to cloud
- Disaster recovery
- Automated Configuration tool cmdlets
- Folders, backups, and logging
- Additional information
- Troubleshooting and recommendations