Manual Chapter : iRules

Applies To:

Show Versions Show Versions

BIG-IP LTM

  • 11.5.10, 11.5.9, 11.5.8, 11.5.7, 11.5.6, 11.5.5, 11.5.4, 11.5.3, 11.5.2, 11.5.1
Manual Chapter

iRules

Introduction to iRules

An iRule is a powerful and flexible feature within BIG-IP® Local Traffic Manager™ that you can use to manage your network traffic. Using syntax based on the industry-standard Tools Command Language (Tcl), the iRules® 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.

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.

   when CLIENT_ACCEPTED {
   if { [IP::addr [IP::client_addr] equals 10.10.10.10] } {
   pool my_pool
   }
   }
  

This iRule is triggered when a client-side connection has been accepted, causing Local Traffic Manager to send the packet to the pool my_pool, if the client’s 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 Local Traffic Manager provides to help you further increase load balancing efficiency.

Important: When referencing an object within an iRule, you must include the full path name of the object.

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 Local 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 Local Traffic Manager 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.

   when HTTP_REQUEST {
  if { [HTTP::uri] contains "aol" } {
     pool aol_pool
  } else {
     pool all_pool
 }
}
  

Operators

An iRule operator compares two operands in an expression.

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

iRule commands

An iRule command within an iRule causes Local 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.
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.

The pool command

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 Local Traffic Manager™ to send a request. Here is an example of this command.

   when HTTP_REQUEST {
  set uri [HTTP::uri]
  if { $uri ends_with ".gif" } {
     pool my_pool
  } elseif { $uri ends_with ".jpg" } {
     pool your_pool
 }
}
  

The node command

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.

   when HTTP_REQUEST {
  if { [HTTP::uri] ends_with ".gif" } {
     node 10.1.2.200 80
 }
}
  

Commands that select a pool of cache servers

You can create an iRule that selects a server from a pool of cache servers. Here is an example of an iRule that selects a server from a pool of cache servers.

when HTTP_REQUEST
   # This line specifies the expressions that determine whether the BIG-IP system sends requests to the cache pool:
   if { [HTTP::uri] ends_with "html" or [HTTP::uri] ends_with "gif" } {
      pool cache_pool 
      set key [crc32 [concat [domain [HTTP::host] 2] [HTTP::uri]]] 
      set cache_mbr [persist lookup hash $key node] 
      if { $cache_mbr ne "" } { 
        # This line verifies that the request is not coming from the cache:
        if { [IP::addr [IP::remote_addr] equals $cache_mbr] } 
          # This line sends the request from the cache to the origin pool:
             pool origin_pool
             return 
          } 
       } 
       # These lines ensure that the persistence record is added for this host/URI:
       persist hash $key
    } else { 
       pool origin_pool 
       } 
       }
Note: Local Traffic Manager™ 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.

The HTTP::redirect command

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.

This is an iRule that is configured to redirect an HTTP response.

   when HTTP_RESPONSE {
  if { [HTTP::status] contains "404"} {
    HTTP::redirect "http://www.siterequest.com/"
 }
}
  

Here is an example of an iRule that redirects an HTTP request.

   when HTTP_REQUEST {
  if { [HTTP::uri] contains "secure"} {
    HTTP::redirect "https://[HTTP::host][HTTP::uri]"
 }
}
  

The snat and snatpool commands

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 BIG-IP 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 Local Traffic Manager™ to select the translation address from a specified SNAT pool that you previously created.

iRules and administrative partitions

You should be aware of certain iRule configuration concepts as they relate to administrative partitions:

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

iRule evaluation

In a basic system configuration where no iRule exists, Local Traffic Manager™ directs incoming traffic to the default pool assigned to the virtual server that receives that traffic. However, you might want Local 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 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 Local Traffic Manager accepts a client connection. Local Traffic Manager then follows the directions in the remainder of the iRule to determine the destination of the packet.

Event types

The iRule command syntax includes several types of event declarations that you can specify within an iRule. For example:

  • Global events, such as CLIENT_ACCEPTED
  • HTTP events, such as HTTP_REQUEST
  • SSL events, such as CLIENTSSL_HANDSHAKE
  • Authentication events, such as AUTH_SUCCESS

For a complete list of iRule events and their descriptions, see the F5 Networks DevCentral web site, http://devcentral.f5.com.

iRule context

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.

The example 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.

when CLIENT_ACCEPTED {
  if { [IP::addr [IP::remote_addr] equals 10.1.1.80] } {
     pool my_pool1
 }
}

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.

