286N/A<!
DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 286N/A <
title>Apache Tutorial: .htaccess files</
title>
286N/A <
body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080" 286N/A <
h1 align="CENTER">.htaccess files</
h1>
286N/A <
li><
a href="#what">What they
are/
How to use them</
a></
li>
286N/A <
li><
a href="#when">When (not) to use them</
a></
li>
286N/A <
li><
a href="#how">How directives are applied</
a></
li>
286N/A <
li><
a href="#auth">Authentication example</
a></
li>
286N/A <
li><
a href="#ssi">Server side includes</
a></
li>
286N/A <
li><
a href="#cgi">CGI</
a></
li>
286N/A <
li><
a href="#troubleshoot">Troubleshooting</
a></
li>
286N/A <
td valign="top"><
strong>Related Modules</
strong><
br />
286N/A <
td valign="top"><
strong>Related Directives</
strong><
br />
286N/A <
h2><
a id="what" name="what">What they
are/
How to use them</
a></
h2>
286N/A <
p>.htaccess files (or "distributed configuration files") provide a way
286N/A to make configuration changes on a per-directory basis. A file,
286N/A containing one or more configuration directives, is placed in a
286N/A particular document directory, and the directives apply to that
286N/A directory, and all subdirectories thereof.</
p>
286N/A <
p>Note: If you want to call your .htaccess file something else, you can
286N/A change the name of the file using the <
a 286N/A example, if you would rather call the file .config then you can put the
286N/A following in your server configuration file:</
p>
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>What you can put in these files is determined by the AllowOverride
286N/A directive. This directive specifies, in categories, what directives will
286N/A be honored if they are found in a .htaccess file. If a directive is
286N/A permitted in a .htaccess file, the documentation for that directive will
286N/A contain an Override section, specifying what value must be in
286N/A AllowOverride in order for that directive to be permitted.</
p>
286N/A <
p>For example, if you look at the docs for the <
a 286N/A directive, you will find that it is permitted in .htaccess files. (See
286N/A the Context line in the directive summary.) The <
a 286N/A "FileInfo". Thus, you must have at least "AllowOverride FileInfo" in
286N/A order for this directive to be honored in .htaccess files.</
p>
286N/A<
td>server config, virtual host, directory, .htaccess</
td></
tr>
286N/A <
p>If you are unsure whether a particular diretive is permitted in a
286N/A .htaccess file, look at the documentation for that directive, and check
286N/A the Context line for ".htaccess"</
p>
286N/A <
h2><
a id="when" name="when">When (not) to use .htaccess files</
a></
h2>
286N/A <
p>In general, you should never use .htaccess files unless you don't have
286N/A access to the main server configuration file. There is, for example, a
286N/A prevailing misconception that user authentication should always be done
286N/A in .htaccess files. This is simply not the case. You can put user
286N/A authentication configurations in the main server configuration, and this
286N/A is, in fact, the preferred way to do things.</
p>
286N/A <
p>.htaccess files should be used in a case where the content providers
286N/A need to make configuration changes to the server on a per-directory
286N/A basis, but do not have root access on the server system. In the event
286N/A that the server administrator is not willing to make frequent
286N/A configuration changes, it might be desirable to permit individual users
286N/A to make these changes in .htaccess files for themselves.</
p>
286N/A <
p>However, in general, use of .htaccess files should be avoided when
286N/A possible. Any configuration that you would consider putting in a
286N/A .htaccess file, can just as effectively be made in a <
a 286N/A section in your main server configuration file.</
p>
286N/A <
p>There are two main reasons to avoid the use of .htaccess files.</
p>
286N/A <
p>The first of these is performance. When AllowOverride is set to allow
286N/A the use of .htaccess files, Apache will look in every directory for
286N/A .htaccess files. Thus, permitting .htaccess files causes a performance
286N/A hit, whether or not you actually even use them! Also, the .htaccess file
286N/A is loaded every time a document is requested.</
p>
286N/A <
p>Further note that Apache must look for .htaccess files in all
286N/A higher-level directories, in order to have a full complement of
286N/A directives that it must apply. (See section on how directives are
286N/A applied, below.) Thus, if a file is requested out of a directory
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>And so, for each file access out of that directory, there are 4
286N/A additional file-system accesses, even if none of those files are present.
286N/A (Note that this would only be the case if .htaccess files were enabled
286N/A for /, which is not usually the case.)</
p>
286N/A <
p>The second consideration is one of security. You are permitting users
286N/A to modify server configuration, which may result in changes over which
286N/A you have no control. Carefully consider whether you want to give your
286N/A users this privilege.</
p>
286N/A <
p>Note that it is completely equivalent to put a .htaccess file in a
286N/A same directive in a Directory section <Directory
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>However, putting this configuration in your server configuration file
286N/A will result in less of a performance hit, as the configuration is loaded
286N/A once when Apache starts, rather than every time a file is requested.</
p>
286N/A <
p>The use of .htaccess files can be disabled completely by setting the
286N/A AllowOverride directive to "none"</
p>
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
h2><
a id="how" name="how">How directives are applied:</
a></
h2>
286N/A <
p>The configuration directives found in a .htaccess file are applied to
286N/A the directory in which the .htaccess file is found, and to all
286N/A subdirectories thereof. However, it is important to also remember that
286N/A there may have been .htaccess files in directories higher up. Directives
286N/A are applied in the order that they are found. Therefore, a .htaccess file
286N/A in a particular directory may override directives found in .htaccess
286N/A files found higher up in the directory tree. And those, in turn, may have
286N/A overriden directives found yet higher up, or in the main server
286N/A configuration file itself.</
p>
286N/A containing the following:</
p>
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>(Note: you must have "AllowOverride Options" in effect to permit the
286N/A use of the "Options" directive in .htaccess files.)</
p>
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>Because of this second .htaccess file, in the directory
286N/A Options Includes is in effect, which completely overrides any earlier
286N/A setting that may have been in place.</
p>
286N/A <
h2><
a id="auth" name="auth">Authentication example</
a></
h2>
286N/A <
p>If you jumped directly to this part of the document to find out how to
286N/A do authentication, it is important to note one thing. There is a common
286N/A misconception that you are required to use .htaccess files in order to
286N/A implement password authentication. This is not the case. Putting
286N/A authentication directives in a <Directory> section, in your main
286N/A server configuration file, is the preferred way to implement this, and
286N/A .htaccess files should be used only if you don't have access to the main
286N/A server configuration file. See above for a discussion of when you should
286N/A and should not use .htaccess files.</
p>
286N/A <
p>Having said that, if you still think you need to use a .htaccess file,
286N/A you may find that a configuration such as what follows may work for
286N/A <
p>You must have "AllowOverride AuthConfig" in effect for these
286N/A directives to be honored.</
p>
286N/A <
p>.htaccess file contents:</
p>
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A AuthName "Password Required"<
br>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>Note that AllowOverride AuthConfig must be in effect for these
286N/A directives to have any effect.</
p>
286N/A for a more complete discussion of authentication and authorization.</
p>
286N/A <
h2><
a id="ssi" name="ssi">SSI example</
a></
h2>
286N/A <
p>Another common use of .htaccess files is to enable Server Side
286N/A Includes for a particular directory. This may be done with the following
286N/A configuration directives, placed in a .htaccess file in the desired
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A AddHandler server-parsed shtml
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>Note that AllowOverride Options and AllowOverride FileInfo must both
286N/A be in effect for these directives to have any effect.</
p>
286N/A <
p>Please see the <
a href="ssi.html">SSI tutorial</
a> for a more
286N/A complete discussion of server-side includes.</
p>
286N/A <
h2><
a id="cgi" name="cgi">CGI example</
a></
h2>
286N/A <
p>Finally, you may wish to use a .htaccess file to permit the execution
286N/A of CGI programs in a particular directory. This may be implemented with
286N/A the following configuration:</
p>
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A AddHandler cgi-script cgi pl
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>Alternately, if you wish to have all files in the given directory be
286N/A considered to be CGI programs, this may be done with the following
286N/A<
blockquote><
table cellpadding="10"><
tr><
td bgcolor="#eeeeee"><
code>
286N/A</
code></
td></
tr></
table></
blockquote>
286N/A <
p>Note that AllowOverride Options must be in effect for these directives
286N/A to have any effect.</
p>
286N/A <
p>Please see the <
a href="cgi.html">CGI tutorial</
a> for a more
286N/A complete discussion of CGI programming and configuration.</
p>
286N/A <
h2><
a id="troubleshoot" name="troubleshoot">Troubleshooting</
a></
h2>
286N/A <
p>When you put configuration directives in a .htaccess file, and you
286N/A don't get the desired effect, there are a number of things that may be
286N/A <
p>Most commonly, the problem is that <
a 286N/A your configuration directives are being honored. Make sure that you don't
286N/A have a AllowOverride None in effect for the file scope in question. A
286N/A good test for this is to put garbage in your .htaccess file and reload.
286N/A If a server error is not generated, then you almost certainly have
286N/A AllowOverride None in effect.</
p>
286N/A <
p>If, on the other hand, you are getting server errors when trying to
286N/A access documents, check your Apache error log. It will likely tell you
286N/A that the directive used in your .htaccess file is not permitted.
286N/A Alternately, it may tell you that you had a syntax error, which you will