Re: Документация, директива pid

Чт Ноя 30 17:02:35 UTC 2017

Hello!

On Thu, Nov 30, 2017 at 01:40:57PM +0200, Gena Makhomed wrote:

> On 29.11.2017 20:47, Maxim Dounin wrote:
> 
> >> -<default>nginx.pid</default>
> >> +<default>Зависит от параметров сборки nginx</default>
> >>    <context>main</context>
> 
> > Это необычайно информативно, и наверное всё, что можно тут
> > сделать, это осознать, что некоторые идеи - просто плохие.
> 
> С моей точки зрения,
> информация в документации должна быть прежде всего достоверной.
> 
> "Значение по умолчанию" - это то значение которое примет директива,
> если она будет отсутствовать в конфиге или будет закомментирована.

Значение по умолчанию - это ещё и то значение, которое примет 
директива, если будет отсутствовать соответствующий параметр 
сборки.

В этом месте, кстати, косяк, который совсем просто исправить - 
вместо "nginx.pid" должно быть "logs/nginx.pid".  Патч:

# HG changeset patch
# User Maxim Dounin <mdounin at mdounin.ru>
# Date 1512060425 -10800
#      Thu Nov 30 19:47:05 2017 +0300
# Node ID 8f885a69374ddf67ff9400c7892f020b88f41839
# Parent  05f5bfdaffa3b71299ae378a37c2902c0e6825f1
Fixed the "pid" directive default value.

diff --git a/xml/en/docs/ngx_core_module.xml b/xml/en/docs/ngx_core_module.xml
--- a/xml/en/docs/ngx_core_module.xml
+++ b/xml/en/docs/ngx_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Core functionality"
         link="/en/docs/ngx_core_module.html"
         lang="en"
-        rev="24">
+        rev="25">
 
 <section id="example" name="Example Configuration">
 
@@ -404,7 +404,7 @@ the JIT support is enabled via the
 
 <directive name="pid">
 <syntax><value>file</value></syntax>
-<default>nginx.pid</default>
+<default>logs/nginx.pid</default>
 <context>main</context>
 
 <para>
diff --git a/xml/ru/docs/ngx_core_module.xml b/xml/ru/docs/ngx_core_module.xml
--- a/xml/ru/docs/ngx_core_module.xml
+++ b/xml/ru/docs/ngx_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Основная функциональность"
         link="/ru/docs/ngx_core_module.html"
         lang="ru"
-        rev="24">
+        rev="25">
 
 <section id="example" name="Пример конфигурации">
 
@@ -402,7 +402,7 @@ load_module modules/ngx_mail_module.so;
 
 <directive name="pid">
 <syntax><value>файл</value></syntax>
-<default>nginx.pid</default>
+<default>logs/nginx.pid</default>
 <context>main</context>
 
 <para>

[...]

> >> +Значение по умолчанию задается в момент конфигурирования nginx
> >> параметром <literal>configure --pid-path</literal>.
> >> +Узнать значение по умолчанию для директивы <literal>pid</literal> можно
> >> запустив команду <literal>nginx -V</literal>
> >> +и посмотрев на значение параметра <literal>configure --pid-path</literal>.
> 
> > Это мало соответствует тому, что хотелось бы видеть в описании
> > директивы.
> 
> Предложите лучший вариант как исправить эти ошибки в документации.

Я предложил ещё в первом письме этого треда - сделать note.  И в 
нём написать, что значение по умолчанию может быть переопределено 
с помощью соответствующего параметра configure.  Собственно, я 
тогда же попросил Ярослава, который у нас занимается 
документацией, на это посмотреть, и заодно привести в порядок 
configure.html.

(Отмечу в скобках, что, скажем, в документации Apache для 
ServerRoot приблизительно так и сделано, 
https://httpd.apache.org/docs/2.4/mod/core.html#serverroot.  А вот 
в описании PidFile не указано, что его значение по умолчанию 
переопределяется с помощью "-D DEFAULT_PIDLOG=...".  Хватит это 
терпеть!)

> >> +<para>
> >> +Не рекомендуется явно указывать значение директивы
> >> <literal>pid</literal> в конфигурационном файле.
> >>    </para>
> > 
> > Это не соответствует действительности.  PID-файл можно и нужно
> > задавать во многих ситуациях, например - если на машине
> > запускается несколько независимых экземпляров nginx'а.  Скажем, в
> > портах FreeBSD такое поддерживается из коробки штатными
> > rc-скриптами.
> 
> В портах FreeBSD используется аргумент командной строки
> nginx -g \"pid ${pidfile};\":
> 
> https://github.com/freebsd/freebsd-ports/blob/master/www/nginx/files/nginx.in#L64
> 
> Если директиву pid указать и в командной строке и в конфиге,
> тогда nginx будет ругаться при старте на такой конфиг:
> 
> nginx: [emerg] "pid" directive is duplicate in /etc/nginx/nginx.conf:2
> 
> Можно ли подробнее узнать про "многие ситуации",
> когда необходимо задавать значение директивы pid в конфиге nginx?
> 
> С моей точки зрения, будет больше вреда чем пользы от явного определения
> пользователями значения директивы pid в конфигурационном файле nginx.

Если хочется вдаваться в семантические различия "-g" и собственно 
конфигурационного файла, то pid именно в конфигурационном файле 
обычно проще и удобнее указывать, если хочется запускать несколько 
экземпляров nginx'а без использования скриптов, которые умеют 
делать это через "-g".   Или когда хочется запустить nginx, 
стоящий в системе, под непривелигированным пользователем - для 
тестов, например.

[...]

> Другая часть ошибок
> systemd: PID file /var/run/nginx.pid not readable (yet?) after start.
> происходит из-за того, что nginx зачем-то не совместим с systemd.
> 
> Это Вы знаете, что сообщения эти "безвредные", да и то, только в том
> случае если в PIDFile= и в директиве pid указано одинаковое значение.
> 
> Но пользователи nginx этого ведь не знают! И они продолжают безуспешно
> искать решение как убрать эти сообщения об ошибках из лог-файлов.
> 
> Хотя проблема то легко решается на стороне nginx патчем в одну строчку.
> http://mailman.nginx.org/pipermail/nginx-devel/2017-November/010658.html

По этому вопросу я уже сказал всё, что считаю нужным, и не 
планирую к нему возвращатья.  Спасибо.

-- 
Maxim Dounin
http://mdounin.ru/
