Date: Fri, 4 Apr 2008 16:25:37 +0000 (+0000) Subject: Run transformation on new documentation X-Git-Tag: 2.3.0~815 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=db55a56f3f2088d828add8d5ef3641db4d0ec95f;p=thirdparty%2Fapache%2Fhttpd.git Run transformation on new documentation git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@644759 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/allmodules.xml b/docs/manual/mod/allmodules.xml index 2bf8eefa029..771fbfec40b 100644 --- a/docs/manual/mod/allmodules.xml +++ b/docs/manual/mod/allmodules.xml @@ -66,6 +66,9 @@ mod_proxy_ftp.xml mod_proxy_http.xml mod_rewrite.xml + mod_session.xml + mod_session_cookie.xml + mod_session_crypto.xml mod_setenvif.xml mod_so.xml mod_speling.xml diff --git a/docs/manual/mod/allmodules.xml.de b/docs/manual/mod/allmodules.xml.de index 787e05075af..0c764736a66 100644 --- a/docs/manual/mod/allmodules.xml.de +++ b/docs/manual/mod/allmodules.xml.de @@ -66,6 +66,9 @@ mod_proxy_ftp.xml mod_proxy_http.xml mod_rewrite.xml + mod_session.xml + mod_session_cookie.xml + mod_session_crypto.xml mod_setenvif.xml mod_so.xml mod_speling.xml diff --git a/docs/manual/mod/allmodules.xml.es b/docs/manual/mod/allmodules.xml.es index adf09fb8a20..c7d89c3ab65 100644 --- a/docs/manual/mod/allmodules.xml.es +++ b/docs/manual/mod/allmodules.xml.es @@ -66,6 +66,9 @@ mod_proxy_ftp.xml mod_proxy_http.xml mod_rewrite.xml + mod_session.xml + mod_session_cookie.xml + mod_session_crypto.xml mod_setenvif.xml mod_so.xml mod_speling.xml diff --git a/docs/manual/mod/allmodules.xml.ja b/docs/manual/mod/allmodules.xml.ja index 0782c2eb312..5453d59e833 100644 --- a/docs/manual/mod/allmodules.xml.ja +++ b/docs/manual/mod/allmodules.xml.ja @@ -66,6 +66,9 @@ mod_proxy_ftp.xml mod_proxy_http.xml mod_rewrite.xml + mod_session.xml + mod_session_cookie.xml + mod_session_crypto.xml mod_setenvif.xml.ja mod_so.xml.ja mod_speling.xml.ja diff --git a/docs/manual/mod/allmodules.xml.ko b/docs/manual/mod/allmodules.xml.ko index 057508fac8e..55fa83c3789 100644 --- a/docs/manual/mod/allmodules.xml.ko +++ b/docs/manual/mod/allmodules.xml.ko @@ -66,6 +66,9 @@ mod_proxy_ftp.xml mod_proxy_http.xml mod_rewrite.xml + mod_session.xml + mod_session_cookie.xml + mod_session_crypto.xml mod_setenvif.xml.ko mod_so.xml.ko mod_speling.xml.ko diff --git a/docs/manual/mod/allmodules.xml.tr b/docs/manual/mod/allmodules.xml.tr index 2bf8eefa029..771fbfec40b 100644 --- a/docs/manual/mod/allmodules.xml.tr +++ b/docs/manual/mod/allmodules.xml.tr @@ -66,6 +66,9 @@ mod_proxy_ftp.xml mod_proxy_http.xml mod_rewrite.xml + mod_session.xml + mod_session_cookie.xml + mod_session_crypto.xml mod_setenvif.xml mod_so.xml mod_speling.xml diff --git a/docs/manual/mod/directives.html.en b/docs/manual/mod/directives.html.en index 830b2c30bce..f0e486a5628 100644 --- a/docs/manual/mod/directives.html.en +++ b/docs/manual/mod/directives.html.en @@ -379,6 +379,21 @@

