Wiki: iRules API

Description

The table command (like the session command) is a way to access the session table. The table command is a superset of the session command, with improved syntax for general purpose use. Please see the table command article series for detailed information on its use.

Session table entries are synched to the peer unit by default. This can be controlled by a database key, StateMirror.MirrorSessions. Ensure the Mirroring Address is configured under System ›› High Availability ›› Network Mirroring, and that the peer unit is reachable. In versions prior to 11.1, if the peer is not reachable, but session mirroring is enabled, TMM will leak memory and may crash. For details see SOL12370.

This command is not available to GTM.

If the table command is used on the standby system in an HA pair, the command will perform a no-op because the content of the standby unit's session db should be updated only through mirroring.

Note - numerical table data is stored as a string value and then converted implicitly and treated like a 64-bit unsigned long integer for arithmetic operations. This can cause unexpected results, but can be avoided by making sure the value is [0, 2^63-1] as TCL itself uses signed 64-bit integers.

Syntax

table set      [-notouch] [-subtable <name>] [-mustexist|-excl] <key> <value> [<timeout> [<lifetime>]]
table add      [-notouch] [-subtable <name>] <key> <value> [<timeout> [<lifetime>]]
table replace  [-notouch] [-subtable <name>] <key> <value> [<timeout> [<lifetime>]]
table lookup   [-notouch] [-subtable <name>] <key>
table incr     [-notouch] [-subtable <name>] [-mustexist] <key> [<delta>]
table append   [-notouch] [-subtable <name>] [-mustexist] <key>  <string>
table delete   [-subtable <name>] <key>|-all
table timeout  [-subtable <name>] [-remaining] <key>
table timeout  [-subtable <name>] <key> [<value>]
table lifetime [-subtable <name>] [-remaining] <key>
table lifetime [-subtable <name>] <key> [<value>]
table keys -subtable <name> [-count|-notouch]

table set

  • Sets a key/value pair in the session table or named subtable, with the specified timeout and lifetime.
  • Returns the entry's value after the set operation is complete.

  • If no timeout is specified, a default of 180 seconds will be used.
  • The timeout may be specified as "indefinite" or "indef", in which case the key/value will not be expired based on access times.
  • The timeout may be specified as 0, in which case an existing timeout will not be changed. A timeout specified as 0 for a new record will be set to the default of 180 seconds.

  • If no lifetime is specified, the default of indefinite will be used.
  • The lifetime may be specified as "indefinite" or "indef", in which case the key/value will not be expired based on life time.
  • The lifetime may be specified as 0, in which case an existing lifetime will not be changed. A lifetime specified as 0 for a new record will be set to the default of indefinite.
  •  Beware of bug ID 560098 when using "indef" as key word

  • If -notouch is specified any existing entry for the key will not have its timestamp updated.
  • If -mustexist is specified, and the key does not already exist, no action will be taken, and an empty string will be returned. Cannot be specified with -excl.
  • If -excl is specified, and the key already exists, the key will not be inserted, and the existing value will be returned. Cannot be specified with -mustexist.

To use a subtable or not to use a subtable for storing your session entries? The short answer is only use a subtable if you need to be able to count the number of keys or retrieve the keys in one command. Manipulating entries in subtables has higher overhead than manipulating an entry not in a subtable. Each subtable itself also takes up memory. All of the entries in a given subtable are on the same processor. So if you put all of your entries (or the vast majority of them) into the same subtable, then one CPU will take a disproportionate amount of memory and load. Which you probably don't want.

table add

  • Exactly the same as table set -excl

table replace

  • Exactly the same as table set -mustexist

table lookup

  • Looks up a value associated with the specified key, in the specified table (if any).
  • If -notouch is specified then any existing entry for the key will not have its timestamp updated.

