Product Documentation

Set up highly available multi-site store configurations

Jan 31, 2017

For stores that aggregate resources from multiple deployments, particularly geographically dispersed deployments, you can configure load balancing and failover between deployments, mapping of users to deployments, and specific disaster recovery deployments to provide highly available resources. Where you have configured separate NetScaler Gateway appliances for your deployments, you can define the optimal appliance for users to access each of the deployments. If you deploy NetScaler Gateway in a global server load balancing configuration, you must update the store configuration with details for each of the appliances.

Configure load balancing, failover, disaster recovery, and user mapping for a store

To set up load balancing, failover, disaster recovery, and user mapping, you edit the store configuration files. After configuring load balancing, failover, disaster recovery, and user mapping for a store, some tasks become unavailable in the Citrix StoreFront management console to prevent misconfiguration.

Important: In multiple server deployments, use only one server at a time to make changes to the configuration of the server group. Ensure that the Citrix StoreFront management console is not running on any of the other servers in the deployment. Once complete, propagate your configuration changes to the server group so that the other servers in the deployment are updated.
  1. Ensure that you have configured the store with details of all the XenDesktop and XenApp deployments that you want to use in your configuration, including disaster recovery deployments. For more information about adding deployments to stores, see Manage the resources made available in stores.
  2. Use a text editor to open the web.config file for the store, which is typically located in the C:\inetpub\wwwroot\Citrix\storename\ directory, where storename is the name specified for the store when it was created.
  3. Locate the following section in the file.
    <resourcesWingConfigurations> 
      <resourcesWingConfiguration name="Default" wingName="Default" /> 
    </resourcesWingConfigurations>
    
  4. Specify your configuration as shown below.
    <resourcesWingConfigurations> 
      <resourcesWingConfiguration name="Default" wingName="Default"> 
        <userFarmMappings> 
          <clear /> 
          <userFarmMapping name="user_mapping"> 
            <groups> 
              <group name="domain\usergroup" sid="securityidentifier" /> 
              <group ... /> 
              ... 
            </groups> 
            <equivalentFarmSets> 
              <equivalentFarmSet name="setname" loadBalanceMode="{LoadBalanced | Failover}"  
               aggregationGroup="aggregationgroupname"> 
                <primaryFarmRefs> 
                  <farm name="primaryfarmname" /> 
                  <farm ... /> 
                  ... 
                </primaryFarmRefs> 
                <backupFarmRefs> 
                  <farm name="backupfarmname" /> 
                  <farm ... /> 
                  ... 
                </backupFarmRefs> 
              </equivalentFarmSet> 
              <equivalentFarmSet ... > 
                ... 
              </equivalentFarmSet> 
            </equivalentFarmSets> 
          </userFarmMapping> 
          <userFarmMapping> 
            ... 
          </userFarmMapping> 
        </userFarmMappings> 
      </resourcesWingConfiguration> 
    </resourcesWingConfigurations>
    

    Use the following elements to define your configuration.

    userFarmMapping
    Specifies groups of deployments and defines the load balancing and failover behavior between those deployments. Identifies deployments to be used for disaster recovery. Controls user access to resources by mapping Microsoft Active Directory user groups to the specified groups of deployments.
    groups
    Specifies the names and security identifiers (SIDs) of Active Directory user groups to which the associated mapping applies. User group names must be entered in the format domain\usergroup. Where more than one group is listed, the mapping is only applied to users who are members of all the specified groups. To enable access for all Active Directory user accounts, set the group name & sid to everyone.
    equivalentFarmSet
    Specifies a group of equivalent deployments providing resources to be aggregated for load balancing or failover, plus an associated group of disaster recovery deployments. The loadBalanceMode attribute determines the allocation of users to deployments. Set the value of the loadBalanceMode attribute to LoadBalanced to randomly assign users to deployments in the equivalent deployment set, evenly distributing users across all the available deployments. When the value of the loadBalanceMode attribute is set to Failover, users are connected to the first available deployment in the order in which they are listed in the configuration, minimizing the number of deployments in use at any given time. Specify names for aggregation groups to identify equivalent deployment sets providing resources to be aggregated. Resources provided by equivalent deployment sets belonging to the same aggregation group are aggregated. While deployments within an equivalent deployment set must be identical, deployments aggregated from different sets do not need to provide exactly the same resources. To specify that the deployments defined in a particular equivalent deployment set should not be aggregated with others, set the aggregation group name to None.
    primaryFarmRefs
    Specifies a set of equivalent XenDesktop or XenApp deployments providing identical resources. Enter the names of deployments that you have already added to the store. The names of the deployments you specify must match exactly the names you entered when you added the deployments to the store.
    optimalGatewayForFarms
    Specifies groups of deployments and defines the optimal NetScaler Gateway appliances for users to access resources provided by these deployments. Typically, the optimal appliance for a deployment is colocated in the same geographical location as that deployment. You only need to define optimal NetScaler Gateway appliances for deployments where the appliance through which users access StoreFront is not the optimal appliance.

