Configuring Session Persistence

Session persistence is configured via the Catalog. Session Persistence Classes are added to the catalog, and can then be assigned to a pool, or selected in a TrafficScript rule.

When TrafficScript is not being used, Session Persistence is enabled on a per-pool basis. You can define multiple pools, and enable session persistence only for those that require it. Note that a back-end server can be in more than one pool.

Several pools can refer to the same session persistence class to share session persistence mappings. For example, a pool containing some HTTP nodes (on port 80) and a pool containing the same nodes running HTTPS services (on port 443) can share the session persistence mappings for users to the services.

When TrafficScript is being used, Session persistence can be overridden with a TrafficScript command. The Traffic Manager will use the Session Persistence Class specified for the pool which handles the request unless this command is used.

Enabling Session Persistence

To view and edit Session Persistence classes, click Catalogs > Persistence. To create a new class, type a name in the box labeled “Create new Session Persistence class” and click Create Class.

The Admin UI now shows a summary of the settings for your new Session Persistence Class.

Selecting a Persistence Method

By default, new Session Persistence Classes are configured with “IP-based Persistence” selected. The following alternatives are available when session persistence is required:

Method	Applicable Protocols	Description
IP-based persistence	All	Send all requests originating from the same source IP address (or optional subnet range) to the same node.
Universal session persistence	All	This class allows you to persist sessions based on any information in a request by setting a unique persistence key in a TrafficScript rule.
Named Node persistence	All	With this method, a TrafficScript rule can direct the connection to a specific node.
Transparent session affinity	HTTP, HTTPS	Insert cookies into the response to track sessions.
Monitor application cookies	HTTP, HTTPS	Monitor a specified application cookie to identify sessions.
J2EE	HTTP, HTTPS	Monitor Java's JSESSIONID cookie and its URL-rewriting fallback.
ASP and ASP.net	HTTP, HTTPS	This method allows both types of ASP sessions to be processed using session persistence.
X-Zeus-Backend cookies	HTTP, HTTPS	Inspect an application cookie named “X-Zeus-Backend”, which names the destination node.
SSL Session ID persistence	SSL protocols	Use the SSL Session ID to identify sessions.

IP-Based Persistence

When IP-based persistence is selected, the Traffic Manager tracks and stores the originating IP address for each request to this pool. When the Traffic Manager receives further traffic from the same IP address, it uses the stored session map information to send requests to the back-end server node it used previously.

You can optionally specify an IPv4 or IPv6 subnet prefix length to ensure requests from the same IP subnet are sent to the same node. This can help to limit the size of the IP session maps maintained by your Traffic Manager cluster.

Some specialized mobile clients might change their IP address during a session, and some clients might share IP addresses (for example, through a proxy server), so this persistence type might not be suitable for some environments.

However, since IP-based persistence is completely transparent and is not protocol-dependent, it is useful for guaranteeing persistent connections for difficult protocols or applications.

IP session maps are shared by all Traffic Manager instances in a cluster. Requests received by different Traffic Managers are directed to the correct node, and if one Traffic Manager fails, the other Traffic Managers are aware of the IP session maps it was maintaining.

Universal Persistence

Universal session persistence uses a persistence key, defined in a TrafficScript rule, and seeks to direct all connections with the same persistence key to the same back-end node.

The persistence key is specified in a rule by the connection.setPersistenceKey() TrafficScript function. This allows persistent sessions based on any information in a request; see Universal PHP Persistence for an example.

Universal session persistence maps are shared by all Traffic Manager machines in a cluster. Requests received by different Traffic Manager machines will be directed to the correct node, and if one Traffic Manager fails, the other Traffic Managers are aware of the universal session maps it was maintaining.

ATTENTION
Note that when using Universal Session Persistence with the SIP protocol over UDP, session persistence will only be applied to the first request sent by a client. All subsequent requests from the same client will be sent to the same node as the first request, even if they have been assigned a different session persistence key. Universal Session Persistence should therefore be used with SIP only when you want all requests from the same client to be directed to the same server.

Named Node Persistence

Named Node session persistence can be used to direct the connection to a specific node in a pool. It gives very fine-grained control over how requests are routed.

A TrafficScript rule can use the connection.setPersistenceNode() function to specify precisely which node should be used in the session persistence decision. For example, when a new connection for a Remote Desktop service is received, a rule could query an external database to determine the node which hosts that user’s desktop, and then use the connection.setPersistenceNode() function to direct the connection to that node.

