ltm rule command matchclass

iRule(1)		      BIG-IP TMSH Manual		      iRule(1)



matchclass
       Performs comparison against the contents of data group.

SYNOPSIS
       matchclass CLASS_OR_VALUE KEYWORDS VALUE_OR_CLASS

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   

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

       matchclass   

	    * 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)

RETURN VALUE
VALID DURING
       ANY_EVENT

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 thestring 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
	      }
	   }
	}

HINTS
SEE ALSO
CHANGE LOG
       @BIGIP-9.0.0 --First introduced the command.



BIG-IP				  2017-01-31			      iRule(1)