1 <?xml version="1.0" encoding="ISO-8859-1" ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision : 1030041 -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : Vincent Deffontaines -->
9 Licensed to the Apache Software Foundation (ASF) under one or more
10 contributor license agreements. See the NOTICE file distributed with
11 this work for additional information regarding copyright ownership.
12 The ASF licenses this file to You under the Apache License, Version 2.0
13 (the "License"); you may not use this file except in compliance with
14 the License. You may obtain a copy of the License at
16 http://www.apache.org/licenses/LICENSE-2.0
18 Unless required by applicable law or agreed to in writing, software
19 distributed under the License is distributed on an "AS IS" BASIS,
20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 See the License for the specific language governing permissions and
22 limitations under the License.
25 <manualpage metafile="htaccess.xml.meta">
26 <parentdocument href="./">Recettes / Tutoriels</parentdocument>
28 <title>Tutoriel Apache : fichiers .htaccess</title>
31 <p>Les fichiers <code>.htaccess</code> fournissent une méthode pour
32 modifier la configuration du serveur au niveau de chaque répertoire.</p>
35 <section id="related"><title>Fichiers .htaccess</title>
36 <note>Les fichiers <code>.htaccess</code> ne doivent être utilisés
37 que si vous n'avez pas accès au fichier de configuration du serveur
38 principal. L'utilisation des fichiers <code>.htaccess</code>
39 ralentit le fonctionnement de votre serveur Apache. Il est toujours
40 préférable de définir les directives que vous pouvez inclure dans un
41 fichier <code>.htaccess</code> dans une section <directive
42 module="core">Directory</directive>, car elles produiront le
43 même effet avec de meilleures performances.</note>
47 <module>mod_authn_file</module>
48 <module>mod_authz_groupfile</module>
49 <module>mod_cgi</module>
50 <module>mod_include</module>
51 <module>mod_mime</module>
55 <directive module="core">AccessFileName</directive>
56 <directive module="core">AllowOverride</directive>
57 <directive module="core">Options</directive>
58 <directive module="mod_mime">AddHandler</directive>
59 <directive module="core">SetHandler</directive>
60 <directive module="mod_authn_core">AuthType</directive>
61 <directive module="mod_authn_core">AuthName</directive>
62 <directive module="mod_authn_file">AuthUserFile</directive>
63 <directive module="mod_authz_groupfile">AuthGroupFile</directive>
64 <directive module="mod_authz_core">Require</directive>
71 <title>Que sont ce fichiers, comment les utiliser ?</title>
73 <p>Les fichiers <code>.htaccess</code> (ou "fichiers de
74 configuration distribués") fournissent une méthode pour modifier la
75 configuration du serveur au niveau d'un répertoire. Un fichier,
76 contenant une ou plusieurs directives de configuration, est placé
77 dans un répertoire de documents particulier, et ses directives
78 s'appliquent à ce répertoire et à tous ses sous-répertoires.</p>
80 <note><title>Note :</title>
81 <p>Si vous voulez donner un autre nom à votre fichier
82 <code>.htaccess</code>, vous pouvez le faire en utilisant la
83 directive <directive module="core">AccessFileName</directive>. Par
84 exemple, si vous préférez nommer votre fichier
85 <code>.config</code>, vous pouvez mettre ceci dans le fichier de
86 configuration de votre serveur :</p>
89 AccessFileName .config
93 <p>En général, les fichiers <code>.htaccess</code> utilisent la même
94 syntaxe que les <a href="../configuring.html#syntax">fichiers de
95 configuration principaux</a>. Ce que vous pouvez mettre dans ces
96 fichier est déterminé par la directive <directive
97 module="core">AllowOverride</directive>. Cette directive spécifie,
98 sous forme de catégories, quelles directives seront traitées si
99 elles se trouvent dans un fichier <code>.htaccess</code>. Si une
100 directive est permise dans un fichier <code>.htaccess</code> file,
101 la documentation de cette directive contiendra une section Override,
102 spécifiant quelle valeur doit prendre <directive
103 module="core">AllowOverride</directive> pour que cette directive
104 soit traitée.</p>
106 <p>Par exemple, si vous regardez la documentation de la directive
107 <directive module="core">AddDefaultCharset</directive>, vous verrez
108 que cette dernière est permise dans les fichiers
109 <code>.htaccess</code> (Voir la ligne de contexte dans le résumé de
110 la directive). La ligne <a
111 href="../mod/directive-dict.html#Context">Override</a> indique
112 <code>FileInfo</code>. Vous devez donc avoir au moins
113 <code>AllowOverride FileInfo</code> pour que cette directive soit
114 traitée dans les fichiers <code>.htaccess</code>.</p>
116 <example><title>Exemple :</title>
120 href="../mod/directive-dict.html#Context">Contexte :</a></td>
121 <td>configuration du serveur, serveur virtuel, directory, .htaccess</td>
126 href="../mod/directive-dict.html#Override">Override:</a></td>
132 <p>Si vous n'êtes pas sûr qu'une directive particulière soit permise
133 dans un fichier <code>.htaccess</code>, lisez la documentation de
134 cette directive, et consultez la ligne de contexte pour
138 <section id="when"><title>Quand doit-on (ne doit-on pas) utiliser
139 les fichiers .htaccess ?</title>
141 <p>En principe, vous ne devriez utiliser les fichiers
142 <code>.htaccess</code> que lorsque vous n'avez pas accès au fichier de
143 configuration du serveur principal. Par exemple, la fausse
145 selon laquelle l'authentification de l'utilisateur devrait toujours
146 être faite dans les fichiers <code>.htaccess</code> est très
147 répandue. Il est aussi souvent avancé, ces dernières
148 années, que les directives de <module>mod_rewrite</module> doivent
149 être définies dans les fichiers <code>.htaccess</code>. Ceci est
150 tout simplement faux. Vous pouvez configurer
151 l'authentification des utilisateurs au niveau de la configuration du
152 serveur principal, et c'est en fait cette méthode qui doit être
153 privilégiée. De même, les directives de
154 <code>mod_rewrite</code> fonctionneront mieux, à de nombreux égards,
155 dans le contexte du serveur principal.</p>
157 <p>Les fichiers <code>.htaccess</code> ne devraient être utilisés
158 que dans le cas où les fournisseurs de contenu ont besoin de
159 modifier la configuration du serveur au niveau d'un répertoire, mais
160 ne possèdent pas l'accès root sur le système du serveur. Si
161 l'administrateur du serveur ne souhaite pas effectuer des
162 modifications de configuration incessantes, il peut être intéressant
163 de permettre aux utilisateurs isolés d'effectuer eux-mêmes ces
164 modifications par le biais de fichiers <code>.htaccess</code>. Ceci
165 est particulièrement vrai dans le cas où le fournisseur d'accès à
166 Internet héberge de nombreux sites d'utilisateurs sur un seul
167 serveur, et souhaite que ces utilisateurs puissent modifier
168 eux-mêmes leurs configurations.</p>
170 <p>Cependant et d'une manière générale, il vaut mieux éviter
171 d'utiliser les fichiers <code>.htaccess</code>. Tout élément de
172 configuration que vous pourriez vouloir mettre dans un fichier
173 <code>.htaccess</code>, peut aussi être mis, et avec la même
174 efficacité, dans une section <directive module="core"
175 type="section">Directory</directive> du fichier de configuration de
176 votre serveur principal.</p>
178 <p>Il y a deux raisons principales d'éviter l'utilisation des
179 fichiers <code>.htaccess</code>.</p>
181 <p>La première est liée aux performances. Lorsque la directive
182 <directive module="core">AllowOverride</directive> est définie de
183 façon à autoriser l'utilisation des fichiers <code>.htaccess</code>,
184 Apache va rechercher leur présence dans chaque répertoire. Ainsi,
185 permettre l'utilisation des fichiers <code>.htaccess</code> est déjà
186 en soi une cause de dégradation des performances, que vous utilisiez
187 effectivement ces fichiers ou non ! De plus, le fichier
188 <code>.htaccess</code> est chargé en mémoire chaque fois qu'un
189 document fait l'objet d'une requête.</p>
191 <p>Notez aussi qu'Apache doit rechercher les fichiers
192 <code>.htaccess</code> dans tous les répertoires de niveau
193 supérieur, afin de rassembler toutes les directives qui s'appliquent
194 au répertoire courant (Voir la section <a href="#how">comment sont
195 appliquées les directives</a>). Ainsi, si un fichier fait l'objet
196 d'une requête à partir d'un répertoire
197 <code>/www/htdocs/exemple</code>, Apache doit rechercher les
198 fichiers suivants :</p>
203 /www/htdocs/.htaccess<br />
204 /www/htdocs/exemple/.htaccess
207 <p>En conséquence, chaque accès à un fichier de ce répertoire
208 nécessite 4 accès au système de fichiers supplémentaires pour
209 rechercher des fichiers <code>.htaccess</code>, même si
210 aucun de ces fichiers n'est présent. Notez que cet exemple ne peut
211 se produire que si les fichiers <code>.htaccess</code> ont été
212 autorisés pour le répertoire <code>/</code>, ce qui est rarement le
215 <p>La seconde raison d'éviter l'utilisation des fichiers
216 <code>.htaccess</code> est liée à la sécurité. Si vous permettez aux
217 utilisateurs de modifier la configuration du serveur, il peut en
218 résulter des conséquences sur lesquelles vous n'aurez aucun
219 contrôle. Réfléchissez bien avant de donner ce privilège à vos
220 utilisateurs. Notez aussi que ne pas donner aux utilisateurs les
221 privilèges dont ils ont besoin va entraîner une augmentation des
222 demandes de support technique. Assurez-vous d'avoir informé
223 clairement vos utilisateurs du niveau de privilèges que vous leur
224 avez attribué. Indiquer exactement comment vous avez défini la
225 directive <directive module="core">AllowOverride</directive> et
226 diriger les utilisateurs vers la documentation correspondante vous
227 évitera bien des confusions ultérieures.</p>
229 <p>Notez que mettre un fichier <code>.htaccess</code> contenant une
230 directive dans un répertoire <code>/www/htdocs/exemple</code>
231 revient exactement au même que mettre la même directive dans une
232 section Directory <code><Directory /www/htdocs/exemple></code>
233 du fichier de configuration de votre serveur principal :</p>
235 <p>Fichier <code>.htaccess</code> dans
236 <code>/www/htdocs/exemple</code> :</p>
238 <example><title>Contenu du fichier .htaccess dans
239 <code>/www/htdocs/exemple</code></title>
240 AddType text/exemple .exm
243 <example><title>Section de votre fichier
244 <code>httpd.conf</code></title>
245 <Directory /www/htdocs/exemple><br />
247 AddType text/exemple .exm<br />
252 <p>Cependant, la perte de performances sera moindre si vous
253 définissez cette directive dans la configuration de
254 votre serveur principal, car cette dernière ne sera chargée qu'une
255 seule fois au moment du démarrage du serveur, alors qu'elle le sera
256 à chaque accès dans le cas d'un fichier <code>.htaccess</code>.</p>
258 <p>L'utilisation des fichiers <code>.htaccess</code> peut être
259 entièrement désactivée en définissant la directive <directive
260 module="core">AllowOverride</directive> à <code>none</code> :</p>
267 <section id="how"><title>Comment sont appliquées les directives ?</title>
269 <p>Les directives de configuration situées dans un fichier
270 <code>.htaccess</code> s'appliquent au répertoire dans lequel ce
271 fichier <code>.htaccess</code> se trouve, ainsi qu'à tous ses
272 sous-répertoires. Cependant, il est important de garder à l'esprit
273 qu'il peut y avoir des fichiers <code>.htaccess</code> dans les
274 répertoires de niveau supérieur. Les directives sont appliquées
275 selon l'ordre dans lequel elles sont rencontrées. Ainsi, les
276 directives d'un fichier <code>.htaccess</code> situé dans un
277 répertoire particulier peuvent écraser les directives se trouvant
278 dans des fichiers <code>.htaccess</code> situés à un niveau
279 supérieur dans l'arborescence des répertoires. Et ces dernières
280 peuvent elles-mêmes avoir écrasé des directives d'un fichier
281 <code>.htaccess</code> situé à un niveau encore plus haut, ou dans
282 le fichier de configuration du serveur principal.</p>
286 <p>Dans le répertoire <code>/www/htdocs/exemple1</code> se trouve un
287 fichier <code>.htaccess</code> contenant ce qui suit :</p>
293 <p>Note : "<code>AllowOverride Options</code>" doit être présent
294 pour permettre l'utilisation de la directive "<directive
295 module="core">Options</directive>" dans les fichiers
296 <code>.htaccess</code>.</p>
298 <p>Dans le répertoire <code>/www/htdocs/exemple1/exemple2</code> se
299 trouve un fichier <code>.htaccess</code> contenant ce qui suit
306 <p>Ainsi, à cause de ce second fichier <code>.htaccess</code> du
307 répertoire <code>/www/htdocs/exemple1/exemple2</code>, l'exécution
308 des CGI est interdite, car la dernière définition d'options
309 <code>Options Includes</code> écrase toute autre définition
310 d'options d'un fichier <code>.htaccess</code> situé dans un
311 répertoire de niveau supérieur.</p>
313 <section id="merge"><title>Interactions entre les fichiers .htaccess
314 et les fichiers de configuration du serveur principal</title>
316 <p>Comme indiqué dans la documentation sur les <a
317 href="../sections.html">Sections de configuration</a>, les fichiers
318 <code>.htaccess</code> peuvent écraser les directives des sections
319 <directive type="section" module="core">Directory</directive> pour
320 le répertoire correspondant, mais peuvent eux-mêmes être écrasés
321 par d'autres types de sections des fichiers de la
322 configuration principale. Cette possibilité peut s'avérer utile pour
323 forcer certaines configurations, même en cas de présence de l'option
324 libérale <directive module="core">AllowOverride</directive>. Par
325 exemple, pour interdire l'exécution de scripts en autorisant la
326 définition de toute autre option dans les fichiers
327 <code>.htaccess</code>, vous pouvez utiliser :</p>
330 <Directory /www/htdocs><br />
332 Allowoverride All<br />
334 </Directory><br />
336 <Location /><br />
338 Options +IncludesNoExec -ExecCGI<br />
343 <note>Dans cet exemple, on considère que le chemin défini par la
344 directive <directive module="core">DocumentRoot</directive> est
345 <code>/www/htdocs</code>.</note>
350 <section id="auth"><title>Exemple d'authentification</title>
352 <p>Si vous accédez directement à ce point du document pour apprendre
353 à effectuer une authentification, il est important de noter ceci. Il
354 existe une fausse idée selon laquelle il serait nécessaire
355 d'utiliser les fichiers <code>.htaccess</code> pour implémenter
356 l'authentification par mot de passe. Ceci est tout simplement faux.
357 Pour y parvenir, il est préférable de mettre les directives
358 d'authentification dans une section <directive module="core"
359 type="section">Directory</directive> du fichier de configuration de
360 votre serveur principal, et les fichiers <code>.htaccess</code> ne
361 devraient être utilisés que dans le cas où vous n'avez pas accès au
362 fichier de configuration du serveur principal. Voir <a
363 href="#when">ci-dessus</a> pour savoir dans quels cas vous devez ou
364 ne devez pas utiliser les fichiers <code>.htaccess</code>.</p>
366 <p>Ceci étant dit, si vous pensez que vous devez quand-même utiliser
367 un fichier <code>.htaccess</code>, vous pouvez utiliser la
368 configuration suivante :</p>
370 <p>Contenu du fichier <code>.htaccess</code> :</p>
374 AuthName "Password Required"<br />
375 AuthUserFile /www/passwords/password.file<br />
376 AuthGroupFile /www/passwords/group.file<br />
380 <p>Notez que <code>AllowOverride AuthConfig</code> doit être présent
381 pour que ces directives produisent leur effet.</p>
383 <p>Vous pouvez vous référer au <a href="auth.html">tutoriel sur
384 l'authentification</a> pour une description plus détaillée de
385 l'authentification et de l'autorisation.</p>
388 <section id="ssi"><title>Exemple d'Inclusion Côté Serveur (Server Side
389 Includes - SSI)</title>
391 <p>Les fichiers <code>.htaccess</code> sont aussi couramment
392 utilisés pour activer les SSI pour un répertoire particulier. Pour y
393 parvenir, on utilise les directives de configuration suivantes,
394 placées dans un fichier <code>.htaccess</code> enregistré dans le
395 répertoire considéré :</p>
398 Options +Includes<br />
399 AddType text/html shtml<br />
400 AddHandler server-parsed shtml
403 <p>Notez que <code>AllowOverride Options</code> et <code>AllowOverride
404 FileInfo</code> doivent être tous les deux présents pour que ces
405 directives puissent produire leur effet.</p>
407 <p>Vous pouvez vous référer au <a href="ssi.html">tutoriel SSI</a>
408 pour une description plus détaillée des SSI.</p>
411 <section id="cgi"><title>Exemple de CGI</title>
413 <p>En fin de compte, vous avez décidé d'utiliser un fichier
414 <code>.htaccess</code> pour permettre l'exécution des programmes CGI
415 dans un répertoire particulier. Pour y parvenir, vous pouvez
416 utiliser la configuration suivante :</p>
419 Options +ExecCGI<br />
420 AddHandler cgi-script cgi pl
423 <p>Alternativement, si vous souhaitez que tous les fichiers d'un
424 répertoire donné soient considérés comme des programmes CGI, vous
425 pouvez utiliser la configuration suivante :</p>
428 Options +ExecCGI<br />
429 SetHandler cgi-script
432 <p>Notez que <code>AllowOverride Options</code> et <code>AllowOverride
433 FileInfo</code> doivent être tous les deux présents pour que ces
434 directives puissent produire leur effet.</p>
436 <p>Vous pouvez vous référer au <a href="cgi.html">tutoriel CGI</a>
437 pour une description plus détaillée de la configuration et de la
438 proprammation CGI.</p>
442 <section id="troubleshoot"><title>Résolution des problèmes</title>
444 <p>De nombreuses raisons peuvent être à l'origine du fait que
445 les directives que vous avez mises dans un fichier
446 <code>.htaccess</code> ne produisent pas l'effet désiré.</p>
448 <p>Le plus souvent, le problème vient du fait que la définition de
449 la directive <directive module="core">AllowOverride</directive>
450 ne permet pas l'activation des directives de votre fichier
451 <code>.htaccess</code>. Vérifiez si une directive
452 <code>AllowOverride None</code> n'affecte pas le répertoire où se
453 trouve votre fichier. Un bon test consiste à mettre des directives
454 dont la syntaxe est erronée dans votre ficher <code>.htaccess</code>
455 et de recharger la page. Si aucune erreur n'est générée par le
456 serveur, il est pratiquement certain qu'une directive
457 <code>AllowOverride None</code> affecte votre répertoire.</p>
459 <p>Par contre, si vous obtenez des erreurs de serveur lorsque vous
460 tentez d'accéder à des documents, consultez votre journal des
461 erreurs d'Apache. Il vous indiquera probablement que la directive
462 utilisée dans votre fichier <code>.htaccess</code> n'est pas
466 [Fri Sep 17 18:43:16 2010] [alert] [client 192.168.200.51] /var/www/html/.htaccess: DirectoryIndex not allowed here
468 <p>Cela signifie soit que vous utilisez une directive qui n'est
469 jamais permise dans les fichiers <code>.htaccess</code>, soit
470 que vous n'avez tout simplement pas défini la directive
471 <directive module="core">AllowOverride</directive> à un niveau
472 suffisant pour la directive que vous utilisez. Consultez la
473 documentation de cette directive pour déterminer quel cas
476 <p>Le journal des erreurs peut aussi vous signaler une erreur de
477 syntaxe dans l'usage de la directive elle-même.</p>
480 [Sat Aug 09 16:22:34 2008] [alert] [client 192.168.200.51] /var/www/html/.htaccess: RewriteCond: bad flag delimiters
483 <p>Dans ce cas, le message d'erreur sera spécifique à l'erreur
484 de syntaxe que vous avez commise.</p>