Skip to content

internal-redirect: Internal redirect to a specified URI

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-internal-redirect provided by the GetPageSpeed Extras repository.

  1. Configure the APT repository as described in APT repository setup.
  2. Install the module:
sudo apt-get update
sudo apt-get install nginx-module-internal-redirect
Show suites and architectures 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

ngx_http_internal_redirect_module allows making an internal redirect. In contrast to rewriting URIs, the redirection is made after rewrite phase. Currently supported request phases are preaccess, access, precontent and content, allowing it to be used with many nginx official or third-party modules.

This module is inspired by the nginx official ngx_http_internal_redirect_module.

Table of Content

Status

This Nginx module is currently considered experimental. Issues and PRs are welcome if you encounter any problems.

Synopsis

server {
    listen 127.0.0.1:80;
    server_name localhost;

    location /old {
        internal_redirect -i ^/old(.+) /new$1 phase=preaccess;
    }

    location /new {
        return 200 'current uri is: $uri';
    }
}

Directives

internal_redirect

Syntax: internal_redirect [-i] pattern replacement [phase=] [flag=] [if= | if!=]

Default: -

Context: http, server, location

Sets the new URI for internal redirection of the request. It is also possible to use a named location instead of the URI. The replacement value can contain variables. If the uri value is empty, then the redirect will not be made. After an internal redirect occurs, the request URI will be changed, and request will be returns to the NGX_HTTP_SERVER_REWRITE_PHASE (server_rewrite) phase. The request proceeds with a server default location. Later at NGX_HTTP_FIND_CONFIG_PHASE (find_config) a new location is chosen based on the new request URI.

For more information about nginx request phases, please refer to Development guide#http_phases

The optional -i parameter specifies that a case-insensitive regular expression match should be performed.

The optional phase= parameter is used to indicate the phase in which this rule takes effect. The possible values ​​are preaccess, access, precontent and content. The rules of each phase will be executed completely before the internal redirection is performed. The default value is preaccess.

The optional flag= parameter is used for additional actions after evaluating the rule. The value of this parameter can be one of: * break stops processing the current set of rules at this phase, and immediately perform an internal redirect; * status_301 returns a redirect with the 301 code. * status_302 returns a redirect with the 302 code. * status_303 returns a redirect with the 303 code. * status_307 returns a redirect with the 307 code. * status_308 returns a redirect with the 308 code.

The if parameter enables conditional redirection. A request will not be redirected if the condition evaluates to “0” or an empty string. You can also use the form of if!= to make negative judgments.