table incr

  • Increments the value associated with the specified key, in the specified subtable (if any). If no delta is specified, a default value of 1 is used. If the key does not already exist, a default value of 0 will be used, and the entry will have a timeout of 180 seconds.
  • Returns the entry's value after the incr operation is complete.
  • If -notouch is specified then any existing entry for the key will not have its timestamp updated.
  • If -mustexist is specified, and the key does not already exist, then no action will be taken.

table append

  • Appends to the value associated with the specified key, in the specified subtable (if any). If the key does not already exist, a starting value of an empty string will be used, and the entry will have a timeout of 180 seconds.
  • Returns the entry's value after the append operation is complete.
  • If -notouch is specified then any existing entry for the key will not have its timestamp updated.
  • If -mustexist is specified, and the key does not already exist, then no action will be taken.

table delete

  • Deletes the key/value pair with specified key, in the specified subtable (if any).
  • If -all is specified in addition to a subtable name, all key/value pairs in the subtable are deleted.

table timeout

  • Returns, and optionally sets, the timeout of the specified key, in the specified subtable (if any).
  • If -remaining is specified, then the time remaining before timeout will be returned instead. If the key does not already exist, an empty string is returned.
  • Returns -1 if no timeout or an indefinite timeout was set for the specified key
  • Any existing entry for the key will not have its timestamp updated.

table lifetime

  • Returns, and optionally sets, the lifetime of the specified key, in the specified subtable (if any).
  • If -remaining is specified, then the time remaining before expiration will be returned instead. If the key does not already exist, an empty string is returned.
  • If -remaining is specified, then <value> is applied only if <value> is less than current lifetime
  • Returns -1 if no lifetime or an indefinite lifetime was set for the specified key
  • Any existing entry for the key will not have its timestamp updated.

Note: By setting a lifetime on an entry, you can have it expire after a certain period of time no matter how many changes or lookups are performed on it. An entry can have a lifetime and a timeout at the same time. It will expire (be removed from the table) whenever the timeout OR the lifetime expires, whichever comes first. For more info see the table article series - https://devcentral.f5.com/Default.aspx?tabid=63&amp;articleType=ArticleView&amp;articleId=2378

table keys

  • Returns a list of the keys in the specified subtable.
  • If -notouch is specified, then any existing entries will not have their timestamps updated.
  • If -count is specified, then a count of the keys in the specified subtable is returned and entries will not have their timestamps updated.

Examples


# Limit each client IP address to 20 concurrent connections
when CLIENT_ACCEPTED {

   # Check if the subtable has over 20 entries
   if { [table keys -subtable connlimit:[IP::client_addr] -count] >= 20 } {
      reject
   } else {

      # Add the client IP:port to the client IP-specific subtable 
      #   with a max lifetime of 180 seconds
      table set -subtable connlimit:[IP::client_addr] [TCP::client_port] "" 180
   }
}

when CLIENT_CLOSED {
   # When the client connection is closed, remove the table entry
   table delete -subtable connlimit:[IP::client_addr] [TCP::client_port]
}

Blacklist IPs for 10 minutes if they make more than 100 DNS queries per second:


when RULE_INIT {
    set static::maxquery 100
    set static::holdtime 600
}
when CLIENT_DATA {
    set srcip [IP::remote_addr]
    if { [table lookup -subtable "blacklist" $srcip] != "" } {
        drop
        return
    }
    set curtime [clock second]
    set key "count:$srcip:$curtime"
    set count [table incr $key]
    table lifetime $key 2
    if { $count > $static::maxquery } {
        table add -subtable "blacklist" $srcip "blocked" indef $static::holdtime
        table delete $key
        drop
        return
    }
}

Related Information

Valid Events:
ALL, except RULE_INIT
Sample Code:

Note: The total size of key+data for individual entries in the session table is limited to roughly 64KB.

Note: If there are a large number of entries in a given subtable (more than about 350, in current versions), then the "keys -count" command may return a count that is higher than the precise count. In practice, the difference is typically small or zero, so this limitation is usually negligible.

  • Introduced: BIGIP-10.1.0

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)