Основной функционал

• Пример конфигурации
• Директивы
• 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
• 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, см. “Отладочный лог”.

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

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

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

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

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

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

Пример:

load_module modules/ngx_mail_module.so;

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

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

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

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

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

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

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

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

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

Определяет 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;

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

worker_cpu_affinity auto 01010101;

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

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

Пример:

worker_priority -10;

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

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

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

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

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

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

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