matchclass

Description

Performs comparisons against the contents of data group. Typically used for conditional logic control.
Note: matchclass has been deprecated in v10 in favor of the new class commands. The class command offers better functionality and performance than matchclass.

Note that you should not use a $:: or :: prefix on the datagroup name when using the matchclass command (or in any datagroup reference on 9.4.4 or later). In v9.4.4 - 10, using $::datagroup_name will work but demote the virtual server from running on all TMMs. For details, see the CMP compatibility page. In v11, using $::datagroup_name will result in a TCL runtime error and reset being sent to the client!

Syntax

matchclass <data-group> <operator name> <value>


matchclass <value> <operator name> <data-group>

matchclass <data-group> <operator name> <value>

  • Compares each member of a data group with the specified value. Returns index of match if found, 0 if no match is found.

matchclass <value> <operator name> <data-group>

  • Compares the specified value with each member of a data group. Returns index of match if found, 0 if no match is found.

How the match is performed depends on the operator you use with the matchclass command. Consider the following…
For the equals operator, either form of the command will produce the same results. Both of the following examples will perform a full string comparison and return the index of the first data group item that is exactly “green”:
[matchclass my_data_group equals "green"]
[matchclass "green" equals my_data_group]

However, when using a partial comparison operator, such as contains, starts_with or ends_with, the order of comparison does matter. This example will return the index of the first row that has the string “green” anywhere in it:
[matchclass my_data_group contains "green"]

And this example will will return the index of the first row containing any of contiguous characters in the string “green” (g, r, e, n, gr, re, ee, en, gre, ree, een, gree, reen, and green will all match):
[matchclass "green" contains my_data_group]

Note: For v10 users: Classes (data groups) used to be accessible as a global TCL list. Starting in v10, accessing a data group as a global variable ($::class_name) simply returns the name of the data group and is no longer a TCL list. You should now use the “class” command for all data group access as matchclass/findclass have been deprecated in v10.
Note: The terms Data Group List and Class are synonymous when referring to matchclass. Data Group Lists are hashed tcl lists containing data for comparison with live traffic conditions. They may be created in the admin web interface under Local Traffic/iRules/Data Group Lists. See Examples below.
Note: The value of the matched item is NOT returned by matchclass. If you need to return a value for a specific match, the findclass command might be what you need. (Link below)

Examples

To redirect any request whose URI starts with any of the listed strings defined in the redirectURIs data group (class), first define the class (Local Traffic >> iRules >> Data Groups). This is how the object definition appears in the bigip.conf file:
class redirectURIs {
  /my/application/directory
  /another/appdir
  /yet/another
}

Now create a rule which references the class:
when HTTP_REQUEST {
  if { [matchclass [HTTP::uri] starts_with redirectURIs] } {
     HTTP::redirect "http://www.domain.com/unavailable.html"
 }
}

To send AOL-sourced connections to a specific pool. (Note: Use the “equals” operator for address comparison with matchclass):
when CLIENT_ACCEPTED {
  if { [matchclass [IP::remote_addr] equals aol] } {
     pool aol_pool
  } else {
     pool all_pool
 }
}

Use matchclass with the TCL “lindex” command to extract the value of the matched item. (Matchclass index starts at 1, while lindex uses a 0 based index, thus the expr {$var - 1} adjustment):
As noted above, use the class get command instead of matchclass and lindex for this example!
when HTTP_REQUEST {
  set idx [matchclass [HTTP::uri] contains color]
  if { -1 != $idx } {
    set val [lindex $::color [expr {$idx - 1}]]
    log local0. "Found match index = $idx; value = $val"
  } else {
    log local0. "Didn't find a match"
  }
}

As matchclass doesn’t support wildcards, you can use a foreach loop to go through the class, element by element. Use string compare as it supports glob style (wildcard) matching:
when RULE_INIT {
   # Create a test class (actually a list in this case).  This could also be defined as a class/datagroup.
   set ::test_class [list abcd abcde abcdef* abcdefg*]

   # Loop through the datagroup line by line.
   foreach element $::test_class {

      # Log the current line.
      log local0. "Current \$element: $element"

      # Compare the element against the string.
      # If the datagroup entry has a wildcard, it should be listed first in the string compare statement.
      if {[string match -nocase $element "ABCDEFG"]}{

         # Found a match, so log it and break out of the foreach loop.
         log local0. "Matched \$element: $element.  Exiting loop."
         break
      }
   }
}