Citrix ADC

Configure persistent connections

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. Persistence is useful for deployments that deal with e-commerce, such as shopping card usage, where the server needs to maintain the state of the connection to track the transaction. To maintain the state of connection, you must configure persistence on a virtual server. With persistence configured, the Citrix ADC appliance selects a data center to process a client request and forwards the IP address of the selected data center for all subsequent DNS requests. If the configured persistence applies to a site that is down, the Citrix ADC appliance uses a GSLB method to select a new site, and the new site becomes persistent for subsequent requests from the client.

The GSLB virtual server is responsible for DNS-based site persistence, and it controls the site persistence for a remote GSLB service. The Citrix ADC appliance supports persistence based on the source IP address or on HTTP cookies.

When you bring a physical service DOWN with a delay time, the physical service goes into the transition out of service (TROFS) state. Site persistence is supported as long as the service is in the 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.

Note: If connection proxy is specified as the site persistence method and if you also want to configure persistence of the physical servers, do not configure SOURCEIP persistence. When the connection is proxied, an IP address owned by the appliance is used, and not the actual IP address of the client. Configure methods such as cookie persistence or rule-based persistence on the load balancing virtual server.

Configure persistence based on source IP address

With source-IP persistence, when a DNS request is received at a data center, the Citrix ADC appliance first looks for an entry in the persistence table and, if an entry for the local DNS server exists and the server mentioned in the entry is configured, the IP address of that server is sent as the DNS response.

For the first request from a particular client, the Citrix ADC appliance selects the best GSLB site for the request and sends its IP address to the client. Since persistence is configured for the source IP address of the client, all subsequent requests by that client or another local DNS server in the same IP subnet are sent the IP address of the GSLB site that was selected for the first request.

For source-IP address based persistence, the same set of persistence identifiers must be configured on the GSLB virtual servers in all data centers. A persistence identifier is a number used by the data centers to identify a particular GSLB virtual server. A cookie transmits the persistence identifier, enabling the Citrix ADC appliance to identify the domain so that it can forward all appropriate requests to the same domain. When persistence is enabled, the persistence information is also exchanged as part of metrics exchange.

For the Citrix ADC appliance to support persistence across sites, persistence must be enabled on the GSLB virtual servers of all participating sites. When you use source IP address persistence on the network identifier, you must configure a subnet mask. For any domain, persistence takes precedence over any other configured GSLB method.

To configure persistence based on source IP address by using the command line interface

At the command prompt, type:

set gslb vserver <name> -persistenceType (SOURCEIP|NONE) -persistenceId <positive_integer> [-persistMask <netmask>] –[timeout <mins>]


set gslb vserver vserver-GSLB-1 -persistenceType SOURCEIP -persistenceId 23 -persistMask –timeout 2

To configure persistence based on source IP address by using the configuration utility

  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 persistence based on HTTP cookies

The Citrix ADC appliance provides persistence at the HTTP-request level by using connection proxy and HTTP redirect. With these persistence methods, the appliance uses an HTTP cookie (known as a “site cookie”) to reconnect the client to the same server. The appliance inserts the site cookie in the first HTTP response.

The site cookie contains information about the selected GSLB service on which the client has a persistent connection. The cookie expiration is based on the cookie timeout configured on the Citrix ADC 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.

When the Citrix ADC 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. The physical server in that GSLB site adds a site cookie to the HTTP header, and connection persistence is in effect.

If the DNS entry in the client cache expires, and then the client sends another DNS query and is directed to a different GSLB site, the new GSLB site uses the site cookie present in the client request header to implement persistence.

When the GSLB configuration at the new site uses connection-proxy persistence, the new site 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.


    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.

If the GSLB configuration uses HTTP redirect persistence, the new site redirects the request to the site that originally inserted the cookie.

Connection proxy persistence can be configured only for local services. However, connection proxy persistence must be enabled on both local and remote GSLB services that are configured for the GSLB virtual server.

Connection proxy occurs when the following conditions are satisfied:

  • Requests are sent from a domain participating in GSLB. The domain is obtained from the URL/Host header.
  • Requests are sent from a local GSLB service whose public IP address matches the public IP address of an active service bound to the GSLB virtual server.
  • 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.

If one of the conditions is not met, connection proxy does not occur, but a site cookie is added if the local GSLB service has connection proxy enabled AND:

  • No site cookie is supplied; OR,
  • The site cookie refers to an IP address that is not an active GSLB remote service; OR,
  • The cookie refers to the IP address of the virtual server on which the request is received.

The following are the limitations of using connection proxy site cookies:

  • Site cookies do not work for non-HTTP(S) protocols.
  • If an HTTP request is sent to a back-up virtual server, the virtual server does not add a cookie.
  • Site cookies do not work if SSL client authentication is required.
  • At the local site, the statistics for a GSLB service on a remote site are not the same as the statistics recorded for that service at the remote site. At the local site, the statistics for a remote GSLB service are slightly higher than the statistics that the remote site records for that same service.

Redirect persistence can be used only:

  • For HTTP or HTTPS protocols.
  • If the domain name is present in the request (either in the URL or in the HOST header), and the domain is a GSLB domain.
  • When the request is received on a backup VIP or a GSLB local service that is in the down state.


In a GSLB parent-child configuration, connection proxy works as intended even when a GSLB service is not configured on a child site. However, if you have additional 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 command line interface

At the command prompt, type:

set gslb service <serviceName> -sitePersistence (ConnectionProxy [-sitePrefix <prefix>] | HTTPredirect -sitePrefix <prefix>)


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 configuration utility

  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.

Configure persistent connections