Applies To:

Show Versions Show Versions

Manual Chapter: Configuration Guide for BIG-IP® version 9.2.2 Global Traffic Management: Writing iRules - 15
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>


15

Writing 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.

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 15.1 shows an example of a simple iRule.

Figure 15.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.

Basic iRule elements

iRules are made up of these basic elements:

  • Event declarations
  • Operators
  • iRule commands

Event declarations

iRules are event-driven, which means that the Global Traffic Manager triggers an iRule based on an event that you specify in the iRule. An event declaration is the specification of an event within an iRule that causes the Global Traffic Manager to trigger that iRule whenever that event occurs. Examples of event declarations that can trigger an iRule are DNS_REQUEST, which triggers an iRule whenever the system receives a DNS request, and LB_SELECTED, which triggers an iRule when a request is sent to a specific pool.

For more information on iRule events, see Specifying events .

Operators

An iRule operator compares two operands in an expression. In addition to using the Tcl standard operators, you can use the operators listed in Table 15.1 .

Table 15.1 iRule operators
Operator
Syntax
Relational operators
contains
matches
equals
starts_with
ends_with
matches_regex
Logical operators
not
and
or

For example, you can use the contains operator to compare a variable operand to a constant. You do this by creating an if statement that represents the following: "If the client's IP address contains 192.168.5.5, send to pool aol_pool." Figure 15.2 shows an iRule that performs this action.

Figure 15.2 An iRule based on the contains operator
when DNS_REQUEST {
  if { [IP::client_addr] contains "1.2.3.4" } {
     pool aol_pool
  } else {
     pool all_pool
 }
}

iRule commands

An iRule command within an iRule causes the Global Traffic Manager to take some action, such as querying for data, manipulating data, or specifying a traffic destination. The types of commands that you can include within iRules are:

  • Statement commands
    These commands cause actions such as selecting a traffic destination or assigning a SNAT translation address. An example of a statement command is pool <name>, which directs traffic to the named load balancing pool. For more information, see Using statement commands .
  • Protocol commands
    These commands search for header and content data. An example of a protocol command is IP::remote_addr, which searches for and returns the remote IP address of a connection. For more information on protocol commands, see Using protocol commands .
  • Utility commands
    These commands are functions that are useful for parsing and manipulating content. An example of a utility command is findstr(), which searches a given piece of text for a specific string. For more information on using utility commands, see Using utility commands .

Specifying traffic destinations

As described in the previous section, iRule commands instruct the Global Traffic Manager to take direct action in some way. The following sections show examples of iRule commands.

For detailed information on iRule commands, see these sections:

Selecting a load balancing pool

Once you have specified a query within your iRule, you can use the pool command to select a load balancing pool to which you want the Global Traffic Manager to send a request. Figure 15.3 shows an example of this command.

Figure 15.3 Example of the pool command within an iRule
when DNS_REQUEST {
  if { [wideip name] ends_with ".org" } {
     pool org_pool
  } elseif { [wideip name] ends_with ".com" } {
     pool com_pool
 }
}

Selecting a specific server

As an alternative to the pool command, you can also write an iRule that directs traffic to a specific server. To do this, you use the host command. Figure 15.4 shows an example of this command.

Figure 15.4 Example of the host command within an iRule
when DNS_REQUEST {
  if { [wideip name] ends_with ".com" } {
     host 10.1.2.200 80
 }
}

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 15.2 .

Table 15.2 Event declarations for iRules
iRule Event
Description
Global Events
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 15.3 lists and describes statement commands that you can use within iRules.

Table 15.3 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 15.4 lists and describes wide IP commands that you can use within iRules.

Table 15.4 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 15.5 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 15.5 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>.

findstr

The findstr command finds the string <search_string> within <string> and returns a sub-string based on the <skip_count> and <terminator> from the matched location.

Note the following;

  • <terminator> may be either a character or length.
  • If <skip_count> is not specified, it defaults to zero.
  • If <terminator> is not specified, it defaults to the end of the string.
  • This command (without <skip_count> or <terminator>) is equivalent to the following Tcl command: "string range <string> [string first <string> <search_string>] end".

The syntax of the findstr() command is as follows:

findstr <string> <search_string> [<skip_count> [<terminator>]

Figure 15.5 shows an example of an iRule using the findstr command.

Figure 15.5 An iRule using the findstr command
when DNS_REQUEST {
  if { [findstr [IP::protocol]] equals "tcp" } {
     pool tcp_servers
  } else {
     pool udp_servers
 }
}

substr

The substr command returns a sub-string <string> based on the values of <skip_count> and <terminator>.

Note the following:

  • The <skip_count> and <terminator> arguments are used in the same way as they are for the findstr command.
  • This command is equivalent to the Tcl string range command except that the value of <terminator> may be either a character or a count.

The syntax of the substr command is:

substr <string> <skip_count> [<terminator>]

findclass

The findclass command searches a data group list for a member that starts with <string> and returns the data-group member string. The member is not required to be equal; instead, the member is only required to start with the string and the command returns the entire member value.

The syntax of the findclass command is:

findclass <string> <data group> [(separator)]

Note that if a separator is specified, the data group member is split on the separator, and the latter portion (that is, the portion following the separator) is returned.

host

The host command searches for a specific host name within the supplied <string>. This command also has a counterpart, host <ip> which searches for an IP address instead of a name.

The syntax of the host command is:

host <string>

Ensuring data integrity

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

Table 15.6 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.

Retreiving resource information

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

Table 15.7 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
Returns the name of the server selected for a load balancing operation.
LB::status
Returns the status of the selected resource.

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 15.8 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 15.9 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 15.10 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)