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 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="mod_authn_core">AuthType</directive>
51 <directive module="mod_authn_core">AuthName</directive>
52 <directive module="mod_authn_file">AuthUserFile</directive>
53 <directive module="mod_authz_groupfile">AuthGroupFile</directive>
54 <directive module="mod_authz_core">Require</directive>
61 <title>What they are/How to use them</title>
63 <p><code>.htaccess</code> files (or "distributed configuration files")
64 provide a way to make configuration changes on a per-directory basis. A
65 file, containing one or more configuration directives, is placed in a
66 particular document directory, and the directives apply to that
67 directory, and all subdirectories thereof.</p>
69 <note><title>Note:</title>
70 <p>If you want to call your <code>.htaccess</code> file something
71 else, you can change the name of the file using the <directive
72 module="core">AccessFileName</directive> directive. For example,
73 if you would rather call the file <code>.config</code> then you
74 can put the following in your server configuration file:</p>
77 AccessFileName .config
81 <p>In general, <code>.htaccess</code> files use the same syntax as
82 the <a href="../configuring.html#syntax">main configuration
83 files</a>. What you can put in these files is determined by the
84 <directive module="core">AllowOverride</directive> directive. This
85 directive specifies, in categories, what directives will be
86 honored if they are found in a <code>.htaccess</code> file. If a
87 directive is permitted in a <code>.htaccess</code> file, the
88 documentation for that directive will contain an Override section,
89 specifying what value must be in <directive
90 module="core">AllowOverride</directive> in order for that
91 directive to be permitted.</p>
93 <p>For example, if you look at the documentation for the <directive
94 module="core">AddDefaultCharset</directive>
95 directive, you will find that it is permitted in <code>.htaccess</code>
96 files. (See the Context line in the directive summary.) The <a
97 href="../mod/directive-dict.html#Context">Override</a> line reads
98 <code>FileInfo</code>. Thus, you must have at least
99 <code>AllowOverride FileInfo</code> in order for this directive to be
100 honored in <code>.htaccess</code> files.</p>
102 <example><title>Example:</title>
106 href="../mod/directive-dict.html#Context">Context:</a></td>
107 <td>server config, virtual host, directory, .htaccess</td>
112 href="../mod/directive-dict.html#Override">Override:</a></td>
118 <p>If you are unsure whether a particular directive is permitted in a
119 <code>.htaccess</code> file, look at the documentation for that
120 directive, and check the Context line for ".htaccess".</p>
123 <section id="when"><title>When (not) to use .htaccess files</title>
125 <p>In general, you should never use <code>.htaccess</code> files unless
126 you don't have access to the main server configuration file. There is,
127 for example, a prevailing misconception that user authentication should
128 always be done in <code>.htaccess</code> files. This is simply not the
129 case. You can put user authentication configurations in the main server
130 configuration, and this is, in fact, the preferred way to do
133 <p><code>.htaccess</code> files should be used in a case where the
134 content providers need to make configuration changes to the server on a
135 per-directory basis, but do not have root access on the server system.
136 In the event that the server administrator is not willing to make
137 frequent configuration changes, it might be desirable to permit
138 individual users to make these changes in <code>.htaccess</code> files
139 for themselves. This is particularly true, for example, in cases where
140 ISPs are hosting multiple user sites on a single machine, and want
141 their users to be able to alter their configuration.</p>
143 <p>However, in general, use of <code>.htaccess</code> files should be
144 avoided when possible. Any configuration that you would consider
145 putting in a <code>.htaccess</code> file, can just as effectively be
146 made in a <directive module="core"
147 type="section">Directory</directive> section in your main server
148 configuration file.</p>
150 <p>There are two main reasons to avoid the use of
151 <code>.htaccess</code> files.</p>
153 <p>The first of these is performance. When <directive
154 module="core">AllowOverride</directive>
155 is set to allow the use of <code>.htaccess</code> files, Apache will
156 look in every directory for <code>.htaccess</code> files. Thus,
157 permitting <code>.htaccess</code> files causes a performance hit,
158 whether or not you actually even use them! Also, the
159 <code>.htaccess</code> file is loaded every time a document is
162 <p>Further note that Apache must look for <code>.htaccess</code> files
163 in all higher-level directories, in order to have a full complement of
164 directives that it must apply. (See section on <a href="#how">how
165 directives are applied</a>.) Thus, if a file is requested out of a
166 directory <code>/www/htdocs/example</code>, Apache must look for the
172 /www/htdocs/.htaccess<br />
173 /www/htdocs/example/.htaccess
176 <p>And so, for each file access out of that directory, there are 4
177 additional file-system accesses, even if none of those files are
178 present. (Note that this would only be the case if
179 <code>.htaccess</code> files were enabled for <code>/</code>, which
180 is not usually the case.)</p>
182 <p>The second consideration is one of security. You are permitting
183 users to modify server configuration, which may result in changes over
184 which you have no control. Carefully consider whether you want to give
185 your users this privilege. Note also that giving users less
186 privileges than they need will lead to additional technical support
187 requests. Make sure you clearly tell your users what level of
188 privileges you have given them. Specifying exactly what you have set
189 <directive module="core">AllowOverride</directive> to, and pointing them
190 to the relevant documentation, will save yourself a lot of confusion
193 <p>Note that it is completely equivalent to put a <code>.htaccess</code>
194 file in a directory <code>/www/htdocs/example</code> containing a
195 directive, and to put that same directive in a Directory section
196 <code><Directory /www/htdocs/example></code> in your main server
199 <p><code>.htaccess</code> file in <code>/www/htdocs/example</code>:</p>
201 <example><title>Contents of .htaccess file in
202 <code>/www/htdocs/example</code></title>
203 AddType text/example .exm
206 <example><title>Section from your <code>httpd.conf</code>
208 <Directory /www/htdocs/example><br />
210 AddType text/example .exm<br />
215 <p>However, putting this configuration in your server configuration
216 file will result in less of a performance hit, as the configuration is
217 loaded once when Apache starts, rather than every time a file is
220 <p>The use of <code>.htaccess</code> files can be disabled completely
221 by setting the <directive module="core">AllowOverride</directive>
222 directive to <code>none</code>:</p>
229 <section id="how"><title>How directives are applied</title>
231 <p>The configuration directives found in a <code>.htaccess</code> file
232 are applied to the directory in which the <code>.htaccess</code> file
233 is found, and to all subdirectories thereof. However, it is important
234 to also remember that there may have been <code>.htaccess</code> files
235 in directories higher up. Directives are applied in the order that they
236 are found. Therefore, a <code>.htaccess</code> file in a particular
237 directory may override directives found in <code>.htaccess</code> files
238 found higher up in the directory tree. And those, in turn, may have
239 overridden directives found yet higher up, or in the main server
240 configuration file itself.</p>
244 <p>In the directory <code>/www/htdocs/example1</code> we have a
245 <code>.htaccess</code> file containing the following:</p>
251 <p>(Note: you must have "<code>AllowOverride Options</code>" in effect
252 to permit the use of the "<directive
253 module="core">Options</directive>" directive in
254 <code>.htaccess</code> files.)</p>
256 <p>In the directory <code>/www/htdocs/example1/example2</code> we have
257 a <code>.htaccess</code> file containing:</p>
263 <p>Because of this second <code>.htaccess</code> file, in the directory
264 <code>/www/htdocs/example1/example2</code>, CGI execution is not
265 permitted, as only <code>Options Includes</code> is in effect, which
266 completely overrides any earlier setting that may have been in
269 <section id="merge"><title>Merging of .htaccess with the main
270 configuration files</title>
272 <p>As discussed in the documentation on <a
273 href="../sections.html">Configuration Sections</a>,
274 <code>.htaccess</code> files can override the <directive
275 type="section" module="core">Directory</directive> sections for
276 the corresponding directory, but will be overriden by other types
277 of configuration sections from the main configuration files. This
278 fact can be used to enforce certain configurations, even in the
279 presence of a liberal <directive
280 module="core">AllowOverride</directive> setting. For example, to
281 prevent script execution while allowing anything else to be set in
282 <code>.htaccess</code> you can use:</p>
285 <Directory /><br />
287 Allowoverride All<br />
289 </Directory><br />
291 <Location /><br />
293 Options +IncludesNoExec -ExecCGI<br />
301 <section id="auth"><title>Authentication example</title>
303 <p>If you jumped directly to this part of the document to find out how
304 to do authentication, it is important to note one thing. There is a
305 common misconception that you are required to use
306 <code>.htaccess</code> files in order to implement password
307 authentication. This is not the case. Putting authentication directives
308 in a <directive module="core" type="section">Directory</directive>
309 section, in your main server configuration file, is the preferred way
310 to implement this, and <code>.htaccess</code> files should be used only
311 if you don't have access to the main server configuration file. See <a
312 href="#when">above</a> for a discussion of when you should and should
313 not use <code>.htaccess</code> files.</p>
315 <p>Having said that, if you still think you need to use a
316 <code>.htaccess</code> file, you may find that a configuration such as
317 what follows may work for you.</p>
319 <p><code>.htaccess</code> file contents:</p>
323 AuthName "Password Required"<br />
324 AuthUserFile /www/passwords/password.file<br />
325 AuthGroupFile /www/passwords/group.file<br />
329 <p>Note that <code>AllowOverride AuthConfig</code> must be in effect
330 for these directives to have any effect.</p>
332 <p>Please see the <a href="auth.html">authentication tutorial</a> for a
333 more complete discussion of authentication and authorization.</p>
336 <section id="ssi"><title>Server Side Includes example</title>
338 <p>Another common use of <code>.htaccess</code> files is to enable
339 Server Side Includes for a particular directory. This may be done with
340 the following configuration directives, placed in a
341 <code>.htaccess</code> file in the desired directory:</p>
344 Options +Includes<br />
345 AddType text/html shtml<br />
346 AddHandler server-parsed shtml
349 <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
350 FileInfo</code> must both be in effect for these directives to have any
353 <p>Please see the <a href="ssi.html">SSI tutorial</a> for a more
354 complete discussion of server-side includes.</p>
357 <section id="cgi"><title>CGI example</title>
359 <p>Finally, you may wish to use a <code>.htaccess</code> file to permit
360 the execution of CGI programs in a particular directory. This may be
361 implemented with the following configuration:</p>
364 Options +ExecCGI<br />
365 AddHandler cgi-script cgi pl
368 <p>Alternately, if you wish to have all files in the given directory be
369 considered to be CGI programs, this may be done with the following
373 Options +ExecCGI<br />
374 SetHandler cgi-script
377 <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
378 FileInfo</code> must both be in effect for these directives to have any
381 <p>Please see the <a href="cgi.html">CGI tutorial</a> for a more
382 complete discussion of CGI programming and configuration.</p>
386 <section id="troubleshoot"><title>Troubleshooting</title>
388 <p>When you put configuration directives in a <code>.htaccess</code>
389 file, and you don't get the desired effect, there are a number of
390 things that may be going wrong.</p>
392 <p>Most commonly, the problem is that <directive
393 module="core">AllowOverride</directive> is not
394 set such that your configuration directives are being honored. Make
395 sure that you don't have a <code>AllowOverride None</code> in effect
396 for the file scope in question. A good test for this is to put garbage
397 in your <code>.htaccess</code> file and reload. If a server error is
398 not generated, then you almost certainly have <code>AllowOverride
399 None</code> in effect.</p>
401 <p>If, on the other hand, you are getting server errors when trying to
402 access documents, check your Apache error log. It will likely tell you
403 that the directive used in your <code>.htaccess</code> file is not
407 [Sat Aug 09 16:19:20 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteLog not allowed here
410 <p>This will indicate either that you've used a directive that is
411 never permitted in <code>.htaccess</code> files, or that you simply
412 don't have <directive module="core">AllowOverride</directive> set to
413 a level sufficient for the directive you've used. Consult the
414 documentation for that particular directive to determine which is
417 <p>Alternately, it may tell you that you had a syntax error in your
418 usage of the directive itself.</p>
421 [Sat Aug 09 16:22:34 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteCond: bad flag delimiters
424 <p>In this case, the error message should be specific to the
425 particular syntax error that you have committed.</p>