Rewrite request URLs by configuring redirect rules - Edge Security Acceleration

How it works

The redirect process:

A client requests a resource.
The ESA POP matches the request against redirect rules. On a match, it returns a redirect status code (e.g., 301 or 302) with the destination URL in the Location response header.
The client follows the Location header and requests the resource from the new URL.

Status codes and scenarios

Status code	Meaning	Method handling	Common scenarios
301	Moved Permanently	GET requests remain unchanged. Other methods may change to GET.	The resource permanently moved to a new URL. Search engines update their indexes.
302	Found	GET requests remain unchanged. Other methods may change to GET.	The resource is temporarily at a different URL. Search engines retain the original link.
303	See Other	GET requests remain unchanged. Other methods are forced to GET, and the request body is discarded.	Redirect after PUT or POST to prevent duplicate submissions on refresh.
307	Temporary Redirect	Method and request body remain unchanged.	Temporary redirect. Prefer over 302 when your site uses non-GET methods.
308	Permanent Redirect	Method and request body remain unchanged.	Permanent redirect that preserves the HTTP method and request body. Use for API migrations or site refactoring requiring method consistency.

Important

If you need to redirect API calls or non-GET requests (such as POST or PUT) while preserving the request method and body, use status code 307 (temporary) or 308 (permanent). Status codes 301 and 302 may convert non-GET requests to GET, resulting in data loss.

Avoid configuring redirects on high-traffic upload paths (such as /api/upload). For such paths, consider splitting them into a dedicated domain or intercepting requests via WAF to prevent abnormal back-to-origin traffic caused by redirects.

Create a redirect rule

ESA evaluates rules in priority order and applies the first match.

In the ESA console, choose Site Management. In the Website column, click the target site.
In the navigation pane on the left, choose Rules > Redirect Rules. Click Create Rule.

On the Add Redirect Rule page, configure the following settings and click OK:

Enter a Rule Name.
In the If requests match... section, define the request conditions to match. For more information, see Components of a rule expression.

URL Redirect:

Single Redirect configuration

Parameter	Type	Description
Redirect Type	Static	Redirect to a fixed URL. For example, set URL to `https://test.example.com/image/1.jpg?test=123`.
Redirect Type	Dynamic	Construct the destination URL dynamically with an expression. For example, to replace the hostname in the request URL while keeping the original path, set Expression to `concat("https://www.example.com", http.request.uri.path)`. Use a valid expression built with supported functions. Entering a plain string containing variables directly will cause a save failure. Common dynamic expression patterns: Preserve original path (non-www to www, HTTP to HTTPS) — Use `concat("https://target-domain.com", http.request.uri.path)` to concatenate the target domain with the original request path. Use this pattern when you need to retain the path during redirect. Remove or replace a path prefix — Use `concat("https://img.example.com", regex_replace(http.request.uri.path, "^/data", ""))` to remove the `/data` prefix from the original path and redirect to the new domain. Combine `regex_replace` with `concat` to transform the path.
Status Code		The HTTP status code returned for the redirect. Valid values: 301 (default), 302, 303, 307, and 308. For details, see Status codes and scenarios.
Retain Query String		Whether to carry the original request's query string to the destination URL. Disabled by default (the original query string is dropped). When Retain Query String is enabled: If the original request has a query string, it overrides the redirect URL's query string. If the original request has no query string, the redirect URL's query string is preserved. For configuration examples, see Configuration examples.

Configuration examples

Static redirect examples

Scenario 1: Request has no query string, redirect URL has a query string

Request contains query string: No
Configured redirect URL contains query string: Yes
Preserve query string: Enabled or disabled
Sample request URL: http://test.example.com/1.jpg
Configured redirect URL: http://test.example.com/image/1.jpg?test=123
Actual redirect Location: http://test.example.com/image/1.jpg?test=123
Notes: No query string in the original request, so the configured URL's query string is used regardless of the Preserve query string setting.

Scenario 2: Both URLs have query strings, Preserve query string enabled

Request contains query string: Yes
Configured redirect URL contains query string: Yes
Preserve query string: Enabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg?test=123
Actual redirect Location: http://test.example.com/image/1.jpg?test=321
Notes: With Preserve query string enabled, only the original request's query string is kept; the configured URL's query parameters are discarded.

Scenario 3: Both URLs have query strings, Preserve query string disabled

Request contains query string: Yes
Configured redirect URL contains query string: Yes
Preserve query string: Disabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg?test=123
Actual redirect Location: http://test.example.com/image/1.jpg?test=123
Notes: With Preserve query string disabled, only the configured URL's query string is kept; the original request's query parameters are discarded.

Scenario 4: Request has a query string, redirect URL does not, Preserve query string enabled

Request contains query string: Yes
Configured redirect URL contains query string: No
Preserve query string: Enabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg
Actual redirect Location: http://test.example.com/image/1.jpg?test=321
Notes: With Preserve query string enabled, the original query string is appended to the configured URL even if it has no query parameters.

Scenario 5: Request has a query string, redirect URL does not, Preserve query string disabled

Request contains query string: Yes
Configured redirect URL contains query string: No
Preserve query string: Disabled
Sample request URL: http://test.example.com/1.jpg?test=321
Configured redirect URL: http://test.example.com/image/1.jpg
Actual redirect Location: http://test.example.com/image/1.jpg
Notes: With Preserve query string disabled, the original query string is discarded and only the configured URL is returned.

Dynamic redirect examples

Scenario 1: Preserve query string disabled

