<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

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

<article name="Управление nginx"
         link="/ru/docs/control.html"
         lang="ru"
         rev="7">

<section>

<para>
Управлять nginx можно с помощью сигналов. Номер главного процесса по умолчанию
записывается в файл <path>/usr/local/nginx/logs/nginx.pid</path>.
Изменить имя этого файла можно при конфигурации сборки или же в
<path>nginx.conf</path> директивой
<link doc="ngx_core_module.xml" id="pid"/>.
Главный процесс поддерживает следующие сигналы:
<note>
<table>

<tr><td width="20%">TERM, INT</td><td>быстрое завершение</td></tr>
<tr><td width="20%">QUIT</td><td>плавное завершение</td></tr>
<tr><td width="20%">HUP</td><td>изменение конфигурации,
обновление изменившейся временной зоны (только для FreeBSD и Linux),
запуск новых рабочих процессов с новой конфигурацией,
плавное завершение старых рабочих процессов</td></tr>
<tr><td width="20%">USR1</td><td>переоткрытие лог-файлов</td></tr>
<tr><td width="20%">USR2</td><td>обновление исполняемого файла</td></tr>
<tr><td width="20%">WINCH</td><td>плавное завершение рабочих процессов</td></tr>

</table>
</note>
</para>

<para>
Управлять рабочими процессами по отдельности не нужно.
Тем не менее, они тоже поддерживают некоторые сигналы:
<note>
<table>

<tr><td width="20%">TERM, INT</td><td>быстрое завершение</td></tr>
<tr><td width="20%">QUIT</td><td>плавное завершение</td></tr>
<tr><td width="20%">USR1</td><td>переоткрытие лог-файлов</td></tr>
<tr><td width="20%">WINCH</td><td>аварийное завершение для отладки
(требует включения <link doc="ngx_core_module.xml" id="debug_points"/>)
</td></tr>

</table>
</note>
</para>

</section>


<section id="reconfiguration" name="Изменение конфигурации">

<para>
Для того чтобы nginx перечитал файл конфигурации, нужно послать
главному процессу сигнал HUP. Главный процесс сначала проверяет
синтаксическую правильность конфигурации, а затем пытается применить
новую конфигурацию, то есть, открыть лог-файлы и новые listen сокеты.
Если ему это не удаётся, то он откатывает изменения и продолжает работать
со старой конфигурацией.
Если же удаётся, то он запускает новые рабочие процессы, а старым
шлёт сообщение о плавном выходе. Старые рабочие процессы закрывают listen
сокеты и продолжают обслуживать старых клиентов. После обслуживания всех
клиентов старые рабочие процессы завершаются.
</para>

<para>
Предположим, на FreeBSD команда
<programlisting>
ps axw -o pid,ppid,user,%cpu,vsz,wchan,command | egrep '(nginx|PID)'
</programlisting>
показывает примерно такую картину:
<programlisting>
  PID  PPID USER    %CPU   VSZ WCHAN  COMMAND
33126     1 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx
33127 33126 nobody   0.0  1380 kqread nginx: worker process (nginx)
33128 33126 nobody   0.0  1364 kqread nginx: worker process (nginx)
33129 33126 nobody   0.0  1364 kqread nginx: worker process (nginx)
</programlisting>
</para>

<para>
Если послать сигнал HUP главному процессу, то картина может быть такой:
<programlisting>
  PID  PPID USER    %CPU   VSZ WCHAN  COMMAND
33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx
33129 33126 nobody   0.0  1380 kqread nginx: worker process is shutting down (nginx)
33134 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33135 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33136 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
</programlisting>
</para>

<para>
Один старый рабочий процесс 33129 всё ещё продолжает работать. По истечении
некоторого времени он завершается:
<programlisting>
  PID  PPID USER    %CPU   VSZ WCHAN  COMMAND
33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx
33134 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33135 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33136 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
</programlisting>
</para>

</section>


<section id="logs" name="Ротация лог-файлов">

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

</section>


<section id="upgrade" name="Обновление исполняемого файла на лету">

<para>
Для обновления исполняемого файла сервера вначале нужно записать
на место старого файла новый.
Затем нужно послать сигнал USR2 главному процессу&mdash;он
переименует свой файл с номером процесса в файл
с суффиксом <path>.oldbin</path>, например,
<path>/usr/local/nginx/logs/nginx.pid.oldbin</path>,
после чего запустит новый исполняемый файл, а тот в свою
очередь&mdash;свои рабочие процессы:
<programlisting>
  PID  PPID USER    %CPU   VSZ WCHAN  COMMAND
33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx
33134 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
33135 33126 nobody   0.0  1380 kqread nginx: worker process (nginx)
33136 33126 nobody   0.0  1368 kqread nginx: worker process (nginx)
36264 33126 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
</programlisting>
</para>

<!--

<para>
Процесс с новым исполняемым файлом 36264 создаёт свой файл с номером процесса
с суффиксом <path>.newbin</path>, например,
<path>/usr/local/nginx/logs/nginx.pid.newbin</path>.
</para>

-->

<para>
Теперь все рабочие процессы наравне принимают запросы.
Если послать сигнал WINCH первому главному процессу, то он пошлёт своим
рабочим процессам сообщение о плавном выходе, и они будут постепенно выходить:
<programlisting>
  PID  PPID USER    %CPU   VSZ WCHAN  COMMAND
33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx
33135 33126 nobody   0.0  1380 kqread nginx: worker process is shutting down (nginx)
36264 33126 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
</programlisting>
</para>

<para>
По истечении времени запросы будут обрабатывать только новые рабочие процессы:
<programlisting>
  PID  PPID USER    %CPU   VSZ WCHAN  COMMAND
33126     1 root     0.0  1164 pause  nginx: master process /usr/local/nginx/sbin/nginx
36264 33126 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
</programlisting>
</para>

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

<listitem>
<para>
Послать старому главному процессу сигнал HUP.
Старый главный процесс, не перечитывая конфигурации,
запустит новые рабочие процессы.
После этого можно плавно завершить все новые процессы,
послав новому главному процессу сигнал QUIT.
</para>
</listitem>

<listitem>
<para>
Послать новому главному процессу сигнал TERM.
В ответ на это он пошлёт сообщение о немедленном выходе своим
рабочим процессам, и все они практически сразу же завершатся.
(Если новые процессы по каким-то причинам не завершаются,
нужно послать им сигнал KILL, который заставит их завершиться.)
По завершению нового главного процесса старый главный процесс
автоматически запустит новые рабочие процессы.
</para>
</listitem>

</list>

</para>

<para>
Если новый главный процесс выходит, то старый главный процесс убирает
суффикс <path>.oldbin</path> из имени файла с номером процесса.
</para>

<para>
Если же обновление прошло удачно, то старому процессу нужно послать сигнал
QUIT, и останутся только новые процессы:
<programlisting>
  PID  PPID USER    %CPU   VSZ WCHAN  COMMAND
36264     1 root     0.0  1148 pause  nginx: master process /usr/local/nginx/sbin/nginx
36265 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36266 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
36267 36264 nobody   0.0  1364 kqread nginx: worker process (nginx)
</programlisting>
</para>

<!--

<para>
После этого остаётся только переименовать
<path>/usr/local/nginx/logs/nginx.pid.newbin</path> в
<path>/usr/local/nginx/logs/nginx.pid</path> и обновление можно считать
завершённым.
</para>

-->

</section>

</article>