Modify incoming request headers-Edge Security Acceleration(ESA)-阿里云帮助中心

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

In the ESA console, select Websites, and in the Website column, click the target site.
In the left navigation pane, choose Rules > Transform Rules.
Click the Modify request header > Client to ESA > Create Rule.

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`
Add	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`
Modify	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

In the ESA console, select Websites, and in the Website column, click the target site.
In the left navigation pane, choose Rules > Transform Rules.
Click the Modify request header > Client to ESA > Create Rule.
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

Verify the result

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

Result verification

上一篇: Rewrite URL 下一篇: Modify outgoing request headers