iRules 101 - #01 - Introduction to iRules

Joe Pruitt, 2007-01-11

Introduction
An iRule is a powerful and exible 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 trafc. iRules utilizes an easy to
learn scripting syntax and enables you to customize how you intercept, inspect, transform, and direct inbound or
outbound application trafc.
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:
iRules 101 #01 Introduction to iRules
iRules 101 #02 If and Expressions
iRules 101 #03 Variables
iRules 101 #04 Switch
iRules 101 #05 Selecting Pools, Pool Members, and Nodes
iRules 101 #06 When
iRules 101 #07 Catch
iRules 101 #08 Classes
iRules 101 #09 Debugging
iRules 101 #10 Regular Expressions
iRules 101 #11 Events
iRules 101 #12 The Session Command
iRules 101 #13a Nested Conditionals
iRules 101 #13b TCL String Commands Part 1
iRules 101 #14 TCL String Commands Part 2
iRules 101 #15 TCL List Handling Commands
iRules 101 #16 Parsing String with the TCL Scan Command
iRules 101 #17 Mapping Protocol Fields with the TCL Binary Scan Command

Components of an iRule
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 ows 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 proles are applied to the
virtual servers). Or they can be prole specic (HTTP_REQUEST, CLIENTSSL_CLIENTCERT, RTSP_RESPONSE, ...)
meaning that their states are only reached if a certain prole is assigned to the virtual server. An event is declared using
the F5-added "when" statement.

whenEVENT_NAME{TCLCODE}

For a list of the available events, refer to the iRule Events wiki document.
The key benet to take away from events is that they allow iRules to be broken into logical pieces and executed in a non-

For a list of the available events, refer to the iRule Events wiki document.
The key benet to take away from events is that they allow iRules to be broken into logical pieces and executed in a nonserial manner. This means that only the code for a specic 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 "ndclass" and "matchclass" assist in
Data Group access, while "ndstr", "geteld", and "substr" assist in working with strings. A full list of F5 added functions
are on the iRules functions wiki document.
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
specic statement "log" to log messages to the system log, or "pool" to assign a load balancing decision to a specied
pool of servers. A full list of iRules specic statements can be found in the iRules Statements wiki document.
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 trafc ow (le 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 specic to a certain prole (HTTP::uri, SIP::call_id, ...). The full list of commands can be
found in the command section of the iRules wiki.
Putting it all together
The following iRule contains several events, operators, functions, statements, and commands.
when HTTP_REQUEST{if{[HTTP::uri]starts_with"/foobar"}{switchglob[HTTP::uri]{"*[09].j

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?

poolnum

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.
Links
TCL Reference - http://tmml.sourceforge.net/doc/tcl/index.html
iRules Events - https://devcentral.f5.com/wiki/default.aspx/iRules.Events
iRules Functions - https://devcentral.f5.com/wiki/default.aspx/iRules.Functions
iRules Statements - https://devcentral.f5.com/wiki/default.aspx/iRules.Statements
iRules Commands - https://devcentral.f5.com/wiki/default.aspx/iRules.Commands
iRules Operators - https://devcentral.f5.com/wiki/default.aspx/iRules.Operators
Disabled TCL Commands - https://devcentral.f5.com/wiki/default.aspx/iRules/DisabledTclCommands.html
Get the Flash Player to see this player.

F5 Networks, Inc. | 401 Elliot Avenue West, Seattle, WA 98119 | 888-882-4447 | f5.com
F5 Networks, Inc.
Corporate Headquarters
info@f5.com

F5 Networks
Asia-Pacific
apacinfo@f5.com

F5 Networks Ltd.
Europe/Middle-East/Africa
emeainfo@f5.com

F5 Networks
Japan K.K.
f5j-info@f5.com

2016 F5 Networks, Inc. All rights reserved. F5, F5 Networks, and the F5 logo are trademarks of F5 Networks, Inc. in the U.S. and in certain other countries. Other F5
trademarks are identified at f5.com. Any other products, services, or company names referenced herein may be trademarks of their respective owners with no
endorsement or affiliation, express or implied, claimed by F5. CS04-00015 0113