Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_userid_module.xml @ 915:893d36b6d013
Updated list of supported linux distributions.
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Mon, 27 May 2013 19:45:45 +0400 |
parents | 17d0c825f098 |
children | 95c3c3bbf1ce |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_userid_module" link="/en/docs/http/ngx_http_userid_module.html" lang="en" rev="3"> <section id="summary"> <para> 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 <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. </para> </section> <section id="example" name="Example Configuration"> <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="Directives"> <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> Allows or prohibits to set cookies and log the received cookies: <list type="tag"> <tag-name><literal>on</literal></tag-name> <tag-desc> allows to set version 2 cookies and log the received cookies; </tag-desc> <tag-name><literal>v1</literal></tag-name> <tag-desc> allows to set version 1 cookies and log the received cookies; </tag-desc> <tag-name><literal>log</literal></tag-name> <tag-desc> prohibits to set cookies but allows to log the received cookies; </tag-desc> <tag-name><literal>off</literal></tag-name> <tag-desc> prohibits to set cookies and log the received cookies. </tag-desc> </list> </para> </directive> <directive name="userid_domain"> <syntax><value>name</value> | <literal>none</literal></syntax> <default>none</default> <context>http</context> <context>server</context> <context>location</context> <para> Defines a domain for which the cookie is set. The parameter <literal>none</literal> disables setting a domain for a cookie. </para> </directive> <directive name="userid_expires"> <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> 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>letter</value> | <value>digit</value> | <literal>=</literal> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <para> 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> <directive name="userid_name"> <syntax><value>name</value></syntax> <default>uid</default> <context>http</context> <context>server</context> <context>location</context> <para> Sets a cookie name. </para> </directive> <directive name="userid_p3p"> <syntax><value>string</value> | <literal>none</literal></syntax> <default>none</default> <context>http</context> <context>server</context> <context>location</context> <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> <directive name="userid_path"> <syntax><value>path</value></syntax> <default>/</default> <context>http</context> <context>server</context> <context>location</context> <para> Defines a path for which the cookie is set. </para> </directive> <directive name="userid_service"> <syntax><value>number</value></syntax> <default>IP address of the server</default> <context>http</context> <context>server</context> <context>location</context> <para> 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 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>