Troubleshoot Automated Configuration and additional information
For commonly occurring error messages for Automated Configuration and corresponding solutions, see the troubleshooting FAQ at Knowledge Center article CTX277730.
Running any cmdlet results in a created log file 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 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
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.
This file counts all Broker PowerShell SDK calls made to export the site configuration to files.
Import, Merge, Restore, Sync, Backup, Compare
This file documents each Rest API call and related information.
This file contains the all
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.
- 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 the Manage tab in Full Configuration while running Automated Configuration.
- Always visually verify the merge/import/restore results in Full Configuration to ensure that the cloud site meets expectations.
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.
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.
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 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
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
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
The backup file information in the preceding cmdlet is based on your own backups.
Changing the default root folder
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 a “.yml” extension are copied to operation subfolders except for the following:
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
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
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.
Add the following parameter to cmdlets to suppress the display of log at the completion of the cmdlet.
Add the following parameter to cmdlets to suppress logging to the PowerShell command window.
As another method, the following parameters can be placed in the CustomerInfo.yml file.
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.
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.)
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.
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.