Export and import the StoreFront configuration

Note:

You can only import StoreFront configurations which are exactly the same StoreFront version as the target StoreFront installation. Each Cumulative Update is considered to be different product version for this limitation.

You can export the entire configuration of a StoreFront deployment. This includes both single server deployments and server group configurations. If an existing deployment is already present on the importing server, the current configuration is erased and then replaced by the configuration contained within the backup archive. If the target server is a clean factory default installation, a new deployment is created using the imported configuration stored within the backup. The exported configuration backup is in the form of a single .zip archive if unencrypted, or a .ctxzip if you choose to encrypt the backup file when it is created.

Scenarios where configuration export and import can be used

• Only backup StoreFront deployments in a working and trusted state. Any changes to the configuration requires a new backup to be taken to replace the old one. You cannot modify existing backups as a file hash of the backup.zip file prevents modification.
• Backup BEFORE upgrading StoreFront for disaster recovery.
• Cloning existing testing StoreFront deployments to put into production
• Creating user acceptance environments by cloning production deployments into a test environment.
• Moving StoreFront during OS migrations such as upgrading the hosting from Window Server 2019 to Windows 2022. In-place OS upgrades are not supported.
• Building extra server groups in multigeo deployments such as in large enterprises with multiple datacenters.

Things to consider when exporting and importing a StoreFront configuration

• Do you currently use any Citrix published authentication SDK examples, such as Magic Word authentication or third party authentication customizations? If so, you must install these packages on ALL importing servers BEFORE importing a configuration containing extra authentication methods. The configuration import fails if required authentication SDK packages are not installed on any of the importing servers. If importing a configuration into a server group, install the authentication packages on all members of the group.
• You can encrypt or decrypt your configuration backups. The exporting and importing PowerShell cmdlets support both use cases.
• You can decrypt encrypted backups (.ctxzip) later, but StoreFront cannot re-encrypt unencrypted backup files (.zip). If an encrypted backup is required, perform the export again using a PowerShell credential object containing a password of your choice.
• The SiteID of the website in IIS where StoreFront is currently installed (exporting server) must match the SiteID of the target website in IIS (importing server) where you want to restore the backed up StoreFront configuration.

PowerShell cmdlets

Export-STFConfiguration

Important:

The SiteID parameter found in StoreFront 3.5 was deprecated in version 3.6. It is no longer necessary to specify the SiteID when performing an import, as the SiteID contained within the backup archive is always be used. Ensure the SiteID matches the existing StoreFront website already configured within IIS on the importing server. SiteID 1 to SiteID 2 configuration imports are NOT supported.

Import-STFConfiguration

Unprotect-STFConfigurationBackup

Configuration export and import examples

Import the StoreFront cmdlets into the current PowerShell session

Open the PowerShell Integrated Scripting Environment (ISE) on the StoreFront server and run:

$env:PSModulePath = [Environment]::GetEnvironmentVariable('PSModulePath','Machine')
$SDKModules = 'C:\Program Files\Citrix\Receiver StoreFront\PowerShellSDK\Modules\Citrix.StoreFront'
Import-Module "$SDKModules\Citrix.StoreFront.psd1" -verbose
Import-Module "$SDKModules.Authentication\Citrix.StoreFront.Authentication.psd1" -verbose
Import-Module "$SDKModules.Roaming\Citrix.StoreFront.Roaming.psd1" -verbose
Import-Module "$SDKModules.Stores\Citrix.StoreFront.Stores.psd1" -verbose
Import-Module "$SDKModules.WebReceiver\Citrix.StoreFront.WebReceiver.psd1" -verbose
<!--NeedCopy-->

Single server scenarios

Create an unencrypted backup of an existing configuration on Server A and restore it onto the same deployment

Export the configuration of the server you wish to back up.

Export-STFConfiguration -targetFolder "$env:userprofile\desktop\" -zipFileName "backup" -NoEncryption
<!--NeedCopy-->

Copy the backup.zip file to a safe location. You can use this backup for disaster recovery to restore the server to its previous state.

Import-STFConfiguration -configurationZip "$env:userprofile\desktop\backup.zip" -HostBaseURL "https://storefront.example.com"
<!--NeedCopy-->

Back up an existing configuration on Server A and restore it onto Server B to create a clone of an existing server

Export the configuration of the server you wish to back up.

Export-STFConfiguration -targetFolder "$env:userprofile\desktop\" -zipFileName "backup" -NoEncryption
<!--NeedCopy-->

Copy the backup.zip file to the desktop of server B.

Import-STFConfiguration -configurationZip "$env:userprofile\desktop\backup.zip" -HostBaseURL "https://serverB.example.com"
<!--NeedCopy-->

StoreFront is already deployed onto a custom website in IIS. Restore the configuration onto another custom website deployment

Server A has StoreFront deployed on a custom website location rather than the usual default website within IIS. The IIS SiteID for the second website created in IIS is 2. The StoreFront website’s physical path can be on another nonsystem drive such as d:\ or on the default c:\ system drive but should use an IIS SiteID greater than 1.

A new website called StoreFront has been configured within IIS, which uses SiteID = 2. StoreFront is already deployed on the custom website in IIS with its physical path on drive d:\inetpub\wwwrooot.

1. Export a copy of the Server A configuration.
2. On Server B, configure IIS with a new website called StoreFront, which also uses SiteID 2.

3. Import the Server A configuration onto Server B. The site ID contained in the backup is used and must match the target website where you want to import the StoreFront configuration.

   Import-STFConfiguration -configurationZip "$env:userprofile\desktop\backup.ctxzip" -HostBaseURL "https://serverB.example.com"
   <!--NeedCopy-->
   

Server group scenarios

Scenario 1: Backup an existing server group configuration and restore it later onto the same server group deployment

