Mercurial > hg > nginx-site
changeset 868:17d0c825f098
Revised the userid module documentation.
- added the "embedded variables" section;
- documented the "$uid_reset" variable;
- documented default parameters of "userid_expires", "userid_mark" and
"userid_p3p" directives;
- improved descriptions of "userid_mark" and "userid_service" directives.
author | Homutov Vladimir <vl@nginx.com> |
---|---|
date | Mon, 18 Mar 2013 13:59:13 +0400 |
parents | 20a50f7bcbd6 |
children | ade81792bdaa |
files | xml/en/docs/http/ngx_http_userid_module.xml xml/ru/docs/http/ngx_http_userid_module.xml |
diffstat | 2 files changed, 140 insertions(+), 32 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_userid_module.xml +++ b/xml/en/docs/http/ngx_http_userid_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_userid_module" link="/en/docs/http/ngx_http_userid_module.html" lang="en" - rev="2"> + rev="3"> <section id="summary"> @@ -18,7 +18,8 @@ The <literal>ngx_http_userid_module</literal> module sets cookies suitable for client identification. Received and set cookies can be logged using the embedded variables -<var>$uid_got</var> and <var>$uid_set</var>. +<link id="var_uid_got">$uid_got</link> and +<link id="var_uid_set">$uid_set</link>. This module is compatible with the <link url="http://www.lexa.ru/programs/mod-uid-eng.html">mod_uid</link> module for Apache. @@ -105,35 +106,50 @@ The parameter <literal>none</literal> di <directive name="userid_expires"> -<syntax><value>time</value> | <literal>max</literal></syntax> -<default/> +<syntax><value>time</value> | <literal>max</literal> | + <literal>off</literal></syntax> +<default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> Sets a time during which a browser should keep the cookie. -The parameter <literal>max</literal> sets the time to +The parameter <literal>max</literal> will cause the cookie to expire on “<literal>31 Dec 2037 23:55:55 GMT</literal>”. This is the maximum time understood by old browsers. +The parameter <literal>off</literal> will cause the cookie to expire at +the end of a browser session. </para> </directive> <directive name="userid_mark"> -<syntax><value>off | letter | digit | =</value></syntax> +<syntax> + <value>letter</value> | <value>digit</value> | + <literal>=</literal> | + <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> -Sets the first symbol of the cookie’s representation base64 tail -(“<literal>==</literal>” by default) and resets all accepted cookies -with another tail. -It may be useful if it's required to add or change the P3P or the cookie expire -time and leave the internally encoded value unchanged. +If parameter is not <literal>off</literal>, enables the cookie marking +mechanism and sets a character used as a mark. +This mechanism allows to add or change +<link id="userid_p3p"/> and/or cookie expiration time while +preserving the client identifier. +The mark can be any letter of the English alphabet (case-sensitive), +digit, or the “<literal>=</literal>” character. +</para> + +<para> +If a mark is set, it is compared with the first padding symbol +in the base64 representation of client identifier passed in a cookie. +If they do not match, a cookie is resent with the specified mark, +expiration time and a <header>P3P</header> header. </para> </directive> @@ -154,8 +170,8 @@ Sets a cookie name. <directive name="userid_p3p"> -<syntax><value>string</value></syntax> -<default/> +<syntax><value>string</value> | <literal>none</literal></syntax> +<default>none</default> <context>http</context> <context>server</context> <context>location</context> @@ -163,6 +179,8 @@ Sets a cookie name. <para> Sets a value for the <header>P3P</header> header field that will be sent along with a cookie. +If set to the special value <literal>none</literal>, +the <header>P3P</header> header will not be sent in a response. </para> </directive> @@ -190,13 +208,48 @@ Defines a path for which the cookie is s <context>location</context> <para> -Identifies the service that set a cookie. +If identifiers are issued by multiple servers (services), +each service should be assigned its own <value>number</value> +in order to ensure that client identifiers are unique. For version 1 cookies the default value is zero. -For version 2 cookies the default value is an IP address of the server. +For version 2 cookies this is the number composed from the last four +octets of the server’s IP address. </para> </directive> </section> + +<section id="variables" name="Embedded variables"> + +<para> +The <literal>ngx_http_userid_module</literal> module +supports the following embedded variables: +<list type="tag"> + +<tag-name id="var_uid_got"><var>$uid_got</var></tag-name> +<tag-desc> +The cookie name and received client identifier. +</tag-desc> + +<tag-name id="var_uid_reset"><var>$uid_reset</var></tag-name> +<tag-desc> +If set to a non-empty string, and it is not “<literal>0</literal>”, +client identifiers are reset. +The special value “<literal>log</literal>” additionally leads to the output of +messages about reset identifiers to the +<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> +The cookie name and sent client identifier. +</tag-desc> + +</list> +</para> + +</section> + </module>
--- a/xml/ru/docs/http/ngx_http_userid_module.xml +++ b/xml/ru/docs/http/ngx_http_userid_module.xml @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_userid_module" link="/ru/docs/http/ngx_http_userid_module.html" lang="ru" - rev="2"> + rev="3"> <section id="summary"> @@ -18,7 +18,8 @@ Модуль <literal>ngx_http_userid_module</literal> выдаёт куки для идентификации клиентов. Для записи в лог полученных и выданных кук можно использовать встроенные -переменные <var>$uid_got</var> и <var>$uid_set</var>. +переменные <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. @@ -105,33 +106,50 @@ userid_p3p 'policyref="/w3c/p3p.xml" <directive name="userid_expires"> -<syntax><value>время</value> | <literal>max</literal></syntax> -<default/> +<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>max</literal> устанавливает срок хранения куки до +31 декабря 2037 года 23:55:55 GMT. Это максимальное время, которое понимают старые браузеры. +Указание параметра <literal>off</literal> позволяет ограничить время +действия куки сессией браузера. </para> </directive> <directive name="userid_mark"> -<syntax><value>off | буква | цифра | =</value></syntax> +<syntax> + <value>буква</value> | <value>цифра</value> | + <literal>=</literal> | + <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> -Задаёт первый символ хвоста base64 (по умолчанию “<literal>==</literal>”) -представления куки и перевыдаёт все принятые куки, у которых этот хвост другой. -Это полезно, если необходимо добавить или поменять P3P или время -хранения куки, но при этом оставить неизменным закодированное внутри число. +Если параметр не <literal>off</literal>, включает механизм маркировки кук +и задаёт символ, используемый в качестве метки. +Этот механизм позволяет добавить или изменить +<link id="userid_p3p"/> и/или время хранения куки, но при этом оставить +неизменным идентификатор клиента. +Меткой может быть любая буква английского алфавита (с учётом регистра), +цифра или знак “<literal>=</literal>”. +</para> + +<para> +Если метка задана, то она сравнивается с первым дополняющим символом +в base64 представлении идентификатора клиента, передаваемом в куке. +Если они не совпадают, то кука перепосылается с заданной меткой, +временем хранения и заголовком <header>P3P</header>. </para> </directive> @@ -152,15 +170,17 @@ userid_p3p 'policyref="/w3c/p3p.xml" <directive name="userid_p3p"> -<syntax><value>строка</value></syntax> -<default/> +<syntax><value>строка</value> | <literal>none</literal></syntax> +<default>none</default> <context>http</context> <context>server</context> <context>location</context> <para> -Задаёт значение для поля заголовка <header>P3P</header>, который будет +Задаёт значение для поля заголовка <header>P3P</header>, которое будет выдаваться вместе с кукой. +Если задано специальное значение <literal>none</literal>, +то в ответе не будет заголовка <header>P3P</header>. </para> </directive> @@ -181,20 +201,55 @@ userid_p3p 'policyref="/w3c/p3p.xml" <directive name="userid_service"> -<syntax><value>число</value></syntax> +<syntax><value>номер</value></syntax> <default>IP-адрес сервера</default> <context>http</context> <context>server</context> <context>location</context> <para> -Задаёт номер сервиса, выдавшего куку. -По умолчанию для куки первой версии используется ноль, -а для второй — IP-адрес сервера. +Если идентификаторы выдаются несколькими серверами (сервисами), +то каждому сервису следует назначить свой собственный <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>