Applies To:

Show Versions Show Versions

Manual Chapter: Configuration Guide for BIG-IP® Global Traffic Management: 13 - Managing iRules
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>


13

Managing iRules


Introducing iRules for the Global Traffic Manager

As you work with the Global Traffic Manager, you might find that you want to incorporate additional customizations beyond the available features associated with load balancing, monitors, or other aspects of your traffic management. For example, you might want to have the Global Traffic Manager respond to a name resolution request with a specific CNAME record, but only when the request is for a particular wide IP and originates from Europe. In the Global Traffic Manager, these customizations are defined through iRules. iRules are code snippets that are based on TCL 8.4. These snippets allow you a great deal of flexibility in managing your global network traffic.

If you are familiar with the BIG-IP Local Traffic Manager, you might already be aware of and use iRules to manage your network traffic on a local level. The iRules in the Global Traffic Manager share a similar syntax with their Local Traffic Manager counterparts, but support a different set of events and objects.

Due to the dynamic nature of iRules development, the following sections focus on providing an overview of iRule operations and describe the events and command specific to the Global Traffic Manager. For additional information on how to write iRules, we recommend you visit F5's DevCentral Web site: http://devcentral.f5.com. At this site, you can learn more about iRules development, as well as discuss iRules functionality with others.

What is an iRule?

An iRule is a script that you write if you want individual connections to target a pool other than the default pool defined for a virtual server. iRules allow you to more directly specify the pools to which you want traffic to be directed. Using iRules, you can send traffic not only to pools, but also to individual pool members or hosts.

The iRules you create can be simple or sophisticated, depending on your content-switching needs. Figure 13.1 shows an example of a simple iRule.

Figure 13.1 Example of an iRule
when DNS_REQUEST {
  if { [IP::addr [IP::client_addr] equals 10.10.10.10] } {
     pool my_pool
 }
}

This iRule is triggered when a DNS request has been detected, causing the Global Traffic Manager to send the packet to the pool my_pool, if the IP address of the local DNS making the request matches 10.10.10.10.

iRules can direct traffic not only to specific pools, but also to individual pool members, including port numbers and URI paths, either to implement persistence or to meet specific load balancing requirements.

The syntax that you use to write iRules is based on the Tool Command Language (Tcl) programming standard. Thus, you can use many of the standard Tcl commands, plus a set of extensions that the Global Traffic Manager provides to help you further increase load balancing efficiency.

For information about standard Tcl syntax, see http://tmml.sourceforge.net/doc/tcl/index.html.

Creating iRules

You create an iRule using the Configuration utility.

To create an iRule

  1. On the Main tab of the navigation pane, expand Global Traffic and click iRules.
    The iRules screen opens.
  2. Click the Create button.
  3. In the Name box, type a 1- to 31-character name.
  4. In the Definition box, type the syntax for your iRule.
  5. If you want to expand the length of the Definition box, check Extend Text Area. Also, if you want the contents of the iRule to wrap within the box, check Wrap Text.
  6. Click the Finished button to save your changes.

For detailed syntax information on writing iRules, see the remainder of this chapter.

Assigning iRules

Within the Global Traffic Manager, you assign iRules to the wide IPs in your network configuration.

To assign an iRule

  1. On the Main tab of the navigation pane, expand Global Traffic and then click Wide IPs.
    The main screen for wide IPs opens.
  2. Click the name of the wide IP to which you want to assign an iRule.
    The properties screen for the wide IP opens.
  3. On the menu bar, click iRules.
    The main iRules screen for the wide IP opens.
  4. Click the Manage button.
    The Manage iRules screen opens.
  5. From the iRule list, select an appropriate iRule.
  6. Click the Add button.
    The new rule appears in the list of assigned iRules.
  7. Click the Finished button to save your changes.

Controlling iRule evaluation

In a basic system configuration where no iRule exists, the Global Traffic Manager directs incoming traffic to the default pool assigned to the wide IP that receives that traffic based on the assigned load balancing modes. However, you might want the Global Traffic Manager to direct certain kinds of connections to other destinations. The way to do this is to write an iRule that directs traffic to that other destination, contingent on a certain type of event occurring. Otherwise, traffic continues to go to the default pool assigned to the wide IP.

