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

[Gena Makhomed]

On 29.11.2017 20:47, Maxim Dounin wrote:

>> -<default>nginx.pid</default>
>> +<default>Зависит от параметров сборки nginx</default>
>>    <context>main</context>

> Это необычайно информативно, и наверное всё, что можно тут
> сделать, это осознать, что некоторые идеи - просто плохие.

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

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

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

Идеальным вариантом, с моей точки зрения, было бы сделать так:

<default><link doc="default_values.xml">Defined at compile 
time</link>.</default>

В виде html это выглядело бы так:

   Default: Defined at compile time.

где текст "Defined at compile time" будет гиперссылкой.

И в документе default_values.html для всех 11 директив описать способ
как можно узнать их значение по умолчанию с помощью команды nginx -V

Но xmllint ругается, что
Element default was declared #PCDATA but contains non text nodes

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

> Это мало соответствует тому, что хотелось бы видеть в описании
> директивы.

Предложите лучший вариант как исправить эти ошибки в документации.

>> +<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.

Часть ошибок
systemd: PID file /var/run/nginx.pid not readable (yet?) after start.
происходит именно из-за того что в unit-файле одно значение PIDFile=
а в конфигурационном файле указано другое значение для директивы pid.

Другая часть ошибок
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

-- 
Best regards,
  Gena