---

5

iRules

---

• Introducing iRules
• Creating rules
• Understanding rules syntax
• Using rules to select pools
• Using rules to redirect HTTP requests
• Configuring class lists
• Additional rule examples

Introducing iRules

iRules is a powerful and flexible feature that you can use to balance your network traffic. The iRules feature not only allows you to create rules and classes to select pools, but also to configure persistence scenarios that allow the BIG-IP system to search on any type of connection data that you define. Thus, the iRules feature significantly enhances your ability to customize your content-switching to suit your exact needs.

What is a rule?

An element of the iRules feature, a rule is a user-written script that chooses among two or more load balancing pools. In other words, a rule selects a pool associated with a virtual server. Rules are an optional feature that you can use if you do not want traffic to target the default pool defined for a virtual server. Rules allow you to more directly specify the pools to which you want traffic to be directed.

Once you have created a rule to select a pool, you can then configure that pool to further direct traffic to individual pool members, either to implement persistence or to meet your specific load balancing requirements. When configuring that pool, you can conveniently use the same expression syntax that you use for rules, to specify the expressions that your pool definition might require for persistence. For information on configuring pools, see Chapter 4, Pools .

When a packet arrives destined for a virtual server that does not match a current connection, the BIG-IP system can select a pool by evaluating a rule associated with a virtual server. The rule can direct traffic to a pool based on specific data such as IP packet headers, HTTP headers or TCP content. Thus, rules can be configured to ask true or false questions such as:

• Does the packet data contain an HTTP request with a URI ending in cgi?
• Does the source address of the packet begin with the octet 206?
• Does the TCP packet data contain the string ABC?

In addition to creating a rule to select a pool, you can also create a rule to redirect a client request to a specific host name, port number, or URI path.

Rules are made up of statements and expressions. Within those expressions, you can use many elements, such as functions, operands, literals, and operators. For descriptions of these elements, see Expressions .

A rule example

The rules you create can be simple or complex, depending on your content-switching needs. Figure 5.1 shows an example of a simple rule.

This simple rule sends .gif and .html content to pool cache_pool and all other content to pool server_pool.

Creating rules

You can create rules using either the Configuration utility or the bigpipe rule command. Each of these methods is described in this section.

To create a rule using the Configuration utility

1. In the navigation pane, click Rules.
   The Rules screen opens.
2. Click the Add button.
   The Add Rule screen opens.
3. In the Name box, type a 1- to 31-character name.
   
   
   • In the Type box, select either Rule Builder or Text Input.
     If you select Rule Builder, the BIG-IP system automatically creates a rule for you, based on rule elements that you select or type in the GUI.
   • If you select Text Input, a screen appears in which you can type the complete text of your rule.
4. Click Done.

To create a rule from the command line

To create a rule from the command line, use the following syntax:

rule <rule_name> { <if_statement> | <discard_statement> |<use_statement>|<cache_statement> | <redirect_statement> | <log_statement> | <accumulate_statement> }

For detailed syntax information on building rule statements, see the remainder of this chapter.

Note

---

Once you have created a rule, you need to configure a virtual server to reference that rule. For information on configuring a virtual server to reference a rule, see Referencing BIG-IP system resources .

Understanding rules syntax

Rules consist of statements, which are made up of a number of different elements, such as functions, constants, variables, and operators. Together, these elements can be used to construct a rule that selects a particular pool associated with a virtual server. They can also be used to redirect client requests.

Rule statements

A rule consists of one or more statements. Rules support the following types of statements:

• An if statement asks a true or false question and, depending on the answer, takes some action.
• A discard statement discards the request. This statement must be conditionally associated with an if statement.
• A use pool statement uses a selected pool for load balancing. This statement must be conditionally associated with an if statement.
• A cache statement uses a selected pool for load balancing. This statement can be conditionally associated with an if statement.
• A redirect to statement sends traffic to a specific destination, rather than to a pool for load balancing.
• A log statement logs a message to the Syslog facility. The statement does this by performing variable expansion on the message as defined for the header insert pool attribute. For more information on the header insert pool attribute, see Chapter 4, Pools .
• An accumulate statement terminates rules processing until another another packet containing additional data is received from the originating client. This statement is useful with the http_content and tcp_content rule variables, when not enough data has been received to be successfully evaluated. For information on these rule variables, see Variables .

