F5 BIG-IP X-Client-IP iRule for SOAP-to-REST Worker

Overview

The F5 BIG-IP X-Client-IP iRule is a Traffic Control Language (TCL) script designed for F5 BIG-IP Local Traffic Managers (LTM). Its primary purpose is to ensure accurate client IP attribution for SOAP requests processed by the SOAP-to-REST worker.

Without this iRule, all SOAP requests ingested by the SOAP-to-REST worker appear to originate from the F5 SNAT pool address. This obscures the real client's IP address, making it difficult to track individual consumers. The iRule solves this by injecting the pre-SNAT source IP into the X-Client-IP request header. The SOAP-to-REST worker's resolveEffectiveClientIp() method prioritizes this header to correctly attribute traffic to individual API consumers.

This iRule operates on HTTP events within the F5 BIG-IP LTM, acting as an intermediary between the client and the SOAP-to-REST worker. It modifies the incoming HTTP request by adding the X-Client-IP header before forwarding the request to the backend.

How it Works

The X-Client-IP iRule operates by intercepting HTTP requests on a configured F5 BIG-IP Virtual Server.

1. Request Ingress: A SOAP request from an API consumer arrives at an F5 BIG-IP Virtual Server.
2. iRule Trigger: If an HTTP profile is enabled on the Virtual Server, the x-client-ip-injection iRule (or similarly named rule) is triggered by the HTTP_REQUEST event.
3. IP Capture: The iRule captures the original source IP address of the client before any Source Network Address Translation (SNAT) occurs.
4. Header Injection: The iRule then injects this pre-SNAT source IP into the X-Client-IP HTTP request header.
5. Request Forwarding: The modified request, now containing the X-Client-IP header, is forwarded to the SOAP-to-REST worker.
6. Worker Processing: The SOAP-to-REST worker's resolveEffectiveClientIp() method reads the X-Client-IP header. This method prioritizes the X-Client-IP header to identify the true client IP, rather than the F5 SNAT pool address.

For this mechanism to function, the iRule must be bound to each Virtual Server whose pool members include the SOAP backend services proxied through the SOAP-to-REST relay. The iRule must also be configured to execute last in the iRule priority order if other iRules are present that might modify or remove the X-Client-IP header.

Prerequisites

To implement and operate the X-Client-IP iRule, the following prerequisites must be met:

• F5 BIG-IP LTM: Version 11.4 or later, which supports iRules TCL 6.x.
• HTTP Profile: An HTTP profile must be enabled on the target Virtual Server. iRules only fire on HTTP events, and HTTP::header commands (used by this iRule) require an HTTP profile.

Installation Example (TMSH CLI)

This example demonstrates how to install and bind the iRule using the F5 BIG-IP Traffic Management Shell (TMSH).

1. Create the iRule: Execute the following command on the BIG-IP shell or via SSH. Replace ... paste the TCL body from x-client-ip.tcl here... with the actual TCL script content. The source does not provide the content of x-client-ip.tcl.

tmsh create ltm rule x-client-ip-injection {
# paste the TCL body from x-client-ip.tcl here
}

2. Bind to a Virtual Server: Modify the target Virtual Server to add the newly created iRule. Replace <vs-name> with the name of your Virtual Server.

tmsh modify ltm virtual <vs-name> rules add { x-client-ip-injection }

3. Save Configuration: Save the system configuration to persist the changes.

tmsh save sys config

Expected Result: After successful installation and binding, the SOAP-to-REST worker will correctly identify the real client IP address. This will manifest in:

• The client_ip field in ingested traffic logs showing the real consumer IP.
• The "Top Consumers" tile in Observability displaying individual IP addresses instead of a single F5 SNAT pool entry.
• Per-consumer filtering in the Live Traffic Log functioning as expected.

API / CLI Reference

This section details the command-line interface (CLI) and REST API methods for managing the F5 BIG-IP X-Client-IP iRule.

CLI Commands (TMSH)

The following TMSH commands are used for iRule management:

• tmsh create ltm rule <name> {... }

• Purpose: Creates a new Local Traffic Manager (LTM) iRule with the specified name and TCL definition.

• Inputs:

• <name>: The desired name for the iRule (e.g., x-client-ip-injection).

• {... }: The TCL script body of the iRule.

• Outputs/Effects: Creates an iRule object in the F5 BIG-IP configuration.

• tmsh modify ltm virtual <vs-name> rules add { <irule-name> }

• Purpose: Binds an existing iRule to a specified Virtual Server.

• Inputs:

• <vs-name>: The name of the Virtual Server to which the iRule will be bound.

• <irule-name>: The name of the iRule to add (e.g., x-client-ip-injection).

• Outputs/Effects: Associates the iRule with the Virtual Server, causing it to execute for traffic processed by that VS.

• tmsh save sys config

• Purpose: Saves the current running configuration to disk, making changes persistent across reboots.

• Inputs: None.

• Outputs/Effects: Persists configuration changes.

• tmsh list ltm virtual recursive | grep -E 'ltm virtual |pool '

• Purpose: Lists all Virtual Servers and their associated pools, useful for identifying which Virtual Servers are forwarding to SOAP backend services.

• Inputs: None.

• Outputs/Effects: Prints a filtered list of Virtual Servers and their pool configurations to standard output.

• tmsh list ltm virtual <vs> rules

• Purpose: Lists the iRules currently bound to a specific Virtual Server.

• Inputs:

• <vs>: The name of the Virtual Server.

• Outputs/Effects: Displays the iRules associated with the specified Virtual Server.

REST API Endpoint

• POST https://<f5-mgmt>/mgmt/tm/ltm/rule
• Purpose: Creates a new LTM iRule via the F5 BIG-IP REST API.
• Method: POST
• Inputs (Request Body - JSON):
• name: (String) The name for the iRule (e.g., "x-client-ip-injection").
• partition: (String) The partition where the iRule will reside (e.g., "Common").
• apiAnonymous: (String) The TCL script body of the iRule (e.g., "when HTTP_REQUEST {... }").
• Example Request:

curl -sk -u admin:<password> \
-X POST https://<f5-mgmt>/mgmt/tm/ltm/rule \
-H 'Content-Type: application/json' \
-d '{
"name": "x-client-ip-injection",
"partition": "Common",
"apiAnonymous": "when HTTP_REQUEST {... }"
}'

• Outputs/Effects: Creates an iRule object on the F5 BIG-IP. The source does not specify success or error responses.

Configuration Reference

The primary configuration for this component is the iRule itself, which is defined by its name and TCL script body.

| Name | Type | Default | Required | Description | | name | string | — | Yes | The name of the iRule. For example, x-client-ip-injection. This name is used to reference the iRule when binding it to Virtual Servers. | | apiAnonymous | string | — | Yes | The TCL script content of the iRule. This is the core logic that injects the X-Client-IP header. The source does not provide the exact script content.

---

All SOAP-to-REST docs