From: Daniel Gruno <humbedooh@apache.org>
Date: Fri, 20 Jul 2012 12:43:57 +0000 (+0000)
Subject: Backport a few changes from trunk that also apply to 2.2
X-Git-Tag: 2.2.23~111
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=53f3177f23b149c600e7135b49452b784010b019;p=thirdparty%2Fapache%2Fhttpd.git

Backport a few changes from trunk that also apply to 2.2

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@1363753 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/howto/htaccess.xml b/docs/manual/howto/htaccess.xml
index b97b8c78fc6..db86c23fa60 100644
--- a/docs/manual/howto/htaccess.xml
+++ b/docs/manual/howto/htaccess.xml
@@ -23,16 +23,15 @@
 <manualpage metafile="htaccess.xml.meta">
 <parentdocument href="./">How-To / Tutorials</parentdocument>
 
-<title>Apache Tutorial: .htaccess files</title>
+<title>Apache HTTP Server Tutorial: .htaccess files</title>
 
 <summary>
 <p><code>.htaccess</code> files provide a way to make configuration
 changes on a per-directory basis.</p>
 </summary>
 
-
 <section id="related"><title>.htaccess files</title>
-   <related>
+    <related>
         <modulelist>
             <module>core</module>
             <module>mod_authn_file</module>
@@ -48,20 +47,18 @@ changes on a per-directory basis.</p>
             <directive module="core">Options</directive>
             <directive module="mod_mime">AddHandler</directive>
             <directive module="core">SetHandler</directive>
-            <directive module="core">AuthType</directive>
-            <directive module="core">AuthName</directive>
+            <directive module="mod_authn_core">AuthType</directive>
+            <directive module="mod_authn_core">AuthName</directive>
             <directive module="mod_authn_file">AuthUserFile</directive>
             <directive module="mod_authz_groupfile">AuthGroupFile</directive>
-            <directive module="core">Require</directive>
+            <directive module="mod_authz_core">Require</directive>
         </directivelist>
 
     </related>
 
     <note>You should avoid using <code>.htaccess</code> files completely if you have access to
-    httpd main server config file. Using <code>.htaccess</code> files slows down your Apache server.
-    Any directive that you can include in a <code>.htaccess</code> file is 
-    better set in a <directive module="core">Directory</directive> block, 
-    as it will have the same effect with better performance.</note>
+    httpd main server config file. Using <code>.htaccess</code> files slows down your Apache http server.
+    Any directive that you can include in a <code>.htaccess</code> file is better set in a <directive module="core">Directory</directive> block, as it will have the same effect with better performance.</note>
 </section>
 
 <section id="what">
@@ -87,7 +84,7 @@ changes on a per-directory basis.</p>
 
     <p>In general, <code>.htaccess</code> files use the same syntax as
     the <a href="../configuring.html#syntax">main configuration
-    files</a>.  What you can put in these files is determined by the
+    files</a>. What you can put in these files is determined by the
     <directive module="core">AllowOverride</directive> directive. This
     directive specifies, in categories, what directives will be
     honored if they are found in a <code>.htaccess</code> file. If a
@@ -129,13 +126,16 @@ changes on a per-directory basis.</p>
 
     <section id="when"><title>When (not) to use .htaccess files</title>
 
-    <p>In general, you should never use <code>.htaccess</code> files unless
+    <p>In general, you should only use <code>.htaccess</code> files when
     you don't have access to the main server configuration file. There is,
-    for example, a prevailing misconception that user authentication should
-    always be done in <code>.htaccess</code> files. This is simply not the
+    for example, a common misconception that user authentication should
+    always be done in <code>.htaccess</code> files, and, in more recent years,
+    another miscomception that <module>mod_rewrite</module> directives
+    must go in <code>.htaccess</code> files. This is simply not the
     case. You can put user authentication configurations in the main server
     configuration, and this is, in fact, the preferred way to do
-    things.</p>
+    things. Likewise, <code>mod_rewrite</code> directives work better,
+    in many respects, in the main server configuration.</p>
 
     <p><code>.htaccess</code> files should be used in a case where the
     content providers need to make configuration changes to the server on a
@@ -159,18 +159,18 @@ changes on a per-directory basis.</p>
 
     <p>The first of these is performance. When <directive
     module="core">AllowOverride</directive>
-    is set to allow the use of <code>.htaccess</code> files, Apache will
+    is set to allow the use of <code>.htaccess</code> files, httpd will
     look in every directory for <code>.htaccess</code> files. Thus,
     permitting <code>.htaccess</code> files causes a performance hit,
     whether or not you actually even use them! Also, the
     <code>.htaccess</code> file is loaded every time a document is
     requested.</p>
 