Warning

---

If not used appropriately, a log statement can produce large amounts of output.

Table 5.1 shows the syntax for rule statements.

Note

---

The maximum number of if statements that you can nest in a rule is 100.

Expressions

Expressions can be specified within rule statements or within pool definitions. Their purpose is to describe some action that the rule or pool is to take, and to provide any data the rule or pool requires to take the action.

Table 5.2 shows the elements that an expression can contain, and their syntax.

Figure 5.2 is a rule that shows two examples of an expression within a rule. The expressions are indicated in boldface type.

Figure 5.2 Examples of expressions specified within a rule

In Figure 5.2 , the element tcp_content is the variable operand. The element contains is the relational operator, and the element substr() is the function. The expressions also contain some literals, such as 50, 3, "XYZ", and "ABC".

Expressions for use within rules and pools include several important features:

• Expression syntax can be used outside of rules, such as within pool persistence definitions.
• Expressions support several functions for enabling persistence and direct selection of pool members.
• Expression functions, variables, and literals can exist on either side of an operator.
• Expressions allow string concatenation using the plus (+) operator.
• Expressions promote integers, addresses, and so on to strings when used with string concatenation.
• Functions with no arguments can be specified without parentheses ().
• The syntax for the http_header and http_cookie variables matches the syntax for functions (for example, http_header(<header_tag_string>)).

The following sections describe all of the elements that an expression can contain.

Note

---

The maximum number of if statements that you can nest in a rule is 100.

Functions

There are functions available that you can use as part of expressions. A primary use of such expressions is to specify them within pool definitions, to either return a string for persistence, or to return a node to which the pool can send traffic directly.

Functions that return a string

The following functions return a string that you specify. They are:

• findstr() - Finds a string within another string and returns the string starting at the offset specified from the match.
• substr() - Returns the string starting at the offset specified.
• getfield() - Splits a string on a character and returns the string corresponding to the specific field.
• findclass() - Finds the member of a class that contains the result of the specified expression and returns that class member.
• decode_uri() - Evaluates the expression and returns a string with any %XX escape sequences decoded as per HTTP escape sequences defined in RFC2396.
• domain() - Parses and returns up to the specified number of trailing parts of a domain name from the specified expression.
• imid() - Used to parse the http_uri variable and user-agent header field for an i-mode identifier string that can be used for i-mode persistence.

findstr()

The findstr() function finds a string within another string and returns the string starting at the offset specified from the match. The function returns an empty string if:

• The argument <expr> does not evaluate into a string.
• The string specified by the argument <string> is not found in the evaluated expression.
• The specified offset would put the return string outside the evaluated expression.

Syntax

The findstr() function takes the following arguments:

findstr(<expr>, <string>, <offset>)

findstr(<expr>, <string>, <offset>, <length>)

findstr(<expr>, <string>, <offset>, <termchr>)

where:

<expr> is the expression to be searched.

<string> is a literal string to search for. A literal string uses double quotation marks, for example, "user=".

<offset> is the offset from the found string of the string to return.

<length> is the number of characters of the string to return.

<termchr> is a literal character the string to return is ended at. A literal character uses apostrophes (single quotation marks), for example, ';'.

Examples

This expression returns the string following a query character:

findstr(http_uri, "?", 1)

This expression returns the three characters following x=:

findstr(http_uri, "x=", 2, 3)

This expression returns the string following user= up to the & character:

