Módulo core#

O módulo fornece funcionalidade essencial e diretivas de configuração necessárias para a operação básica do servidor, e lida com tarefas críticas como gerenciar processos worker, configurar modelos orientados a eventos, e processar conexões e requisições recebidas. Inclui diretivas essenciais para configurar o processo principal, log de erros, e controlar o comportamento do servidor em baixo nível.

Exemplo de configuração#

user www www;
worker_processes 2;

error_log /var/log/error.log info;

events {

    use kqueue; worker_connections 2048;
}

Diretivas#

accept_mutex#

Sintaxe

accept_mutex on | off;

Padrão

accept_mutex off;

Contexto

events

Quando accept_mutex está habilitado, processos worker aceitarão novas conexões alternadamente. Sem essa configuração, todos os processos worker são notificados de novas conexões, o que pode levar ao uso ineficiente de recursos do sistema se o volume de novas conexões for baixo.

Nota

Não há necessidade de habilitar accept_mutex em sistemas que suportam a flag EPOLLEXCLUSIVE ou ao usar a diretiva reuseport.

accept_mutex_delay#

Sintaxe

accept_mutex_delay tempo;

Padrão

accept_mutex_delay 500ms;

Contexto

events

Se accept_mutex estiver habilitado, esta diretiva especifica o tempo máximo que um processo worker aguardará para continuar aceitando novas conexões enquanto outro processo worker já está lidando com novas conexões.

daemon#

Sintaxe

daemon on | off;

Padrão

daemon on;

Contexto

main

Determina se o Angie deve executar como daemon. Isso é usado principalmente durante o desenvolvimento.

debug_connection#

Sintaxe

debug_connection address | CIDR | unix:;

Padrão

—

Contexto

events

Habilita logs de depuração para conexões específicas de clientes. Outras conexões usarão o nível de logging definido pela diretiva error_log. Você pode especificar conexões por endereço IPv4 ou IPv6, rede, ou hostname. Para conexões usando sockets de domínio UNIX, use o parâmetro unix: para habilitar logs de depuração.

events {

    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    #  ...
}

Nota

Para que esta diretiva funcione, o Angie deve ser compilado com log de depuração habilitado.

debug_points#

Sintaxe

debug_points abort | stop;

Padrão

—

Contexto

main

Esta diretiva é usada para depuração.

Quando ocorre um erro interno, como vazamento de socket durante reinicializações de processos worker, habilitar debug_points criará um arquivo core (abort) ou parará o processo (stop) para análise posterior com um depurador do sistema.

env#

Sintaxe

env variable[=value];

Padrão

env TZ;

Contexto

main

Por padrão, o Angie remove todas as variáveis de ambiente herdadas de seu processo pai exceto a variável TZ. Esta diretiva permite preservar algumas variáveis herdadas, modificar seus valores, ou criar novas variáveis de ambiente.

Essas variáveis são então:

Note que controlar bibliotecas do sistema desta forma nem sempre pode ser efetivo, pois bibliotecas frequentemente verificam variáveis apenas durante a inicialização, que ocorre antes desta diretiva fazer efeito. A variável TZ é sempre herdada e acessível ao módulo Perl a menos que explicitamente configurado de outra forma.

Exemplo:

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

Nota

A variável de ambiente ANGIE é usada internamente pelo Angie e não deve ser definida diretamente pelo usuário.

error_log#

Sintaxe

error_log file [level] [[filter=part:match] ...] [rate=rate] [format=format];

Padrão

error_log logs/error.log error; (o caminho depende da opção de compilação --error-log-path)

Contexto

main, http, mail, stream, server, location

Configura o logging, permitindo que múltiplos logs sejam especificados no mesmo nível de configuração. Se um arquivo de log não for explicitamente definido no nível de configuração main, o arquivo padrão será usado.

O primeiro parâmetro especifica o arquivo para armazenar o log. O valor especial stderr seleciona o fluxo de erro padrão. Para configurar logging para syslog, use o prefixo "syslog:". Para fazer log para um buffer de memória cíclico, use o prefixo "memory:" seguido do tamanho do buffer; isso é tipicamente usado para depuração.

O segundo parâmetro define o nível de logging, que pode ser um dos seguintes: debug, info, notice, warn, error, crit, alert, ou emerg. Esses níveis são listados em ordem de severidade crescente. Definir um nível de log capturará mensagens de severidade igual e superior:

