Persistence settings

Last published : Sep 24, 2026
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.
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.
The * in the preceding table refers to the following:
250K sessions per core is the default per packet engine. To configure 1 million session entries per packet engine, run the following command:
set lb parameter -sessionsthreshold <1000000*number of PE>
For a 3 PE system, run the following command:
set lb parameter -sessionsthreshold 3000000
Table 1. Limitations on Number of Simultaneous Persistent Connections
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.
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
Table 2. Persistence Types Available for Each Type of Virtual Server
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.

Configure persistence based on cookies

When you enable persistence based on cookies, the NetScaler appliance 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 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 appliance inserts the cookie \&lt;NSC\_XXXX\>= \&lt;ServiceIP\> \&lt;ServicePort\> \&lt;expires\>
where:
  • <\&lt;NSC\_XXXX\> is the virtual server ID that is derived from the virtual server name.
  • <\&lt;ServiceIP\> is the hexadecimal value of the IP address of the service.
  • <\&lt;ServicePort\> is the hexadecimal value of the port of the service.
  • <\&lt;expires\> is the absolute expiration time for the cookie. The default value is 2 minutes
Once the specified date and time are reached, the client’s browser automatically deletes the cookie from its cache. If the client's subsequent requests do not include the cookie value, the back-end server is selected based on the configured load balancing method.
If the useEncryptedPersistenceCookie option is enabled, NetScaler encrypts ServiceIP and ServicePort using the SHA2 hash algorithm when it inserts a cookie and decrypts 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, 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, NetScaler inserts the absolute Coordinated Universal Time (UTC) of the cookie’s expiration (the expires attribute of the HTTP cookie), calculated as the sum of the current UTC time on NetScaler, and the timeout value.
  • If an HTTP cookie version 1 is used, 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, 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 change the HTTP cookie version.

To change the HTTP cookie version by using the CLI

At the command prompt, type;
set ns param [-cookieversion ( 0 | 1 )]
Example:
set ns param -cookieversion 1

To change the HTTP cookie version by using the GUI

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

To configure persistence based on cookies by using the CLI

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 GUI

  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.

Configure persistence based on server IDs in URLs

The NetScaler appliance can maintain persistence based on the server IDs in the URLs. In a technique called URL passive persistence, 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 the port specified as a hexadecimal number. 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 the token sid=. Thus, a request with the URL http://www.citrix.com/index.asp?&sid;=c0a864100050 is directed to the server with the IP address 10.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 CLI

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 GUI

  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.