You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by hu...@apache.org on 2012/07/20 14:43:57 UTC
svn commit: r1363753 - in /httpd/httpd/branches/2.2.x/docs/manual/howto:
htaccess.xml public_html.xml
Author: humbedooh
Date: Fri Jul 20 12:43:57 2012
New Revision: 1363753
URL: http://svn.apache.org/viewvc?rev=1363753&view=rev
Log:
Backport a few changes from trunk that also apply to 2.2
Modified:
httpd/httpd/branches/2.2.x/docs/manual/howto/htaccess.xml
httpd/httpd/branches/2.2.x/docs/manual/howto/public_html.xml
Modified: httpd/httpd/branches/2.2.x/docs/manual/howto/htaccess.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/howto/htaccess.xml?rev=1363753&r1=1363752&r2=1363753&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/howto/htaccess.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/howto/htaccess.xml Fri Jul 20 12:43:57 2012
@@ -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>
- </Directory>
+</Directory>
</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 />
<Location /><br />
<indent>
-Options +IncludesNoExec -ExecCGI<br />
+ Options +IncludesNoExec -ExecCGI<br />
</indent>
</Location>
</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>
Modified: httpd/httpd/branches/2.2.x/docs/manual/howto/public_html.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/howto/public_html.xml?rev=1363753&r1=1363752&r2=1363753&view=diff
==============================================================================
--- httpd/httpd/branches/2.2.x/docs/manual/howto/public_html.xml (original)
+++ httpd/httpd/branches/2.2.x/docs/manual/howto/public_html.xml Fri Jul 20 12:43:57 2012
@@ -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 @@
<Directory /home/*/public_html/cgi-bin/><br />
Options ExecCGI<br />
SetHandler cgi-script<br />
- </Directory>
+</Directory>
</example>
<p>Then, presuming that <code>UserDir</code> is set to