is a powerful and flexible feature within the BIG-IP®
Local Traffic Manager 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.
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.
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.
shows an example of an event declaration within an iRule.
For more information on iRule events, see the Configuration Guide for BIG-IP® Local Traffic Manager
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 D.1
| || |
| || |contains
| || |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 D.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 the Configuration Guide for BIG-IP® Local Traffic Manager
| || |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 the Configuration Guide for BIG-IP® Local Traffic Manager
This event occurs when a new user session is created. This is triggered after
creating the session context and initial session variables related to users source IP, browser capabilities and accepted languages.
This event provides a notification that a new session is created. You can use
this event to prevent a session from being created when a specific event occurs. For example, if the user is exceeding the concurrent sessions limit, or if the user does not qualify for a new session due to custom logic, you can prevent a session from starting.
You can use ACCESS::session commands to get and set various session
variables. Admin can also use TCP, SSL, and HTTP iRule commands to determine various TCP, SSL, or HTTP properties of the user.
This event provides a notification that access policy execution has
completed for the user. You can use this event to perform post-access-policy work. For example, you can read and set session variables after the access policy is executed.
You can use ACCESS::policy and ACCESS::session commands to get and
set various session variables. Admin can also use TCP, SSL, and HTTP iRule commands to determine various TCP, SSL, or HTTP properties of the user.
This event occurs when a resource request passes the access control criteria
and is allowed through the ACCESS filter. This event is only triggered for resource requests and does not trigger for internal access control URIs such as my.policy
This event notifies you that a resource request is being allowed to pass
through the network. You can use this event to create custom logic that is not supported in a standard ACL.
You can use this event to implement custom logic that is not supported in
the standard ACLs. For example, you can send out a specific response, based on specific session variables, and HTTP or SSL properties of the user. This event may also be useful for logging purposes.
This event occurs when a user session is removed. This can occur because a
user logs out, because the user session times out due to inactivity, or because the user session is terminated by an administrator.
You can use the ACCESS::session command to get session variables in this
event. iRule commands which require a flow context can not be used in this event.
You can get the current agent ID (using an iRule command ACCESS::policy
agent_id ) to determine which iRule agent raised the event, and to do create some customized logic.
Use this event to execute iRule logic inside TMM at the desired point in the
access policy execution. For example, if you want to do concurrent session checks for a particular AD group, insert this agent after the AD query, and once users group has been retrieved from AD query, check to see how many concurrent sessions exist for that user group in an iRule inside TMM.
This command disables the access control enforcement for a particular
request URI. The request passes through the access policy without any access control checks, except for checks that the session is valid and that the policy reaches an allow ending.
For example, ACCESS::session data get "session.user.clientip"
gets the users client IP address.
For example, ACCESS::session data set "myown_custom_variable" "my_value"
creates the custom variable myown_custom_variable
, and sets it to the value my_value
This deletes the user session and all associated session variables. The
session is removed immediately after this command is invoked and no session variables can be accessed after this command.
This commands returns TRUE when the session with provided sid exists,
and returns FALSE otherwise. This command is allowed to be executed in different events other then ACCESS events. One scenario for which you can use this command is to support a nonstandard HTTP application. The iRule verifies the MRHSession cookie, and provides a customized response that instructs the client to re-authenticate, as in the following example.
The ACCESS::policy command can only be used in
ACCESS_POLICY_COMPLETED, ACCESS_ACL_ALLOWED and ACCESS_ACL_DENIED events.
For example, to add an additional ACL named additional_acl
to a users request before allowing it to go through, use the following example.