diff --git a/docs/manual/mod/index.html.en b/docs/manual/mod/index.html.en index f830799725a..def8c3e6f09 100644 --- a/docs/manual/mod/index.html.en +++ b/docs/manual/mod/index.html.en @@ -166,7 +166,10 @@ by other LDAP modules mod_proxy

Provides a rule-based rewriting engine to rewrite requested URLs on the fly

mod_setenvif

Allows the setting of environment variables based +

mod_session

Session support

mod_session_cookie

Cookie based session support

mod_session_crypto

Session encryption support

mod_setenvif

Allows the setting of environment variables based on characteristics of the request

mod_so

Loading of executable code and modules into the server at start-up or restart time

diff --git a/docs/manual/mod/mod_session.html b/docs/manual/mod/mod_session.html new file mode 100644 index 00000000000..d1b7201085c --- /dev/null +++ b/docs/manual/mod/mod_session.html @@ -0,0 +1,3 @@ +URI: mod_session.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/docs/manual/mod/mod_session.html.en b/docs/manual/mod/mod_session.html.en new file mode 100644 index 00000000000..c2a03edc43c --- /dev/null +++ b/docs/manual/mod/mod_session.html.en @@ -0,0 +1,426 @@ + + + +mod_session - Apache HTTP Server + + + + + + +

+Apache > HTTP Server > Documentation > Version 2.3 > Modules

Apache Module mod_session

Available Languages: en

+ + + +

Description:	Session support
Status:	Extension
Module Identifier:	session_module
Source File:	mod_session.c

Summary

+ +

Warning

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.

+ +

This module provides support for a server wide per user session + interface. Sessions can be used for keeping track of whether a user + has been logged in, or for other per user information that should + be kept available across requests.

+ +

Sessions may be stored on the server, or may be stored on the + browser. Sessions may also be optionally encrypted for added security. + These features are divided into several modules in addition to + mod_session: mod_session_crypto, + mod_session_cookie and mod_session_dbd. + Depending on the server requirements, load the appropriate modules + into the server (either statically at compile time or dynamically + via the LoalModule directive).

+ +

Sessions may be manipulated from other modules that depend on the + session, or the session may be read from and written to using + environment variables and HTTP headers, as appropriate.

+ +

Topics

What is a session?
Who can use a session?
Keeping sessions on the server
Keeping sessions on the browser
Basic Examples
Session Privacy
Cookie Privacy
Session Support for Authentication

What is a session?

At the core of the session interface is a table of key and value pairs + that are made accessible across browser requests.

+ +

These pairs can be set any valid set of strings, as needed by the + application making use of the session.

+ +

Who can use a session?

The session interface is primarily developed for the use by other + server modules, such as mod_auth_form, however CGI + based applications can optionally be granted access to the contents + of the session via the HTTP_SESSION environment variable. Sessions + have the option to be modified and/or updated by inserting an HTTP + response header containing the new session parameters.

+ +

Keeping sessions on the server

Apache can be configured to keep track of per user sessions stored + on a particular server or group of servers. This functionality is + similar to the sessions available in typical application servers.

+ +

If configured, sessions are tracked through the use of a session ID that + is stored inside a cookie, or extracted from the parameters embedded + within the URL query string, as found in a typical GET request.

+ +

As the contents of the session are stored exclusively on the server, + there is an expectation of privacy of the contents of the session. This + does have performance and resource implications should a large number + of sessions be present, or where a large number of webservers have to + share sessions with one another.

+ +

The mod_session_dbd module allows the storage of user + sessions within a SQL database via mod_dbd.

+ +

Keeping sessions on the browser

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.

+ +

This has the advantage that minimal resources are required on the + server to keep track of sessions, and multiple servers within a server + farm have no need to share session information.

+ +

The contents of the session however are exposed to the client, with a + corresponding risk of a loss of privacy. The + mod_session_crypto module can be configured to encrypt the + contents of the session before writing the session to the client.

+ +

The mod_session_cookie allows the storage of user + sessions on the browser within an HTTP cookie.

+ +

Basic Examples

+ +

Creating a session is as simple as turning the session on, and deciding + where the session will be stored. In this example, the session will be + stored on the browser, in a cookie called session.

+ +

