--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: new_api_2_4.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ -->
+<title>API Changes in Apache HTTP Server 2.4 since 2.2 - Apache HTTP Server</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body id="manual-page"><div id="page-header">
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
+<p class="apache">Apache HTTP Server Version 2.3</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>API Changes in Apache HTTP Server 2.4 since 2.2</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/developer/new_api_2_4.html" title="English"> en </a></p>
+</div>
+
+ <p>This document describes changes to the Apache HTTPD API from
+ version 2.2 to 2.4, that may be of interest to module/application
+ developers and core hacks. At the time of writing, the 2.4 API
+ is not finalised, and this document may serve to highlight
+ points that call for further review.</p>
+ <p>API changes fall into two categories: APIs that are altogether new,
+ and existing APIs that are expanded or changed. The latter are
+ further divided into those where all changes are back-compatible
+ (so existing modules can ignore them), and those that might
+ require attention by maintainers. As with the transition from
+ HTTPD 2.0 to 2.2, existing modules and applications will require
+ recompiling and may call for some attention, but most should not
+ require any substantial updating (although some may be able to
+ take advantage of API changes to offer significant improvements).</p>
+ <p>For the purpose of this document, the API is split according
+ to the public header files. These headers are themselves the
+ reference documentation, and can be used to generate a browsable
+ HTML reference with <code>make docs</code>.</p>
+</div>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#ap_expr">ap_expr (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#ap_listen">ap_listen (changed; back-compatible)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#ap_mpm">ap_mpm (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#ap_slotmem">ap_slotmem (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#ap_socache">ap_socache (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#heartbeat">heartbeat (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#http_config">http_config (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#http_core">http_core (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#httpd">httpd (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#http_log">http_log (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#http_request">http_request (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#mod_auth">mod_auth (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#mod_core">mod_core (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#mod_request">mod_request (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#mpm_common">mpm_common (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#scoreboard">scoreboard (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#util_cookies">util_cookies (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#util_ldap">util_ldap (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#util_mutex">util_mutex (NEW!)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#util_script">util_script (changed)</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#util_time">util_time (changed)</a></li>
+</ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="ap_expr" id="ap_expr">ap_expr (NEW!)</a></h2>
+
+ <p>Introduces a new API to parse and evaluate boolean and algebraic
+ expressions, including provision for a standard syntax and
+ customised variants.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="ap_listen" id="ap_listen">ap_listen (changed; back-compatible)</a></h2>
+
+ <p>Introduces new API to enable apache child processes to serve different purposes.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="ap_mpm" id="ap_mpm">ap_mpm (changed)</a></h2>
+
+ <p><code>ap_mpm_run</code> is replaced by a new <code>mpm</code> hook.
+ Also <code>ap_graceful_stop_signalled</code> is lost, and
+ <code>ap_mpm_register_timed_callback</code> is new.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="ap_slotmem" id="ap_slotmem">ap_slotmem (NEW!)</a></h2>
+
+ <p>Introduces an API for modules to allocate and manage memory slots
+ (normally) for shared memory.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="ap_socache" id="ap_socache">ap_socache (NEW!)</a></h2>
+
+ <p>API to manage a shared object cache.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="heartbeat" id="heartbeat">heartbeat (NEW!)</a></h2>
+
+ <p>common structures for heartbeat modules (should this be public API?)</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="http_config" id="http_config">http_config (changed)</a></h2>
+
+ <ul>
+ <li>Introduces per-module, per-directory loglevels, including macro wrappers.</li>
+ <li>New AP_DECLARE_MODULE macro to declare all modules.</li>
+ <li>New APLOG_USE_MODULE macro necessary for per-module loglevels in
+ multi-file modules.</li>
+ <li>New API to retain data across module unload/load</li>
+ <li>New check_config hook</li>
+ <li>New ap_process_fnmatch_configs() to process wildcards</li>
+ </ul>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="http_core" id="http_core">http_core (changed)</a></h2>
+
+ <ul>
+ <li>REMOVED ap_default_type, ap_requires, all 2.2 authnz API</li>
+ <li>Introduces Optional Functions for logio and authnz</li>
+ <li>New function ap_get_server_name_for_url to support ipv6 literals.</li>
+ </ul>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="httpd" id="httpd">httpd (changed)</a></h2>
+
+ <ul>
+ <li>Introduce per-directory, per-module loglevel</li>
+ <li>New loglevels APLOG_TRACEn</li>
+ <li>Support for mod_request kept_body</li>
+ <li>Support buffering filter data for async requests</li>
+ <li>New CONN_STATE values</li>
+ <li>Function changes: ap_escape_html updated; ap_unescape_all, ap_escape_path_segment_buffer</li>
+ </ul>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="http_log" id="http_log">http_log (changed)</a></h2>
+
+ <ul>
+ <li>Introduce per-directory, per-module loglevel</li>
+ <li>New loglevels APLOG_TRACEn</li>
+ <li>ap_log_*error become macro wrappers (fully back-compatible if
+ APLOG_MARK macro is used)</li>
+ <li>piped logging revamped</li>
+ <li>module_index added to error_log hook</li>
+ <li>new function: ap_log_command_line</li>
+ </ul>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="http_request" id="http_request">http_request (changed)</a></h2>
+
+ <ul>
+ <li>New auth_internal API and auth_provider API</li>
+ <li>New EOR bucket type</li>
+ <li>New function ap_process_async_request</li>
+ <li>New flags AP_AUTH_INTERNAL_PER_CONF and AP_AUTH_INTERNAL_PER_URI</li>
+ <li>New access_checker_ex hook to apply additional access control and/or
+ bypass authentication.</li>
+ <li>New functions ap_hook_check_access_ex, ap_hook_check_access,
+ ap_hook_check_authn, ap_hook_check_authz which accept
+ AP_AUTH_INTERNAL_PER_* flags</li>
+ <li>DEPRECATED direct use of ap_hook_access_checker, access_checker_ex,
+ ap_hook_check_user_id, ap_hook_auth_checker</li>
+ </ul>
+ <p>When possible, registering all access control hooks (including
+ authentication and authorization hooks) using AP_AUTH_INTERNAL_PER_CONF
+ is recommended. If all modules' access control hooks are registered
+ with this flag, then whenever the server handles an internal
+ sub-request that matches the same set of access control configuration
+ directives as the initial request (which is the common case), it can
+ avoid invoking the access control hooks another time.</p>
+ <p>If your module requires the old behavior and must perform access
+ control checks on every sub-request with a different URI from the
+ initial request, even if that URI matches the same set of access
+ control configuration directives, then use AP_AUTH_INTERNAL_PER_URI.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="mod_auth" id="mod_auth">mod_auth (NEW!)</a></h2>
+
+ <p>Introduces the new provider framework for authn and authz</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="mod_core" id="mod_core">mod_core (NEW!)</a></h2>
+
+ <p>This introduces low-level APIs to send arbitrary headers,
+ and exposes functions to handle HTTP OPTIONS and TRACE.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="mod_request" id="mod_request">mod_request (NEW!)</a></h2>
+
+ <p>The API for <code class="module"><a href="../mod/mod_request.html">mod_request</a></code>, to make input data
+ available to multiple application/handler modules where required,
+ and to parse HTML form data.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="mpm_common" id="mpm_common">mpm_common (changed)</a></h2>
+
+ <ul>
+ <li>REMOVES: accept, lockfile, lock_mech, set_scoreboard (locking uses the new ap_mutex API)</li>
+ <li>NEW API to drop privileges (delegates this platform-dependent
+ function to modules)</li>
+ <li>NEW Hooks: mpm_query, mpm_note_child_killed, timed_callback, get_name, and function ap_mpm_note_child_killed</li>
+ </ul>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="scoreboard" id="scoreboard">scoreboard (changed)</a></h2>
+
+ <p>ap_get_scoreboard_worker is gratuitously made non-back-compatible
+ as an alternative version is introduced. Additional proxy_balancer
+ support. Child status stuff revamped.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="util_cookies" id="util_cookies">util_cookies (NEW!)</a></h2>
+
+ <p>Introduces a new API for managing HTTP Cookies.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="util_ldap" id="util_ldap">util_ldap (changed)</a></h2>
+
+ <p>I have yet to get a handle on this update.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="util_mutex" id="util_mutex">util_mutex (NEW!)</a></h2>
+
+ <p>A wrapper for APR proc and global mutexes in httpd.</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="util_script" id="util_script">util_script (changed)</a></h2>
+
+ <p>NEW: ap_args_to_table</p>
+ </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="util_time" id="util_time">util_time (changed)</a></h2>
+
+ <p>NEW: ap_recent_ctime_ex</p>
+ </div></div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/developer/new_api_2_4.html" title="English"> en </a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2010 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+</body></html>
\ No newline at end of file
</code></p></div>
+ <p>If no matching virtual host is found, then the first listed
+ virtual host that matches the IP address and port will be used.</p>
+
+
<p>IPv6 addresses must be enclosed in square brackets, as shown
in the following example:</p>
ServerName www.example.com:80
</code></p></div>
+ <p>The <code class="directive">ServerName</code> directive
+ may appear anywhere within the definition of a server. However,
+ each appearance overrides the previous appearance (within that
+ server).</p>
+
<p>If no <code class="directive">ServerName</code> is specified, then the
server attempts to deduce the hostname by performing a reverse
lookup on the IP address. If no port is specified in the
<code class="directive"><a href="#servername">ServerName</a></code> from the "main"
server configuration will be inherited.</p>
+ <p>If no matching virtual host is found, then the first listed
+ virtual host that matches the IP address will be used. As a
+ consequence, the first listed virtual host is the default virtual
+ host.</p>
+
<div class="warning"><h3>Security</h3>
<p>See the <a href="../misc/security_tips.html">security tips</a>
document for details on why your security could be compromised if the
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.de.xsl"?>
-<!-- English Revision: 167959:966890 (outdated) -->
+<!-- English Revision: 167959:987251 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 669847:966890 (outdated) -->
+<!-- English Revision: 669847:987251 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 813376:966890 (outdated) -->
+<!-- English Revision: 813376:987251 (outdated) -->
<!-- =====================================================
Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
Reviewed by: Orhan Berent <berent belgeler.org>
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: mod_authn_socache.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ This file is generated from xml source: DO NOT EDIT
+ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ -->
+<title>mod_authn_socache - Apache HTTP Server</title>
+<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
+<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
+<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<link href="../images/favicon.ico" rel="shortcut icon" /></head>
+<body>
+<div id="page-header">
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
+<p class="apache">Apache HTTP Server Version 2.3</p>
+<img alt="" src="../images/feather.gif" /></div>
+<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
+<div id="path">
+<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
+<div id="page-content">
+<div id="preamble"><h1>Apache Module mod_authn_socache</h1>
+<div class="toplang">
+<p><span>Available Languages: </span><a href="../en/mod/mod_authn_socache.html" title="English"> en </a></p>
+</div>
+<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Manages a cache of authentication credentials to relieve
+the load on backends</td></tr>
+<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>authn_socache_module</td></tr>
+<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_authn_socache.c</td></tr>
+<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.3 and later</td></tr></table>
+<h3>Summary</h3>
+
+ <p>Maintains a cache of authentication credentials, so that a new backend
+ lookup is not required for every authenticated request.</p>
+</div>
+<div id="quickview"><h3 class="directives">Directives</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#authncachecontext">AuthnCacheContext</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authncacheprovider">AuthnCacheProvider</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authncachesocache">AuthnCacheSOCache</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#authncachetimeout">AuthnCacheTimeout</a></li>
+</ul>
+<h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#intro">Authentication Cacheing</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#dev">Cacheing with custom modules</a></li>
+</ul></div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="intro" id="intro">Authentication Cacheing</a></h2>
+ <p>Some users of more heavyweight authentication such as SQL database
+ lookups (<code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>) 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>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="usage" id="usage">Usage</a></h2>
+ <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 (<code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code>)
+ or dbm (<code class="module"><a href="../mod/mod_authn_dbm.html">mod_authn_dbm</a></code>) 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 or LDAP based authentication are more
+ likely to benefit, particularly where there is an observed
+ performance issue. Amongst the standard modules, <code class="module"><a href="../mod/mod_authnz_ldap.html">mod_authnz_ldap</a></code> manages its own cache, so only
+ <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code> will usually benefit from this cache.</p>
+ <p>The basic rules to cache for a provider are:</p>
+ <ol><li>Include the provider you're cacheing for in an
+ <code class="directive">AuthnCacheProvider</code> directive.</li>
+ <li>List <var>socache</var> ahead of the provider you're
+ cacheing for in your <code class="directive"><a href="../mod/mod_auth_basic.html#authbasicprovider">AuthBasicProvider</a></code> or <code class="directive"><a href="../mod/mod_auth_digest.html#authdigestprovider">AuthDigestProvider</a></code> directive.</li>
+ </ol>
+ <p>A simple usage example to accelerate <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>
+ using dbm as a cache engine:</p>
+ <div class="example"><pre>
+ <Directory /usr/www/myhost/private>
+ AuthType Basic
+ AuthName "Cached Authentication Example"
+ AuthBasicProvider socache dbd
+ AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"
+ AuthnCacheProvider dbd
+ AuthnCacheContext dbd-authn-example
+ AuthnCacheSOCache dbm
+ Require valid-user
+ </Directory>
+ </pre></div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="dev" id="dev">Cacheing with custom modules</a></h2>
+ <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>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthnCacheContext" id="AuthnCacheContext">AuthnCacheContext</a> <a name="authncachecontext" id="authncachecontext">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify a context string for use in the cache key</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnCacheContext <var>directory|server|custom-string</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>directory</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_socache</td></tr>
+</table>
+ <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
+ <code class="directive">AuthnCacheContext</code> 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>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthnCacheProvider" id="AuthnCacheProvider">AuthnCacheProvider</a> <a name="authncacheprovider" id="authncacheprovider">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify which authn provider(s) to cache for</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnCacheProvider <var>authn-provider</var> [...]</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>None</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_socache</td></tr>
+</table>
+ <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 <code class="module"><a href="../mod/mod_authn_dbd.html">mod_authn_dbd</a></code>
+ or by a custom provider <var>myprovider</var>, but leave those looked
+ up by lightweight providers like file or dbm lookup alone:</p>
+ <div class="example"><p><code>
+ AuthnCacheProvider dbd myprovider
+ </code></p></div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthnCacheSOCache" id="AuthnCacheSOCache">AuthnCacheSOCache</a> <a name="authncachesocache" id="authncachesocache">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Select socache backend provider to use</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnCacheSOCache <var>provider-name</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>None</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_socache</td></tr>
+</table>
+ <p>This is a server-wide setting. If not set, your platform's
+ default will be used.</p>
+ <div class="note"><h3>socache</h3>
+ <p>The cache is built on the the <var>socache</var> framework.
+ We need a link here once that's documented!</p>
+ </div>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="AuthnCacheTimeout" id="AuthnCacheTimeout">AuthnCacheTimeout</a> <a name="authncachetimeout" id="authncachetimeout">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set a timeout for cache entries</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AuthnCacheTimeout <var>timeout</var> (seconds)</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>300 (5 minutes)</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>AuthConfig</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_authn_socache</td></tr>
+</table>
+ <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>
+
+</div>
+</div>
+<div class="bottomlang">
+<p><span>Available Languages: </span><a href="../en/mod/mod_authn_socache.html" title="English"> en </a></p>
+</div><div id="footer">
+<p class="apache">Copyright 2010 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
+</body></html>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile>
+ <basename>mod_authn_socache</basename>
+ <path>/mod/</path>
+ <relpath>..</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
--- /dev/null
+# GENERATED FROM XML -- DO NOT EDIT
+
+URI: new_api_2_4.html.en
+Content-Language: en
+Content-type: text/html; charset=ISO-8859-1
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!-- GENERATED FROM XML: DO NOT EDIT -->
+
+<metafile>
+ <basename>new_api_2_4</basename>
+ <path>/</path>
+ <relpath>.</relpath>
+
+ <variants>
+ <variant>en</variant>
+ </variants>
+</metafile>
exactly what Apache HTTP Server does when deciding what virtual host to
serve a request from.</p>
- <p>If you just want to <cite>make it work</cite> without
- understanding how, here are <a href="examples.html">some
- examples</a>.</p>
+ <p>Most users should read about <a href="name-based.html#namevip">
+ Name-based vs. IP-based Virtual Hosts</a> to decide which type they
+ want to use, then read more about <a href="name-based.html">name-based</a>
+ or <a href="ip-based.html">IP-based</a> virtualhosts, and then see
+ <a href="examples.html">some examples</a>.</p>
+
+ <p>If you want to understand all the details, then you can
+ come back to this page.</p>
</div>
-<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#configparsing">Configuration File Parsing</a></li>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#configparsing">Configuration File</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#hostmatching">Virtual Host Matching</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#tips">Tips</a></li>
-</ul></div>
+</ul><h3>See also</h3><ul class="seealso"><li><a href="ip-based.html">IP-based Virtual Host Support</a></li><li><a href="name-based.html">Name-based Virtual Hosts Support</a></li><li><a href="examples.html">Virtual Host examples for common setups</a></li><li><a href="mass.html">Dynamically configured mass virtual hosting</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="configparsing" id="configparsing">Configuration File Parsing</a></h2>
+<h2><a name="configparsing" id="configparsing">Configuration File</a></h2>
- <p>There is a <em>main_server</em> which consists of all the
+ <p>There is a <em>main server</em> which consists of all the
definitions appearing outside of
- <code><VirtualHost></code> sections. There are virtual
+ <code><VirtualHost></code> sections.</p>
+
+ <p>There are virtual
servers, called <em>vhosts</em>, which are defined by
<code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
sections.</p>
- <p>The
- <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code> directive
- may appear anywhere within the definition of a server. However,
- each appearance overrides the previous appearance (within that
- server).</p>
-
- <p>The main_server has no default
- <code>ServerAlias</code>. The default <code>ServerName</code>,
- if not specified, is deduced from the server's IP address.</p>
-
- <p>Port numbers specified in the <code>VirtualHost</code> directive do
- not influence what port numbers Apache will listen on, they only discriminate between
- which <code>VirtualHost</code> will be selected to handle a request.</p>
+ <p>Each <code>VirtualHost</code> directive includes one
+ or more addresses and optional ports.</p>
+
+ <p>Hostnames can be used in place of IP addresses in a virtual
+ host definition, but they are resolved at startup and if any name
+ resolutions fail, those virtual host definitions are ignored.
+ This is, therefore, not recommended.</p>
+
+ <p>If using IP-based vhosts, the address can be specified
+ as <code>_default_</code>, which will match a request if no
+ other vhost has the explicit address on which the request was
+ received.</p>
+
+ <p>If using name-based vhosts, the address can be specified as
+ <code>*</code>, which will match a request if no
+ other vhost has the explicit address on which the request was
+ received. The corresponding <code>NameVirtualHost</code>
+ directive must also use <code>*</code>.</p>
+
+ <p>The address appearing in the <code>VirtualHost</code>
+ directive can have an optional port. If the port is unspecified,
+ it is treated as a wildcard port, which can also be indicated
+ explicitly using <code>*</code>.
+ The wildcard port matches any port.</p>
+
+ <p>(Port numbers specified in the <code>VirtualHost</code> directive do
+ not influence what port numbers Apache will listen on, they only control
+ which <code>VirtualHost</code> will be selected to handle a request.
+ Use the <code class="directive"><a href="../mod/core.html#listen">Listen</a></code> directive to
+ control the addresses and ports on which the server listens.)
+ </p>
- <p>Each address appearing in the <code>VirtualHost</code>
- directive can have an optional port. If the port is unspecified
- it is treated as a wildcard port. The special port <code>*</code>
- indicates a wildcard that matches any port. Collectively the
- entire set of addresses (including multiple <code>A</code>
- record results from DNS lookups) are called the vhost's
+ <p>Collectively the
+ entire set of addresses (including multiple
+ results from DNS lookups) are called the vhost's
<em>address set</em>.</p>
- <p>Unless a <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code>
- directive is used for the exact IP address and port pair in the
- <code>VirtualHost</code> directive, Apache selects the best match
- only on the basis of the IP address (or wildcard) and port number.
- If there are multiple identical best matches, the first <code>VirtualHost</code>
- appearing in the configuration file will be selected.</p>
-
- <p>If you want Apache to <em>further</em> discriminate on the basis of the
- HTTP <code>Host</code> header supplied by the client, the
- <code>NameVirtualHost</code> directive <em>must</em> appear
- with the exact IP address (or wildcard) and port pair used in a correspnding
- set of <code>VirtualHost</code> directives.</p>
-
- <p>The name-based virtual host selection occurs only after the a single IP-based
- virtual host has been selected, and only considers the set of virtual hosts
- the carry an identical IP address and port pair.</p>
-
- <p>Hostnames can be used in place of IP addresses in a virtual host definition,
- but it is resolved at startup and is not recommended.</p>
+ <p>If you want Apache to discriminate on the
+ basis of the HTTP <code>Host</code> header supplied by the client,
+ the <code>NameVirtualHost</code> directive <em>must</em> appear
+ with the exact IP address (or wildcard) and port pair used in a
+ corresponding set of <code>VirtualHost</code> directives.</p>
+ <p>The
+ <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code> directive
+ may appear anywhere within the definition of a server. However,
+ each appearance overrides the previous appearance (within that
+ server). If no <code>ServerName</code> is specified, the server
+ attempts to deduce it from the server's IP address.</p>
- <p>Multiple <code>NameVirtualHost</code> directives can be used
- each with a set of <code>VirtualHost</code> directives but only
+ <p>Multiple <code>NameVirtualHost</code> directives can be used,
+ each with a set of <code>VirtualHost</code> directives, but only
one <code>NameVirtualHost</code> directive should be used for
each specific IP:port pair.</p>
+ <p>The first name-based vhost in the configuration file for a
+ given IP:port pair is significant because it is used for all
+ requests received on that address and port for which no other
+ vhost for that IP:port pair has a matching ServerName or
+ ServerAlias. It is also used for all SSL connections if the
+ server does not support <a class="glossarylink" href="../glossary.html#servernameindication" title="see glossary">Server Name Indication</a>.</p>
+
+ <p>If there are no vhosts defined for an address in a
+ <code>NameVirtualHost</code> directive, the
+ <code>NameVirtualHost</code> directive is ignored at startup and an error is
+ logged.</p>
+
<p>The ordering of <code>NameVirtualHost</code> and
- <code>VirtualHost</code> directives is not important which
+ <code>VirtualHost</code> directives is not important, which
makes the following two examples identical (only the order of
the <code>VirtualHost</code> directives for <em>one</em>
address set is important, see below):</p>
<p>(To aid the readability of your configuration you should
prefer the left variant.)</p>
- <p>During initialization a list for each IP address is
- generated and inserted into an hash table. If the IP address is
- used in a <code>NameVirtualHost</code> directive the list
- contains all name-based vhosts for the given IP address. If
- there are no vhosts defined for that address the
- <code>NameVirtualHost</code> directive is ignored and an error
- is logged. For an IP-based vhost the list in the hash table is
- empty.</p>
-
- <p>Due to a fast hashing function the overhead of hashing an IP
- address during a request is minimal and almost not existent.
- Additionally the table is optimized for IP addresses which vary
- in the last octet.</p>
-
<p>For every vhost various default values are set. In
particular:</p>
<code class="directive"><a href="../mod/core.html#receivebuffersize">ReceiveBufferSize</a></code>,
or <code class="directive"><a href="../mod/core.html#sendbuffersize">SendBufferSize</a></code>
directive then the respective value is inherited from the
- main_server. (That is, inherited from whatever the final
- setting of that value is in the main_server.)</li>
+ main server. (That is, inherited from whatever the final
+ setting of that value is in the main server.)</li>
<li>The "lookup defaults" that define the default directory
permissions for a vhost are merged with those of the
- main_server. This includes any per-directory configuration
+ main server. This includes any per-directory configuration
information for any module.</li>
<li>The per-server configs for each module from the
- main_server are merged into the vhost server.</li>
+ main server are merged into the vhost server.</li>
</ol>
- <p>Essentially, the main_server is treated as "defaults" or a
+ <p>Essentially, the main server is treated as "defaults" or a
"base" on which to build each vhost. But the positioning of
- these main_server definitions in the config file is largely
- irrelevant -- the entire config of the main_server has been
- parsed when this final merging occurs. So even if a main_server
+ these main server definitions in the config file is largely
+ irrelevant -- the entire config of the main server has been
+ parsed when this final merging occurs. So even if a main server
definition appears after a vhost definition it might affect the
vhost definition.</p>
- <p>If the main_server has no <code>ServerName</code> at this
+ <p>If the main server has no <code>ServerName</code> at this
point, then the hostname of the machine that <code class="program"><a href="../programs/httpd.html">httpd</a></code>
- is running on is used instead. We will call the <em>main_server address
+ is running on is used instead. We will call the <em>main server address
set</em> those IP addresses returned by a DNS lookup on the
- <code>ServerName</code> of the main_server.</p>
+ <code>ServerName</code> of the main server.</p>
<p>For any undefined <code>ServerName</code> fields, a
name-based vhost defaults to the address given first in the
<p>Any vhost that includes the magic <code>_default_</code>
wildcard is given the same <code>ServerName</code> as the
- main_server.</p>
+ main server.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<p>The server determines which vhost to use for a request as
follows:</p>
- <h3><a name="hashtable" id="hashtable">Hash table lookup</a></h3>
+ <h3><a name="hashtable" id="hashtable">IP address lookup</a></h3>
+
+ <p>When the connection is first received on some address and port,
+ the server looks for all the <code>VirtualHost</code> definitions
+ that have the same IP address and port.</p>
- <p>When the connection is first made by a client, the IP
- address to which the client connected is looked up in the
- internal IP hash table.</p>
+ <p>If there are no exact matches for the address and port, then
+ wildcard (<code>*</code>) matches are considered.</p>
- <p>If the lookup fails (the IP address wasn't found) the
- request is served from the <code>_default_</code> vhost if
- there is such a vhost for the port to which the client sent the
- request. If there is no matching <code>_default_</code> vhost
- the request is served from the main_server.</p>
+ <p>If there are still no matches, then vhosts with IP
+ address specified as <code>_default_</code> that match the
+ port are considered.</p>
- <p>If the IP address is not found in the hash table then the
- match against the port number may also result in an entry
- corresponding to a <code>NameVirtualHost *</code>, which is
- subsequently handled like other name-based vhosts.</p>
+ <p>If no matches are found, the request is served by the
+ main server.</p>
- <p>If the lookup succeeded (a corresponding list for the IP
- address was found) the next step is to decide if we have to
- deal with an IP-based or a name-base vhost.</p>
+ <p>If there are <code>VirtualHost</code> definitions for
+ the IP address, the next step is to decide if we have to
+ deal with an IP-based or a name-based vhost.</p>
<h3><a name="ipbased" id="ipbased">IP-based vhost</a></h3>
- <p>If the entry we found has an empty name list then we have
- found an IP-based vhost, no further actions are performed and
- the request is served from that vhost.</p>
+ <p>If there is no <code>NameVirtualHost</code> directive
+ matching the vhost, no further actions are performed and
+ the request is served from the first matching vhost.</p>
<h3><a name="namebased" id="namebased">Name-based vhost</a></h3>
- <p>If the entry corresponds to a name-based vhost the name list
- contains one or more vhost structures. This list contains the
- vhosts in the same order as the <code>VirtualHost</code>
- directives appear in the config file.</p>
-
- <p>The first vhost on this list (the first vhost in the config
- file with the specified IP address) has the highest priority
- and catches any request to an unknown server name or a request
- without a <code>Host:</code> header field.</p>
-
- <p>If the client provided a <code>Host:</code> header field the
- list is searched for a matching vhost and the first hit on a
- <code>ServerName</code> or <code>ServerAlias</code> is taken
- and the request is served from that vhost. A <code>Host:</code>
- header field can contain a port number, but Apache always
+ <p>If the entry corresponds to a name-based vhost, the "list" in
+ the remaining steps refers to the list of vhosts that matched, in
+ the order they were in the configuration file.</p>
+
+ <p>If the connection is using SSL, the server supports <a class="glossarylink" href="../glossary.html#servernameindication" title="see glossary">Server Name Indication</a>, and
+ the SSL client handshake includes the TLS extension with the
+ requested hostname, then that hostname is used below just like the
+ <code>Host:</code> header would be used on a non-SSL connection.
+ Otherwise, the first name-based vhost whose address matched is
+ used for SSL connections. This is significant because the
+ vhost determines which certificate the server will use for the
+ connection.</p>
+
+ <p>If the request contains a <code>Host:</code> header field, the
+ list is searched for the first vhost with a matching
+ <code>ServerName</code> or <code>ServerAlias</code>, and the
+ request is served from that vhost. A <code>Host:</code> header
+ field can contain a port number, but Apache always ignores it and
matches against the real port to which the client sent the
request.</p>
- <p>If the client submitted a HTTP/1.0 request without
- <code>Host:</code> header field we don't know to what server
- the client tried to connect to. In this case, the first virtual host
- (that is, the one listed first in the server configuration file) for
- the IP address and port to which the client connected, is
- used to serve this request.</p>
+ <p>The first vhost in the config
+ file with the specified IP address has the highest priority
+ and catches any request to an unknown server name, or a request
+ without a <code>Host:</code> header field (such as a HTTP/1.0
+ request).</p>
<h3><a name="persistent" id="persistent">Persistent connections</a></h3>
- <p>The IP lookup described above is only done <em>once</em> for a
- particular TCP/IP session while the name lookup is done on
+ <p>The <em>IP lookup</em> described above is only done <em>once</em> for a
+ particular TCP/IP session while the <em>name lookup</em> is done on
<em>every</em> request during a KeepAlive/persistent
- connection. In other words a client may request pages from
+ connection. In other words, a client may request pages from
different name-based vhosts during a single persistent
connection.</p>
configuration file has the highest priority for its
corresponding address set.</li>
- <li>The <code>Host:</code> header field is never used during the
+ <li>Any port in the <code>Host:</code> header field is never used during the
matching process. Apache always uses the real port to which
the client sent the request.</li>
extension of the "best match" principle, as a specific and exact match
is favored over a wildcard.</li>
- <li>The main_server is only used to serve a request if the IP
- address and port number to which the client connected is
- unspecified and does not match any other vhost (including a
- <code>_default_</code> vhost). In other words the main_server
+ <li>The main server is only used to serve a request if the IP
+ address and port number to which the client connected
+ does not match any vhost (including a
+ <code>_default_</code> vhost). In other words, the main server
only catches a request for an unspecified address/port
combination (unless there is a <code>_default_</code> vhost
which matches that port).</li>
- <li>A <code>_default_</code> vhost or the main_server is
+ <li>A <code>_default_</code> vhost or the main server is
<em>never</em> matched for a request with an unknown or
missing <code>Host:</code> header field if the client
connected to an address (and port) which is used for
some further tips:</p>
<ul>
- <li>Place all main_server definitions before any
+ <li>Place all main server definitions before any
<code>VirtualHost</code> definitions. (This is to aid the
readability of the configuration -- the post-config merging
process makes it non-obvious that definitions mixed in around
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 420990:931520 (outdated) -->
+<!-- English Revision: 420990:987254 (outdated) -->
<!-- French translation by Vincent Deffontaines, review by alain B -->
<!-- Updated by Lucien Gentis -->
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 105989:931520 (outdated) -->
+<!-- English Revision: 105989:987254 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 420990:931520 (outdated) -->
+<!-- English Revision: 420990:987254 (outdated) -->
<!-- =====================================================
Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
Reviewed by: Orhan Berent <berent belgeler.org>
<h2><a name="requirements" id="requirements">System requirements</a></h2>
<p>As the term <cite>IP-based</cite> indicates, the server
- <strong>must have a different IP address for each IP-based
+ <strong>must have a different IP address/port combination for each IP-based
virtual host</strong>. This can be achieved by the machine
having several physical network connections, or by use of
virtual interfaces which are supported by most modern operating
systems (see system documentation for details, these are
frequently called "ip aliases", and the "ifconfig" command is
- most commonly used to set them up).</p>
+ most commonly used to set them up), and/or using multiple
+ port numbers.</p>
+
+ <p>In many cases, <a href="name-based.html">name-based
+ virtual hosts</a> are more convenient, because they allow
+ many virtual hosts to share a single address/port.
+ See <a href="name-based.html#namevip">Name-based vs. IP-based
+ Virtual Hosts</a> to help you decide.
+ </p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- English Revision: 752951 -->
+<!-- English Revision: 752951:987242 (outdated) -->
<!-- French translation by alain B, review by Vincent Deffontaines -->
<!--
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 659902:752951 (outdated) -->
+<!-- English Revision: 659902:987242 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 105989:752951 (outdated) -->
+<!-- English Revision: 105989:987242 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<variants>
<variant>en</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
<variant outdated="yes">ja</variant>
<variant outdated="yes">ko</variant>
- <variant>tr</variant>
+ <variant outdated="yes">tr</variant>
</variants>
</metafile>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 752951 -->
+<!-- English Revision: 752951:987242 (outdated) -->
<!-- =====================================================
Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
Reviewed by: Orhan Berent <berent belgeler.org>
<div class="section">
<h2><a name="namevip" id="namevip">Name-based vs. IP-based Virtual Hosts</a></h2>
- <p>IP-based virtual hosts use the IP address of the connection to
+ <p><a href="ip-based.html">IP-based virtual hosts</a> use the IP address of the connection to
determine the correct virtual host to serve. Therefore you need to
- have a separate IP address for each host. With name-based virtual
+ have a separate IP address for each host.</p>
+
+ <p>With name-based virtual
hosting, the server relies on the client to report the hostname as
part of the HTTP headers. Using this technique, many different hosts
can share the same IP address.</p>
using IP-based virtual hosting:</p>
<ul>
- <li>Name-based virtual hosting cannot be used with SSL secure servers
+ <li>Name-based virtual hosting often <a href="../ssl/ssl_faq.html#vhosts">
+ cannot be used with SSL secure servers</a>
because of the nature of the SSL protocol.</li>
<li>Some operating systems and network equipment implement bandwidth
<p>To use name-based virtual hosting, you must designate the IP
address (and possibly port) on the server that will be accepting
- requests for the hosts. This is configured using the <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code> directive.
+ requests that need to be distinguished by hostname.
+ This is configured using the <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code> directive.
In the normal case where any and all IP addresses on the server should
be used, you can use <code>*</code> as the argument to <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code>. If you're planning to use
multiple ports (e.g. running SSL) you should add a Port to the argument,
- such as <code>*:80</code>. Note that mentioning an IP address in a
+ such as <code>*:80</code>.</p>
+
+ <div class="note"><p>Note that mentioning an IP address in a
<code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code> directive does not
- automatically make the server listen to that IP address. See
+ automatically make the server <em>listen</em> to that IP address. See
<a href="../bind.html">Setting which addresses and ports Apache uses</a>
for more details. In addition, any IP address specified here must be
- associated with a network interface on the server.</p>
+ associated with a network interface on the server.</p></div>
<p>The next step is to create a <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> block for
each different host that you would like to serve. The argument to the
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.de.xsl"?>
-<!-- English Revision: 420990:930608 (outdated) -->
+<!-- English Revision: 420990:987242 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
-<!-- English Revision: 930608 -->
+<!-- English Revision: 930608:987242 (outdated) -->
<!-- French translation by alain B, review by Vincent Deffontaines
updated by Lucien GENTIS -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
-<!-- English Revision: 420990:930608 (outdated) -->
+<!-- English Revision: 420990:987242 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<?xml version='1.0' encoding='EUC-KR' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ko.xsl"?>
-<!-- English Revision: 420990:930608 (outdated) -->
+<!-- English Revision: 420990:987242 (outdated) -->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
<variants>
<variant outdated="yes">de</variant>
<variant>en</variant>
- <variant>fr</variant>
+ <variant outdated="yes">fr</variant>
<variant outdated="yes">ja</variant>
<variant outdated="yes">ko</variant>
<variant outdated="yes">tr</variant>
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.tr.xsl"?>
-<!-- English Revision: 659902:930608 (outdated) -->
+<!-- English Revision: 659902:987242 (outdated) -->
<!-- =====================================================
Translated by: Nilgün Belma Bugüner <nilgun belgeler.org>
Reviewed by: Orhan Berent <berent belgeler.org>
projects / apache / commitdiff