Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_userid_module.xml @ 868:17d0c825f098

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 2ff9c3ea8c98
children 95c3c3bbf1ce
comparison
equal deleted inserted replaced
867:20a50f7bcbd6 868:17d0c825f098
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9 9
10 <module name="Module ngx_http_userid_module" 10 <module name="Module ngx_http_userid_module"
11 link="/en/docs/http/ngx_http_userid_module.html" 11 link="/en/docs/http/ngx_http_userid_module.html"
12 lang="en" 12 lang="en"
13 rev="2"> 13 rev="3">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 The <literal>ngx_http_userid_module</literal> module sets cookies 18 The <literal>ngx_http_userid_module</literal> module sets cookies
19 suitable for client identification. 19 suitable for client identification.
20 Received and set cookies can be logged using the embedded variables 20 Received and set cookies can be logged using the embedded variables
21 <var>$uid_got</var> and <var>$uid_set</var>. 21 <link id="var_uid_got">$uid_got</link> and
22 <link id="var_uid_set">$uid_set</link>.
22 This module is compatible with the 23 This module is compatible with the
23 <link url="http://www.lexa.ru/programs/mod-uid-eng.html">mod_uid</link> 24 <link url="http://www.lexa.ru/programs/mod-uid-eng.html">mod_uid</link>
24 module for Apache. 25 module for Apache.
25 </para> 26 </para>
26 27
103 104
104 </directive> 105 </directive>
105 106
106 107
107 <directive name="userid_expires"> 108 <directive name="userid_expires">
108 <syntax><value>time</value> | <literal>max</literal></syntax> 109 <syntax><value>time</value> | <literal>max</literal> |
109 <default/> 110 <literal>off</literal></syntax>
111 <default>off</default>
110 <context>http</context> 112 <context>http</context>
111 <context>server</context> 113 <context>server</context>
112 <context>location</context> 114 <context>location</context>
113 115
114 <para> 116 <para>
115 Sets a time during which a browser should keep the cookie. 117 Sets a time during which a browser should keep the cookie.
116 The parameter <literal>max</literal> sets the time to 118 The parameter <literal>max</literal> will cause the cookie to expire on
117 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. 119 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
118 This is the maximum time understood by old browsers. 120 This is the maximum time understood by old browsers.
121 The parameter <literal>off</literal> will cause the cookie to expire at
122 the end of a browser session.
119 </para> 123 </para>
120 124
121 </directive> 125 </directive>
122 126
123 127
124 <directive name="userid_mark"> 128 <directive name="userid_mark">
125 <syntax><value>off | letter | digit | =</value></syntax> 129 <syntax>
130 <value>letter</value> | <value>digit</value> |
131 <literal>=</literal> |
132 <literal>off</literal></syntax>
126 <default>off</default> 133 <default>off</default>
127 <context>http</context> 134 <context>http</context>
128 <context>server</context> 135 <context>server</context>
129 <context>location</context> 136 <context>location</context>
130 137
131 <para> 138 <para>
132 Sets the first symbol of the cookie’s representation base64 tail 139 If parameter is not <literal>off</literal>, enables the cookie marking
133 (“<literal>==</literal>” by default) and resets all accepted cookies 140 mechanism and sets a character used as a mark.
134 with another tail. 141 This mechanism allows to add or change
135 It may be useful if it's required to add or change the P3P or the cookie expire 142 <link id="userid_p3p"/> and/or cookie expiration time while
136 time and leave the internally encoded value unchanged. 143 preserving the client identifier.
144 The mark can be any letter of the English alphabet (case-sensitive),
145 digit, or the “<literal>=</literal>” character.
146 </para>
147
148 <para>
149 If a mark is set, it is compared with the first padding symbol
150 in the base64 representation of client identifier passed in a cookie.
151 If they do not match, a cookie is resent with the specified mark,
152 expiration time and a <header>P3P</header> header.
137 </para> 153 </para>
138 154
139 </directive> 155 </directive>
140 156
141 157
152 168
153 </directive> 169 </directive>
154 170
155 171
156 <directive name="userid_p3p"> 172 <directive name="userid_p3p">
157 <syntax><value>string</value></syntax> 173 <syntax><value>string</value> | <literal>none</literal></syntax>
158 <default/> 174 <default>none</default>
159 <context>http</context> 175 <context>http</context>
160 <context>server</context> 176 <context>server</context>
161 <context>location</context> 177 <context>location</context>
162 178
163 <para> 179 <para>
164 Sets a value for the <header>P3P</header> header field that will be 180 Sets a value for the <header>P3P</header> header field that will be
165 sent along with a cookie. 181 sent along with a cookie.
182 If set to the special value <literal>none</literal>,
183 the <header>P3P</header> header will not be sent in a response.
166 </para> 184 </para>
167 185
168 </directive> 186 </directive>
169 187
170 188
188 <context>http</context> 206 <context>http</context>
189 <context>server</context> 207 <context>server</context>
190 <context>location</context> 208 <context>location</context>
191 209
192 <para> 210 <para>
193 Identifies the service that set a cookie. 211 If identifiers are issued by multiple servers (services),
212 each service should be assigned its own <value>number</value>
213 in order to ensure that client identifiers are unique.
194 For version 1 cookies the default value is zero. 214 For version 1 cookies the default value is zero.
195 For version 2 cookies the default value is an IP address of the server. 215 For version 2 cookies this is the number composed from the last four
196 </para> 216 octets of the server’s IP address.
197 217 </para>
198 </directive> 218
219 </directive>
220
221 </section>
222
223
224 <section id="variables" name="Embedded variables">
225
226 <para>
227 The <literal>ngx_http_userid_module</literal> module
228 supports the following embedded variables:
229 <list type="tag">
230
231 <tag-name id="var_uid_got"><var>$uid_got</var></tag-name>
232 <tag-desc>
233 The cookie name and received client identifier.
234 </tag-desc>
235
236 <tag-name id="var_uid_reset"><var>$uid_reset</var></tag-name>
237 <tag-desc>
238 If set to a non-empty string, and it is not “<literal>0</literal>”,
239 client identifiers are reset.
240 The special value “<literal>log</literal>” additionally leads to the output of
241 messages about reset identifiers to the
242 <link doc="../ngx_core_module.xml" id="error_log"/>.
243 </tag-desc>
244
245 <tag-name id="var_uid_set"><var>$uid_set</var></tag-name>
246 <tag-desc>
247 The cookie name and sent client identifier.
248 </tag-desc>
249
250 </list>
251 </para>
199 252
200 </section> 253 </section>
201 254
202 </module> 255 </module>