You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by mi...@apache.org on 2012/02/26 11:43:20 UTC
svn commit: r1293804 - in /httpd/httpd/branches/2.4.x: ./
docs/manual/mod/mod_session.xml
Author: minfrin
Date: Sun Feb 26 10:43:20 2012
New Revision: 1293804
URL: http://svn.apache.org/viewvc?rev=1293804&view=rev
Log:
Backport:
Add a section to the mod_session documentation that better describes how to integrate
applications with mod_session.
Modified:
httpd/httpd/branches/2.4.x/ (props changed)
httpd/httpd/branches/2.4.x/docs/manual/mod/mod_session.xml
Propchange: httpd/httpd/branches/2.4.x/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Sun Feb 26 10:43:20 2012
@@ -1,3 +1,3 @@
/httpd/httpd/branches/revert-ap-ldap:1150158-1150173
/httpd/httpd/branches/wombat-integration:723609-723841
-/httpd/httpd/trunk:1200496,1200556,1200702,1200955,1200968,1201032,1201042,1201111,1201194,1201198,1201202,1201450,1201956,1202236,1202453,1202456,1202886,1203400,1203714,1203859,1203980,1204630,1204968,1204990,1205061,1205075,1205379,1205885,1206291,1206472,1206587,1206850,1206940,1206978,1207719,1208753,1208835,1209053,1209085,1209417,1209432,1209461,1209601,1209603,1209618,1209623,1209741,1209754,1209766,1209776,1209797-1209798,1209811-1209812,1209814,1209908,1209910,1209913,1209916-1209917,1209947,1209952,1210067,1210080,1210120,1210124,1210130,1210148,1210219,1210221,1210252,1210284,1210336,1210378,1210725,1210892,1210951,1210954,1211351,1211364,1211490,1211495,1211528,1211663,1211680,1212872,1212883,1213338,1213381,1213391,1213567,1214003,1214005,1214015,1215514,1220462,1220467,1220493,1220524,1220570,1220768,1220794,1220826,1220846,1221205,1221292,1222335,1222370,1222473,1222915,1222917,1222921,1223048,1225060,1225197-1225199,1225223,1225380,1225476,1225478,1225791,12
25795-1225796,1226339,1226375,1227910,1228700,1228816,1229024,1229059,1229099,1229116,1229134,1229136,1229930,1230286,1231442,1231446,1231508,1231510,1231518,1232575,1232594,1232630,1232838,1234180,1234297,1234479,1234511,1234565,1234574,1234642-1234643,1234876,1234899,1235019,1236122,1236701,1237407,1238545,1238768,1239029-1239030,1239071,1239565,1240315,1240470,1240778,1241069,1241071,1242967,1243176,1243246,1243797,1243799,1244211,1245717,1290823,1290835,1291819-1291820,1291834,1291840
+/httpd/httpd/trunk:1200496,1200556,1200702,1200955,1200968,1201032,1201042,1201111,1201194,1201198,1201202,1201450,1201956,1202236,1202453,1202456,1202886,1203400,1203714,1203859,1203980,1204630,1204968,1204990,1205061,1205075,1205379,1205885,1206291,1206472,1206587,1206850,1206940,1206978,1207719,1208753,1208835,1209053,1209085,1209417,1209432,1209461,1209601,1209603,1209618,1209623,1209741,1209754,1209766,1209776,1209797-1209798,1209811-1209812,1209814,1209908,1209910,1209913,1209916-1209917,1209947,1209952,1210067,1210080,1210120,1210124,1210130,1210148,1210219,1210221,1210252,1210284,1210336,1210378,1210725,1210892,1210951,1210954,1211351,1211364,1211490,1211495,1211528,1211663,1211680,1212872,1212883,1213338,1213381,1213391,1213567,1214003,1214005,1214015,1215514,1220462,1220467,1220493,1220524,1220570,1220768,1220794,1220826,1220846,1221205,1221292,1222335,1222370,1222473,1222915,1222917,1222921,1223048,1225060,1225197-1225199,1225223,1225380,1225476,1225478,1225791,12
25795-1225796,1226339,1226375,1227910,1228700,1228816,1229024,1229059,1229099,1229116,1229134,1229136,1229930,1230286,1231442,1231446,1231508,1231510,1231518,1232575,1232594,1232630,1232838,1234180,1234297,1234479,1234511,1234565,1234574,1234642-1234643,1234876,1234899,1235019,1236122,1236701,1237407,1238545,1238768,1239029-1239030,1239071,1239565,1240315,1240470,1240778,1241069,1241071,1242967,1243176,1243246,1243797,1243799,1244211,1245717,1290823,1290835,1291819-1291820,1291834,1291840,1293678
Modified: httpd/httpd/branches/2.4.x/docs/manual/mod/mod_session.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.4.x/docs/manual/mod/mod_session.xml?rev=1293804&r1=1293803&r2=1293804&view=diff
==============================================================================
--- httpd/httpd/branches/2.4.x/docs/manual/mod/mod_session.xml (original)
+++ httpd/httpd/branches/2.4.x/docs/manual/mod/mod_session.xml Sun Feb 26 10:43:20 2012
@@ -63,10 +63,17 @@
<section id="whatisasession"><title>What is a session?</title>
<p>At the core of the session interface is a table of key and value pairs
- that are made accessible across browser requests.</p>
-
- <p>These pairs can be set to any valid string, as needed by the
- application making use of the session.</p>
+ that are made accessible across browser requests. These pairs can be set
+ to any valid string, as needed by the application making use of the
+ session.</p>
+
+ <p>The "session" is a <strong>application/x-www-form-urlencoded</strong>
+ string containing these key value pairs, as defined by the
+ <a href="http://www.w3.org/TR/html4/">HTML specification</a>.</p>
+
+ <p>The session can optionally be encrypted and base64 encoded before
+ being written to the storage mechanism, as defined by the
+ administrator.</p>
</section>
<section id="whocanuseasession"><title>Who can use a session?</title>
@@ -99,9 +106,9 @@
</section> <!-- /serversession -->
<section id="browsersession"><title>Keeping sessions on the browser</title>
- <p>Where keeping track of a session on a server is too resource
- intensive or inconvenient, the option exists to store the contents
- of the session within a cookie on the client browser instead.</p>
+ <p>In high traffic environments where keeping track of a session on a
+ server is too resource intensive or inconvenient, the option exists to store
+ the contents of the session within a cookie on the client browser instead.</p>
<p>This has the advantage that minimal resources are required on the
server to keep track of sessions, and multiple servers within a server
@@ -251,6 +258,64 @@
examples.</p>
</section>
+ <section id="integration"><title>Integrating Sessions with External Applications</title>
+
+ <p>In order for sessions to be useful, it must be possible to share the contents
+ of a session with external applications, and it must be possible for an
+ external application to write a session of its own.</p>
+
+ <p> A typical example might be an application that changes a user's password set by
+ <module>mod_auth_form</module>. This application would need to read the current
+ username and password from the session, make the required changes to the user's
+ password, and then write the new password to the session in order to provide a
+ seamless transition to the new password.</p>
+
+ <p>A second example might involve an application that registers a new user for
+ the first time. When registration is complete, the username and password is
+ written to the session, providing a seamless transition to being logged in.</p>
+
+ <dl>
+ <dt>Apache modules</dt>
+ <dd>Modules within the server that need access to the session can use the
+ <strong>mod_session.h</strong> API in order to read from and write to the
+ session. This mechanism is used by modules like <module>mod_auth_form</module>.
+ </dd>
+
+ <dt>CGI programs and scripting languages</dt>
+ <dd>Applications that run within the webserver can optionally retrieve the
+ value of the session from the <strong>HTTP_SESSION</strong> environment
+ variable. The session should be encoded as a
+ <strong>application/x-www-form-urlencoded</strong> string as described by the
+ <a href="http://www.w3.org/TR/html4/">HTML specification</a>. The environment
+ variable is controlled by the setting of the
+ <directive module="mod_session">SessionEnv</directive> directive. The session
+ can be written to by the script by returning a
+ <strong>application/x-www-form-urlencoded</strong> response header with a name
+ set by the <directive module="mod_session">SessionHeader</directive>
+ directive. In both cases, any encryption or decryption, and the reading the
+ session from or writing the session to the chosen storage mechanism is handled
+ by the <module>mod_session</module> modules and corresponding configuration.
+ </dd>
+
+ <dt>Applications behind <module>mod_proxy</module></dt>
+ <dd>If the <directive module="mod_session">SessionHeader</directive>
+ directive is used to define an HTTP request header, the session, encoded as
+ a <strong>application/x-www-form-urlencoded</strong> string, will be made
+ available to the application. If the same header is provided in the response,
+ the value of this response header will be used to replace the session. As
+ above, any encryption or decryption, and the reading the session from or
+ writing the session to the chosen storage mechanism is handled by the
+ <module>mod_session</module> modules and corresponding configuration.</dd>
+
+ <dt>Standalone applications</dt>
+ <dd>Applications might choose to manipulate the session outside the control
+ of the Apache HTTP server. In this case, it is the responsibility of the
+ application to read the session from the chosen storage mechanism,
+ decrypt the session, update the session, encrypt the session and write
+ the session to the chosen storage mechanism, as appropriate.</dd>
+ </dl>
+
+ </section>
<directivesynopsis>
<name>Session</name>