Manual Chapter :
Using Access iRule Events
Applies To:
Show Versions
BIG-IP APM
- 11.4.1, 11.4.0
An iRule is a powerful and flexible feature within the BIG-IP® Local Traffic ManagerTM system 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.
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 at 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. 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.
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 made up of these basic elements:
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.
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.
| Relational operators | |
| 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 15.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. |
| | 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. |
This table includes session variables and related reference information for each session variable that you can use with Access Policy Manager®.
Note: iRule event access policy items must be processed and completed before the access policy can continue.
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.
In this example, the system writes the browser user-agent to the log file when the session starts.
| log local0.notice "APM: Received a new session from browser: [ACCESS::session data get "session.user.agent"]" |
In this example, the system limits application access to the subnet 192.168.255.0 only.
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.
For example, you can further limit access based on specific session variables, rate controls, or HTTP or SSL properties of the user.
You can use ACCESS::session commands to get and set session variables in this event, and ACCESS::acl commands to enforce additional ACLs.
This event occurs when a resource request fails to meet the access control criteria and is denied access.
This event provides notification that a resource request has been denied to pass through the network.
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.
You can use ACCESS::session commands to get and set session variables in this event, and ACCESS::acl commands to enforce additional ACLs.
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.
This event allows you to insert an iRule event agent in an access policy at some point in the access policy:
On the server during access policy execution, the iRule event agent is executed and ACCESS_POLICY_AGENT_EVENT is raised in iRules®.
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.
Use ACCESS::disable to disable access functionality for a specific request. When you disable access functionality, all access checks are skipped for the current request. This command is applied to a single request only. For the next request on the same connection or flow, the system will process access checks, unless another ACCESS::disable event is invoked.
This command allows you to bypass or disable access control features selectively for a backend application.
For example, if the backend server has URIs that you dont want to protect, or you want to allow access without a valid session, you can use ACCESS::disable in your iRule to disable access checking for those URIs.
This returns the value of session variable. Admin can read multiple session variables in the single instance of this command.
This sets the value of session variable to be the given . Admin can set multiple session variables in the single instance of this command.
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.
This returns the identifier for the agent raising the ACCESS_CUSTOM_EVENT.
The ACCESS::policy command can only be used in ACCESS_POLICY_COMPLETED, ACCESS_ACL_ALLOWED and ACCESS_ACL_DENIED events.
This returns the result of ACL match for a particular URI in ACCESS_ACL_ALLOWED and ACCESS_ACL_DENIED events.
ACCESS::acl commands can only be used in 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.
