ajp: Suporte ao proxy do protocolo AJP com NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

• RedHat Enterprise Linux 7, 8, 9 e 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 e Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 e Amazon Linux 2

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_ajp_module.so;

Este documento descreve o nginx-module-ajp v0.3.6 lançado em 13 de fevereiro de 2026.

---

    http {
            upstream tomcats {
                    server 127.0.0.1:8009;
                    keepalive 10;
            }

            server {

                    listen 80;

                    location / {
                            ajp_keep_conn on;
                            ajp_pass tomcats;
                    }
            }
    }

Descrição

Com este módulo, o Nginx pode se conectar diretamente à porta AJP. A motivação para escrever esses módulos é o alto desempenho e robustez do Nginx.

Diretrizes

ajp_buffers

sintaxe: ajp_buffers the_number is_size;

padrão: ajp_buffers 8 4k/8k;

contexto: http, server, location

Esta diretiva especifica o número e o tamanho dos buffers, nos quais será lida a resposta obtida do servidor AJP. Por padrão, o tamanho de um buffer é igual ao tamanho de uma página. Dependendo da plataforma, isso pode ser 4K, 8K ou 16K.

ajp_buffer_size

sintaxe: ajp_buffer_size the_size;

padrão: ajp_buffer_size 4k/8k;

contexto: http, server, location

Esta diretiva define o tamanho do buffer, no qual será lida a primeira parte da resposta obtida do servidor AJP.

Nesta parte da resposta, geralmente está localizado o pequeno cabeçalho de resposta.

Por padrão, o tamanho do buffer é igual ao tamanho de um buffer na diretiva ajp_buffers; no entanto, é possível configurá-lo para um valor menor.

ajp_cache

sintaxe: ajp_cache zone;

padrão: off

contexto: http, server, location

A diretiva especifica a área que, na verdade, é o nome da memória compartilhada para cache. A mesma área pode ser usada em vários lugares. Você deve definir o ajp_cache_path primeiro.

ajp_cache_key

sintaxe: ajp_cache_key line;

padrão: none

contexto: http, server, location

A diretiva especifica quais informações estão incluídas na chave para cache, por exemplo

    ajp_cache_key "$host$request_uri$cookie_user";

Observe que, por padrão, o nome do host do servidor não está incluído na chave do cache. Se você estiver usando subdomínios para diferentes locais em seu site, precisará incluí-lo, por exemplo, alterando a chave do cache para algo como

    ajp_cache_key "$scheme$host$request_uri";

ajp_cache_methods

sintaxe: ajp_cache_methods [GET HEAD POST];

padrão: ajp_cache_methods GET HEAD;

contexto: main,http,location

GET/HEAD é uma sintaxe simplificada, ou seja, você não pode desativar GET/HEAD mesmo que defina apenas

    ajp_cache_methods  POST;

ajp_cache_min_uses

sintaxe: ajp_cache_min_uses n;

padrão: ajp_cache_min_uses 1;

contexto: http, server, location

Define o número de solicitações após as quais a resposta será armazenada em cache.

ajp_cache_path

sintaxe: ajp_cache_path /path/to/cache [levels=m:n keys_zone=name:time inactive=time clean_time=time];

padrão: none

contexto: http, server, location

Esta diretiva define o caminho do cache e outros parâmetros de cache. Os dados em cache são armazenados em arquivos. A chave e o nome do arquivo em cache são md5 da URL proxy. O parâmetro Levels define o número de subdiretórios no cache, por exemplo, para:

    ajp_cache_path  /data/nginx/cache  levels=1:2   keys_zone=one:10m;

os nomes dos arquivos serão como:

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

ajp_cache_use_stale

sintaxe: ajp_cache_use_stale [updating|error|timeout|invalid_header|http_500];

padrão: ajp_cache_use_stale off;

contexto: http, server, location

Se ocorrer um erro ao trabalhar com o servidor AJP, é possível usar uma resposta em cache obsoleta. Esta diretiva determina em quais casos isso é permitido. Os parâmetros da diretiva correspondem aos da diretiva ajp_next_upstream.

