Troubleshoot Automated configuration and additional information
Important:
For commonly occurring error messages for Automated configuration and corresponding solutions, see the troubleshooting FAQ at Knowledge Center article CTX277730.
Automated configuration tool errors
Automated configuration tool operations can sometimes produce errors. When this happens failures can occur when processing components like Machine Catalogs, Delivery Groups, or Group Policies, for example. Using OnErrorAction and continuation parameters allows you to catch errors mid-processing, resolve them, and pick up where you left off.
The default OnErrorAction value is StopCompEnd. When an error occurs, the tool finishes processing the current component. No additional components are processed, and errors do not carry forward to downstream, dependent components. After you resolve any errors, you can rerun your cmdlets with any continuation parameter applied.
OnErrorAction parameter
You can define OnErrorAction parameter values on migration commands to control how the tool responds to errors that it finds when processing components.
This table shows parameter values and their descriptions:
| Value | Description |
|---|---|
Continue |
Attempts to process as many of all components as possible. |
Pause |
Pauses at the end of processing and prompts you to continue or stop. |
StopCompEnd |
Attempts to process as much of the component as possible. Stops after the component is finished. (Default) |
StopImmediately |
Processing stops when an error is found. |
Migration cmdlets
You can apply the OnErrorAction parameter to the following migration commands:
Compare-CvadAcToSiteImport-CvadAcToSiteMerge-CvadAcToSiteNew-CvadAcToSiteRestore-CvadAcToSite
Example: Merge-CvadAcToSite -OnErrorAction StopImmediately
Resume parameters
These parameters define how the tool resumes after an operation pauses or stops because of an error.
You can apply resume parameters to migration cmdlets that include one of the following OnErrorAction parameter values:
PauseStopCompEndStopImmediately
This table shows parameter values and their descriptions:
| Value | Description |
|---|---|
-AllRemaining |
Requires a starting component. Processing begins at the starting component and processes all remaining components. Multiple components are processed. |
-Resume |
Uses the component from CurrentComponent.txt as the starting point. All remaining is set to true. Multiple components are processed. |
-Repeat |
Uses the component from CurrentComponent.txt as the starting point. All remaining is set to false. Only one component is processed. |
The last component processed is stored in the CurrentComponent.txt file in the AutoConfig folder. Editing this file is not recommended.
If you specify -Resume or -Repeat, and CurrentComponent.txt is missing or invalid, processing stops, and you are prompted to select a component.
Setting the OnErrorAction in the CustomerInfo.yml file
You can also set OnErrorAction values in the CustomerInfo.yml file. Set the values using the following cmdlets:
- For a new file:
New-CvadAcCustomerInfoFile -OnErrorAction Continue | Pause | StopCompEnd | StopImmediately - For an existing file:
Set-CvadAcCustomerInfoFile -OnErrorAction Continue | Pause | StopCompEnd | StopImmediately
Logs
Running any cmdlet results in a log file creation and an entry in the main 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 main history log is located in *%HOMEPATH%\Documents\Citrix\AutoConfig*, in the file named History.Log. Each cmdlet execution results in a main log entry containing the date, operation, result, backup, and log file locations of the execution.
You can also use the New-CvadAcZipInfoForSupport cmdlet to collect logs to send to Citrix for support. This cmdlet zips all log and .yml files in a single zip file. Customer sensitive information (CustomerInfo.yml and CvadAcSecurity.yml) is not included in the zip. The Icon.yml file is also excluded due to its size. The zip file is placed in %HOMEPATH%\Documents\Citrix\AutoConfig and named CvadAcSupport_yyyy_mm_dd_hh_mm_ss.zip, based on the date and timestamp. This zip file can also act as a backup.
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 where applicable
- Main 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 counts 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.
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.
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 or change data in Studio while running Automated configuration.
- Always visually verify the merge or import or restore results in Studio to ensure that the cloud site meets expectations.
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.
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.
Backups
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.
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 -RestoreFolder %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss -DeliveryGroups -MachineCatalogs
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 -RestoreFolder %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
- CvadAcSecurity.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 -RestoreFolder parameter.
Automation
Automated configuration tool cmdlets can be run in automation scripts without administrator 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
Add the following parameter to cmdlets to suppress logging to the PowerShell command window.
-Quiet
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 Desktops installation media.
Note:
Automated configuration cannot be run on the Cloud Connector.
Moving to Citrix Cloud Government and Japan Control Plane
The Citrix Cloud Government and Japan Control Plane environments use 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 these environments.
- In the %HOMEPATH%\Documents\Citrix\AutoConfig folder, edit CustomerInfo.yml.
-
Add one of the following lines, depending on the environment you want to connect to, to CustomerInfo.yml (or change it, if already present.)
Environment: 'ProductionGov'or
Environment: 'ProductionJP'
Automated Configuration is now able to be used on these environments.
Citrix Cloud data collection
For information on what information Citrix Cloud collects, see Citrix Cloud Services Customer Content and Log Handling.
Additional resources
Discussion forum
Visit the Citrix Discussion forum for Automated Configuration.
Video
Watch Under the Hood of the Automated Configuration Tool for Citrix Virtual Apps and Desktops on YouTube.
Training
The Cloud Learning Center contains step-by-step video guides to building a service deployment, including the tasks described in this article. See Migrating Citrix Virtual Apps and Desktops to Citrix Cloud Learning Path.