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 time;

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];

Padrão

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

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.

Nota

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

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 file;

Padrão

—

Contexto

main

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

$ sudo angie -V

Exemplo:

load_module modules/ngx_mail_module.so;

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 dispositivo;

Padrão

—

Contexto

main

Especifica o nome do acelerador SSL de hardware.

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 como engine:name:id nunca são herdadas, enquanto chaves secretas especificadas como data:value são sempre 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 size;

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 time;

Padrão

—

Contexto

main

Configura um timeout em segundos 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, 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.