Módulo HTTP#

O módulo HTTP principal implementa a funcionalidade básica de um servidor HTTP: isso inclui definir blocos de servidor, configurar localizações para roteamento de requisições, servir arquivos estáticos e controlar acesso, configurar redirecionamentos, suportar conexões keep-alive, e gerenciar cabeçalhos de requisição e resposta.

Os outros módulos nesta seção estendem essa funcionalidade, permitindo que você configure e otimize flexivelmente o servidor HTTP para vários cenários e requisitos.

Diretivas#

absolute_redirect#

Sintaxe	`absolute_redirect` `on` \| `off`;
Padrão	`absolute_redirect on;`
Contexto	http, server, location

Se desabilitado, redirecionamentos emitidos pelo Angie serão relativos.

Veja também as diretivas server_name_in_redirect e port_in_redirect.

aio#

Sintaxe	`aio` `on` \| `off` \| `threads` [=pool];
Padrão	`aio off;`
Contexto	http, server, location

Habilita ou desabilita o uso de I/O de arquivo assíncrono (AIO) no FreeBSD e Linux:

location /video/ {
  aio            on;
  output_buffers 1 64k;
}

No FreeBSD, AIO pode ser usado a partir do FreeBSD 4.3. Antes do FreeBSD 11.0, AIO pode ser linkado estaticamente no kernel:

options VFS_AIO

ou carregado dinamicamente como um módulo carregável do kernel:

kldload aio

No Linux, AIO pode ser usado a partir da versão 2.6.22 do kernel. Além disso, é necessário habilitar directio, ou caso contrário a leitura será bloqueante:

location /video/ {
  aio            on;
  directio       512;
  output_buffers 1 128k;
}

No Linux, directio pode ser usado apenas para ler blocos que estão alinhados em limites de 512 bytes (ou 4K para XFS). O final não alinhado do arquivo é lido em modo bloqueante. O mesmo vale para requisições de intervalo de bytes e para requisições FLV que não começam do início de um arquivo: a leitura de dados não alinhados no início e fim de um arquivo será bloqueante.

Quando tanto AIO quanto sendfile estão habilitados no Linux, AIO é usado para arquivos que são maiores ou iguais ao tamanho especificado na diretiva directio, enquanto sendfile é usado para arquivos de tamanhos menores ou quando directio está desabilitado:

location /video/ {
  sendfile       on;
  aio            on;
  directio       8m;
}

Finalmente, arquivos podem ser lidos e enviados usando multi-threading, sem bloquear um processo worker:

location /video/ {
  sendfile       on;
  aio            threads;
}

Operações de leitura e envio de arquivo são transferidas para threads do pool especificado. Se o nome do pool for omitido, o pool com o nome "default" é usado. O nome do pool também pode ser definido com variáveis:

aio threads=pool$disk;

Por padrão, multi-threading está desabilitado, deve ser habilitado com o parâmetro de configuração --with-threads. Atualmente, multi-threading é compatível apenas com os métodos epoll, kqueue, e eventport. Envio multi-threaded de arquivos é suportado apenas no Linux.

Veja também a diretiva sendfile.

aio_write#

Sintaxe	`aio_write` `on` \| `off`;
Padrão	`aio_write off;`
Contexto	http, server, location

Se aio estiver habilitado, especifica se é usado para escrever arquivos. Atualmente, isso funciona apenas quando usando aio threads e é limitado a escrever arquivos temporários com dados recebidos de servidores proxy.

alias#

Sintaxe	`alias` path;
Padrão	—
Contexto	location

Define uma substituição para a localização especificada. Por exemplo, com a seguinte configuração:

location /i/ {
  alias /data/w3/images/;
}

na requisição de /i/top.gif, o arquivo /data/w3/images/top.gif será enviado.

O valor path pode conter variáveis, exceto $document_root e $realpath_root.

Se alias for usado dentro de uma localização definida com uma expressão regular, então tal expressão regular deve conter capturas e alias deve referenciar essas capturas, por exemplo:

location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
  alias /data/w3/images/$1;
}

Quando a localização corresponde à última parte do valor da diretiva:

location /images/ {
  alias /data/w3/images/;
}

é melhor usar a diretiva root em vez disso:

location /images/ {
  root /data/w3;
}

auth_delay#

Sintaxe	`auth_delay` time;
Padrão	`auth_delay 0s;`
Contexto	http, server, location

Atrasa o processamento de requisições não autorizadas com código de resposta 401 para prevenir ataques de temporização quando o acesso é limitado por senha ou pelo resultado de subrequisição.

auto_redirect#

Sintaxe	`auto_redirect` [`on` \| `off` \| `default`];
Padrão	`auto_redirect default;`
Contexto	http, server, location

Controla o comportamento de redirecionamento quando uma localização de prefixo termina com uma barra:

location /prefix/ {
    auto_redirect on;
}

Aqui, uma requisição para /prefix causa um redirecionamento para /prefix/.

O valor on habilita explicitamente o redirecionamento, enquanto off o desabilita. Quando definido como default, o redirecionamento é habilitado apenas se a localização processa requisições com api, proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass, ou grpc_pass.

chunked_transfer_encoding#

Sintaxe	`chunked_transfer_encoding` `on` \| `off`;
Padrão	`chunked_transfer_encoding on;`
Contexto	http, server, location

Permite desabilitar a codificação de transferência em chunks no HTTP/1.1. Pode ser útil quando usando um software que falha em suportar codificação em chunks apesar do requisito do padrão.

client#

Sintaxe	`client` { ... }
Padrão	—
Contexto	http

Cria um contexto especial client para processar requisições HTTP internas que o Angie executa por conta própria sem envolvimento de cliente externo.

O contexto client isola o tráfego de serviço de vários módulos do Angie do tráfego de usuário, permitindo controle adicional sobre ele. Dentro deste contexto, apenas location`s nomeados (com o prefixo :samp:`@) podem ser definidos; eles não são acessíveis para requisições HTTP externas e só podem ser chamados programaticamente através de mecanismos internos do servidor.

O contexto client é usado para:

enviar requisições para a autoridade certificadora no módulo ACME via o location @acme predefinido, que pode ser adicionalmente configurado usando diretivas do módulo Proxy;
requisições para a API do Docker no módulo Docker via os location @docker_events predefinidos e @docker_containers, que podem ser adicionalmente configurados usando diretivas do módulo Proxy;
verificações de saúde de servidores proxy via upstream_probe (PRO);
modo sticky learn com remote_action no módulo stream Upstream.

O suporte para múltiplos blocos client permite agrupar configurações comuns para múltiplos blocos location dentro de cada bloco, o que ajuda a evitar duplicação de configuração.

Diretivas especificadas em cada bloco client são herdadas apenas por blocos location explicitamente declarados dentro dele. Em particular, é por isso que elas não afetam a configuração de outros módulos que implicitamente usam o bloco client para requisições de saída (por exemplo, ACME ou Docker).

Exemplo de uso de múltiplos blocos client com herança de configurações:

client {

    proxy_set_header Host docker.example.com;
    proxy_set_header Authorization "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==";

    location @docker_events {

    }

    location @docker_containers {

    }
}

client {

    upstream_probe_timeout 3s;
    proxy_method GET;
    proxy_set_header Host backend.example.com;
    proxy_set_header X-Real-IP $remote_addr;

    location @health_check {

        proxy_pass http://upstream-server/health;
    }
}

Nota

As mesmas diretivas são permitidas aqui como em location`s regulares, mas apenas manipuladores de conteúdo (como :ref:`js_content ou autoindex) e manipuladores de variáveis (como map), bem como diretivas que geram requisições por si mesmas, como upstream_probe, realmente funcionam.

Diretivas que operam em outras etapas de processamento de requisição (como limit_req, auth_request, try_files, filtros de imagem, XSLT, etc.) não funcionam aqui.

client_body_buffer_size#

Sintaxe	`client_body_buffer_size` size;
Padrão	`client_body_buffer_size 8k\|16k;`
Contexto	http, server, location

Define o tamanho do buffer para leitura do corpo da requisição do cliente. Se o corpo da requisição for maior que o buffer, todo o corpo ou apenas sua parte é escrito em um arquivo temporário. Por padrão, o tamanho do buffer é igual a duas páginas de memória. No x86, outras plataformas de 32 bits e x86-64, isso é 8K. Em outras plataformas de 64 bits, geralmente é 16K.

client_body_in_file_only#

Sintaxe	`client_body_in_file_only` `on` \| `clean` \| `off`;
Padrão	`client_body_in_file_only off;`
Contexto	http, server, location

Determina se deve salvar todo o corpo da requisição do cliente em um arquivo. Esta diretiva pode ser usada durante depuração, ou ao usar a variável $request_body_file, ou o método $r->request_body_file do módulo Perl.