iRules are therefore evaluated whenever an event occurs that you have specified in the iRule. For example, if an iRule includes the event declaration DNS_REQUEST, then the iRule is triggered whenever the Global Traffic Manager receives a name resolution request. The Global Traffic Manager then follows the directions in the remainder of the iRule to determine the destination of the packet.

Specifying events

The iRules feature includes several types of event declarations that you can make in an iRule. Specifying an event declaration determines when the Global Traffic Manager evaluates the iRule. The following sections list and describe these event types. Also described is the concept of iRule context and the use of the when keyword.

Event types

The iRule command syntax includes several types of event declarations that you can specify within an iRule. These event types are listed in table 13.1 .

Table 13.1 Event declarations for iRules
iRule Event
Description
DNS_REQUEST
Triggered when a DNS request is received from a client.
LB_SELECTED
Triggered when the Global Traffic Manager has selected a target node.
LB_FAILED
Triggered when a connection to the server was unable to complete. This might occur if the pool has no available members or a selected pool member is otherwise not available.

Using the when keyword

You make an event declaration in an iRule by using the when keyword, followed by the event name. For example:

when DNS_REQUEST {

iRule details...

}

Listing iRules on wide IPs

When you assign multiple iRules as resources for a wide IP, it is important to consider the order in which you list them on the wide IP. This is because the Global Traffic Manager processes duplicate iRule events in the order that the applicable iRules are listed. An iRule event can therefore terminate the triggering of events, thus preventing the Global Traffic Manager from triggering subsequent events.

To organize the list of iRules

  1. On the Main tab of the navigation pane, expand Global Traffic and then click Wide IPs.
    The main screen for wide IPs opens.
  2. Click the name of the wide IP to which you want to assign an iRule.
    The properties screen for the wide IP opens.
  3. On the menu bar, click iRules.
    The main iRules screen for the wide IP opens.
  4. Click Manage.
    The Manage iRules screen opens.
  5. Click the name of an assigned iRule and then use either the Up button to move the iRule up one position, or the Down button to move the iRule down one position.
  6. Click the Finished button to save your changes.

Using statement commands

Some of the commands available for use within iRules are known as statement commands. Statement commands enable the Global Traffic Manager to perform a variety of different actions. For example, some of these commands specify the pools or servers to which you want the Global Traffic Manager to direct traffic.

Table 13.2 lists and describes statement commands that you can use within iRules.

Table 13.2 iRule statement commands
Statement Command
Description
discard
Causes the current packet or connection (depending on the context of the event) to be discarded. This statement must be conditionally associated with an if statement.
drop
Same as the discard command.
[use] host <string>
Causes the server host, as identified by a string, to be used directly, thus bypassing any load-balancing.
if { <expression> } {
<statement_command>
}
elseif { <expression> } {
<statement_command>
}
Asks a true or false question and, depending on the answer, takes some action.
Note that the maximum number of if statements that you can nest in an iRule is 100.
log [<facility>.<level>] <message>
Generates and logs the specified message to the Syslog facility.
[use] host <addr> [<port>]
Causes the server host, as identified by IP address and, optionally, port number, to be used directly, thus bypassing any load-balancing.
[use] pool <pool_name> [member <addr> [<port>]]
Causes the Global Traffic Manager to load balance traffic to the named pool. This statement must be conditionally associated with an if statement. Optionally, you can specify a specific pool member to which you want to direct the traffic.
reject
Causes the connection to be rejected, returning a reset as appropriate for the protocol.
return
Terminates execution of the iRule event .

Using wide IP commands

The Global Traffic Manager supports several iRule commands that are unique to its global traffic management capabilities. These commands can specify a specific CNAME or wide IP name, or determine the geographic origin of the request.

Table 13.3 lists and describes wide IP commands that you can use within iRules.

Table 13.3 iRule wide IP commands
Statement Command
Description
cname <cname>
Returns the <cname> referenced.
wideip name
Returns the wide IP name requested.
ttl <value>
Overrides the default time-to-live value. If this command is used for a CNAME, the value overrides the default of 0. If this command is used for a pool, the value overrides the time-to-live value for that pool.
whereis <ip> [[country] [continent]]
Returns the geographic location of a specific IP address. If the keywords [country] or [continent] are not specified, this command returns all location data.

