<!-- review: finished -->

<a id="http-rewrite"></a>

# Rewrite

El módulo se utiliza para cambiar la URI de la solicitud utilizando expresiones regulares PCRE, devolver redirecciones y seleccionar configuraciones condicionalmente.

Las directivas [break](#break), [if](#if), [return](#return), [rewrite](#id4) y [set](#set) se procesan en el siguiente orden:

* las directivas de este módulo especificadas en el nivel server se ejecutan secuencialmente;
* repetidamente:
  > * se busca una location basada en la URI de la solicitud;
  > * las directivas de este módulo especificadas dentro de la ubicación encontrada se ejecutan secuencialmente;
  > * el bucle se repite si una URI de solicitud fue [reescrita](#id4), pero [no más](https://es.angie.software//angie/docs/configuration/modules/http/index.md#internal) de 10 veces.

<a id="directives-39"></a>

## Directivas

<a id="index-0"></a>

<a id="break"></a>

### break

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `break`;             |
|--------------------------------------------------------------------------------------------|----------------------|
| Predeterminado                                                                             | —                    |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | server, location, if |

Detiene el procesamiento del conjunto actual de directivas del módulo http_rewrite.

Si una directiva se especifica dentro de la location, el procesamiento posterior de la solicitud continúa en esta location.

Ejemplo:

```nginx
if ($slow) {
    limit_rate 10k;
    break;
}
```

<a id="index-1"></a>

<a id="if"></a>

### if

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `if` (condición) { ... }   |
|--------------------------------------------------------------------------------------------|----------------------------|
| Predeterminado                                                                             | —                          |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | server, location           |

La condición especificada es evaluada. Si es verdadera, las directivas de este módulo especificadas dentro de las llaves se ejecutan, y a la solicitud se le asigna la configuración dentro de la directiva if. Las configuraciones dentro de las directivas if se heredan del nivel de configuración anterior.

#### WARNING
Aunque las directivas de otros módulos pueden usarse dentro del bloque if,
esto no se recomienda,
ya que puede conducir a un comportamiento inesperado.

Una condición puede ser cualquiera de las siguientes:

* un nombre de variable; falso si el valor de una variable es una cadena vacía o "0";
* comparación de una variable con una cadena usando los operadores "=" y "!=";
* coincidencia de una variable con una expresión regular usando los operadores "~" (para coincidencias sensibles a mayúsculas y minúsculas) y "~\*" (para coincidencias insensibles a mayúsculas y minúsculas). Las expresiones regulares pueden contener capturas que se ponen a disposición para su posterior reutilización en las variables $1..$9. Los operadores negativos "!~" y "!~\*" también están disponibles. Si una expresión regular incluye los caracteres "}" o ";", toda la expresión debe estar encerrada entre comillas simples o dobles.
* comprobación de la existencia de un archivo con los operadores "-f" y "!-f";
* comprobación de la existencia de un directorio con los operadores "-d" y "!-d";
* comprobación de la existencia de un archivo, directorio o enlace simbólico con los operadores "-e" y "!-e";
* comprobación de un archivo ejecutable con los operadores "-x" y "!-x".

Ejemplos:

```nginx
if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;
}

if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    set $id $1;
}

if ($request_method = POST) {
    return 405;
}

if ($slow) {
    limit_rate 10k;
}

if ($invalid_referer) {
    return 403;
}
```

#### NOTE
El valor de la variable integrada [$invalid_referer](https://es.angie.software//angie/docs/configuration/modules/http/http_referer.md#v-invalid-referer) es establecido por la directiva [valid_referers](https://es.angie.software//angie/docs/configuration/modules/http/http_referer.md#valid-referers).

<a id="index-2"></a>

<a id="return"></a>

### return

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `return` código [texto];<br/><br/>`return` código URL;<br/><br/>`return` URL;   |
|--------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| Predeterminado                                                                             | —                                                                               |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | server, location, if                                                            |

Detiene el procesamiento y devuelve el `código` especificado al cliente. El código no estándar 444 cierra una conexión sin enviar una cabecera de respuesta.

Es posible especificar una URL de redirección (para los códigos 301, 302, 303, 307 y 308) o el texto del cuerpo de la respuesta (para otros códigos). El texto del cuerpo de la respuesta y la URL de redirección pueden contener variables. Como caso especial, una URL de redirección puede especificarse como una URI local a este servidor, en cuyo caso la URL de redirección completa se forma de acuerdo con el esquema de solicitud ($scheme) y las directivas [server_name_in_redirect](https://es.angie.software//angie/docs/configuration/modules/http/index.md#server-name-in-redirect) y [port_in_redirect](https://es.angie.software//angie/docs/configuration/modules/http/index.md#port-in-redirect).

Además, una URL para redirección temporal con el código 302 puede especificarse como único parámetro. Dicho parámetro debe comenzar con la cadena `http://`, `https://` o "$scheme". Una URL puede contener variables.

Véase también la directiva [error_page](https://es.angie.software//angie/docs/configuration/modules/http/index.md#error-page).

<a id="index-3"></a>

<a id="id4"></a>

### rewrite

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `rewrite` regex reemplazo [bandera];   |
|--------------------------------------------------------------------------------------------|----------------------------------------|
| Predeterminado                                                                             | —                                      |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | server, location, if                   |

Si la expresión regular especificada coincide con una URI de solicitud, la URI se cambia según lo especificado en la cadena de `reemplazo`. Las directivas rewrite se ejecutan secuencialmente en el orden de su aparición en el archivo de configuración. Es posible terminar el procesamiento posterior de las directivas usando `banderas`. Si una cadena de `reemplazo` comienza con `http://`, `https://` o "$scheme", el procesamiento se detiene y la redirección se devuelve al cliente.

Un parámetro opcional `bandera` puede ser uno de los siguientes:

| `last`      | detiene el procesamiento del conjunto actual de directivas del módulo http_rewrite e inicia una búsqueda de una nueva location que coincida con la URI modificada;   |
|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `break`     | detiene el procesamiento del conjunto actual de directivas del módulo http_rewrite como con la directiva break;                                                      |
| `redirect`  | devuelve una redirección temporal con el código 302; se utiliza si una cadena de `reemplazo` no comienza con `http://`, `https://` o "$scheme";                      |
| `permanent` | devuelve una redirección permanente con el código 301.                                                                                                               |

La URL de redirección completa se forma de acuerdo con el esquema de la solicitud ($scheme) y las directivas [server_name_in_redirect](https://es.angie.software//angie/docs/configuration/modules/http/index.md#server-name-in-redirect) y [port_in_redirect](https://es.angie.software//angie/docs/configuration/modules/http/index.md#port-in-redirect).

Ejemplo:

```nginx
server {
#    ...
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    return  403;
#    ...
}
```

Pero si estas directivas se colocan dentro de la ubicación "/download/", la bandera `last` debe ser reemplazada por `break`, o de lo contrario Angie realizará 10 ciclos y devolverá el error 500:

```nginx
location /download/ {
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  break;
    return  403;
}
```

Si una cadena de `reemplazo` incluye nuevos argumentos de solicitud, los argumentos de solicitud anteriores se añaden después de ellos. Si esto no es deseable, colocar un signo de interrogación al final de una cadena de reemplazo evita que se añadan, por ejemplo:

```nginx
rewrite ^/users/(.*)$ /show?user=$1? last;
```

Si una expresión regular incluye los caracteres "}" o ";", toda la expresión debe estar entre comillas simples o dobles.

<a id="index-4"></a>

<a id="rewrite-log"></a>

### rewrite_log

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `rewrite_log` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|-------------------------------|
| Predeterminado                                                                             | `rewrite_log off;`            |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server, location, if    |

Habilita o deshabilita el registro de los resultados del procesamiento de las directivas del módulo http_rewrite en el [error_log](https://es.angie.software//angie/docs/configuration/modules/core.md#error-log) en el nivel notice.

<a id="index-5"></a>

<a id="set"></a>

### set

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `set` $variable valor;   |
|--------------------------------------------------------------------------------------------|--------------------------|
| Predeterminado                                                                             | —                        |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | server, location, if     |

Establece un valor para la variable especificada. El valor puede contener texto, variables y su combinación.

<a id="index-6"></a>

<a id="uninitialized-variable-warn"></a>

### uninitialized_variable_warn

| [Sintaxis](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | `uninitialized_variable_warn` `on` | `off`;   |
|--------------------------------------------------------------------------------------------|-----------------------------------------------|
| Predeterminado                                                                             | `uninitialized_variable_warn on;`             |
| [Contexto](https://es.angie.software//angie/docs/configuration/configfile.md#configfile)   | http, server, location, if                    |

Controla si se registran advertencias sobre variables no inicializadas.

<a id="internal-implementation"></a>

## Implementación Interna

Las directivas del módulo http_rewrite se compilan en la etapa de configuración en instrucciones internas que se interpretan durante el procesamiento de la solicitud. Un intérprete es una simple máquina virtual de pila.

Por ejemplo, las directivas

```nginx
location /download/ {
    if ($forbidden) {
        return 403;
    }

    if ($slow) {
        limit_rate 10k;
    }

    rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
}
```

se traducirán en estas instrucciones:

```console
variable $forbidden
check for zero
    return 403
    end of code
variable $slow
check for zero
match of regular expression
copy "/"
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code
```

Nótese que no hay instrucciones para la directiva [limit_rate](https://es.angie.software//angie/docs/configuration/modules/http/index.md#limit-rate), ya que no está relacionada con el módulo `http_rewrite`. Se crea una configuración separada para el bloque `if`. Si la condición es verdadera, la solicitud obtiene esta configuración, donde `limit_rate` es igual a 10k.

La directiva

```nginx
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
```

puede reducirse en una instrucción si la primera barra en la expresión regular se coloca dentro de los paréntesis:

```nginx
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
```

Las instrucciones correspondientes se verán así:

```console
match of regular expression
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code
```