Além disso, o parâmetro updating permite usar uma resposta em cache obsoleta se ela estiver sendo atualizada no momento. Isso permite minimizar o número de acessos aos servidores AJP ao atualizar dados em cache.

ajp_cache_valid

sintaxe: ajp_cache_valid [http_error_code|time];

padrão: none

contexto: http, server, location

Define o tempo de cache para diferentes códigos de resposta. Por exemplo, as seguintes diretivas

    ajp_cache_valid 200 302 10m;
    ajp_cache_valid 404      1m;

definem 10 minutos de cache para respostas com códigos 200 e 302, e 1 minuto para respostas com código 404.

Se apenas o tempo de cache for especificado

    ajp_cache_valid 5m;

então apenas as respostas 200, 301 e 302 são armazenadas em cache.

Além disso, pode-se especificar para armazenar em cache quaisquer respostas usando o parâmetro any:

    ajp_cache_valid 200 302 10m;
    ajp_cache_valid 301      1h;
    ajp_cache_valid any      1m;

Os parâmetros de cache também podem ser definidos diretamente no cabeçalho da resposta. Isso tem uma precedência maior do que a definição do tempo de cache usando a diretiva. O campo de cabeçalho “X-Accel-Expires” define o tempo de cache de uma resposta em segundos. O valor 0 desabilita o cache de uma resposta. Se um valor começar com o prefixo @, ele define um tempo absoluto em segundos desde a Epoch, até o qual a resposta pode ser armazenada em cache. Se o cabeçalho não incluir o campo “X-Accel-Expires”, os parâmetros de cache podem ser definidos nos campos de cabeçalho “Expires” ou “Cache-Control”. Se um cabeçalho incluir o campo “Set-Cookie”, tal resposta não será armazenada em cache. O processamento de um ou mais desses campos de cabeçalho de resposta pode ser desabilitado usando a diretiva ajp_ignore_headers.

ajp_connect_timeout

sintaxe: ajp_connect_timeout time;

padrão: ajp_connect_timeout 60s;

contexto: http, server, location

Esta diretiva atribui um tempo limite para a conexão com o servidor upstream. É necessário ter em mente que esse tempo limite não pode ser superior a 75 segundos.

Este não é o tempo até que o servidor retorne as páginas, isso é a declaração ajp_read_timeout. Se seu servidor upstream estiver ativo, mas travado (por exemplo, não tiver threads suficientes para processar sua solicitação, colocando você na fila de conexões para lidar mais tarde), então esta declaração não ajudará, pois a conexão com o servidor já foi estabelecida.

ajp_header_packet_buffer_size

sintaxe: ajp_header packet_buffer_size;

padrão: ajp_header_packet_buffer_size 8k;

contexto: http, server, location

Define o tamanho do buffer do pacote de solicitação encaminhada. O intervalo é (0, 2^16).

ajp_headers_hash_bucket_size

sintaxe: ajp_headers_hash_bucket_size size;

padrão: ajp_headers_hash_bucket_size 64;

contexto: http, server, location

Define o tamanho do bucket para tabelas hash usadas pelas diretivas ajp_hide_header e ajp_set_header.

ajp_headers_hash_max_size

sintaxe: ajp_headers_hash_max_size size;

padrão: ajp_headers_hash_max_size 512;

contexto: http, server, location

Define o tamanho máximo das tabelas hash usadas pelas diretivas ajp_hide_header e ajp_set_header.

ajp_hide_header

sintaxe: ajp_hide_header name;

contexto: http, server, location

Por padrão, o Nginx não passa os cabeçalhos "Status" e "X-Accel-..." do processo AJP de volta ao cliente. Esta diretiva pode ser usada para ocultar outros cabeçalhos também.

Se os cabeçalhos "Status" e "X-Accel-..." devem ser fornecidos, então é necessário usar a diretiva ajp_pass_header para forçá-los a serem retornados ao cliente.

ajp_ignore_headers

sintaxe: ajp_ignore_headers name [name ...];

padrão: none

contexto: http, server, location

Esta diretiva (0.7.54+) proíbe o processamento das linhas de cabeçalho da resposta do servidor proxy.

