Configure persistence based on user-defined rules

Last published : Sep 22, 2026
Warning:
The use of classic expressions for the persistence rule in the load balancing feature is removed and no longer available for the filter rule on the NetScaler appliance release 13.1 onwards. Citrix recommends that you do not use these policy expressions through the NetScaler command line interface, NetScaler GUI, or Nitro automation. For more information, see Table 1 and Table 2 in the Classic Policy Deprecation FAQ page.
When rule based persistence is configured, the NetScaler appliance creates a persistence session based on the contents of the matched rule before directing the request to the service selected by the configured load balancing method. Later, it directs all requests that match the rule to the same service. You can configure rule based persistence for services of type HTTP, SSL, RADIUS, ANY, TCP, and SSL_TCP.
Rule based persistence requires a classic or Advanced policy expression. You can use a classic expression to evaluate request headers, or you can use a Advanced policy expression to evaluate request headers, Web form data in a request, response headers, or response bodies. For example, you can use a classic expression to configure persistence based on the contents of the HTTP Host header. You can also use a Advanced policy expression to configure persistence based on application session information in a response cookie or custom header. For more information on creating and using classic and Advanced policy expressions, see Policies and Expressions.
The expressions that you can configure depend on the type of service for which you are configuring rule based persistence. For example, certain RADIUS-specific expressions are not allowed for protocols other than RADIUS, and TCP-option based expressions are not allowed for service types other than the ANY type. For TCP and SSL_TCP service types, you can use expressions that evaluate TCP/IP protocol data, Layer 2 data, TCP options, and TCP payloads.
Note: For a use case that involves configuring rule based persistence based on Financial Information eXchange ("FIX") Protocol data transmitted over TCP, see Configuring Rule Based Persistence Based on a Name-Value Pair in a TCP Byte Stream.
Rule based persistence can be used for maintaining persistence with entities such as Citrix SD-WAN™ appliances, Citrix SD-WAN plug-ins, cache servers, and application servers.
Note: On an ANY virtual server, you cannot configure rule-based persistence for the responses.
To configure persistence based on a user-defined rule, you first configure persistence as described in Configuring Persistence Types That Do Not Require a Rule, and set the persistence type to RULE. You can then perform the following procedures. You can configure rule based persistence by using the configuration utility or the CLI.

To configure persistence based on user-defined rules by using the CLI

At the command prompt, type:
set lb vserver <vserverName> [-rule <expression>][-resRule <expression>]
Example:
set lb vserver vsvr_name –rule http.req.header("cookie").value(0).typecast_nvlist_t('=',';').value("server")

set lb vserver vsvr_name –resrule http.res.header("set-cookie").value(0).typecast_nvlist_t('=',';').value("server")

To configure persistence based on user-defined rules by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and open the virtual server.
  2. In the Persistence section, choose the persistence type that meets your requirement. The most suitable persistence type for the virtual server is available as option buttons. Other persistence types that are applicable to the specific virtual server type can be selected from the Others list.
Note
Prior to NetScaler release 12.0 build 56.20, all persistence types are available in a single Persistence drop-down list without any option buttons.

Example: Classic Expression for a Request Payload

The following classic expression creates a persistence session based on the presence of a User-Agent HTTP header that contains the string, "MyBrowser", and directs any subsequent client requests that contain this header and string to the same server that was selected for the initial request.
http header User-Agent contains MyBrowser

Example: Advanced policy Expression for a Request Header

The following Advanced policy expression does the same thing as the previous classic expression.
HTTP.REQ.HEADER("User-Agent").CONTAINS ("MyBrowser")

Example: Advanced policy Expression for a Response Cookie

The following expression examines responses for "server" cookies, and then directs any requests that contain that cookie to the same server that was selected for the initial request.
HTTP.RES.HEADER("SET-COOKIE").VALUE(0).TYPECAST_NVLIST_T('=',';').VALUE("server")