Using utility commands

The Global Traffic Manager includes a number of utility commands that you can use within iRules. You can use these commands to parse and retrieve content, verify data integrity, and retrieve information about active pools and pool members.

Parsing and manipulating content

Table 13.4 lists and describes the commands that return a string that you specify. The pages following the table provide detail and examples of the commands.

Table 13.4 Utility commands that parse and manipulate content
Command
Description
findstr
Finds a string within another string and returns the string starting at the offset specified from the match.
substr
Finds a string within another string and returns the string starting at the offset specified from the match.
findclass
Finds the member of a data group that contains the result of the specified expression, and returns that data group member or the portion following the separator, if a separator was provided.
host
Searches for a specific host name within the supplied <string>.

Ensuring data integrity

Some of the commands available for use within iRules allow you to check the integrity of data. Table 13.5 lists and describes these commands.

Table 13.5 Utility commands for ensuring data integrity
Utility Command
Description
crc32 <string>
Returns the crc32 checksum for the provided string, or if an error occurs, an empty string. Used to ensure data integrity.
md5 <string>
Returns the RSA Data Security, Inc. MD5 Message Digest Algorithm (md5) message digest of the provided string, or if an error occurs, an empty string. Used to ensure data integrity.

Retrieving resource information

Some of the commands available for use within iRules allow you to retrieve data about servers, pools, and pool members. Table 13.6 lists and describes these commands.

Table 13.6 Utility commands for retrieving pool information
Utility Command
Description
active_members <pool name>
Returns the number of active members in the pool.
member_priority <pool name> member <ip> [<port>]
Returns the priority for pool member ip:port.
LB::server [<pool | name | address | port>
Returns the name of the server selected for a load balancing operation.
LB::status [<up | down | session enabled | session disabled>]
Returns the status of the selected resource.
LB::status pool <name> member <address> [<port> <up | down | session enabled | session disabled>]
Returns the status of the selected pool.
LB::status vs <ip> <port> [<up | down | session enabled | session disabled>]
Returns the status of the selected virtual server.

Using protocol commands

The Global Traffic Manager includes a number of protocol commands that you can use within iRules. You can use these commands to identify IP addresses and ports of both the clients and servers for a given name resolution transaction.

IP commands

The Global Traffic Manager supports the following IP commands.

Table 13.7 IP commands for iRules
Protocol Command
Description
IP::remote_addr
Returns the IP address of the client for a given name resolution request. Equivalent to IP::client_addr.
IP::local_addr
Returns the IP address of the server for a given name resolution request. Equivalent to IP::server_addr.
IP::client_addr
Returns the IP address of the client for a given name resolution request. Equivalent to IP::remote_addr.
IP::server_addr
Returns the IP address of the server for a given name resolution request. Equivalent to IP::local_addr.
IP::protocol
Returns the IP protocol value, such as TCP or UDP.

TCP commands

The Global Traffic Manager supports the following TCP commands.

Table 13.8 TCP commands for iRules
Protocol Command
Description
TCP::client_port
Returns the client's TCP port/service number.
TCP::server_port
Returns the server's TCP port/service number.

UDP commands

The Global Traffic Manager supports the following UDP commands.

Table 13.9 UDP commands for iRules
Protocol Command
Description
UDP::client_port
Returns the client's UDP port/service number.
UDP::server_port
Returns the server's UDP port/service number.

Removing iRules

Within the Global Traffic Manager, you can remove an iRule from a wide IP at any time.

To remove an iRule

  1. On the Main tab of the navigation pane, expand Global Traffic and then click Wide IPs.
    The main screen for wide IPs opens.
  2. Click the name of the wide IP to which you want to assign an iRule.
    The properties screen for the wide IP opens.
  3. On the menu bar, click iRules.
    The main iRules screen for the wide IP opens.
  4. Click Manage.
    The Manage iRules screen opens.
  5. Select the iRule that you would like to remove, and then click the Remove button to remove it.
  6. Click the Finished button to save your changes.



Table of Contents   |   << Previous Chapter   |   Next Chapter >>

Was this resource helpful in solving your issue?




NOTE: Please do not provide personal information.



Incorrect answer. Please try again: Please enter the words to the right: Please enter the numbers you hear:

Additional Comments (optional)