Основной модуль#

Модуль предоставляет основную функциональность и директивы конфигурации, необходимые для базовой работы сервера, а также решает важные задачи, такие как управление рабочими процессами, настройка событийно-ориентированных моделей и обработка входящих соединений и запросов. Он включает ключевые директивы для настройки основного процесса, ведения журналов ошибок и контроля поведения сервера на низком уровне.

Пример конфигурации#

user www www;
worker_processes 2;

error_log /var/log/error.log info;

events {

    use kqueue; worker_connections 2048;
}

Директивы#

accept_mutex#

Синтаксис	`accept_mutex` `on` \| `off`;
По умолчанию	`accept_mutex off;`
Контекст	events

Когда accept_mutex включен, рабочие процессы будут принимать новые соединения поочередно. Иначе уведомления о новых соединениях получают все рабочие процессы, что может привести к неэффективному использованию системных ресурсов, если количество новых соединений невелико.

Примечание

Нет необходимости включать accept_mutex на системах, которые поддерживают флаг EPOLLEXCLUSIVE, или при использовании директивы reuseport.

accept_mutex_delay#

Синтаксис	`accept_mutex_delay` время;
По умолчанию	`accept_mutex_delay 500ms;`
Контекст	events

Если accept_mutex включен, эта директива указывает максимальное время, в течение которого рабочий процесс ждет, чтобы продолжить принимать новые соединения, если другой рабочий процесс уже обрабатывает новые соединения.

daemon#

Синтаксис	`daemon` `on` \| `off`;
По умолчанию	`daemon on;`
Контекст	main

Определяет, будет ли Angie запускаться в режиме демона. Используется в основном для разработки.

debug_connection#

Синтаксис	`debug_connection` адрес \| CIDR \| `unix`:;
По умолчанию	—
Контекст	events

Включает отладочный лог для отдельных клиентских соединений. Для остальных соединений используется уровень лога, заданный директивой error_log. Указывать соединения можно по IPv4- или IPv6-адресу, сети или имени хоста. Используйте параметр unix:, чтобы включить отладочный лог для соединений через UNIX-сокеты.

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:;
    #  ...
}

Примечание

Чтобы эта директива работала, в сборке Angie должен быть включен отладочный лог.

debug_points#

Синтаксис	`debug_points` `abort` \| `stop`;
По умолчанию	—
Контекст	main

Эта директива используется для отладки.

В случае обнаружения внутренней ошибки, например, утечки сокетов в момент перезапуска рабочих процессов, включение debug_points либо создаст файл дампа памяти (abort), либо остановит процесс (stop) для анализа с помощью отладчика.

env#

Синтаксис	`env` переменная [=значение];
По умолчанию	`env TZ;`
Контекст	main

По умолчанию Angie удаляет все переменные окружения, унаследованные от родительского процесса, кроме переменной TZ. Эта директива позволяет сохранить часть унаследованных переменных, поменять их значения или создать новые переменные окружения.

Эти переменные затем:

наследуются во время обновления исполняемого файла на лету;
используются модулем Perl;
доступны рабочими процессами.

Обратите внимание, что управление системными библиотеками таким образом может быть не всегда эффективным, поскольку библиотеки часто проверяют переменные только во время инициализации, которая происходит до срабатывания этой директивы. Переменная TZ всегда наследуется и доступна модулю Perl, если не задано явно иное поведение.

Пример:

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

Примечание

Переменная окружения ANGIE используется внутри Angie и не должна задаваться напрямую пользователем.

error_log#

Изменено в версии 1.12.0.

Синтаксис	`error_log` файл [уровень] [[`filter=`часть:шаблон] ...] [`rate=`скорость] [`format=`формат];
По умолчанию	`error_log logs/error.log error;` (путь зависит от параметра сборки `--error-log-path`)
Контекст	main, http, mail, stream, server, location

Настраивает логирование, позволяя указывать несколько логов на одном уровне конфигурации. Если файл лога не указан явно на уровне конфигурации main, будет использоваться файл по умолчанию.

