Applies To:

Show Versions Show Versions

Manual Chapter: Writing iRules
Manual Chapter
Table of Contents   |   << Previous Chapter   |   Next Chapter >>

17 
An iRule is a powerful and flexible feature within the BIG-IP® local traffic management system that you can use to manage your network traffic. Using syntax based on the industry-standard Tools Command Language (Tcl), the iRulesTM feature not only allows you to select pools based on header data, but also allows you to direct traffic by searching on any type of content data that you define. Thus, the iRules feature significantly enhances your ability to customize your content switching to suit your exact needs.
The remainder of this introduction presents an overview of iRules, lists the basic elements that make up an iRule, and shows some examples of how to use iRules to direct traffic to a specific destination such as a pool or a particular node.
Important: For complete and detailed information on iRules syntax, see the F5 Networks DevCentral web site, http://devcentral.f5.com. Note that iRules must conform to standard Tcl grammar rules; therefore, for more information on Tcl syntax, see http://tmml.sourceforge.net/doc/tcl/index.html.
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 destinations to which you want traffic to be directed. Using iRules, you can send traffic not only to pools, but also to individual pool members, ports, or URIs.
The iRules you create can be simple or sophisticated, depending on your content-switching needs. Figure 17.1 shows an example of a simple iRule.
Figure 17.1 Example of an iRule
This iRule is triggered when a client-side connection has been accepted, causing the BIG-IP system to send the packet to the pool my_pool, if the clients address matches 10.10.10.10.
Using a feature called the Universal Inspection Engine, you can write an iRule that searches either a header of a packet, or actual packet content, and then directs the packet based on the result of that search. iRules can also direct packets based on the result of a client authentication attempt.
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 robust set of extensions that the BIG-IP system provides to help you further increase load balancing efficiency.
iRules are event-driven, which means that the BIG-IP system 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 BIG-IP system to trigger that iRule whenever that event occurs. Examples of event declarations that can trigger an iRule are HTTP_REQUEST, which triggers an iRule whenever the system receives an HTTP request, and CLIENT_ACCCEPTED, which triggers an iRule when a client has established a connection.
Figure 17.2 shows an example of an event declaration within an iRule.
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 17.1.
Table 17.1 iRule operators
Relational operators
contains
matches
equals
starts_with
ends_with
matches_regex
Logical operators
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 HTTP URI contains aol, send to pool aol_pool." Figure 17.2, shows an iRule that performs this action.
An iRule command within an iRule causes the BIG-IP system 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 iRule commands.
Commands that query or manipulate data
Some commands search for header and content data, while others perform data manipulation such as inserting headers into HTTP requests. An example of a query command is IP::remote_addr, which searches for and returns the remote IP address of a connection. An example of a data manipulation command is HTTP::header remove <name>, which removes the last occurrence of the named header from a request or response.
Utility commands
These commands are functions that are useful for parsing and manipulating content. An example of a utility command is decode_uri <string>, which decodes the named string using HTTP URI encoding and returns the result. For more information on using utility commands, see Utility commands.
As described in the previous section, iRule commands instruct the BIG-IP system to take direct action in some way. The following sections show examples of iRule commands that either direct traffic to a specific destination or assign translation addresses for SNAT implementation.
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 BIG-IP system to send a request. Figure 17.3 shows an example of this command.
Figure 17.3 Example of the pool command within an iRule
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 node command. Figure 17.4 shows an example of this command.
Figure 17.4 Example of the node command within an iRule
You can create an iRule that selects a server from a pool of cache servers. Figure 17.5 shows an iRule that selects a server from a pool of cache servers.
Note that the BIG-IP system redirects URIs to a new cache member at the time that the BIG-IP system receives a request for the URI, rather than when the pool member becomes unavailable.
In addition to configuring an iRule to select a specific pool, you can also configure an iRule to redirect an HTTP request to a specific location, using the HTTP::redirect iRule command. The location can be either a host name or a URI.
For example, Figure 17.6 shows an iRule that is configured to redirect an HTTP response.
Figure 17.7 shows an example of an iRule that redirects an HTTP request.
The iRules feature includes the two statement commands snat and snatpool. Using the snat command, you can assign a specified translation address to an original IP address from within the iRule, instead of using the SNAT screens within the Configuration utility.
Using the snatpool command also assigns a translation address to an original IP address, although unlike the snat command, the snatpool command causes the BIG-IP system to select the translation address from a specified SNAT pool that you previously created.
Important: When you create an iRule, the BIG-IP system places the iRule into your current administrative partition. For information on partitions, see the TMOSTM Management Guide for BIG-IP® Systems.
1.
On the Main tab of the navigation pane, expand Local Traffic, and click iRules.
The iRules screen opens.
Note: If the Create button is unavailable, this indicates that your user role does not grant you permission to create an iRule.
3.
In the Name box, type a 1- to 31-character name.
4.
In the Definition box, type the syntax for your iRule.
5.
Click Finished.
Important: Once you have created an iRule, you need to configure a virtual server to reference the iRule. For information on configuring a virtual server to reference an iRule, see Chapter 2, Configuring Virtual Servers.
An iRule can reference any object, regardless of the partition in which the referenced object resides. For example, an iRule that resides in partition_a can contain a pool statement that specifies a pool residing in partition_b.
You can remove iRule assignments only from virtual servers that reside in the current Write partition or in partition Common.
Note that you can associate an iRule only with virtual servers that reside in the current Write partition or in partition Common.
You can associate an existing iRule with multiple virtual servers. In this case, the iRule becomes the only iRule that is associated with each virtual server in the current Write partition. Because this command overwrites all previous iRule assignments, F5 does not recommend use of this command.
In a basic system configuration where no iRule exists, the BIG-IP system directs incoming traffic to the default pool assigned to the virtual server that receives that traffic. However, you might want the BIG-IP system 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 virtual server.
iRules are therefore evaluated whenever an event occurs that you have specified in the iRule. For example, if an iRule includes the event declaration CLIENT_ACCEPTED, then the iRule is triggered whenever the BIG-IP system accepts a client connection. The BIG-IP system then follows the directions in the remainder of the iRule to determine the destination of the packet.
Assign the iRule to a virtual server.
When an iRule is assigned to virtual server, this means that the virtual server references the iRule, similar to the way that a virtual server references a pool or a profile.
Ensure that the virtual server references the appropriate profile.
For example, if your iRule includes the event declaration HTTP_REQUEST, then the BIG-IP system only evaluates the iRule if the virtual server references an http profile type.
Note: When assigning an iRule that specifies the event HTTP_REQUEST, make sure that the virtual server references the appropriate profile type.
The iRules feature includes several types of event declarations that you can make in an iRule. Specifying an event declaration determines when the BIG-IP system 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.
SSL events, such as CLIENTSSL_HANDSHAKE
For a complete list of iRule events and their descriptions, see the F5 Networks DevCentral web site, http://devcentral.f5.com.
For every event that you specify within an iRule, you can also specify a context, denoted by the keywords clientside or serverside. Because each event has a default context associated with it, you need only declare a context if you want to change the context from the default.
For example, Figure 17.8 shows my_iRule1, which includes the event declaration CLIENT_ACCEPTED, as well as the iRule command IP::remote_addr. In this case, the IP address that the iRule command returns is that of the client, because the default context of the event declaration CLIENT_ACCEPTED is clientside.
Figure 17.8 An iRule that uses default clientside context
Similarly, if you include the event declaration SERVER_CONNECTED in an iRule as well as the iRule command IP::remote_addr, the IP address that the iRule command returns is that of the server, because the default context of the event declaration SERVER_CONNECTED is serverside.
Figure 17.8 shows what happens when you write an iRule that uses the default context when processing iRule commands. You can, however, explicitly specify the clientside and serverside keywords to alter the behavior of iRule commands.
Continuing with the previous example, Figure 17.9, shows the event declaration SERVER_CONNECTED and explicitly specifies the clientside keyword for the iRule command IP::remote_addr. In this case, the IP address that the iRule command returns is that of the client, despite the serverside default context of the event declaration.
You make an event declaration in an iRule by using the when keyword, followed by the event name. The previous figure shows an example of an event declaration in an iRule.
When you assign multiple iRules as resources for a virtual server, it is important to consider the order in which you list them on the virtual server. This is because the BIG-IP system 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 BIG-IP system from triggering subsequent events.
Note: If an iRule references a profile, the BIG-IP system processes this type of iRule last, regardless of its order in the list of iRules assigned to a virtual server.
Some of the commands available for use within iRules are known as statement commands. Statement commands enable the BIG-IP system to perform a variety of different actions. For example, some of these commands specify the pools or servers to which you want the BIG-IP system to direct traffic. Other commands specify translation addresses for implementing SNAT connections. Still others specify objects such as data groups or a persistence profiles.
For a complete list of statement commands, see the F5 Networks DevCentral web site, http://devcentral.f5.com.
Using iRules commands, you can query for specific data contained in the header or content of a request or response, or you can manipulate that data. Data manipulation refers to inserting, replacing, and removing data, as well as setting certain values found in headers and cookies.
For example, using the IP::idle_timeout command within in iRule, you can query for the current idle timeout value that is set in a packet header and then load balance the packet accordingly. You can also use the IP::idle_timeout command to set the idle timeout to a specific value of your choice.
iRule query and manipulation commands are grouped into categories called namespaces. Except for commands in the global namespace, each iRule query or manipulation command includes the namespace in its command name. For example, one of the commands in the IP namespace is IP::idle_timeout. One of the commands in the HTTP namespace is HTTP::header.
For a complete list of namespaces for iRules commands, see the F5 Networks DevCentral web site, http://devcentral.f5.com.
The BIG-IP system includes a number of utility commands that you can use within iRules. You can use these commands to parse and retrieve content, encode data into ASCII format, verify data integrity, and retrieve information about active pools and pool members.
When you are writing an iRule, you might want that iRule to recognize the value of a particular profile setting so that it can make a more-informed traffic management decision. Fortunately, the iRules feature includes a command that is specifically designed to read the value of profile settings that you specify within the iRule.
Not only can iRules read the values of profile settings, but they can also override values for certain settings. This means that you can apply configuration values to individual connections that differ from the values the BIG-IP system applies to most connections passing through a virtual server.
The iRules feature includes a command called PROFILE. When you specify the PROFILE command in an iRule and name a profile type and setting, the iRule reads the value of that particular profile setting. To do this, the iRule finds the named profile type that is assigned to the virtual server and reads the value of the setting that you specified in the PROFILE command sequence. The iRule can then use this information to manage traffic.
For example, you can specify the command PROFILE::tcp idle_timeout within your iRule. The BIG-IP system then finds the TCP profile that is assigned to the virtual server (for example, my_tcp) and queries for the value that you assigned to the Idle Timeout setting.
Some of the iRule commands for querying and manipulating header and content data have equivalent settings within various profiles. When you use those commands in an iRule, and an event triggers that iRule, the BIG-IP system overrides the values of those profile settings, using the value specified within the iRule instead.
For example, an HTTP profile might specify a certain buffer size to use for compressing HTTP data, but you might want to specify a different buffer size for a particular type of HTTP connection. In this case, you can include the command HTTP::compress_buffer_size in your iRule, specifying a different value than the value in the profile.
Chapter 7, Enabling Session Persistence, describes how to enable session persistence by configuring a persistence profile and assigning it to a virtual server. As described in that chapter, the BIG-IP system applies those persistence profile settings to every applicable session that passes through the virtual server. For example, if you have assigned the msrdp profile to the virtual server, then the BIG-IP system applies those settings to every incoming Microsoft® Remote Desktop Protocol (RDP) connection.
There are cases, however, when you might want to enable persistence in a more granular way. For example, instead of using the ssl persistence profile, which acts on non-terminated SSL traffic only, you might want to persist sessions based on SSL certificate status that you insert into the header of an HTTP request. To do this, you write an iRule using the HTTP::header command and then assign the iRule to the virtual server. Whenever the BIG-IP system accepts an SSL request, the iRule inserts the certificate status as a header into the request, and persists the session based on that status.
The BIG-IP system includes a special iRule command, persist, for implementing the types of session persistence described in Chapter 7, Enabling Session Persistence. You simply type the persist command in your iRule, specifying a persistence type.
For example, you can write an iRule that enables persistence for SSL connections when a particular event occurs, basing the persistence on the session ID. Figure 17.10 shows an example of an iRule that you could write to do this:.
You can use the persist none, hash, srcaddr, destaddr, and uie commands in any circumstance, even if a corresponding persistence profile is not configured and assigned to the virtual server. However, the persist ssl, cookie, msrdp, and sip commands require that you assign a corresponding persistence profile to the virtual server. Attempts to use these commands without a corresponding profile result in a run-time iRule error. For information on assigning a persistence profile to a virtual server, see Chapter 2, Configuring Virtual Servers.
Data groups are useful when writing iRules. A data group is simply a group of related elements, such as a set of IP addresses for AOL clients. When you specify a data group along with the matchclass command or the contains operator, you eliminate the need to list multiple values as arguments in an iRule expression.
Note: You can manage only those data groups that you have permission to manage, based on your user role and partition access assignment.
Warning: Do not attempt to modify or delete any of the three pre-configured data groups (private_net, images, and aol). Doing so can produce adverse results.
The BIG-IP system includes an iRule command called matchclass, which you can use to select a pool based on whether the command being used in the iRule represents a member of a specific data group. When you use the matchclass command, the BIG-IP system knows that the string following the identifier is the name of a data group.
For example, using the matchclass command, you can cause the BIG-IP system to load balance all incoming AOL connections to the pool aol_pool, if the value of the IP::remote_addr command is a member of the data group AOL. Figure 17.11 shows this type of iRule. In this case, the matchclass command simply indicates that the object named aol is a collection of values (that is, a data group).
Figure 17.11 An iRule based on the matchclass command
Note that an expression such as [IP::remote__addr] equals matchclass $::aol is true if the expression is true with at least one specific value in the data group.
When using the matchclass command within an iRule, you can specify any of three types of data groups:
1.
On the Main tab of the navigation pane, expand Local Traffic, and click iRules.
The iRules screen opens.
2.
On the menu bar, click Data Group List.
4.
In the Name box, type a unique name for the data group, such as my_address_group.
5.
In the Type box, select Address.
The screen expands to show more settings.
6.
7.
In the Address box, type the first IP address for the data group. If you are creating a network data group, also enter a network mask in the Mask box.
8.
Click Add.
The entry appears in the Address Records box.
10.
Click Finished.
A string data group contains a list of strings, such as *.jpg or *.gif. The following procedure creates a string data group.
1.
On the Main tab of the navigation pane, expand Local Traffic, and click iRules.
The iRules screen opens.
2.
On the menu bar, click Data Group List.
4.
In the Name box, type a unique name for the data group, such as my__images.
5.
In the Type box, select String.
The screen expands to show the string-specific settings.
6.
In the String box, type the first string for the data group.
7.
Click Add.
The entry appears in the String Records box.
9.
Click Finished.
1.
On the Main tab of the navigation pane, expand Local Traffic, click iRules.
The iRules screen opens.
2.
On the menu bar, click Data Group List.
4.
In the Name box, type a unique name for the data group, such as my__integer_group.
5.
In the Type box, select Integer.
The screen expands to display the Records section.
6.
In the Integer box, type the first integer for the data group.
7.
Click Add.
The entry appears in the Integer Records box.
9.
Click Finished.
When you create data groups, the BIG-IP system automatically saves them in their entirety in the bigip.conf file. This type of storage is known as in-line storage.
When any data in the data group needs to be updated, the entire data group must be reloaded. In general, in-line storage uses additional system resources due to extensive searching requirements on large data groups. Also, in-line storage requires you to reload entire data groups when incrementally updating data. For these reasons, the BIG-IP system offers you the ability to store you data groups externally, that is, outside of the bigip.conf file.
You have the option to store data groups in another location on the BIG-IP system, that is, outside of the bigip.conf file. Such data groups are called external data groups. Because the data group is stored externally in another location, the bigip.conf file itself contains only meta-data for the data group. The data in an externally-stored data group file is stored as a comma-separated list of values (CSV format).
Important: If you attempt to load a bigip.conf file that contains external data group meta-data, and the file was created prior to BIG-IP system version 9.4, the system generates an error. The meta-data for the external data group contains the keyword extern, which generates an error during the load process. On BIG-IP systems running version 9.4 or later, the extern keyword is no longer needed in the bigip.conf file.
Creating external data groups 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 an iRule uses a large data group to direct traffic to a pool.
An external data group must reside in either the /config or the /var/class directory. The default location for storing external data groups is the /config directory.
To implement an external data group, you must first use a text editor to create a text file according to the format specified in Figure 17.12. Then you can use the Configuration utility to create a data group of type (External File) that references the text file that you previously created.
1.
On the Main tab of the navigation pane, expand Local Traffic, and click iRules.
The iRules screen opens.
2.
On the menu bar, click Data Group List.
4.
In the Name box, type the name of the existing data group that you want to store in an external location.
5.
In the Type box, select (External File).
6.
In the Path / Filename box, type a path and file name for the external location, for example, /var/class/my_address_group.
This file name should match the name that you assigned to the data group itself.
Note: If you are storing the data group in the /config directory (the default location), you do not need to specify /config in the path name. Simply typing the file name of the data group is sufficient.
7.
In the File Contents box, select the file type that pertains to the data group (Address, String, or Integer).
8.
Click Finished.
The BIG-IP system stores the data in an external data group file in comma-separated lists, and the formats of any data values, such as IP addresses, match the formats used in the bigip.conf file. Figure 17.12 shows the contents of the data group file /config/ip2.data group.
network 195.93.32.0 mask 255.255.255.0,
network 195.93.33.0 mask 255.255.255.0,
network 195.93.34.0 mask 255.255.255.0,
network 195.93.48.0 mask 255.255.255.0,
network 195.93.49.0 mask 255.255.255.0,
network 195.93.50.0 mask 255.255.255.0
1.
On the Main tab of the navigation pane, expand Local Traffic, and click iRules.
The iRules screen opens.
2.
On the menu bar, click Data Group List.
3.
Click the name of a data group.
This displays the properties of that data group.
Using the Configuration utility, you can add members to or delete members from an existing data group if that data group is stored in line.
If the data group is stored externally, you can manage its members using the bigpipe utility. For more information, see the Bigpipe Utility Reference Guide.
1.
On the Main tab of the navigation pane, expand Local Traffic, and click iRules.
The iRules screen opens.
2.
On the menu bar, click Data Group List.
3.
Click the name of a data group.
This displays the properties of that data group.
5.
Click Add.
6.
Click Update.
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)