Configuração

Níveis Capturados

debug

debug, info, notice, warn, error, crit, alert, emerg

info

info, notice, warn, error, crit, alert, emerg

notice

notice, warn, error, crit, alert, emerg

warn

warn, error, crit, alert, emerg

error

error, crit, alert, emerg

crit

crit, alert, emerg

alert

alert, emerg

emerg

emerg

Se este parâmetro for omitido, error é usado como nível de logging padrão.

Os parâmetros opcionais filter=part:match restringem quais mensagens são gravadas no log, de modo que um único destino possa coletar apenas os eventos de interesse. Cada parâmetro testa uma parte (part) da mensagem em relação ao padrão match, onde part é um dos seguintes:

  • logline — com format=default, a mensagem junto com qualquer erro de sistema e detalhes de contexto, mas sem o prefixo de data e hora, nível, processo, thread e conexão; não corresponde a entradas com format=json;

  • message — com format=default, o texto da mensagem sem erro de sistema nem detalhes de contexto; com format=json, o fragmento serializado e escapado que contém o membro message, e não o seu valor bruto;

  • tag — uma tag anexada à mensagem, incluindo as tags adicionadas pela diretiva error_log_user_tag e por suas contrapartes stream e mail;

  • sourcefile — o arquivo-fonte que emitiu a mensagem; disponível somente quando o Angie é compilado com o log de depuração habilitado;

  • qualquer outro nome — um campo do contexto da mensagem, como um dos campos mostrados no formato JSON abaixo.

Por padrão, o padrão match é comparado como uma substring. Use o prefixo = para exigir correspondência exata, ou ~ para usar uma expressão regular, o que requer uma compilação com a biblioteca PCRE.

Com format=json, uma correspondência exata em message deve cobrir todo o fragmento serializado, incluindo a sintaxe JSON e o escape.

Vários parâmetros filter= podem ser especificados para uma mesma diretiva; uma mensagem só é gravada quando corresponde a todos eles. No entanto, cada campo de contexto pode ser testado por apenas um parâmetro filter= por diretiva: um segundo parâmetro no mesmo campo nunca corresponde, portanto nenhuma mensagem é gravada no destino.

O parâmetro opcional rate=rate limita a taxa máxima de mensagens gravadas no log, em mensagens por segundo; o valor pode terminar com o sufixo m/s (por exemplo, rate=2000m/s). Por padrão, é usado rate=1000 (1000 mensagens por segundo); defina rate=0 para desabilitar o limite.

O limite é aplicado separadamente a cada diretiva error_log e de forma independente em cada processo worker. Uma enxurrada de mensagens de baixa severidade (por exemplo, info) não suprime as de severidade mais alta, como error, pois níveis mais severos têm direito a uma rajada proporcionalmente maior; o inverso não é verdadeiro. As mensagens excedentes são descartadas. Isso limita o log, em vez de silenciá-lo: sob sobrecarga contínua, as mensagens continuam sendo gravadas aproximadamente na taxa configurada.

Quando um destino começa a descartar mensagens, o Angie grava nele um aviso "too many log messages, limiting" do mesmo nível no lugar da primeira mensagem descartada; o aviso pode se repetir durante uma sobrecarga contínua. O aviso não carrega detalhes de contexto nem tags e precisa passar pelos parâmetros filter= do destino, portanto um destino filtrado por tag ou por um campo de contexto nunca o recebe. O aviso também não é gravado no destino com o nível mais detalhado entre as diretivas error_log em vigor (o primeiro declarado, se vários compartilham esse nível), de modo que, com um único destino, nenhum aviso aparece.

A limitação de taxa não se aplica quando o nível de logging debug está em vigor para uma mensagem — seja porque o próprio arquivo de log usa o nível debug, seja porque os logs de depuração estão habilitados para a conexão por meio de debug_connection.

Nota

Para que o nível de logging debug funcione, o Angie deve ser compilado com log de depuração habilitado.

O parâmetro opcional format=format seleciona o formato usado nas entradas do log. O padrão, format=default, produz o formato tradicional de texto simples descrito abaixo; format=json grava cada entrada como um único objeto JSON em uma linha.

No formato padrão, cada entrada no log de erros tem o seguinte formato:

timestamp [level] PID#TID: *connection_id message