-    <p>Further note that Apache must look for <code>.htaccess</code> files
+    <p>Further note that httpd must look for <code>.htaccess</code> files
     in all higher-level directories, in order to have a full complement of
     directives that it must apply. (See section on <a href="#how">how
     directives are applied</a>.) Thus, if a file is requested out of a
-    directory <code>/www/htdocs/example</code>, Apache must look for the
+    directory <code>/www/htdocs/example</code>, httpd must look for the
     following files:</p>
 
     <example>
@@ -186,6 +186,17 @@ changes on a per-directory basis.</p>
     <code>.htaccess</code> files were enabled for <code>/</code>, which
     is not usually the case.)</p>
 
+    <p>In the case of <directive
+    module="mod_rewrite">RewriteRule</directive> directives, in
+    <code>.htaccess</code> context these regular expressions must be
+    re-compiled with every request to the directory, whereas in main
+    server configuration context they are compiled once and cached.
+    Additionally, the rules themselves are more complicated, as one must
+    work around the restrictions that come with per-directory context
+    and <code>mod_rewrite</code>. Consult the <a
+    href="../rewrite/intro.html#htaccess">Rewrite Guide</a> for more
+    detail on this subject.</p>
+
     <p>The second consideration is one of security. You are permitting
     users to modify server configuration, which may result in changes over
     which you have no control. Carefully consider whether you want to give
@@ -207,7 +218,7 @@ changes on a per-directory basis.</p>
 
     <example><title>Contents of .htaccess file in
     <code>/www/htdocs/example</code></title>
-        AddType text/example .exm
+    <highlight language="config">AddType text/example .exm</highlight>
     </example>
 
     <example><title>Section from your <code>httpd.conf</code>
@@ -216,12 +227,12 @@ changes on a per-directory basis.</p>
       <indent>
         AddType text/example .exm<br />
       </indent>
-      &lt;/Directory&gt;
+&lt;/Directory&gt;
     </example>
 
     <p>However, putting this configuration in your server configuration
     file will result in less of a performance hit, as the configuration is
-    loaded once when Apache starts, rather than every time a file is
+    loaded once when httpd starts, rather than every time a file is
     requested.</p>
 
     <p>The use of <code>.htaccess</code> files can be disabled completely
@@ -281,10 +292,10 @@ changes on a per-directory basis.</p>
     <code>.htaccess</code> files can override the <directive
     type="section" module="core">Directory</directive> sections for
     the corresponding directory, but will be overriden by other types
-    of configuration sections from the main configuration files.  This
+    of configuration sections from the main configuration files. This
     fact can be used to enforce certain configurations, even in the
     presence of a liberal <directive
-    module="core">AllowOverride</directive> setting.  For example, to
+    module="core">AllowOverride</directive> setting. For example, to
     prevent script execution while allowing anything else to be set in
     <code>.htaccess</code> you can use:</p>
 
@@ -297,7 +308,7 @@ Allowoverride All<br />
 <br />
 &lt;Location /&gt;<br />
 <indent>
-Options +IncludesNoExec -ExecCGI<br />
+    Options +IncludesNoExec -ExecCGI<br />
 </indent>
 &lt;/Location&gt;
     </example>
@@ -330,7 +341,7 @@ Options +IncludesNoExec -ExecCGI<br />
       AuthName "Password Required"<br />
       AuthUserFile /www/passwords/password.file<br />
       AuthGroupFile /www/passwords/group.file<br />
-      Require Group admins
+Require Group admins
     </example>
 
     <p>Note that <code>AllowOverride AuthConfig</code> must be in effect
@@ -350,7 +361,7 @@ Options +IncludesNoExec -ExecCGI<br />
     <example>
        Options +Includes<br />
        AddType text/html shtml<br />
-       AddHandler server-parsed shtml
+AddHandler server-parsed shtml
     </example>
 
     <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
@@ -369,7 +380,7 @@ Options +IncludesNoExec -ExecCGI<br />
 
     <example>
        Options +ExecCGI<br />
-       AddHandler cgi-script cgi pl
+AddHandler cgi-script cgi pl
     </example>
 
     <p>Alternately, if you wish to have all files in the given directory be
@@ -378,7 +389,7 @@ Options +IncludesNoExec -ExecCGI<br />
 
     <example>
        Options +ExecCGI<br />
-       SetHandler cgi-script
+SetHandler cgi-script
     </example>
 
     <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