Browser based session

+ Session On + SessionCookieName session path=/ +

+ +

The session is not useful unless it can be written to or read from. The + following example shows how values can be injected into the session through + the use of a predetermined HTTP response header called + X-Replace-Session.

+ +

Writing to a session

+ Session On + SessionCookieName session path=/ + SessionHeader X-Replace-Session +

+ +

The header should contain name value pairs expressed in the same format + as a query string in a URL, as in the example below. Setting a key to the + empty string has the effect of removing that key from the session.

+ +

CGI to write to a session

+ #!/bin/bash + echo "Content-Type: text/plain" + echo "X-Replace-Session: key1=foo&key2=&key3=bar" + echo + env +

+ +

If configured, the session can be read back from the HTTP_SESSION + environment variable. By default, the session is kept private, so this + has to be explicitly turned on with the + SessionEnv directive.

+ +

Read from a session

+ Session On + SessionEnv On + SessionCookieName session path=/ + SessionHeader X-Replace-Session +

+ +

Once read, the CGI variable HTTP_SESSION should contain + the value key1=foo&key3=bar.

+ +

Session Privacy

+ +

Using the "show cookies" feature of your browser, you would have seen + a clear text representation of the session. This could potentially be a + problem should the end user need to be kept unaware of the contents of + the session, or where a third party could gain unauthorised access to the + data within the session.

+ +

The contents of the session can be optionally encrypted before being + placed on the browser using the mod_session_crypto + module.

+ +

Browser based encrypted session

+ Session On + SessionCryptoPassphrase secret + SessionCookieName session path=/ +

+ +

The session will be automatically decrypted on load, and encrypted on + save by Apache, the underlying application using the session need have + no knowledge that encryption is taking place.

+ +

Sessions stored on the server rather than on the browser can also be + encrypted as needed, offering privacy where potentially sensitive + information is being shared between webservers in a server farm using + the mod_session_dbd module.

+ +

Cookie Privacy

+ +

The HTTP cookie mechanism also offers privacy features, such as the + ability to restrict cookie transport to SSL protected pages only, or + to prevent browser based javascript from gaining access to the contents + of the cookie.

+ +

Warning

Some of the HTTP cookie privacy features are either non standard, or + are not implemented consistently across browsers. The session modules + allow you to set cookie parameters, but it makes no guarantee that privacy + will be respected by the browser. If security is a concern, use the + mod_session_crypto to encrypt the contents of the session, + or store the session on the server using the mod_session_dbd + module.

+ +

Standard cookie parameters can be specified after the name of the cookie, + as in the example below.

+ +

Setting cookie parameters

+ Session On + SessionCryptoPassphrase secret + SessionCookieName session path=/private;domain=example.com;httponly;secure; +

+ +

In cases where the Apache server forms the frontend for backend origin servers, + it is possible to have the session cookies removed from the incoming HTTP headers using + the SessionCookieRemove directive. + This keeps the contents of the session cookies from becoming accessible from the + backend server. +

+ +

Session Support for Authentication

+ +

As is possible within many application servers, authentication modules can use + a session for storing the username and password after login. The + mod_auth_form saves the user's login name and password within + the session.

+ +

Form based authentication

+ Session On + SessionCryptoPassphrase secret + SessionCookieName session path=/ + AuthFormProvider file + AuthUserFile conf/passwd + AuthType form + AuthName realm + ... +

+ +

See the mod_auth_form module for documentation and complete + examples.

+ +

Session Directive

+ + + + + + + + +

Description:	Enables a session for the current directory or location
Syntax:	`Session On\|Off`
Default:	`Session Off`
Context:	directory
Status:	Extension
Module:	mod_session
Compatibility:	Available in Apache 2.3.0 and later

The Session directive enables a session for the + directory or location container. Further directives control where the + session will be stored and how privacy is maintained.

+ +

SessionEnv Directive

+ + + + + + + + +

Description:	Control whether the contents of the session are written to the +`HTTP_SESSION` environment variable
Syntax:	`SessionEnv On\|Off`
Default:	`SessionEnv Off`
Context:	directory
Status:	Extension
Module:	mod_session
Compatibility:	Available in Apache 2.3.0 and later

