This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
-<title>Apache Tutorial: .htaccess files - Apache HTTP Server</title>
+<title>Apache HTTP Server Tutorial: .htaccess files - 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 rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
<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.2</a> > <a href="./">How-To / Tutorials</a></div><div id="page-content"><div id="preamble"><h1>Apache Tutorial: .htaccess files</h1>
+<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.2</a> > <a href="./">How-To / Tutorials</a></div><div id="page-content"><div id="preamble"><h1>Apache HTTP Server Tutorial: .htaccess files</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/howto/htaccess.html" title="English"> en </a> |
<a href="../fr/howto/htaccess.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="related" id="related">.htaccess files</a></h2>
- <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/core.html">core</a></code></li><li><code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code></li><li><code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code></li><li><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code></li><li><code class="module"><a href="../mod/mod_include.html">mod_include</a></code></li><li><code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/core.html#accessfilename">AccessFileName</a></code></li><li><code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code></li><li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li><li><code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code></li><li><code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code></li><li><code class="directive"><a href="../mod/core.html#authtype">AuthType</a></code></li><li><code class="directive"><a href="../mod/core.html#authname">AuthName</a></code></li><li><code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code></li><li><code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code></li><li><code class="directive"><a href="../mod/core.html#require">Require</a></code></li></ul></td></tr></table>
+ <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/core.html">core</a></code></li><li><code class="module"><a href="../mod/mod_authn_file.html">mod_authn_file</a></code></li><li><code class="module"><a href="../mod/mod_authz_groupfile.html">mod_authz_groupfile</a></code></li><li><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code></li><li><code class="module"><a href="../mod/mod_include.html">mod_include</a></code></li><li><code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/core.html#accessfilename">AccessFileName</a></code></li><li><code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code></li><li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li><li><code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code></li><li><code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code></li><li><code class="directive"><a href="../mod/mod_authn_core.html#authtype">AuthType</a></code></li><li><code class="directive"><a href="../mod/mod_authn_core.html#authname">AuthName</a></code></li><li><code class="directive"><a href="../mod/mod_authn_file.html#authuserfile">AuthUserFile</a></code></li><li><code class="directive"><a href="../mod/mod_authz_groupfile.html#authgroupfile">AuthGroupFile</a></code></li><li><code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code></li></ul></td></tr></table>
<div class="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 <code class="directive"><a href="../mod/core.html#directory">Directory</a></code> block,
- as it will have the same effect with better performance.</div>
+ 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 <code class="directive"><a href="../mod/core.html#directory">Directory</a></code> block, as it will have the same effect with better performance.</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="what" id="what">What they are/How to use them</a></h2>
<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
<code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> directive. This
directive specifies, in categories, what directives will be
honored if they are found in a <code>.htaccess</code> file. If a
<div class="section">
<h2><a name="when" id="when">When (not) to use .htaccess files</a></h2>
- <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 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> 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
<code>.htaccess</code> files.</p>
<p>The first of these is performance. When <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code>
- 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>
<div class="example"><p><code>
<code>.htaccess</code> files were enabled for <code>/</code>, which
is not usually the case.)</p>
+ <p>In the case of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> 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
<p><code>.htaccess</code> file in <code>/www/htdocs/example</code>:</p>
<div class="example"><h3>Contents of .htaccess file in
- <code>/www/htdocs/example</code></h3><p><code>
- AddType text/example .exm
- </code></p></div>
+ <code>/www/htdocs/example</code></h3><pre class="prettyprint lang-config">AddType text/example .exm</pre>
+</div>
<div class="example"><h3>Section from your <code>httpd.conf</code>
file</h3><p><code>
<span class="indent">
AddType text/example .exm<br />
</span>
- </Directory>
+</Directory>
</code></p></div>
<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
<p>As discussed in the documentation on <a href="../sections.html">Configuration Sections</a>,
<code>.htaccess</code> files can override the <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> 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 <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> setting. For example, to
+ presence of a liberal <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> setting. For example, to
prevent script execution while allowing anything else to be set in
<code>.htaccess</code> you can use:</p>
<br />
<Location /><br />
<span class="indent">
-Options +IncludesNoExec -ExecCGI<br />
+ Options +IncludesNoExec -ExecCGI<br />
</span>
</Location>
</code></p></div>
AuthName "Password Required"<br />
AuthUserFile /www/passwords/password.file<br />
AuthGroupFile /www/passwords/group.file<br />
- Require Group admins
+Require Group admins
</code></p></div>
<p>Note that <code>AllowOverride AuthConfig</code> must be in effect
<div class="example"><p><code>
Options +Includes<br />
AddType text/html shtml<br />
- AddHandler server-parsed shtml
+AddHandler server-parsed shtml
</code></p></div>
<p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
<div class="example"><p><code>
Options +ExecCGI<br />
- AddHandler cgi-script cgi pl
+AddHandler cgi-script cgi pl
</code></p></div>
<p>Alternately, if you wish to have all files in the given directory be
<div class="example"><p><code>
Options +ExecCGI<br />
- SetHandler cgi-script
+SetHandler cgi-script
</code></p></div>
<p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
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>
+
+ <div class="example"><p><code>
+ [Fri Sep 17 18:43:16 2010] [alert] [client 192.168.200.51] /var/www/html/.htaccess: DirectoryIndex not allowed here
+ </code></p></div>
+
+ <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 <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> 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>
+
+ <div class="example"><p><code>
+ [Sat Aug 09 16:22:34 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteCond: bad flag delimiters
+ </code></p></div>
+
+ <p>In this case, the error message should be specific to the
+ particular syntax error that you have committed.</p>
</div></div>
<div class="bottomlang">
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 <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code> directive.</p>
-
+<p>Note that, by default, access to these directories is <strong>not</strong>
+ enabled. You can enable access when using <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code> by uncommenting the line</p>
+ <div class="example"><p><code>
+ #Include conf/extra/httpd-userdir.conf
+ </code></p></div>
+ <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>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#related">Per-user web directories</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#userdir">Setting the file path with UserDir</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#redirect">Redirecting to external URLs</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#enable">Restricting what users are permitted to use this
+<li><img alt="" src="../images/down.gif" /> <a href="#enable">Restricting what users are permitted to use this
feature</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cgi">Enabling a cgi directory for each user</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#htaccess">Allowing users to alter configuration</a></li>
UserDir public_html /var/html
</code></p></div>
- <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>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<p>The <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code> directive can be
used to redirect user directory requests to external URLs.</p>
-
+
<div class="example"><p><code>
UserDir http://example.org/users/*/
</code></p></div>
-
+
<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>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
-<h2><a name="enable" id="enable">Restricting what users are permitted to use this
+<h2><a name="enable" id="enable">Restricting what users are permitted to use this
feature</a></h2>
<Directory /home/*/public_html/cgi-bin/><br />
Options ExecCGI<br />
SetHandler cgi-script<br />
- </Directory>
+</Directory>
</code></p></div>
<p>Then, presuming that <code>UserDir</code> is set to
projects / thirdparty / apache / httpd.git / commitdiff
