iControl 101 - #09 - iRules

iRules are the internal scripting language of the BIG-IP and can be used to attain full control of traffic flowing through your network.  But, did you know that you can automate the management of iRules across your Virtual Servers with iControl?  This article will discuss the iControl methods that can be used to query, create, delete iRules as well as how to apply them to Virtual Servers.

The Interfaces

There are two interfaces that I will highlight in this article.  For the management of the iRules themselves such as querying, creating, and deleting, you will want to look in the LocalLB::Rule interface.  This fairly small interface (11 methods) gives you the power to have full control of the management of the iRules on the system.

Once you have created your iRules and are ready to put them into production, you'll want to head over to the LocalLB::VirtualServer interface.  iRules are attributes of a Virtual Server so, consequently, there are methods in there to add and remove configured rules to the specified Virtuals.

The following examples will use the iControl CmdLet's for Microsoft PowerShell as the iControl client.  If you are using one of the many other languages that are supported with iControl, the logic will be the same.  For these examples, the following setup is required for the iControl Cmdlets.

PS> Add-PSSnapIn iControlSnapIn
PS> Initialize-F5.iControl -Hostname bigip_address -Username username -Password password
PS> $ic = Get-F5.iControl

Determining the iRules on your system.

The LocalLB::Rule::query_all_rules() method will return an array of RuleDefinition structures, one for each iRule.  The RuleDefinition Structure contains the "rule_name" and "rule_definition".  The following example will call the query_all_rules() method and list out all of the Rule names followed by the actual iRule content (rule_definition).

PS> $RuleDefinitions = $ic.LocalLBRule.query_all_rules()
PS> $RuleDefinitions | Format-List
rule_name       : _sys_auth_ldap
rule_definition :     when HTTP_REQUEST {
                          if {not [info exists tmm_auth_http_sids(ldap)]} {
                              set tmm_auth_sid [AUTH::start pam default_ldap]
                              set tmm_auth_http_sids(ldap) $tmm_auth_sid
                              if {[info exists tmm_auth_subscription]} {
...

The LocalLB::Rule::query_rule() method is also available if you want to specify a specific list of iRules to query.

Creating an iRule

The LocalLB::Rule::create() method takes in an array of RuleDefinition structures defining the new iRules to be created.  For this example, I am allocating a single RuleDefinition structure for a single iRule and passing in an array size of one to the create method.  I will then call the query_rule() method to show you the creation took effect.

PS> $RuleDefinition = New-Object -TypeName iControl.LocalLBRuleRuleDefinition
PS> $RuleDefinition.rule_name = "MyCoolRule"
PS> $RuleDefinition.rule_definition = @"
>> when HTTP_REQUEST {
>>   log local0. {URI: [HTTP::uri]}
>> }
>> "@
>>
PS> $ic.LocalLBRule.create( (,$RuleDefinition) )
PS> $ic.LocalLBRule.query_rule( (,"MyCoolRule") ) | Format-List
rule_name       : MyCoolRule
rule_definition : when HTTP_REQUEST {
                    log local0. {URI: [HTTP::uri]}
                  }

Deleting an iRule

Deleting an iRule is as simple as passing the rule name to the LocalLB::Rule::delete_rule() method.  The following sample will delete the previously created "MyCoolRule" iRule and then attempt to query it again and show the exception that is thrown as a result of the requested iRule name not existing on the system.

PS> $ic.LocalLBRule.delete_rule( (,"MyCoolRule") )
PS> $ic.LocalLBRule.query_rule( (,"MyCoolRule") ) | format-list
Exception calling "query_rule" with "1" argument(s): "Exception caught in LocalLB::Rule::query_rule()
Exception: Common::OperationFailed
    primary_error_code   : 16908342 (0x01020036)
    secondary_error_code : 0
    error_string         : 01020036:3: The requested rule (MyCoolRule) was not found."
At line:1 char:27
+ $ic.LocalLBRule.query_rule( <<<<  (,"MyCoolRule") ) | format-list

Applying the iRule to a Virtual Server

Now, go ahead and recreate that iRule by calling the create() method again.  Once you've got the iRule in place, You'll want to jump over to the LocalLB::VirtualServer interface and it's add_rule() method.  This method takes an array of virtual servers and a 2-d array for the iRules (1-n iRules for each virtual server passed in).

PS> # Create the iRule
PS> $ic.LocalLBRule.create( (,$RuleDefinition) )
PS>
PS> # Allocate and populate parameters
PS> $VirtualServerRule = New-Object -TypeName iControl.LocalLBVirtualServerVirtualServerRule
PS> $VirtualServerRule.rule_name = "MyCoolRule"
PS> $VirtualServerRule.priority = 500
PS> $VirtualServerRules = New-Object -TypeName "iControl.LocalLBVirtualServerVirtualServerRule[][]" 1,1
PS> $VirtualServerRules[0][0] = $VirtualServerRule
PS>
PS> # Call add_rule to add the iRule to the specified virtual servers resource list.
PS> $ic.LocalLBVirtualServer.add_rule( (,"virtual_name"), $VirtualServerRules )
PS>
PS> # Call get_rule to make sure the add_rule call worked.
PS> $ic.LocalLBVirtualServer.get_rule( (,"virtual_name") ) | format-list
rule_name : MyCoolRule
priority  : 500

Conclusion

While the iRule Editor makes this easy to do on a single system, there may be a time when you need to deploy an iRule to multiple systems and an automated approach sounds more appealing than the manual effort required for mass deployment.  In this case, whip out your favorite programming language, spend a couple of minutes building a solution, click "GO" and grab a cup of coffee and relax.