`on`	arquivos temporários não são removidos após o processamento da requisição
`clean`	permite que os arquivos temporários deixados após o processamento da requisição sejam removidos

client_body_in_single_buffer#

Sintaxe	`client_body_in_single_buffer` `on` \| `off`;
Padrão	`client_body_in_single_buffer off;`
Contexto	http, server, location

Determina se deve salvar todo o corpo da requisição do cliente em um único buffer. A diretiva é recomendada ao usar a variável $request_body para reduzir o número de operações de cópia envolvidas.

client_body_temp_path#

Sintaxe	`client_body_temp_path` path [level1 [level2 [level3]]];
Padrão	`client_body_temp_path client_body_temp;` (o caminho depende da opção de compilação `--http-client-body-temp-path`)
Contexto	http, server, location

Define um diretório para armazenar arquivos temporários com corpos de requisição do cliente. Até três níveis de hierarquia de subdiretórios podem ser usados sob o diretório especificado. Por exemplo, na seguinte configuração

client_body_temp_path /spool/angie/client_temp 1 2;

um caminho para um arquivo temporário pode parecer assim:

/spool/angie/client_temp/7/45/00000123457

client_body_timeout#

Sintaxe	`client_body_timeout` time;
Padrão	`client_body_timeout 60s;`
Contexto	http, server, location

Define um timeout para leitura do corpo da requisição do cliente. O timeout é definido apenas para um período entre duas operações de leitura sucessivas, não para a transmissão de todo o corpo da requisição. Se um cliente não transmitir nada dentro deste tempo, a requisição é terminada com o erro 408 (Request Time-out).

client_header_buffer_size#

Sintaxe	`client_header_buffer_size` size;
Padrão	`client_header_buffer_size 1k;`
Contexto	http, server

Define o tamanho do buffer para leitura do cabeçalho da requisição do cliente. Para a maioria das requisições, um buffer de 1K bytes é suficiente. No entanto, se uma requisição incluir cookies longos, ou vier de um cliente WAP, pode não caber em 1K. Se uma linha de requisição ou um campo de cabeçalho de requisição não couber neste buffer, então buffers maiores, configurados pela diretiva large_client_header_buffers, são alocados.

Se a diretiva for especificada no nível server, o valor do servidor padrão pode ser usado. Consulte a seção Seleção de servidor virtual para detalhes.

client_header_timeout#

Sintaxe	`client_header_timeout` time;
Padrão	`client_header_timeout 60s;`
Contexto	http, server

Define um timeout para leitura do cabeçalho da requisição do cliente. Se um cliente não transmitir o cabeçalho inteiro dentro deste tempo, a requisição é terminada com o erro 408 (Request Time-out).

client_max_body_size#

Sintaxe	`client_max_body_size` size;
Padrão	`client_max_body_size 1m;`
Contexto	http, server, location

Define o tamanho máximo permitido do corpo da requisição do cliente. Se o tamanho em uma requisição exceder o valor configurado, o erro 413 (Request Entity Too Large) é retornado ao cliente. Esteja ciente de que os navegadores não conseguem exibir corretamente este erro.

`0`	desabilita a verificação do tamanho do corpo da requisição do cliente

connection_pool_size#

Sintaxe	`connection_pool_size` size;
Padrão	`connection_pool_size 256` \| `512;`
Contexto	http, server, location

Permite o ajuste preciso das alocações de memória por conexão. Esta diretiva tem impacto mínimo na performance e geralmente não deve ser usada. Por padrão:

`256` (bytes)	em plataformas de 32 bits
`512` (bytes)	em plataformas de 64 bits

default_type#

Sintaxe	`default_type` mime-type;
Padrão	`default_type text/plain;`
Contexto	http, server, location

Define o tipo MIME padrão de uma resposta. O mapeamento de extensões de nome de arquivo para tipos MIME pode ser definido com a diretiva types.

directio#

Sintaxe	`directio` size \| `off`;
Padrão	`directio off;`
Contexto	http, server, location

Habilita o uso da flag O_DIRECT (FreeBSD, Linux), da flag F_NOCACHE (macOS), ou da função directio() (Solaris), ao ler arquivos que são maiores ou iguais ao tamanho especificado. A diretiva automaticamente desabilita o uso de sendfile para uma determinada requisição. É recomendado para servir arquivos grandes:

directio 4m;

ou ao usar aio no Linux.

directio_alignment#

Sintaxe	`directio_alignment` size;
Padrão	`directio_alignment 512;`
Contexto	http, server, location

Define o alinhamento para directio. Na maioria dos casos, um alinhamento de 512 bytes é suficiente. No entanto, ao usar XFS no Linux, precisa ser aumentado para 4K.

disable_symlinks#

Sintaxe

disable_symlinks off;

disable_symlinks on | if_not_owner [from=part];

Padrão

disable_symlinks off;

Contexto

http, server, location

Determina como os links simbólicos devem ser tratados ao abrir arquivos:

`off`	Links simbólicos no caminho são permitidos e não verificados. Este é o comportamento padrão.
`on`	Se qualquer componente do caminho for um link simbólico, o acesso ao arquivo é negado.
`if_not_owner`	O acesso ao arquivo é negado se qualquer componente do caminho for um link simbólico, e o link e o objeto para o qual ele aponta tiverem proprietários diferentes.
`from=`part	Ao verificar links simbólicos (parâmetros `on` e `if_not_owner`), todos os componentes do caminho são geralmente verificados. É possível pular a verificação de links simbólicos na parte inicial do caminho especificando adicionalmente o parâmetro `from=part`. Neste caso, links simbólicos são verificados apenas a partir do componente do caminho que segue a parte inicial especificada. Se o valor não for uma parte inicial do caminho verificado, o caminho é verificado inteiramente, como se este parâmetro não tivesse sido especificado. Se o valor corresponder completamente ao nome do arquivo, links simbólicos não são verificados. Variáveis podem ser usadas no valor do parâmetro.

Exemplo:

disable_symlinks on from=$document_root;

Esta diretiva está disponível apenas em sistemas que possuem as interfaces openat() e fstatat(). Tais sistemas incluem versões modernas do FreeBSD, Linux e Solaris.

Aviso

Os parâmetros on e if_not_owner adicionam sobrecarga de processamento.

Em sistemas que não suportam abrir diretórios apenas para busca, usar estes parâmetros requer que os processos worker tenham permissões de leitura para todos os diretórios sendo verificados.

Nota

Os módulos AutoIndex, Random Index e DAV atualmente ignoram esta diretiva.

error_page#

Sintaxe	`error_page` code ... [=[response]] uri;
Padrão	—
Contexto	http, server, location, if in location

Define a URI que será mostrada para os erros especificados. O valor uri pode usar variáveis.

Exemplo:

error_page 404             /404.html;
error_page 500 502 503 504 /50x.html;

Isso causa um redirecionamento interno para a uri especificada com o método da requisição do cliente alterado para "GET" (para todos os métodos exceto "GET" e "HEAD").

Além disso, é possível alterar o código de resposta para outro usando a sintaxe como =response, por exemplo:

error_page 404 =200 /empty.gif;

Se uma resposta de erro é processada por um servidor proxy ou um servidor FastCGI/uwsgi/SCGI/gRPC, e o servidor pode retornar diferentes códigos de resposta (por exemplo, 200, 302, 401, ou 404), é possível passar o código que ele retorna:

error_page 404 = /404.php;

Se não há necessidade de alterar o URI e método durante o redirecionamento interno, é possível passar o processamento de erro para um location nomeado:

location / {
  error_page 404 = @fallback;
}

location @fallback {
  proxy_pass http://backend;
}

Nota

Se um erro ocorre durante o processamento do uri, a resposta com o código do último erro ocorrido é retornada ao cliente.

Também é possível usar redirecionamentos de URL para processamento de erro:

error_page 403      http://example.com/forbidden.html;
error_page 404 =301 http://example.com/notfound.html;

Neste caso, por padrão, o código de resposta 302 é retornado ao cliente. Ele só pode ser alterado para um dos códigos de resposta de redirecionamento (301, 302, 303, 307, e 308).

etag#

Sintaxe	`etag` `on` \| `off`;
Padrão	`etag on;`
Contexto	http, server, location

Habilita ou desabilita a geração automática do campo de cabeçalho de resposta ETag para recursos estáticos.

http#

Sintaxe	`http` { ... }
Padrão	—
Contexto	main

Fornece o contexto do arquivo de configuração no qual as diretivas do servidor HTTP são especificadas.

if_modified_since#

Sintaxe	`if_modified_since` `off` \| `exact` \| `before`;
Padrão	`if_modified_since exact;`
Contexto	http, server, location

Especifica como comparar o tempo de modificação de uma resposta com o tempo no campo de cabeçalho de requisição If-Modified-Since:

`off`	a resposta é sempre considerada modificada
`exact`	correspondência exata
`before`	o tempo de modificação da resposta é menor ou igual ao tempo no campo de cabeçalho de requisição `If-Modified-Since`

ignore_invalid_headers#

Sintaxe	`ignore_invalid_headers` `on` \| `off`;
Padrão	`ignore_invalid_headers on;`
Contexto	http, server

Controla se o Angie ignora campos de cabeçalho com nomes inválidos. Nomes válidos são compostos de letras inglesas, dígitos, hífens, e possivelmente sublinhados (conforme controlado pela diretiva underscores_in_headers).

Se a diretiva é especificada no nível server, o valor do servidor padrão pode ser usado.

internal#

Sintaxe	`internal;`
Padrão	—
Contexto	location

Especifica que um determinado location só pode ser usado para requisições internas. Para requisições externas, o erro de cliente 404 (Not Found) é retornado. Requisições internas são as seguintes:

requisições redirecionadas pelas diretivas error_page, index, random_index, e try_files;
requisições redirecionadas pelo campo de cabeçalho de resposta X-Accel-Redirect de um servidor upstream;
sub-requisições formadas pelo comando include virtual do módulo SSI, pelas diretivas do módulo Addition, e pelas diretivas auth_request e mirror;
requisições alteradas pela diretiva rewrite.

Exemplo:

error_page 404 /404.html;

location = /404.html {
  internal;
}

Nota

Há um limite de 10 redirecionamentos internos por requisição para prevenir ciclos de processamento de requisição que podem ocorrer em configurações incorretas. Se este limite é atingido, o erro 500 (Internal Server Error) é retornado. Em tais casos, a mensagem rewrite or internal redirection cycle pode ser vista no log de erro.

keepalive_disable#

Sintaxe	`keepalive_disable` `none` \| browser ...;
Padrão	`keepalive_disable msie6;`
Contexto	http, server, location

Desabilita conexões keep-alive com navegadores com comportamento inadequado. Os parâmetros browser especificam quais navegadores serão afetados.

`none`	habilita conexões keep-alive com todos os navegadores
`msie6`	desabilita conexões keep-alive com versões antigas do MSIE, uma vez que uma requisição POST é recebida
`safari`	desabilita conexões keep-alive com Safari e navegadores similares ao Safari no macOS e sistemas operacionais similares ao macOS

keepalive_requests#

Sintaxe	`keepalive_requests` number;
Padrão	`keepalive_requests 1000;`
Contexto	http, server, location

Define o número máximo de requisições que podem ser atendidas através de uma conexão keep-alive. Após o número máximo de requisições ser feito, a conexão é fechada.

O fechamento periódico de conexões é necessário para liberar alocações de memória por conexão. Portanto, usar um número máximo muito alto de requisições pode resultar em uso excessivo de memória e não é recomendado.

keepalive_time#

Sintaxe	`keepalive_time` time;
Padrão	`keepalive_time 1h;`
Contexto	http, server, location

Limita o tempo máximo durante o qual requisições podem ser processadas através de uma conexão keep-alive. Após este tempo ser atingido, a conexão é fechada seguindo o processamento da requisição subsequente.

keepalive_timeout#

Sintaxe	`keepalive_timeout` timeout [header_timeout];
Padrão	`keepalive_timeout 75s;`
Contexto	http, server, location

timeout	define um timeout durante o qual uma conexão keep-alive do cliente permanecerá aberta no lado do servidor
`0`	desabilita conexões keep-alive do cliente

O segundo parâmetro, opcional, define um valor no campo de cabeçalho Keep‑Alive: timeout=time na resposta. Os dois parâmetros podem diferir.

O campo de cabeçalho Keep-Alive: timeout=time é reconhecido pelo Mozilla e Konqueror. O MSIE fecha conexões keep-alive por si só em cerca de 60 segundos.

large_client_header_buffers#

Sintaxe	`large_client_header_buffers` number size;
Padrão	`large_client_header_buffers 4 8k;`
Contexto	http, server

Define o número máximo e o tamanho dos buffers usados para ler cabeçalhos de requisição grandes do cliente. Uma linha de requisição não pode exceder o tamanho de um buffer, ou o erro 414 (Request-URI Too Large) é retornado ao cliente. Um campo de cabeçalho de requisição também não pode exceder o tamanho de um buffer, ou o erro 400 (Bad Request) é retornado ao cliente. Os buffers são alocados apenas sob demanda. Por padrão, o tamanho do buffer é igual a 8K bytes. Se após o fim do processamento da requisição uma conexão é transicionada para o estado keep-alive, esses buffers são liberados.

Se a diretiva for especificada no nível server, o valor do servidor padrão pode ser usado.

limit_except#

Sintaxe	`limit_except` method1 [method2...] { ... };
Padrão	—
Contexto	location

Limita os métodos HTTP permitidos dentro de uma localização. O parâmetro method pode ser um dos seguintes: GET, HEAD, POST, PUT, DELETE, MKCOL, COPY, MOVE, OPTIONS, PROPFIND, PROPPATCH, LOCK, UNLOCK, ou PATCH. Permitir o método GET também torna o método HEAD permitido. O acesso a outros métodos pode ser limitado usando as diretivas dos módulos Access e Auth Basic:

limit_except GET {
  allow 192.168.1.0/32;
  deny  all;
}

Nota

A restrição neste exemplo se aplica a todos os métodos exceto GET e HEAD.

limit_rate#

Sintaxe	`limit_rate` rate;
Padrão	`limit_rate 0;`
Contexto	http, server, location, if in location

Limita a taxa de transmissão de resposta para um cliente. A taxa é especificada em bytes por segundo. O valor zero desabilita a limitação de taxa. O limite é definido por requisição, e assim se um cliente abrir simultaneamente duas conexões, a taxa geral será duas vezes maior que o limite especificado.

O valor do parâmetro pode conter variáveis. Pode ser útil em casos onde a taxa deve ser limitada dependendo de uma determinada condição:

map $slow $rate {
  1     4k;
  2     8k;
}

limit_rate $rate;

O limite de taxa também pode ser definido na variável $limit_rate, no entanto, este método não é recomendado:

server {

  if ($slow) {
    set $limit_rate 4k;
  }

}

O limite de taxa também pode ser definido no campo de cabeçalho X-Accel-Limit-Rate de uma resposta de servidor proxy. Esta capacidade pode ser desabilitada usando as diretivas proxy_ignore_headers, fastcgi_ignore_headers, uwsgi_ignore_headers, e scgi_ignore_headers.

limit_rate_after#

Sintaxe	`limit_rate_after` size;
Padrão	`limit_rate_after 0;`
Contexto	http, server, location, if in location

Define a quantidade inicial após a qual a transmissão adicional de uma resposta para um cliente será limitada por taxa. O valor do parâmetro pode conter variáveis.

Exemplo:

location /flv/ {
 flv;
 limit_rate_after 500k;
 limit_rate       50k;
}

lingering_close#

Sintaxe	`lingering_close` `on` \| `always` \| `off`;
Padrão	`lingering_close on;`
Contexto	http, server, location

Controla como o Angie fecha conexões de cliente.

`on`	instrui o Angie a aguardar e processar dados adicionais de um cliente antes de fechar completamente uma conexão, mas apenas se a heurística sugerir que um cliente pode estar enviando mais dados.
`always`	fará com que o Angie aguarde incondicionalmente e processe dados adicionais do cliente.
`off`	diz ao Angie para nunca aguardar mais dados e fechar a conexão imediatamente. Este comportamento quebra o protocolo e não deve ser usado em circunstâncias normais.

Para controlar o fechamento de conexões HTTP/2, a diretiva deve ser especificada no nível server.

lingering_time#

Sintaxe	`lingering_time` time;
Padrão	`lingering_time 30s;`
Contexto	http, server, location

Quando lingering_close está em efeito, esta diretiva especifica o tempo máximo durante o qual o Angie processará (lerá e ignorará) dados adicionais vindos de um cliente. Após isso, a conexão será fechada, mesmo se houver mais dados.

lingering_timeout#

Sintaxe	`lingering_timeout` time;
Padrão	`lingering_timeout 5s;`
Contexto	http, server, location

Quando lingering_close está em efeito, esta diretiva especifica o tempo máximo de espera para que mais dados do cliente cheguem. Se os dados não forem recebidos durante este tempo, a conexão é fechada. Caso contrário, os dados são lidos e ignorados, e o Angie começa a aguardar mais dados novamente. O ciclo "aguardar-ler-ignorar" é repetido, mas não por mais tempo que o especificado pela diretiva lingering_time.

Durante o desligamento gracioso, conexões keep-alive do cliente são fechadas apenas se elas estiverem inativas por pelo menos o tempo especificado em lingering_timeout.

Nota

No nginx, uma diretiva similar é chamada keepalive_min_timeout.

