granicus.if.org Git - apache/blob - docs/manual/mod/mod_session.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>mod_session - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body>
  17 <div id="page-header">
  18 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  19 <p class="apache">Apache HTTP Server Version 2.5</p>
  20 <img alt="" src="../images/feather.gif" /></div>
  21 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  22 <div id="path">
  23 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  24 <div id="page-content">
  25 <div id="preamble"><h1>Apache Module mod_session</h1>
  26 <div class="toplang">
  27 <p><span>Available Languages: </span><a href="../en/mod/mod_session.html" title="English">&nbsp;en&nbsp;</a></p>
  28 </div>
  29 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Session support</td></tr>
  30 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  31 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>session_module</td></tr>
  32 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_session.c</td></tr>
  33 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table>
  34 <h3>Summary</h3>
  35
  36     <div class="warning"><h3>Warning</h3>
  37       <p>The session modules make use of HTTP cookies, and as such can fall
  38       victim to Cross Site Scripting attacks, or expose potentially private
  39       information to clients. Please ensure that the relevant risks have
  40       been taken into account before enabling the session functionality on
  41       your server.</p>
  42     </div>
  43
  44     <p>This module provides support for a server wide per user session
  45     interface. Sessions can be used for keeping track of whether a user
  46     has been logged in, or for other per user information that should
  47     be kept available across requests.</p>
  48
  49     <p>Sessions may be stored on the server, or may be stored on the
  50     browser. Sessions may also be optionally encrypted for added security.
  51     These features are divided into several modules in addition to
  52     <code class="module"><a href="../mod/mod_session.html">mod_session</a></code>; <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code>,
  53     <code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code> and <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code>.
  54     Depending on the server requirements, load the appropriate modules
  55     into the server (either statically at compile time or dynamically
  56     via the <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code> directive).</p>
  57
  58     <p>Sessions may be manipulated from other modules that depend on the
  59     session, or the session may be read from and written to using
  60     environment variables and HTTP headers, as appropriate.</p>
  61
  62 </div>
  63 <div id="quickview"><h3 class="directives">Directives</h3>
  64 <ul id="toc">
  65 <li><img alt="" src="../images/down.gif" /> <a href="#session">Session</a></li>
  66 <li><img alt="" src="../images/down.gif" /> <a href="#sessionenv">SessionEnv</a></li>
  67 <li><img alt="" src="../images/down.gif" /> <a href="#sessionexclude">SessionExclude</a></li>
  68 <li><img alt="" src="../images/down.gif" /> <a href="#sessionheader">SessionHeader</a></li>
  69 <li><img alt="" src="../images/down.gif" /> <a href="#sessioninclude">SessionInclude</a></li>
  70 <li><img alt="" src="../images/down.gif" /> <a href="#sessionmaxage">SessionMaxAge</a></li>
  71 </ul>
  72 <h3>Topics</h3>
  73 <ul id="topics">
  74 <li><img alt="" src="../images/down.gif" /> <a href="#whatisasession">What is a session?</a></li>
  75 <li><img alt="" src="../images/down.gif" /> <a href="#whocanuseasession">Who can use a session?</a></li>
  76 <li><img alt="" src="../images/down.gif" /> <a href="#serversession">Keeping sessions on the server</a></li>
  77 <li><img alt="" src="../images/down.gif" /> <a href="#browsersession">Keeping sessions on the browser</a></li>
  78 <li><img alt="" src="../images/down.gif" /> <a href="#basicexamples">Basic Examples</a></li>
  79 <li><img alt="" src="../images/down.gif" /> <a href="#sessionprivacy">Session Privacy</a></li>
  80 <li><img alt="" src="../images/down.gif" /> <a href="#cookieprivacy">Cookie Privacy</a></li>
  81 <li><img alt="" src="../images/down.gif" /> <a href="#authentication">Session Support for Authentication</a></li>
  82 <li><img alt="" src="../images/down.gif" /> <a href="#integration">Integrating Sessions with External Applications</a></li>
  83 </ul><h3>See also</h3>
  84 <ul class="seealso">
  85 <li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
  86 <li><code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code></li>
  87 <li><code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
  88 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  89 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  90 <div class="section">
  91 <h2><a name="whatisasession" id="whatisasession">What is a session?</a></h2>
  92       <p>At the core of the session interface is a table of key and value pairs
  93       that are made accessible across browser requests. These pairs can be set
  94       to any valid string, as needed by the application making use of the
  95       session.</p>
  96
  97       <p>The "session" is a <strong>application/x-www-form-urlencoded</strong>
  98       string containing these key value pairs, as defined by the
  99       <a href="http://www.w3.org/TR/html4/">HTML specification</a>.</p>
 100
 101       <p>The session can optionally be encrypted and base64 encoded before
 102       being written to the storage mechanism, as defined by the
 103       administrator.</p>
 104
 105     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 106 <div class="section">
 107 <h2><a name="whocanuseasession" id="whocanuseasession">Who can use a session?</a></h2>
 108       <p>The session interface is primarily developed for the use by other
 109       server modules, such as <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>, however CGI
 110       based applications can optionally be granted access to the contents
 111       of the session via the HTTP_SESSION environment variable. Sessions
 112       have the option to be modified and/or updated by inserting an HTTP
 113       response header containing the new session parameters.</p>
 114
 115     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 116 <div class="section">
 117 <h2><a name="serversession" id="serversession">Keeping sessions on the server</a></h2>
 118       <p>Apache can be configured to keep track of per user sessions stored
 119       on a particular server or group of servers. This functionality is
 120       similar to the sessions available in typical application servers.</p>
 121
 122       <p>If configured, sessions are tracked through the use of a session ID that
 123       is stored inside a cookie, or extracted from the parameters embedded
 124       within the URL query string, as found in a typical GET request.</p>
 125
 126       <p>As the contents of the session are stored exclusively on the server,
 127       there is an expectation of privacy of the contents of the session. This
 128       does have performance and resource implications should a large number
 129       of sessions be present, or where a large number of webservers have to
 130       share sessions with one another.</p>
 131
 132       <p>The <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module allows the storage of user
 133       sessions within a SQL database via <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>.</p>
 134
 135     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 136 <div class="section">
 137 <h2><a name="browsersession" id="browsersession">Keeping sessions on the browser</a></h2>
 138       <p>In high traffic environments where keeping track of a session on a
 139       server is too resource intensive or inconvenient, the option exists to store
 140       the contents of the session within a cookie on the client browser instead.</p>
 141
 142       <p>This has the advantage that minimal resources are required on the
 143       server to keep track of sessions, and multiple servers within a server
 144       farm have no need to share session information.</p>
 145
 146       <p>The contents of the session however are exposed to the client, with a
 147       corresponding risk of a loss of privacy. The
 148       <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code> module can be configured to encrypt the
 149       contents of the session before writing the session to the client.</p>
 150
 151       <p>The <code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code> allows the storage of user
 152       sessions on the browser within an HTTP cookie.</p>
 153
 154     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 155 <div class="section">
 156 <h2><a name="basicexamples" id="basicexamples">Basic Examples</a></h2>
 157
 158       <p>Creating a session is as simple as turning the session on, and deciding
 159       where the session will be stored. In this example, the session will be
 160       stored on the browser, in a cookie called <code>session</code>.</p>
 161
 162       <div class="example"><h3>Browser based session</h3><pre class="prettyprint lang-config">
 163 Session On
 164 SessionCookieName session path=/
 165         </pre>
 166 </div>
 167
 168       <p>The session is not useful unless it can be written to or read from. The
 169       following example shows how values can be injected into the session through
 170       the use of a predetermined HTTP response header called
 171       <code>X-Replace-Session</code>.</p>
 172
 173       <div class="example"><h3>Writing to a session</h3><pre class="prettyprint lang-config">
 174 Session On
 175 SessionCookieName session path=/
 176 SessionHeader X-Replace-Session
 177         </pre>
 178 </div>
 179
 180       <p>The header should contain name value pairs expressed in the same format
 181       as a query string in a URL, as in the example below. Setting a key to the
 182       empty string has the effect of removing that key from the session.</p>
 183
 184       <div class="example"><h3>CGI to write to a session</h3><pre class="prettyprint lang-sh">
 185 #!/bin/bash
 186 echo "Content-Type: text/plain"
 187 echo "X-Replace-Session: key1=foo&amp;key2=&amp;key3=bar"
 188 echo
 189 env
 190         </pre>
 191 </div>
 192
 193       <p>If configured, the session can be read back from the HTTP_SESSION
 194       environment variable. By default, the session is kept private, so this
 195       has to be explicitly turned on with the
 196       <code class="directive"><a href="#sessionenv">SessionEnv</a></code> directive.</p>
 197
 198       <div class="example"><h3>Read from a session</h3><pre class="prettyprint lang-config">
 199 Session On
 200 SessionEnv On
 201 SessionCookieName session path=/
 202 SessionHeader X-Replace-Session
 203         </pre>
 204 </div>
 205
 206       <p>Once read, the CGI variable <code>HTTP_SESSION</code> should contain
 207       the value <code>key1=foo&amp;key3=bar</code>.</p>
 208
 209     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 210 <div class="section">
 211 <h2><a name="sessionprivacy" id="sessionprivacy">Session Privacy</a></h2>
 212
 213       <p>Using the "show cookies" feature of your browser, you would have seen
 214       a clear text representation of the session. This could potentially be a
 215       problem should the end user need to be kept unaware of the contents of
 216       the session, or where a third party could gain unauthorised access to the
 217       data within the session.</p>
 218
 219       <p>The contents of the session can be optionally encrypted before being
 220       placed on the browser using the <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code>
 221       module.</p>
 222
 223       <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">
 224 Session On
 225 SessionCryptoPassphrase secret
 226 SessionCookieName session path=/
 227         </pre>
 228 </div>
 229
 230       <p>The session will be automatically decrypted on load, and encrypted on
 231       save by Apache, the underlying application using the session need have
 232       no knowledge that encryption is taking place.</p>
 233
 234       <p>Sessions stored on the server rather than on the browser can also be
 235       encrypted as needed, offering privacy where potentially sensitive
 236       information is being shared between webservers in a server farm using
 237       the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module.</p>
 238
 239     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 240 <div class="section">
 241 <h2><a name="cookieprivacy" id="cookieprivacy">Cookie Privacy</a></h2>
 242
 243       <p>The HTTP cookie mechanism also offers privacy features, such as the
 244       ability to restrict cookie transport to SSL protected pages only, or
 245       to prevent browser based javascript from gaining access to the contents
 246       of the cookie.</p>
 247
 248       <div class="warning"><h3>Warning</h3>
 249       <p>Some of the HTTP cookie privacy features are either non-standard, or
 250       are not implemented consistently across browsers. The session modules
 251       allow you to set cookie parameters, but it makes no guarantee that privacy
 252       will be respected by the browser. If security is a concern, use the
 253       <code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code> to encrypt the contents of the session,
 254       or store the session on the server using the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code>
 255       module.</p>
 256       </div>
 257
 258       <p>Standard cookie parameters can be specified after the name of the cookie,
 259       as in the example below.</p>
 260
 261       <div class="example"><h3>Setting cookie parameters</h3><pre class="prettyprint lang-config">
 262 Session On
 263 SessionCryptoPassphrase secret
 264 SessionCookieName session path=/private;domain=example.com;httponly;secure;
 265         </pre>
 266 </div>
 267
 268       <p>In cases where the Apache server forms the frontend for backend origin servers,
 269       it is possible to have the session cookies removed from the incoming HTTP headers using
 270       the <code class="directive"><a href="../mod/mod_session_cookie.html#sessioncookieremove">SessionCookieRemove</a></code> directive.
 271       This keeps the contents of the session cookies from becoming accessible from the
 272       backend server.
 273       </p>
 274
 275     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 276 <div class="section">
 277 <h2><a name="authentication" id="authentication">Session Support for Authentication</a></h2>
 278
 279       <p>As is possible within many application servers, authentication modules can use
 280       a session for storing the username and password after login. The
 281       <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> saves the user's login name and password within
 282       the session.</p>
 283
 284       <div class="example"><h3>Form based authentication</h3><pre class="prettyprint lang-config">
 285 Session On
 286 SessionCryptoPassphrase secret
 287 SessionCookieName session path=/
 288 AuthFormProvider file
 289 AuthUserFile conf/passwd
 290 AuthType form
 291 AuthName realm
 292 #...
 293         </pre>
 294 </div>
 295
 296       <p>See the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module for documentation and complete
 297       examples.</p>
 298
 299     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 300 <div class="section">
 301 <h2><a name="integration" id="integration">Integrating Sessions with External Applications</a></h2>
 302
 303       <p>In order for sessions to be useful, it must be possible to share the contents
 304       of a session with external applications, and it must be possible for an
 305       external application to write a session of its own.</p>
 306
 307       <p> A typical example might be an application that changes a user's password set by
 308       <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>. This application would need to read the current
 309       username and password from the session, make the required changes to the user's
 310       password, and then write the new password to the session in order to provide a
 311       seamless transition to the new password.</p>
 312
 313       <p>A second example might involve an application that registers a new user for
 314       the first time. When registration is complete, the username and password is
 315       written to the session, providing a seamless transition to being logged in.</p>
 316
 317       <dl>
 318       <dt>Apache modules</dt>
 319       <dd>Modules within the server that need access to the session can use the
 320       <strong>mod_session.h</strong> API in order to read from and write to the
 321       session. This mechanism is used by modules like <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>.
 322       </dd>
 323
 324       <dt>CGI programs and scripting languages</dt>
 325       <dd>Applications that run within the webserver can optionally retrieve the
 326       value of the session from the <strong>HTTP_SESSION</strong> environment
 327       variable. The session should be encoded as a
 328       <strong>application/x-www-form-urlencoded</strong> string as described by the
 329       <a href="http://www.w3.org/TR/html4/">HTML specification</a>. The environment
 330       variable is controlled by the setting of the
 331       <code class="directive"><a href="#sessionenv">SessionEnv</a></code> directive. The session
 332       can be written to by the script by returning a
 333       <strong>application/x-www-form-urlencoded</strong> response header with a name
 334       set by the <code class="directive"><a href="#sessionheader">SessionHeader</a></code>
 335       directive. In both cases, any encryption or decryption, and the reading the
 336       session from or writing the session to the chosen storage mechanism is handled
 337       by the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> modules and corresponding configuration.
 338       </dd>
 339
 340       <dt>Applications behind <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dt>
 341       <dd>If the <code class="directive"><a href="#sessionheader">SessionHeader</a></code>
 342       directive is used to define an HTTP request header, the session, encoded as
 343       a <strong>application/x-www-form-urlencoded</strong> string, will be made
 344       available to the application. If the same header is provided in the response,
 345       the value of this response header will be used to replace the session. As
 346       above, any encryption or decryption, and the reading the session from or
 347       writing the session to the chosen storage mechanism is handled by the
 348       <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> modules and corresponding configuration.</dd>
 349
 350       <dt>Standalone applications</dt>
 351       <dd>Applications might choose to manipulate the session outside the control
 352       of the Apache HTTP server. In this case, it is the responsibility of the
 353       application to read the session from the chosen storage mechanism,
 354       decrypt the session, update the session, encrypt the session and write
 355       the session to the chosen storage mechanism, as appropriate.</dd>
 356       </dl>
 357
 358     </div>
 359 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 360 <div class="directive-section"><h2><a name="Session" id="Session">Session</a> <a name="session" id="session">Directive</a></h2>
 361 <table class="directive">
 362 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables a session for the current directory or location</td></tr>
 363 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Session On|Off</code></td></tr>
 364 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Session Off</code></td></tr>
 365 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 366 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 367 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 368 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
 369 </table>
 370     <p>The <code class="directive">Session</code> directive enables a session for the
 371     directory or location container. Further directives control where the
 372     session will be stored and how privacy is maintained.</p>
 373
 374 </div>
 375 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 376 <div class="directive-section"><h2><a name="SessionEnv" id="SessionEnv">SessionEnv</a> <a name="sessionenv" id="sessionenv">Directive</a></h2>
 377 <table class="directive">
 378 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Control whether the contents of the session are written to the
 379 <var>HTTP_SESSION</var> environment variable</td></tr>
 380 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionEnv On|Off</code></td></tr>
 381 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionEnv Off</code></td></tr>
 382 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 383 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 384 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 385 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
 386 </table>
 387     <p>If set to <var>On</var>, the <code class="directive">SessionEnv</code> directive
 388     causes the contents of the session to be written to a CGI environment
 389     variable called <var>HTTP_SESSION</var>.</p>
 390
 391     <p>The string is written in the URL query format, for example:</p>
 392
 393     <div class="example"><p><code>
 394       <code>key1=foo&amp;key3=bar</code>
 395     </code></p></div>
 396
 397
 398 </div>
 399 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 400 <div class="directive-section"><h2><a name="SessionExclude" id="SessionExclude">SessionExclude</a> <a name="sessionexclude" id="sessionexclude">Directive</a></h2>
 401 <table class="directive">
 402 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is ignored</td></tr>
 403 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionExclude <var>path</var></code></td></tr>
 404 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 405 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 406 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 407 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
 408 </table>
 409     <p>The <code class="directive">SessionExclude</code> directive allows sessions to
 410     be disabled relative to URL prefixes only. This can be used to make a
 411     website more efficient, by targeting a more precise URL space for which
 412     a session should be maintained. By default, all URLs within the directory
 413     or location are included in the session. The
 414     <code class="directive"><a href="#sessionexclude">SessionExclude</a></code> directive takes
 415     precedence over the
 416     <code class="directive"><a href="#sessioninclude">SessionInclude</a></code> directive.</p>
 417
 418     <div class="warning"><h3>Warning</h3>
 419     <p>This directive has a similar purpose to the <var>path</var> attribute
 420     in HTTP cookies, but should not be confused with this attribute. This
 421     directive does not set the <var>path</var> attribute, which must be
 422     configured separately.</p></div>
 423
 424 </div>
 425 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 426 <div class="directive-section"><h2><a name="SessionHeader" id="SessionHeader">SessionHeader</a> <a name="sessionheader" id="sessionheader">Directive</a></h2>
 427 <table class="directive">
 428 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Import session updates from a given HTTP response header</td></tr>
 429 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionHeader <var>header</var></code></td></tr>
 430 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
 431 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 432 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 433 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 434 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
 435 </table>
 436     <p>The <code class="directive">SessionHeader</code> directive defines the name of an
 437     HTTP response header which, if present, will be parsed and written to the
 438     current session.</p>
 439
 440     <p>The header value is expected to be in the URL query format, for example:</p>
 441
 442     <div class="example"><p><code>
 443       <code>key1=foo&amp;key2=&amp;key3=bar</code>
 444     </code></p></div>
 445
 446     <p>Where a key is set to the empty string, that key will be removed from the
 447     session.</p>
 448
 449
 450 </div>
 451 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 452 <div class="directive-section"><h2><a name="SessionInclude" id="SessionInclude">SessionInclude</a> <a name="sessioninclude" id="sessioninclude">Directive</a></h2>
 453 <table class="directive">
 454 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define URL prefixes for which a session is valid</td></tr>
 455 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionInclude <var>path</var></code></td></tr>
 456 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>all URLs</code></td></tr>
 457 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 458 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 459 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 460 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
 461 </table>
 462     <p>The <code class="directive">SessionInclude</code> directive allows sessions to
 463     be made valid for specific URL prefixes only. This can be used to make a
 464     website more efficient, by targeting a more precise URL space for which
 465     a session should be maintained. By default, all URLs within the directory
 466     or location are included in the session.</p>
 467
 468     <div class="warning"><h3>Warning</h3>
 469     <p>This directive has a similar purpose to the <var>path</var> attribute
 470     in HTTP cookies, but should not be confused with this attribute. This
 471     directive does not set the <var>path</var> attribute, which must be
 472     configured separately.</p></div>
 473
 474 </div>
 475 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 476 <div class="directive-section"><h2><a name="SessionMaxAge" id="SessionMaxAge">SessionMaxAge</a> <a name="sessionmaxage" id="sessionmaxage">Directive</a></h2>
 477 <table class="directive">
 478 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define a maximum age in seconds for a session</td></tr>
 479 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionMaxAge <var>maxage</var></code></td></tr>
 480 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionMaxAge 0</code></td></tr>
 481 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 482 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
 483 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 484 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session</td></tr>
 485 </table>
 486     <p>The <code class="directive">SessionMaxAge</code> directive defines a time limit
 487     for which a session will remain valid. When a session is saved, this time
 488     limit is reset and an existing session can be continued. If a session
 489     becomes older than this limit without a request to the server to refresh
 490     the session, the session will time out and be removed. Where a session is
 491     used to stored user login details, this has the effect of logging the user
 492     out automatically after the given time.</p>
 493
 494     <p>Setting the maxage to zero disables session expiry.</p>
 495
 496 </div>
 497 </div>
 498 <div class="bottomlang">
 499 <p><span>Available Languages: </span><a href="../en/mod/mod_session.html" title="English">&nbsp;en&nbsp;</a></p>
 500 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 501 <script type="text/javascript"><!--//--><![CDATA[//><!--
 502 var comments_shortname = 'httpd';
 503 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_session.html';
 504 (function(w, d) {
 505     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 506         d.write('<div id="comments_thread"><\/div>');
 507         var s = d.createElement('script');
 508         s.type = 'text/javascript';
 509         s.async = true;
 510         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 511         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 512     }
 513     else {
 514         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 515     }
 516 })(window, document);
 517 //--><!]]></script></div><div id="footer">
 518 <p class="apache">Copyright 2013 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 519 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 520 if (typeof(prettyPrint) !== 'undefined') {
 521     prettyPrint();
 522 }
 523 //--><!]]></script>
 524 </body></html>