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