PoC Guide: Automated Configuration Tool - Backup and Restore On-Premises

Overview

The Citrix Automated Configuration Tool (ACT) migrates workloads and aids in daily Citrix administration tasks for both on-premises and Cloud. The ACT Backup and Restore functionality allow Citrix administrators to create a Citrix Site backup in configuration files (.yaml), which contain the current state of the site. Think of this as a point-in-time snapshot of your Citrix Site, rather than an incremental backup. ACT generates configuration files for each of the Citrix components (Machine Catalogs, Delivery Groups, Applications, and Host Connections). The ACT Backup and Restore feature are only available as part of the Citrix Web Studio console. The article Install Web Studio details the steps required to install and configure the Citrix Web Studio console.

Backup and Restore Process

When you select the Backup + Restore tab in Citrix Web Studio, you're prompted to download and install the Automated Configuration Tool. The Backup and Restore process is completed using the PowerShell SDK of the ACT.

Download the .msi file and install the Automated Configuration Tool. It's suggested to install it on a Citrix Delivery Controller server.

After installing the Automated Configuration Tool, verify the installation by viewing it listed under 'Programs and Features'.

A Direct Access icon named Auto Config is created for the Automated Configuration Tool on the desktop.

Creating a Backup and Restore

Before starting working with the tool, let’s get familiar with the main base cmdlets of the Automation Configuration Tool:

• Backup-CvadAcToFile - Backs up all the configurations from your Citrix Site.
• Restore-CvadAcToSite - Restores backup YAML files to the Citrix Site. This can refer to the same or a different Citrix Site.

Based on these cmdlets, you can do either a full restore or a granular selection of the component you want by adding a switch pointing to the specific resource/configuration file (.yml) such as -includebyname (we explain this later and provide examples).

Backing up your site is a straightforward process, as mentioned, the Automated Configuration Tool exports your site “snapshot” into configuration files. The ACT files are in the folder %HOMEPATH%\Documents\Citrix\AutoConfig

Below is a screenshot displaying the contents of a backup folder. A unique folder is created for each backup with the date and time stamp of when the backup was completed. Every backup folder has configuration files that can be used to restore.

Backup and Restore Example

This example walks you through the following processes to begin using the Automated Configuration Tool:

1. Creating the base folder structure %HOMEPATH%\Documents\Citrix\AutoConfig
2. Modifying the CustomerInfo.yml file for On-Premises
3. Creating a Backup
4. Restoring from Backup

Creating the Folder Structure

The ACT requires a folder structure to locate the .yml files generated during the backup. First, we need to 'export' the initial configuration.

• Launch ACT and run the command Export-CvadAcToFile

ACT creates the folder structure, and in it the configuration files. Below is a screenshot displaying the results.

Modifying Configuration File for On-Premises

• Open the CustomerInfo.yml file from C:\Users\%username%\Documents\Citrix\AutoConfig
• Find the 'Environment' variable and replace the value 'Production' with 'OnPrem'

Note:

Remember, the 'OnPrem' parameter is case-sensitive. Be sure to capitalize both the 'O' and 'P,' or else you are asked to log in to Citrix Cloud.

Creating a Backup

Once the Folder structure is ready, you can continue to run the 'Backup' cmdlet. As mentioned before, to create a backup you need to run the following command: Backup-CvadAcToFile

Restoring from Backup

Files that are imported come from the folder specified using the -RestoreFolder parameter. This parameter recognizes the folder that holds the .yml files to restore the site. This must be a fully qualified folder path. This cmdlet can also be used to revert to the previous configuration or to backup and restore your Citrix Site. This command can add, delete, and update your Citrix Cloud Site.

Note:

The switch name corresponds to each .yaml file's content, allowing you to restore components like Machine Catalogs, Delivery Groups, Applications, and Policies.

Here are some examples of restoration granularity and their corresponding commands:

• Restore to a specific backup
  • Restore-CvadAcToSite -RestoreFolder %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

Restore Granular for specific components

• Restore a specific Machine Catalog

  • Restore-CvadAcToSite -RestoreFolder %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss -MachineCatalog -IncludeByName “name of the catalog”

• Restore a specific Delivery Group

  • Restore-CvadAcToSite -RestoreFolder %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss -DeliveryGroups -IncludeByName “name of the Delivery Group”

Running the Restore

Launch ACT and enter the 'Restore' command depending on what you want to restore, either a full restore or by component.

We're restoring a single Delivery group in this example to demonstrate how detailed and granular the command syntax can be. Restore-CvadAcToSite -RestoreFolder C:\Users\amiringectxadminaz\Documents\Citrix\AutoConfig\Backup_2023_04_14_10_50_31 -DeliveryGroups -IncludeByName “VDI-MANUAL”

Let’s break down this command for a clear understanding of how it works. This provides guidance on using other switches:

• Restore-CvadAcToSite: This is the base Restore command or instruction.
• -RestoreFolder: followed by the folder name. It calls the specific path/location of the files that we want to restore.
• -DeliveryGroups: Switch used to specify Citrix Component to migrate.
• -IncludeByName: Specify a single resource to migrate using this command (add suffix/prefix to restore multiple resources with similar names).

A prompt request for you to 'Confirm' if you want to continue.

• Type YES to continue.

The ACT starts the process by contacting the backup folder that you specified in the command, followed by the specific component (Delivery Group, in this example). ACT reads and pulls the existing information in the DeliveryGroups.yml file, as demonstrated below:

Final Result

Once ACT finishes running the restore process, it generates a Log File with details of what was done and list recommendations in case something goes wrong. Below you can see the content of the log file.

From the Citrix Web Studio console and click the Refresh button on the top right corner to refresh the console and show the restored components.

• Click “Refresh” on the Citrix Web Studio console.
• The Restore process is complete.

Summary

This guide walked you through configuring the ACT folder structure, modifying the On-Premises configuration, creating a backup, and performing a restore. To learn more about the Citrix Automated Configuration Tool cmdlets, visit the Automated Configuration Tool product documentation