listen#

Sintaxe

listen address[:port] [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on | off] [reuseport] [so_keepalive=on|off|[keepidle]:[samp:keepintvl]:[samp:keepcnt]];

listen port [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on | off] [reuseport] [so_keepalive=on|off|[keepidle]:[samp:keepintvl]:[samp:keepcnt]];

listen unix:path [default_server] [ssl] [http2 | quic] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[samp:keepintvl]:[samp:keepcnt]];

Padrão

listen *:80 | *:8000;

Contexto

server

Define o address e a port para o socket de escuta, ou o caminho para um socket de domínio UNIX no qual o servidor aceitará requisições. Um address também pode ser um nome de host, por exemplo:

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

Endereços IPv6 são especificados entre colchetes:

listen [::]:8000;
listen [::1];

Sockets de domínio UNIX são especificados com o prefixo unix::

listen unix:/var/run/angie.sock;

Tanto address quanto port, ou apenas address ou apenas port, podem ser especificados. Quando algumas partes são omitidas, as seguintes regras se aplicam:

Se apenas o address for fornecido, a porta 80 é usada.
Se apenas a port for fornecida, o Angie escuta em todas as interfaces IPv4 (e IPv6, se habilitado) disponíveis. O primeiro bloco server para essa porta torna-se o servidor padrão para requisições com um cabeçalho Host não correspondente.
Se a diretiva for omitida inteiramente, o Angie usa *:80 quando executado com privilégios de superusuário ou *:8000 caso contrário.

`default_server`	O servidor com este parâmetro especificado será o servidor padrão para o par address:port fornecido (juntos eles formam um socket de escuta). Se não houver diretivas com o parâmetro `default_server`, o servidor padrão para o socket de escuta será o primeiro servidor na configuração que serve este socket.
`ssl`	indica que todas as conexões aceitas neste socket de escuta devem funcionar em modo SSL. Isso permite uma configuração mais compacta para o servidor que manipula tanto requisições HTTP quanto HTTPS.
`http2`	configura a porta para aceitar conexões HTTP/2. Normalmente, para que isso funcione, o parâmetro `ssl` também deve ser especificado, mas o Angie também pode ser configurado para aceitar conexões HTTP/2 sem SSL. Descontinuado desde a versão 1.2.0. Use a diretiva http2 em vez disso.
`quic`	configura a porta para aceitar conexões QUIC. Para usar esta opção, o Angie deve ter o módulo HTTP3 habilitado e configurado. Com `quic` definido, você também pode especificar `reuseport` para que múltiplos processos worker possam ser usados.
`proxy_protocol`	indica que todas as conexões aceitas neste socket de escuta devem usar o protocolo PROXY.

A diretiva listen também pode especificar vários parâmetros adicionais específicos para chamadas de sistema relacionadas a sockets. Estes parâmetros podem ser especificados em qualquer diretiva listen, mas apenas uma vez para um determinado socket de escuta.

`setfib=`number	define a tabela de roteamento, FIB (a opção `SO_SETFIB`) para o socket de escuta. Atualmente isso funciona apenas no FreeBSD.
`fastopen=`number	habilita "TCP Fast Open" para o socket de escuta e limita o comprimento máximo para a fila de conexões que ainda não completaram o handshake de três vias.

Aviso

Não habilite "TCP Fast Open" a menos que o servidor possa lidar com o recebimento do mesmo pacote SYN com dados mais de uma vez.

Aviso

Não habilite "TCP Fast Open" a menos que o servidor possa lidar com o recebimento do mesmo pacote SYN com dados mais de uma vez.

`backlog=`number	define o parâmetro `backlog` na chamada `listen()` que limita o comprimento máximo da fila de conexões pendentes. Por padrão, backlog é definido como -1 no FreeBSD, DragonFly BSD e macOS, e como 511 em outras plataformas.
`rcvbuf=`size	define o tamanho do buffer de recebimento (a opção `SO_RCVBUF`) para o socket de escuta.
`sndbuf=`size	define o tamanho do buffer de envio (a opção `SO_SNDBUF`) para o socket de escuta.
`accept_filter=`filter	define o nome do filtro de aceitação (a opção `SO_ACCEPTFILTER`) para o socket de escuta que filtra conexões de entrada antes de passá-las para `accept()`. Isso funciona apenas no FreeBSD e NetBSD 5.0+. Os valores possíveis são `dataready` e `httpready`.
`deferred`	instrui a usar um `accept()` adiado (a opção de socket `TCP_DEFER_ACCEPT`) no Linux.
`bind`	instrui a fazer uma chamada `bind()` separada para um determinado par endereço:porta. Isso é útil porque se houver várias diretivas `listen` com a mesma porta mas endereços diferentes, e uma das diretivas `listen` escuta em todos os endereços para a `porta` dada (`:porta`), o Angie fará `bind()` apenas para `:porta`. Deve-se notar que a chamada de sistema `getsockname()` será feita neste caso para determinar o endereço que aceitou a conexão. Se os parâmetros `setfib`, `fastopen`, `backlog`, `rcvbuf`, `sndbuf`, `accept_filter`, `deferred`, `ipv6only`, `reuseport` ou `so_keepalive` forem usados, então para um determinado par `endereço:porta` uma chamada `bind()` separada sempre será feita.
`ipv6only=on` \| `off`	determina (via a opção de socket `IPV6_V6ONLY`) se um socket IPv6 escutando em um endereço curinga [::] aceitará apenas conexões IPv6 ou tanto conexões IPv6 quanto IPv4. Este parâmetro está ativado por padrão. Só pode ser definido uma vez na inicialização.
`reuseport`	instrui a criar um socket de escuta individual para cada processo worker (usando a opção de socket `SO_REUSEPORT` no Linux 3.9+ e DragonFly BSD, ou `SO_REUSEPORT_LB` no FreeBSD 12+), permitindo que o kernel distribua conexões de entrada entre processos worker. Atualmente isso funciona apenas no Linux 3.9+, DragonFly BSD e FreeBSD 12+. Aviso O uso inadequado do parâmetro `reuseport` pode ter implicações de segurança.
`multipath`	habilita a aceitação de conexões via Multipath TCP (MPTCP), suportado no kernel Linux desde a versão 5.6. Este parâmetro é incompatível com `quic`.

so_keepalive=on | off | [keepidle]:[samp:keepintvl]:[samp:keepcnt]

Configura o comportamento "TCP keepalive" para o socket de escuta.

`''`	se este parâmetro for omitido, então as configurações do sistema operacional estarão em vigor para o socket
`on`	a opção `SO_KEEPALIVE` é ativada para o socket
`off`	a opção `SO_KEEPALIVE` é desativada para o socket

Alguns sistemas operacionais suportam a configuração de parâmetros TCP keepalive em uma base por socket usando as opções de socket TCP_KEEPIDLE, TCP_KEEPINTVL e TCP_KEEPCNT. Em tais sistemas, eles podem ser configurados usando os parâmetros keepidle, keepintvl e keepcnt. Um ou dois parâmetros podem ser omitidos, caso em que a configuração padrão do sistema para a opção de socket correspondente estará em vigor. Por exemplo,

so_keepalive=30m::10

definirá o timeout de inatividade (TCP_KEEPIDLE) para 30 minutos, deixará o intervalo de sonda (TCP_KEEPINTVL) em seu padrão do sistema, e definirá a contagem de sondas (TCP_KEEPCNT) para 10 sondas.

Exemplo:

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

location#

Sintaxe	`location` ([ = \| ~ \| ~* \| ^~ ] uri \| `@name`)+ { ... }
Padrão	—
Contexto	server, location

Define a configuração dependendo de se o URI da requisição corresponde a qualquer uma das expressões de correspondência.

A correspondência é realizada contra um URI normalizado, após decodificar o texto codificado na forma "%XX", resolver referências a componentes de caminho relativo "." e "..", e possível compressão de duas ou mais barras adjacentes em uma única barra.

Um location pode ser definido por uma string de prefixo, ou por uma expressão regular.

Expressões regulares são especificadas com o modificador precedente:

`~*`	Correspondência insensível a maiúsculas e minúsculas
`~`	Correspondência sensível a maiúsculas e minúsculas

Para encontrar um location que corresponda a uma requisição, o Angie primeiro verifica os locations definidos com strings de prefixo (locations de prefixo). Entre eles, o location com o prefixo correspondente mais longo é selecionado e lembrado.

Nota

Para sistemas operacionais insensíveis a maiúsculas e minúsculas como macOS, a correspondência de string de prefixo é insensível a maiúsculas e minúsculas. No entanto, a correspondência é limitada a locales de byte único.

Em seguida, as expressões regulares são verificadas na ordem de sua aparição no arquivo de configuração. A busca para após a primeira correspondência, e a configuração correspondente é usada. Se nenhuma correspondência com uma expressão regular for encontrada, então a configuração do location de prefixo lembrado anteriormente é usada.

