2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_session.xml.meta">
25 <name>mod_session</name>
26 <description>Session support</description>
27 <status>Extension</status>
28 <sourcefile>mod_session.c</sourcefile>
29 <identifier>session_module</identifier>
30 <compatibility>Available in Apache 2.3 and later</compatibility>
33 <note type="warning"><title>Warning</title>
34 <p>The session modules make use of HTTP cookies, and as such can fall
35 victim to Cross Site Scripting attacks, or expose potentially private
36 information to clients. Please ensure that the relevant risks have
37 been taken into account before enabling the session functionality on
41 <p>This module provides support for a server wide per user session
42 interface. Sessions can be used for keeping track of whether a user
43 has been logged in, or for other per user information that should
44 be kept available across requests.</p>
46 <p>Sessions may be stored on the server, or may be stored on the
47 browser. Sessions may also be optionally encrypted for added security.
48 These features are divided into several modules in addition to
49 <module>mod_session</module>; <module>mod_session_crypto</module>,
50 <module>mod_session_cookie</module> and <module>mod_session_dbd</module>.
51 Depending on the server requirements, load the appropriate modules
52 into the server (either statically at compile time or dynamically
53 via the <directive module="mod_so">LoadModule</directive> directive).</p>
55 <p>Sessions may be manipulated from other modules that depend on the
56 session, or the session may be read from and written to using
57 environment variables and HTTP headers, as appropriate.</p>
60 <seealso><module>mod_session_cookie</module></seealso>
61 <seealso><module>mod_session_crypto</module></seealso>
62 <seealso><module>mod_session_dbd</module></seealso>
64 <section id="whatisasession"><title>What is a session?</title>
65 <p>At the core of the session interface is a table of key and value pairs
66 that are made accessible across browser requests.</p>
68 <p>These pairs can be set to any valid string, as needed by the
69 application making use of the session.</p>
72 <section id="whocanuseasession"><title>Who can use a session?</title>
73 <p>The session interface is primarily developed for the use by other
74 server modules, such as <module>mod_auth_form</module>, however CGI
75 based applications can optionally be granted access to the contents
76 of the session via the HTTP_SESSION environment variable. Sessions
77 have the option to be modified and/or updated by inserting an HTTP
78 response header containing the new session parameters.</p>
81 <section id="serversession"><title>Keeping sessions on the server</title>
82 <p>Apache can be configured to keep track of per user sessions stored
83 on a particular server or group of servers. This functionality is
84 similar to the sessions available in typical application servers.</p>
86 <p>If configured, sessions are tracked through the use of a session ID that
87 is stored inside a cookie, or extracted from the parameters embedded
88 within the URL query string, as found in a typical GET request.</p>
90 <p>As the contents of the session are stored exclusively on the server,
91 there is an expectation of privacy of the contents of the session. This
92 does have performance and resource implications should a large number
93 of sessions be present, or where a large number of webservers have to
94 share sessions with one another.</p>
96 <p>The <module>mod_session_dbd</module> module allows the storage of user
97 sessions within a SQL database via <module>mod_dbd</module>.</p>
99 </section> <!-- /serversession -->
101 <section id="browsersession"><title>Keeping sessions on the browser</title>
102 <p>Where keeping track of a session on a server is too resource
103 intensive or inconvenient, the option exists to store the contents
104 of the session within a cookie on the client browser instead.</p>
106 <p>This has the advantage that minimal resources are required on the
107 server to keep track of sessions, and multiple servers within a server
108 farm have no need to share session information.</p>
110 <p>The contents of the session however are exposed to the client, with a
111 corresponding risk of a loss of privacy. The
112 <module>mod_session_crypto</module> module can be configured to encrypt the
113 contents of the session before writing the session to the client.</p>
115 <p>The <module>mod_session_cookie</module> allows the storage of user
116 sessions on the browser within an HTTP cookie.</p>
118 </section> <!-- /browsersession -->
120 <section id="basicexamples"><title>Basic Examples</title>
122 <p>Creating a session is as simple as turning the session on, and deciding
123 where the session will be stored. In this example, the session will be
124 stored on the browser, in a cookie called <code>session</code>.</p>
126 <example><title>Browser based session</title>
128 SessionCookieName session path=/<br />
131 <p>The session is not useful unless it can be written to or read from. The
132 following example shows how values can be injected into the session through
133 the use of a predetermined HTTP response header called
134 <code>X-Replace-Session</code>.</p>
136 <example><title>Writing to a session</title>
138 SessionCookieName session path=/<br />
139 SessionHeader X-Replace-Session<br />
142 <p>The header should contain name value pairs expressed in the same format
143 as a query string in a URL, as in the example below. Setting a key to the
144 empty string has the effect of removing that key from the session.</p>
146 <example><title>CGI to write to a session</title>
148 echo "Content-Type: text/plain"<br />
149 echo "X-Replace-Session: key1=foo&key2=&key3=bar"<br />
154 <p>If configured, the session can be read back from the HTTP_SESSION
155 environment variable. By default, the session is kept private, so this
156 has to be explicitly turned on with the
157 <directive module="mod_session">SessionEnv</directive> directive.</p>
159 <example><title>Read from a session</title>
162 SessionCookieName session path=/<br />
163 SessionHeader X-Replace-Session<br />
166 <p>Once read, the CGI variable <code>HTTP_SESSION</code> should contain
167 the value <code>key1=foo&key3=bar</code>.</p>
170 <section id="sessionprivacy"><title>Session Privacy</title>
172 <p>Using the "show cookies" feature of your browser, you would have seen
173 a clear text representation of the session. This could potentially be a
174 problem should the end user need to be kept unaware of the contents of
175 the session, or where a third party could gain unauthorised access to the
176 data within the session.</p>
178 <p>The contents of the session can be optionally encrypted before being
179 placed on the browser using the <module>mod_session_crypto</module>
182 <example><title>Browser based encrypted session</title>
184 SessionCryptoPassphrase secret<br />
185 SessionCookieName session path=/<br />
188 <p>The session will be automatically decrypted on load, and encrypted on
189 save by Apache, the underlying application using the session need have
190 no knowledge that encryption is taking place.</p>
192 <p>Sessions stored on the server rather than on the browser can also be
193 encrypted as needed, offering privacy where potentially sensitive
194 information is being shared between webservers in a server farm using
195 the <module>mod_session_dbd</module> module.</p>
198 <section id="cookieprivacy"><title>Cookie Privacy</title>
200 <p>The HTTP cookie mechanism also offers privacy features, such as the
201 ability to restrict cookie transport to SSL protected pages only, or
202 to prevent browser based javascript from gaining access to the contents
205 <note type="warning"><title>Warning</title>
206 <p>Some of the HTTP cookie privacy features are either non-standard, or
207 are not implemented consistently across browsers. The session modules
208 allow you to set cookie parameters, but it makes no guarantee that privacy
209 will be respected by the browser. If security is a concern, use the
210 <module>mod_session_crypto</module> to encrypt the contents of the session,
211 or store the session on the server using the <module>mod_session_dbd</module>
215 <p>Standard cookie parameters can be specified after the name of the cookie,
216 as in the example below.</p>
218 <example><title>Setting cookie parameters</title>
220 SessionCryptoPassphrase secret<br />
221 SessionCookieName session path=/private;domain=example.com;httponly;secure;<br />
224 <p>In cases where the Apache server forms the frontend for backend origin servers,
225 it is possible to have the session cookies removed from the incoming HTTP headers using
226 the <directive module="mod_session_cookie">SessionCookieRemove</directive> directive.
227 This keeps the contents of the session cookies from becoming accessible from the
232 <section id="authentication"><title>Session Support for Authentication</title>
234 <p>As is possible within many application servers, authentication modules can use
235 a session for storing the username and password after login. The
236 <module>mod_auth_form</module> saves the user's login name and password within
239 <example><title>Form based authentication</title>
241 SessionCryptoPassphrase secret<br />
242 SessionCookieName session path=/<br />
243 AuthFormProvider file<br />
244 AuthUserFile conf/passwd<br />
250 <p>See the <module>mod_auth_form</module> module for documentation and complete
257 <description>Enables a session for the current directory or location</description>
258 <syntax>Session On|Off</syntax>
259 <default>Session Off</default>
260 <contextlist><context>server config</context>
261 <context>virtual host</context>
262 <context>directory</context>
263 <context>.htaccess</context>
267 <p>The <directive>Session</directive> directive enables a session for the
268 directory or location container. Further directives control where the
269 session will be stored and how privacy is maintained.</p>
274 <name>SessionMaxAge</name>
275 <description>Define a maximum age in seconds for a session</description>
276 <syntax>SessionMaxAge <var>maxage</var></syntax>
277 <default>SessionMaxAge 0</default>
278 <contextlist><context>server config</context>
279 <context>virtual host</context>
280 <context>directory</context>
281 <context>.htaccess</context>
285 <p>The <directive>SessionMaxAge</directive> directive defines a time limit
286 for which a session will remain valid. When a session is saved, this time
287 limit is reset and an existing session can be continued. If a session
288 becomes older than this limit without a request to the server to refresh
289 the session, the session will time out and be removed. Where a session is
290 used to stored user login details, this has the effect of logging the user
291 out automatically after the given time.</p>
293 <p>Setting the maxage to zero disables session expiry.</p>
298 <name>SessionEnv</name>
299 <description>Control whether the contents of the session are written to the
300 <var>HTTP_SESSION</var> environment variable</description>
301 <syntax>SessionEnv On|Off</syntax>
302 <default>SessionEnv Off</default>
303 <contextlist><context>server config</context>
304 <context>virtual host</context>
305 <context>directory</context>
306 <context>.htaccess</context>
310 <p>If set to <var>On</var>, the <directive>SessionEnv</directive> directive
311 causes the contents of the session to be written to a CGI environment
312 variable called <var>HTTP_SESSION</var>.</p>
314 <p>The string is written in the URL query format, for example:</p>
317 <code>key1=foo&key3=bar</code>
324 <name>SessionHeader</name>
325 <description>Import session updates from a given HTTP response header</description>
326 <syntax>SessionHeader <var>header</var></syntax>
327 <default>none</default>
328 <contextlist><context>server config</context>
329 <context>virtual host</context>
330 <context>directory</context>
331 <context>.htaccess</context>
335 <p>The <directive>SessionHeader</directive> directive defines the name of an
336 HTTP response header which, if present, will be parsed and written to the
339 <p>The header value is expected to be in the URL query format, for example:</p>
342 <code>key1=foo&key2=&key3=bar</code>
345 <p>Where a key is set to the empty string, that key will be removed from the
352 <name>SessionInclude</name>
353 <description>Define URL prefixes for which a session is valid</description>
354 <syntax>SessionInclude <var>path</var></syntax>
355 <default>all URLs</default>
356 <contextlist><context>server config</context>
357 <context>virtual host</context>
358 <context>directory</context>
359 <context>.htaccess</context>
363 <p>The <directive>SessionInclude</directive> directive allows sessions to
364 be made valid for specific URL prefixes only. This can be used to make a
365 website more efficient, by targeting a more precise URL space for which
366 a session should be maintained. By default, all URLs within the directory
367 or location are included in the session.</p>
369 <note type="warning"><title>Warning</title>
370 <p>This directive has a similar purpose to the <var>path</var> attribute
371 in HTTP cookies, but should not be confused with this attribute. This
372 directive does not set the <var>path</var> attribute, which must be
373 configured separately.</p></note>
378 <name>SessionExclude</name>
379 <description>Define URL prefixes for which a session is ignored</description>
380 <syntax>SessionExclude <var>path</var></syntax>
381 <default>none</default>
382 <contextlist><context>server config</context>
383 <context>virtual host</context>
384 <context>directory</context>
385 <context>.htaccess</context>
389 <p>The <directive>SessionExclude</directive> directive allows sessions to
390 be disabled relative to URL prefixes only. This can be used to make a
391 website more efficient, by targeting a more precise URL space for which
392 a session should be maintained. By default, all URLs within the directory
393 or location are included in the session. The
394 <directive module="mod_session">SessionExclude</directive> directive takes
396 <directive module="mod_session">SessionInclude</directive> directive.</p>
398 <note type="warning"><title>Warning</title>
399 <p>This directive has a similar purpose to the <var>path</var> attribute
400 in HTTP cookies, but should not be confused with this attribute. This
401 directive does not set the <var>path</var> attribute, which must be
402 configured separately.</p></note>