1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="htaccess.xml.meta">
24 <parentdocument href="./">How-To / Tutorials</parentdocument>
26 <title>Apache HTTP Server Tutorial: .htaccess files</title>
29 <p><code>.htaccess</code> files provide a way to make configuration
30 changes on a per-directory basis.</p>
33 <section id="related"><title>.htaccess files</title>
37 <module>mod_authn_file</module>
38 <module>mod_authz_groupfile</module>
39 <module>mod_cgi</module>
40 <module>mod_include</module>
41 <module>mod_mime</module>
45 <directive module="core">AccessFileName</directive>
46 <directive module="core">AllowOverride</directive>
47 <directive module="core">Options</directive>
48 <directive module="mod_mime">AddHandler</directive>
49 <directive module="core">SetHandler</directive>
50 <directive module="core">AuthType</directive>
51 <directive module="core">AuthName</directive>
52 <directive module="mod_authn_file">AuthUserFile</directive>
53 <directive module="mod_authz_groupfile">AuthGroupFile</directive>
54 <directive module="core">Require</directive>
59 <note>You should avoid using <code>.htaccess</code> files completely if you have access to
60 httpd main server config file. Using <code>.htaccess</code> files slows down your Apache http server.
61 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>
65 <title>What they are/How to use them</title>
67 <p><code>.htaccess</code> files (or "distributed configuration files")
68 provide a way to make configuration changes on a per-directory basis. A
69 file, containing one or more configuration directives, is placed in a
70 particular document directory, and the directives apply to that
71 directory, and all subdirectories thereof.</p>
73 <note><title>Note:</title>
74 <p>If you want to call your <code>.htaccess</code> file something
75 else, you can change the name of the file using the <directive
76 module="core">AccessFileName</directive> directive. For example,
77 if you would rather call the file <code>.config</code> then you
78 can put the following in your server configuration file:</p>
80 <highlight language="config">AccessFileName .config</highlight>
83 <p>In general, <code>.htaccess</code> files use the same syntax as
84 the <a href="../configuring.html#syntax">main configuration
85 files</a>. What you can put in these files is determined by the
86 <directive module="core">AllowOverride</directive> directive. This
87 directive specifies, in categories, what directives will be
88 honored if they are found in a <code>.htaccess</code> file. If a
89 directive is permitted in a <code>.htaccess</code> file, the
90 documentation for that directive will contain an Override section,
91 specifying what value must be in <directive
92 module="core">AllowOverride</directive> in order for that
93 directive to be permitted.</p>
95 <p>For example, if you look at the documentation for the <directive
96 module="core">AddDefaultCharset</directive>
97 directive, you will find that it is permitted in <code>.htaccess</code>
98 files. (See the Context line in the directive summary.) The <a
99 href="../mod/directive-dict.html#Context">Override</a> line reads
100 <code>FileInfo</code>. Thus, you must have at least
101 <code>AllowOverride FileInfo</code> in order for this directive to be
102 honored in <code>.htaccess</code> files.</p>
104 <example><title>Example:</title>
108 href="../mod/directive-dict.html#Context">Context:</a></td>
109 <td>server config, virtual host, directory, .htaccess</td>
114 href="../mod/directive-dict.html#Override">Override:</a></td>
120 <p>If you are unsure whether a particular directive is permitted in a
121 <code>.htaccess</code> file, look at the documentation for that
122 directive, and check the Context line for ".htaccess".</p>
125 <section id="when"><title>When (not) to use .htaccess files</title>
127 <p>In general, you should only use <code>.htaccess</code> files when
128 you don't have access to the main server configuration file. There is,
129 for example, a common misconception that user authentication should
130 always be done in <code>.htaccess</code> files, and, in more recent years,
131 another misconception that <module>mod_rewrite</module> directives
132 must go in <code>.htaccess</code> files. This is simply not the
133 case. You can put user authentication configurations in the main server
134 configuration, and this is, in fact, the preferred way to do
135 things. Likewise, <code>mod_rewrite</code> directives work better,
136 in many respects, in the main server configuration.</p>
138 <p><code>.htaccess</code> files should be used in a case where the
139 content providers need to make configuration changes to the server on a
140 per-directory basis, but do not have root access on the server system.
141 In the event that the server administrator is not willing to make
142 frequent configuration changes, it might be desirable to permit
143 individual users to make these changes in <code>.htaccess</code> files
144 for themselves. This is particularly true, for example, in cases where
145 ISPs are hosting multiple user sites on a single machine, and want
146 their users to be able to alter their configuration.</p>
148 <p>However, in general, use of <code>.htaccess</code> files should be
149 avoided when possible. Any configuration that you would consider
150 putting in a <code>.htaccess</code> file, can just as effectively be
151 made in a <directive module="core"
152 type="section">Directory</directive> section in your main server
153 configuration file.</p>
155 <p>There are two main reasons to avoid the use of
156 <code>.htaccess</code> files.</p>
158 <p>The first of these is performance. When <directive
159 module="core">AllowOverride</directive>
160 is set to allow the use of <code>.htaccess</code> files, httpd will
161 look in every directory for <code>.htaccess</code> files. Thus,
162 permitting <code>.htaccess</code> files causes a performance hit,
163 whether or not you actually even use them! Also, the
164 <code>.htaccess</code> file is loaded every time a document is
167 <p>Further note that httpd must look for <code>.htaccess</code> files
168 in all higher-level directories, in order to have a full complement of
169 directives that it must apply. (See section on <a href="#how">how
170 directives are applied</a>.) Thus, if a file is requested out of a
171 directory <code>/www/htdocs/example</code>, httpd must look for the
177 /www/htdocs/.htaccess<br />
178 /www/htdocs/example/.htaccess
181 <p>And so, for each file access out of that directory, there are 4
182 additional file-system accesses, even if none of those files are
183 present. (Note that this would only be the case if
184 <code>.htaccess</code> files were enabled for <code>/</code>, which
185 is not usually the case.)</p>
187 <p>In the case of <directive
188 module="mod_rewrite">RewriteRule</directive> directives, in
189 <code>.htaccess</code> context these regular expressions must be
190 re-compiled with every request to the directory, whereas in main
191 server configuration context they are compiled once and cached.
192 Additionally, the rules themselves are more complicated, as one must
193 work around the restrictions that come with per-directory context
194 and <code>mod_rewrite</code>. Consult the <a
195 href="../rewrite/intro.html#htaccess">Rewrite Guide</a> for more
196 detail on this subject.</p>
198 <p>The second consideration is one of security. You are permitting
199 users to modify server configuration, which may result in changes over
200 which you have no control. Carefully consider whether you want to give
201 your users this privilege. Note also that giving users less
202 privileges than they need will lead to additional technical support
203 requests. Make sure you clearly tell your users what level of
204 privileges you have given them. Specifying exactly what you have set
205 <directive module="core">AllowOverride</directive> to, and pointing them
206 to the relevant documentation, will save yourself a lot of confusion
209 <p>Note that it is completely equivalent to put a <code>.htaccess</code>
210 file in a directory <code>/www/htdocs/example</code> containing a
211 directive, and to put that same directive in a Directory section
212 <code><Directory /www/htdocs/example></code> in your main server
215 <p><code>.htaccess</code> file in <code>/www/htdocs/example</code>:</p>
217 <example><title>Contents of .htaccess file in
218 <code>/www/htdocs/example</code></title>
219 <highlight language="config">AddType text/example .exm</highlight>
222 <example><title>Section from your <code>httpd.conf</code>
224 <highlight language="config">
225 <Directory /www/htdocs/example>
226 AddType text/example .exm
231 <p>However, putting this configuration in your server configuration
232 file will result in less of a performance hit, as the configuration is
233 loaded once when httpd starts, rather than every time a file is
236 <p>The use of <code>.htaccess</code> files can be disabled completely
237 by setting the <directive module="core">AllowOverride</directive>
238 directive to <code>none</code>:</p>
240 <highlight language="config">AllowOverride None</highlight>
243 <section id="how"><title>How directives are applied</title>
245 <p>The configuration directives found in a <code>.htaccess</code> file
246 are applied to the directory in which the <code>.htaccess</code> file
247 is found, and to all subdirectories thereof. However, it is important
248 to also remember that there may have been <code>.htaccess</code> files
249 in directories higher up. Directives are applied in the order that they
250 are found. Therefore, a <code>.htaccess</code> file in a particular
251 directory may override directives found in <code>.htaccess</code> files
252 found higher up in the directory tree. And those, in turn, may have
253 overridden directives found yet higher up, or in the main server
254 configuration file itself.</p>
258 <p>In the directory <code>/www/htdocs/example1</code> we have a
259 <code>.htaccess</code> file containing the following:</p>
261 <highlight language="config">Options +ExecCGI</highlight>
263 <p>(Note: you must have "<code>AllowOverride Options</code>" in effect
264 to permit the use of the "<directive
265 module="core">Options</directive>" directive in
266 <code>.htaccess</code> files.)</p>
268 <p>In the directory <code>/www/htdocs/example1/example2</code> we have
269 a <code>.htaccess</code> file containing:</p>
271 <highlight language="config">Options Includes</highlight>
273 <p>Because of this second <code>.htaccess</code> file, in the directory
274 <code>/www/htdocs/example1/example2</code>, CGI execution is not
275 permitted, as only <code>Options Includes</code> is in effect, which
276 completely overrides any earlier setting that may have been in
279 <section id="merge"><title>Merging of .htaccess with the main
280 configuration files</title>
282 <p>As discussed in the documentation on <a
283 href="../sections.html">Configuration Sections</a>,
284 <code>.htaccess</code> files can override the <directive
285 type="section" module="core">Directory</directive> sections for
286 the corresponding directory, but will be overriden by other types
287 of configuration sections from the main configuration files. This
288 fact can be used to enforce certain configurations, even in the
289 presence of a liberal <directive
290 module="core">AllowOverride</directive> setting. For example, to
291 prevent script execution while allowing anything else to be set in
292 <code>.htaccess</code> you can use:</p>
294 <highlight language="config">
295 <Directory /www/htdocs>
300 Options +IncludesNoExec -ExecCGI<br />
304 <note>This example assumes that your <directive
305 module="core">DocumentRoot</directive> is <code>/www/htdocs</code>.</note>
310 <section id="auth"><title>Authentication example</title>
312 <p>If you jumped directly to this part of the document to find out how
313 to do authentication, it is important to note one thing. There is a
314 common misconception that you are required to use
315 <code>.htaccess</code> files in order to implement password
316 authentication. This is not the case. Putting authentication directives
317 in a <directive module="core" type="section">Directory</directive>
318 section, in your main server configuration file, is the preferred way
319 to implement this, and <code>.htaccess</code> files should be used only
320 if you don't have access to the main server configuration file. See <a
321 href="#when">above</a> for a discussion of when you should and should
322 not use <code>.htaccess</code> files.</p>
324 <p>Having said that, if you still think you need to use a
325 <code>.htaccess</code> file, you may find that a configuration such as
326 what follows may work for you.</p>
328 <p><code>.htaccess</code> file contents:</p>
330 <highlight language="config">
332 AuthName "Password Required"
333 AuthUserFile /www/passwords/password.file
334 AuthGroupFile /www/passwords/group.file
338 <p>Note that <code>AllowOverride AuthConfig</code> must be in effect
339 for these directives to have any effect.</p>
341 <p>Please see the <a href="auth.html">authentication tutorial</a> for a
342 more complete discussion of authentication and authorization.</p>
345 <section id="ssi"><title>Server Side Includes example</title>
347 <p>Another common use of <code>.htaccess</code> files is to enable
348 Server Side Includes for a particular directory. This may be done with
349 the following configuration directives, placed in a
350 <code>.htaccess</code> file in the desired directory:</p>
352 <highlight language="config">
354 AddType text/html shtml
355 AddHandler server-parsed shtml
358 <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
359 FileInfo</code> must both be in effect for these directives to have any
362 <p>Please see the <a href="ssi.html">SSI tutorial</a> for a more
363 complete discussion of server-side includes.</p>
366 <section id="cgi"><title>CGI example</title>
368 <p>Finally, you may wish to use a <code>.htaccess</code> file to permit
369 the execution of CGI programs in a particular directory. This may be
370 implemented with the following configuration:</p>
372 <highlight language="config">
374 AddHandler cgi-script cgi pl
377 <p>Alternately, if you wish to have all files in the given directory be
378 considered to be CGI programs, this may be done with the following
381 <highlight language="config">
383 SetHandler cgi-script
386 <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
387 FileInfo</code> must both be in effect for these directives to have any
390 <p>Please see the <a href="cgi.html">CGI tutorial</a> for a more
391 complete discussion of CGI programming and configuration.</p>
395 <section id="troubleshoot"><title>Troubleshooting</title>
397 <p>When you put configuration directives in a <code>.htaccess</code>
398 file, and you don't get the desired effect, there are a number of
399 things that may be going wrong.</p>
401 <p>Most commonly, the problem is that <directive
402 module="core">AllowOverride</directive> is not
403 set such that your configuration directives are being honored. Make
404 sure that you don't have a <code>AllowOverride None</code> in effect
405 for the file scope in question. A good test for this is to put garbage
406 in your <code>.htaccess</code> file and reload the page. If a server error is
407 not generated, then you almost certainly have <code>AllowOverride
408 None</code> in effect.</p>
410 <p>If, on the other hand, you are getting server errors when trying to
411 access documents, check your httpd error log. It will likely tell you
412 that the directive used in your <code>.htaccess</code> file is not
416 [Fri Sep 17 18:43:16 2010] [alert] [client 192.168.200.51] /var/www/html/.htaccess: DirectoryIndex not allowed here
419 <p>This will indicate either that you've used a directive that is
420 never permitted in <code>.htaccess</code> files, or that you simply
421 don't have <directive module="core">AllowOverride</directive> set to
422 a level sufficient for the directive you've used. Consult the
423 documentation for that particular directive to determine which is
426 <p>Alternately, it may tell you that you had a syntax error in your
427 usage of the directive itself.</p>
430 [Sat Aug 09 16:22:34 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteCond: bad flag delimiters
433 <p>In this case, the error message should be specific to the
434 particular syntax error that you have committed.</p>