A previous configuration backup was taken while only two StoreFront servers, 2012R2-A and 2012R2-B, were members of the server group. Within the backup archive is a record of the CitrixClusterMembership at the time the backup was taken containing only the two original servers 2012R2-A and 2012R2-B. The StoreFront server group deployment has subsequently increased in size since the original backup was taken due to business demand, so an additional node 2012R2-C has been added to the server group. The underlying StoreFront configuration of the server group held in the backup has not changed. The current CitrixClusterMembership of three servers must be maintained even if an old backup containing only the two original server group nodes is imported. During import the current cluster membership is preserved and then written back once the configuration has been successfully imported onto the primary server. The import also preserves the current CitrixClusterMembership if server group nodes were removed from the server group since the original backup was taken.

1. Export the Server Group 1 configuration from 2012R2-A, which is the primary server used to manage the entire server group.

   

2. Later you add an additional server, 2012R2-C to the existing server group.

   

3. The configuration of the server group must be restored to a known previously working state. StoreFront backs up the current CitrixClusterMembership of three servers during the import process, and then restores it after the import has succeeded.

4. Import the Server Group 1 configuration back onto node 2012R2-A.

   Import-STFConfiguration -configurationZip "$env:userprofile\desktop\backup.ctxzip" -HostBaseURL "https://servergroup1.example.com"
   <!--NeedCopy-->
   

5. Propagate the newly imported configuration to the entire server group, so all servers have a consistent configuration after import.

Scenario 2: Backup an existing configuration from Server Group 1 and use it to create a new Server Group on a different factory default installation. You can then add other new server group members to the new primary server

Server Group 2 is created containing two new servers, 2012R2-C and 2012R2-D. The Server Group 2 configuration will be based on the configuration of an existing deployment, Server Group 1, which also contains two servers 2012R2-A and 2012R2-B. The CitrixClusterMembership contained within the backup archive is not used when creating a new server group. The current CitrixClusterMembership is always backed up and then restored after the import is successful. When creating a new deployment using an imported configuration, the CitrixClusterMembership security group contains only the importing server until additional servers are joined to the new group. Server Group 2 is a new deployment and intended to coexist alongside Server Group 1. Specify the -HostBaseURL parameter. Server Group 2 will be created using a new factory default StoreFront installation.

1. Export the Server Group 1 configuration from 2012R2-A, which is the primary server used to manage the entire server group.

2. Import the Server Group 1 configuration onto node 2012R2-C, which will be the primary server used to manage the newly created Server Group 2.

   Import-STFConfiguration -configurationZip "$env:userprofile\desktop\backup.ctxzip" -HostBaseURL "https://servergroup2.example.com"
   <!--NeedCopy-->
   

3. Join any additional servers that will be part of the new Server Group 2 deployment. Propagation of the newly imported configuration from Server Group 1 to all new members of Server Group 2 is automatic, as this forms part of the normal join process when a new server is added.

Scenario 3: Backup an existing configuration from Server Group A and use it to overwrite the existing Server Group B configuration

Server Group 1 and Server Group 2 already exist in two separate data centers. Many StoreFront configuration changes are made on Server Group 1, which you should apply to Server Group 2 in the other data center. You can port the changes from Server Group 1 to Server Group 2. Do not use the CitrixClusterMembership within the backup archive on Server Group 2. Specify the -HostBaseURL parameter during import, as the Server Group 2 host base URL should not be changed to the same FQDN that is currently in use by Server Group 1. Server Group 2 is an existing deployment.

1. Export the Server Group 1 configuration from 2012R2-A, which is the primary server used to manage the entire server group.

2. Import the Server Group 1 configuration onto the factory default installation on node 2012R2-C, which will be the primary server of the new Server Group 2.

   Import-STFConfiguration -configurationZip "$env:userprofile\desktop\backup.zip" -NoEncryption -HostBaseURL "https://servergroup2.example.com"
   <!--NeedCopy-->
   

Create an encrypted backup of your server configuration

A PowerShell credential object comprises both a Windows account username and a password. PowerShell credential objects ensure that your password stays protected in memory.

Note:

To encrypt a configuration backup archive, you need only the password to perform encryption and decryption. The username stored within the credential object is not used. You must create a credential object containing the same password within the PowerShell session that is used on both the exporting and importing servers. Within the credential object you can specify any user.

PowerShell requires that you specify a user when creating a new credential object. This example code obtains the currently logged on Windows user for convenience.

Create a PowerShell Credential Object within your Powershell session on the exporting server.

$User = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
$Password = "Pa55w0rd"
$Password = $Password | ConvertTo-SecureString -asPlainText -Force
$CredObject = New-Object System.Management.Automation.PSCredential($User,$Password)
<!--NeedCopy-->

Export the configuration to backup.ctxzip which is an encrypted zip file.

Export-STFConfiguration -targetFolder "$env:userprofile\desktop\" -zipFileName "backup" -Credential $CredObject
<!--NeedCopy-->

Create an identical PowerShell Credential Object within your Powershell session on the importing server.

Import-STFConfiguration -configurationZip "$env:userprofile\desktop\backup.ctxzip" -Credential $CredObject -HostBaseURL "https://storefront.example.com"
<!--NeedCopy-->

Unprotect an existing encrypted backup archive

$User = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
$Password = "Pa55w0rd"
$Password = $Password | ConvertTo-SecureString -asPlainText -Force
$CredObject = New-Object System.Management.Automation.PSCredential($User,$Password)

Unprotect-STFConfigurationExport -encryptedConfigurationZip "$env:userprofile\desktop\backup.ctxzip" -credential $CredObject -outputFolder "c:\StoreFrontBackups" -Force
<!--NeedCopy-->