Com algumas exceções mencionadas abaixo, blocos location podem ser aninhados.

Expressões regulares podem criar grupos de captura que podem ser usados posteriormente com outras diretivas.

Se o location de prefixo correspondente mais longo tiver o modificador ^~, então as expressões regulares não são verificadas.

Além disso, usando o modificador =, é possível definir uma correspondência exata de URI e location. Se uma correspondência exata for encontrada, a busca termina. Por exemplo, se uma requisição / acontece frequentemente, definir location =/ acelerará o processamento dessas requisições, pois a busca termina após a primeira comparação. Tal location não pode conter locations aninhados, pois define uma correspondência exata.

Exemplo:

location =/ {
   #configuração A
}

location / {
   #configuração B
}

location /documents/ {
   #configuração C
}

location ^~/images/ {
   #configuração D
}

location ~*\.(gif|jpg|jpeg)$ {
   #configuração E
}

Uma requisição / corresponderá à configuração A,
uma requisição /index.html corresponderá à configuração B,
uma requisição /documents/document.html corresponderá à configuração C,
uma requisição /images/1.gif corresponderá à configuração D,
e uma requisição /documents/1.jpg corresponderá à configuração E.

Nota

Se um prefixo location termina com uma barra e auto_redirect está habilitado, ocorre o seguinte: Quando uma requisição chega com a URI que não possui barra final mas que corresponde exatamente ao prefixo, um redirecionamento permanente com código 301 é retornado, apontando para a URI solicitada com a barra anexada.

Com uma localização de correspondência exata de URI, o redirecionamento não é aplicado:

location /user/ {
  proxy_pass http://user.example.com;
}

location =/user {
  proxy_pass http://login.example.com;
}

O prefixo @ define um location nomeado. Tais localizações não são usadas para processamento regular de requisições, mas são destinadas apenas para redirecionamento de requisições. Elas não podem ser aninhadas e não podem conter localizações aninhadas.

Localizações combinadas#

Vários contextos location que definem blocos de configuração idênticos podem ser compactados listando todas as suas expressões correspondentes em uma única location com um único bloco de configuração. Isso é chamado de location combinada.

Suponha que as configurações A, D e E do exemplo anterior definam configurações idênticas; você pode combiná-las em uma location:

location =/
         ^~/images/
         ~*\.(gif|jpg|jpeg)$ {
   # configuração geral
}

Uma location nomeada também pode fazer parte da combinação:

location =/
         @named_combined {
   #...
}

Aviso

Uma location combinada não pode ter um espaço entre a expressão correspondente e seu modificador. Forma correta: location ~*/match(ing|es|er)$ ....

Nota

Atualmente, uma location combinada não pode conter imediatamente nem proxy_pass e diretivas similares com URI definido, nem api ou alias. No entanto, essas diretivas podem ser usadas por localizações aninhadas dentro de uma localização combinada.

log_not_found#

Sintaxe	`log_not_found` `on` \| `off`;
Padrão	`log_not_found on;`
Contexto	http, server, location

Habilita ou desabilita o registro de erros sobre arquivos não encontrados no error_log.

log_subrequest#

Sintaxe	`log_subrequest` `on` \| `off`;
Padrão	`log_subrequest off;`
Contexto	http, server, location

Habilita ou desabilita o registro de sub-requisições no access_log.

max_headers#

Sintaxe	`max_headers` number;
Padrão	`max_headers 1000;`
Contexto	http, server

Define o número máximo de campos de cabeçalho de requisição do cliente permitidos. Se este limite for excedido, um erro 400 (Bad Request) é retornado.

Quando esta diretiva é definida no nível server, o valor do servidor padrão pode ser aplicado. Para mais informações, consulte a seção Seleção de servidor virtual.

max_ranges#

Sintaxe	`max_ranges` number;
Padrão	—
Contexto	http, server, location

Limita o número máximo permitido de intervalos em requisições byte-range. Requisições que excedem o limite são processadas como se não houvesse intervalos de bytes especificados. Por padrão, o número de intervalos não é limitado.

`0`	desabilita completamente o suporte a byte-range

merge_slashes#

Sintaxe	`merge_slashes` `on` \| `off`;
Padrão	`merge_slashes on;`
Contexto	http, server

Habilita ou desabilita a compressão de duas ou mais barras adjacentes em um URI em uma única barra.

Note que a compressão é essencial para a correspondência correta de string de prefixo e localizações de expressão regular. Sem ela, a requisição //scripts/one.php não corresponderia

location /scripts/ { }

e poderia ser processada como um arquivo estático. Então ela é convertida para /scripts/one.php.

Desativar a compressão pode se tornar necessário se um URI contém nomes codificados em base64, já que base64 usa o caractere "/" internamente. No entanto, por considerações de segurança, é melhor evitar desativar a compressão.

Se a diretiva for especificada no nível server, o valor do servidor padrão pode ser usado.

msie_padding#

Sintaxe	`msie_padding` `on` \| `off`;
Padrão	`msie_padding on;`
Contexto	http, server, location

Habilita ou desabilita a adição de comentários às respostas para clientes MSIE com status maior que 400 para aumentar o tamanho da resposta para 512 bytes.

msie_refresh#

Sintaxe	`msie_refresh` `on` \| `off`;
Padrão	`msie_refresh off;`
Contexto	http, server, location

Habilita ou desabilita a emissão de atualizações em vez de redirecionamentos para clientes MSIE.

open_file_cache#

Sintaxe

open_file_cache off;

open_file_cache max=N [inactive=time];

Padrão

open_file_cache off;

Contexto

http, server, location

Configura um cache que pode armazenar:

descritores de arquivo abertos, seus tamanhos e tempos de modificação;
informações sobre existência de diretórios;
erros de busca de arquivo, como "arquivo não encontrado", "sem permissão de leitura", e assim por diante.

O cache de erros deve ser habilitado separadamente pela diretiva open_file_cache_errors.

max

define o número máximo de elementos no cache; no overflow do cache os elementos menos recentemente usados (LRU) são removidos;

inactive

define um tempo após o qual um elemento é removido do cache se não foi acessado durante este tempo;

Por padrão, é definido como 60 segundos.

off

desabilita o cache.

Exemplo:

open_file_cache          max=1000 inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

open_file_cache_errors#

Sintaxe	`open_file_cache_errors` `on` \| `off`;
Padrão	`open_file_cache_errors off;`
Contexto	http, server, location

Habilita ou desabilita o cache de erros de busca de arquivo por open_file_cache.

open_file_cache_min_uses#

Sintaxe	`open_file_cache_min_uses` number;
Padrão	`open_file_cache_min_uses 1;`
Contexto	http, server, location

Define o número mínimo de acessos ao arquivo durante o período configurado pelo parâmetro inactive da diretiva open_file_cache, necessário para que um descritor de arquivo permaneça aberto no cache.

open_file_cache_valid#

Sintaxe	`open_file_cache_valid` time;
Padrão	`open_file_cache_valid 60s;`
Contexto	http, server, location

Define um tempo após o qual os elementos do open_file_cache devem ser validados.

output_buffers#

Sintaxe	`output_buffers` number size;
Padrão	`output_buffers 2 32k;`
Contexto	http, server, location

Define o número e o tamanho dos buffers usados para ler uma resposta do disco.

port_in_redirect#

Sintaxe	`port_in_redirect` `on` \| `off`;
Padrão	`port_in_redirect on;`
Contexto	http, server, location

Habilita ou desabilita a especificação da porta em redirecionamentos absolutos emitidos pelo Angie.

O uso do nome do servidor primário em redirecionamentos é controlado pela diretiva server_name_in_redirect.

postpone_output#

Sintaxe	`postpone_output` size;
Padrão	`postpone_output 1460;`
Contexto	http, server, location

Se possível, a transmissão de dados do cliente será adiada até que o Angie tenha pelo menos o número especificado de bytes para enviar.

`0`	desabilita o adiamento da transmissão de dados

read_ahead#

Sintaxe	`read_ahead` size;
Padrão	`read_ahead 0;`
Contexto	http, server, location

Define a quantidade de pré-leitura para o kernel ao trabalhar com arquivos.

No Linux, a chamada de sistema posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL) é usada, e portanto o parâmetro size é ignorado.

No FreeBSD, a chamada de sistema fcntl(O_READAHEAD, size ), suportada desde FreeBSD 9.0-CURRENT, é usada.

recursive_error_pages#

Sintaxe	`recursive_error_pages` `on` \| `off`;
Padrão	`recursive_error_pages off;`
Contexto	http, server, location

Habilita ou desabilita fazer vários redirecionamentos usando a diretiva error_page. O número de tais redirecionamentos é limitado.

request_pool_size#

