mod_usertrack.xml revision 6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fc
1ad6a171cee261581034996877314cf29fc92227rbowen<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
1ad6a171cee261581034996877314cf29fc92227rbowen<modulesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen<description>
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive<em>Clickstream</em> logging of user activity on a site
1ad6a171cee261581034996877314cf29fc92227rbowen</description>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>Previous releases of Apache have included a module which
1ad6a171cee261581034996877314cf29fc92227rbowen generates a 'clickstream' log of user activity on a site using
1ad6a171cee261581034996877314cf29fc92227rbowen cookies. This was called the "cookies" module, mod_cookies. In
1ad6a171cee261581034996877314cf29fc92227rbowen Apache 1.2 and later this module has been renamed the "user
1ad6a171cee261581034996877314cf29fc92227rbowen tracking" module, mod_usertrack. This module has been
1ad6a171cee261581034996877314cf29fc92227rbowen simplified and new directives added.</p>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>Previously, the cookies module (now the user tracking
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj module) did its own logging, using the <directive>CookieLog</directive>
1ad6a171cee261581034996877314cf29fc92227rbowen directive. In this release, this module does no logging at all.
1ad6a171cee261581034996877314cf29fc92227rbowen Instead, a configurable log format file should be used to log
1ad6a171cee261581034996877314cf29fc92227rbowen user click-streams. This is possible because the logging module
1ad6a171cee261581034996877314cf29fc92227rbowen now allows multiple log files. The cookie itself is logged by
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj using the text <code>%{cookie}n</code> in the log file format. For
1ad6a171cee261581034996877314cf29fc92227rbowen example:</p>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>For backward compatibility the configurable log module
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive implements the old <directive
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive module="mod_log_config">CookieLog</directive> directive, but this
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive should be upgraded to the above <directive
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive module="mod_log_config">CustomLog</directive> directive. </p>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>(the following is from message
1ad6a171cee261581034996877314cf29fc92227rbowen <022701bda43d$9d32bbb0$1201a8c0@christian.office.sane.com>
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj in the new-httpd archives) </p>
1ad6a171cee261581034996877314cf29fc92227rbowenFrom: "Christian Allen" <christian@sane.com>
1ad6a171cee261581034996877314cf29fc92227rbowenSubject: Re: Apache Y2K bug in mod_usertrack.c
1ad6a171cee261581034996877314cf29fc92227rbowenDate: Tue, 30 Jun 1998 11:41:56 -0400
1ad6a171cee261581034996877314cf29fc92227rbowenDid some work with cookies and dug up some info that might be useful.
1ad6a171cee261581034996877314cf29fc92227rbowenTrue, Netscape claims that the correct format NOW is four digit dates, and
1ad6a171cee261581034996877314cf29fc92227rbowenfour digit dates do in fact work... for Netscape 4.x (Communicator), that
1ad6a171cee261581034996877314cf29fc92227rbowenis. However, 3.x and below do NOT accept them. It seems that Netscape
1ad6a171cee261581034996877314cf29fc92227rbowenoriginally had a 2-digit standard, and then with all of the Y2K hype and
1ad6a171cee261581034996877314cf29fc92227rbowenprobably a few complaints, changed to a four digit date for Communicator.
1ad6a171cee261581034996877314cf29fc92227rbowenFortunately, 4.x also understands the 2-digit format, and so the best way to
1ad6a171cee261581034996877314cf29fc92227rbowenensure that your expiration date is legible to the client's browser is to
1ad6a171cee261581034996877314cf29fc92227rbowenuse 2-digit dates.
1ad6a171cee261581034996877314cf29fc92227rbowenHowever, this does not limit expiration dates to the year 2000; if you use
1ad6a171cee261581034996877314cf29fc92227rbowenan expiration year of "13", for example, it is interpreted as 2013, NOT
1ad6a171cee261581034996877314cf29fc92227rbowen1913! In fact, you can use an expiration year of up to "37", and it will be
1ad6a171cee261581034996877314cf29fc92227rbowenunderstood as "2037" by both MSIE and Netscape versions 3.x and up (not sure
1ad6a171cee261581034996877314cf29fc92227rbowenabout versions previous to those). Not sure why Netscape used that
1ad6a171cee261581034996877314cf29fc92227rbowenparticular year as its cut-off point, but my guess is that it was in respect
1ad6a171cee261581034996877314cf29fc92227rbowento UNIX's 2038 problem. Netscape/MSIE 4.x seem to be able to understand
1ad6a171cee261581034996877314cf29fc92227rbowen2-digit years beyond that, at least until "50" for sure (I think they
1ad6a171cee261581034996877314cf29fc92227rbowenunderstand up until about "70", but not for sure).
1ad6a171cee261581034996877314cf29fc92227rbowenSummary: Mozilla 3.x and up understands two digit dates up until "37"
1ad6a171cee261581034996877314cf29fc92227rbowen(2037). Mozilla 4.x understands up until at least "50" (2050) in 2-digit
1ad6a171cee261581034996877314cf29fc92227rbowenform, but also understands 4-digit years, which can probably reach up until
1ad6a171cee261581034996877314cf29fc92227rbowen9999. Your best bet for sending a long-life cookie is to send it for some
1ad6a171cee261581034996877314cf29fc92227rbowentime late in the year "37".
1ad6a171cee261581034996877314cf29fc92227rbowen<directivesynopsis>
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive<description>The domain to which the tracking cookie applies</description>
1ad6a171cee261581034996877314cf29fc92227rbowen<contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen</contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>This directive controls the setting of the domain to which
1ad6a171cee261581034996877314cf29fc92227rbowen the tracking cookie applies. If not present, no domain is
1ad6a171cee261581034996877314cf29fc92227rbowen included in the cookie header field.</p>
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj <p>The domain string <strong>must</strong> begin with a dot, and
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj <strong>must</strong> include at least one embedded dot. That is,
1ad6a171cee261581034996877314cf29fc92227rbowen ".foo.com" is legal, but "foo.bar.com" and ".com" are not.</p>
1ad6a171cee261581034996877314cf29fc92227rbowen</directivesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen<directivesynopsis>
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive<description>Expiry time for the tracking cookie</description>
1ad6a171cee261581034996877314cf29fc92227rbowen<contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen</contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>When used, this directive sets an expiry time on the cookie
1ad6a171cee261581034996877314cf29fc92227rbowen generated by the usertrack module. The <em>expiry-period</em>
1ad6a171cee261581034996877314cf29fc92227rbowen can be given either as a number of seconds, or in the format
1ad6a171cee261581034996877314cf29fc92227rbowen such as "2 weeks 3 days 7 hours". Valid denominations are:
1ad6a171cee261581034996877314cf29fc92227rbowen years, months, weeks, hours, minutes and seconds. If the expiry
1ad6a171cee261581034996877314cf29fc92227rbowen time is in any format other than one number indicating the
1ad6a171cee261581034996877314cf29fc92227rbowen number of seconds, it must be enclosed by double quotes.</p>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>If this directive is not used, cookies last only for the
1ad6a171cee261581034996877314cf29fc92227rbowen current browser session.</p>
1ad6a171cee261581034996877314cf29fc92227rbowen</directivesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen<directivesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen<contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen</contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>This directive allows you to change the name of the cookie
1ad6a171cee261581034996877314cf29fc92227rbowen this module uses for its tracking purposes. By default the
1ad6a171cee261581034996877314cf29fc92227rbowen <p>You must specify a valid cookie name; results are
1ad6a171cee261581034996877314cf29fc92227rbowen unpredictable if you use a name containing unusual characters.
1ad6a171cee261581034996877314cf29fc92227rbowen Valid characters include A-Z, a-z, 0-9, "_", and "-".</p>
1ad6a171cee261581034996877314cf29fc92227rbowen</directivesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen<directivesynopsis>
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive<description>Format of the cookie header field</description>
1ad6a171cee261581034996877314cf29fc92227rbowen<syntax>CookieStyle
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj <em>Netscape|Cookie|Cookie2|RFC2109|RFC2965</em></syntax>
1ad6a171cee261581034996877314cf29fc92227rbowen<contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen</contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>This directive controls the format of the cookie header
1ad6a171cee261581034996877314cf29fc92227rbowen field. The three formats allowed are:</p>
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj <li><strong>Netscape</strong>, which is the original but now deprecated
1ad6a171cee261581034996877314cf29fc92227rbowen syntax. This is the default, and the syntax Apache has
1ad6a171cee261581034996877314cf29fc92227rbowen historically used.</li>
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj <li><strong>Cookie</strong> or <strong>RFC2109</strong>, which is the syntax that
1ad6a171cee261581034996877314cf29fc92227rbowen superseded the Netscape syntax.</li>
a4bd20fca128fbe09c54d02d96fa92be3b402297patrikj <li><strong>Cookie2</strong> or <strong>RFC2965</strong>, which is the most
1ad6a171cee261581034996877314cf29fc92227rbowen current cookie syntax.</li>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>Not all clients can understand all of these formats. but you
1ad6a171cee261581034996877314cf29fc92227rbowen should use the newest one that is generally acceptable to your
1ad6a171cee261581034996877314cf29fc92227rbowen users' browsers.</p>
1ad6a171cee261581034996877314cf29fc92227rbowen</directivesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen<directivesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen<contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen</contextlist>
1ad6a171cee261581034996877314cf29fc92227rbowen <p>When the user track module is compiled in, and
1ad6a171cee261581034996877314cf29fc92227rbowen "CookieTracking on" is set, Apache will start sending a
1ad6a171cee261581034996877314cf29fc92227rbowen user-tracking cookie for all new requests. This directive can
1ad6a171cee261581034996877314cf29fc92227rbowen be used to turn this behavior on or off on a per-server or
1ad6a171cee261581034996877314cf29fc92227rbowen per-directory basis. By default, compiling mod_usertrack will
1ad6a171cee261581034996877314cf29fc92227rbowen not activate cookies. </p>
1ad6a171cee261581034996877314cf29fc92227rbowen</directivesynopsis>
1ad6a171cee261581034996877314cf29fc92227rbowen</modulesynopsis>