]> granicus.if.org Git - apache/blob - docs/manual/mod/mod_session_dbd.html.en
Update docco xforms
[apache] / docs / manual / mod / mod_session_dbd.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_dbd - 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" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
13 <body>
14 <div id="page-header">
15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
16 <p class="apache">Apache HTTP Server Version 2.3</p>
17 <img alt="" src="../images/feather.gif" /></div>
18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
19 <div id="path">
20 <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.3</a> &gt; <a href="./">Modules</a></div>
21 <div id="page-content">
22 <div id="preamble"><h1>Apache Module mod_session_dbd</h1>
23 <div class="toplang">
24 <p><span>Available Languages: </span><a href="../en/mod/mod_session_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
25 </div>
26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>DBD/SQL based session support</td></tr>
27 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
28 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>session_dbd_module</td></tr>
29 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_session_dbd.c</td></tr>
30 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table>
31 <h3>Summary</h3>
32
33     <div class="warning"><h3>Warning</h3>
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
38       your server.</p>
39     </div>
40
41     <p>This submodule of <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> provides support for the
42     storage of user sessions within a SQL database using the
43     <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> module.</p>
44
45     <p>Sessions can either be <strong>anonymous</strong>, where the session is
46     keyed by a unique UUID string stored on the browser in a cookie, or
47     <strong>per user</strong>, where the session is keyed against the userid of
48     the logged in user.</p>
49
50     <p>SQL based sessions are hidden from the browser, and so offer a measure of
51     privacy without the need for encryption.</p>
52     
53     <p>Different webservers within a server farm may choose to share a database,
54     and so share sessions with one another.</p>
55     
56     <p>For more details on the session interface, see the documentation for
57     the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> module.</p>
58     
59 </div>
60 <div id="quickview"><h3 class="directives">Directives</h3>
61 <ul id="toc">
62 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdcookiename">SessionDBDCookieName</a></li>
63 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdcookiename2">SessionDBDCookieName2</a></li>
64 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdcookieremove">SessionDBDCookieRemove</a></li>
65 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbddeletelabel">SessionDBDDeleteLabel</a></li>
66 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdinsertlabel">SessionDBDInsertLabel</a></li>
67 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdperuser">SessionDBDPerUser</a></li>
68 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdselectlabel">SessionDBDSelectLabel</a></li>
69 <li><img alt="" src="../images/down.gif" /> <a href="#sessiondbdupdatelabel">SessionDBDUpdateLabel</a></li>
70 </ul>
71 <h3>Topics</h3>
72 <ul id="topics">
73 <li><img alt="" src="../images/down.gif" /> <a href="#dbdconfig">DBD Configuration</a></li>
74 <li><img alt="" src="../images/down.gif" /> <a href="#anonymous">Anonymous Sessions</a></li>
75 <li><img alt="" src="../images/down.gif" /> <a href="#peruser">Per User Sessions</a></li>
76 <li><img alt="" src="../images/down.gif" /> <a href="#housekeeping">Database Housekeeping</a></li>
77 </ul><h3>See also</h3>
78 <ul class="seealso">
79 <li><code class="module"><a href="../mod/mod_session.html">mod_session</a></code></li>
80 <li><code class="module"><a href="../mod/mod_session_crypto.html">mod_session_crypto</a></code></li>
81 <li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
82 <li><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code></li>
83 </ul></div>
84 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
85 <div class="section">
86 <h2><a name="dbdconfig" id="dbdconfig">DBD Configuration</a></h2>
87
88       <p>Before the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module can be configured to maintain a
89       session, the <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> module must be configured to make the various database queries
90       available to the server.</p>
91       
92       <p>There are four queries required to keep a session maintained, to select an existing session,
93       to update an existing session, to insert a new session, and to delete an expired or empty
94       session. These queries are configured as per the example below.</p>
95
96       <div class="example"><h3>Sample DBD configuration</h3><p><code>
97         DBDriver pgsql<br />
98         DBDParams "dbname=apachesession user=apache password=xxxxx host=localhost"<br />
99         DBDPrepareSQL "delete from session where key = %s" deletesession<br />
100         DBDPrepareSQL "update session set value = %s, expiry = %lld where key = %s" updatesession<br />
101         DBDPrepareSQL "insert into session (value, expiry, key) values (%s, %lld, %s)" insertsession<br />
102         DBDPrepareSQL "select value from session where key = %s and (expiry = 0 or expiry &gt; %lld)" selectsession<br />
103         DBDPrepareSQL "delete from session where expiry != 0 and expiry &lt; %lld" cleansession<br />
104       </code></p></div>
105
106     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
107 <div class="section">
108 <h2><a name="anonymous" id="anonymous">Anonymous Sessions</a></h2>
109     
110       <p>Anonymous sessions are keyed against a unique UUID, and stored on the
111       browser within an HTTP cookie. This method is similar to that used by most
112       application servers to store session information.</p>
113     
114       <p>To create a simple anonymous session and store it in a postgres database
115       table called <var>apachesession</var>, and save the session ID in a cookie
116       called <var>session</var>, configure the session as follows:</p>
117       
118       <div class="example"><h3>SQL based anonymous session</h3><p><code>
119         Session On<br />
120         SessionDBDCookieName session path=/<br />
121       </code></p></div>
122       
123       <p>For more examples on how the session can be configured to be read
124       from and written to by a CGI application, see the
125       <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> examples section.</p>
126       
127       <p>For documentation on how the session can be used to store username
128       and password details, see the <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
129
130     </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
131 <div class="section">
132 <h2><a name="peruser" id="peruser">Per User Sessions</a></h2>
133     
134       <p>Per user sessions are keyed against the username of a successfully
135       authenticated user. It offers the most privacy, as no external handle
136       to the session exists outside of the authenticated realm.</p>
137       
138       <p>Per user sessions work within a correctly configured authenticated
139       environment, be that using basic authentication, digest authentication
140       or SSL client certificates. Due to the limitations of who came first,
141       the chicken or the egg, per user sessions cannot be used to store
142       authentication credentials from a module like
143       <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code>.</p>
144     
145       <p>To create a simple per user session and store it in a postgres database
146       table called <var>apachesession</var>, and with the session keyed to the
147       userid, configure the session as follows:</p>
148       
149       <div class="example"><h3>SQL based per user session</h3><p><code>
150         Session On<br />
151         SessionDBDPerUser On<br />
152       </code></p></div>
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="housekeeping" id="housekeeping">Database Housekeeping</a></h2>
157       <p>Over the course of time, the database can be expected to start accumulating
158       expired sessions. At this point, the <code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code> module
159       is not yet able to handle session expiry automatically.</p>
160       
161       <div class="warning"><h3>Warning</h3>
162       <p>The administrator will need to set up an external process via cron to clean
163       out expired sessions.</p>
164       </div>
165
166     </div>
167 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
168 <div class="directive-section"><h2><a name="SessionDBDCookieName" id="SessionDBDCookieName">SessionDBDCookieName</a> <a name="sessiondbdcookiename" id="sessiondbdcookiename">Directive</a></h2>
169 <table class="directive">
170 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name and attributes for the RFC2109 cookie storing the session ID</td></tr>
171 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDCookieName <var>name</var> <var>attributes</var></code></td></tr>
172 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
173 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
174 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
175 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
176 </table>
177     <p>The <code class="directive">SessionDBDCookieName</code> directive specifies the name and
178     optional attributes of an RFC2109 compliant cookie inside which the session ID will
179     be stored. RFC2109 cookies are set using the <code>Set-Cookie</code> HTTP header.
180     </p>
181
182     <p>An optional list of cookie attributes can be specified, as per the example below.
183     These attributes are inserted into the cookie as is, and are not interpreted by
184     Apache. Ensure that your attributes are defined correctly as per the cookie specification.
185     </p>
186
187     <div class="example"><h3>Cookie with attributes</h3><p><code>
188       Session On<br />
189       SessionDBDCookieName session path=/private;domain=example.com;httponly;secure;version=1;<br />
190     </code></p></div>
191
192
193 </div>
194 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
195 <div class="directive-section"><h2><a name="SessionDBDCookieName2" id="SessionDBDCookieName2">SessionDBDCookieName2</a> <a name="sessiondbdcookiename2" id="sessiondbdcookiename2">Directive</a></h2>
196 <table class="directive">
197 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name and attributes for the RFC2965 cookie storing the session ID</td></tr>
198 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDCookieName2 <var>name</var> <var>attributes</var></code></td></tr>
199 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
200 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
201 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
202 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
203 </table>
204     <p>The <code class="directive">SessionDBDCookieName2</code> directive specifies the name and
205     optional attributes of an RFC2965 compliant cookie inside which the session ID will
206     be stored. RFC2965 cookies are set using the <code>Set-Cookie2</code> HTTP header.
207     </p>
208     
209     <p>An optional list of cookie attributes can be specified, as per the example below.
210     These attributes are inserted into the cookie as is, and are not interpreted by
211     Apache. Ensure that your attributes are defined correctly as per the cookie specification.
212     </p>
213     
214     <div class="example"><h3>Cookie2 with attributes</h3><p><code>
215       Session On<br />
216       SessionDBDCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;<br />
217     </code></p></div>
218
219
220 </div>
221 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
222 <div class="directive-section"><h2><a name="SessionDBDCookieRemove" id="SessionDBDCookieRemove">SessionDBDCookieRemove</a> <a name="sessiondbdcookieremove" id="sessiondbdcookieremove">Directive</a></h2>
223 <table class="directive">
224 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Control for whether session ID cookies should be removed from incoming HTTP headers</td></tr>
225 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDCookieRemove On|Off</code></td></tr>
226 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionDBDCookieRemove On</code></td></tr>
227 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
228 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
229 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
230 </table>
231     <p>The <code class="directive">SessionDBDCookieRemove</code> flag controls whether the cookies
232     containing the session ID will be removed from the headers during request processing.</p>
233
234     <p>In a reverse proxy situation where the Apache server acts as a server frontend for
235     a backend origin server, revealing the contents of the session ID cookie to the backend
236     could be a potential privacy violation. When set to on, the session ID cookie will be
237     removed from the incoming HTTP headers.</p>
238
239
240 </div>
241 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
242 <div class="directive-section"><h2><a name="SessionDBDDeleteLabel" id="SessionDBDDeleteLabel">SessionDBDDeleteLabel</a> <a name="sessiondbddeletelabel" id="sessiondbddeletelabel">Directive</a></h2>
243 <table class="directive">
244 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The SQL query to use to remove sessions from the database</td></tr>
245 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDDeleteLabel <var>label</var></code></td></tr>
246 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionDBDDeleteLabel deletesession</code></td></tr>
247 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
248 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
249 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
250 </table>
251     <p>The <code class="directive">SessionDBDDeleteLabel</code> directive sets the default delete
252     query label to be used to delete an expired or empty session. This label must have been previously
253     defined using the <code class="directive"><a href="../mod/mod_dbd.html#dbdpreparesql">DBDPrepareSQL</a></code> directive.</p>
254
255
256 </div>
257 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
258 <div class="directive-section"><h2><a name="SessionDBDInsertLabel" id="SessionDBDInsertLabel">SessionDBDInsertLabel</a> <a name="sessiondbdinsertlabel" id="sessiondbdinsertlabel">Directive</a></h2>
259 <table class="directive">
260 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The SQL query to use to insert sessions into the database</td></tr>
261 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDInsertLabel <var>label</var></code></td></tr>
262 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionDBDInsertLabel insertsession</code></td></tr>
263 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
264 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
265 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
266 </table>
267     <p>The <code class="directive">SessionDBDInsertLabel</code> directive sets the default insert
268     query label to be used to load in a session. This label must have been previously defined using the
269     <code class="directive"><a href="../mod/mod_dbd.html#dbdpreparesql">DBDPrepareSQL</a></code> directive.</p>
270
271     <p>If an attempt to update the session affects no rows, this query will be called to insert the
272     session into the database.</p>
273
274
275 </div>
276 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
277 <div class="directive-section"><h2><a name="SessionDBDPerUser" id="SessionDBDPerUser">SessionDBDPerUser</a> <a name="sessiondbdperuser" id="sessiondbdperuser">Directive</a></h2>
278 <table class="directive">
279 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable a per user session</td></tr>
280 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDPerUser On|Off</code></td></tr>
281 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionDBDPerUser Off</code></td></tr>
282 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
283 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
284 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
285 </table>
286     <p>The <code class="directive">SessionDBDPerUser</code> flag enables a per user session keyed
287     against the user's login name. If the user is not logged in, this directive will be
288     ignored.</p>
289
290
291 </div>
292 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
293 <div class="directive-section"><h2><a name="SessionDBDSelectLabel" id="SessionDBDSelectLabel">SessionDBDSelectLabel</a> <a name="sessiondbdselectlabel" id="sessiondbdselectlabel">Directive</a></h2>
294 <table class="directive">
295 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The SQL query to use to select sessions from the database</td></tr>
296 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDSelectLabel <var>label</var></code></td></tr>
297 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionDBDSelectLabel selectsession</code></td></tr>
298 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
299 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
300 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
301 </table>
302     <p>The <code class="directive">SessionDBDSelectLabel</code> directive sets the default select
303     query label to be used to load in a session. This label must have been previously defined using the
304     <code class="directive"><a href="../mod/mod_dbd.html#dbdpreparesql">DBDPrepareSQL</a></code> directive.</p>
305
306
307 </div>
308 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
309 <div class="directive-section"><h2><a name="SessionDBDUpdateLabel" id="SessionDBDUpdateLabel">SessionDBDUpdateLabel</a> <a name="sessiondbdupdatelabel" id="sessiondbdupdatelabel">Directive</a></h2>
310 <table class="directive">
311 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The SQL query to use to update existing sessions in the database</td></tr>
312 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionDBDUpdateLabel <var>label</var></code></td></tr>
313 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SessionDBDUpdateLabel updatesession</code></td></tr>
314 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
315 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
316 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_dbd</td></tr>
317 </table>
318     <p>The <code class="directive">SessionDBDUpdateLabel</code> directive sets the default update
319     query label to be used to load in a session. This label must have been previously defined using the
320     <code class="directive"><a href="../mod/mod_dbd.html#dbdpreparesql">DBDPrepareSQL</a></code> directive.</p>
321
322     <p>If an attempt to update the session affects no rows, the insert query will be
323     called to insert the session into the database. If the database supports InsertOrUpdate,
324     override this query to perform the update in one query instead of two.</p>
325
326
327 </div>
328 </div>
329 <div class="bottomlang">
330 <p><span>Available Languages: </span><a href="../en/mod/mod_session_dbd.html" title="English">&nbsp;en&nbsp;</a></p>
331 </div><div id="footer">
332 <p class="apache">Copyright 2011 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>
333 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
334 </body></html>