NGINX If Is Evil: Guía completa para una lógica condicional segura
Este artículo es una traducción del original en inglés.
La frase “NGINX if is evil” se ha vuelto legendaria en la comunidad de servidores web. Si ha configurado NGINX para algún proyecto significativo, probablemente haya encontrado esta advertencia. Pero, ¿qué hace que la directiva if sea tan peligrosa? ¿Es una exageración o hay una base técnica real detrás de esta notoria reputación?
Esta guía completa explica exactamente por qué la directiva if causa problemas en ciertos contextos, qué casos de uso son realmente seguros y cómo implementar una lógica condicional robusta sin caer en las trampas que han perjudicado a innumerables administradores de sistemas.
Entender por qué la directiva if causa problemas
La directiva if en NGINX se comporta de forma fundamentalmente distinta a los condicionales de los lenguajes de programación. Cuando los desarrolladores de NGINX añadieron soporte para lógica condicional, crearon algo que parece una simple sentencia if-else pero que opera mediante un mecanismo completamente diferente. Esta discrepancia arquitectónica es precisamente la razón por la que existe la advertencia NGINX if is evil.
La causa raíz: el cambio de contexto de configuración
Cuando escribe un bloque if en NGINX, no está simplemente añadiendo una comprobación condicional. Está creando un contexto de configuración completamente nuevo. Esto es lo que ocurre internamente:
- NGINX crea una configuración de location nueva para cada módulo HTTP
- El bloque
ifse trata como una location anidada implícita - Cuando la condición se evalúa como verdadera, NGINX cambia toda la configuración de la solicitud a este nuevo contexto
- Las directivas que no se establecieron explícitamente dentro del bloque
ifno se heredan de la location padre
Esta decisión arquitectónica significa que algunas directivas funcionan perfectamente dentro de bloques if mientras que otras fallan de formas inesperadas y, a veces, espectaculares. Entender este mecanismo es esencial para evitar los patrones peligrosos.
La arquitectura del módulo rewrite de NGINX
La directiva if forma parte del ngx_http_rewrite_module, que procesa las directivas de forma imperativa durante la fase de rewrite. Sin embargo, la mayoría de las demás directivas de NGINX son declarativas y esperan operar dentro de un contexto de configuración estable.
Esta incompatibilidad entre el módulo rewrite imperativo y la naturaleza declarativa de otros módulos es la fuente fundamental del comportamiento problemático. Cuando lo entienda, podrá predecir qué configuraciones funcionarán y cuáles causarán problemas.
Directivas seguras dentro de bloques if de NGINX
No todos los usos de if son problemáticos. Las siguientes directivas están diseñadas explícitamente para funcionar de forma segura dentro de bloques if:
1. La directiva return
Usar return dentro de un bloque if es completamente seguro y es el patrón más común:
server {
listen 80;
server_name example.com;
location / {
# Safe: Block POST requests
if ($request_method = POST) {
return 405;
}
# Safe: Redirect HTTP to HTTPS
if ($scheme = http) {
return 301 https://$server_name$request_uri;
}
root /var/www/html;
}
}
La directiva return termina inmediatamente el procesamiento de la solicitud y envía una respuesta al cliente, evitando cualquier problema de contexto de configuración.
2. La directiva rewrite
La directiva rewrite es otra opción segura, especialmente con los indicadores last o break:
server {
listen 80;
server_name example.com;
location / {
# Safe: Rewrite based on query parameter
if ($arg_redirect) {
rewrite ^ /new-location last;
}
# Safe: Rewrite old URLs to new format
if ($request_uri ~* "^/old-path/(.*)$") {
rewrite ^ /new-path/$1 permanent;
}
root /var/www/html;
}
}
3. La directiva set
Establecer variables dentro de bloques if funciona de forma fiable y es útil para construir una lógica condicional compleja:
server {
listen 80;
server_name example.com;
location / {
set $is_mobile "";
# Safe: Detect mobile user agents
if ($http_user_agent ~* "(mobile|android|iphone|ipad)") {
set $is_mobile "1";
}
# Use the variable later in your configuration
add_header X-Mobile $is_mobile;
root /var/www/html;
}
}
Nota: Aunque set es generalmente seguro, herramientas como Gixy adoptan un enfoque conservador y lo marcan como potencialmente inseguro. En la práctica, set funciona correctamente dentro de bloques if, pero tenga en cuenta que los analizadores estáticos pueden advertir al respecto.
4. La directiva break
La directiva break detiene el procesamiento de rewrite y es segura de usar:
location / {
if ($slow) {
limit_rate 10k;
break;
}
}
Patrones peligrosos: qué evitar
Entender los patrones inseguros es crucial para evitar pesadillas de configuración. A continuación se presentan escenarios problemáticos documentados que demuestran por qué NGINX if is evil en contextos específicos:
Problema 1: múltiples bloques if con add_header
Este es un ejemplo problemático clásico que todavía afecta a las versiones modernas de NGINX (probado en NGINX 1.26.3):
# DANGEROUS: Only X-Second will be present in the response!
location /api/ {
set $condition 1;
if ($condition) {
add_header X-First "1";
}
if ($condition) {
add_header X-Second "1";
}
return 204;
}
Probar esta configuración revela el problema:
curl -I http://localhost/api/
# HTTP/1.1 204 No Content
# X-Second: 1
# Note: X-First is MISSING!
Cada bloque if crea un nuevo contexto de configuración, y gana el último bloque if que coincide para las directivas que solo pueden aplicarse una vez. El add_header del primer bloque if se pierde.
Problema 2: proxy_pass con componentes dinámicos
Cuando hay un bloque if presente, proxy_pass puede comportarse de forma inesperada con las transformaciones de URI. Aunque ajustar proxy_buffer_size es sencillo, combinar proxy_pass con bloques if requiere precaución adicional:
# RISKY: The /v2/ URI transformation might not work as expected
location /api/ {
if ($request_method = OPTIONS) {
add_header Access-Control-Allow-Origin "*";
return 204;
}
proxy_pass http://backend/v2/;
}
Problema 3: interacción con try_files
Combinar if con try_files históricamente ha causado problemas. Como se explica en nuestro artículo sobre las implicaciones de rendimiento de try_files, la propia directiva try_files tiene peculiaridades, y añadir bloques if aumenta la complejidad:
# POTENTIALLY PROBLEMATIC
location / {
set $check 1;
if ($check) {
# Even an empty if block can affect try_files behavior
}
try_files $uri $uri/ @fallback;
}
Aunque las versiones modernas de NGINX (1.26+) han mejorado este comportamiento, mezclar if con try_files todavía debe abordarse con precaución.
Detección automatizada con Gixy
Gixy es un analizador estático para configuraciones de NGINX que detecta automáticamente errores de configuración de seguridad, incluido el uso problemático de if. Es una herramienta excelente para detectar patrones “if is evil” antes de que causen problemas en producción.
Instalar Gixy
En sistemas basados en RHEL (Rocky Linux, AlmaLinux, CentOS), instale Gixy desde el repositorio de GetPageSpeed:
dnf install https://extras.getpagespeed.com/release-latest.rpm
dnf install gixy
Ejecutar Gixy
Analice su configuración de NGINX:
gixy /etc/nginx/nginx.conf
Gixy informará de problemas como:
>> Problem: [if_is_evil] If is Evil... when used in location context.
Severity: HIGH
Description: Directive "if" has problems when used in location context,
in some cases it does not do what you expect but something completely
different instead.
Additional info: https://gixy.org/en/checks/if-is-evil/
Gixy comprueba múltiples problemas de seguridad, incluidas vulnerabilidades SSRF, ataques de división HTTP y problemas de redefinición de cabeceras, muchos de los cuales pueden introducirse inadvertidamente mediante un uso inadecuado de if.
Mejores alternativas a la directiva if
La directiva map: su mejor aliada
La directiva map es la alternativa recomendada para la mayoría de la lógica condicional. Se evalúa durante la inicialización de variables, no durante el procesamiento de la solicitud, lo que la hace predecible y eficiente:
# Define the map at http level
map $request_method $method_not_allowed {
default 0;
POST 1;
PUT 1;
DELETE 1;
}
server {
listen 80;
server_name example.com;
location / {
if ($method_not_allowed) {
return 405 "Method not allowed";
}
root /var/www/html;
}
}
La directiva map admite coincidencias de patrones complejas con expresiones regulares:
# Route based on user agent
map $http_user_agent $backend {
default "http://desktop-backend";
~*mobile "http://mobile-backend";
~*googlebot "http://seo-backend";
}
server {
location / {
proxy_pass $backend;
}
}
Usar map de forma eficaz evita la mayoría de los escenarios en los que la directiva if causa problemas.
Múltiples condiciones mediante concatenación de variables
NGINX no admite operadores AND/OR nativos en las sentencias if. Utilice la concatenación de variables en su lugar:
server {
listen 80;
server_name example.com;
location / {
set $condition "";
if ($request_method = POST) {
set $condition "P";
}
if ($http_x_api_key = "secret") {
set $condition "${condition}K";
}
# Only matches when BOTH conditions are true
if ($condition = "PK") {
return 200 "Authenticated POST request";
}
return 403 "Access denied";
}
}
El truco de la location con nombre mediante error_page
Para enrutamientos complejos que normalmente requerirían un uso inseguro de if, el patrón error_page proporciona una solución limpia:
server {
listen 80;
server_name example.com;
location /api/ {
# Trigger named location for OPTIONS requests
error_page 418 = @cors_preflight;
if ($request_method = OPTIONS) {
return 418;
}
# This proxy_pass works correctly
proxy_pass http://backend/v2/;
}
location @cors_preflight {
add_header Access-Control-Allow-Origin "*";
add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
add_header Access-Control-Max-Age 86400;
return 204;
}
}
Este patrón utiliza el código de estado HTTP 418 (I’m a teapot) como mecanismo de enrutamiento interno. La directiva error_page lo captura y enruta a la location con nombre, evitando por completo los problemas de contexto de configuración.
Ejemplos prácticos: patrones seguros del mundo real
Redirección de HTTP a HTTPS
server {
listen 80;
server_name example.com www.example.com;
# Safe and efficient - no if needed
return 301 https://example.com$request_uri;
}
Para una redirección condicional basada en el dominio específico:
server {
listen 80;
server_name example.com www.example.com;
if ($host = www.example.com) {
return 301 https://example.com$request_uri;
}
return 301 https://$host$request_uri;
}
Modo de mantenimiento
# Using map for maintenance bypass (e.g., admin IPs)
map $remote_addr $maintenance_bypass {
default 0;
192.168.1.100 1; # Admin IP
10.0.0.0/8 1; # Internal network
}
server {
listen 80;
server_name example.com;
set $maintenance 1; # Set to 0 to disable maintenance mode
if ($maintenance_bypass) {
set $maintenance 0;
}
if ($maintenance = 1) {
return 503 "Site under maintenance";
}
root /var/www/html;
}
Detección y bloqueo de bots
map $http_user_agent $bad_bot {
default 0;
~*crawl 0; # Allow legitimate crawlers
~*googlebot 0;
~*bingbot 0;
~*wget 1; # Block wget
~*python 1; # Block Python scripts
"" 1; # Block empty user agents
}
server {
listen 80;
server_name example.com;
if ($bad_bot) {
return 403 "Access denied";
}
root /var/www/html;
}
Restricciones geográficas
# Requires ngx_http_geoip2_module
map $geoip2_country_code $allowed_country {
default no;
US yes;
CA yes;
GB yes;
}
server {
listen 80;
server_name example.com;
if ($allowed_country = no) {
return 403 "Service not available in your region";
}
root /var/www/html;
}
Probar sus configuraciones con if
Valide siempre su configuración antes de desplegarla. El hecho de que NGINX if is evil en ciertos contextos no significa que no pueda usarlo; significa que debe probarlo a fondo:
# Test configuration syntax
nginx -t
# Run static analysis with Gixy
gixy /etc/nginx/nginx.conf
# Test with specific HTTP methods
curl -I http://localhost/your-path
curl -X POST http://localhost/your-path
curl -X OPTIONS http://localhost/your-path
# Test with custom headers
curl -H "User-Agent: Mobile" http://localhost/your-path
curl -H "X-Special: true" http://localhost/your-path
# Check response headers to verify behavior
curl -sI http://localhost/ | grep -E "^X-|^HTTP"
Contexto histórico y mejoras modernas
La advertencia original “if is evil” de la wiki de NGINX se escribió hace años, cuando estos problemas eran más graves y menos comprendidos. Las versiones modernas de NGINX (1.20+) han mejorado algunos casos límite, pero la arquitectura fundamental no ha cambiado.
Los problemas centrales que hacen problemáticos ciertos patrones de if siguen existiendo:
- Sigue produciéndose el cambio de contexto de configuración
- Múltiples bloques
ifsiguen compitiendo por la posición de último-gana - La herencia de directivas a través de los límites de
ifsigue siendo impredecible
Lo que ha mejorado es la documentación y el conocimiento de la comunidad. Ahora dispone de una guía clara sobre patrones seguros e inseguros, y herramientas como Gixy pueden detectar automáticamente configuraciones problemáticas.
Resumen: las reglas de la directiva if
- Directivas seguras dentro de bloques if:
return,rewrite,set,break - Evitar dentro de bloques if:
add_header(con múltiples bloques if),proxy_passcon transformaciones de URI,try_files - Usar la directiva map para lógica condicional compleja: casi siempre es mejor
- Usar locations con nombre con
error_pagepara enrutamientos que requerirían patrones if inseguros - Probar a fondo antes de desplegar cualquier configuración con bloques if
- Usar Gixy para detectar automáticamente patrones problemáticos
- Entender el contexto que hace peligrosos ciertos patrones: el cambio de configuración, no la directiva en sí
La directiva if no es intrínsecamente malvada; simplemente se malinterpreta. Al entender cómo NGINX procesa los bloques if y usar los patrones seguros documentados aquí, puede escribir configuraciones condicionales robustas sin encontrar problemas.
Recuerde: en caso de duda, recurra a la directiva map. Maneja la mayoría de los escenarios de lógica condicional de forma elegante y evita las trampas que dieron origen a la infame advertencia “NGINX if is evil”.
De la validación puntual a la cobertura continua. Una directiva if puede ser segura hoy y peligrosa tras una refactorización. GetPageSpeed Amplify ejecuta análisis gixy programados en cada host y vincula los hallazgos con métricas en tiempo real del entorno de ejecución de NGINX. Compatible de forma directa con el obsoleto nginx-amplify-agent (fin de vida en enero de 2026).