<?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="2">

<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
<var>$uid_got</var> and <var>$uid_set</var>.
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></syntax>
<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
“<literal>31 Dec 2037 23:55:55 GMT</literal>”.
This is the maximum time understood by old browsers.
</para>

</directive>


<directive name="userid_mark">
<syntax><value>off | letter | digit | =</value></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.
</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></syntax>
<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.
</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>
Identifies the service that set a cookie.
For version 1 cookies the default value is zero.
For version 2 cookies the default value is an IP address of the server.
</para>

</directive>

</section>

</module>