granicus.if.org Git - apache/blob - docs/manual/mod/mod_usertrack.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_usertrack.xml.meta">
  24 <name>mod_usertrack</name>
  25 <description>
  26 <em>Clickstream</em> logging of user activity on a site
  27 </description>
  28 <status>Extension</status>
  29 <sourcefile>mod_usertrack.c</sourcefile>
  30 <identifier>usertrack_module</identifier>
  31
  32 <summary>
  33     <p>Provides tracking of a user through your website via browser
  34     cookies.</p>
  35 </summary>
  36
  37
  38 <section id="logging">
  39 <title>Logging</title>
  40
  41     <p><module>mod_usertrack</module> sets a cookie which can be logged
  42     via <module>mod_log_config</module> configurable logging formats:</p>
  43
  44     <example>
  45     LogFormat "%{Apache}n %r %t" usertrack<br />
  46     CustomLog logs/clickstream.log usertrack
  47     </example>
  48
  49 </section>
  50
  51 <directivesynopsis>
  52 <name>CookieDomain</name>
  53 <description>The domain to which the tracking cookie applies</description>
  54 <syntax>CookieDomain <em>domain</em></syntax>
  55 <contextlist>
  56 <context>server config</context>
  57 <context>virtual host</context>
  58 <context>directory</context>
  59 <context>.htaccess</context>
  60 </contextlist>
  61 <override>FileInfo</override>
  62
  63 <usage>
  64
  65     <p>This directive controls the setting of the domain to which
  66     the tracking cookie applies. If not present, no domain is
  67     included in the cookie header field.</p>
  68
  69     <p>The domain string <strong>must</strong> begin with a dot, and
  70     <strong>must</strong> include at least one embedded dot. That is,
  71     <code>.example.com</code> is legal, but <code>www.example.com</code> and
  72     <code>.com</code> are not.</p>
  73
  74     <note>Most browsers in use today will not allow cookies to be set
  75     for a two-part top level domain, such as <code>.co.uk</code>,
  76     although such a domain ostensibly fulfills the requirements
  77     above.<br />
  78
  79     These domains are equivalent to top level domains such as
  80     <code>.com</code>, and allowing such cookies may be a security
  81     risk. Thus, if you are under a two-part top level domain, you
  82     should still use your actual domain, as you would with any other top
  83     level domain (for example <code>.example.co.uk</code>).
  84     </note>
  85 </usage>
  86 </directivesynopsis>
  87
  88
  89 <directivesynopsis>
  90 <name>CookieExpires</name>
  91 <description>Expiry time for the tracking cookie</description>
  92 <syntax>CookieExpires <em>expiry-period</em></syntax>
  93 <contextlist>
  94 <context>server config</context>
  95 <context>virtual host</context>
  96 <context>directory</context>
  97 <context>.htaccess</context>
  98 </contextlist>
  99 <override>FileInfo</override>
 100
 101 <usage>
 102     <p>When used, this directive sets an expiry time on the cookie
 103     generated by the usertrack module. The <em>expiry-period</em>
 104     can be given either as a number of seconds, or in the format
 105     such as "2 weeks 3 days 7 hours". Valid denominations are:
 106     years, months, weeks, days, hours, minutes and seconds. If the expiry
 107     time is in any format other than one number indicating the
 108     number of seconds, it must be enclosed by double quotes.</p>
 109
 110     <p>If this directive is not used, cookies last only for the
 111     current browser session.</p>
 112 </usage>
 113 </directivesynopsis>
 114
 115 <directivesynopsis>
 116 <name>CookieName</name>
 117 <description>Name of the tracking cookie</description>
 118 <syntax>CookieName <em>token</em></syntax>
 119 <default>CookieName Apache</default>
 120 <contextlist>
 121 <context>server config</context>
 122 <context>virtual host</context>
 123 <context>directory</context>
 124 <context>.htaccess</context>
 125 </contextlist>
 126 <override>FileInfo</override>
 127
 128 <usage>
 129     <p>This directive allows you to change the name of the cookie
 130     this module uses for its tracking purposes. By default the
 131     cookie is named "<code>Apache</code>".</p>
 132
 133     <p>You must specify a valid cookie name; results are
 134     unpredictable if you use a name containing unusual characters.
 135     Valid characters include A-Z, a-z, 0-9, "_", and "-".</p>
 136 </usage>
 137 </directivesynopsis>
 138
 139 <directivesynopsis>
 140 <name>CookieStyle</name>
 141 <description>Format of the cookie header field</description>
 142 <syntax>CookieStyle
 143     <em>Netscape|Cookie|Cookie2|RFC2109|RFC2965</em></syntax>
 144 <default>CookieStyle Netscape</default>
 145 <contextlist>
 146 <context>server config</context>
 147 <context>virtual host</context>
 148 <context>directory</context>
 149 <context>.htaccess</context>
 150 </contextlist>
 151 <override>FileInfo</override>
 152
 153 <usage>
 154     <p>This directive controls the format of the cookie header
 155     field. The three formats allowed are:</p>
 156
 157     <ul>
 158       <li><strong>Netscape</strong>, which is the original but now deprecated
 159       syntax. This is the default, and the syntax Apache has
 160       historically used.</li>
 161
 162       <li><strong>Cookie</strong> or <strong>RFC2109</strong>, which is the syntax that
 163       superseded the Netscape syntax.</li>
 164
 165       <li><strong>Cookie2</strong> or <strong>RFC2965</strong>, which is the most
 166       current cookie syntax.</li>
 167     </ul>
 168
 169     <p>Not all clients can understand all of these formats, but you
 170     should use the newest one that is generally acceptable to your
 171     users' browsers. At the time of writing, most browsers support all
 172     three of these formats, with <code>Cookie2</code> being the
 173     preferred format.</p>
 174 </usage>
 175 </directivesynopsis>
 176
 177
 178
 179 <directivesynopsis>
 180 <name>CookieTracking</name>
 181 <description>Enables tracking cookie</description>
 182 <syntax>CookieTracking on|off</syntax>
 183 <default>CookieTracking off</default>
 184 <contextlist>
 185 <context>server config</context>
 186 <context>virtual host</context>
 187 <context>directory</context>
 188 <context>.htaccess</context>
 189 </contextlist>
 190 <override>FileInfo</override>
 191
 192 <usage>
 193     <p>When <module>mod_usertrack</module> is loaded, and
 194     <code>CookieTracking on</code> is set, Apache will send a
 195     user-tracking cookie for all new requests. This directive can
 196     be used to turn this behavior on or off on a per-server or
 197     per-directory basis. By default, enabling
 198     <module>mod_usertrack</module> will <strong>not</strong>
 199     activate cookies. </p>
 200
 201 </usage>
 202 </directivesynopsis>
 203
 204 </modulesynopsis>