Transparent Session Affinity

Transparent session affinity inserts cookies into the HTTP response to track sessions. This is generally the most appropriate method for HTTP and SSL-decrypted HTTPS traffic as it does not require the nodes to set any cookies in their response.

Transparent session maps are stored in a client-side cookie named "X-Mapping-xxxxxx", where "xxxxxx" is a unique identifier. All Traffic Managers in a cluster inspect the value of this session cookie and send the session to the same server node.

By default, the session cookie is inserted only if the corresponding request does not already contain a matching cookie. To force the Traffic Manager to insert the session cookie into every response sent to the client, enable "Set the cookie in every response". By including the session cookie with every response to the client, a TrafficScript response rule can then examine or modify the session cookie or any directives it might have.

To set HTTP cookie directives that the Traffic Manager should include with the session cookie, use the "Directives to include in the cookie" setting. For example, by adding the directive "Secure", most clients include the session cookie only with requests that are sent over a secure (HTTPS) connection. This allows a user to keep the use of the "X-Mapping-" session cookie out of sight from third parties who might see the contents of any insecure connection to the same destination.

To add more than one directive, use a semi-colon separator. For example, if both the "Secure" and "Max-Age" directives are used, specify the directive list as "Secure; Max-Age=3600".

Monitor Application Cookies

Application cookie persistence monitors a named cookie in the HTTP response from the node. For example, PHP applications may generate session cookies named “PHPSESSID” that the clustered PHP application could track and index session state. This persistence method directs a request to the same server node if it contains an application cookie. You need to specify the name of the application cookie you wish to monitor.

Application cookie session maps are stored in a client-side cookie “K-CookieName-xxxxxx”, where “CookieName” is the name of the monitored cookie, “xxxxxx” is an opaque string that identifies the session persistence class, and the value of the cookie is an opaque string that identifies the preferred node. All Traffic Manager machines in a cluster will inspect the value of this session cookie and send the session to the same server node.

If the back-end server changes the value of the application cookie, the session is still valid and clients will continue to be directed to the same server node.

J2EE JSESSIONID Cookies/URL

J2EE JSESSIONID cookies/URL persistence monitors both the JSESSIONID cookie (as for application cookie persistence) and the jsessionid path parameter. These are defined in the Java extension specification (v2.4) and are used by Java extension containers such as BEA WebLogic, IBM WebSphere Application Server, JBoss/Tomcat and others.

J2EE session maps are shared by all Traffic Manager machines in a cluster, so requests received by different Traffic Manager machines will apply the same sessions.

ASP.net Session Persistence

ASP (Active Server Pages) is a server-side scripting protocol created by Microsoft to handle dynamically generated Web pages. In order to use ASP Session management in a server cluster, the same Web server must handle all requests coming from a user for the life of the session.

ASP sessions can use cookies or can be cookieless, depending on numerous factors, such as the lack of support of cookies by the browser or the user disabling them voluntarily.

•For cookie-based sessions: The Traffic Manager’s ASP Session Persistence class detects and uses the cookie to identify the client's session.

•For cookieless sessions: The Traffic Manager’s ASP Session Persistence class detects and uses the ASP identifier embedded in URLs generated by the ASP application.

ASP session maps are shared by all Traffic Manager machines in a cluster, so requests received by different Traffic Manager machines will apply the same sessions.

Note that if you have several distinct ASP applications hosted behind a single hostname, each application will generate its own cookie. You will need to have a separate ASP.Net session persistence class for each application so that mappings between cookies and nodes are managed independently for each application. For example, you may inspect the request URL to determine which application is being accessed and select the session persistence class using the TrafficScript function connection.setPersistence().

X-Zeus-Backend Cookies

X-Zeus-Backend cookie persistence looks for a cookie named X-Zeus-Backend in each application request. If the cookie is present, and contains the name of a node in the current pool, the request is sent to that node. The cookie can be inserted either by a back-end server or by a TrafficScript rule.

This persistence method is deprecated, and provided only for backward compatibility with Zeus Load Balancer persistence cookies.

SSL Session ID Persistence (SSL Pass-Through Only)

