<?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>