Configure subscription synchronization

To configure periodic pull synchronization of users' application subscriptions from stores in different StoreFront deployments, you execute Windows PowerShell commands.

Note: The StoreFront and PowerShell consoles cannot be open at the same time. Always close the StoreFront admin console before using the PowerShell console to administer your StoreFront configuration. Likewise, close all instances of PowerShell before opening the StoreFront console.
Important: In multiple server deployments, use only one server at a time to make changes to the configuration of the server group. Ensure that the Citrix StoreFront management console is not running on any of the other servers in the deployment. Once complete, propagate your configuration changes to the server groups so that the other servers in the deployment are updated.

When establishing your subscription synchronization, note that the configured Delivery Controllers must be named identically between the synchronized Stores and that the Delivery Controller names are case sensitive. Failing to duplicate the Delivery Controller names exactly may lead to users having different subscriptions across the synchronized Stores.

  1. Use an account with local administrator permissions to start Windows PowerShell and, at a command prompt, type the following commands to import the StoreFront modules.
    Import-Module "installationlocation\Management\Cmdlets\UtilsModule.psm1" 
    Import-Module "installationlocation\Management\Cmdlets\ 
      SubscriptionSyncModule.psm1"
    

    Where installationlocation is the directory in which StoreFront is installed, typically C:\Program Files\Citrix\Receiver StoreFront\.

  2. To specify the remote StoreFront deployment containing the store to be synchronized, type the following command.
    Add-DSSubscriptionsRemoteSyncCluster –clusterName deploymentname 
      –clusterAddress deploymentaddress
    

    Where deploymentname is a name that helps you identify the remote deployment and deploymentaddress is the externally accessible address of the StoreFront server or load-balanced server group for the remote deployment.

  3. To specify the remote store with which to synchronize users' application subscriptions, type the following command.
    Add-DSSubscriptionsRemoteSyncStore –clusterName deploymentname 
      –storeName storename
    

    Where deploymentname is the name that you defined for the remote deployment in the previous step and storename is the name specified for both the local and remote stores when they were created. To synchronize application subscriptions between the stores, both stores must have the same name in their respective StoreFront deployments.

  4. To configure synchronization to occur at a particular time every day, type the following command.
    Add-DSSubscriptionsSyncSchedule –scheduleName 
      synchronizationname –startTime hh:mm
    

    Where synchronizationname is a name that helps you identify the schedule you are creating. Use the -startTime setting to specify a time of day at which you want to synchronize subscriptions between the stores. Configure further schedules to specify additional synchronization times throughout the day.

  5. Alternatively, to configure regular synchronization at a specific interval, type the following command.
    Add-DSSubscriptionsSyncReoccuringSchedule –scheduleName 
      synchronizationname –startTime hh:mm:ss -repeatMinutes interval
    

    Where synchronizationname is a name that helps you identify the schedule you are creating. Use the -startTime setting to specify the a time of day at which you want to start the reoccurring schedule. For interval, specify the time in minutes between each synchronization.

  6. Add the Microsoft Active Directory domain machine accounts for each StoreFront server in the remote deployment to the local Windows user group CitrixSubscriptionSyncUsers on the current server.

    This will allow the servers in the remote deployment to access the subscription store service on the local deployment once you have configured a synchronization schedule on the remote deployment. The CitrixSubscriptionSyncUsers group is automatically created when you import the subscription synchronization module in Step 1. For more information about modifying local user groups, see http://technet.microsoft.com/en-us/library/cc772524.aspx.

  7. If your local StoreFront deployment consists of multiple servers, use the Citrix StoreFront management console to propagate the configuration changes to the other servers in the group.

    For more information about propagating changes in a multiple server StoreFront deployment, see Configure server groups.

  8. Repeat Steps 1 to 7 on the remote StoreFront deployment to configure a complementary subscription synchronization schedule from the remote deployment to the local deployment.

    When configuring the synchronization schedules for your StoreFront deployments, ensure that the schedules do not lead to a situation where the deployments are attempting to synchronize simultaneously.

  9. To start synchronizing users' application subscriptions between the stores, restart the subscription store service on both the local and remote deployments. At a Windows PowerShell command prompt on a server in each deployment, type the following command.
    Restart-DSSubscriptionsStoreSubscriptionService
    
  10. To remove an existing subscription synchronization schedule, type the following command. Then, propagate the configuration change to the other StoreFront servers in the deployment and restart the subscription store service.
    Remove-DSSubscriptionsSchedule –scheduleName synchronizationname  
    

    Where synchronizationname is the name that you specified for the schedule when you created it.

  11. To list the subscription synchronization schedules currently configured for your StoreFront deployment, type the following command.
    Get-DSSubscriptionsSyncScheduleSummary
    

