Product Documentation

Choosing and Configuring Persistence Settings

Sep 04, 2013

You must configure persistence on a virtual server if you want to maintain the states of connections on the servers represented by that virtual server (for example, connections used in e-commerce). The appliance then uses the configured load balancing method for the initial selection of a server, but forwards to that same server all subsequent requests from the same client.

If persistence is configured, it overrides the load balancing methods once the server has been selected. If the configured persistence applies to a service that is down, the appliance uses the load balancing methods to select a new service, and the new service becomes persistent for subsequent requests from the client. If the selected service is in an Out Of Service state, it continues to serve the outstanding requests but does not accept new requests or connections. After the shutdown period elapses, the existing connections are closed. The following table lists the types of persistence that you can configure.

Table 1. Limitations on Number of Simultaneous Persistent Connections
Persistence Type Persistent Connections
Source IP, SSL Session ID, Rule, DESTIP, SRCIPDESTIP 250K
CookieInsert, URL passive, Custom Server ID Memory limit. In case of CookieInsert, if time out is not 0, any number of connections is allowed until limited by memory.

If the configured persistence cannot be maintained because of a lack of resources on an appliance, the load balancing methods are used for server selection. Persistence is maintained for a configured period of time, depending on the persistence type. Some persistence types are specific to certain virtual servers. The following table shows the relationship.

Table 2. Persistence Types Available for Each Type of Virtual Server
Persistence TypeHeader 1 HTTP HTTPS TCP UDP/IP SSL_Bridge
Source IP YES YES YES YES YES
CookieInsert YES YES NO NO NO
SSL Session ID NO YES NO NO YES
URL Passive YES YES NO NO NO
Custom Server ID YES YES NO NO NO
Rule YES YES NO NO NO
SRCIPDESTIP N/A N/A YES YES N/A
DESTIP N/A N/A YES YES N/A

You can also specify persistence for a group of virtual servers. When you enable persistence on the group, the client requests are directed to the same selected server regardless of which virtual server in the group receives the client request. When the configured time for persistence elapses, any virtual server in the group can be selected for incoming client requests.

Two commonly used persistence types are persistence based on cookies and persistence based on server IDs in URLs.

Configuring Persistence Based on Cookies

Updated: 2013-08-23

When you enable persistence based on cookies, the NetScaler adds an HTTP cookie into the Set-Cookie header field of the HTTP response. The cookie contains information about the service to which the HTTP requests must be sent. The client stores the cookie and includes it in all subsequent requests, and the NetScaler uses it to select the service for those requests. You can use this type of persistence on virtual servers of type HTTP or HTTPS.

The NetScaler inserts the cookie <NSC_XXXX>= <ServiceIP> <ServicePort>

where:

  • <NSC_XXXX> is the virtual server ID that is derived from the virtual server name.
  • <ServiceIP> is the hexadecimal value of the IP address of the service.
  • <ServicePort> is the hexadecimal value of the port of the service.

The NetScaler encrypts ServiceIP and ServicePort when it inserts a cookie, and decrypts them when it receives a cookie.

Note: If the client is not allowed to store the HTTP cookie, the subsequent requests do not have the HTTP cookie, and persistence is not honored.

By default, the NetScaler sends HTTP cookie version 0, in compliance with the Netscape specification. It can also send version 1, in compliance with RFC 2109.

You can configure a timeout value for persistence that is based on HTTP cookies. Note the following:

  • If HTTP cookie version 0 is used, the NetScaler inserts the absolute Coordinated Universal Time (GMT) of the cookie’s expiration (the expires attribute of the HTTP cookie), calculated as the sum of the current GMT time on a NetScaler, and the timeout value.
  • If an HTTP cookie version 1 is used, the NetScaler inserts a relative expiration time (Max-Age attribute of the HTTP cookie). In this case, the client software calculates the actual expiration time.
Note: Most client software currently installed (Microsoft Internet Explorer and Netscape browsers) understand HTTP cookie version 0; however, some HTTP proxies understand HTTP cookie version 1.

If you set the timeout value to 0, the NetScaler does not specify the expiration time, regardless of the HTTP cookie version used. The expiration time then depends on the client software, and such cookies are not valid if that software is shut down. This persistence type does not consume any system resources. Therefore, it can accommodate an unlimited number of persistent clients.

