Product Documentation

Configure optimal NetScaler Gateway routing for a store

Nov 30, 2015
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:

Example2 for nonstandard vServer port 500:

-Farms (String Array)

Specifies a set of (typically collocated) XenDesktop, XenApp, and VDI-in-a-Box 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"

-staUrls (String Array)

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

Example: "",""

-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.


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


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 "" `
                        -Farms "XenApp","XenDesktop" `
                        -StaUrls "",""  `
                        -StasUseLoadBalancing:$false `
                        -StasBypassDuration 00.02:00:00 `
                        -EnableSessionReliability:$false `
                        -UseTwoTickets:$false `


This script returns configured OptimalGatewayForFarms for the store called Internal.

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


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


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"


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.

      Dynamically identified gateway in request: Gateway1

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