@@ -401,15 +412,35 @@ Options +IncludesNoExec -ExecCGI<br />
     set such that your configuration directives are being honored. Make
     sure that you don't have a <code>AllowOverride None</code> in effect
     for the file scope in question. A good test for this is to put garbage
-    in your <code>.htaccess</code> file and reload. If a server error is
+    in your <code>.htaccess</code> file and reload the page. If a server error is
     not generated, then you almost certainly have <code>AllowOverride
     None</code> in effect.</p>
 
     <p>If, on the other hand, you are getting server errors when trying to
-    access documents, check your Apache error log. It will likely tell you
+    access documents, check your httpd error log. It will likely tell you
     that the directive used in your <code>.htaccess</code> file is not
-    permitted. Alternately, it may tell you that you had a syntax error,
-    which you will then need to fix.</p>
+    permitted.</p>
+
+    <example>
+    [Fri Sep 17 18:43:16 2010] [alert] [client 192.168.200.51] /var/www/html/.htaccess: DirectoryIndex not allowed here
+    </example>
+
+    <p>This will indicate either that you've used a directive that is
+    never permitted in <code>.htaccess</code> files, or that you simply
+    don't have <directive module="core">AllowOverride</directive> set to
+    a level sufficient for the directive you've used. Consult the
+    documentation for that particular directive to determine which is
+    the case.</p>
+
+    <p>Alternately, it may tell you that you had a syntax error in your
+    usage of the directive itself.</p>
+
+    <example>
+    [Sat Aug 09 16:22:34 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteCond: bad flag delimiters
+    </example>
+
+    <p>In this case, the error message should be specific to the
+    particular syntax error that you have committed.</p>
 
 </section>
 
diff --git a/docs/manual/howto/public_html.xml b/docs/manual/howto/public_html.xml
index ea71a24dfb1..4d1f7687475 100644
--- a/docs/manual/howto/public_html.xml
+++ b/docs/manual/howto/public_html.xml
@@ -27,13 +27,22 @@
 
 <summary>
 <p>On systems with multiple users, each user can be permitted to have a
-    web site in their home directory using the <directive 
+    web site in their home directory using the <directive
     module="mod_userdir">UserDir</directive> directive. Visitors
     to a URL <code>http://example.com/~username/</code> will get content
     out of the home directory of the user "<code>username</code>", out of
     the subdirectory specified by the <directive
     module="mod_userdir">UserDir</directive> directive.</p>
-
+<p>Note that, by default, access to these directories is <strong>not</strong>
+    enabled. You can enable access when using <directive module="mod_userdir"
+    >UserDir</directive> by uncommenting the line</p>
+    <example>
+      #Include conf/extra/httpd-userdir.conf
+    </example>
+    <p>in the default config file, and adapting the <code
+    >httpd-userdir.conf</code>
+    file as necessary, or by including the appropriate directives in a
+    <code>Directory</code> block within the main config file.</p>
 </summary>
 
 <seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
@@ -100,30 +109,30 @@
       UserDir public_html /var/html
     </example>
 
-    <p>For the URL <code>http://example.com/~rbowen/file.html</code>, 
-    Apache will search for <code>~rbowen</code>. If it isn't found, 
+    <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
+    Apache will search for <code>~rbowen</code>. If it isn't found,
     Apache will search for <code>rbowen</code> in <code>/var/html</code>. If
-    found, the above URL will then be translated to the file path 
+    found, the above URL will then be translated to the file path
     <code>/var/html/rbowen/file.html</code></p>
 
   </section>
-  
+
   <section id="redirect">
     <title>Redirecting to external URLs</title>
     <p>The <directive module="mod_userdir">UserDir</directive> directive can be
       used to redirect user directory requests to external URLs.</p>
-      
+
     <example>
       UserDir http://example.org/users/*/
     </example>
-    
+
     <p>The above example will redirect a request for
     <code>http://example.com/~bob/abc.html</code> to
     <code>http://example.org/users/bob/abc.html</code>.</p>
   </section>
 
   <section id="enable">
-    <title>Restricting what users are permitted to use this 
+    <title>Restricting what users are permitted to use this
     feature</title>
 
     <p>Using the syntax shown in the UserDir documentation, you can restrict
@@ -160,7 +169,7 @@
       &lt;Directory /home/*/public_html/cgi-bin/&gt;<br />
        Options ExecCGI<br />
        SetHandler cgi-script<br />
-       &lt;/Directory&gt;
+&lt;/Directory&gt;
     </example>
 
     <p>Then, presuming that <code>UserDir</code> is set to