Sintaxe	`request_pool_size` size;
Padrão	`request_pool_size 4k;`
Contexto	http, server

Permite o ajuste preciso das alocações de memória por requisição. Esta diretiva tem impacto mínimo na performance e geralmente não deve ser usada.

reset_timedout_connection#

Sintaxe	`reset_timedout_connection` `on` \| `off`;
Padrão	`reset_timedout_connection off;`
Contexto	http, server, location

Habilita ou desabilita o reset de conexões que expiraram e conexões fechadas com o código não-padrão 444. O reset é realizado da seguinte forma. Antes de fechar um socket, a opção SO_LINGER é definida para ele com um valor de timeout de 0. Quando o socket é fechado, TCP RST é enviado para o cliente, e toda a memória associada com este socket é liberada. Isso ajuda a evitar manter um socket já fechado no estado FIN_WAIT1 com buffers preenchidos por muito tempo.

Nota

conexões keep-alive são fechadas normalmente quando expiram.

resolver#

Sintaxe	`resolver` address ... [`valid=`time] [`ipv4=on` \| `off`] [`ipv6=on` \| `off`] [`status_zone=`zone];
Padrão	—
Contexto	http, server, location, upstream

Configura servidores de nomes usados para resolver nomes de servidores upstream em endereços, por exemplo:

resolver 127.0.0.53 [::1]:5353;

O endereço pode ser especificado como um nome de domínio ou endereço IP, com uma porta opcional. Se a porta não for especificada, a porta 53 é usada. Os servidores de nomes são consultados em modo round-robin.

Por padrão, o Angie faz cache das respostas usando o valor TTL de uma resposta.

valid

parâmetro opcional permite sobrescrever o período de validade do cache de resposta

resolver 127.0.0.53 [::1]:5353 valid=30s;

Por padrão, o Angie procurará tanto endereços IPv4 quanto IPv6 durante a resolução.

`ipv4=off`	desabilita a busca de endereços IPv4
`ipv6=off`	desabilita a busca de endereços IPv6

status_zone

parâmetro opcional; habilita a coleta de métricas de solicitação e resposta do servidor DNS (/status/resolvers/<zone>) na zona especificada

Dica

Para prevenir spoofing de DNS, é recomendado usar servidores DNS em uma rede local confiável adequadamente protegida.

Dica

Ao executar no Docker, use o endereço do servidor DNS interno correspondente, como 127.0.0.11.

resolver_timeout#

Sintaxe	`resolver_timeout` time;
Padrão	`resolver_timeout 30s;`
Contexto	http, server, location, upstream

Define um timeout para resolução de nomes, por exemplo:

resolver_timeout 5s;

root#

Sintaxe	`root` path;
Padrão	`root html;`
Contexto	http, server, location, if in location

Define o diretório raiz para solicitações. Por exemplo, com a seguinte configuração

location /i/ {
  root /data/w3;
}

O arquivo /data/w3/i/top.gif será enviado em resposta à solicitação /i/top.gif.

O valor path pode conter variáveis, exceto $document_root e $realpath_root.

Um caminho para o arquivo é construído simplesmente adicionando uma URI ao valor da diretiva root. Se uma URI precisa ser modificada, a diretiva alias deve ser usada.

satisfy#

Sintaxe	`satisfy` `all` \| `any`;
Padrão	`satisfy all;`
Contexto	http, server, location

Permite acesso se todos (all) ou pelo menos um (any) dos módulos Access, Auth Basic, ou Auth Request permitirem acesso.

location / {
  satisfy any;

  allow 192.168.1.0/32;
  deny  all;

  auth_basic           "closed site";
  auth_basic_user_file conf/htpasswd;
}

send_lowat#

Sintaxe	`send_lowat` size;
Padrão	`send_lowat 0;`
Contexto	http, server, location

Se a diretiva for definida com um valor diferente de zero, o Angie tentará minimizar o número de operações de envio nos sockets do cliente usando a flag NOTE_LOWAT do método kqueue ou a opção de socket SO_SNDLOWAT. Em ambos os casos, o tamanho especificado é usado.

send_timeout#

Sintaxe	`send_timeout` time;
Padrão	`send_timeout 60s;`
Contexto	http, server, location

Define um timeout para transmitir uma resposta ao cliente. O timeout é definido apenas entre duas operações de escrita sucessivas, não para a transmissão de toda a resposta. Se o cliente não receber nada dentro deste tempo, a conexão é fechada.

sendfile#

Sintaxe	`sendfile` `on` \| `off`;
Padrão	`sendfile off;`
Contexto	http, server, location, if in location

Habilita ou desabilita o uso de sendfile().

aio pode ser usado para pré-carregar dados para sendfile():

location /video/ {
  sendfile       on;
  tcp_nopush     on;
  aio            on;
}

Nesta configuração, sendfile() é chamado com a flag SF_NODISKIO que faz com que não bloqueie na E/S do disco, mas, em vez disso, reporte que os dados não estão na memória. O Angie então inicia um carregamento assíncrono de dados lendo um byte. Na primeira leitura, o kernel do FreeBSD carrega os primeiros 128K bytes de um arquivo na memória, embora as próximas leituras carreguem apenas dados em blocos de 16K. Isso pode ser alterado usando a diretiva read_ahead.

sendfile_max_chunk#

Sintaxe	`sendfile_max_chunk` size;
Padrão	`sendfile_max_chunk 2m;`
Contexto	http, server, location

Limita a quantidade de dados que pode ser transferida em uma única chamada sendfile(). Sem o limite, uma conexão rápida pode monopolizar completamente o processo worker.

server#

Sintaxe	`server` { ... }
Padrão	—
Contexto	http

Define a configuração para um servidor virtual. Não há separação clara entre servidores virtuais baseados em IP (baseados no endereço IP) e baseados em nome (baseados no campo de cabeçalho de solicitação "Host"). Em vez disso, as diretivas listen descrevem todos os endereços e portas que devem aceitar conexões para o servidor, e a diretiva server_name lista todos os nomes de servidor.

Exemplos de configurações são fornecidos no documento Como o Angie processa uma solicitação.

server_name#

Sintaxe	`server_name` name ...;
Padrão	`server_name ""`;
Contexto	server

Define nomes de um servidor virtual, por exemplo:

server {
  server_name example.com www.example.com;
}

O primeiro nome torna-se o nome primário do servidor.

Nomes de servidor podem incluir um asterisco ("*") substituindo a primeira ou última parte de um nome:

server {
  server_name example.com *.example.com www.example.*;
}

Tais nomes são chamados de nomes curinga.

Os dois primeiros nomes mencionados acima podem ser combinados em um:

server {
  server_name .example.com;
}

Também é possível usar expressões regulares em nomes de servidor, precedendo o nome com um til ("~"):

server {
  server_name ~^www\d+\.example\.com$ www.example.com;
}

Expressões regulares podem conter capturas que podem ser usadas posteriormente em outras diretivas:

server {
  server_name ~^(www\.)?(.+)$;

  location / {
     root /sites/$2;
  }
}

server {
  server_name _;

  location / {
     root /sites/default;
  }
}

Grupos de captura nomeados em expressões regulares criam variáveis que podem então ser usadas em outras diretivas:

server {
  server_name ~^(www\.)?(?<domain>.+)$;

  location / {
     root /sites/$domain;
  }
}

server {
  server_name _;

  location / {
     root /sites/default;
  }
}

Nota

Se a diretiva for definida como $hostname, o nome do host do servidor web é usado.

Você também pode especificar um nome de servidor vazio (""):

server {
    server_name www.example.com "";
}

Ao procurar por um servidor virtual por um nome que é correspondido por múltiplas opções (por exemplo, tanto um curinga quanto uma expressão regular), a primeira opção correspondente será selecionada na seguinte ordem de prioridade:

nome exato;
nome mais longo com um curinga no início, como *.example.com;
nome mais longo com um curinga no final, como mail.*;
a primeira expressão regular correspondente (na ordem de aparição na configuração), incluindo um nome vazio.

Aviso

Para fazer o server_name funcionar com TLS, você precisa terminar a conexão TLS. A diretiva corresponde ao Host em uma requisição HTTP, então o handshake deve ser completado e a conexão descriptografada.

server_name_in_redirect#

Sintaxe	`server_name_in_redirect` `on` \| `off`;
Padrão	`server_name_in_redirect off`;
Contexto	http, server, location

Habilita ou desabilita o uso do nome do servidor primário, especificado pela diretiva server_name, em redirecionamentos absolutos emitidos pelo Angie.

`on`	o nome do servidor primário, especificado pela diretiva server_name, é usado
`off`	o nome do campo de cabeçalho de requisição "Host" é usado. Se este campo não estiver presente, o endereço IP do servidor é usado.

O uso de uma porta em redirecionamentos é controlado pela diretiva port_in_redirect.