The SSL session ID persistence method sends all SSL traffic with the same SSL session ID to the same server node. It is only applicable to SSL pass-through traffic, not SSL-decrypted traffic.

Connections using the TLSv1.3 protocol do not use session IDs for session resumption, therefore this method does not apply in that case.

SSL handshakes are expensive in terms of CPU time, network bandwidth, and latency. The SSL session ID persistence method reduces the number of SSL handshake operations your nodes perform by ensuring that a resumed connection is directed to the node that created (and stored) the session.

SSL Session ID session maps are shared by all Traffic Manager machines in a cluster. Requests received by different Traffic Manager machines will be directed to the correct node, and if one Traffic Manager fails, the other Traffic Managers are aware of the SSL Session ID session maps it was maintaining.

SSL session ID persistence is not appropriate for application-level session persistence because many SSL clients regularly renegotiate their SSL session ID. To achieve application-level session persistence you should either use IP-based session persistence, or decrypt the traffic and use universal session persistence or an HTTP method if applicable.

Resolving Session Persistence Maps to Nodes

When the Traffic Manager receives a new connection and there is no session persistence information, the Traffic Manager uses its load balancing logic to choose a node for that connection. The chosen node (IP address and port) is recorded in the session persistence mapping, which is either internal (in the case of IP, Universal or SSL session persistence) or in an external cookie (Transparent, Application cookie or X-Zeus-Backend cookie).

When another connection in that session is received and the Traffic Manager is ready to forward that connection to a node in a pool, the Traffic Manager inspects the session persistence class in use to determine if a particular node should be used.

If a node with the same IP address and port exists in the pool for the connection, then the Traffic Manager sends the connection to that node.

If there is not an exact match, the Traffic Manager searches the pool for any nodes with the same IP address (but different ports). If just one such node exists, the Traffic Manager sends the connection to that node.

This allows session persistence information to be shared between different pools with different nodes types.

For example, a Web-based application may use an HTTP interface to manage items in a shopping cart, and a secure HTTPS interface to manage payment. Session persistence requirements may dictate that users must be directed to the same physical machine for both HTTP and HTTPS traffic.

Both services (HTTP and HTTPS) could reference the same session persistence class. When a user first connects to the HTTP service, the Traffic Manager would use the HTTP pool. A session would be established with a particular node (IP address, port 80) in that pool.

When the user accesses the HTTPS service, the Traffic Manager might use a different pool containing HTTPS nodes. The session persistence class will then direct the request to the same physical machine (IP address, port 443) in the HTTPS pool.

Node Failure Options

Sometimes, the node required by the session persistence mapping might not be available. For example, it might be marked as “failed” by a monitor, or the Traffic Manager might be unable to connect to it.

The Traffic Manager provides alternative actions for sessions currently using that node. Use the failuremode setting to select one of the following actions:

Action	Description
Choose a new node to use	The pool discards the session map and chooses a new node, using the current load-balancing algorithm.
Redirect the user to a given URL...	The pool sends an HTTP 302 redirect to the configured location (the URL setting) as a response to the request. The resource at the redirect location could display a message, or cause the user to log in again and establish a new session.
Close the connection	The pool immediately closes the connection.

If you select “Redirect the user to a given URL...” or “Close the connection”, use the delete setting to choose whether to discard or retain the session map. If you set delete to “No” (to retain the session map), where the client returns and the session's node is available again, the Traffic Manager sends the request to the same node.

If you select “Choose a new node to use”, the Traffic Manager implicitly deletes the session map.

Draining Connections

Sometimes it is necessary to take a back-end server out of service; for example, to upgrade software, perform hardware maintenance or to decommission or repurpose it.

A pool’s “Connection Draining” capability is designed to facilitate this. When you mark a node as “draining”, the Traffic Manager stops sending it any new connections. However, any connections that are in a session previously established to that node are still sent to that node.

This allows you to safely remove a node from a pool without interrupting either ongoing connections, or longer-term established sessions. Use the Activity section of the Admin UI to obtain details of how long a draining node has been idle, and then make a judgment as to whether all sessions have completed.

For example, suppose you have an e-commerce service and you use session persistence to tie individuals’ sessions to particular back-end nodes. You mark one of your nodes as draining.

No new sessions are established with that node.

Existing, established sessions are allowed to continue with that node.