Первый параметр указывает файл для хранения лога. Специальное значение stderr задает стандартный поток ошибок. Для настройки логирования в syslog используйте префикс "syslog:". Для логирования в циклический буфер памяти используйте префикс "memory:", за которым следует размер буфера; обычно он используется для отладки.

Второй параметр задает уровень логирования одним из следующих значений: debug, info, notice, warn, error, crit, alert или emerg. Уровни перечислены в порядке возрастания серьезности. При задании уровня будут логироваться сообщения равного и более высокого уровня:

Настройка	Уровни записи
`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`

Если этот параметр не задан, по умолчанию используется уровень логирования error.

Необязательные параметры filter=часть:шаблон ограничивают набор сообщений, записываемых в лог, позволяя одному приемнику собирать только интересующие события. Каждый параметр сопоставляет одну часть сообщения с шаблоном, где часть — одно из следующих значений:

logline — при format=default текст сообщения вместе со сведениями о системной ошибке и контексте, но без префикса с временной меткой, уровнем, идентификаторами процесса, потока и соединения; при format=json совпадений не дает;
message — при format=default текст сообщения без сведений о системной ошибке и контексте; при format=json — экранированный сериализованный фрагмент с полем message, а не исходное значение этого поля;
tag — тег, прикрепленный к сообщению, включая теги, добавляемые директивой error_log_user_tag и ее аналогами в модулях stream и mail;
sourcefile — файл исходного кода, в котором возникло сообщение; доступно только в сборке Angie с включенным отладочным логом;
любое другое имя — поле контекста сообщения, например одно из полей, показанных ниже в формате JSON.

По умолчанию шаблон сопоставляется как подстрока. Добавьте перед ним префикс = для точного совпадения или ~ для сопоставления с регулярным выражением, что требует сборки с библиотекой PCRE.

При format=json точный фильтр по message должен охватывать весь сериализованный фрагмент, включая синтаксис и экранирование JSON.

Для одной директивы можно задать несколько параметров filter=; сообщение записывается, только если оно соответствует всем из них.

Необязательный параметр rate=скорость ограничивает максимальную скорость записи сообщений в лог, в сообщениях в секунду; значение может оканчиваться суффиксом m/s (например, rate=2000m/s). По умолчанию используется rate=1000 (1000 сообщений в секунду); чтобы отключить ограничение, укажите rate=0.

Ограничение применяется отдельно к каждому логу, заданному директивой error_log, и независимо в каждом рабочем процессе. Поток сообщений низкой серьезности (например, уровня info) не подавляет сообщения более высокой серьезности, такие как error, поскольку более серьезным уровням разрешен пропорционально больший всплеск; обратное неверно. Избыточные сообщения отбрасываются. Ограничение не отключает логирование, а замедляет его: при постоянной перегрузке сообщения продолжают записываться со скоростью, приблизительно равной заданной.

Если ограничиваемый лог не является первым в действующей цепочке логов, первое отброшенное сообщение также приводит к записи уведомления "too many log messages, limiting" того же уровня. Уведомление может появиться снова при постоянной перегрузке. Для первого лога в цепочке, в том числе единственного, оно не записывается.

Ограничение скорости не применяется, если для сообщения действует уровень логирования debug: когда сам лог задан с уровнем debug или когда для соединения включено отладочное логирование директивой debug_connection.

Примечание

Чтобы работал уровень логирования debug, в сборке Angie должен быть включен отладочный лог.

Необязательный параметр format=формат задает формат записей лога. Значение по умолчанию, format=default, соответствует традиционному текстовому формату, описанному ниже; format=json выводит каждую запись в виде отдельного JSON-объекта на одной строке.

В формате по умолчанию каждая запись в журнале ошибок имеет следующий формат:

временная_метка [уровень] PID#TID: *номер_соединения сообщение

Где:

