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     <highlight language="config">
  45 LogFormat "%{Apache}n %r %t" usertrack
  46 CustomLog "logs/clickstream.log" usertrack
  47     </highlight>
  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
  86     <highlight language="config">
  87     CookieDomain .example.com
  88     </highlight>
  89 </usage>
  90 </directivesynopsis>
  91
  92
  93 <directivesynopsis>
  94 <name>CookieExpires</name>
  95 <description>Expiry time for the tracking cookie</description>
  96 <syntax>CookieExpires <em>expiry-period</em></syntax>
  97 <contextlist>
  98 <context>server config</context>
  99 <context>virtual host</context>
 100 <context>directory</context>
 101 <context>.htaccess</context>
 102 </contextlist>
 103 <override>FileInfo</override>
 104
 105 <usage>
 106     <p>When used, this directive sets an expiry time on the cookie
 107     generated by the usertrack module. The <em>expiry-period</em>
 108     can be given either as a number of seconds, or in the format
 109     such as "2 weeks 3 days 7 hours". Valid denominations are:
 110     years, months, weeks, days, hours, minutes and seconds. If the expiry
 111     time is in any format other than one number indicating the
 112     number of seconds, it must be enclosed by double quotes.</p>
 113
 114     <p>If this directive is not used, cookies last only for the
 115     current browser session.</p>
 116
 117     <highlight language="config">
 118     CookieExpires "3 weeks"
 119     </highlight>
 120 </usage>
 121 </directivesynopsis>
 122
 123 <directivesynopsis>
 124 <name>CookieName</name>
 125 <description>Name of the tracking cookie</description>
 126 <syntax>CookieName <em>token</em></syntax>
 127 <default>CookieName Apache</default>
 128 <contextlist>
 129 <context>server config</context>
 130 <context>virtual host</context>
 131 <context>directory</context>
 132 <context>.htaccess</context>
 133 </contextlist>
 134 <override>FileInfo</override>
 135
 136 <usage>
 137     <p>This directive allows you to change the name of the cookie
 138     this module uses for its tracking purposes. By default the
 139     cookie is named "<code>Apache</code>".</p>
 140
 141     <p>You must specify a valid cookie name; results are
 142     unpredictable if you use a name containing unusual characters.
 143     Valid characters include A-Z, a-z, 0-9, "_", and "-".</p>
 144
 145     <highlight language="config">
 146     CookieName clicktrack
 147     </highlight>
 148 </usage>
 149
 150 </directivesynopsis>
 151
 152 <directivesynopsis>
 153 <name>CookieStyle</name>
 154 <description>Format of the cookie header field</description>
 155 <syntax>CookieStyle
 156     <em>Netscape|Cookie|Cookie2|RFC2109|RFC2965</em></syntax>
 157 <default>CookieStyle Netscape</default>
 158 <contextlist>
 159 <context>server config</context>
 160 <context>virtual host</context>
 161 <context>directory</context>
 162 <context>.htaccess</context>
 163 </contextlist>
 164 <override>FileInfo</override>
 165
 166 <usage>
 167     <p>This directive controls the format of the cookie header
 168     field. The three formats allowed are:</p>
 169
 170     <ul>
 171       <li><strong>Netscape</strong>, which is the original but now deprecated
 172       syntax. This is the default, and the syntax Apache has
 173       historically used.</li>
 174
 175       <li><strong>Cookie</strong> or <strong>RFC2109</strong>, which is the syntax that
 176       superseded the Netscape syntax.</li>
 177
 178       <li><strong>Cookie2</strong> or <strong>RFC2965</strong>, which is the most
 179       current cookie syntax.</li>
 180     </ul>
 181
 182     <p>Not all clients can understand all of these formats, but you
 183     should use the newest one that is generally acceptable to your
 184     users' browsers. At the time of writing, most browsers support all
 185     three of these formats, with <code>Cookie2</code> being the
 186     preferred format.</p>
 187
 188     <highlight language="config">
 189     CookieStyle Cookie2
 190     </highlight>
 191 </usage>
 192 </directivesynopsis>
 193
 194
 195
 196 <directivesynopsis>
 197 <name>CookieTracking</name>
 198 <description>Enables tracking cookie</description>
 199 <syntax>CookieTracking on|off</syntax>
 200 <default>CookieTracking off</default>
 201 <contextlist>
 202 <context>server config</context>
 203 <context>virtual host</context>
 204 <context>directory</context>
 205 <context>.htaccess</context>
 206 </contextlist>
 207 <override>FileInfo</override>
 208
 209 <usage>
 210     <p>When <module>mod_usertrack</module> is loaded, and
 211     <code>CookieTracking on</code> is set, Apache will send a
 212     user-tracking cookie for all new requests. This directive can
 213     be used to turn this behavior on or off on a per-server or
 214     per-directory basis. By default, enabling
 215     <module>mod_usertrack</module> will <strong>not</strong>
 216     activate cookies. </p>
 217
 218     <highlight language="config">
 219     CookieTracking on
 220     </highlight>
 221
 222 </usage>
 223 </directivesynopsis>
 224
 225 </modulesynopsis>