After 60 minutes, you inspect the Activity > Draining Nodes page in the Admin UI. You observe that the node has been idle for 35 minutes. It is most likely safe to conclude that all established sessions have now completed, and you can remove the node safely.

In practice, the time periods involved in determining whether a node has finished draining will be very much dependent on the application and user behavior. In setting up the system, an administrator will have to decide these values in relation to the desired use.

To learn more about how to configure connection draining, see Draining, Disabling, or Removing a Node.

Configuring Session Persistence Caches

Some session persistence methods use client-side cookies to store the session persistence data. The remaining session persistence methods use caches in the Traffic Manager, shared automatically across a cluster, to store session persistence mapping.

For each persistence method that uses a cache, you can configure the maximum number of map entries each cache can hold. Additionally, for certain methods, you can configure the expiry time for each session map entry.

Setting an expiry time on cached session maps can help to redistribute load between pool nodes when new nodes are added, or when nodes recover from a failure. This is especially true in enterprise environments where the set of clients might be fixed. Configuring a session cache with a limited lifespan can also help when placing your nodes into a draining state. For further information on draining, see Draining, Disabling, or Removing a Node.

The Traffic Manager does not actively delete cache entries when they reach the defined expiry time. Instead, the cache entry time is checked against the expiry value only when the entry is looked up. If the session is still current, the Traffic Manager returns the session and resets the cache entry time for that session mapping. If the session is deemed expired, the Traffic Manager deletes it from the cache and establishes a new session.

When a cache fills up faster than the Traffic Manager is able to remove expired session entries, the Traffic Manager discards the oldest (least recently used) entry when a new entry is added.

To configure persistence method caches, click System > Global Settings > Cache Settings. The following table shows the persistence class types, the corresponding cache size setting, and (if applicable) the corresponding expiry setting:

Persistence Type	Cache Size Setting (number of entries)	Cache Expiry Setting (lifespan in seconds)
IP session persistence	ip_cache_size	ip_cache_expiry
Universal session persistence	universal_cache_size	universal_cache_expiry
SSL session-id session persistence	ssl_cache_size	(not applicable)
J2EE session persistence	j2ee_cache_size	j2ee_cache_expiry
ASP session persistence	asp_cache_size	(not applicable)

ATTENTION
Cache size and expiry settings are global - the value you set applies equally to all Session Persistence class instances you create for a particular persistence method.

To monitor the behavior of the caches, plot session persistence cache data values in the Activity Monitor. First, click Activity to use the Activity Monitor. Next, click Change Data and expand the Cache Values section in the "Values to monitor" tree. This section contains a sub-tree of persistence cache types. Select/expand the persistence type you want to monitor from the list, and tick the relevant data items to add to the graph. To plot the selected values, click Apply.

Key values to help you monitor and size the cache appropriately are shown in the following table:

Setting	Description
Entries	The number of entries in the cache
EntriesMax	The configured maximum size of the cache
Oldest	The time since the least recently used entry was last used

After the Traffic Manager has processed a number of sessions, it is normal for the cache to completely fill up. The Oldest value indicates how long entries are retained without being used or expired out of the cache.

To help you size your cache, you need to consider the rate at which new entries are added to your cache (entries per second) and the length of time (in seconds) that you want these entries to be retained since they were last used. Multiply these two values together to get an estimate of the required cache size, and monitor the Oldest value to check that entries are not prematurely discarded because the cache has filled.

If you need fine-grained control of session persistence records, the most effective means is to use client-side cookies with specific expiry times, and tie the session persistence to the presence of the cookie.

Using Session Persistence with Multi-Hosted Traffic IP Addresses

If you use multi-hosted Traffic IP Addresses with the ‘consider source port’ setting enabled, then requests from one source IP address (i.e. from a client) will be handled by all of the Traffic Managers in your cluster (see Creating a Traffic IP Group).

In this situation, session persistence methods that rely on state sharing (session maps are shared between the Traffic Managers) may not work reliably. There is a short delay before session information is propagated across the cluster, and clients may visit several Traffic Managers during this period, resulting in corruption of the client’s session persistence mapping.

Session persistence algorithms that depend on state sharing are:

•IP-based Session Persistence

•Universal Session Persistence

•SSL SessionID Session Persistence

•J2EE and ASP.NET Session Persistence

Do not use the consider source port setting in any multi-hosted Traffic IP addresses that are used by services that use any of the above session persistence methods.