Make a start on documenting mod_authn_socache

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@957958 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 174 insertions, 0 deletions

diff --git a/docs/manual/mod/mod_authn_socache.xml b/docs/manual/mod/mod_authn_socache.xml
new file mode 100644
index 0000000000..f339c51c21
--- /dev/null
+++ b/docs/manual/mod/mod_authn_socache.xml
@@ -0,0 +1,174 @@
+
+<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<!--
+ 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_authn_socache.xml.meta">
+
+<name>mod_authn_socache</name>
+<description>Manages a cache of authentication credentials to relieve
+the load on backends</description>
+<status>Base</status>
+<sourcefile>mod_authn_socache.c</sourcefile>
+<identifier>authn_socache_module</identifier>
+<compatibility>Version 2.3 and later</compatibility>
+
+<summary>
+    <p>Maintains a cache of authentication credentials, so that a new backend
+    lookup is not required for every authenticated request.</p>
+</summary>
+
+<section id="intro"><title>Authentication Cacheing</title>
+    <p>Some users of more heavyweight authentication such as SQL database
+    lookups (<module>mod_authn_dbd</module>) have reported it putting an
+    unacceptable load on their authentication provider.  A typical case
+    in point is where an HTML page contains hundreds of objects
+    (images, scripts, stylesheets, media, etc), and a request to the page
+    generates hundreds of effectively-immediate requests for authenticated
+    additional contents.</p>
+    <p>mod_authn_socache provides a solution to this problem by
+    maintaining a cache of authentication credentials.</p>
+</section>
+
+<section id="usage"><title>Usage</title>
+    <p>The authentication cache should be used where authentication
+    lookups impose a significant load on the server, or a backend or
+    network.  Authentication by file (<module>mod_authn_file</module>)
+    or dbm (<module>mod_authn_dbm</module>) are unlikely to benefit,
+    as these are fast and lightweight in their own right (though in some
+    cases, such as a network-mounted file, cacheing may be worthwhile).
+    Other providers such as SQL, LDAP or Radius based authentication
+    are more likely to benefit, particularly where there is an observed
+    performance issue.</p>
+    <p>The basic rules to cache for a provider are:</p>
+    <ol><li>Include the provider you're cacheing for in an
+            <directive>AuthnCacheProvider</directive> directive.</li>
+        <li>List <var>socache</var> ahead of the provider you're
+            cacheing for in your <directive module="mod_auth_basic"
+            >AuthBasicProvider</directive> or <directive module=
+            "mod_auth_digest">AuthDigestProvider</directive> directive.</li>
+    </ol>
+    <p>A simple usage example to accelerate <module>mod_authn_dbd</module>
+    [TODO]</p>
+</section>
+
+<section id="dev"><title>Cacheing with custom modules</title>
+    <p>Module developers should note that their modules must be enabled
+    for cacheing with mod_authn_cache.  A single optional API function
+    <var>ap_authn_cache_store</var> is provided to cache credentials
+    a provider has just looked up or generated.  Usage examples are
+    available in <a
+    href="http://svn.eu.apache.org/viewvc?view=revision&amp;revision=957072"
+    >r957072</a>, in which three authn providers are enabled for cacheing.</p>
+</section>
+
+<directivesynopsis>
+<name>AuthnCacheSOCache</name>
+<description>Select socache backend provider to use</description>
+<syntax>AuthnCacheSOCache <var>provider-name</var></syntax>
+<contextlist><context>server config</context></contextlist>
+<override>None</override>
+
+<usage>
+    <p>This is a server-wide setting.  If not set, your platform's
+       default will be used.</p>
+    <note><title>socache</title>
+      <p>The cache is built on the the <var>socache</var> framework.
+      We need a link here once that's documented!</p>
+    </note>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthnCacheProvider</name>
+<description>Specify which authn provider(s) to cache for</description>
+<syntax>AuthnCacheProvider <var>authn-provider</var> [...]</syntax>
+<contextlist><context>directory</context><context>.htaccess</context></contextlist>
+<override>AuthConfig</override>
+<default>None</default>
+
+<usage>
+    <p>This directive specifies an authentication provider or providers
+    to cache for.  Credentials found by a provider not listed in an
+    AuthnCacheProvider directive will not be cached.</p>
+
+    <p>For example, to cache credentials found by <module>mod_authn_dbd</module>
+    or by a custom provider <var>myprovider</var>, but leave those looked
+    up by lightweight providers like file or dbm lookup alone:</p>
+    <example>
+        AuthnCacheProvider dbd myprovider
+    </example>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthnCacheTimeout</name>
+<description>Set a timeout for cache entries</description>
+<syntax>AuthnCacheTimeout <var>timeout</var> (seconds)</syntax>
+<contextlist><context>directory</context><context>.htaccess</context></contextlist>
+<override>AuthConfig</override>
+<default>300 (5 minutes)</default>
+
+<usage>
+    <p>Cacheing authentication data can be a security issue, though short-term
+    cacheing is unlikely to be a problem.  Typically a good solution is to
+    cache credentials for as long as it takes to relieve the load on a
+    backend, but no longer, though if changes to your users and passwords
+    are infrequent then a longer timeout may suit you.  The default 300
+    seconds (5 minutes) is both cautious and ample to keep the load
+    on a backend such as dbd (SQL database queries) down.</p>
+    <p>This should not be confused with session timeout, which is an
+    entirely separate issue.  However, you may wish to check your
+    session-management software for whether cached credentials can
+    "accidentally" extend a session, and bear it in mind when setting
+    your timeout.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>AuthnCacheContext</name>
+<description>Specify a context string for use in the cache key</description>
+<syntax>AuthnCacheContext <var>directory|server|custom-string</var></syntax>
+<contextlist><context>directory</context></contextlist>
+<default>directory</default>
+
+<usage>
+    <p>This directive specifies a string to be used along with the supplied
+    username (and realm in the case of Digest Authentication) in constructing
+    a cache key.  This serves to disambiguate identical usernames serving
+    different authentication areas on the server.</p>
+    <p>Two special values for this are <var>directory</var>, which uses
+    the directory context of the request as a string, and <var>server</var>
+    which uses the virtual host name.</p>
+    <p>The default is <var>directory</var>, which is also the most
+    conservative setting.  This is likely to be less than optimal, as it
+    (for example) causes <var>$app-base</var>, <var>$app-base/images</var>,
+    <var>$app-base/scripts</var> and <var>$app-base/media</var> each to
+    have its own separate cache key.  A better policy is to name the
+    <directive>AuthnCacheContext</directive> for the password
+    provider: for example a <var>htpasswd</var> file or database table.</p>
+    <p>Contexts can be shared across different areas of a server, where
+    credentials are shared.  However, this has potential to become a vector
+    for cross-site or cross-application security breaches, so this directive
+    is not permitted in <var>.htaccess</var> contexts.</p>
+</usage>
+</directivesynopsis>
+ 
+</modulesynopsis>
+