временная_метка — дата и время события;
уровень — уровень логирования события;
PID#TID — идентификаторы процесса и потока;
*номер_соединения — порядковый номер соединения, общий для всех запросов этого соединения (если применимо);
сообщение — текст сообщения об ошибке или событии.

При format=json каждая запись вместо этого выводится в виде отдельного JSON-объекта; здесь для удобства чтения он развернут построчно, а в самом файле лога занимает одну строку:

{
    "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"
    ]
}

Где:

time — дата и время события, в формате ISO 8601;
level — уровень логирования события;
pid и tid — идентификаторы процесса и потока;
connection — номер соединения (то же значение, что показано как *номер_соединения в текстовом формате); присутствует, если запись связана с соединением;
message — текст сообщения об ошибке или событии;
error — присутствует, если сообщение связано с системной ошибкой; объект с полями code и message;
http, stream или mail — объект со сведениями о контексте записи, ключом которого служит имя модуля, где возникла запись (для контекстных сведений вне этих модулей используется общий объект context); объект присутствует, только если такие сведения есть, а запись логируется на уровне, отличном от debug. У каждого модуля свой набор полей; например, внутри http вложенный объект request содержит request_line — строку запроса, а также другие сведения о запросе;
tags — список тегов, прикрепленных к записи; присутствует, если задан хотя бы один тег; включает теги, добавляемые модулями автоматически, а также директивой error_log_user_tag;
truncated — true, присутствует, только если запись пришлось усечь, чтобы уместить ее в буфер журнала ошибок.

events#

Синтаксис	`events` { ... };
По умолчанию	—
Контекст	main

Предоставляет контекст конфигурационного файла для директив, влияющих на обработку соединений.

include#

Синтаксис	`include` файл \| маска;
По умолчанию	—
Контекст	любой

Включает в конфигурацию другой файл или файлы, подходящие под заданную маску. Включаемые файлы должны содержать синтаксически верные директивы и блоки.

Пример:

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

load_module#

Синтаксис	`load_module` файл;
По умолчанию	—
Контекст	main

Загружает динамический модуль из указанного файла. Относительные пути задаются от параметра сборки --prefix, уточнить который можно так:

$ sudo angie -V

Пример:

load_module modules/ngx_mail_module.so;

Если динамический модуль был собран для другой сборки Angie, загрузка завершится ошибкой вида: "module "..." was built for "..." but you are running "Angie"".

lock_file#

Синтаксис	`lock_file` файл;
По умолчанию	`lock_file logs/angie.lock;` (путь зависит от параметра сборки `--lock-path`)
Контекст	main

Angie использует механизм блокировок для реализации accept_mutex и сериализации доступа к разделяемой памяти. На большинстве систем блокировки управляются с помощью атомарных операций, что делает эту директиву ненужной. Однако на некоторых системах используется альтернативный механизм lock file. Эта директива устанавливает префикс для имен файлов блокировок.

master_process#

Синтаксис	`master_process` `on` \| `off`;
По умолчанию	`master_process on;`
Контекст	main

Определяет, будут ли запускаться рабочие процессы. Эта директива предназначена для разработчиков Angie.

multi_accept#

Синтаксис	`multi_accept` `on` \| `off`;
По умолчанию	`multi_accept off;`
Контекст	events

`on`	Рабочий процесс будет принимать сразу все новые соединения.
`off`	Рабочий процесс будет принимать только одно новое соединение за раз.

Примечание

Директива игнорируется при использовании метода обработки соединений kqueue, так как он сам задает число новых соединений, ожидающих приема.

pcre_jit#

Синтаксис	`pcre_jit` `on` \| `off`;
По умолчанию	`pcre_jit off;`
Контекст	main

Разрешает или запрещает использование JIT-компиляции (PCRE JIT) для регулярных выражений, известных на момент парсинга конфигурации.

Использование PCRE JIT заметно ускоряет обработку регулярных выражений.

Примечание