Pode-se especificar a string como "X-Accel-Redirect", "X-Accel-Expires", "Expires" ou "Cache-Control".

ajp_ignore_client_abort

sintaxe: ajp_ignore_client_abort on|off;

padrão: ajp_ignore_client_abort off;

contexto: http, server, location

Esta diretiva determina se a solicitação atual ao servidor AJP deve ser abortada caso o cliente cancele a solicitação ao servidor.

ajp_intercept_errors

sintaxe: ajp_intercept_errors on|off;

padrão: ajp_intercept_errors off;

contexto: http, server, location

Esta diretiva determina se os erros 4xx e 5xx devem ser transferidos de volta ao cliente ou se o Nginx deve responder com a diretiva error_page.

Nota: Você precisa definir explicitamente o manipulador error_page para que isso seja útil. Como Igor diz, "nginx não intercepta um erro se não houver um manipulador personalizado para ele, não mostra suas páginas padrão. Isso permite interceptar alguns erros, enquanto passa outros como estão."

ajp_keep_conn

sintaxe: ajp_keep_conn on|off;

padrão: ajp_keep_conn off;

contexto: http, server, location

Esta diretiva determina se a conexão deve ser mantida ativa com o servidor backend.

ajp_next_upstream

sintaxe: ajp_next_upstream [error|timeout|invalid_header|http_500|http_502|http_503|http_504|http_404|off];

padrão: ajp_next_upstream error timeout;

contexto: http, server, location

A diretiva determina em quais casos a solicitação será transmitida para o próximo servidor:

• error — ocorreu um erro ao conectar-se ao servidor, enviar uma solicitação a ele ou ler sua resposta;
• timeout — ocorreu um tempo limite durante a conexão com o servidor, transferência da solicitação ou enquanto lia a resposta do servidor;
• invalid_header — o servidor retornou uma resposta vazia ou incorreta;
• http_500 — o servidor retornou uma resposta com código 500;
• http_502 — o servidor retornou uma resposta com código 502;
• http_503 — o servidor retornou uma resposta com código 503;
• http_504 — o servidor retornou uma resposta com código 504;
• http_404 — o servidor retornou uma resposta com código 404;
• off — proíbe a transferência da solicitação para o próximo servidor. A transferência da solicitação para o próximo servidor só é possível quando nada foi transferido para o cliente — ou seja, se um erro ou tempo limite ocorrer no meio da transferência da solicitação, não será possível tentar a solicitação atual em um servidor diferente.

ajp_max_data_packet_size

sintaxe: ajp_max_data_packet_size size;

padrão: ajp_max_data_packet_size 8k;

contexto: http, server, location

Define o tamanho máximo do pacote de dados AJP. O intervalo é [8k, 2^16];

ajp_max_temp_file_size

sintaxe: ajp_max_temp_file_size size;

padrão: ajp_max_temp_file_size 1G;

contexto: http, server, location, if

O tamanho máximo de um arquivo temporário quando o conteúdo é maior que o buffer do proxy. Se o arquivo for maior que esse tamanho, ele será servido de forma síncrona do servidor upstream em vez de ser armazenado em disco.

Se ajp_max_temp_file_size for igual a zero, o uso de arquivos temporários será desabilitado.

ajp_pass

sintaxe: ajp_pass ajp-server

padrão: none

contexto: location, if in location

A diretiva atribui a porta ou socket na qual o servidor AJP está escutando. A porta pode ser indicada sozinha ou como um endereço e porta, por exemplo:

    ajp_pass   localhost:9000;

usando um socket de domínio Unix:

    ajp_pass   unix:/tmp/ajp.socket;

Você também pode usar um bloco upstream.

    upstream backend  {
            server   localhost:1234;
    }

    ajp_pass   backend;

ajp_secret

sintaxe: ajp_secret ajpsecret

padrão: none

A diretiva atribui o segredo do servidor AJP.

ajp_pass_header

sintaxe: ajp_pass_header name;

contexto: http, server, location

Permite passar campos de cabeçalho específicos do servidor AJP para um cliente.

ajp_pass_request_headers

sintaxe: ajp_pass_request_headers [ on | off ];