Configure optimal NetScaler Gateway routing for a store

Important: In multiple server deployments, use only one server at a time to make changes to the configuration of the server group. Ensure that the Citrix StoreFront management console is not running on any of the other servers in the deployment. Once complete, propagate your configuration changes to the server group so that the other servers in the deployment are updated.

Use PowerShell to configure optimal NetScaler Gateway routing for a store

Configure optimal NetScaler Gateway routing to optimize the handling of ICA connection routing from the HDX engine to published resources such as XenDesktop VDAs or XenApp or XenDesktop published applications using StoreFront. Typically, the optimal gateway for a site is collocated in the same geographical location.

You need only define optimal NetScaler Gateway appliances for deployments where the appliance through which users access StoreFront is not the optimal gateway. If launches should be directed back through the gateway making the launch request, StoreFront does this automatically.

Example scenario

1 x UK Gateway –> 1 x UK StoreFront

–> UK Apps and Desktops local

–> US Apps and Desktops used only for UK failover

   

1 x US Gateway–> 1 x UK StoreFront

–> US Apps and Desktops local

-> UK Apps and Desktops used only for US failover

A UK gateway provides remote access to UK hosted resources such as apps and desktops using a UK StoreFront.

The UK storefront has both a UK based and US based NetScaler Gateway defined and UK and US farms in its delivery controller list. UK users access remote resources through their geographically collocated gateway, StoreFront, and farms. If their UK resources become unavailable, they can connect to US resources as a temporary failover alternative.

Without optimal gateway routing all ICA launches would pass through the UK gateway that made the launch request regardless of where the resources are geographically located. By default, gateways used to make launch requests are identified dynamically by StoreFront when the request is made. Optimal gateway routing overrides this and forces US connections through the gateway closest to the US farms that provides apps and desktops.

Note: You can map only a single optimal gateway per site for each StoreFront store.
Figure 1. Suboptimal gateway routing
Figure 2. Optimal gateway routing

PowerShell API parameters