Для работы JIT необходима библиотека PCRE версии 8.20 или выше, собранная с параметром сборки --enable-jit. Если Angie собирается с библиотекой PCRE (--with-pcre=), поддержка JIT включается с помощью параметра --with-pcre-jit.

pid#

Синтаксис	`pid` файл \| `off`;
По умолчанию	`pid logs/angie.pid;` (путь зависит от параметра сборки `--pid-path`)
Контекст	main

Указывает файл, где будет храниться идентификатор главного процесса Angie. Файл создается атомарно, что обеспечивает корректность его содержимого. Настройка off отключает создание этого файла.

Примечание

Если значение file изменяется при переконфигурации, но указывает на симлинк предыдущего PID-файла, файл не будет создан заново.

ssl_engine#

Синтаксис	`ssl_engine` устройство;
По умолчанию	—
Контекст	main

Задает название аппаратного SSL-акселератора.

ssl_object_cache_inheritable#

Синтаксис	`ssl_object_cache_inheritable` `on` \| `off`;
Значение по умолчанию	`ssl_object_cache_inheritable on;`
Контекст	main

Если включено, SSL-объекты (SSL-сертификаты, секретные ключи, доверенные сертификаты CA, списки отзыва сертификатов) наследуются при перезагрузке конфигурации.

SSL-объекты, загруженные из файлов, наследуются, если время их изменения и индекс файла не изменились с момента предыдущей загрузки конфигурации. Секретные ключи, указанные как engine:name:id, никогда не наследуются, тогда как ключи, указанные как data:value, всегда наследуются.

SSL-объекты, загруженные из переменных, не могут быть унаследованы.

Пример:

ssl_object_cache_inheritable on;

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

thread_pool#

Синтаксис	`thread_pool` имя `threads=`число [`max_queue=`число];
По умолчанию	`thread_pool default threads=32 max_queue=65536;`
Контекст	main

Задает имя и параметры пула потоков, используемого для многопоточной обработки операций чтения и отправки файлов без блокирования рабочих процессов.

Параметр threads задает число потоков в пуле.

Если все потоки в пуле заняты выполнением заданий, новые задания ждут в очереди. Параметр max_queue ограничивает число заданий, ожидающих своего выполнения в очереди. По умолчанию в очереди может находиться до 65536 заданий. Если очередь переполнена, новые задания завершаются с ошибкой.

timer_resolution#

Синтаксис	`timer_resolution` интервал;
По умолчанию	—
Контекст	main

Уменьшает разрешение таймеров времени в рабочих процессах, за счет чего уменьшается число системных вызовов gettimeofday(). По умолчанию gettimeofday() вызывается при каждом получении событий из ядра. При уменьшении разрешения функция вызывается только раз за указанный интервал.

Пример:

timer_resolution 100ms;

Внутренняя реализация интервала зависит от используемого метода:

Фильтр EVFILT_TIMER, если используется kqueue.
Функция timer_create(), если используется eventport.
Функция setitimer(), в противном случае.

use#

Синтаксис	`use` метод;
По умолчанию	—
Контекст	events

Задает метод, используемый для обработки соединений. Обычно нет необходимости задавать его явно, поскольку по умолчанию Angie выбирает наиболее эффективный метод.

user#

Синтаксис	`user` пользователь [группа];
По умолчанию	`user <параметр сборки --user> <параметр сборки --group>;`
Контекст	main

Задает пользователя и группу для рабочих процессов (см. также параметры сборки). Если задан только пользователь, для группы также задается указанное имя пользователя.

worker_aio_requests#

Синтаксис	`worker_aio_requests` число;
По умолчанию	`worker_aio_requests 32;`
Контекст	events

При использовании aio с методом обработки соединений epoll задает максимум операций асинхронного ввода-вывода, ожидающих обработки, для одного рабочего процесса.

worker_connections#

Синтаксис	`worker_connections` число;
По умолчанию	`worker_connections 512;`
Контекст	events

