Manual Chapter : Using Access iRule Events

Applies To:

Show Versions Show Versions

BIG-IP APM

  • 11.4.1, 11.4.0
Manual Chapter
15 
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.
Figure 15.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 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.
Figure 15.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 15.1.
Table 15.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 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®.
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.
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.
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.
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.
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.
For example, ACCESS::session data get "session.user.clientip" gets the users client IP address.
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.
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.
For example, to add an additional ACL named additional_acl to a users request before allowing it to go through, use the following example.