An iRule is a powerful and flexible feature of BIG-IP devices based on F5's exclusive TMOS architecture. iRules provide you with unprecedented control to directly manipulate and manage any IP application traffic. iRules utilizes an easy to learn scripting syntax and enables you to customize how you intercept, inspect, transform, and direct inbound or outbound application traffic. In this series of tech tips, we'll talk about the TCL language, it's usage and control structures, as well as iRule extensions to the TCL language. Other articles in the series:
An iRule consists of one or more event declarations, each containing TCL code that is executed when that event occurs. First, it will be helpful to explain what an event is.
Event
An event is an extension to TCL that F5 has added to facilitate modular based programming. Between the time when a connection flows into TMOS, and out the other side, there are a series of internal states that are reached by that connection. Each of these states equate to an event in the iRule language. These states, such as CLIENT_ACCEPTED, can occur globally in scope (meaning they happen for all connections regardless of which profiles are applied to the virtual servers). Or they can be profile specific (HTTP_REQUEST, CLIENTSSL_CLIENTCERT, RTSP_RESPONSE, ...) meaning that their states are only reached if a certain profile is assigned to the virtual server. An event is declared using the F5-added "when" statement.
when EVENT_NAME { TCL-CODE }
For a list of the available events, refer to the iRule Events on Cloud Docs.
The key benefit to take away from events is that they allow iRules to be broken into logical pieces and executed in a non-serial manner. This means that only the code for a specific event is executed when that event occurs.
TCL
iRules use a TCL runtime engine to execute the script logic. The documentation for the TCL language can be found at http://tmml.sourceforge.net/doc/tcl/index.html. The TCL language can be broken down into operators and commands. In TCL, essentially everything is considered a command. We've taken the various commands and segmented them into three types: functions, statements, and commands.
Operators
An operator is a token that "operates" on other values. When you compare two values, you will use an operator to do the comparison. In addition to the builtin TCL operators (==, <=, >=, ...), operators such as "starts_with", "contains", and "ends_with" have been added to act as helpers for common comparisons. A list of the iRules added/enhanced operators can be found here.
Functions
Functions are utility commands that, most often, return a value. Functions like "findclass" and "matchclass" assist in Data Group access, while "findstr", "getfield", and "substr" assist in working with strings. A full list of F5 added functions are on the iRules functions.
Statements
Statements are commands that typically don't return a value. The purpose of a statement is, basically, to "do something". You can use TCL's "if" and "switch" statements to perform conditional tests, or you could use the iRules specific statement "log" to log messages to the system log, or "pool" to assign a load balancing decision to a specified pool of servers. A full list of iRules specific statements can be found in the iRules Statements.
Commands
Commands are pretty much every other control structure you can use within TCL. With commands, you can do things like getting the URI of a HTTP Request (HTTP::uri), or encrypting data with an AES key (AES::encrypt). The extensive list of commands are documented in the iRules Commands wiki document.
Several commands within the TCL language have been disabled in the iRules implementation. Basically, any command that could cause an unexpected halt in the traffic flow (file IO, Socket calls, procedures, ...) have been removed. A list of disabled commands can be found here.
In addition to the standard TCL command set, F5 has added additional commands that are either global in scope (TCP::client_port, IP::addr, ...) or specific to a certain profile (HTTP::uri, SIP::call_id, ...). The full list of commands can be found in the command section of the iRules on Cloud Docs.
Putting it all together
The following iRule contains several events, operators, functions, statements, and commands.
whenHTTP_REQUEST { if { [HTTP::uri] starts_with "/foobar" } { switch -glob [HTTP::uri] { "*[0-9].jpg" { pool numbers_pool } default { if { [string length [substr [HTTP::uri] 0 "?"]] > 0 } { HTTP::respond 200 content "<html><head><title>Where's the number?</title></head></body><h1>Where's the number?</h1></body></html>" } } } } } whenHTTP_RESPONSE { if { [HTTP::header Content-Length] > 100 } { log local0. "too much data requested." drop } }
Questions
Can you identify all operators, functions, statements, and commands?
What is "default" in the switch statement?
What happens with the Content-Length header is empty in the HTTP Response?
What's the difference with -glob in a switch statement and a full blown regular expression?
When do you need to use brackets around functions, statements, and commands?
Conclusion
In this article, we've gone over the basic components of the iRules language. In future articles in this series, we'll dig deeper into the various components of iRules and how to make best use of those features.
In the iRule example the "if" condition will always be true. URI's always start with a "/" so the string length should be checking for greater than 1 and not 0. Also the subst command duplicates the functionality of the [HTTP::path] command however that command may be newer than this article as it was released in version 9.0.0.
