Основные функции

• Пример конфигурации
• Директивы
• accept_mutex
• accept_mutex_delay
• daemon
• debug_connection
• debug_points
• env
• error_log
• events
• include
• load_module
• lock_file
• master_process
• multi_accept
• pcre_jit
• pid
• ssl_engine
• ssl_object_cache_inheritable
• stall_threshold
• thread_pool
• timer_resolution
• use
• user
• worker_aio_requests
• worker_connections
• worker_cpu_affinity
• worker_priority
• worker_processes
• worker_rlimit_core
• worker_rlimit_nofile
• worker_shutdown_timeout
• working_directory

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

user www www;
worker_processes 2;

error_log /var/log/nginx-error.log info;

events {
    use kqueue;
    worker_connections 2048;
}

...

Директивы

Если включён accept_mutex, рабочие процессы будут по очереди принимать новые соединения. В противном случае все рабочие процессы получат уведомление о новых соединениях, и при небольшом их количестве некоторые рабочие процессы могут лишь расходовать системные ресурсы.

Включать accept_mutex не требуется в системах, поддерживающих флаг EPOLLEXCLUSIVE (1.11.3), или при использовании reuseport.

До версии 1.11.3 значением по умолчанию было on.

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

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

Включает отладочный журнал для выбранных клиентских соединений. Для остальных соединений используется уровень ведения журнала, заданный директивой error_log. Отлаживаемые соединения задаются IPv4- или IPv6-адресом (1.3.0, 1.2.1) либо сетью. Соединение также можно указать с помощью имени узла. Для соединений через сокеты домена UNIX (1.3.0, 1.2.1) отладочный журнал включается параметром «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:;
    ...
}

Чтобы эта директива работала, nginx необходимо собрать с --with-debug, см. «Отладочный журнал».

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

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

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

• наследуются при обновлении исполняемого файла без остановки;
• используются модулем ngx_http_perl_module;
• используются рабочими процессами. Следует учитывать, что управлять таким образом системными библиотеками удаётся не всегда, поскольку библиотеки обычно проверяют переменные только при инициализации — задолго до того, как их можно задать с помощью этой директивы. Исключение составляет упомянутое выше обновление исполняемого файла без остановки.

Переменная TZ всегда наследуется и доступна модулю ngx_http_perl_module, если только она не настроена явно.

Пример использования:

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

Переменная окружения NGINX используется nginx внутри программы, и пользователь не должен задавать её напрямую.

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

Первый параметр задаёт file, в который будет записываться журнал. Специальное значение stderr указывает на стандартный файл ошибок. Ведение журнала в syslog настраивается с помощью префикса «syslog:». Запись в циклический буфер памяти настраивается с помощью префикса «memory:» и буфера size и обычно используется для отладки (1.7.11).

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

Чтобы работало ведение debug журнала, nginx необходимо собрать с --with-debug, см. «Отладочный журнал».

Параметр json (1.29.8) включает запись журнала в формате JSON с поддержкой контекстных тегов:

{
  "level": "error",
  "timestamp": "2026-05-13T10:30:15.042+00:00",
  "pid": 12345,  "tid": 12345,  "cnum": 3,
  "msg": "connect() failed",
  "client": "192.168.1.10",  "server": "example.com",
  "request": "GET /api HTTP/1.1",
  "upstream": "http://127.0.0.1:8080/api",
  "errno": 111,
  "errtext": "Connection refused"
}

Размер записи журнала не может превышать 2 КБ; данные сверх этого ограничения обрезаются до “truncated”:1. Отладочное ведение журнала для JSON не поддерживается.

Этот параметр доступен в рамках нашей коммерческой подписки.

Начиная с версии 1.7.11 директиву можно указывать на уровне stream, а начиная с версии 1.9.0 — на уровне mail.

Задаёт контекст конфигурационного файла, в котором указываются директивы, влияющие на обработку соединений.

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

Пример использования:

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

Загружает динамический модуль.

Пример:

load_module modules/ngx_mail_module.so;

nginx использует механизм блокировок для реализации accept_mutex и сериализации доступа к разделяемой памяти. В большинстве систем блокировки реализуются с помощью атомарных операций, и эта директива игнорируется. В остальных системах используется механизм «lock file». Эта директива задаёт префикс имён файлов блокировок.

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

Если multi_accept отключён, рабочий процесс будет принимать по одному новому соединению за раз. В противном случае рабочий процесс будет принимать все новые соединения одновременно.

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

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

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

JIT доступен в библиотеках PCRE начиная с версии 8.20, собранной с параметром конфигурации --enable-jit. Если библиотека PCRE собирается вместе с nginx (--with-pcre=), поддержка JIT включается параметром конфигурации --with-pcre-jit.

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

Задаёт имя аппаратного ускорителя SSL.

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

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

Объекты 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;
    }
}

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

Эта директива доступна в рамках нашей коммерческой подписки.

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

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

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

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

Пример:

timer_resolution 100ms;

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

• фильтр EVFILT_TIMER, если используется kqueue;
• timer_create(), если используется eventport;
• setitimer() в остальных случаях.

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

Задаёт учётные данные user и group, используемые рабочими процессами. Если group не указан, используется группа с тем же именем, что и у user.

При использовании aio с методом обработки соединений epoll задаёт максимальное number незавершённых операций асинхронного ввода-вывода для одного рабочего процесса.

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

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

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

Например,

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

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

worker_processes    2;
worker_cpu_affinity 0101 1010;

привязывает первый рабочий процесс к CPU0/CPU2, а второй — к CPU1/CPU3. Второй пример подходит для систем с гиперпоточностью.

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

worker_processes auto;
worker_cpu_affinity auto;

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

worker_cpu_affinity auto 01010101;

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

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

Пример:

worker_priority -10;

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

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

Параметр auto поддерживается начиная с версий 1.3.8 и 1.2.5.

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

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

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

Задаёт текущий рабочий каталог для рабочего процесса. В основном он используется при записи файла core; в этом случае рабочему процессу необходимо иметь разрешение на запись в указанный каталог.