If set to On, the SessionEnv directive + causes the contents of the session to be written to a CGI environment + variable called HTTP_SESSION.

+ +

The string is written in the URL query format, for example:

+ +

+ key1=foo&key3=bar +

+ + +

SessionExclude Directive

+ + + + + + + + +

Description:	Define URL prefixes for which a session is ignored
Syntax:	`SessionExclude path`
Default:	`none`
Context:	directory
Status:	Extension
Module:	mod_session
Compatibility:	Available in Apache 2.3.0 and later

The SessionExclude directive allows sessions to + be disabled specific URL prefixes only. This can be used to make a + website more efficient, by targeting a more precise URL space for which + a session should be maintained. By default, all URLs within the directory + or location are included in the session. The + SessionExclude directive takes + precedence over the + SessionInclude directive.

+ +

Warning

This directive has a similar purpose to the path attribute + in HTTP cookies, but should not be confused with this attribute. This + directive does not set the path attribute, which must be + configured separately.

+ +

SessionHeader Directive

+ + + + + + + + +

Description:	Import session updates from a given HTTP response header
Syntax:	`SessionHeader header`
Default:	`none`
Context:	directory
Status:	Extension
Module:	mod_session
Compatibility:	Available in Apache 2.3.0 and later

The SessionHeader directive defines the name of an + HTTP response header which, if present, will be parsed and written to the + current session.

+ +

The header value is expected to be in the URL query format, for example:

+ +

+ key1=foo&key2=&key3=bar +

+ +

Where a key is set to the empty string, that key will be removed from the + session.

+ + +

SessionInclude Directive

+ + + + + + + + +

Description:	Define URL prefixes for which a session is valid
Syntax:	`SessionInclude path`
Default:	`all URLs`
Context:	directory
Status:	Extension
Module:	mod_session
Compatibility:	Available in Apache 2.3.0 and later

The SessionInclude directive allows sessions to + be made valid for specific URL prefixes only. This can be used to make a + website more efficient, by targeting a more precise URL space for which + a session should be maintained. By default, all URLs within the directory + or location are included in the session.

+ +

Warning

+ +

SessionMaxAge Directive

+ + + + + + + + +

Description:	Define a maximum age in seconds for a session
Syntax:	`SessionMaxAge maxage`
Default:	`SessionMaxAge 0`
Context:	directory
Status:	Extension
Module:	mod_session
Compatibility:	Available in Apache 2.3.0 and later

The SessionMaxAge directive defines a time limit + for which a session will remain valid. When a session is saved, this time + limit is reset and an existing session can be continued. If a session + becomes older than this limit without a request to the server to refresh + the session, the session will time out and be removed. Where a session is + used to stored user login details, this has the effect of logging the user + out automatically after the given time.

+ +

Setting the maxage to zero disables session expiry.

+ +

Available Languages: en

+ \ No newline at end of file diff --git a/docs/manual/mod/mod_session.xml.meta b/docs/manual/mod/mod_session.xml.meta new file mode 100644 index 00000000000..8174287b4da --- /dev/null +++ b/docs/manual/mod/mod_session.xml.meta @@ -0,0 +1,11 @@ + + + + mod_session + /mod/ + .. + + + en + + diff --git a/docs/manual/mod/mod_session_cookie.html b/docs/manual/mod/mod_session_cookie.html new file mode 100644 index 00000000000..0fc3e74f533 --- /dev/null +++ b/docs/manual/mod/mod_session_cookie.html @@ -0,0 +1,3 @@ +URI: mod_session_cookie.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/docs/manual/mod/mod_session_cookie.html.en b/docs/manual/mod/mod_session_cookie.html.en new file mode 100644 index 00000000000..29af571e847 --- /dev/null +++ b/docs/manual/mod/mod_session_cookie.html.en @@ -0,0 +1,174 @@ + + + +mod_session_cookie - Apache HTTP Server + + + + + + +

+Apache > HTTP Server > Documentation > Version 2.3 > Modules