The preceding example 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, the following example 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 server-side default context of the event declaration.

when SERVER_CONNECTED {
  if { [IP::addr [IP::addr [clientside {IP::remote_addr}] equals 10.1.1.80] } {
     discard
  } 
 }
Note: You make an event declaration in an iRule by using the when keyword, followed by the event name. The figure shows an example of an event declaration in an iRule.

iRules assignment to a virtual server

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 Local 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 Local Traffic Manager from triggering subsequent events.

Note: If an iRule references a profile, Local Traffic Manager processes this type of iRule last, regardless of its order in the list of iRules assigned to a virtual server.

iRule command types

There are three types of iRule commands:

  • Statement commands
  • Query and manipulation commands
  • Utility commands (also known as functions)

Statement commands

Some of the commands available for use within iRules are known as statement commands. Statement commands enable Local Traffic Manager™ to perform a variety of different actions. For example, some of these commands specify the pools or servers to which you want Local Traffic Manager 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.

Query and manipulation commands

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.

Utility commands

Local Traffic Manager 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.

iRules and profiles

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 Local Traffic Manager™ applies to most connections passing through a virtual server.

The profile command

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. Local Traffic Manager™ 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.

Commands that override profile settings

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, Local Traffic Manager™ 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.

Data groups

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 class match command or the contains operator, you eliminate the need to list multiple values as arguments in an iRule expression.

You can define three types of data groups: address, integer, and string.

The BIG-IP® system includes three pre-configured data groups: private_net, images, and aol.

To understand the usefulness of data groups, it is helpful to first understand the class match command and the contains operator.

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.

About the class match command

The BIG-IP® system includes an iRule command called class, with a match option, 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 class command, the BIG-IP system knows that the string following the identifier is the name of a data group.

For example, using the class 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. In this case, the class match command simply indicates that the object named aol is a collection of values (that is, a data group).

when CLIENT_ACCEPTED {
  if { [class match [IP::remote_addr] equals aol] } { 
     pool aol_pool
  } else {
     pool all_pool
 }
}

Storage options

With Local Traffic Manager™, you can store data groups in two ways, either in-line or externally.

In-line storage

When you create data groups, Local Traffic Manager automatically saves them in their entirety in the bigip.conf file. This type of storage is known as in-line storage.

In general, in-line storage uses additional system resources due to extensive searching requirements on large data groups. For this reason, Local Traffic Manager offers you the ability to store your data groups externally, that is, outside of the bigip.conf file file.

External storage

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 the filename and 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.

To create an external data group, you first import a file from another location, using the System options of the BIG-IP Configuration utility. You then use the Local Traffic iRules® screens to create an external data group that is based on the imported file.

External data groups can scale to greater than 10,000,000 entries, depending on platform hardware and available memory (8 GB, or more, memory is recommended). Data groups with larger data items can be supported with fewer entries. Additionally, updates to external data groups are completely atomic: for example, the system updates a data group only after the new data successfully completes loading. You can use the command [class exists xyz] to check whether a data group has finished loading.

iFiles

Using the BIG-IP Configuration utility, you can create a special file called an iFile. An iFile is a file that is based on an external file that you previously imported to the BIG-IP® system from another system. You can reference an iFile from within an iRule, based on a specific iRule event.

To create an iFile and use it within an iRule, you start from the Local Traffic option on the Main tab.

Important: Prior to creating an iFile, you must import a file to the BIG-IP system from another system.

iFile commands

With these iRule commands, you can reference the new iFile from within an iRule:

  • [ifile get IFILENAME]
  • [ifile listall]
  • [ifile attributes IFILENAME]
  • [ifile size IFILENAME]
  • [ifile last_updated_by IFILENAME]
  • [ifile last_update_time IFILENAME]
  • [ifile revision IFILENAME]
  • [ifile checksum IFILENAME]
  • array set [file attributes IFILENAME]
ltm rule ifile_rule {
     when HTTP_RESPONSE {
     # return a list of iFiles in all partitions
     set listifiles [ifile listall]
     log local0. "list of ifiles: $listifiles"
  
     # return the attributes of an iFile specified
     array set array_attributes [ifile attributes      "/Common/ifileURL"]     
     foreach {array attr} [array get array_attributes ] {
     log local0. "$array : $attr"
     }
  
     # serve an iFile when http status is 404.
     set file [ifile get "Common/ifileURL"]
     log local0. "file: $ifile"
     if { [HTTP::status] equals "404" } {
       HTTP:Respond 200 ifile "/Common/ifileURL"
  
    }
  }
  }