Parameter Description
-SiteId (Int)

Site ID within IIS. This is typically 1 for the site in IIS where StoreFront is installed by default.

-ResourcesVirtualPath (String)

Path to the store that is to be configured to have a farm to optimal gateway mapping.

Example: “/Citrix/Store”

-GatewayName (String)

Name given to identify the Netscaler Gateway within StoreFront.

Example 1: ExternalGateway

Example 2: InternalGateway

-Hostnames (String Array)

Specifies the fully qualified domain name (FQDN) and port of the optimal NetScaler Gateway appliance.

Example1 for standard vServer port 443: gateway.example.com

Example2 for nonstandard vServer port 500: gateway.example.com:500

-Farms (String Array)

Specifies a set of (typically collocated) XenDesktop, XenApp, and App Controller deployments that share a common optimal NetScaler Gateway appliance. A farm can contain just a single delivery controller or multiple delivery controller that provides published resources.

You can configure a XenDesktop site in StoreFront under delivery controllers as “XenDesktop”. This represents a single farm.

This could contain multiple delivery controllers in its failover list:

Example: “XenDesktop"

XenDesktop-A.example.com

XenDesktop-B.example.com

XenDesktop-C.example.com

-staUrls (String Array)

Specifies the URLs for XenDesktop or XenApp servers running the Secure Ticket Authority (STA). If using multiple farms, list the STA servers on each using a comma separated list:

Example: "http://xenapp-a.ptd.com/scripts/ctxsta.dll","http://xendesktop-a.ptd.com/scripts/ctxsta.dll"

-StasUseLoadBalancing (Boolean)

Set to true: randomly obtains session tickets from all STAs, evenly distributing requests across all the STAs.

Set to false: users are connected to the first available STA in the order in which they are listed in the configuration, minimizing the number of STAs in use at any given time.

-StasBypassDuration

Set the time period, in hours, minutes, and seconds, for which an STA is considered unavailable after a failed request.

Example: 00.02:00:00

-EnableSessionReliability (Boolean)

Set to true: keeps disconnected sessions open while Receiver attempts to reconnect automatically. If you configured multiple STAs and want to ensure that session reliability is always available, set the value of the useTwoTickets attribute to true to obtain session tickets from two different STAs in case one STA becomes unavailable during the session.

-UseTwoTickets (Boolean)

Set to true: obtains session tickets from two different STAs in case one STA becomes unavailable during the session.

Set to false: uses only a single STA server.

-EnabledOnDirectAccess (Boolean)

Set to true: ensures that when local users on the internal network log on to StoreFront directly, connections to their resources are still routed through the optimal appliance defined for the farm.

Set to false: connections to resources are not routed through the optimal appliance for the farm unless users access StoreFront through a NetScaler Gateway.

