<?xml version="1.0"?>

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

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

<module name="Модуль ngx_http_userid_module"
        link="/ru/docs/http/ngx_http_userid_module.html"
        lang="ru"
        rev="5">

<section id="summary">

<para>
Модуль <literal>ngx_http_userid_module</literal> выдаёт куки
для идентификации клиентов.
Для записи в лог полученных и выданных кук можно использовать встроенные
переменные <link id="var_uid_got">$uid_got</link> и
<link id="var_uid_set">$uid_set</link>.
Модуль совместим с модулем
<link url="http://www.lexa.ru/programs/mod-uid.html">mod_uid</link>
для Apache.
</para>

</section>


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

<para>
<example>
userid         on;
userid_name    uid;
userid_domain  example.com;
userid_path    /;
userid_expires 365d;
userid_p3p     'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"';
</example>
</para>

</section>


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

<directive name="userid">
<syntax>
    <literal>on</literal> |
    <literal>v1</literal> |
    <literal>log</literal> |
    <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает выдачу кук и запись приходящих кук в лог:
<list type="tag">

<tag-name><literal>on</literal></tag-name>
<tag-desc>
разрешает выдачу кук версии 2
и запись приходящих кук в лог;
</tag-desc>

<tag-name><literal>v1</literal></tag-name>
<tag-desc>
разрешает выдачу кук версии 1
и запись приходящих кук в лог;
</tag-desc>

<tag-name><literal>log</literal></tag-name>
<tag-desc>
запрещает выдачу кук,
но разрешает запись приходящих кук в лог;
</tag-desc>

<tag-name><literal>off</literal></tag-name>
<tag-desc>
запрещает выдачу кук и запись приходящих кук в лог.
</tag-desc>

</list>
</para>

</directive>


<directive name="userid_domain">
<syntax><value>имя</value> | <literal>none</literal></syntax>
<default>none</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт домен, для которого устанавливается кука.
Параметр <literal>none</literal> запрещает выдавать домен для куки.
</para>

</directive>


<directive name="userid_expires">
<syntax><value>время</value> | <literal>max</literal> |
    <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт время, в течение которого браузер должен хранить куку.
Параметр <literal>max</literal> устанавливает срок хранения куки до
31 декабря 2037 года 23:55:55 GMT.
Указание параметра <literal>off</literal> позволяет ограничить время
действия куки сессией браузера.
</para>

</directive>


<directive name="userid_flags">
<syntax>
    <literal>off</literal> |
    <value>флаг</value> ...</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.19.3</appeared-in>

<para>
Если параметр не <literal>off</literal>,
задаёт один или несколько дополнительных флагов для куки:
<literal>secure</literal>,
<literal>httponly</literal>,
<literal>samesite=strict</literal>,
<literal>samesite=lax</literal>,
<literal>samesite=none</literal>.
</para>

</directive>


<directive name="userid_mark">
<syntax>
    <value>буква</value> | <value>цифра</value> |
    <literal>=</literal> |
    <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Если параметр не <literal>off</literal>, включает механизм маркировки кук
и задаёт символ, используемый в качестве метки.
Этот механизм позволяет добавить или изменить
<link id="userid_p3p"/> и/или время хранения куки, но при этом оставить
неизменным идентификатор клиента.
Меткой может быть любая буква английского алфавита (с учётом регистра),
цифра или знак “<literal>=</literal>”.
</para>

<para>
Если метка задана, то она сравнивается с первым дополняющим символом
в base64 представлении идентификатора клиента, передаваемом в куке.
Если они не совпадают, то кука перепосылается с заданной меткой,
временем хранения и заголовком <header>P3P</header>.
</para>

</directive>


<directive name="userid_name">
<syntax><value>имя</value></syntax>
<default>uid</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт имя куки.
</para>

</directive>


<directive name="userid_p3p">
<syntax><value>строка</value> | <literal>none</literal></syntax>
<default>none</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


<directive name="userid_path">
<syntax><value>путь</value></syntax>
<default>/</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт путь, для которого устанавливается кука.
</para>

</directive>


<directive name="userid_service">
<syntax><value>номер</value></syntax>
<default>IP-адрес сервера</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>

</section>


<section id="variables" name="Встроенные переменные">

<para>
Модуль <literal>ngx_http_userid_module</literal>
поддерживает следующие встроенные переменные:
<list type="tag">

<tag-name id="var_uid_got"><var>$uid_got</var></tag-name>
<tag-desc>
Имя куки и полученный идентификатор клиента.
</tag-desc>

<tag-name id="var_uid_reset"><var>$uid_reset</var></tag-name>
<tag-desc>
Если значением является непустая строка не равная “<literal>0</literal>”,
то клиентские идентификаторы перевыдаются.
Специальное значение “<literal>log</literal>” дополнительно приводит к выдаче
сообщений о перевыданных идентификаторах в
<link doc="../ngx_core_module.xml" id="error_log"/>.
</tag-desc>

<tag-name id="var_uid_set"><var>$uid_set</var></tag-name>
<tag-desc>
Имя куки и выданный идентификатор клиента.
</tag-desc>

</list>
</para>

</section>

</module>