padrão: ajp_pass_request_headers on;

contexto: http, server, location

Permite passar campos de cabeçalho de solicitação do cliente para o servidor.

ajp_pass_request_body

sintaxe: ajp_pass_request_body [ on | off ] ;

padrão: ajp_pass_request_body on;

contexto: http, server, location

Permite passar o corpo da solicitação do cliente para o servidor.

ajp_read_timeout

sintaxe: ajp_read_timeout time;

padrão: ajp_read_timeout_time 60

contexto: http, server, location

A diretiva define a quantidade de tempo que o upstream deve esperar para que um processo AJP envie dados. Altere esta diretiva se você tiver processos AJP de longa duração que não produzem saída até que tenham terminado o processamento. Se você estiver vendo um erro de tempo limite no upstream no log de erros, aumente este parâmetro para algo mais apropriado.

ajp_send_lowat

sintaxe: ajp_send_lowat [ on | off ];

padrão: ajp_send_lowat off;

contexto: http, server, location, if

Esta diretiva define SO_SNDLOWAT. Esta diretiva está disponível apenas no FreeBSD.

ajp_send_timeout

sintaxe: ajp_send_timeout time;

padrão: ajp_send_timeout 60;

contexto: http, server, location

Esta diretiva atribui um tempo limite à transferência da solicitação para o servidor upstream. O tempo limite é estabelecido não na transferência total da solicitação, mas apenas entre duas operações de gravação. Se após esse tempo o servidor upstream não aceitar novos dados, o nginx encerrará a conexão.

ajp_set_header

sintaxe: ajp_set_header name value;

contexto: http, server, location

Permite redefinir ou adicionar campos ao cabeçalho da solicitação passada para o servidor AJP. O valor pode conter texto, variáveis e suas combinações.

Essas diretivas são herdadas do nível de configuração anterior se e somente se não houver diretivas ajp_set_header definidas no nível atual.

ajp_store

sintaxe: ajp_store [on | off | path] ;

padrão: ajp_store off;

contexto: http, server, location

Esta diretiva define o caminho no qual os arquivos upstream são armazenados. O parâmetro "on" preserva arquivos de acordo com o caminho especificado nas diretivas alias ou root. O parâmetro "off" proíbe o armazenamento. Além disso, o nome do caminho pode ser claramente atribuído com a ajuda da linha com as variáveis:

    ajp_store   /data/www$original_uri;

O tempo de modificação do arquivo será definido para a data do cabeçalho "Last-Modified" na resposta. Para poder salvar arquivos neste diretório, é necessário que o caminho esteja sob o diretório com arquivos temporários, dado pela diretiva ajp_temp_path para a localização dos dados.

Esta diretiva pode ser usada para criar cópias locais para a saída dinâmica do backend que não muda com frequência, por exemplo:

    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 claro, ajp_store não é um cache, é mais um espelho sob demanda.

ajp_store_access

sintaxe: ajp_store_access users:permissions [users:permission ...];

padrão: ajp_store_access user:rw;

contexto: http, server, location

Esta diretiva atribui as permissões para os arquivos e diretórios criados, por exemplo:

    ajp_store_access  user:rw  group:rw  all:r;

Se quaisquer direitos para grupos ou todos forem atribuídos, não é necessário atribuir direitos para o usuário:

    ajp_store_access  group:rw  all:r;

ajp_temp_path

sintaxe: ajp_temp_path dir-path [ level1 [ level2 [ level3 ] ] ] ;

padrão: $NGX_PREFIX/ajp_temp

contexto: http, server, location

Esta diretiva funciona como client_body_temp_path para especificar um local para armazenar em buffer grandes solicitações proxy no sistema de arquivos.

ajp_temp_file_write_size

sintaxe: ajp_temp_file_write_size size;

padrão: ajp_temp_file_write_size ["#ajp buffer size"] * 2;

contexto: http, server, location, if

Define a quantidade de dados que será gravada no ajp_temp_path ao escrever. Pode ser usado para evitar que um processo worker bloqueie por muito tempo enquanto grava dados.

Problemas Conhecidos

*

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-ajp.