ajp: Soporte para proxy del protocolo AJP con NGINX
Instalación
Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:
- RedHat Enterprise Linux 7, 8, 9 y 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 y Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-ajp
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-ajp
Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:
load_module modules/ngx_http_ajp_module.so;
Este documento describe nginx-module-ajp v0.3.6 lanzado el 13 de febrero de 2026.
http {
upstream tomcats {
server 127.0.0.1:8009;
keepalive 10;
}
server {
listen 80;
location / {
ajp_keep_conn on;
ajp_pass tomcats;
}
}
}
Descripción
Con este módulo, Nginx puede conectarse directamente al puerto AJP. La motivación para escribir estos módulos es el alto rendimiento y robustez de Nginx.
Directivas
ajp_buffers
sintaxis: ajp_buffers el_número es_tamaño;
predeterminado: ajp_buffers 8 4k/8k;
contexto: http, server, location
Esta directiva especifica el número y el tamaño de los buffers, en los que se leerá la respuesta obtenida del servidor AJP. Por defecto, el tamaño de un buffer es igual al tamaño de una página. Dependiendo de la plataforma, esto es 4K, 8K o 16K.
ajp_buffer_size
sintaxis: ajp_buffer_size el_tamaño;
predeterminado: ajp_buffer_size 4k/8k;
contexto: http, server, location
Esta directiva establece el tamaño del buffer, en el que se leerá la primera parte de la respuesta obtenida del servidor AJP.
En esta parte de la respuesta se encuentra, como regla general, el pequeño encabezado de respuesta.
Por defecto, el tamaño del buffer es igual al tamaño de un buffer en la directiva ajp_buffers; sin embargo, es posible establecerlo a un tamaño menor.
ajp_cache
sintaxis: ajp_cache zona;
predeterminado: off
contexto: http, server, location
La directiva especifica el área que en realidad es el nombre de la memoria compartida para el almacenamiento en caché. La misma área puede ser utilizada en varios lugares. Debes establecer primero ajp_cache_path.
ajp_cache_key
sintaxis: ajp_cache_key línea;
predeterminado: none
contexto: http, server, location
La directiva especifica qué información se incluye en la clave para el almacenamiento en caché, por ejemplo
ajp_cache_key "$host$request_uri$cookie_user";
Ten en cuenta que, por defecto, el nombre del host del servidor no se incluye en la clave de caché. Si estás utilizando subdominios para diferentes ubicaciones en tu sitio web, necesitas incluirlo, por ejemplo, cambiando la clave de caché a algo como
ajp_cache_key "$scheme$host$request_uri";
ajp_cache_methods
sintaxis: ajp_cache_methods [GET HEAD POST];
predeterminado: ajp_cache_methods GET HEAD;
contexto: main,http,location
GET/HEAD es azúcar sintáctica, es decir, no puedes deshabilitar GET/HEAD incluso si solo estableces
ajp_cache_methods POST;
ajp_cache_min_uses
sintaxis: ajp_cache_min_uses n;
predeterminado: ajp_cache_min_uses 1;
contexto: http, server, location
Establece el número de solicitudes después de las cuales la respuesta será almacenada en caché.
ajp_cache_path
sintaxis: ajp_cache_path /path/to/cache [levels=m:n keys_zone=name:time inactive=time clean_time=time];
predeterminado: none
contexto: http, server, location
Esta directiva establece la ruta de caché y otros parámetros de caché. Los datos en caché se almacenan en archivos. La clave y el nombre del archivo en caché es el md5 de la URL proxy. El parámetro Levels establece el número de subdirectorios en la caché, por ejemplo para:
ajp_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
los nombres de archivo serán como:
/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c
ajp_cache_use_stale
sintaxis: ajp_cache_use_stale [updating|error|timeout|invalid_header|http_500];
predeterminado: ajp_cache_use_stale off;
contexto: http, server, location
Si ocurre un error al trabajar con el servidor AJP, es posible utilizar una respuesta en caché obsoleta. Esta directiva determina en qué casos está permitido. Los parámetros de la directiva coinciden con los de la directiva ajp_next_upstream.
Además, el parámetro updating permite utilizar una respuesta en caché obsoleta si se está actualizando actualmente. Esto permite minimizar el número de accesos a los servidores AJP al actualizar los datos en caché.
ajp_cache_valid
sintaxis: ajp_cache_valid [http_error_code|time];
predeterminado: none
contexto: http, server, location
Establece el tiempo de almacenamiento en caché para diferentes códigos de respuesta. Por ejemplo, las siguientes directivas
ajp_cache_valid 200 302 10m;
ajp_cache_valid 404 1m;
establecen 10 minutos de almacenamiento en caché para respuestas con códigos 200 y 302, y 1 minuto para respuestas con código 404.
Si solo se especifica el tiempo de almacenamiento en caché
ajp_cache_valid 5m;
entonces solo se almacenan en caché las respuestas 200, 301 y 302.
Además, se puede especificar almacenar en caché cualquier respuesta utilizando el parámetro any:
ajp_cache_valid 200 302 10m;
ajp_cache_valid 301 1h;
ajp_cache_valid any 1m;
Los parámetros de almacenamiento en caché también se pueden establecer directamente en el encabezado de respuesta. Esto tiene una mayor precedencia que el establecimiento del tiempo de almacenamiento en caché utilizando la directiva. El campo de encabezado “X-Accel-Expires” establece el tiempo de almacenamiento en caché de una respuesta en segundos. El valor 0 desactiva el almacenamiento en caché de una respuesta. Si un valor comienza con el prefijo @, establece un tiempo absoluto en segundos desde Epoch, hasta el cual la respuesta puede ser almacenada en caché. Si el encabezado no incluye el campo “X-Accel-Expires”, los parámetros de almacenamiento en caché pueden establecerse en los campos de encabezado “Expires” o “Cache-Control”. Si un encabezado incluye el campo “Set-Cookie”, dicha respuesta no será almacenada en caché. El procesamiento de uno o más de estos campos de encabezado de respuesta se puede deshabilitar utilizando la directiva ajp_ignore_headers.
ajp_connect_timeout
sintaxis: ajp_connect_timeout tiempo;
predeterminado: ajp_connect_timeout 60s;
contexto: http, server, location
Esta directiva asigna un tiempo de espera para la conexión al servidor upstream. Es necesario tener en cuenta que este tiempo de espera no puede ser superior a 75 segundos.
Este no es el tiempo hasta que el servidor devuelve las páginas, este es el ajp_read_timeout declaración. Si tu servidor upstream está activo, pero colgado (por ejemplo, no tiene suficientes hilos para procesar tu solicitud, por lo que te coloca en el grupo de conexiones para tratar más tarde), entonces esta declaración no ayudará ya que la conexión al servidor se ha realizado.
ajp_header_packet_buffer_size
sintaxis: ajp_header packet_buffer_size;
predeterminado: ajp_header_packet_buffer_size 8k;
contexto: http, server, location
Establece el tamaño del buffer del paquete de solicitud reenvíada. El rango es (0, 2^16).
ajp_headers_hash_bucket_size
sintaxis: ajp_headers_hash_bucket_size tamaño;
predeterminado: ajp_headers_hash_bucket_size 64;
contexto: http, server, location
Establece el tamaño del bucket para las tablas hash utilizadas por las directivas ajp_hide_header y ajp_set_header.
ajp_headers_hash_max_size
sintaxis: ajp_headers_hash_max_size tamaño;
predeterminado: ajp_headers_hash_max_size 512;
contexto: http, server, location
Establece el tamaño máximo de las tablas hash utilizadas por las directivas ajp_hide_header y ajp_set_header.
ajp_hide_header
sintaxis: ajp_hide_header nombre;
contexto: http, server, location
Por defecto, Nginx no pasa los encabezados "Status" y "X-Accel-..." del proceso AJP de vuelta al cliente. Esta directiva se puede utilizar para ocultar otros encabezados también.
Si los encabezados "Status" y "X-Accel-..." deben ser proporcionados, entonces es necesario usar la directiva ajp_pass_header para forzarlos a ser devueltos al cliente.
ajp_ignore_headers
sintaxis: ajp_ignore_headers nombre [nombre ...];
predeterminado: none
contexto: http, server, location
Esta directiva (0.7.54+) prohíbe el procesamiento de las líneas de encabezado de la respuesta del servidor proxy.
Puede especificar la cadena como "X-Accel-Redirect", "X-Accel-Expires", "Expires" o "Cache-Control".
ajp_ignore_client_abort
sintaxis: ajp_ignore_client_abort on|off;
predeterminado: ajp_ignore_client_abort off;
contexto: http, server, location
Esta directiva determina si la solicitud actual al servidor AJP debe ser abortada en caso de que el cliente aborte la solicitud al servidor.
ajp_intercept_errors
sintaxis: ajp_intercept_errors on|off;
predeterminado: ajp_intercept_errors off;
contexto: http, server, location
Esta directiva determina si se deben transferir los errores 4xx y 5xx de vuelta al cliente o permitir que Nginx responda con la directiva error_page.
Nota: Necesitas definir explícitamente el manejador error_page para que esto sea útil. Como dice Igor, "nginx no intercepta un error si no hay un manejador personalizado para él, no muestra sus páginas predeterminadas. Esto permite interceptar algunos errores, mientras que otros se pasan tal como están."
ajp_keep_conn
sintaxis: ajp_keep_conn on|off;
predeterminado: ajp_keep_conn off;
contexto: http, server, location
Esta directiva determina si se debe mantener la conexión activa con el servidor backend.
ajp_next_upstream
sintaxis: ajp_next_upstream [error|timeout|invalid_header|http_500|http_502|http_503|http_504|http_404|off];
predeterminado: ajp_next_upstream error timeout;
contexto: http, server, location
La directiva determina en qué casos la solicitud se transmitirá al siguiente servidor:
- error — ocurrió un error al conectarse al servidor, enviar una solicitud a él o leer su respuesta;
- timeout — ocurrió un tiempo de espera durante la conexión con el servidor, transferencia de la solicitud o mientras se leía la respuesta del servidor;
- invalid_header — el servidor devolvió una respuesta vacía o incorrecta;
- http_500 — el servidor devolvió una respuesta con código 500;
- http_502 — el servidor devolvió una respuesta con código 502;
- http_503 — el servidor devolvió una respuesta con código 503;
- http_504 — el servidor devolvió una respuesta con código 504;
- http_404 — el servidor devolvió una respuesta con código 404;
- off — prohíbe la transferencia de la solicitud al siguiente servidor. La transferencia de la solicitud al siguiente servidor solo es posible cuando no se ha transferido nada al cliente; es decir, si ocurre un error o tiempo de espera en medio de la transferencia de la solicitud, no es posible reintentar la solicitud actual en un servidor diferente.
ajp_max_data_packet_size
sintaxis: ajp_max_data_packet_size tamaño;
predeterminado: ajp_max_data_packet_size 8k;
contexto: http, server, location
Establece el tamaño máximo del paquete de datos de AJP. El rango es [8k, 2^16];
ajp_max_temp_file_size
sintaxis: ajp_max_temp_file_size tamaño;
predeterminado: ajp_max_temp_file_size 1G;
contexto: http, server, location, if
El tamaño máximo de un archivo temporal cuando el contenido es más grande que el buffer proxy. Si el archivo es más grande que este tamaño, se servirá de manera sincrónica desde el servidor upstream en lugar de almacenarse en el disco.
Si ajp_max_temp_file_size es igual a cero, se desactivará el uso de archivos temporales.
ajp_pass
sintaxis: ajp_pass ajp-server
predeterminado: none
contexto: location, if en location
La directiva asigna el puerto o socket en el que el servidor AJP está escuchando. El puerto puede indicarse por sí mismo o como una dirección y puerto, por ejemplo:
ajp_pass localhost:9000;
usando un socket de dominio Unix:
ajp_pass unix:/tmp/ajp.socket;
También puedes usar un bloque upstream.
upstream backend {
server localhost:1234;
}
ajp_pass backend;
ajp_secret
sintaxis: ajp_secret ajpsecret
predeterminado: none
La directiva asigna el secreto del servidor AJP.
ajp_pass_header
sintaxis: ajp_pass_header nombre;
contexto: http, server, location
Permite pasar campos de encabezado específicos desde el servidor AJP al cliente.
ajp_pass_request_headers
sintaxis: ajp_pass_request_headers [ on | off ];
predeterminado: ajp_pass_request_headers on;
contexto: http, server, location
Permite pasar campos de encabezado de solicitud desde el cliente al servidor.
ajp_pass_request_body
sintaxis: ajp_pass_request_body [ on | off ] ;
predeterminado: ajp_pass_request_body on;
contexto: http, server, location
Permite pasar el cuerpo de la solicitud desde el cliente al servidor.
ajp_read_timeout
sintaxis: ajp_read_timeout tiempo;
predeterminado: ajp_read_timeout_time 60
contexto: http, server, location
La directiva establece la cantidad de tiempo que el upstream debe esperar a que un proceso AJP envíe datos. Cambia esta directiva si tienes procesos AJP de larga duración que no producen salida hasta que han terminado de procesar. Si ves un error de tiempo de espera en el upstream en el registro de errores, entonces aumenta este parámetro a algo más apropiado.
ajp_send_lowat
sintaxis: ajp_send_lowat [ on | off ];
predeterminado: ajp_send_lowat off;
contexto: http, server, location, if
Esta directiva establece SO_SNDLOWAT. Esta directiva solo está disponible en FreeBSD.
ajp_send_timeout
sintaxis: ajp_send_timeout tiempo;
predeterminado: ajp_send_timeout 60;
contexto: http, server, location
Esta directiva asigna un tiempo de espera con la transferencia de la solicitud al servidor upstream. El tiempo de espera se establece no en toda la transferencia de la solicitud, sino solo entre dos operaciones de escritura. Si después de este tiempo el servidor upstream no acepta nuevos datos, entonces Nginx cerrará la conexión.
ajp_set_header
sintaxis: ajp_set_header nombre valor;
contexto: http, server, location
Permite redefinir o agregar campos al encabezado de solicitud pasado al servidor AJP. El valor puede contener texto, variables y sus combinaciones.
Estas directivas se heredan del nivel de configuración anterior si y solo si no hay directivas ajp_set_header definidas en el nivel actual.
ajp_store
sintaxis: ajp_store [on | off | path] ;
predeterminado: ajp_store off;
contexto: http, server, location
Esta directiva establece la ruta en la que se almacenan los archivos upstream. El parámetro "on" preserva los archivos de acuerdo con la ruta especificada en las directivas alias o root. El parámetro "off" prohíbe el almacenamiento. Además, el nombre de la ruta se puede asignar claramente con la ayuda de la línea con las variables:
ajp_store /data/www$original_uri;
El tiempo de modificación para el archivo se establecerá en la fecha del encabezado "Last-Modified" en la respuesta. Para poder guardar archivos en este directorio, es necesario que la ruta esté bajo el directorio con archivos temporales, dado por la directiva ajp_temp_path para la ubicación de datos.
Esta directiva se puede utilizar para crear copias locales para la salida dinámica del backend que no cambia muy a menudo, por ejemplo:
location /images/ {
root /data/www;
error_page 404 = @fetch;
}
location @fetch {
internal;
ajp_pass backend;
ajp_store on;
ajp_store_access user:rw group:rw all:r;
ajp_temp_path /data/temp;
root /data/www;
}
Para ser claros, ajp_store no es una caché, es más bien un espejo bajo demanda.
ajp_store_access
sintaxis: ajp_store_access users:permissions [users:permission ...];
predeterminado: ajp_store_access user:rw;
contexto: http, server, location
Esta directiva asigna los permisos para los archivos y directorios creados, por ejemplo:
ajp_store_access user:rw group:rw all:r;
Si se asignan derechos para grupos o todos, entonces no es necesario asignar derechos para el usuario:
ajp_store_access group:rw all:r;
ajp_temp_path
sintaxis: ajp_temp_path dir-path [ level1 [ level2 [ level3 ] ] ] ;
predeterminado: $NGX_PREFIX/ajp_temp
contexto: http, server, location
Esta directiva funciona como client_body_temp_path para especificar una ubicación para almacenar en búfer solicitudes proxy grandes en el sistema de archivos.
ajp_temp_file_write_size
sintaxis: ajp_temp_file_write_size tamaño;
predeterminado: ajp_temp_file_write_size ["#ajp buffer size"] * 2;
contexto: http, server, location, if
Establece la cantidad de datos que se vaciarán en el ajp_temp_path al escribir. Puede usarse para evitar que un proceso de trabajo se bloquee durante demasiado tiempo mientras se envían datos.
Problemas conocidos
*
GitHub
Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-ajp.