findstr(http_uri, "user=", 5, `&')

substr()

The substr() function returns the string starting at the offset specified. The function returns an empty string if:

• The value of the <expr> argument does not evaluate into a string
• The value of the <offset> argument puts the return string outside of the evaluated expression.

Syntax

The substr() function takes the following arguments:

substr(<expr>, <offset>)
substr(<expr>, <offset>, <length>)
substr(<expr>, <offset>, <termchr>)

where:

<expr> is the expression providing the source string.

<offset> is the offset from the beginning of the string to return.

<length> is the number of characters of the string to return.

<termchr> is a literal character with which the string to return is ended.

Examples

This expression returns the string starting after the first character:

substr(http_uri, 1)

This expression returns a string of three characters starting after the second character:

substr(http_uri, 2, 3)

This expression returns the string starting at the fifth character and ending at the & character:

substr(http_uri, 5, '&')

getfield()

The getfield() function splits a string on a character, and returns the string corresponding to the specific field. The function returns an empty string if the value of <expr> does not evaluate into a string, or if the specified <fieldnum> value is greater than the number of fields the evaluated <expr> was split into. If the specified <split> character or string is not found in the evaluated <expr>, then it is treated as one field.

Syntax

The getfield() function takes the following arguments:

getfield(<expr>, <split>, <fieldnum>)

where:

<expr> is the expression to be split.

<split> is a literal character or string used to split the string into fields. A literal character uses apostrophes (single quotation marks), for example, `;'.

<fieldnum> is the number of the field to return.

Example

The following example of the getfield function returns the third field after splitting on a ; character:

getfield(http_uri, `;', 3)

Using this example, the expression ABC;DEF;123 returns the string 123.

findclass()

The findclass() function finds the member of a class that starts with or matches the beginning of that class member. This function returns the value of that class member. This is similar to the one of class identifier, except that the member is not required to be equal; instead, the member is only required to start with the string and returns the entire member value.

Syntax

The findclass() function takes the following arguments:

findclass(<expr>, <classname>)

where:

<expr> is the expression whose result is searched for in members.

<classname> is a literal class name in which to search for a member.

Example

This expression returns the member containing the domain portion of the http_host string:

findclass(domain(http_host, 2), external_servers)

decode_uri()

The decode_uri() function evaluates the expression and returns a string with any %XX escape sequences decoded as per HTTP escape sequences defined in RFC2396.

Syntax

The decode_uri() function takes the following arguments:

decode_uri(<expr>)

where:

<expr> is the expression providing the string to convert.

Example

This expression returns the HTTP URI with any escape sequences decoded:

decode_uri(http_uri)

This expression returns the binary string 0x00 0x03:

decode_uri("%00%03")

domain()

The domain() function parses and returns up to the specified number of trailing parts of a domain name from the specified expression. The function automatically parses out the portion following a `:' (representing a port or service) from the return string. The function also detects a dotted quad and returns the full quad regardless of the <count> specified. If the evaluated domain name does not have the specified number of trailing parts, the number of parts found are returned.

Syntax

The domain() function takes the following arguments:

domain(<expr>, <count>)

where:

<expr> is the expression to be parsed for a domain name.

<count> is the number of trailing parts in the domain name to return.

Example

The following example of the domain function returns the last two parts of a domain name:

domain(http_host, 2)

Using this example, the host name www.mysite.com returns the string mysite.com.

imid()

The imid() function is specifically used to parse the http_uri variable and user-agent header field for an i-mode^TM identifier string that can be used for i-mode persistence. The imid() function takes no arguments and simply returns the string representing the i-mode identifier or the empty string, if none is found.

Functions that return a node address

There are a number of expressions that you can use primarily to directly select a particular node (pool member) within a pool. They are:

• node() - Returns a literal node address converted from a string representation of an address and port.
• mapclass2node - Represents a short-hand combination of the functions findclass(), findstr(), and node().
• wlnode() - Returns a literal node address converted from a specific BEA WebLogicTM string format, representing the application IP address and service, into a literal node address.

node()

The node() function returns a literal node address converted from a string representation of an address and port. This function is designed primarily to be used with the persist expressions for directly selecting a node to which to persist.

Syntax

The node() function takes the following arguments:

node(<expr>)

where:

<expr> is the expression providing the string to convert.

Examples

node("10.0.0.3:80") // returns the node represented by 10.0.0.3, port 80

node(getfield(http_cookie("SERVER"), ';', 1))

mapclass2node()

The mapclass2node() function is a short-hand combination of the functions findclass(), findstr(), and node(). The function is equivalent to the following syntax:

node(findstr(findclass(<expr>, <classname>), "",1))

where "" represents a space character.

Syntax

The mapclass2node() function takes the following arguments:

mapclass2node(<expr>, <classname>, [<delim>])

where:

<expr> is the expression whose result is searched for in members of the named class.

<classname> is a literal name for the class in which to search for a member.

<delim> is the delimiter separating the matched string from the node address and service.

Examples

For the following class:

class external_servers {
"ABC 10.0.0.1:80",
"DEF 10.0.0.2:80"

}

this example returns a node that matches one of the server names found in the class external_servers:

mapclass2node(findstr(http_uri, 'server=', 7, 6), external_servers)

wlnode()

The wlnode() function returns a literal node address converted from a string of the BEA WebLogic format for identifying the application node to which the connection should persist.

The wlnode() function is designed primarily to be used with the persist expressions for directly selecting a node to which to persist.

Syntax

The wlnode() function takes the following arguments:

wlnode(<expr>)

where:

<expr> is the expression providing the BEA WebLogic string.

Examples

wlnode("10.0.0.3:80") // returns the node represented by 10.0.0.3, port 80

wlnode(http_cookie("JSESSIONID"))

Constant and variable operands

Operands are of two types: constant operands (constants) and variable operands (variables). You can use both types of operands in an expression.

Constants

Constants are elements of an expression whose values do not change. Possible constants are:

• IP protocol constants, for example:
  UDP or TCP
• IP addresses expressed in masked dot notation, for example:
  
  

  206.0.0.0 netmask 255.0.0.0

• Strings of ASCII characters, for example:
  
  

  "pictures/bigip.gif"

• Regular expression strings

Variables

Variables are elements of an expression that have changeable values. Therefore, they need to be referred to by a constant descriptive name. The variables available depend on the context in which the rule containing them is evaluated. Following are descriptions of the variables that you can use within a rule.

IP packet header variable

Table 5.3 lists and describes the available IP packet header variables for use within a rule.

HTTP request string variables

The BIG-IP system replaces all HTTP request string variables with string literals. In command line syntax, you refer to HTTP request variables by a predefined set of names. Internally, an HTTP request variable points to a method for extracting the desired string from the current HTTP request header or content data. Before an HTTP request variable is used in a relational expression, the BIG-IP system replaces the variable with the extracted string.

Table 5.4 lists and describes the available HTTP request string variables for use within a rule.

TCP string variables

The BIG-IP system replaces all TCP request string variables with string literals. In command line syntax, you refer to TCP request variables by a predefined set of names. Internally, a TCP request variable points to a method for extracting the desired string from the current TCP request data. Before a TCP request variable is used in a relational expression, the BIG-IP system replaces the variable with the extracted string.

Table 5.5 lists and describes the available TCP request string variables for use within a rule.

Operators

Operators can be of two types: relational operators and logical operators.

Relational operators

In a rule, relational operators compare two operands to form relational expressions. Table 5.6 lists the relational operators and the corresponding meanings.

It is useful to note that while the contains and matches_regex operators provide similar functionality, they require different operands on the right side of the expression. The contains operator requires a literal string operand, whereas the matches_regex operator requires a regular expression.

Tip

---

Relational expressions using the contains operator require less processing than similar expressions using the matches_regex operator. It is therefore recommended that you use contains instead of matches_regex wherever possible.

Logical operators

Logical operators modify an expression or connect two expressions together to form a logical expression. Arguments to logical operators must return a value of true. Table 5.7 lists the logical operators and their meanings.

Using rules to select pools

Rules can search for various kinds of data within a request before selecting the appropriate pool to service that request. Table 5.8 lists the various criteria you can use when creating a rule to select a pool.

Note

---

You must define a pool before you can define a rule that references the pool.

Selecting pools based on header or content data

Using rule variables such as http_header, http_content, and tcp_content, you can create a rule that selects a pool based on data that resides in the header or content of a request.

For example, you may want a rule that logically states: "If the packet data contains an HTTP request with a URI ending in cgi, then load balance using the pool cgi_pool. Otherwise, load balance using the pool default_pool".

Figure 5.3 shows a rule that illustrates this example.

Regarding the tcp_content variable, you might want a rule that logically states: "If the packet data contains a TCP request containing the string "XYZ", then load balance using the pool xyz_servers. If the string is not found, search for the string "ABC" at the specified offset and load balance using the pool abc_servers. If the string "ABC" is not found, load balance using the pool web_servers".

Figure 5.4 shows a rule that illustrates this example.

Figure 5.4 Sample rule using a TCP request string variable

Another example is shown in Figure 5.5 .

Figure 5.5 Sample rule using an HTTP request string variable

Note that in Figure 5.5 , the search for string "ABC" is not limited to the first 20 bytes in the HTTP content. If you want to restrict a search to a specific region of the content, such as the first 20 bytes, you can include an expression in the rule, using the substr() function. Figure 5.6 shows an example.

Figure 5.6 Sample rule that restricts a search to the first 20 bytes of data

For information on functions such as the substr() function shown in the above example, see Functions .

To specify HTTP request string or TCP request string variables within a rule using the Configuration utility

1. In the navigation pane, click Rules.
2. Click the Add button.
3. In the Name box, type a unique name for the rule.
4. In the Type box, click the button for Rule Builder.
5. Click Next.
6. On the left side of the screen, select a variable.
7. Fill in all information within the row.
8. Click Next.
9. Select Discard.
10. Click Next.
11. Select either No Action or Discard from the box.
12. Click Done.

To specify HTTP request string or TCP request string variables within a rule from the command line

The following example shows the syntax for specifying an IP packet header variable within a rule.

b rule my_rule { if '( http_uri ends_with "cgi" )' { use '( cgi_pool )' }\
else { use '( another_pool )' } }

For examples of rules that select pools based on header information inserted into HTTP requests by an SSL Accelerator proxy, see Inserting headers into HTTP requests .

Selecting pools based on IP packet header data

In addition to specifying the HTTP and TCP request string variables within a rule, you can also select a pool by specifying IP packet header information. The types of information you can specify in a rule are:

• Client IP address
• Server IP address
• Client port number
• Server port number
• IP protocol number
• QoS level
• ToS level

The following sections describe these specific types of IP packet header data that you can specify within a rule. For the procedure on specifying IP packet header variables within a rule, see To specify IP packet header variables within a rule using the Configuration utility .

IP addresses

You can specify the client_addr or the server_addr variable within a rule to select a pool. For example, if you want to load balance based on part of the client's IP address, you might want a rule that states:

"All client requests with the first byte of their source address equal to 206 will load balance using a pool named clients_from_206 pool. All other requests will load balance using a pool named other_clients_pool."

Figure 5.7 shows a rule that implements the preceding statement.

For additional examples of rules using IP packet header information, see Additional rule examples .

Port numbers

The BIG-IP system includes rule variables that you can use to select a pool based on the port number of the client or server. These variables are client_port and server_port.

To configure a rule to select a pool based on a port number, use the syntax shown in the example in Figure 5.8 .

IP protocol numbers

The BIG-IP system includes a rule variable, ip_protocol, that you can use to select a pool based on an IP protocol number.

To configure a rule to select a pool based on an IP protocol number, use the syntax shown in the example in Figure 5.9 .

Quality of Service (QoS) level

The Quality of Service (QoS) standard is a means by which network equipment can identify and treat traffic differently based on an identifier. As traffic enters the site, the BIG-IP system can apply a rule that sends the traffic to different pools of servers based on the QoS level within a packet.

To configure a rule to select a pool based on the QoS level of a packet, you can use the link_qos rule variable, as shown in the example in Figure 5.10 .

For information on setting QoS values on packets based on the pool selected for that packet, see Configuring the Quality of Service (QoS) level .

IP Type-Of-Service (ToS) level

The Type of Service (ToS) standard is a means by which network equipment can identify and treat traffic differently based on an identifier. As traffic enters the site, the BIG-IP system can apply a rule that sends the traffic to different pools of servers based on the ToS level within a packet.

The variable that you use to set the ToS level on a packet is ip_tos. This variable is sometimes referred to as the DiffServ variable.

To configure a rule to select a pool based on the ToS level of a packet, you can use the ip_tos rule variable, as shown in the example in Figure 5.11 .

For information on setting ToS values on packets based on the pool selected for that packet, see Configuring the Type of Service (ToS) level .

Specifying IP packet header variables within a rule

You can use either the Configuration utility or the bigpipe rule command to specify IP packet header variables within a rule.

To specify IP packet header variables within a rule using the Configuration utility

1. In the navigation pane, click Rules.
2. Click the Add button.
3. In the Name box, enter a unique name for the rule.
4. In the Type box, click the button for Rule Builder.
5. Click Next.
6. On the left side of the screen, select a variable.
7. Fill in all information within the row.
8. Click Next.
9. Select Discard.
10. Click Next.
11. Select No Action or Discard from the box.
12. Click Done.

To specify IP packet header variables within a rule from the command line

The following example shows the syntax for specifying an IP packet header variable within a rule.

b rule my_rule { if '( client_addr == 10.12.12.10 )' { use '( pool_A80 )' } }

Using the one of class identifier

The BIG-IP system includes a class identifier called one of, which you can use to match a variable to members of class. Using the one of identifier means that the BIG-IP system applies the relational operator to the left of the one of identifier to members of the named class.

For example, prior to the availability of the one of identifier, a rule that was intended to send incoming AOL connections to the pool aol_pool was written as shown in Figure 5.12 , where multiple values for the client_addr variable had to be individually specified.

Using the one of identifier instead, you can cause the BIG-IP system to load balance all incoming AOL connections to the pool aol_pool, if the value of the client_addr variable is a member of the class AOL. Figure 5.13 shows this type of rule. In this case, the one of indicates that the variable aol is actually a list of values.

Note that the value of an expression such as client_addr equals one of aol is true if the expression is true for at least one member the class.

Note

---

The one of class identifier requires a class name as one of its operands. Also, you cannot use the one of identifier with the relational operator matches_regex. For more information on the one of identifier, see Configuring class lists .

For more information on the types of classes that the BIG-IP system allows and the commands for creating classes, see Configuring class lists .

Selecting pools based on HTTP header data

A rule can contain a cache statement that selects a pool based on HTTP header data. A cache statement returns either the origin pool, the hot pool, or the cache pool. When the cache pool is selected, it is accompanied by the indicated node address and port. When a rule returns both a pool and a node, the BIG-IP system does not do any additional load balancing or persistence processing.

Figure 5.14 shows an example of a rule containing a cache statement.

Cache statements

A cache statement may be either the only statement in a rule, or it may be nested within an if statement. Rules with cache statements are used to select pools based on HTTP header data. Figure 5.15 shows an example of a cache statement within a rule.

Figure 5.15 Example of a cache statement within a rule

Table 5.9 describes the cache statement attributes and their syntax.

Using rules to redirect HTTP requests

In addition to configuring a rule to select a specific pool, you can also configure a rule to redirect an HTTP request to a specific location, using the redirect to operator and a set of format strings included in the BIG-IP system. The location can be either a host name, port number, or URI. The format strings are: %h, %p, and %u. These format strings can be used within a redirection string to indicate which parts of the string (host name, port number, and URI path) do not indicate a redirection.

For example, the string https://%h:443/%u specifies that the HTTP request is to be redirected to a different protocol (https instead of the standard http) and a different port number (443). The host name and the URI path remain the same, indicated by the %h and %u format strings.

Figure 5.16 shows a rule that is configured to redirect an HTTP request.

The preceding rule applies the format string to the URL. In this case, the format string sets the protocol to https, strips the requested port number (if any), changes it to 8080, and applies a trailing slash (/) to the end of the URI, if the URI ends with the string baz.

Note

---

The %u format string strips the first character of the URI path. This is usually a slash (/), and this modification is done purely for aesthetic reasons. Thus when describing a URL, the string http://%h/%u is used instead of http://%h%u.

For more information on HTTP redirection and format strings, see Redirecting HTTP requests .

Configuring class lists

Class lists are useful for simplifying rules. Using the one of identifier and a class name within a rule eliminates the need to specify multiple values for a relational operator within the expression. For a more detailed explanation, see Using the one of class identifier .

The remainder of this section describes the types of class lists that you are allowed to create, the storage options available, some predefined classes included in the BIG-IP system, and the procedure for creating a class.

Class types

When using the one of identifier within a rule, you can specify any of three types of classes: classes of IP addresses, classes of strings, and classes of numeric values.

Note

---

Although the one of identifier works with string classes, you cannot use it with the relational operator matches_regex.

IP address classes

There are two types of IP address classes: network IP address and host IP address.

The following command creates a network IP address class named my_netwk and contains network IP addresses:

b class my_ntwk { network 10.2.2.0 mask 255.255.255.0 }

Figure 5.17 shows the resulting network IP address type of class.

The following command creates a host IP address class named my_host and contains one or more host IP addresses:

b class my_host { host 10.1.1.1 }

Figure 5.18 shows the resulting host IP address type of class.

Figure 5.18 An example of a host IP address type of class

String classes

The following command creates a string class named images.

b class images { \".gif\" }

Note: This example shows the use of escape characters for the quotation marks.

Figure 5.19 shows the resulting string type of class.

Numeric value classes

The following command creates a numeric value class named my_protos.

b class my_protos { 27 38 93 }

Figure 5.20 shows the resulting numeric value type of class.

Note

---

The size of a class is limited by system resources only.

Storage options

The BIG-IP system allows you to store classes in two ways, either in-line or externally.

In-line storage

Classes that are stored in-line are saved in their entirety in the bigip.conf file. Also, when any data in the class needs to be updated, the entire class must be reloaded. In general, in-line storage uses additional system resources due to extensive searching requirements on large classes. Also, in-line storage requires you to reload entire classes when incrementally updating data.

To create an in-line class using the Configuration utility

1. In the navigation pane, click Rules.
2. Click the Classes tab.
   This displays a list of the currently-defined in-line classes.
3. Click the Add button.
   This displays the Add Class screen.
4. In the Class Name box, type in a class name.
5. In the Class Type box, select a class type, either Address, String, or Value.
6. In the File Mode box, select a file mode, either Read or Read/Write.
7. In the Sizing box, type a number.
8. Click Done.

External storage

You have the option to store classes in another location on the BIG-IP system, that is, outside of the bigip.conf file. Such classes are called external classes. The default location for storing external classes is the /config directory. Because the class is stored externally in another location, the bigip.conf file itself contains only meta-data for the class. The data in an externally-stored class file is stored as a comma-separated list of values (CSV format).

Creating external classes is useful because data does not need to be sorted when being loaded. Instead, data is stored in a hash-table in the kernel. This storage method translates to improvements in performance when a rule uses a large class to direct traffic to a pool.

The syntax for the class meta-data that is stored in the bigip.conf file is as follows:

class <name> extern {
<variable> <value>
<variable> <value>
...
}

The value of the <name> field is the name that you want to assign to the class.

Table 5.10 lists and describes the allowed values for the <variable> field, along with the corresponding values for the <value> field. Note that the value of the <value> field varies depending on the whether the <variable> field is filename, type, mode, or sizing.

Figure 5.21 shows an example of class meta-data in the bigip.conf file. Note that this meta-data references the externally-stored class file /home/ip2.class.

The data in an external class file is stored in comma-separated lists, and the formats of any data values, such as IP addresses, match the formats used in the bigip.conf file. Continuing with the example above, Figure 5.22 shows the contents of the class file /home/ip2.class.

Creating and deleting external classes

Using the Configuration utility, you can create or delete externally-stored classes.

To create an external class using the Configuration utility

1. In the navigation pane, click Rules.
2. Click the External Classes tab.
   This displays a list of the currently-defined external classes.
3. Click the Add button.
   This displays the Add External Class screen.
4. In the Class Name box, type in a class name.
5. In the Class Type box, select a class type, either Address, String, or Value.
6. In the File Name box, type the path name to the class.
7. In the File Mode box, select a file mode, either Read or Read/Write. The default value is Read.
8. In the Sizing box, type a number. The default value is 1024.
9. Click Done.

To delete an external class using the Configuration utility

1. In the navigation pane, click Rules.
2. Click the External Classes tab.
   This displays a list of the currently-defined external classes.
3. In the Delete column, click the Delete button (trashcan icon) corresponding to a class name.

Note

---

If you use the bigpipe reset command to delete configuration components, the command does not delete any externally-stored classes. You must delete externally-stored classes explicitly, using the Configuration utility as shown above.

Displaying external class data

Using either the Configuration utility or the bigpipe command, you can display the properties of an existing external class, or you can display either the class meta-data or the contents of the external class.

To display the properties of an external class using the Configuration utility

1. In the navigation pane, click Rules.
2. Click the External Classes tab.
   This displays a list of the currently-defined external classes.
3. In the Class Name column, click a class name.

To display external class meta-data from the command line

You can display the meta-data information for an externally stored class using the following bigpipe command syntax, where <name> is the class name.

b class <name> show

To display the contents of an external class from the command line

You can display the contents of an external class file using the following bigpipe command syntax, where <name> is the class name.

b class <name> dump

To display a class member from the command line

You can display the contents of a particular class member using the following bigpipe command syntax, where <name> is the class name and <value> is the name of the member.

b class <name> member show <value>

Managing external class members

From the properties page of an external class, you can add, delete, or search for class members. This ability to manage class members eliminates the need to re-load the entire class list when the class needs to change incrementally.

Note

---

You can only add or delete a class member when the class mode is set to ReadWrite. To change the class mode, use the Configuration utility.

To manage external class members using the Configuration utility

1. In the navigation pane, click Rules.
2. Click the External Classes tab.
   This displays a list of the currently-defined external classes.
3. In the Class Name column, click a class name.
4. Enter the appropriate member data.
5. In the Resources box, click the ADD, DEL, or FIND button.
   Clicking one of these buttons causes the change to take effect immediately.

To manage external class members from the command line

You can add or delete a member from an external class using the following bigpipe command syntax, where <name> is the class name and <value list> is a list of one or more elements of the appropriate type (Address, String, or Value).

b class <name> member add | delete { <value list> }

For example, the following command adds the member ".gif" to the class my_class:

b class my_class member add \".gif\"

Including external class lists when synchronizing configurations

When you synchronize a BIG-IP system configuration for redundant systems, the BIG-IP system only includes class lists that reside in the /config directory (that is, in-line stored class lists). If you want the synchronization to include externally-stored class lists, you must add anassociated entry for each class list into the bigip.conf file. You add these entries using the bigpipe db command.

To include external class lists when synchronizing configurations

When you want the BIG-IP system to include externally-stored class lists when synchronizing configurations for redundant systems, use the bigpipe db command to create special entries in the bigip.conf file. For example, the following command adds an entry into the bigip.conf file for the externally-stored class list /home/string/class. The 700 number designates the entry as corresponding to an externally stored class list.

b db set Common.Bigip.Sync.700.file = "/home/string/class"

Predefined classes

The BIG-IP system includes a number of predefined classes. They are:

• AOL Network
• Image Extensions
• Non-routable addresses

These classes are located in the file /etc/default_classes.txt. When the bigpipe load command is issued, the lists are loaded. Unless modified by a user, these lists are not saved to the file bigip.conf.

To view classes

To view classes, including the default classes, use the following command.

bigpipe class show

Additional rule examples

This section contains additional examples of rules including:

• Cookie rule
• Language rule
• AOL rule
• Cache rule
• Protocol specific rule

Cookie rule

Figure 5.23 shows a cookie rule that load balances based on the user ID that contains the word VIRTUAL.

Language rule

Figure 5.24 shows a rule that load balances based on the language requested by the browser.

AOL rule

Figure 5.25 and 5.26 are examples of rules that you can use to load balance incoming AOL connections.

Cache rule

Figure 5.27 shows an example of a rule that you can use to send cache content, such as .gifs, to a specific pool.

Rule using the ip_protocol variable

Figure 5.28 shows a rule that uses the ip_protocol variable.

Rule using IP address and port variables

Figure 5.29 shows a rule that uses the server_addr and server_port rule variables.

Rule using the one of class identifier

A good use of the one of class identifier in a rule is when you create a string class, and then write a rule to match a variable to the members of that class. For example, Figure 5.30 shows a string class that you could create, called images.

Given the above class, you could then create a rule that uses the one of identifier to to match the value of the variable http_uri to one or more members of the class images. Figure 5.31 shows this rule.

Rule based on HTTP header insertion

You can create rules based on headers that an SSL Accelerator proxy has inserted into HTTP requests. For examples of these types of rules, see Inserting headers into HTTP requests .

Note

---

The variables that the SSL Accelerator proxy uses to insert headers into HTTP requests cannot be used within pool and rule expressions.

---