Backport a few changes from trunk that also apply to 2.2

<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>

        <modulelist>

            <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">

    <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

    <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>

    <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

    <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>

    <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

    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>

    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>