Note: When PowerShell scripts span multiple lines such as shown below, each line must end with the backtick control character (').

Copy the following code examples into the Windows PowerShell Integrated Scripting Environment (ISE) to validate the code using the dynamic compiler before you run it.

Configure an optimal gateway for a farm

Example:

Create or overwrite OptimalGatewayForFarms mappings for the store Internal.

& "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1" 
 
Set-DSOptimalGatewayForFarms -SiteId 1 `
                        -ResourcesVirtualPath /Citrix/Internal  `
                        -GatewayName "gateway1"  `
                        -Hostnames "gateway1.example.com:500" `
                        -Farms "XenApp","XenDesktop" `
                        -StaUrls "https://xenapp.example.com/scripts/ctxsta.dll","https://xendesktop.example.com/scripts/ctxsta.dll"  `
                        -StasUseLoadBalancing:$false `
                        -StasBypassDuration 00.02:00:00 `
                        -EnableSessionReliability:$false `
                        -UseTwoTickets:$false `
                        -EnabledOnDirectAccess:$true

Example:

This script returns configured OptimalGatewayForFarms for the store called Internal.

Get-DSOptimalGatewayForFarms -SiteId 1 –ResourcesVirtualPath “/Citrix/Internal”

Example:

Remove all optimal gateway for farms mappings for store called Internal.

Remove-DSOptimalGatewayForFarms -SiteId 1 -ResourcesVirtualPath “/Citrix/Internal”

Configure a NULL gateway for a farm

Example:

This script prevents all ICA launches from passing through a gateway for the list of specified farms for the store called Internal.

Set-DSFarmsWithNullOptimalGateway -SiteId 1 -ResourcesVirtualPath /Citrix/Store -Farms "Farm1","Farm2"

Example:

This script returns all farms that are configured to prevent ICA launches from passing through a gateway for a store called Internal.

Get-DSFarmsWithNullOptimalGateway -SiteId 1 -ResourcesVirtualPath "/Citrix/Internal"

Determine if your OptimalGatewayForFarms mappings are being used by StoreFront

  1. Enable StoreFront tracing on all server group nodes using PowerShell by running:
    & "$Env:PROGRAMFILES\Citrix\Receiver StoreFront\Scripts\ImportModules.ps1" 
     
    #Traces output is to c:\Program Files\Citrix\Receiver Storefront\admin\trace\ 
    Set-DSTraceLevel -All -TraceLevel Verbose
    
  2. Open the Debug View tool on the desktop of a StoreFront server. If you are using a storefront server group, you might have to do this on all nodes to ensure you obtain traces from the node that receives the launch request.
  3. Enable Capture Global Win32 events.

  4. Save the trace output as a .log file and open the file with Notepad. Search for the log entries shown in the example scenarios below.
  5. Turn tracing off afterwards, as it consumes a lot of disk space on your StoreFront servers.
    Set-DSTraceLevel -All -TraceLevel Off
    

    Tested optimal gateway scenarios

    • External client logs on Gateway1. Launch is directed through the designated optimal gateway Gateway2 for the farm Farm2.
      Set-DSOptimalGatewayForFarms -onDirectAccess=false
      

      Farm2 is configured to use the optimal gateway Gateway2.

      Farm2 has optimal gateway on direct access disabled.

      The optimal gateway Gateway2 will be used for the launch.

    • Internal client logs on using StoreFront. Launch is directed through the designated optimal gateway Gateway1 for the farm Farm1.
      Set-DSOptimalGatewayForFarms -onDirectAccess=true
      

      No dynamically identified gateway in request. StoreFront was contacted directly.

      Farm1 is configured to use the optimal gateway Gateway1.

      Farm1 has optimal gateway on direct access enabled.

      The optimal gateway Gateway1 will be used for the launch.

    • Internal client logs on using Gateway1. Launches of resources on Farm1 are prevented from passing through any gateway and StoreFront is contacted directly.
      Set-DSFarmsWithNullOptimalGateway
      

      Dynamically identified gateway in request: Gateway1

      Farm1 is configured to not use a gateway. No gateway will be used for launch.

To configure a store for NetScaler Gateway global server load balancing

Important: In multiple server deployments, use only one server at a time to make changes to the configuration of the server group. Ensure that the Citrix StoreFront management console is not running on any of the other servers in the deployment. Once complete, propagate your configuration changes to the server group so that the other servers in the deployment are updated.
  1. Use the Enable Remote Access task to configure the store with details of your load-balanced NetScaler Gateway deployment. For more information, see Manage remote access to stores through NetScaler Gateway.
  2. When prompted for the NetScaler Gateway URL, enter the load-balanced URL for the deployment. For the subnet IP address, specify the virtual server IP address for one of the appliances in your deployment.
  3. Repeat the process using exactly the same settings except for the display name and the subnet IP address. For the subnet IP address, enter the virtual server IP address for another appliance in your deployment.
  4. Continue until you have added entries for all the appliances in your load-balanced NetScaler Gateway deployment. Each entry should be identical except for the display name and the subnet IP address.