DocsICP FilingConsole
Documentation
Home Page Edge Security Acceleration ESA (Next-Gen) User Guide Rules Set up rules Transform rules Modify incoming request headers

Modify incoming request headers

Updated at:
Copy as MD
Product
My Favorites

Add, modify, or delete specific incoming request headers at the edge to control what your backend receives—for example, injecting Accept-Encoding or Accept-Language headers to customize visitor experiences and track usage behavior.

Overview

The modify incoming request headers feature lets you add, modify, or delete request headers at edge nodes before requests reach your origin. This lets you:

  • Controlling back-to-origin routing — Add or modify headers to control how origin servers handle requests.

  • Enriching backend logs — Pass client information (such as originating IP addresses) through custom headers for logging and analytics.

  • Removing irrelevant headers — Delete unnecessary headers from the original request to reduce overhead and improve security.

Configure incoming request headers

Prerequisites

Before you begin, make sure that you have:

  • Created a site in the ESA console. For more information, see Rule Precedence.

  • Enabled the Rules feature for your site.

Steps

  1. In the ESA console, select Websites, and in the Website column, click the target site.

  2. In the left navigation pane, choose Rules > Transform Rules.

  3. Click the Modify request header > Client to ESA > Create Rule.

    Add rule

  4. In the Add Request Header Modification Rule area, configure the following fields:

    • Rule Name: Enter a custom name for the rule.

    • If requests match...: Select the condition that determines which requests the rule applies to.

      • All Requests: The rule applies to all requests for the current site.

      • Filtered Requests: The rule applies only to traffic that matches a custom expression. Configure an expression to filter traffic.

    • Modify Request Header: Specify the action to perform on matching requests. Use the following table to choose the operation type and mode.

      Operation

      Mode

      Description

      Example

      Add

      Static

      Ensures the specified request header is present in the origin request. Creates the header if it does not exist, or overwrites the existing header with the same name.

      To add a request header named x-code with the value key1, enter:
      - Header Name: x-code
      - Header Value: key1

      Dynamic

      The header value can be set to an expression.

      To add a request header named True-Client-IP with the value ip.src to record the client's originating IP address, enter:
      - Header Name: True-Client-IP
      - Header Value: ip.src

      Modify

      Static

      Changes the value of a specified request header in the origin request. Takes effect only if a header with the specified name already exists; otherwise, no action is taken.

      To change the value of the request header named x-code to key2 in the origin request, enter:
      - Header Name: x-code
      - Header Value: key2

      Dynamic

      The header value can be set to an expression.

      To change the request header named True-Client-IP to the value ip.src in the origin request, setting its value to the client's originating IP address, enter:
      - Header Name: True-Client-IP
      - Header Value: ip.src

      Delete

      Removes all headers from the origin request that match the specified Header Name, regardless of whether duplicate headers exist.

      To delete the request header named x-code, enter the Header Name: x-code.
Note

  • Request header names starting with ali-swift, ali-esa-inner, x-swift, or x-site cannot be configured (case-insensitive).

  • To specify multiple values for Header Value, separate them with a comma (,).

  • The Delete operation works the same way for both Static and Dynamic modes. The Modify operation takes effect only if the original request contains a header with the specified name; otherwise, no action is taken.

  • Within a single rule, multiple operations are executed sequentially. If different operations target the same header name, the last operation overwrites the previous ones.

Dynamic expression configuration examples

This example shows how to add a dynamic expression that passes the client's originating IP address in a custom request header.

Add a dynamic expression for True-Client-IP-IN

Procedure

  1. In the ESA console, select Websites, and in the Website column, click the target site.

  2. In the left navigation pane, choose Rules > Transform Rules.

  3. Click the Modify request header > Client to ESA > Create Rule.

    Add rule

  4. In the Add Incoming Request Header area, configure the following fields:

    • Rule Name: Enter add-client-ip-in.

    • Match Condition: Select All Requests to apply the rule to all requests for the current site.

    • Header Operation:

      • Type: Dynamic

      • Operation: Add

      • Header Name: True-Client-IP-IN

      • Header Value: ip.src

    Expression configuration

Verify the result

After configuration, the true-client-ip-in header contains the client's originating IP address.

Result verification

Previous：Rewrite URLNext：Modify outgoing request headers