| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_session_cookie.xml.meta"> |
| |
| <name>mod_session_cookie</name> |
| <description>Cookie based session support</description> |
| <status>Extension</status> |
| <sourcefile>mod_session_cookie.c</sourcefile> |
| <identifier>session_cookie_module</identifier> |
| <compatibility>Available in Apache 2.3 and later</compatibility> |
| |
| <summary> |
| <note type="warning"><title>Warning</title> |
| <p>The session modules make use of HTTP cookies, and as such can fall |
| victim to Cross Site Scripting attacks, or expose potentially private |
| information to clients. Please ensure that the relevant risks have |
| been taken into account before enabling the session functionality on |
| your server.</p> |
| </note> |
| |
| <p>This submodule of <module>mod_session</module> provides support for the |
| storage of user sessions on the remote browser within HTTP cookies.</p> |
| |
| <p>Using cookies to store a session removes the need for the server or |
| a group of servers to store the session locally, or collaborate to share |
| a session, and can be useful for high traffic environments where a |
| server based session might be too resource intensive.</p> |
| |
| <p>If session privacy is required, the <module>mod_session_crypto</module> |
| module can be used to encrypt the contents of the session before writing |
| the session to the client.</p> |
| |
| <p>For more details on the session interface, see the documentation for |
| the <module>mod_session</module> module.</p> |
| |
| </summary> |
| <seealso><module>mod_session</module></seealso> |
| <seealso><module>mod_session_crypto</module></seealso> |
| <seealso><module>mod_session_dbd</module></seealso> |
| |
| <section id="basicexamples"><title>Basic Examples</title> |
| |
| <p>To create a simple session and store it in a cookie called |
| <var>session</var>, configure the session as follows:</p> |
| |
| <example><title>Browser based session</title> |
| <highlight language="config"> |
| Session On |
| SessionCookieName session path=/ |
| </highlight> |
| </example> |
| |
| <p>For more examples on how the session can be configured to be read |
| from and written to by a CGI application, see the |
| <module>mod_session</module> examples section.</p> |
| |
| <p>For documentation on how the session can be used to store username |
| and password details, see the <module>mod_auth_form</module> module.</p> |
| |
| </section> |
| |
| <directivesynopsis> |
| <name>SessionCookieName</name> |
| <description>Name and attributes for the RFC2109 cookie storing the session</description> |
| <syntax>SessionCookieName <var>name</var> <var>attributes</var></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| <context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>SessionCookieName</directive> directive specifies the name and |
| optional attributes of an RFC2109 compliant cookie inside which the session will |
| be stored. RFC2109 cookies are set using the <code>Set-Cookie</code> HTTP header. |
| </p> |
| |
| <p>An optional list of cookie attributes can be specified, as per the example below. |
| These attributes are inserted into the cookie as is, and are not interpreted by |
| Apache. Ensure that your attributes are defined correctly as per the cookie specification. |
| </p> |
| |
| <example><title>Cookie with attributes</title> |
| <highlight language="config"> |
| Session On |
| SessionCookieName session path=/private;domain=example.com;httponly;secure;version=1; |
| </highlight> |
| </example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SessionCookieName2</name> |
| <description>Name and attributes for the RFC2965 cookie storing the session</description> |
| <syntax>SessionCookieName2 <var>name</var> <var>attributes</var></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| <context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>SessionCookieName2</directive> directive specifies the name and |
| optional attributes of an RFC2965 compliant cookie inside which the session will |
| be stored. RFC2965 cookies are set using the <code>Set-Cookie2</code> HTTP header. |
| </p> |
| |
| <p>An optional list of cookie attributes can be specified, as per the example below. |
| These attributes are inserted into the cookie as is, and are not interpreted by |
| Apache. Ensure that your attributes are defined correctly as per the cookie specification. |
| </p> |
| |
| <example><title>Cookie2 with attributes</title> |
| <highlight language="config"> |
| Session On |
| SessionCookieName2 session path=/private;domain=example.com;httponly;secure;version=1; |
| </highlight> |
| </example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SessionCookieRemove</name> |
| <description>Control for whether session cookies should be removed from incoming HTTP headers</description> |
| <syntax>SessionCookieRemove On|Off</syntax> |
| <default>SessionCookieRemove Off</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| <context>.htaccess</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>SessionCookieRemove</directive> flag controls whether the cookies |
| containing the session will be removed from the headers during request processing.</p> |
| |
| <p>In a reverse proxy situation where the Apache server acts as a server frontend for |
| a backend origin server, revealing the contents of the session cookie to the backend |
| could be a potential privacy violation. When set to on, the session cookie will be |
| removed from the incoming HTTP headers.</p> |
| |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |