Wiki: iRules API


Causes the system to use the named persistence type to persist the connection. Also allows direct inspection and manipulation of the persistence table.


Note: Items marked with <item> are meant to be replaced with a value. Arguments bracketed by [ ] are used to note they are optional. They should not be confused with Tcl command evaluation.

persist simple [<mask>] [<timeout>]        
persist source_addr [<mask>] [<timeout>]        
persist sticky [<mask>] [<timeout>]        
persist dest_addr [<mask>] [<timeout>]        
persist ssl [<timeout>]        
persist msrdp [<timeout>] 
persist cookie [insert [<cookie_name>] [<expiration>] |
                rewrite [<cookie_name>] [<expiration>] |
                passive [<cookie_name>] |
                hash <cookie_name> [ {<offset> [<length>]} [<timeout>]] ]
persist uie <string> [<timeout>]        
persist hash <string> [<timeout>]
persist carp <string>
persist none

  <timeout> = The timeout in seconds.

These permutations are used to manipulate the persistence table directly:

persist add <mode> <key> [<timeout>]
   <key> = <mode specific value> | { <value> [any virtual|service|pool] [pool <name>] }        
     the latter key specification is used to add persistence entries that can be used across virtuals, services, or pools. 

persist lookup <mode> <key> [all|node|port|pool]  
  "all" or no specification returns a list containing the node, port and pool name.  
  Specifying any of the other return types will return the specified item only.       
   <key> = <mode specific value> | { <value> [any virtual|service|pool] [pool <name>] }        
     the latter key specification is used to access persistence entries across virtuals, services, or pools.
persist delete <mode> <key>        
   <mode> = simple | source_addr | sticky | dest_addr | ssl | uie | hash        
   <key> = <mode specific value> | { <value> [any virtual|service|pool] [pool <name>] }        
     the latter key specification is used to delete persistence entries regardless of virtual, service, or pool association.

Note: When using the latter key specification above (e.g. = { any virtual }), the persist command expects the key (the data and associated "any virtual" commands) to be a single argument; in other words, a list. Often, users will want to specify some variable data in such a command. However, the usual way of creating a list (via braces, as shown above) will inhibit variable and command expansion. See iRules Optimization 101 - #4 - Delimiters: Braces, Brackets, Quotes and more (linked in Related Info section below) for more information on this. To use variables and commands with these key specifications, users should either use the list command to construct a list, or use double quotes, which Tcl will interpret as a list. See the last two examples below.

Note: 'persist none' disables persistence (whether enabled via profile or iRule) until the current connection is closed or another persist iRule command is used.

Note: The following persistence methods require a corresponding persistence profile be added to the virtual server: ssl, msrdp, cookie


   # Persist the client connection based on the SSL session ID
    persist ssl

   # Look up the UIE persistence record for 11111111
   persist lookup uie {11111111 pool pool_1}


   # Look up the client IP in UIE persistence records for any virtual server
   set lookup_key [list [IP::client_addr] any virtual]
   set value [persist lookup uie $lookup_key]

   # Save the value of the UIE persistence record for this client for any pool
   set value [persist lookup uie [IP::client_addr] any pool]

   # Save the value of the UIE persistence record for a generic token for any virtual server
   set value [persist lookup uie [list $myVar any virtual]]

# Select different persistence methods by HTTP URI


   # Check the requested URI
   switch -glob [HTTP::uri] {
      "/path1/* -
      "/path2/* {
         # Request was for an IIS URI so select the pool and set a pool-specific cookie
         pool iis_pool
         persist cookie insert iis_persist 0
      default {
         # Request was for an iPlanet URI so select the pool and source address persistence with a /24 source mask
         pool iplanet_pool
         persist source_addr 0

Use CARP persistence to ensure connections between two hosts are hashed to the same firewall pool member in an LTM firewall sandwich regardless of which host initiates a connection.

	# Persist on the client and destination IP addresses
	# Use lsort to order them the same regardless of which host is originating the connection
	# Replace the space with an underscore so the persist command is given a single string
	persist carp [string map {" " "_"} [lsort "[IP::client_addr] [IP::local_addr]"]]

Related Information

Valid Events:

Sample Code:

Version Specific Notes
LTM 10.0 - 10.2.1 Changing an iRule assignment on a virtual server may cause TMM to panic. See AskF5 SOL11149 (ID 223883, formerly CR132598). Fixed in 10.2.2


When using the session or persist commands, one common error that occurs is "Prerequisite operation not in progress". The most common cause for this error is that there is no pool currently selected for the connection. Persistence and session entries by default are limited to a single pool. For most virtual servers, a default pool is specified in bigip.conf, and this pool will be used when persistence or session queries are made. Selecting a default pool to use is usually the best way to eliminate this error. If you cannot specify a default pool (for example, with a forwarding virtual), then you can specify that the operation should be across all pools using the any pool option described above.

Note that while the "carp" persistence method does not use the precise hash algorithm described in the Cache Array Routing Protocol draft specification, the effect is the same. See SOL11362 - Overview of the CARP hash algorithm for details.

Note that "persist uie" will not change the node of an established connection. To do so, first run LB::detach.

In 11.1.0 and later persist cannot be run in the context of a serverside event without wrapping it in a clientside command.