K13033: Constructing CMP-compatible iRules

Non-Diagnostic

Original Publication Date: Mar 10, 2015

Update Date: Jul 13, 2019

Topic iRules use global variables to make variable data available to other connections, virtual servers, and Traffic Management Microkernel (TMM) instances. If a virtual server references an iRule that uses a global variable that is not compatible with Clustered Multiprocessing (CMP), the virtual server is ineligible for CMP processing. In most cases, F5 recommends retaining the benefits of CMP processing when using iRules.

This article details the various ways to represent global variable data to make it available to other connections, virtual servers, and TMM instances.

Prerequisites

To benefit from this article, you should be familiar with the following topics:

CMP for your version, as described in one of the following articles: K14358: Overview of Clustered Multiprocessing (11.3.0 and later) K14248: Overview of Clustered Multiprocessing (11.0.0 - 11.2.x) K7751: Overview of Clustered Multiprocessing (9.x - 10.x) Construction of iRules that use variables

Description

In many cases, you may require variable data in an iRule to be available only within the of the current connection. The use of Tool Command Language () local variables satisfies this requirement and does not affect CMP compatibility.

In other cases, you may require variable data to be available globally, outside the context of a connection. The most common requirement is to be able to capture data from one connection and then to reference that data from subsequent connections, which are part of the same session. You can further refine this requirement to include multiple connections traversing the same TMM instance, such as on a system or virtual server without CMP enabled, or on multiple related connections on CMP-enabled virtual servers which may traverse different TMM instances.

You can also use global variables to share data among multiple iRules running on the same BIG-IP system. For example, in order to set and enforce a cumulative concurrent connection limit, an iRule must set a globally accessible limit value and also allow each iRule instance to update a separate globally accessible counter value. Using global variables can force the BIG-IP system to automatically disable CMP processing. This is known as demotion. Demotion of a virtual server limits processing of that virtual server to only one CPU core, which can adversely affect performance on multi-core BIG-IP systems because only a fraction of the available CPU resources is available for each demoted virtual server. In addition, CMP demotion can create an internal communication bottleneck for virtual servers that are enabled for WebAccelerator or BIG-IP ASM.

The following sections explain each of three popular methods for globally sharing data derived by iRules, including the CMP compatibility of each method.

Using Tcl global variables Using static global variables Using the session table to store global variable data

Using Tcl global variables

Tcl global variables are not actually global on a BIG-IP system with CMP enabled because the TMM instances do not share them. Tcl global variables are globally accessible only within the local TMM instance. This means that each TMM instance needs to separately set and update its own copy of the variable and the value of the variable. As a result, the TMM process running on one processor cannot access the contents of the same Tcl global variable set by a different TMM process, even if both TMM processes are handling connections for the same virtual server. Because of this limitation, using a Tcl global variable in an iRule automatically demotes any virtual server to which the iRule is applied. This demotion avoids the confusion that might otherwise result from accessing and updating multiple instances of the same global variable. Because the virtual server is automatically demoted from CMP, F5 recommends that you restrict the use of Tcl global variables to iRules to virtual servers that do not depend on CMP processing.

Important: A known issue prevents automatic demotion of virtual servers which reference but do not set. For more information, refer to K13259: A virtual server that references an iRule using a global variable may not be demoted from CMP.

You can identify the Tcl global variable by using the :: or $:: prefix. For example, a line of code setting a value to a global variable ::example may appear similar to the following example: set ::example 0

A line of code referencing a global variable ::example may appear similar to the following example: puts $::example

Using static global variables

If you need to share data that the iRule will never modify across CMP-enabled virtual servers, you can use a static global variable. A static global variable stores data globally to the entire BIG-IP system and is set within each TMM instance each time the iRule is started. The value of a static global variable does not change unless the iRule is restarted. Static global variables must be set within the RULE_INIT event and propagate to all TMM instances each time the iRule is started, which includes when the iRule loads at system startup, when you reload the configuration, or when you modify and save the iRule using the Configuration utility.

Important: While you can use the set command to modify a static global variable within an iRule and outside of the RULE_INIT event, such modifications do not propagate to each TMM instance. Instead, they are visible to only the TMM process on which you make the modification. This may result in inconsistent values for the static global variable across TMM instances. As a result, F5 strongly recommends that you do not update the value of any static global variable within the iRule.

To use static global variables, use the $static:: variable syntax. For example, the following iRule sets a static global variable and then reads it: when RULE_INIT { # Change to "1" to enable debugging log statements set static::debug 0 } when HTTP_REQUEST { if { $static::debug != 0 } { log local0. "Got HTTP request: [HTTP::host] ; [HTTP::uri]" }

Note: For BIG-IP GTM static global variables, use the $::static:: variable syntax. For example: when RULE_INIT { # Log debug to /var/log/ltm? 1=yes 0=no. set ::static::tdebug 1 } when LB_SELECTED { if { $::static::tdebug } { log local0. "Client IP: [IP::client_addr]" } }

Any iRule running on a virtual server on the entire BIG-IP system can read the static global variable debug, and CMP compatibility is preserved for any virtual server to which you apply the iRule. In the previous example, since the static::debug global variable is set to 0, the iRule does not log the HTTP host or URI. The most efficient way to change the debug option to 1 on a live BIG-IP system is to modify the iRule using the Configuration utility and save the changes. The changes are then propagated to each TMM instance.

Using the session table to store global variables

If you need to share non-static global data across CMP-enabled virtual servers, you can use the session table to store and reference the data. Session table data is shared among all TMM instances. Using the session table requires more operational overhead, but the benefit of preserving CMP processing for the virtual server typically outweighs this impact.

You can use the table command to manipulate the session table. For more information, refer to The table Command: on DevCentral and table on F5 Cloud Docs. Recommendations

There are several options to choose from when using global variables or the equivalent functionality in session tables. Each of these options has advantages and disadvantages, and you should make your decision about whether or not to use them based on your performance and implementation requirements. F5 makes the following recommendations:

Restrict the use of Tcl global variables to iRules that you apply to virtual servers which do not depend on CMP processing. Use static global variables for sharing static data (data that iRules will not update) among TMM instances that CMP-enabled virtual servers use, or use them for sharing static data among multiple iRules without affecting the CMP status of any virtual server to which it an iRule is applied. Use session tables for sharing global, dynamic data (data that iRules will update) among CMP- enabled virtual servers.

Supplemental Information

static - iRules on F5 Cloud Docs CMP Compatibility - iRules on F5 Cloud Docs class - iRules on F5 Cloud Docs

Applies to:

Product: BIG-IP, BIG-IP AAM, BIG-IP AFM, BIG-IP Analytics, BIG-IP APM, BIG-IP ASM, BIG-IP GTM, BIG- IP Link Controller, BIG-IP LTM, BIG-IP PEM 15.X.X, 14.X.X, 13.X.X, 12.X.X, 11.X.X, 10.X.X

Product: Legacy Products, BIG-IP Edge Gateway, BIG-IP PSM, BIG-IP WebAccelerator, BIG-IP WOM 15.X.X, 14.X.X, 13.X.X, 12.X.X, 11.X.X, 10.X.X