Preserve query string: Disabled
Sample request URL: https://test.example.com/image/1.jpg?test=123
Expression: concat("https://www.example.com", http.request.uri.path)
Actual redirect Location: https://www.example.com/image/1.jpg
Notes:
- With Preserve query string disabled, the path (/image/1.jpg) is kept and the query string (?test=123) is dropped.
- The expression concatenates hostname and path only; query parameters are not handled.

Scenario 2: Preserve query string enabled

Preserve query string: Enabled
Sample request URL: https://test.example.com/image/1.jpg?test=123
Expression: concat("https://www.example.com", http.request.uri.path)
Actual redirect Location: https://www.example.com/image/1.jpg?test=123
Notes:
- With Preserve query string enabled, the original query string is appended to the generated URL even if the expression does not handle query parameters.
- The expression handles path concatenation only; the system appends the query string per configuration.

Scenario 3: wildcard_replace function, Preserve query string enabled

Preserve query string: Enabled
Sample request URL: https://www.example.com/image-flower-20250816-1.html?src=cdn
Expression: wildcard_replace(http.request.full_uri, "https://www.example.com/image-*", "https://www.example.com/${1}")
Actual redirect Location: https://www.example.com/flower-20250816-1.html?src=cdn
Notes:
- With Preserve query string enabled, the system appends the original query string (e.g., ?src=cdn) to the destination URL.
- The expression handles path rewriting only; the system passes through the query string per configuration.

Scenario 4: wildcard_replace function, Preserve query string disabled

Preserve query string: Disabled
Sample request URL: https://www.example.com/index.html?place=garden&date=20250816
Expression: wildcard_replace(http.request.full_uri, "https://www.example.com/index.html?place=garden&date=*", "https://www.example.com/flower-${1}-1.html")
Actual redirect Location: https://www.example.com/flower-20250816-1.html
Notes:
- With Preserve query string disabled, the destination URL is built entirely from the expression. Original parameters (e.g., place=garden) are used only for matching; * captures the value after date and substitutes it as ${1}.
- The final URL excludes the original query parameters.

FAQ

How do I redirect between a root domain (bare domain) and a www domain?

The approach depends on your DNS configuration:

Using ESA for redirect: Both the root domain and the www domain must be connected to ESA via CNAME or NS records. Even if you configure a redirect rule, the source domain must retain its CNAME record so ESA can recognize incoming traffic. After both domains are connected to ESA, configure the corresponding hostname redirect rule in the ESA redirect rules.
Root domain has MX records and cannot be CNAMEd (DNS conflict): Use the URL forwarding feature provided by your DNS provider. Note that DNS URL forwarding only supports HTTP and traffic does not pass through ESA.
Important: If you previously configured a URL forwarding record in your DNS settings, you must delete that record and add the ESA CNAME before using ESA redirect rules. Otherwise, ESA redirect rules will not take effect.

What should I do if a redirect rule does not take effect or redirects to the wrong URL?

Check the following items in order:

Verify the match condition covers the target domain precisely: For example, if you only configured a rule for the www domain but users access the root domain, add a root domain rule or use a wildcard to cover both.
Confirm that DNS is correctly connected to ESA: If you are using ESA redirect, the domain must be connected to ESA via CNAME or NS records. Relying solely on the origin server's redirect configuration or DNS URL forwarding will not work.
Check for higher-priority rules overriding the redirect rule: Review the rule priority order and ensure no upstream rule is intercepting or modifying the request before the redirect rule is evaluated.
Verify dynamic expression syntax: URL concatenation requires the concat function. Entering a raw string with variables will fail. Use valid expression functions such as concat, regex_replace, or wildcard_replace.

What should I do if redirects cause an infinite loop or make the website inaccessible?

Try the following troubleshooting steps:

Check for a circular redirect configuration: Verify whether the www domain's origin server points to the root domain while you have also configured a root-to-www redirect, creating a loop. Restore the origin to the actual IP address or the original upstream origin address.
HTTP-to-HTTPS redirect: Use the Force HTTPS feature in the ESA console rather than manually configuring redirect rules. Manual rules can conflict with each other and create redirect loops.
Clear the redirect cache: If a stale redirect response persists due to caching, purge the cache in the ESA console and then re-test the redirect behavior.
Check for mismatched rules: Confirm that redirect rules do not inadvertently match health check endpoints or special internal paths, which could cause access failures.

How do I configure conditional redirects based on device type (such as mobile) or request characteristics?

You can use request headers such as User-Agent in the incoming request match conditions:

Matching method: Use Contains rather than Equals for User-Agent matching, because User-Agent strings are typically long and vary across devices.
Mobile redirect example: Set the match condition to User-Agent Contains Mobile or use keywords such as Android or iPhone, then configure the action as a 302 redirect to the mobile domain.
Advanced control: Combine path, query parameters, and other conditions for granular redirect control. For example, redirect mobile users accessing / to m.example.com, while desktop users continue to the standard domain.

Why does the browser URL not change after I configure a redirect rule?

If the browser URL does not change, you may be using URL rewrite instead of request redirect:

ESA request redirect sends a 3xx response to the client, which causes the browser to navigate to the new URL and update the address bar.
URL rewrite only modifies the origin request path transparently (server-side proxy) and does not change the browser URL. If you need to keep the browser URL unchanged while modifying the path sent to the origin, use the URL Rewrite feature instead of redirect rules.
Note on acceleration region: If the acceleration region does not include the Chinese mainland, users in the Chinese mainland may not experience acceleration when accessing the redirect target.

Plan support

Feature	Entrance	Pro	Premium	Enterprise
Number of rules	10	25	50	125

Edge Security Acceleration:Request redirects