How to configure persistence in GSLB

Last published : Sep 22, 2026
Persistence ensures that a series of client requests for a particular domain name is sent to the same data center instead of being load balanced. If persistence is configured for a particular domain, it takes precedence over the configured GSLB method. You can use persistence for deployments where an information related to a client transaction is stored locally on an instance, which has served the initial requests. For example, the deployments for e-commerce that uses a shopping cart, where the server needs to maintain the state of the connection to track the transaction. The NetScaler appliance selects a data center to process a client request. With persistence enabled, it forwards the same IP address of the selected data center for all subsequent Domain Name System (DNS) requests. If a persistence session points to a data center that is DOWN, the NetScaler appliance uses the configured GSLB method to select a new data center. It then becomes persistent for subsequent requests from the client. For persistence in GSLB, the same set of persistence identifiers (persistID) must be configured on the GSLB virtual servers in all data centers. The GSLB module uses the persistence identifier to uniquely identify a GSLB virtual server. When Source IP persistence is enabled on the GSLB virtual server, the persistence sessions are also exchanged as part of the metrics exchange. For the NetScaler appliance to support persistence across sites, persistence related configuration must be done on all the participating GSLB sites. Citrix recommends persistence in GSLB for stateful applications, which requires clients to reconnect to the same application instance for the subsequent requests.
You can achieve persistence in GSLB by the following ways:
  • Persistence on GSLB virtual server
  • Site persistence on GSLB services
Related information

Persistence on GSLB virtual server

Persistence on GSLB virtual server is used during the DNS requests. The Source IP address of the DNS request is used to create persistence session between the client and the data center. DNS clients are generally the Local DNS (LDNS) or DNS gateways proxying a set of clients sitting behind them (in ISPs). Persistence on a GSLB virtual server is application protocol agnostic. In general, multiple DNS gateways or Local Domain Name Servers (LDNS) are configured in the client network. Citrix® recommends you to configure an appropriate persistence mask because for the subsequent DNS requests, irrespective of the upstream LDNS devices used to connect to the ADC appliance, the client is able to persist to the same data center, which had served the earlier requests. After the persistence session is created for an LDNS IP address, all the end clients connecting using that LDNS are given the same data center IP address.

Site persistence on GSLB services

Site persistence becomes effective while processing the application requests. Site persistence works only for HTTP and HTTPS traffic because the persistency is achieved using HTTP cookie. As cookies are maintained on HTTP clients (browsers), it gives visibility into the clients sitting behind the DNS gateways. When you use cookies to achieve persistency for clients, no resources are consumed on the ADC appliance for each incoming client. When you bring a GSLB service DOWN with a delay time, the service goes into the transition to out of service (TROFS) state. Persistence is supported as long as the service is in the UP or TROFS state. That is, if the same client sends a request for the same service within the specified delay time after a service is marked TROFS, the same GSLB site (data center) services the request.
If you access an application through an alias, ensure that the CNAME record is also configured on the NetScaler appliance. In a parent-child topology, site persistence does not work when you access an application through an alias.
Note
If the connection proxy is specified as the site persistence method and you also want to configure persistence on LB virtual servers, source IP persistence is not recommended. When the connection is proxied, an IP address owned by the ADC appliance is used, and not the actual IP address of the client. Configure an appropriate persistence, which does not use source IP of the HTTP(S) request to identify the client, for example, cookie persistence or rule-based persistence.

Configure persistence based on source IP address

If source IP persistence is configured on GSLB virtual server, persistence sessions are created for the source IP address of the DNS request. Depending on the Extended Client Subnet (ECS) feature, the source IP address of the DNS request is taken from any of the following:
Persistence sessions for a client last until the persistence timeout. After the timeout period expires, existing persistence sessions are cleared. For subsequent requests, a new GSLB decision is made and a different GSLB service IP address might be selected. The source IP persistence on GSLB virtual server and site persistence on GSLB service complements each other. If source IP persistence is disabled on GSLB virtual server, the GSLB virtual server chooses a different GSLB service each time the DNS tries to do the resolution. The client also connects to a different GSLB service and the data center which receives the application request proxy the connection to the data center which served the client first. This might add some latency. So by enabling source IP persistence on GSLB virtual server can avoid frequent such multiple hops for application requests. If the source IP persistence session has expired and the client reconnects after that, the site persistence connects the client back to the data center, which had served the client initially. Also, if the client connects back through a DNS gateway, which does not fall within the persistence mask range configured, then as well site persistence helps clients stick to the data center that served the first request.

