You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by ni...@apache.org on 2010/06/25 16:12:16 UTC
svn commit: r957958 -
/httpd/httpd/trunk/docs/manual/mod/mod_authn_socache.xml
Author: niq
Date: Fri Jun 25 14:12:16 2010
New Revision: 957958
URL: http://svn.apache.org/viewvc?rev=957958&view=rev
Log:
Make a start on documenting mod_authn_socache
Added:
httpd/httpd/trunk/docs/manual/mod/mod_authn_socache.xml (with props)
Added: httpd/httpd/trunk/docs/manual/mod/mod_authn_socache.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/mod_authn_socache.xml?rev=957958&view=auto
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/mod_authn_socache.xml (added)
+++ httpd/httpd/trunk/docs/manual/mod/mod_authn_socache.xml Fri Jun 25 14:12:16 2010
@@ -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&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>
+
Propchange: httpd/httpd/trunk/docs/manual/mod/mod_authn_socache.xml
------------------------------------------------------------------------------
svn:eol-style = native