<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
-
-<modulesynopsis>
-<name>mod_usertrack</name>
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+<!-- $LastChangedRevision$ -->
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<modulesynopsis metafile="mod_usertrack.xml.meta">
+<name>mod_usertrack</name>
<description>
- This module uses cookies to provide for a
- <em>clickstream</em> log of user activity on a site.
+<em>Clickstream</em> logging of user activity on a site
</description>
<status>Extension</status>
<sourcefile>mod_usertrack.c</sourcefile>
<identifier>usertrack_module</identifier>
-<compatibility>Known as mod_cookies prior to Apache 1.3.</compatibility>
<summary>
- <p>Previous releases of Apache have included a module which
- generates a 'clickstream' log of user activity on a site using
- cookies. This was called the "cookies" module, mod_cookies. In
- Apache 1.2 and later this module has been renamed the "user
- tracking" module, mod_usertrack. This module has been
- simplified and new directives added.</p>
+ <p>Provides tracking of a user through your website via browser
+ cookies.</p>
</summary>
-<section>
+<section id="logging">
<title>Logging</title>
- <p>Previously, the cookies module (now the user tracking
- module) did its own logging, using the <directive>CookieLog</directive>
- directive. In this release, this module does no logging at all.
- Instead, a configurable log format file should be used to log
- user click-streams. This is possible because the logging module
- now allows multiple log files. The cookie itself is logged by
- using the text <code>%{cookie}n</code> in the log file format. For
- example:</p>
-<example>
-CustomLog logs/clickstream "%{cookie}n %r %t"
-</example>
-
- <p>For backward compatibility the configurable log module
- implements the old <directive>CookieLog</directive> directive, but this
- should be upgraded to the above <directive>CustomLog</directive> directive. </p>
-</section>
+ <p><module>mod_usertrack</module> sets a cookie which can be logged
+ via <module>mod_log_config</module> configurable logging formats:</p>
-<section>
-<title>2-digit or 4-digit dates for cookies?</title>
-
- <p>(the following is from message
- <022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com>
- in the new-httpd archives) </p>
-<pre>
-From: "Christian Allen" <christian@sane.com>
-Subject: Re: Apache Y2K bug in mod_usertrack.c
-Date: Tue, 30 Jun 1998 11:41:56 -0400
-
-Did some work with cookies and dug up some info that might be useful.
-
-True, Netscape claims that the correct format NOW is four digit dates, and
-four digit dates do in fact work... for Netscape 4.x (Communicator), that
-is. However, 3.x and below do NOT accept them. It seems that Netscape
-originally had a 2-digit standard, and then with all of the Y2K hype and
-probably a few complaints, changed to a four digit date for Communicator.
-Fortunately, 4.x also understands the 2-digit format, and so the best way to
-ensure that your expiration date is legible to the client's browser is to
-use 2-digit dates.
-
-However, this does not limit expiration dates to the year 2000; if you use
-an expiration year of "13", for example, it is interpreted as 2013, NOT
-1913! In fact, you can use an expiration year of up to "37", and it will be
-understood as "2037" by both MSIE and Netscape versions 3.x and up (not sure
-about versions previous to those). Not sure why Netscape used that
-particular year as its cut-off point, but my guess is that it was in respect
-to UNIX's 2038 problem. Netscape/MSIE 4.x seem to be able to understand
-2-digit years beyond that, at least until "50" for sure (I think they
-understand up until about "70", but not for sure).
-
-Summary: Mozilla 3.x and up understands two digit dates up until "37"
-(2037). Mozilla 4.x understands up until at least "50" (2050) in 2-digit
-form, but also understands 4-digit years, which can probably reach up until
-9999. Your best bet for sending a long-life cookie is to send it for some
-time late in the year "37".
-</pre>
+ <highlight language="config">
+LogFormat "%{Apache}n %r %t" usertrack
+CustomLog "logs/clickstream.log" usertrack
+ </highlight>
</section>
<directivesynopsis>
<name>CookieDomain</name>
-<description>controls the setting of the domain to which the tracking cookie applies.</description>
+<description>The domain to which the tracking cookie applies</description>
<syntax>CookieDomain <em>domain</em></syntax>
-<default>None</default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
+<override>FileInfo</override>
<usage>
<p>The domain string <strong>must</strong> begin with a dot, and
<strong>must</strong> include at least one embedded dot. That is,
- ".foo.com" is legal, but "foo.bar.com" and ".com" are not.</p>
+ <code>.example.com</code> is legal, but <code>www.example.com</code> and
+ <code>.com</code> are not.</p>
+
+ <note>Most browsers in use today will not allow cookies to be set
+ for a two-part top level domain, such as <code>.co.uk</code>,
+ although such a domain ostensibly fulfills the requirements
+ above.<br />
+
+ These domains are equivalent to top level domains such as
+ <code>.com</code>, and allowing such cookies may be a security
+ risk. Thus, if you are under a two-part top level domain, you
+ should still use your actual domain, as you would with any other top
+ level domain (for example <code>.example.co.uk</code>).
+ </note>
+
+ <highlight language="config">
+ CookieDomain .example.com
+ </highlight>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>CookieExpires</name>
+<description>Expiry time for the tracking cookie</description>
<syntax>CookieExpires <em>expiry-period</em></syntax>
-<default></default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
-<override></override>
-<compatibility>In 1.3.20 and earlier, not usable in directory and
-.htaccess</compatibility>
+<override>FileInfo</override>
<usage>
<p>When used, this directive sets an expiry time on the cookie
generated by the usertrack module. The <em>expiry-period</em>
can be given either as a number of seconds, or in the format
such as "2 weeks 3 days 7 hours". Valid denominations are:
- years, months, weeks, hours, minutes and seconds. If the expiry
+ years, months, weeks, days, hours, minutes and seconds. If the expiry
time is in any format other than one number indicating the
number of seconds, it must be enclosed by double quotes.</p>
<p>If this directive is not used, cookies last only for the
current browser session.</p>
+
+ <highlight language="config">
+ CookieExpires "3 weeks"
+ </highlight>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>CookieName</name>
+<description>Name of the tracking cookie</description>
<syntax>CookieName <em>token</em></syntax>
-<default>Apache</default>
+<default>CookieName Apache</default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
+<override>FileInfo</override>
<usage>
<p>This directive allows you to change the name of the cookie
<p>You must specify a valid cookie name; results are
unpredictable if you use a name containing unusual characters.
Valid characters include A-Z, a-z, 0-9, "_", and "-".</p>
+
+ <highlight language="config">
+ CookieName clicktrack
+ </highlight>
</usage>
+
</directivesynopsis>
<directivesynopsis>
<name>CookieStyle</name>
-<description>Controls the format of the cookie header field</description>
+<description>Format of the cookie header field</description>
<syntax>CookieStyle
<em>Netscape|Cookie|Cookie2|RFC2109|RFC2965</em></syntax>
-<default></default>
+<default>CookieStyle Netscape</default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
+<override>FileInfo</override>
<usage>
<p>This directive controls the format of the cookie header
current cookie syntax.</li>
</ul>
- <p>Not all clients can understand all of these formats. but you
+ <p>Not all clients can understand all of these formats, but you
should use the newest one that is generally acceptable to your
- users' browsers.</p>
+ users' browsers. At the time of writing, most browsers support all
+ three of these formats, with <code>Cookie2</code> being the
+ preferred format.</p>
+
+ <highlight language="config">
+ CookieStyle Cookie2
+ </highlight>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>CookieTracking</name>
+<description>Enables tracking cookie</description>
<syntax>CookieTracking on|off</syntax>
-<default></default>
+<default>CookieTracking off</default>
<contextlist>
<context>server config</context>
<context>virtual host</context>
<override>FileInfo</override>
<usage>
- <p>When the user track module is compiled in, and
- "CookieTracking on" is set, Apache will start sending a
+ <p>When <module>mod_usertrack</module> is loaded, and
+ <code>CookieTracking on</code> is set, Apache will send a
user-tracking cookie for all new requests. This directive can
be used to turn this behavior on or off on a per-server or
- per-directory basis. By default, compiling mod_usertrack will
- not activate cookies. </p>
+ per-directory basis. By default, enabling
+ <module>mod_usertrack</module> will <strong>not</strong>
+ activate cookies. </p>
+
+ <highlight language="config">
+ CookieTracking on
+ </highlight>
</usage>
</directivesynopsis>
</modulesynopsis>
-
projects / apache / blobdiff