Задает максимум соединений, которые одновременно может открыть рабочий процесс.

Обратите внимание, что это число включает все соединения, такие как соединения с проксируемыми серверами, а не только клиентские. Кроме того, фактическое количество одновременных соединений не может превышать системный лимит на открытые файлы, который можно настроить с помощью worker_rlimit_nofile.

worker_cpu_affinity#

Синтаксис

worker_cpu_affinity маска_CPU ...;

worker_cpu_affinity auto [маска_CPU];

По умолчанию

—

Контекст

main

Привязывает рабочие процессы к группам процессоров. Каждая группа процессоров задается битовой маской разрешенных процессоров. Для каждого рабочего процесса должна быть задана отдельная группа. По умолчанию рабочие процессы не привязаны к конкретным процессорам.

Пример:

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

Эта конфигурация привязывает каждый рабочий процесс к отдельному процессору.

В качестве альтернативы:

worker_processes    2;
worker_cpu_affinity 0101 1010;

Это привязывает первый рабочий процесс к CPU0 и CPU2, а второй рабочий процесс к CPU1 и CPU3. Такая настройка подходит для гипертрединга.

Специальное значение auto позволяет автоматически привязывать рабочие процессы к доступным процессорам:

worker_processes auto;
worker_cpu_affinity auto;

С помощью необязательной маски можно ограничить процессоры, доступные для автоматической привязки:

worker_cpu_affinity auto 01010101;

Примечание

Директива доступна только на FreeBSD и Linux.

worker_priority#

Синтаксис	`worker_priority` число;
По умолчанию	`worker_priority 0;`
Контекст	main

Задает приоритет планирования рабочих процессов подобно тому, как это делается командой nice: отрицательное число означает более высокий приоритет. Диапазон возможных значений — от -20 до 20.

Пример:

worker_priority -10;

worker_processes#

Синтаксис	`worker_processes` число \| `auto`;
По умолчанию	`worker_processes 1;`
Контекст	main

Задает число рабочих процессов.

Оптимальное значение зависит от разных факторов, включая число ядер процессора, количество жестких дисков и характер нагрузки. Если вы не уверены, рекомендуется начать с числа доступных ядер процессора. Значение auto пытается автоматически определить оптимальное количество.

worker_rlimit_core#

Синтаксис	`worker_rlimit_core` размер;
По умолчанию	—
Контекст	main

Меняет ограничение на наибольший размер дампа памяти (RLIMIT_CORE) для рабочих процессов. Используется для увеличения ограничения без перезапуска главного процесса.

worker_rlimit_nofile#

Синтаксис	`worker_rlimit_nofile` число;
По умолчанию	—
Контекст	main

Меняет ограничение на максимальное число открытых файлов (RLIMIT_NOFILE) для рабочих процессов. Используется для увеличения ограничения без перезапуска главного процесса.

worker_shutdown_timeout#

Синтаксис	`worker_shutdown_timeout` время;
По умолчанию	—
Контекст	main

Задает таймаут в секундах для постепенного завершения рабочих процессов. По истечении указанного времени Angie попытается закрыть все открытые сейчас соединения, чтобы ускорить завершение работы.

Постепенное завершение работы инициируется отправкой сигнала QUIT главному процессу, который приказывает рабочим процессам прекратить принимать новые подключения, позволяя завершить уже существующие. Рабочие процессы продолжают обрабатывать активные запросы до их завершения, после чего корректно завершают свою работу. Если соединения остаются открытыми дольше worker_shutdown_timeout, Angie принудительно закроет эти соединения для завершения работы. Также клиентские постоянные соединения закрываются только в случае, если они неактивны не менее времени, заданного в lingering_timeout.

working_directory#

Синтаксис	`working_directory` каталог;
По умолчанию	—
Контекст	main

Задает каталог, который будет текущим для рабочего процесса. Основное применение — запись дампа памяти, поэтому рабочий процесс должен иметь права на запись в этот каталог.