Onde:

  • timestamp — data e hora locais do evento

  • level — nível de logging do evento

  • PID#TID — identificadores de processo e thread

  • *connection_id — número serial da conexão, compartilhado por todas as requisições da mesma conexão (se aplicável)

  • message — texto da mensagem de erro ou evento

Com format=json, cada entrada é gravada como um único objeto JSON, mostrado aqui formatado para facilitar a leitura; no arquivo de log ele ocupa uma única linha:

{
    "time": "2026-02-14T09:23:10.874Z",
    "level": "error",
    "pid": 22738,
    "tid": 22738,
    "connection": 7,
    "message": "limiting requests, excess: 1.000 by zone \"one\"",
    "http": {
        "client": "127.0.0.1",
        "request": {
            "server": "localhost",
            "request_line": "GET /debug HTTP/1.1",
            "host": "localhost"
        }
    },
    "tags": [
        "http"
    ]
}

Onde:

  • time — data e hora do evento em UTC, no formato ISO 8601 com o sufixo Z; os milissegundos são incluídos, exceto quando são zero

  • level — nível de logging do evento

  • pid e tid — identificadores de processo e thread

  • connection — número da conexão (o mesmo valor mostrado como *connection_id no formato de texto simples), presente quando a entrada está associada a uma conexão

  • message — texto da mensagem de erro ou evento

  • error — presente quando a mensagem está associada a um erro de sistema; um objeto com os campos code e message

  • http, stream ou mail — um objeto com os detalhes de contexto da entrada, identificado pelo nome do módulo de onde a entrada se originou (um objeto genérico context é usado para detalhes de contexto fora desses módulos); o objeto só aparece em entradas que carregam tais detalhes e são registradas em um nível diferente de debug. O objeto de cada módulo tem seu próprio conjunto de campos; por exemplo, em http, um objeto aninhado request contém request_line, a linha da requisição, além de outros detalhes da requisição

  • tags — lista de tags anexadas à entrada, presente quando pelo menos uma tag se aplica; inclui as tags adicionadas automaticamente pelos módulos e pelas diretivas error_log_user_tag

  • truncated — true, presente somente quando a entrada precisou ser truncada para caber no buffer do log de erros

events#

Sintaxe

events { ... };

Padrão

—

Contexto

main

Fornece o contexto do arquivo de configuração para diretivas que afetam o processamento de conexões.

include#

Sintaxe

include file | mask;

Padrão

—

Contexto

any

Inclui outro arquivo, ou arquivos que correspondem à mask especificada, na configuração. Os arquivos incluídos devem conter diretivas e blocos sintaticamente corretos.

Exemplo:

include mime.types;
include vhosts/*.conf;

load_module#

Sintaxe

load_module arquivo;

Padrão

—

Contexto

main

Carrega um módulo dinâmico do arquivo especificado. Se um caminho relativo for fornecido, ele é interpretado com base na --prefix opção de compilação. Para verificar o caminho:

$ sudo angie -V

Exemplo:

load_module modules/ngx_mail_module.so;

Se um módulo dinâmico foi compilado para uma compilação diferente do Angie, o carregamento falha com um erro como: "module "..." was built for "..." but you are running "Angie"".

lock_file#

Sintaxe

lock_file arquivo;

Padrão

lock_file logs/angie.lock; (o caminho depende da --lock-path opção de compilação)

Contexto

main

O Angie usa um mecanismo de bloqueio para implementar accept_mutex e serializar o acesso à memória compartilhada. Na maioria dos sistemas, os bloqueios são gerenciados usando operações atômicas, tornando esta diretiva desnecessária. Em certos sistemas, no entanto, um mecanismo alternativo de arquivo de bloqueio é usado. Esta diretiva define um prefixo para nomes de arquivos de bloqueio.

master_process#

Sintaxe

master_process on | off;

Padrão

master_process on;

Contexto

main

Determina se os processos worker são iniciados. Esta diretiva é destinada aos desenvolvedores do Angie.

multi_accept#

Sintaxe

multi_accept on | off;

Padrão

multi_accept off;

Contexto

events

on

Um processo worker aceitará todas as novas conexões simultaneamente.

off

Um processo worker aceitará uma nova conexão por vez.

Nota

Esta diretiva é ignorada se o método de processamento de conexão kqueue for usado, pois ele fornece o número de novas conexões prontas para serem aceitas.

pcre_jit#

Sintaxe

pcre_jit on | off;

Padrão

pcre_jit off;

Contexto

main

Habilita ou desabilita a "compilação just-in-time" (PCRE JIT) para expressões regulares conhecidas no momento da análise da configuração.

O PCRE JIT pode acelerar significativamente o processamento de expressões regulares.

Nota

JIT está disponível nas bibliotecas PCRE a partir da versão 8.20, desde que sejam compiladas com a opção de configuração --enable-jit. Quando o Angie é compilado com a biblioteca PCRE (--with-pcre=), o suporte JIT é habilitado usando a opção --with-pcre-jit.

pid#

Sintaxe

pid arquivo | off;

Padrão

pid logs/angie.pid; (o caminho depende da --pid-path opção de compilação)

Contexto

main

Especifica o arquivo que armazenará o ID do processo principal do Angie. O arquivo é criado atomicamente, o que garante que seu conteúdo esteja sempre correto. A configuração off desabilita a criação deste arquivo.

Nota

Se a configuração do arquivo for modificada durante a reconfiguração mas apontar para um link simbólico do arquivo PID anterior, o arquivo não será recriado.

ssl_engine#

Sintaxe

ssl_engine engine;

Padrão

—

Contexto

main

Faz com que o OpenSSL use por padrão o engine com o nome especificado para todos os algoritmos implementados pelo engine. O engine também pode ser definido no arquivo de configuração do OpenSSL.

ssl_object_cache_inheritable#

Sintaxe

ssl_object_cache_inheritable on | off;

Padrão

ssl_object_cache_inheritable on;

Contexto

main

Se habilitado, objetos SSL (certificados SSL, chaves secretas, certificados CA confiáveis, listas CRL) são herdados através de recarregamentos de configuração.

Objetos SSL carregados de arquivos são herdados se seu tempo de modificação e índice de arquivo não mudaram desde o carregamento de configuração anterior. Chaves secretas especificadas com o prefixo engine: ou store: nunca são herdadas, enquanto certificados e chaves especificados com o prefixo data: são sempre herdados. Chaves secretas protegidas por senha não são armazenadas em cache e, portanto, nunca são herdadas.

Objetos SSL carregados de variáveis não podem ser herdados.

Exemplo:

ssl_object_cache_inheritable on;

http {
    server {
        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;
    }
}

thread_pool#

Sintaxe

thread_pool nome threads=número [max_queue=número];

Padrão

thread_pool default threads=32 max_queue=65536;

Contexto

main

Define o nome e parâmetros de um pool de threads usado para leitura e envio multi-threaded de arquivos sem bloquear processos worker.

O parâmetro threads define o número de threads no pool.

Se todas as threads no pool estiverem ocupadas executando tarefas, novas tarefas aguardam em uma fila. O parâmetro max_queue limita o número de tarefas permitidas para aguardar na fila. Por padrão, até 65536 tarefas podem estar na fila. Quando a fila transborda, a tarefa é completada com um erro.

timer_resolution#

Sintaxe

timer_resolution intervalo;

Padrão

—

Contexto

main

Reduz a resolução do timer nos processos worker, reduzindo assim o número de chamadas do sistema gettimeofday(). Por padrão, gettimeofday() é chamado cada vez que um evento do kernel é recebido. Com resolução reduzida, gettimeofday() é chamado apenas uma vez por intervalo especificado.

Exemplo:

timer_resolution 100ms;

A implementação interna do intervalo depende do método usado:

  • o filtro EVFILT_TIMER se kqueue for usado;

  • timer_create() se eventport for usado;

  • setitimer() caso contrário.

use#

Sintaxe

use método;

Padrão

—

Contexto

events

Especifica o método a ser usado para processamento de conexão. Normalmente não há necessidade de especificá-lo explicitamente, porque o Angie usará por padrão o método mais eficiente.

user#

Sintaxe

user usuário [grupo];

Padrão

user <parâmetro de compilação --user> <parâmetro de compilação --group>;

Contexto

main

Define as credenciais de usuário e grupo usadas pelos processos worker (veja também parâmetros de compilação). Se grupo for omitido, um grupo cujo nome é igual ao do usuário é usado.

worker_aio_requests#

Sintaxe

worker_aio_requests número;

Padrão

worker_aio_requests 32;

Contexto

events

Ao usar aio com o método de processamento de conexão epoll, define o número máximo de operações de I/O assíncronas pendentes para um único processo worker.

worker_connections#

Sintaxe

worker_connections número;

Padrão

worker_connections 512;

Contexto

events

Define o número máximo de conexões simultâneas que podem ser abertas por um processo worker.

Deve-se ter em mente que este número inclui todas as conexões (por exemplo, conexões com servidores proxy, entre outras), não apenas conexões com clientes. Outra consideração é que o número real de conexões simultâneas não pode exceder o limite atual no número máximo de arquivos abertos, que pode ser alterado por worker_rlimit_nofile.

worker_cpu_affinity#

Sintaxe

worker_cpu_affinity cpumask ...;

worker_cpu_affinity auto [cpumask];

Padrão

—

Contexto

main

Vincula processos worker aos conjuntos de CPUs. Cada conjunto de CPU é representado por uma máscara de bits das CPUs permitidas. Deve haver um conjunto separado definido para cada um dos processos worker. Por padrão, os processos worker não são vinculados a nenhuma CPU específica.

Por exemplo:

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

Esta configuração vincula cada processo worker a uma CPU separada.

Alternativamente:

worker_processes    2;
worker_cpu_affinity 0101 1010;

Isso vincula o primeiro processo worker à CPU0 e CPU2, e o segundo processo worker à CPU1 e CPU3. Esta configuração é adequada para hyper-threading.

O valor especial auto permite vincular processos worker automaticamente às CPUs disponíveis:

worker_processes auto;
worker_cpu_affinity auto;

O parâmetro opcional mask pode ser usado para limitar as CPUs disponíveis para vinculação automática:

worker_cpu_affinity auto 01010101;

Nota

A diretiva está disponível apenas no FreeBSD e Linux.

worker_priority#

Sintaxe

worker_priority number;

Padrão

worker_priority 0;

Contexto

main

Define a prioridade de agendamento para processos worker como é feito pelo comando nice: um number negativo significa prioridade mais alta. O intervalo permitido normalmente varia de -20 a 20.

Exemplo:

worker_priority -10;

worker_processes#

Sintaxe

worker_processes number | auto;

Padrão

worker_processes 1;

Contexto

main

Define o número de processos worker.

O valor ideal depende de muitos fatores incluindo (mas não limitado a) o número de núcleos de CPU, o número de discos rígidos que armazenam dados, e padrão de carga. Quando há dúvida, defini-lo para o número de núcleos de CPU disponíveis seria um bom começo (o valor "auto" tentará detectá-lo automaticamente).

worker_rlimit_core#

Sintaxe

worker_rlimit_core tamanho;

Padrão

—

Contexto

main

Altera o limite no maior tamanho de um arquivo core (RLIMIT_CORE) para processos worker. Usado para aumentar o limite sem reiniciar o processo principal.

worker_rlimit_nofile#

Sintaxe

worker_rlimit_nofile number;

Padrão

—

Contexto

main

Altera o limite no número máximo de arquivos abertos (RLIMIT_NOFILE) para processos worker. Usado para aumentar o limite sem reiniciar o processo principal.

worker_shutdown_timeout#

Sintaxe

worker_shutdown_timeout tempo;

Padrão

—

Contexto

main

Configura um timeout para um desligamento gracioso de processos worker. Quando o tempo especificado expira, o Angie tentará fechar todas as conexões atualmente abertas para facilitar o desligamento.

O desligamento gracioso é iniciado enviando um sinal QUIT para o processo principal, que instrui os processos worker a parar de aceitar novas conexões e permite que as conexões existentes sejam concluídas. Os processos worker continuam a lidar com requisições ativas até que terminem, e então desligam graciosamente. Se as conexões permanecerem abertas por mais tempo que worker_shutdown_timeout, o Angie fechará forçadamente essas conexões para completar o desligamento. Além disso, conexões keep-alive de cliente são fechadas apenas se estiverem inativas por pelo menos o tempo especificado por lingering_timeout.

working_directory#

Sintaxe

working_directory directory;

Padrão

—

Contexto

main

Define o diretório de trabalho atual para um processo worker. É usado principalmente ao escrever um arquivo core, caso em que um processo worker deve ter permissão de escrita para o diretório especificado.