server_names_hash_bucket_size#

Sintaxe	`server_names_hash_bucket_size` size;
Padrão	`server_names_hash_bucket_size 32` \| `64` \| `128;`
Contexto	http

Define o tamanho do bucket para as tabelas hash de nomes de servidor. O valor padrão depende do tamanho da linha de cache do processador. Os detalhes da configuração de tabelas hash são fornecidos em um documento separado.

server_names_hash_max_size#

Sintaxe	`server_names_hash_max_size` size;
Padrão	`server_names_hash_max_size 512`;
Contexto	http

Define o tamanho máximo das tabelas hash de nomes de servidor. Os detalhes da configuração de tabelas hash são fornecidos em um documento separado.

server_tokens#

Sintaxe	`server_tokens` `on` \| `off` \| `build` \| string;
Padrão	`server_tokens on;`
Contexto	http, server, location

Habilita ou desabilita a emissão da versão do Angie em páginas de erro e no campo de cabeçalho de resposta Server. O parâmetro build habilita a emissão do nome da build, definido pelo respectivo parâmetro configure, junto com a versão.

Adicionado na versão 1.1.0: PRO

No Angie PRO, se a diretiva define uma string, que também pode conter variáveis, as páginas de erro e o campo de cabeçalho de resposta Server usarão o valor interpolado das variáveis da string em vez do nome do servidor, versão e nome da build. Uma string vazia desabilita a emissão do campo Server.

status_zone#

Sintaxe	`status_zone` `off` \| zone \| key `zone=`zone[:number];
Padrão	—
Contexto	server, location, if in location

Aloca uma zona de memória compartilhada para coletar métricas de /status/http/location_zones/<zone> e /status/http/server_zones/<zone>.

Vários contextos server podem compartilhar a mesma zona para coleta de dados; o valor especial off desabilita a coleta de dados em blocos location aninhados.

A sintaxe com um único valor zone combina todas as métricas para o contexto atual em uma zona de memória compartilhada:

server {

    listen 80;
    server_name *.example.com;

    status_zone single;
    # ...
}

A sintaxe alternativa permite definir os seguintes parâmetros:

key

Uma string com variáveis, cujo valor determina o agrupamento de requisições na zona. Todas as requisições que produzem valores idênticos após substituição são agrupadas juntas. Se a substituição produzir um valor vazio, as métricas não são atualizadas.

zone

O nome da zona de memória compartilhada.

number (opcional)

O número máximo de grupos separados para coletar métricas. Se novos valores de key excederem este limite, eles são agrupados sob zone.

O valor padrão é 1.

No exemplo a seguir, todas as requisições que compartilham o mesmo valor $host são agrupadas na host_zone. As métricas são rastreadas separadamente para cada $host único até que haja 10 grupos de métricas. Uma vez que este limite seja atingido, quaisquer valores $host adicionais são incluídos sob a host_zone:

server {

    listen 80;
    server_name *.example.com;

    status_zone $host zone=host_zone:10;

    location / {

        proxy_pass http://example.com;
    }
}

As métricas resultantes são assim divididas entre hosts individuais na saída da API.

subrequest_output_buffer_size#

Sintaxe	`subrequest_output_buffer_size` size;
Padrão	`subrequest_output_buffer_size 4k` \| `8k;`
Contexto	http, server, location

Define o tamanho do buffer usado para armazenar o corpo da resposta de uma subrequisição. Por padrão, o tamanho do buffer é igual a uma página de memória. Isso é 4K ou 8K, dependendo da plataforma. Pode ser feito menor, no entanto.

Nota

A diretiva é aplicável apenas para subrequisições com corpos de resposta salvos na memória. Por exemplo, tais subrequisições são criadas por SSI.

tcp_nodelay#

Sintaxe	`tcp_nodelay` `on` \| `off`;
Padrão	`tcp_nodelay on;`
Contexto	http, server, location

Habilita ou desabilita o uso da opção TCP_NODELAY. A opção é habilitada quando uma conexão é transicionada para o estado keep-alive. Adicionalmente, é habilitada em conexões SSL, para proxy sem buffer, e para proxy WebSocket.

tcp_nopush#

Sintaxe	`tcp_nopush` `on` \| `off`;
Padrão	`tcp_nopush off`;
Contexto	http, server, location

Habilita ou desabilita o uso da opção de socket TCP_NOPUSH no FreeBSD ou da opção de socket TCP_CORK no Linux. As opções são habilitadas apenas quando sendfile é usado. Habilitar a opção permite

enviar o cabeçalho da resposta e o início de um arquivo em um pacote, no Linux e FreeBSD 4.*;
enviar um arquivo em pacotes completos.

try_files#

Sintaxe

try_files file ... uri;

try_files file ... =code;

Padrão

—

Contexto

server, location

Verifica a existência de arquivos na ordem especificada e usa o primeiro arquivo encontrado para o processamento da requisição; o processamento é realizado no contexto atual. O caminho para um arquivo é construído a partir do parâmetro file de acordo com as diretivas root e alias. É possível verificar a existência de um diretório especificando uma barra no final do nome, por exemplo $uri/. Se nenhum dos arquivos for encontrado, um redirecionamento interno para o uri especificado no último parâmetro é feito. Por exemplo:

location /images/ {
  try_files $uri /images/default.gif;
}

location = /images/default.gif {
  expires 30s;
}

O último parâmetro também pode apontar para um location nomeado, como mostrado nos exemplos abaixo. O último parâmetro também pode ser um código:

location / {
  try_files $uri $uri/index.html $uri.html =404;
}

No exemplo a seguir,

location / {
  try_files $uri $uri/ @drupal;
}

a diretiva try_files é equivalente a

location / {
  error_page 404 = @drupal;
  log_not_found off;
}

E aqui,

location ~ \.php$ {
  try_files $uri @drupal;

  fastcgi_pass ...;

  fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;

#  ...
}

try_files verifica a existência do arquivo PHP antes de passar a requisição para o servidor FastCGI.

Exemplo em proxy Mongrel:

location / {
  try_files /system/maintenance.html
           $uri $uri/index.html $uri.html
           @mongrel;
}

location @mongrel {
  proxy_pass http://mongrel;
}

Exemplo para Drupal/FastCGI:

location / {
  try_files $uri $uri/ @drupal;
}

location ~ \.php$ {
  try_files $uri @drupal;

  fastcgi_pass ...;

  fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
  fastcgi_param SCRIPT_NAME     $fastcgi_script_name;
  fastcgi_param QUERY_STRING    $args;

#  ... outros fastcgi_param
}

location @drupal {
  fastcgi_pass ...;

  fastcgi_param SCRIPT_FILENAME /path/to/index.php;
  fastcgi_param SCRIPT_NAME     /index.php;
  fastcgi_param QUERY_STRING    q=$uri&$args;

#  ... outros fastcgi_param
}

Exemplo para Wordpress e Joomla:

location / {
  try_files $uri $uri/ @wordpress;
}

location ~ \.php$ {
  try_files $uri @wordpress;

  fastcgi_pass ...;

  fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
#  ... outros fastcgi_param
}

location @wordpress {
  fastcgi_pass ...;

  fastcgi_param SCRIPT_FILENAME /path/to/index.php;
#  ... outros fastcgi_param
}

types#

Sintaxe	`types` { ... }
Padrão	`types text/html html; image/gif gif; image/jpeg jpg;`
Contexto	http, server, location

Mapeia extensões de nomes de arquivo para tipos MIME de respostas. As extensões não diferenciam maiúsculas de minúsculas. Várias extensões podem ser mapeadas para um tipo, por exemplo:

types {
  application/octet-stream bin exe dll;
  application/octet-stream deb;
  application/octet-stream dmg;
}

Uma tabela de mapeamento suficientemente completa é distribuída com o Angie e está localizada no arquivo conf/mime.types.

Para fazer um location específico retornar o tipo MIME "application/octet-stream" para todas as respostas, a seguinte configuração pode ser usada:

location /download/ {
  types        { }
  default_type application/octet-stream;
}

types_hash_bucket_size#

Sintaxe	`types_hash_bucket_size` size;
Padrão	`types_hash_bucket_size 64;`
Contexto	http, server, location

Define o tamanho do bucket para as tabelas hash de tipos. Os detalhes da configuração de tabelas hash são discutidos separadamente.

types_hash_max_size#

Sintaxe	`types_hash_max_size` size;
Padrão	`types_hash_max_size 1024;`
Contexto	http, server, location

Define o tamanho máximo das tabelas hash de tipos. Os detalhes da configuração de tabelas hash são discutidos separadamente.

underscores_in_headers#

Sintaxe	`underscores_in_headers` `on` \| `off`;
Padrão	`underscores_in_headers off`;
Contexto	http, server

