Controlling iRule Evaluation

In a basic system configuration where no iRule exists, the BIG-IP directs incoming traffic to the default pool assigned to the virtual server that receives that traffic. However, you might want the BIG-IP 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.

Rules 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 LTM system accepts a client request. The BIG-IP then follows the directions in the remainder or the iRule to determine the destination of the packet.

Configuration prerequisites

Before the BIG-IP can evaluate the iRule that you have written, you must do the following:

  • 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 only evaluates the iRule if the virtual server references an http profile type.

For information on assigning iRules and profiles to virtual servers, see Chapter 2, Configuring Virtual Servers, of the BIG-IP Configuration Guide.

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 BIG-IP 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:

  • Global events
  • HTTP events
  • SSL events
  • Authentication events

The following table lists and describes the events that you can declare in an iRule for each of these event types.

iRule Event Description
Global Events
CLIENT_ACCEPTED Triggered when a client establishes a connection.
CLIENT_DATA Triggered when a client receives new data while the connection is in collect state.
SERVER_SELECTED Triggered when the BIG-IP has selected a target node.
SERVER_CONNECTED Triggered when the system establishes a connection with the target node.
SERVER_DATA Triggered when the system has received new data from the target node while the connection is in hold state.
RULE_INIT Triggered when you add or modify an iRule. You use this event to initialize global variables that you are using within iRules.
HTTP Events
HTTP_REQUEST Triggered when the system fully parses a complete client request header (that is, the method, URI, version and all headers, not including the body).
HTTP_REQUEST_DATA Triggered whenever the request receives new HTTP content data.
HTTP_RESPONSE Triggered when the system parses all of the response status and header lines from the server response.
HTTP_RESPONSE_DATA Triggered whenever the system receives new HTTP content data from the response.
HTTP_RESPONSE_CONTINUE Triggered whenever the system receives a 100 Continue response from the server.
SSL Events
CLIENTSSL_HANDSHAKE Triggered when a client-side SSL handshake is completed.
CLIENTSSL_CLIENTCERT Triggered when the system adds an SSL client certificate to the client certificate chain. The BIG-IP can retrieve the X509 certificate and its X509 issuer with the SSL::cert and SSL::cert issuer commands.
SERVERSSL_HANDSHAKE Triggered when a server-side SSL handshake is completed.
Authentication Events
AUTH_FAILURE Triggered when an unsuccessful authorization operation is completed. A default handler for this event is associated with each of the authentication profiles, and causes the system to close the connection.
AUTH_ERROR Triggered when an error occurs during authorization. A default handler for this event is associated with each of the authentication profiles, and causes the system to close the connection. The associated authentication session ID is invalidated and the user should immediately discard the session ID upon receipt of this event.
AUTH_WANTCREDENTIAL Triggered when an authorization operation needs an additional credential. See also the description of the AUTH::wantcredential_prompt. command in section Querying Authentication Data. A default handler for this event is associated with each of the authentication profiles, and causes the system to close the connection unless it can obtain the desired credential. Typically this implies that the protocol layer that provides the credential has also not yet obtained the credential, because the system did not enable the necessary authentication protocol. Each of the authentication profiles contains appropriate default handlers for its respective protocol.
AUTH_SUCCESS Triggered when a successful authorization has completed all of the required authentication services.

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.

For example, Figure 1 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 1 An iRule that uses default clientside context

iRule my_iRule1 { 
    when CLIENT_ACCEPTED 
    if { [IP::remote_addr] eq 10.1.1.80 } { 
    pool my_pool1 
}

Likewise, Figure 2 shows my_iRule2, which includes the event declaration SERVER_CONNECTED, as well as the iRule command IP::remote_addr. In this case, 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 2 An iRule that uses default serverside context

iRule my_iRule2 { 
    when SERVER_CONNECTED 
    if { [IP::remote_addr] eq 10.1.1.80 } { 
    pool my_pool2 
}

The preceding two examples show 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 3 shows my_iRule3, which includes the event declaration SERVER_ACCEPTED 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.

Figure 3 An iRule that explicitly specifies iRule context

iRule my_iRule3 { 
    when SERVER_CONNECTED 
    if { clientside [IP::remote_addr] eq 10.1.1.80 } { 
    pool my_pool2 
}

Using the when keyword

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.

Listing iRules on 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 the BIG-IP 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 from triggering subsequent events.

Note


If an iRule references a profile, the BIG-IP processes this type of iRule last, regardless of its order in the list of iRules assigned to a virtual server.

Specifying statement commands

Some of the commands available for use within iRules are known as statement commands. Statement commands cause the BIG-IP to take direct action in some way. For example, some of these commands specify the pools or servers to which you want the BIG-IP to direct traffic. Other commands specify URIs or port numbers to which to redirect traffic, as well as translation addresses for implementing SNAT connections.

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

Statement Command Description
cache {
origin_pool
cache_pool
[hot_pool ]
[hot_threshold ]
[cool_threshold ]
[hit_period ]
[content_hash_size ]
[persist ]}
Dynamically chooses a pool to use (see the pool command) for load-balancing. If the evaluates to false, the origin pool is used. If true, the cache pool is used, unless the hot criteria is met and then the hot_pool is used. This statement can be conditionally associated with an if statement.
clientside {} Causes the specified iRule commands to be evaluated under the client-side context. This command has no effect if the iRule is already being evaluated under the client-side context.
detach Discontinues evaluating this iRule event on this connection. However, the iRule continues to run.
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.
forward Sets the connection to forward IP packets.
if { } {

}

elseif { } {

}

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 [ } Generates and logs the specified message to the Syslog facility. The statement does this by performing variable expansion on the message as defined for the Header Insert HTTP profile attribute.

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

matchclass Specifies a data group. Often used within an if statement and in conjunction with the contains operator.
[use] node [ ] Causes the identified server node to be used directly, thus bypassing any load-balancing.
peer { } Causes the specified iRule commands to be evaluated under the peer's (opposite) context.
persist Causes the BIG-IP to use the named persistence profile to persist the connection. For more information on using iRules to enable persistence, see Working with profiles.
[use] pool [member [ ]] Causes the BIG-IP 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.
[use] rateclass Causes the BIG-IP to select the specified rate class to use when transmitting packets.
reject Causes the connection to be rejected, returning a reset as appropriate for the protocol.
return [] Terminates execution of the iRule event and optionally return the result of evaluating .
serverside { } Causes the specified iRule commands to be evaluated under the server-side context. This command has no effect if the iRule is already being evaluated under the server-side context.
[use] snat [ ] Causes the BIG-IP to assign the specified translation address to one or more origin IP addresses specified in the iRule.
[use] snatpool Causes the pool of addresses identified by to be used as translation addresses to create a SNAT.