An administrator can use the procedure in the following table to change the HTTP cookie version.

To change the HTTP cookie version by using the configuration utility

  1. Navigate to System > Settings.
  2. In the details pane, click Change HTTP Parameters.
  3. In the Configure HTTP Parameters dialog box, under Cookie, select Version 0 or Version 1.
Note: For information about the parameters, see "Configuring Persistence Based on Cookies."

To configure persistence based on cookies by using the command line interface

At the command prompt, type the following commands to configure persistence based on cookies and verify the configuration:
  • set lb vserver <name> -persistenceType COOKIEINSERT
  • show lb vserver <name>

    Example

    > set lb vserver vserver-LB-1 -persistenceType COOKIEINSERT 
     Done 
    > show lb vserver vserver-LB-1 
        vserver-LB-1 (10.102.29.60:80) - HTTP   Type: ADDRESS 
        . 
        . 
        . 
        Persistence: COOKIEINSERT (version 0)   Persistence Timeout: 2 min 
        . 
        . 
        . 
     Done 
    >

To configure persistence based on cookies by using the configuration utility

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  2. In the details pane, select the virtual server for which you want to configure persistence (for example, vserver-LB-1), and then click Open.
  3. In the Configure Virtual Server (Load Balancing) dialog box, on the Method and Persistence tab, in the Persistence list, select COOKIEINSERT.
  4. In the Time-out (min) text box, type the time-out value (for example, 2).
  5. Click OK.
  6. Verify that the virtual server for which you configured persistence is correctly configured by selecting the virtual server and viewing the Details section at the bottom of the pane.

Configuring Persistence Based on Server IDs in URLs

Updated: 2013-08-23

The NetScaler can maintain persistence based on the server IDs in the URLs. In a technique called URL passive persistence, the NetScaler extracts the server ID from the server response and embeds it in the URL query of the client request. The server ID is an IP address and port specified as a hexadecimal number. The NetScaler extracts the server ID from subsequent client requests and uses it to select the server.

URL passive persistence requires configuring either a payload expression or a policy infrastructure expression specifying the location of the server ID in the client requests. For more information about expressions, see "Policy Configuration and Reference."

Note: If the server ID cannot be extracted from the client requests, server selection is based on the load balancing method.

Example: Payload Expression

The expression, URLQUERY contains sid= configures the system to extract the server ID from the URL query of a client request, after matching token sid=. Thus, a request with the URL http://www.citrix.com/index.asp?&sid;=c0a864100050 is directed to the server with the IP address10.102.29.10 and port 80.

The timeout value does not affect this type of persistence, which is maintained as long as the server ID can be extracted from the client requests. This persistence type does not consume any system resources, so it can accommodate an unlimited number of persistent clients.

Note: For information about the parameters, see "Load Balancing."

To configure persistence based on server IDs in URLs by using the command line interface

At the command prompt, type the following commands to configure persistence based on server IDs in URLs and verify the configuration:
  • set lb vserver <name> -persistenceType URLPASSIVE
  • show lb vserver <name>

    Example

    > set lb vserver vserver-LB-1 -persistenceType URLPASSIVE 
     Done 
    > show lb vserver vserver-LB-1 
        vserver-LB-1 (10.102.29.60:80) - HTTP   Type: ADDRESS 
        . 
        . 
        . 
        Persistence: URLPASSIVE Persistence Timeout: 2 min 
        . 
        . 
        . 
     Done 
    >

To configure persistence based on server IDs in URLs by using the configuration utility

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  2. In the details pane, select the virtual server for which you want to configure persistence (for example, vserver-LB-1), and then click Open.
  3. In the Configure Virtual Server (Load Balancing) dialog box, on the Method and Persistence tab, in the Persistence list, select URLPASSIVE.
  4. In the Time-out (min) text box, type the time-out value (for example, 2).
  5. In the Rule text box, enter a valid expression. Alternatively, click Configure next to the Rule text box and use the Create Expression dialog box to create an expression.
  6. Click OK.
  7. Verify that the virtual server for which you configured persistence is correctly configured by selecting the virtual server and viewing the Details section at the bottom of the pane.