Habilita ou desabilita o uso de sublinhados em campos de cabeçalho de requisição do cliente. Quando o uso de sublinhados está desabilitado, campos de cabeçalho de requisição cujos nomes contêm sublinhados são marcados como inválidos e estão sujeitos à diretiva ignore_invalid_headers.

Se a diretiva for especificada no nível server, o valor do servidor padrão pode ser usado.

variables_hash_bucket_size#

Sintaxe	`variables_hash_bucket_size` size;
Padrão	`variables_hash_bucket_size 64;`
Contexto	http

Define o tamanho do bucket para a tabela hash de variáveis. Os detalhes da configuração de tabelas hash são discutidos separadamente.

variables_hash_max_size#

Sintaxe	`variables_hash_max_size` size;
Padrão	`variables_hash_max_size 1024;`
Contexto	http

Define o tamanho máximo da tabela hash de variáveis. Os detalhes da configuração de tabelas hash são discutidos separadamente.

Variáveis Integradas#

O módulo http_core suporta variáveis integradas com nomes correspondentes às variáveis do Apache Server. Em primeiro lugar, estas são variáveis que representam campos de cabeçalho de requisição do cliente, como $http_user_agent, $http_cookie, e assim por diante. Além disso, existem outras variáveis:

`$angie_version`#

versão do Angie

`$arg_<name>`#

argumento name na linha de requisição

`$args`#

argumentos na linha de requisição

`$binary_remote_addr`#

endereço do cliente em forma binária, o comprimento do valor é sempre 4 bytes para endereços IPv4 ou 16 bytes para endereços IPv6

`$body_bytes_sent`#

número de bytes enviados ao cliente, não contando o cabeçalho de resposta; esta variável é compatível com o parâmetro "%B" do módulo mod_log_config do Apache

`$bytes_sent`#

número de bytes enviados a um cliente

`$connection`#

número serial da conexão

`$connection_requests`#

número atual de requisições feitas através de uma conexão

`$connection_time`#

tempo de conexão em segundos com resolução de milissegundos

`$content_length`#

campo de cabeçalho de requisição Content-Length

`$content_type`#

campo de cabeçalho de requisição Content-Type

`$document_root`#

valor da diretiva root ou alias para a requisição atual

`$document_uri`#

mesmo que $uri

`$host`#

nesta ordem de precedência: nome do host da linha de requisição, ou nome do host do campo de cabeçalho de requisição "Host", ou o nome do servidor correspondente a uma requisição

`$hostname`#

nome do host

`$http_<name>`#

campo de cabeçalho de requisição arbitrário; a última parte do nome da variável corresponde ao nome do campo convertido para minúsculas com traços substituídos por sublinhados

`$https`#

on se a conexão opera em modo SSL, ou uma string vazia caso contrário

`$is_args`#

? se uma linha de requisição tem argumentos, ou uma string vazia caso contrário

`$limit_rate`#

definir esta variável habilita limitação de taxa de resposta; veja limit_rate

`$msec`#

tempo atual em segundos com resolução de milissegundos

`$pid`#

PID do processo worker

`$pipe`#

p se a requisição foi pipelined, . caso contrário

`$proxy_protocol_addr`#

endereço do cliente do cabeçalho do protocolo PROXY

O protocolo PROXY deve ser previamente habilitado definindo o parâmetro proxy_protocol na diretiva listen.

`$proxy_protocol_port`#

porta do cliente do cabeçalho do protocolo PROXY

O protocolo PROXY deve ser previamente habilitado definindo o parâmetro proxy_protocol na diretiva listen.

`$proxy_protocol_server_addr`#

endereço do servidor do cabeçalho do protocolo PROXY

O protocolo PROXY deve ser previamente habilitado definindo o parâmetro proxy_protocol na diretiva listen.

`$proxy_protocol_server_port`#

porta do servidor do cabeçalho do protocolo PROXY

O protocolo PROXY deve ser previamente habilitado definindo o parâmetro proxy_protocol na diretiva listen.

`$proxy_protocol_tlv_<name>`#

TLV do cabeçalho do protocolo PROXY. O name pode ser um nome de tipo TLV ou seu valor numérico. No último caso, o valor é hexadecimal e deve ser prefixado com 0x:

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

TLVs SSL também podem ser acessados por nome de tipo TLV ou seu valor numérico, ambos prefixados por ssl_:

$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21

Os seguintes nomes de tipo TLV são suportados:

alpn (0x01) - protocolo de camada superior usado sobre a conexão
authority (0x02) - valor do nome do host passado pelo cliente
unique_id (0x05) - id único da conexão
netns (0x30) - nome do namespace
ssl (0x20) - estrutura TLV SSL binária

Os seguintes nomes de tipo SSL TLV são suportados:

ssl_version (0x21) - versão SSL usada na conexão do cliente
ssl_cn (0x22) - Nome Comum do certificado SSL
ssl_cipher (0x23) - nome da cifra usada
ssl_sig_alg (0x24) - algoritmo usado para assinar o certificado
ssl_key_alg (0x25) - algoritmo de chave pública

Além disso, o seguinte nome de tipo SSL TLV especial é suportado:

ssl_verify - resultado da verificação do certificado SSL do cliente: 0 se o cliente apresentou um certificado e foi verificado com sucesso, diferente de zero caso contrário

O protocolo PROXY deve ser previamente habilitado definindo o parâmetro proxy_protocol na diretiva listen.

`$query_string`#

mesmo que $args

`$realpath_root`#

um nome de caminho absoluto correspondente ao valor da diretiva root ou alias para a requisição atual, com todos os links simbólicos resolvidos para caminhos reais

`$remote_addr`#

endereço do cliente

`$remote_port`#

porta do cliente

`$remote_user`#

nome de usuário fornecido com a autenticação Basic

`$request`#

linha de requisição original completa

`$request_body`#

corpo da requisição

O valor da variável é disponibilizado em localizações processadas pelas diretivas proxy_pass, fastcgi_pass, uwsgi_pass, e scgi_pass quando o corpo da requisição foi lido para um buffer de memória.

`$request_body_file`#

Nome de um arquivo temporário com o corpo da requisição. No final do processamento, o arquivo precisa ser removido. Para sempre escrever o corpo da requisição em um arquivo, habilite client_body_in_file_only. Ao passar o nome de um arquivo temporário em uma requisição proxy ou em uma requisição para um servidor FastCGI/uwsgi/SCGI, a passagem do próprio corpo da requisição deve ser desabilitada com as diretivas proxy_pass_request_body off, fastcgi_pass_request_body off, uwsgi_pass_request_body off, ou scgi_pass_request_body off, respectivamente.

`$request_completion`#

OK se uma requisição foi completada, ou uma string vazia caso contrário

`$request_filename`#

caminho do arquivo para a requisição atual, baseado nas diretivas root ou alias, e na URI da requisição

`$request_id`#

identificador único da requisição gerado a partir de 16 bytes aleatórios, em hexadecimal

`$request_length`#

comprimento da requisição (incluindo linha de requisição, cabeçalho e corpo da requisição)

`$request_method`#

método da requisição, geralmente GET ou POST

`$request_time`#

tempo de processamento da requisição em segundos com resolução de milissegundos; tempo decorrido desde que os primeiros bytes foram lidos do cliente

`$request_uri`#

URI completa original da requisição (com argumentos)

`$scheme`#

esquema da requisição, "http" ou "https"

`$sent_http_<name>`#

campo de cabeçalho de resposta arbitrário; a última parte do nome da variável corresponde ao nome do campo convertido para minúsculas com traços substituídos por sublinhados

`$sent_trailer_<name>`#

campo arbitrário enviado no final da resposta; a última parte do nome da variável corresponde ao nome do campo convertido para minúsculas com traços substituídos por sublinhados

`$server_addr`#

Endereço do servidor que aceitou uma requisição.

Calcular o valor da variável geralmente requer uma chamada de sistema. Para evitar uma chamada de sistema, as diretivas listen devem especificar endereços e usar o parâmetro bind.

`$server_name`#

nome do servidor que aceitou uma requisição

`$server_port`#

porta do servidor que aceitou uma requisição

`$server_protocol`#

protocolo da requisição, geralmente "HTTP/1.0", "HTTP/1.1", ou "HTTP/2.0"

`$status`#

status da resposta

`$time_iso8601`#

hora local no formato padrão ISO 8601

`$time_local`#

hora local no formato Common Log Format

`$tcpinfo_rtt, $tcpinfo_rttvar, $tcpinfo_snd_cwnd, $tcpinfo_rcv_space`#

informações sobre a conexão TCP do cliente; disponível em sistemas que suportam a opção de socket TCP_INFO

`$uri`#

URI atual na requisição, normalizada.

O valor de $uri pode mudar durante o processamento da requisição, por exemplo, ao fazer redirecionamentos internos, ou ao usar arquivos de índice.