mod_usertrack.xml revision 53bae66d3dc14a667e14a451f7bc65a893dd450f
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm</description>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm <p>Previous releases of Apache have included a module which
b1771b4ea91b15a5da4a96f93e8aa78e700fd51ajohanengelen generates a 'clickstream' log of user activity on a site using
5c45bb188ab729e501e48732842cb9de6a9813beAlex Valavanis cookies. This was called the "cookies" module, mod_cookies. In
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm Apache 1.2 and later this module has been renamed the "user
d431763a9ec8059aa4962688de8144319969fb0fjohanengelen tracking" module, mod_usertrack. This module has been
d431763a9ec8059aa4962688de8144319969fb0fjohanengelen simplified and new directives added.</p>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm <p>Previously, the cookies module (now the user tracking
79d46cc367c4181803d9a7a327b163643f23e8a7cilix module) did its own logging, using the <directive>CookieLog</directive>
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof directive. In this release, this module does no logging at all.
9cadd148aa37a81210a58fc68e5c8c72ab7ea125Jabiertxof Instead, a configurable log format file should be used to log
9cadd148aa37a81210a58fc68e5c8c72ab7ea125Jabiertxof user click-streams. This is possible because the logging module
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm now allows multiple log files. The cookie itself is logged by
5ce8d034d9fe78f969629cfe65d1a2518f173ba9cilix using the text <code>%{cookie}n</code> in the log file format. For
0b8c1be8fec73b0ce317e9afa5ca6aa35a3b2545johanengelen example:</p>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm <p>For backward compatibility the configurable log module
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm implements the old <directive
79d46cc367c4181803d9a7a327b163643f23e8a7cilix module="mod_log_config">CookieLog</directive> directive, but this
79d46cc367c4181803d9a7a327b163643f23e8a7cilix should be upgraded to the above <directive
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm module="mod_log_config">CustomLog</directive> directive. </p>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm <p>(the following is from message
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm <022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com>
652726ac02dc3b0e805d2a2a0045f30458dca46cJabiertxof in the new-httpd archives) </p>
652726ac02dc3b0e805d2a2a0045f30458dca46cJabiertxofFrom: "Christian Allen" <christian@sane.com>
652726ac02dc3b0e805d2a2a0045f30458dca46cJabiertxofSubject: Re: Apache Y2K bug in mod_usertrack.c
652726ac02dc3b0e805d2a2a0045f30458dca46cJabiertxofDate: Tue, 30 Jun 1998 11:41:56 -0400
7809c81148155b4c4777463f9dbbbf714233e897JabiertxofDid some work with cookies and dug up some info that might be useful.
7809c81148155b4c4777463f9dbbbf714233e897JabiertxofTrue, Netscape claims that the correct format NOW is four digit dates, and
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxoffour digit dates do in fact work... for Netscape 4.x (Communicator), that
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxofis. However, 3.x and below do NOT accept them. It seems that Netscape
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxoforiginally had a 2-digit standard, and then with all of the Y2K hype and
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxofprobably a few complaints, changed to a four digit date for Communicator.
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxofFortunately, 4.x also understands the 2-digit format, and so the best way to
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxofensure that your expiration date is legible to the client's browser is to
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxofuse 2-digit dates.
7809c81148155b4c4777463f9dbbbf714233e897JabiertxofHowever, this does not limit expiration dates to the year 2000; if you use
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxofan expiration year of "13", for example, it is interpreted as 2013, NOT
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof1913! In fact, you can use an expiration year of up to "37", and it will be
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxofunderstood as "2037" by both MSIE and Netscape versions 3.x and up (not sure
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxofabout versions previous to those). Not sure why Netscape used that
9cadd148aa37a81210a58fc68e5c8c72ab7ea125Jabiertxofparticular year as its cut-off point, but my guess is that it was in respect
9cadd148aa37a81210a58fc68e5c8c72ab7ea125Jabiertxofto UNIX's 2038 problem. Netscape/MSIE 4.x seem to be able to understand
9cadd148aa37a81210a58fc68e5c8c72ab7ea125Jabiertxof2-digit years beyond that, at least until "50" for sure (I think they
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxofunderstand up until about "70", but not for sure).
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrmSummary: Mozilla 3.x and up understands two digit dates up until "37"
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm(2037). Mozilla 4.x understands up until at least "50" (2050) in 2-digit
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrmform, but also understands 4-digit years, which can probably reach up until
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm9999. Your best bet for sending a long-life cookie is to send it for some
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrmtime late in the year "37".
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm<directivesynopsis>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm<description>The domain to which the tracking cookie applies</description>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm<contextlist>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm</contextlist>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm <p>This directive controls the setting of the domain to which
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof the tracking cookie applies. If not present, no domain is
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof included in the cookie header field.</p>
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof <p>The domain string <strong>must</strong> begin with a dot, and
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof <strong>must</strong> include at least one embedded dot. That is,
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof ".foo.com" is legal, but "foo.bar.com" and ".com" are not.</p>
5cf332777b4c27336d64c273ac63bce3ee27a53dAlex Valavanis</directivesynopsis>
f84b3e8cf4811cb3ce6c33fb7341d0e836be583cjohanengelen<directivesynopsis>
f84b3e8cf4811cb3ce6c33fb7341d0e836be583cjohanengelen<description>Expiry time for the tracking cookie</description>
f84b3e8cf4811cb3ce6c33fb7341d0e836be583cjohanengelen<syntax>CookieExpires <em>expiry-period</em></syntax>
f84b3e8cf4811cb3ce6c33fb7341d0e836be583cjohanengelen<contextlist>
7e06f69b2d196711819d5fb5935e09cd89734bb4johanengelen</contextlist>
7073d105e612f7dc898c292742bee9655d2a51b2johanengelen <p>When used, this directive sets an expiry time on the cookie
7073d105e612f7dc898c292742bee9655d2a51b2johanengelen generated by the usertrack module. The <em>expiry-period</em>
7073d105e612f7dc898c292742bee9655d2a51b2johanengelen can be given either as a number of seconds, or in the format
7073d105e612f7dc898c292742bee9655d2a51b2johanengelen such as "2 weeks 3 days 7 hours". Valid denominations are:
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm years, months, weeks, days, hours, minutes and seconds. If the expiry
7073d105e612f7dc898c292742bee9655d2a51b2johanengelen time is in any format other than one number indicating the
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm number of seconds, it must be enclosed by double quotes.</p>
fefed98e624e5b375661d137181340caa08440e3johanengelen <p>If this directive is not used, cookies last only for the
fefed98e624e5b375661d137181340caa08440e3johanengelen current browser session.</p>
fefed98e624e5b375661d137181340caa08440e3johanengelen</directivesynopsis>
fefed98e624e5b375661d137181340caa08440e3johanengelen<directivesynopsis>
fefed98e624e5b375661d137181340caa08440e3johanengelen<description>Name of the tracking cookie</description>
2015416b7a65a6c77a69ed97b746e0efbefe0578Johan B. C. Engelen<syntax>CookieName <em>token</em></syntax>
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix<contextlist>
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix</contextlist>
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix <p>This directive allows you to change the name of the cookie
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix this module uses for its tracking purposes. By default the
1e944d29efb206f5d0b5d1069cb098e22169d548cilix <p>You must specify a valid cookie name; results are
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof unpredictable if you use a name containing unusual characters.
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof Valid characters include A-Z, a-z, 0-9, "_", and "-".</p>
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof</directivesynopsis>
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof<directivesynopsis>
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof<description>Format of the cookie header field</description>
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof<syntax>CookieStyle
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof <em>Netscape|Cookie|Cookie2|RFC2109|RFC2965</em></syntax>
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof<contextlist>
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof</contextlist>
0b2d8abc1011ad865fce3b883ccb2587cb15cc90Johan B. C. Engelen <p>This directive controls the format of the cookie header
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix field. The three formats allowed are:</p>
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix <li><strong>Netscape</strong>, which is the original but now deprecated
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix syntax. This is the default, and the syntax Apache has
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof historically used.</li>
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof <li><strong>Cookie</strong> or <strong>RFC2109</strong>, which is the syntax that
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof superseded the Netscape syntax.</li>
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof <li><strong>Cookie2</strong> or <strong>RFC2965</strong>, which is the most
7809c81148155b4c4777463f9dbbbf714233e897Jabiertxof current cookie syntax.</li>
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof <p>Not all clients can understand all of these formats. but you
58ed9b010ec4b66e241ab201ef78bb7a3d88a20aJabiertxof should use the newest one that is generally acceptable to your
1e944d29efb206f5d0b5d1069cb098e22169d548cilix users' browsers.</p>
1e944d29efb206f5d0b5d1069cb098e22169d548cilix</directivesynopsis>
797bee69297bbdd86c5cff2e0771a71d1e2ac69dcilix<directivesynopsis>
7655c8b8ffe3674dd7e7c74f450fb7194943c0deJon A. Cruz<description>Enables tracking cookie</description>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm<contextlist>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm</contextlist>
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm <p>When the user track module is compiled in, and
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm "CookieTracking on" is set, Apache will start sending a
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm user-tracking cookie for all new requests. This directive can
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm be used to turn this behavior on or off on a per-server or
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm per-directory basis. By default, compiling mod_usertrack will
f07bfd5a05d43a6d11f7cd442f085149092dea88pjrm not activate cookies. </p>