mod_session.xml revision a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
c02e0e10f0a74a9855dfebeb82b6aecadc5aa7e1nd<!-- $LastChangedRevision$ -->
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin Licensed to the Apache Software Foundation (ASF) under one or more
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin contributor license agreements. See the NOTICE file distributed with
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin this work for additional information regarding copyright ownership.
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin The ASF licenses this file to You under the Apache License, Version 2.0
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin (the "License"); you may not use this file except in compliance with
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin the License. You may obtain a copy of the License at
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin Unless required by applicable law or agreed to in writing, software
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin distributed under the License is distributed on an "AS IS" BASIS,
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin See the License for the specific language governing permissions and
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin limitations under the License.
7d4ff16d849b1b7cda8b88c60fe6cc94bbe6b09ftakashi<compatibility>Available in Apache 2.3 and later</compatibility>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The session modules make use of HTTP cookies, and as such can fall
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin victim to Cross Site Scripting attacks, or expose potentially private
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin information to clients. Please ensure that the relevant risks have
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin been taken into account before enabling the session functionality on
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin your server.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>This module provides support for a server wide per user session
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin interface. Sessions can be used for keeping track of whether a user
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin has been logged in, or for other per user information that should
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin be kept available across requests.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Sessions may be stored on the server, or may be stored on the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin browser. Sessions may also be optionally encrypted for added security.
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin These features are divided into several modules in addition to
016241a6ee9c7b02ff94f30f90e705012ea08e41jsl <module>mod_session</module>; <module>mod_session_crypto</module>,
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <module>mod_session_cookie</module> and <module>mod_session_dbd</module>.
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin Depending on the server requirements, load the appropriate modules
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin into the server (either statically at compile time or dynamically
016241a6ee9c7b02ff94f30f90e705012ea08e41jsl via the <directive module="mod_so">LoadModule</directive> directive).</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Sessions may be manipulated from other modules that depend on the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin session, or the session may be read from and written to using
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin environment variables and HTTP headers, as appropriate.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<seealso><module>mod_session_cookie</module></seealso>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<seealso><module>mod_session_crypto</module></seealso>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="whatisasession"><title>What is a session?</title>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>At the core of the session interface is a table of key and value pairs
135d3fdd11143f5080be44cf584c33512ed48b50minfrin that are made accessible across browser requests. These pairs can be set
135d3fdd11143f5080be44cf584c33512ed48b50minfrin to any valid string, as needed by the application making use of the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin session.</p>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <p>The "session" is a <strong>application/x-www-form-urlencoded</strong>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin string containing these key value pairs, as defined by the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <a href="http://www.w3.org/TR/html4/">HTML specification</a>.</p>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <p>The session can optionally be encrypted and base64 encoded before
135d3fdd11143f5080be44cf584c33512ed48b50minfrin being written to the storage mechanism, as defined by the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin administrator.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="whocanuseasession"><title>Who can use a session?</title>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The session interface is primarily developed for the use by other
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin server modules, such as <module>mod_auth_form</module>, however CGI
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin based applications can optionally be granted access to the contents
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin of the session via the HTTP_SESSION environment variable. Sessions
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin have the option to be modified and/or updated by inserting an HTTP
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin response header containing the new session parameters.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="serversession"><title>Keeping sessions on the server</title>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Apache can be configured to keep track of per user sessions stored
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin on a particular server or group of servers. This functionality is
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin similar to the sessions available in typical application servers.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>If configured, sessions are tracked through the use of a session ID that
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin is stored inside a cookie, or extracted from the parameters embedded
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin within the URL query string, as found in a typical GET request.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>As the contents of the session are stored exclusively on the server,
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin there is an expectation of privacy of the contents of the session. This
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin does have performance and resource implications should a large number
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin of sessions be present, or where a large number of webservers have to
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin share sessions with one another.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The <module>mod_session_dbd</module> module allows the storage of user
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin sessions within a SQL database via <module>mod_dbd</module>.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="browsersession"><title>Keeping sessions on the browser</title>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <p>In high traffic environments where keeping track of a session on a
135d3fdd11143f5080be44cf584c33512ed48b50minfrin server is too resource intensive or inconvenient, the option exists to store
135d3fdd11143f5080be44cf584c33512ed48b50minfrin the contents of the session within a cookie on the client browser instead.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>This has the advantage that minimal resources are required on the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin server to keep track of sessions, and multiple servers within a server
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin farm have no need to share session information.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The contents of the session however are exposed to the client, with a
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin corresponding risk of a loss of privacy. The
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <module>mod_session_crypto</module> module can be configured to encrypt the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin contents of the session before writing the session to the client.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The <module>mod_session_cookie</module> allows the storage of user
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin sessions on the browser within an HTTP cookie.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="basicexamples"><title>Basic Examples</title>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Creating a session is as simple as turning the session on, and deciding
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin where the session will be stored. In this example, the session will be
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin stored on the browser, in a cookie called <code>session</code>.</p>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCookieName session path=/
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The session is not useful unless it can be written to or read from. The
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin following example shows how values can be injected into the session through
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin the use of a predetermined HTTP response header called
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCookieName session path=/
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionHeader X-Replace-Session
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The header should contain name value pairs expressed in the same format
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin as a query string in a URL, as in the example below. Setting a key to the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin empty string has the effect of removing that key from the session.</p>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohecho "X-Replace-Session: key1=foo&key2=&key3=bar"
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>If configured, the session can be read back from the HTTP_SESSION
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin environment variable. By default, the session is kept private, so this
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin has to be explicitly turned on with the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <directive module="mod_session">SessionEnv</directive> directive.</p>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionEnv On
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCookieName session path=/
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionHeader X-Replace-Session
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Once read, the CGI variable <code>HTTP_SESSION</code> should contain
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="sessionprivacy"><title>Session Privacy</title>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Using the "show cookies" feature of your browser, you would have seen
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin a clear text representation of the session. This could potentially be a
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin problem should the end user need to be kept unaware of the contents of
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin the session, or where a third party could gain unauthorised access to the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin data within the session.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The contents of the session can be optionally encrypted before being
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin placed on the browser using the <module>mod_session_crypto</module>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin module.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <example><title>Browser based encrypted session</title>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCryptoPassphrase secret
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCookieName session path=/
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The session will be automatically decrypted on load, and encrypted on
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin save by Apache, the underlying application using the session need have
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin no knowledge that encryption is taking place.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Sessions stored on the server rather than on the browser can also be
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin encrypted as needed, offering privacy where potentially sensitive
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin information is being shared between webservers in a server farm using
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="cookieprivacy"><title>Cookie Privacy</title>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The HTTP cookie mechanism also offers privacy features, such as the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin ability to restrict cookie transport to SSL protected pages only, or
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin to prevent browser based javascript from gaining access to the contents
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin of the cookie.</p>
1fd5131d5732e639b0b4225ca0afea717c41bc11trawick <p>Some of the HTTP cookie privacy features are either non-standard, or
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin are not implemented consistently across browsers. The session modules
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin allow you to set cookie parameters, but it makes no guarantee that privacy
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin will be respected by the browser. If security is a concern, use the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <module>mod_session_crypto</module> to encrypt the contents of the session,
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin or store the session on the server using the <module>mod_session_dbd</module>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin module.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Standard cookie parameters can be specified after the name of the cookie,
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin as in the example below.</p>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCryptoPassphrase secret
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCookieName session path=/private;domain=example.com;httponly;secure;
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>In cases where the Apache server forms the frontend for backend origin servers,
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin it is possible to have the session cookies removed from the incoming HTTP headers using
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin the <directive module="mod_session_cookie">SessionCookieRemove</directive> directive.
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin This keeps the contents of the session cookies from becoming accessible from the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin backend server.
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <section id="authentication"><title>Session Support for Authentication</title>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>As is possible within many application servers, authentication modules can use
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin a session for storing the username and password after login. The
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <module>mod_auth_form</module> saves the user's login name and password within
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin the session.</p>
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCryptoPassphrase secret
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohSessionCookieName session path=/
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohAuthFormProvider file
ab152dac543de24fadd7ed0159c9f380af02061bhumbedoohAuthType form
3658293f56f1683ca41e3bc5b70d98b203d8004bcoarAuthName "realm"
ab152dac543de24fadd7ed0159c9f380af02061bhumbedooh </highlight>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>See the <module>mod_auth_form</module> module for documentation and complete
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin examples.</p>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <section id="integration"><title>Integrating Sessions with External Applications</title>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <p>In order for sessions to be useful, it must be possible to share the contents
135d3fdd11143f5080be44cf584c33512ed48b50minfrin of a session with external applications, and it must be possible for an
135d3fdd11143f5080be44cf584c33512ed48b50minfrin external application to write a session of its own.</p>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <p> A typical example might be an application that changes a user's password set by
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <module>mod_auth_form</module>. This application would need to read the current
135d3fdd11143f5080be44cf584c33512ed48b50minfrin username and password from the session, make the required changes to the user's
135d3fdd11143f5080be44cf584c33512ed48b50minfrin password, and then write the new password to the session in order to provide a
135d3fdd11143f5080be44cf584c33512ed48b50minfrin seamless transition to the new password.</p>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <p>A second example might involve an application that registers a new user for
135d3fdd11143f5080be44cf584c33512ed48b50minfrin the first time. When registration is complete, the username and password is
135d3fdd11143f5080be44cf584c33512ed48b50minfrin written to the session, providing a seamless transition to being logged in.</p>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <dd>Modules within the server that need access to the session can use the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <strong>mod_session.h</strong> API in order to read from and write to the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin session. This mechanism is used by modules like <module>mod_auth_form</module>.
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <dd>Applications that run within the webserver can optionally retrieve the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin value of the session from the <strong>HTTP_SESSION</strong> environment
135d3fdd11143f5080be44cf584c33512ed48b50minfrin variable. The session should be encoded as a
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <strong>application/x-www-form-urlencoded</strong> string as described by the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <a href="http://www.w3.org/TR/html4/">HTML specification</a>. The environment
135d3fdd11143f5080be44cf584c33512ed48b50minfrin variable is controlled by the setting of the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <directive module="mod_session">SessionEnv</directive> directive. The session
135d3fdd11143f5080be44cf584c33512ed48b50minfrin can be written to by the script by returning a
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <strong>application/x-www-form-urlencoded</strong> response header with a name
135d3fdd11143f5080be44cf584c33512ed48b50minfrin set by the <directive module="mod_session">SessionHeader</directive>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin directive. In both cases, any encryption or decryption, and the reading the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin session from or writing the session to the chosen storage mechanism is handled
135d3fdd11143f5080be44cf584c33512ed48b50minfrin by the <module>mod_session</module> modules and corresponding configuration.
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <dt>Applications behind <module>mod_proxy</module></dt>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <dd>If the <directive module="mod_session">SessionHeader</directive>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin directive is used to define an HTTP request header, the session, encoded as
135d3fdd11143f5080be44cf584c33512ed48b50minfrin a <strong>application/x-www-form-urlencoded</strong> string, will be made
135d3fdd11143f5080be44cf584c33512ed48b50minfrin available to the application. If the same header is provided in the response,
135d3fdd11143f5080be44cf584c33512ed48b50minfrin the value of this response header will be used to replace the session. As
135d3fdd11143f5080be44cf584c33512ed48b50minfrin above, any encryption or decryption, and the reading the session from or
135d3fdd11143f5080be44cf584c33512ed48b50minfrin writing the session to the chosen storage mechanism is handled by the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <module>mod_session</module> modules and corresponding configuration.</dd>
135d3fdd11143f5080be44cf584c33512ed48b50minfrin <dd>Applications might choose to manipulate the session outside the control
135d3fdd11143f5080be44cf584c33512ed48b50minfrin of the Apache HTTP server. In this case, it is the responsibility of the
135d3fdd11143f5080be44cf584c33512ed48b50minfrin application to read the session from the chosen storage mechanism,
135d3fdd11143f5080be44cf584c33512ed48b50minfrin decrypt the session, update the session, encrypt the session and write
135d3fdd11143f5080be44cf584c33512ed48b50minfrin the session to the chosen storage mechanism, as appropriate.</dd>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<description>Enables a session for the current directory or location</description>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</contextlist>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The <directive>Session</directive> directive enables a session for the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin directory or location container. Further directives control where the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin session will be stored and how privacy is maintained.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<description>Define a maximum age in seconds for a session</description>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</contextlist>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The <directive>SessionMaxAge</directive> directive defines a time limit
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin for which a session will remain valid. When a session is saved, this time
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin limit is reset and an existing session can be continued. If a session
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin becomes older than this limit without a request to the server to refresh
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin the session, the session will time out and be removed. Where a session is
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin used to stored user login details, this has the effect of logging the user
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin out automatically after the given time.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Setting the maxage to zero disables session expiry.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<description>Control whether the contents of the session are written to the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<var>HTTP_SESSION</var> environment variable</description>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</contextlist>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>If set to <var>On</var>, the <directive>SessionEnv</directive> directive
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin causes the contents of the session to be written to a CGI environment
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The string is written in the URL query format, for example:</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<description>Import session updates from a given HTTP response header</description>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</contextlist>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The <directive>SessionHeader</directive> directive defines the name of an
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin HTTP response header which, if present, will be parsed and written to the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin current session.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The header value is expected to be in the URL query format, for example:</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>Where a key is set to the empty string, that key will be removed from the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin session.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<description>Define URL prefixes for which a session is valid</description>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</contextlist>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The <directive>SessionInclude</directive> directive allows sessions to
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin be made valid for specific URL prefixes only. This can be used to make a
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin website more efficient, by targeting a more precise URL space for which
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin a session should be maintained. By default, all URLs within the directory
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin or location are included in the session.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>This directive has a similar purpose to the <var>path</var> attribute
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin in HTTP cookies, but should not be confused with this attribute. This
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin directive does not set the <var>path</var> attribute, which must be
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin<description>Define URL prefixes for which a session is ignored</description>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</contextlist>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>The <directive>SessionExclude</directive> directive allows sessions to
016241a6ee9c7b02ff94f30f90e705012ea08e41jsl be disabled relative to URL prefixes only. This can be used to make a
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin website more efficient, by targeting a more precise URL space for which
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin a session should be maintained. By default, all URLs within the directory
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin or location are included in the session. The
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <directive module="mod_session">SessionExclude</directive> directive takes
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin precedence over the
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <directive module="mod_session">SessionInclude</directive> directive.</p>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin <p>This directive has a similar purpose to the <var>path</var> attribute
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin in HTTP cookies, but should not be confused with this attribute. This
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin directive does not set the <var>path</var> attribute, which must be
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</directivesynopsis>
fb8ee8b7a3a2503b95bf47685f9083e0b9834e6fminfrin</modulesynopsis>