To configure persistence based on source IP address by using the CLI

At the command prompt, type:
set gslb vserver <name> -persistenceType (SOURCEIP|NONE) -persistenceId <positive_integer> [-persistMask <netmask>] –[timeout <mins>]
Example:
set gslb vserver vserver-GSLB-1 -persistenceType SOURCEIP -persistenceId 23 -persistMask 255.255.255.255 –timeout 2

To configure persistence based on source IP address by using the GUI

  1. Navigate to Traffic Management > GSLB > Virtual Servers and double-click the GSLB virtual server whose method you want to change (for example, vserver-GSLB-1).
  2. Click the Persistence section and, from the Persistence drop-down list, select SOURCEIP and set the following parameters:
    • Persistence Id—persistenceID
    • Time-out—timeout
    • IPv4 Netmask or IPv6 Mask length—persistMask

Configure site persistence based on HTTP cookies

Site persistence is achieved using HTTP cookies (known as a “site cookie”) to reconnect the client to the same server. When the GSLB appliance responds to a client DNS request by sending the IP address of the selected GSLB site, the client sends an HTTP request to that GSLB site. Application endpoint in that GSLB site adds a site cookie to the HTTP header, and site persistence is in effect. If the client sends a DNS query after the client cache is expired, the DNS request might be directed to a different GSLB site. The new GSLB site uses the site cookie present in the client request header to implement persistence. Site persistence feature becomes active under the following conditions:
  • When the domain name in the host header matches one of the GSLB domains
  • When site persistence is enabled on the GSLB service that represents the virtual server receiving the application traffic.
The site cookie contains information about the selected GSLB service on which the client has a persistent connection. If the GSLB service pointed by the cookie is DOWN or removed from the GLSB configuration, then the virtual server that receives the traffic continues to process the traffic. The cookie expiration is based on the cookie timeout configured on the NetScaler appliance. If the virtual server names are not identical on all the sites, you must use the persistence identifier. Cookies inserted are compliant with RFC 2109.
NetScaler supports two types of site persistence:
  • Connection Proxy
  • HTTP redirect

Connection Proxy

In the Connection Proxy mode of site persistence, the data center that receives the subsequent application request performs the following tasks to establish a connection:
  1. Creates a connection to the GSLB site that inserted the site cookie.
  2. Proxies the client request to the original site.
    Note:
    The proxy server establishes connection with the original site using the following details:
    • The SNIP of the new site is the source IP address.
    • The GSLB service public IP address of the original site is the destination IP address.
    • An ephemeral port is the source port and GSLB service port is the destination port.
    • Uses either HTTP or HTTPS protocols depending on the GSLB service type.
  3. Receives a response from the original GSLB site.
  4. Relays that response back to the client.
  5. Closes the connection.

HTTP redirect

If the GSLB configuration uses HTTP redirect persistence, the new site redirects the request to the site that originally inserted the cookie. Domain name in the redirect URL is the site domain. Ensure that both cookies and SSL certificates are applicable to both GSLB domain and site domain. To apply cookies for both GSLB and site domain, the cookie domain must be the site to GSLB domain. To apply SSL certificates to both GSLB and site domain, certificate bound to the SSL virtual server must be a wildcard certificate.
Connection proxy occurs when the following conditions are satisfied:
  • Requests are sent for a domain participating in GSLB. The domain is obtained from the URL/Host header.
  • The local GSLB service has connection proxy enabled.
  • The request includes a valid cookie that contains the IP address of an active remote GSLB service.
Note
In a GSLB parent-child configuration, the connection proxy works as intended even when a GSLB service is not configured on a child site. However, if you have extra configuration such as client authentication, client IP address insertion, or other SSL-specific requirement, you must add an explicit GSLB service on the site and configure it accordingly.
For more information about parent-child topology, see Parent-Child Topology Deployment Using the MEP Protocol.

To set persistence based on HTTP cookies by using the CLI

At the command prompt, type:
set gslb service <serviceName> -sitePersistence (ConnectionProxy [-sitePrefix <prefix>] | HTTPredirect -sitePrefix <prefix>)
Example:
set gslb service service-GSLB-1 -sitePersistence ConnectionProxy
set gslb service service-GSLB-1 -sitePersistence HTTPRedirect -sitePrefix vserver-GSLB-1

To set persistence based on cookies by using the GUI

  1. Navigate to Traffic Management > GSLB > Services and select the service that you want to configure for site persistence (for example, service-GSLB-1).
  2. Click the Site Persistence section and set persistence based on cookies.