ajp: Support du proxy du protocole AJP avec NGINX
Installation
Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :
- RedHat Enterprise Linux 7, 8, 9 et 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 et 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
Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :
load_module modules/ngx_http_ajp_module.so;
Ce document décrit nginx-module-ajp v0.3.6 publié le 13 février 2026.
http {
upstream tomcats {
server 127.0.0.1:8009;
keepalive 10;
}
server {
listen 80;
location / {
ajp_keep_conn on;
ajp_pass tomcats;
}
}
}
Description
Avec ce module, Nginx peut se connecter directement au port AJP. La motivation de l'écriture de ces modules est la haute performance et la robustesse de Nginx.
Directives
ajp_buffers
syntax: ajp_buffers the_number is_size;
default: ajp_buffers 8 4k/8k;
context: http, server, location
Cette directive spécifie le nombre et la taille des tampons, dans lesquels sera lue la réponse obtenue du serveur AJP. Par défaut, la taille d'un tampon est égale à la taille d'une page. Selon la plateforme, cela est soit 4K, 8K ou 16K.
ajp_buffer_size
syntax: ajp_buffer_size the_size;
default: ajp_buffer_size 4k/8k;
context: http, server, location
Cette directive définit la taille du tampon, dans lequel sera lue la première partie de la réponse obtenue du serveur AJP.
Dans cette partie de la réponse, le petit en-tête de réponse est généralement situé.
Par défaut, la taille du tampon est égale à la taille d'un tampon dans la directive ajp_buffers; cependant, il est possible de la définir à moins.
ajp_cache
syntax: ajp_cache zone;
default: off
context: http, server, location
La directive spécifie la zone qui est en fait le nom de la mémoire partagée pour le cache. La même zone peut être utilisée à plusieurs endroits. Vous devez d'abord définir le ajp_cache_path.
ajp_cache_key
syntax: ajp_cache_key line;
default: none
context: http, server, location
La directive spécifie quelles informations sont incluses dans la clé pour le cache, par exemple
ajp_cache_key "$host$request_uri$cookie_user";
Notez qu'en par défaut, le nom d'hôte du serveur n'est pas inclus dans la clé de cache. Si vous utilisez des sous-domaines pour différents emplacements sur votre site Web, vous devez l'inclure, par exemple en changeant la clé de cache en quelque chose comme
ajp_cache_key "$scheme$host$request_uri";
ajp_cache_methods
syntax: ajp_cache_methods [GET HEAD POST];
default: ajp_cache_methods GET HEAD;
context: main,http,location
GET/HEAD est une syntaxe sucrée, c'est-à-dire que vous ne pouvez pas désactiver GET/HEAD même si vous définissez juste
ajp_cache_methods POST;
ajp_cache_min_uses
syntax: ajp_cache_min_uses n;
default: ajp_cache_min_uses 1;
context: http, server, location
Définit le nombre de requêtes après lesquelles la réponse sera mise en cache.
ajp_cache_path
syntax: ajp_cache_path /path/to/cache [levels=m:n keys_zone=name:time inactive=time clean_time=time];
default: none
context: http, server, location
Cette directive définit le chemin du cache et d'autres paramètres de cache. Les données mises en cache sont stockées dans des fichiers. La clé et le nom de fichier dans le cache sont le md5 de l'URL proxifiée. Le paramètre Levels définit le nombre de sous-répertoires dans le cache, par exemple pour :
ajp_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
les noms de fichiers seront comme :
/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c
ajp_cache_use_stale
syntax: ajp_cache_use_stale [updating|error|timeout|invalid_header|http_500];
default: ajp_cache_use_stale off;
context: http, server, location
Si une erreur se produit lors du travail avec le serveur AJP, il est possible d'utiliser une réponse mise en cache obsolète. Cette directive détermine dans quels cas cela est permis. Les paramètres de la directive correspondent à ceux de la directive ajp_next_upstream.
De plus, le paramètre updating permet d'utiliser une réponse mise en cache obsolète si elle est actuellement en cours de mise à jour. Cela permet de minimiser le nombre d'accès aux serveurs AJP lors de la mise à jour des données mises en cache.
ajp_cache_valid
syntax: ajp_cache_valid [http_error_code|time];
default: none
context: http, server, location
Définit le temps de mise en cache pour différents codes de réponse. Par exemple, les directives suivantes
ajp_cache_valid 200 302 10m;
ajp_cache_valid 404 1m;
définissent 10 minutes de mise en cache pour les réponses avec les codes 200 et 302, et 1 minute pour les réponses avec le code 404.
Si seul le temps de mise en cache est spécifié
ajp_cache_valid 5m;
alors seules les réponses 200, 301 et 302 sont mises en cache.
De plus, il peut être spécifié de mettre en cache toutes les réponses en utilisant le paramètre any :
ajp_cache_valid 200 302 10m;
ajp_cache_valid 301 1h;
ajp_cache_valid any 1m;
Les paramètres de mise en cache peuvent également être définis directement dans l'en-tête de réponse. Cela a une priorité plus élevée que la définition du temps de mise en cache à l'aide de la directive. Le champ d'en-tête “X-Accel-Expires” définit le temps de mise en cache d'une réponse en secondes. La valeur 0 désactive la mise en cache d'une réponse. Si une valeur commence par le préfixe @, elle définit un temps absolu en secondes depuis l'Époque, jusqu'à laquelle la réponse peut être mise en cache. Si l'en-tête n'inclut pas le champ “X-Accel-Expires”, les paramètres de mise en cache peuvent être définis dans les champs d'en-tête “Expires” ou “Cache-Control”. Si un en-tête inclut le champ “Set-Cookie”, une telle réponse ne sera pas mise en cache. Le traitement d'un ou plusieurs de ces champs d'en-tête de réponse peut être désactivé à l'aide de la directive ajp_ignore_headers.
ajp_connect_timeout
syntax: ajp_connect_timeout time;
default: ajp_connect_timeout 60s;
context: http, server, location
Cette directive attribue un délai d'attente pour la connexion au serveur en amont. Il est nécessaire de garder à l'esprit que ce délai d'attente ne peut pas dépasser 75 secondes.
Ce n'est pas le temps jusqu'à ce que le serveur renvoie les pages, c'est la déclaration ajp_read_timeout. Si votre serveur en amont est opérationnel, mais suspendu (par exemple, il n'a pas assez de threads pour traiter votre demande, donc il vous met dans le pool de connexions à traiter plus tard), alors cette déclaration ne sera pas utile car la connexion au serveur a été établie.
ajp_header_packet_buffer_size
syntax: ajp_header packet_buffer_size;
default: ajp_header_packet_buffer_size 8k;
context: http, server, location
Définit la taille du tampon du paquet de demande Forward. La plage est (0, 2^16).
ajp_headers_hash_bucket_size
syntax: ajp_headers_hash_bucket_size size;
default: ajp_headers_hash_bucket_size 64;
context: http, server, location
Définit la taille du seau pour les tables de hachage utilisées par les directives ajp_hide_header et ajp_set_header.
ajp_headers_hash_max_size
syntax: ajp_headers_hash_max_size size;
default: ajp_headers_hash_max_size 512;
context: http, server, location
Définit la taille maximale des tables de hachage utilisées par les directives ajp_hide_header et ajp_set_header.
ajp_hide_header
syntax: ajp_hide_header name;
context: http, server, location
Par défaut, Nginx ne transmet pas les en-têtes "Status" et "X-Accel-..." du processus AJP au client. Cette directive peut être utilisée pour masquer d'autres en-têtes également.
Si les en-têtes "Status" et "X-Accel-..." doivent être fournis, alors il est nécessaire d'utiliser la directive ajp_pass_header pour forcer leur retour au client.
ajp_ignore_headers
syntax: ajp_ignore_headers name [name ...];
default: none
context: http, server, location
Cette directive (0.7.54+) interdit le traitement des lignes d'en-tête de la réponse du serveur proxy.
Elle peut spécifier la chaîne comme "X-Accel-Redirect", "X-Accel-Expires", "Expires" ou "Cache-Control".
ajp_ignore_client_abort
syntax: ajp_ignore_client_abort on|off;
default: ajp_ignore_client_abort off;
context: http, server, location
Cette directive détermine si la requête actuelle au serveur AJP doit être annulée en cas d'annulation de la requête par le client.
ajp_intercept_errors
syntax: ajp_intercept_errors on|off;
default: ajp_intercept_errors off;
context: http, server, location
Cette directive détermine s'il faut ou non transférer les erreurs 4xx et 5xx au client ou permettre à Nginx de répondre avec la directive error_page.
Note : Vous devez définir explicitement le gestionnaire error_page pour que cela soit utile. Comme le dit Igor, "nginx n'intercepte pas une erreur s'il n'y a pas de gestionnaire personnalisé pour cela, il ne montre pas ses pages par défaut. Cela permet d'intercepter certaines erreurs, tout en laissant passer d'autres telles quelles."
ajp_keep_conn
syntax: ajp_keep_conn on|off;
default: ajp_keep_conn off;
context: http, server, location
Cette directive détermine s'il faut ou non garder la connexion active avec le serveur backend.
ajp_next_upstream
syntax: ajp_next_upstream [error|timeout|invalid_header|http_500|http_502|http_503|http_504|http_404|off];
default: ajp_next_upstream error timeout;
context: http, server, location
La directive détermine dans quels cas la requête sera transmise au serveur suivant :
- error — une erreur s'est produite lors de la connexion au serveur, de l'envoi d'une requête à celui-ci ou de la lecture de sa réponse ;
- timeout — un délai d'attente s'est produit lors de la connexion avec le serveur, du transfert de la requête ou lors de la lecture de la réponse du serveur ;
- invalid_header — le serveur a renvoyé une réponse vide ou incorrecte ;
- http_500 — le serveur a renvoyé une réponse avec le code 500 ;
- http_502 — le serveur a renvoyé une réponse avec le code 502 ;
- http_503 — le serveur a renvoyé une réponse avec le code 503 ;
- http_504 — le serveur a renvoyé une réponse avec le code 504 ;
- http_404 — le serveur a renvoyé une réponse avec le code 404 ;
- off — cela interdit le transfert de la requête au serveur suivant. Le transfert de la requête au serveur suivant n'est possible que lorsque rien n'a été transféré au client -- c'est-à-dire que si une erreur ou un délai d'attente survient au milieu du transfert de la requête, il n'est pas possible de réessayer la requête actuelle sur un autre serveur.
ajp_max_data_packet_size
syntax: ajp_max_data_packet_size size;
default: ajp_max_data_packet_size 8k;
context: http, server, location
Définit la taille maximale du paquet de données AJP. La plage est [8k, 2^16];
ajp_max_temp_file_size
syntax: ajp_max_temp_file_size size;
default: ajp_max_temp_file_size 1G;
context: http, server, location, if
La taille maximale d'un fichier temporaire lorsque le contenu est plus grand que le tampon proxy. Si le fichier est plus grand que cette taille, il sera servi de manière synchrone depuis le serveur en amont plutôt que mis en mémoire tampon sur le disque.
Si ajp_max_temp_file_size est égal à zéro, l'utilisation de fichiers temporaires sera désactivée.
ajp_pass
syntax: ajp_pass ajp-server
default: none
context: location, if in location
La directive attribue le port ou le socket sur lequel le serveur AJP écoute. Le port peut être indiqué par lui-même ou comme une adresse et un port, par exemple :
ajp_pass localhost:9000;
en utilisant un socket de domaine Unix :
ajp_pass unix:/tmp/ajp.socket;
Vous pouvez également utiliser un bloc upstream.
upstream backend {
server localhost:1234;
}
ajp_pass backend;
ajp_secret
syntax: ajp_secret ajpsecret
default: none
La directive attribue le secret du serveur AJP.
ajp_pass_header
syntax: ajp_pass_header name;
context: http, server, location
Permet de passer des champs d'en-tête spécifiques du serveur AJP au client.
ajp_pass_request_headers
syntax: ajp_pass_request_headers [ on | off ];
default: ajp_pass_request_headers on;
context: http, server, location
Permet de passer les champs d'en-tête de requête du client au serveur.
ajp_pass_request_body
syntax: ajp_pass_request_body [ on | off ] ;
default: ajp_pass_request_body on;
context: http, server, location
Permet de passer le corps de la requête du client au serveur.
ajp_read_timeout
syntax: ajp_read_timeout time;
default: ajp_read_timeout_time 60
context: http, server, location
La directive définit la durée pendant laquelle l'amont doit attendre qu'un processus AJP envoie des données. Changez cette directive si vous avez des processus AJP de longue durée qui ne produisent pas de sortie tant qu'ils n'ont pas terminé le traitement. Si vous voyez une erreur de délai d'attente en amont dans le journal des erreurs, augmentez ce paramètre à quelque chose de plus approprié.
ajp_send_lowat
syntax: ajp_send_lowat [ on | off ];
default: ajp_send_lowat off;
context: http, server, location, if
Cette directive définit SO_SNDLOWAT. Cette directive n'est disponible que sur FreeBSD.
ajp_send_timeout
syntax: ajp_send_timeout time;
default: ajp_send_timeout 60;
context: http, server, location
Cette directive attribue un délai d'attente lors du transfert de la requête au serveur en amont. Le délai d'attente est établi non pas sur l'ensemble du transfert de la requête, mais uniquement entre deux opérations d'écriture. Si après ce temps le serveur en amont ne prend pas de nouvelles données, alors Nginx ferme la connexion.
ajp_set_header
syntax: ajp_set_header name value;
context: http, server, location
Permet de redéfinir ou d'ajouter des champs à l'en-tête de requête passé au serveur AJP. La valeur peut contenir du texte, des variables et leurs combinaisons.
Ces directives sont héritées du niveau de configuration précédent si et seulement si aucune directive ajp_set_header n'est définie au niveau actuel.
ajp_store
syntax: ajp_store [on | off | path] ;
default: ajp_store off;
context: http, server, location
Cette directive définit le chemin dans lequel les fichiers en amont sont stockés. Le paramètre "on" préserve les fichiers conformément au chemin spécifié dans les directives alias ou root. Le paramètre "off" interdit le stockage. De plus, le nom du chemin peut être clairement attribué à l'aide de la ligne avec les variables :
ajp_store /data/www$original_uri;
Le temps de modification du fichier sera défini à la date de l'en-tête "Last-Modified" dans la réponse. Pour pouvoir sauvegarder des fichiers dans ce répertoire, il est nécessaire que le chemin soit sous le répertoire avec des fichiers temporaires, donné par la directive ajp_temp_path pour l'emplacement des données.
Cette directive peut être utilisée pour créer des copies locales pour la sortie dynamique du backend qui ne change pas très souvent, par exemple :
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;
}
Pour être clair, ajp_store n'est pas un cache, c'est plutôt un miroir à la demande.
ajp_store_access
syntax: ajp_store_access users:permissions [users:permission ...];
default: ajp_store_access user:rw;
context: http, server, location
Cette directive attribue les permissions pour les fichiers et répertoires créés, par exemple :
ajp_store_access user:rw group:rw all:r;
Si des droits pour des groupes ou tous sont attribués, il n'est pas nécessaire d'attribuer des droits pour l'utilisateur :
ajp_store_access group:rw all:r;
ajp_temp_path
syntax: ajp_temp_path dir-path [ level1 [ level2 [ level3 ] ] ] ;
default: $NGX_PREFIX/ajp_temp
context: http, server, location
Cette directive fonctionne comme client_body_temp_path pour spécifier un emplacement pour mettre en mémoire tampon de grandes requêtes proxifiées sur le système de fichiers.
ajp_temp_file_write_size
syntax: ajp_temp_file_write_size size;
default: ajp_temp_file_write_size ["#ajp buffer size"] * 2;
context: http, server, location, if
Définit la quantité de données qui sera vidée vers le ajp_temp_path lors de l'écriture. Cela peut être utilisé pour empêcher un processus de travail de se bloquer trop longtemps lors de l'écriture des données.
Known Issues
*
GitHub
Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-ajp.