<?xml version="1.0"?>

<!DOCTYPE module SYSTEM "../../../dtd/module.dtd">

<module name="Основная функциональность"
        link="/ru/docs/ngx_core_module.html"
        lang="ru">

<section id="example" name="Пример конфигурации">

<para>
<example>
user www www;
worker_processes 2;

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

events {
    use kqueue;
    worker_connections 2048;
}

...
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="daemon">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>main</context>

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

</directive>


<directive name="error_log">
<syntax>
<value>файл</value>
[<literal>debug</literal> |
<literal>info</literal> |
<literal>notice</literal> |
<literal>warn</literal> |
<literal>error</literal> |
<literal>crit</literal> |
<literal>alert</literal> |
<literal>emerg</literal>]</syntax>
<default>logs/error.log error</default>
<context>main</context>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Конфигурирует запись в лог.
</para>

<para>
Первый параметр задаёт файл, который будет хранить лог.
<!--
Если имя файла не абсолютное, к нему добавляется в начало путь префикса.
-->
</para>

<para>
Второй параметр определяет уровень лога.
Уровни лога, указанные выше, перечислены в порядке возрастания их серьёзности.
При установке определённого уровня в лог попадают все сообщения
указанного и более серьёзных уровней.
Например, при стандартном уровне <literal>error</literal> в лог попадают
сообщения уровней <literal>error</literal>, <literal>crit</literal>,
<literal>alert</literal> и <literal>emerg</literal>.

<note>
Для работы уровня лога <literal>debug</literal> необходимо сконфигурировать
nginx с <literal>--with-debug</literal>.
</note>
</para>

</directive>


<directive name="env">
<syntax><value>переменная</value>[=<value>значение</value>]</syntax>
<default>TZ</default>
<context>main</context>

<para>
Позволяет ограничить набор переменных окружения, поменять им значения
или же создать новые переменные окружения для следующих случаев:
<list type="bullet">

<listitem>
наследование переменных во время
<link doc="control.xml" id="upgrade">обновления исполняемого файла на лету</link>;
</listitem>

<listitem>
использование переменных модулем
<link doc="http/ngx_http_perl_module.xml">ngx_http_perl_module</link>;
</listitem>

<listitem>
использование переменных рабочими процессами.
Однако нужно иметь в виду, что управление поведением системных библиотек
подобным образом возможно не всегда, поскольку зачастую библиотеки используют
переменные только во время инициализации, то есть ещё до того, как их
можно задать с помощью данной директивы.
Исключением из этого является вышеописанное
<link doc="control.xml" id="upgrade">обновление исполняемого файла на лету</link>.
</listitem>

</list>
</para>

<para>
Если переменная TZ не описана явно, то она всегда наследуется
и всегда доступна модулю
<link doc="http/ngx_http_perl_module.xml">ngx_http_perl_module</link>.
</para>

<para>
Пример использования:
<example>
env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;
</example>
</para>

</directive>


<directive name="include">
<syntax><value>файл</value> | <value>маска</value></syntax>
<default/>
<context/>

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

<para>
Пример использования:
<example>
include mime.types;
include vhosts/*.conf;
</example>
</para>

</directive>


<directive name="master_process">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>main</context>

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

</directive>


<directive name="pcre_jit">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>main</context>
<appeared-in>1.1.12</appeared-in>

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

<para>
Использование PCRE JIT способно существенно ускорить обработку
регулярных выражений.
<note>
Для работы JIT необходима библиотека PCRE версии 8.20 или выше,
собранная с параметром конфигурации <literal>--enable-jit</literal>.
При сборке библиотеки PCRE вместе с nginx (<literal>--with-pcre=</literal>),
для включения поддержки JIT необходимо использовать параметр
конфигурации <literal>--with-pcre-jit</literal>.
</note>
</para>

</directive>


<directive name="pid">
<syntax><value>файл</value></syntax>
<default>nginx.pid</default>
<context>main</context>

<para>
Задаёт <value>файл</value>, в котором будет храниться номер (PID) основного процесса.
</para>

</directive>


<directive name="ssl_engine">
<syntax><value>устройство</value></syntax>
<default/>
<context>main</context>

<para>
Задаёт название аппаратного SSL-акселератора.
</para>

</directive>


<directive name="timer_resolution">
<syntax><value>интервал</value></syntax>
<default/>
<context>main</context>

<para>
Уменьшает разрешение таймеров времени в рабочих процессах, за счёт
чего уменьшается число системных вызовов <c-func>gettimeofday</c-func>.
По умолчанию <c-func>gettimeofday</c-func> вызывается после каждой
операции получения событий из ядра.
C уменьшенным разрешением <c-func>gettimeofday</c-func> вызывается только
один раз за указанный <value>интервал</value>.
</para>

<para>
Пример использования:
<example>
timer_resolution 100ms;
</example>
</para>

<para>
Внутренняя реализация интервала зависит от используемого метода:
<list type="bullet">

<listitem>
фильтр <c-def>EVFILT_TIMER</c-def> при использовании <literal>kqueue</literal>;
</listitem>

<listitem>
<c-func>timer_create</c-func> при использовании <literal>eventport</literal>;
</listitem>

<listitem>
и <c-func>setitimer</c-func> во всех остальных случаях.
</listitem>

</list>
</para>

</directive>


<directive name="user">
<syntax><value>пользователь</value> [<value>группа</value>]</syntax>
<default>nobody nobody</default>
<context>main</context>

<para>
Задаёт пользователя и группу, с правами которого будут работать
рабочие процессы.
Если <value>группа</value> не задана, то используется группа, имя
которой совпадает с именем пользователя.
</para>

</directive>


<directive name="worker_priority">
<syntax><value>число</value></syntax>
<default>0</default>
<context>main</context>

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

<para>
Пример использования:
<example>
worker_priority -10;
</example>
</para>

</directive>


<directive name="worker_processes">
<syntax><value>число</value></syntax>
<default>1</default>
<context>main</context>

<para>
Задаёт число рабочих процессов.
</para>

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

</directive>


<directive name="worker_rlimit_core">
<syntax><value>размер</value></syntax>
<default/>
<context>main</context>

<para>
Изменяет ограничение на наибольший размер core-файла
(<c-def>RLIMIT_CORE</c-def>) для рабочих процессов.
Используется для увеличения ограничения без перезапуска основного процесса.
</para>

</directive>


<directive name="worker_rlimit_nofile">
<syntax><value>число</value></syntax>
<default/>
<context>main</context>

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

</directive>


<directive name="working_directory">
<syntax><value>каталог</value></syntax>
<default/>
<context>main</context>

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

</directive>

</section>

</module>