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: 1654831:1673945 (outdated) -->
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="intro.xml.meta">
26 <parentdocument href="./">Rewrite</parentdocument>
28 <title>Introduction au module Apache mod_rewrite</title>
31 <p>Ce document est un complément à la <a
32 href="../mod/mod_rewrite.html">documentation de référence</a> du module
33 <module>mod_rewrite</module>. Il décrit les concepts de base dont la
34 connaissance est nécessaire pour l'utilisation de
35 <module>mod_rewrite</module>. D'autres documents entrent d'avantage dans
36 les détails, mais celui-ci devrait aider le débutant à se mouiller les
41 <seealso><a href="../mod/mod_rewrite.html">Documentation du
42 module mod_rewrite</a></seealso>
43 <!-- <seealso><a href="intro.html">Introduction à mod_rewrite</a></seealso> -->
44 <seealso><a href="remapping.html">Redirection and remise en
45 correspondance</a></seealso>
46 <seealso><a href="access.html">Contrôle d'accès</a></seealso>
47 <seealso><a href="vhosts.html">Serveurs virtuels</a></seealso>
48 <seealso><a href="proxy.html">Mise en cache</a></seealso>
49 <seealso><a href="rewritemap.html">Utilisation de RewriteMap</a></seealso>
50 <seealso><a href="advanced.html">Techniques avancées</a></seealso>
51 <seealso><a href="avoid.html">Quand ne pas utiliser mod_rewrite</a></seealso>
53 <section id="introduction"><title>Introduction</title>
54 <p>Le module Apache <module>mod_rewrite</module> est un module puissant
55 et sophistiqué qui permet la réécriture des URLs. Grâce à lui, vous
56 pouvez effectuer quasiment tous les types de réécriture d'URLs dont vous
57 avez besoin. Il est cependant assez complexe, et peut paraître
58 intimidant au débutant. Certains ont aussi tendance à traiter les
59 règles de réécriture comme des incantations magiques, et à les utiliser
60 sans vraiment comprendre leur manière d'agir.</p>
62 <p>Ce document a pour ambition d'être suffisamment explicite pour
63 permettre la compréhension, et non la copie en aveugle, de ce qui suit.
66 <p>Gardez à l'esprit que de nombreuses tâches de manipulation d'URLs
67 courantes n'ont pas besoin de la puissance et de la complexité de
68 <module>mod_rewrite</module>. Pour les tâches simples, voir
69 <module>mod_alias</module> et la documentation sur la <a
70 href="../urlmapping.html">Mise en correspondance des URLs avec le
71 système de fichiers</a>.</p>
73 <p>Enfin, avant de procéder, assurez-vous d'avoir configuré le niveau de
74 journalisation de <module>mod_rewrite</module> à un des niveaux de trace
75 via la directive <directive module="core">LogLevel</directive>. Bien que
76 ceci risque de vous submerger sous une énorme quantité d'informations,
77 le débogage des problèmes avec la configuration de
78 <module>mod_rewrite</module> est à ce prix car vous verrez alors
79 exactement comment chaque règle est traitée.</p>
83 <section id="regex"><title>Expressions rationnelles</title>
85 <p>mod_rewrite utilise le vocabulaire des <a
86 href="http://pcre.org/">Expressions rationnelles compatibles Perl</a>.
87 Ce document n'a pas pour prétention d'être une référence détaillée des
88 expressions rationnelles. A cet effet, nous recommandons les <a
89 href="http://pcre.org/pcre.txt">pages de manuel de PCRE</a>, la <a
90 href="http://perldoc.perl.org/perlre.html">page de manuel des
91 expressions rationnelles Perl</a>, et l'ouvrage <a
92 href="http://shop.oreilly.com/product/9780596528126.do">Mastering
93 Regular Expressions, by Jeffrey Friedl</a>.</p>
95 <p>Dans ce document, nous avons pour but de vous fournir suffisamment de
96 vocabulaire des expressions rationnelles pour vous mettre le pied à
97 l'étrier, sans être dépassé, en espérant que les directives <directive
98 module="mod_rewrite">RewriteRule</directive> vous apparaîtront comme des
99 formules scientifiques, plutôt que comme des incantations magiques.</p>
101 <section id="regexvocab"><title>Vocabulaire des expressions rationnelles</title>
103 <p>Vous trouverez dans ce qui suit le minimum à connaître pour être en
104 mesure d'écrire des expressions rationnelles et des règles <directive
105 module="mod_rewrite">RewriteRule</directive>. Ceci ne représente
106 certainement pas un vocabulaire des expressions rationnelles complet,
107 mais constitue un bon point de départ, et devrait vous aider à
108 déchiffrer les expressions rationnelles simples, et à écrire vos propres
114 <th>Signification</th>
118 <tr><td><code>.</code></td><td>Correspond à tout caractère unique
119 </td><td><code>c.t</code> correspondra à <code>cat</code>,
120 <code>cot</code>, <code>cut</code>, etc.</td></tr>
121 <tr><td><code>+</code></td><td>Répète le caractère de correspondance
122 précédent une ou plusieurs fois</td>
123 <td><code>a+</code> correspond à <code>a</code>, <code>aa</code>,
124 <code>aaa</code>, etc.</td></tr>
125 <tr><td><code>*</code></td><td>Répète le caractère de correspondance
126 précédent zéro ou plusieurs fois</td>
127 <td><code>a*</code> correspond à tout ce à quoi correspond
128 <code>a+</code>, mais correspond aussi à la chaîne vide.</td></tr>
129 <tr><td><code>?</code></td><td>Rend la correspondance optionnelle.</td><td>
130 <code>colou?r</code> correspondra à <code>color</code> et <code>colour</code>.</td>
132 <tr><td><code>^</code></td><td>Appelé ancrage, correspond au début de la
134 <td><code>^a</code> correspond à une chaîne qui commence par
135 <code>a</code></td></tr>
136 <tr><td><code>$</code></td><td>L'autre ancrage, correspond à la fin de
137 la chaîne.</td>
138 <td><code>a$</code> correspond à une chaîne qui se termine par
139 <code>a</code>.</td></tr>
140 <tr><td><code>( )</code></td><td>Regroupe plusieurs caractères en une
141 seule entité, et conserve une correspondance à des fins d'utilisation
142 dans une référence arrière.</td>
143 <td><code>(ab)+</code>
144 correspond à <code>ababab</code> - à savoir, le <code>+</code>
145 s'applique au groupe.
146 Pour plus de détails sur les références arrières, voir <a
147 href="#InternalBackRefs">ci-dessous</a>.</td></tr>
148 <tr><td><code>[ ]</code></td><td>Une classe de caractères - correspond à
149 un des caractères de la classe</td>
150 <td><code>c[uoa]t</code> correspond à <code>cut</code>,
151 <code>cot</code> ou <code>cat</code>.</td></tr>
152 <tr><td><code>[^ ]</code></td><td>Négation de la classe de caractères -
153 correspond à tout caractère ne faisant pas partie de la classe</td>
154 <td><code>c[^/]t</code> correspond à <code>cat</code> ou
155 <code>c=t</code> mais pas à <code>c/t</code></td></tr>
158 <p>Avec <module>mod_rewrite</module>, le caractère <code>!</code> peut
159 préfixer une expression rationnelle afin d'en exprimer la négation.
160 Autrement dit, une chaîne ne correspondra que si elle ne correspond pas
161 à l'expression située après le <code>!</code>.</p>
165 <section id="InternalBackRefs"><title>Disponibilité des références
166 arrières dans les expressions rationnelles</title>
168 <p>Vous devez vous souvenir d'une chose importante : chaque fois
169 que vous utilisez des parenthèses dans un <em>Modèle</em> ou dans
170 un des <em>modèles de conditions</em>, des références arrières
171 sont créées en interne et peuvent être rappelées via les chaînes
172 <code>$N</code> et <code>%N</code> (voir ci-dessous). Ces
173 références sont disponibles lors de la
174 création de la chaîne de substitution d'une directive
175 <directive module="mod_rewrite">RewriteRule</directive> ou de la
176 chaîne de test d'une directive <directive
177 module="mod_rewrite">RewriteCond</directive>.</p>
178 <p>Les captures dans les modèles de directives <directive
179 module="mod_rewrite">RewriteRule</directive> sont paradoxalement
180 disponibles dans toutes les directives <directive
181 module="mod_rewrite">RewriteCond</directive> qui précèdent, car
182 les expressions des directives <directive
183 module="mod_rewrite">RewriteRule</directive> sont évaluées avant
184 les conditions individuelles.</p>
186 <p>La figure 1 montre à quels endroits les
187 références arrières sont suceptibles
188 d'être développées, et illustre le flux des comparaisons
189 effectuées par les règles RewriteRule et
190 RewriteCond. Dans les chapitres suivants, nous examinerons comment
191 utiliser ces références arrières, donc ne vous affolez pas si
192 elles vous paraissent un peu exotiques au premier abord.</p>
195 <img src="../images/rewrite_backreferences.png"
196 alt="Flux des comparaisons effectuées par les règles RewriteRule
197 et RewriteCond" /><br />
198 <dfn>Figure 1 :</dfn> Le cheminement d'une référence arrière à
199 travers une règle.<br />
200 Dans cet exemple, une requête pour <code>/test/1234</code> serait
201 transformée en
202 <code>/admin.foo?page=test&id=1234&host=admin.example.com</code>.
208 <section id="rewriterule"><title>Les bases des règles de réécriture</title>
209 <p>Une règle de réécriture <directive
210 module="mod_rewrite">RewriteRule</directive> est constituée de trois
211 arguments séparés par des espaces. Les arguments sont :</p>
213 <li><var>Modèle</var>: le modèle des URLs auxquelles la règle doit
215 <li><var>Substitution</var>: vers quoi la requête correspondante doit être
216 transformée;</li>
217 <li><var>[drapeaux]</var>: options affectant la requête réécrite.</li>
220 <p>Le <var>Modèle</var> est une <a href="#regex">expression
221 rationnelle</a>. Au sein de la première règle de réécriture, ou jusqu'à
222 ce qu'une substitution survienne, elle est comparée au chemin de
223 l'URL de la requête entrante (la
224 partie située après le nom d'hôte mais avant tout point d'interrogation
225 qui indique le début d'une chaîne de paramètres de
226 requête) ou, dans un contexte de répertoire, au chemin de la
227 requête relativement au répertoire pour lequel la
228 règle est définie. Lorsqu'une substitution a eu lieu, les
229 règles suivantes effectuent leurs comparaisons par rapport à la valeur
230 substituée.</p>
233 <img src="../images/syntax_rewriterule.png"
234 alt="Syntaxe de la directive RewriteRule" /><br />
235 <dfn>Figure 2 :</dfn> Syntaxe de la directive RewriteRule.
238 <p>La chaîne de <var>Substitution</var> peut, quant à elle, être de
242 <dt>Un chemin complet du système de fichiers vers une ressource</dt>
244 <highlight language="config">
245 RewriteRule ^/jeux /usr/local/jeux/web
247 <p>Ceci peut faire correspondre une requête à toute localisation voulue de
248 votre système de fichiers, un peu comme la directive <directive
249 module="mod_alias">Alias</directive>.</p>
252 <dt>Un chemin web vers une ressource</dt>
254 <highlight language="config">
255 RewriteRule ^/foo$ /bar
257 <p>Si la directive <directive module="core">DocumentRoot</directive> a
258 pour valeur <code>/usr/local/apache2/htdocs</code>, cette règle va faire
259 correspondre les requêtes pour <code>http://example.com/foo</code> au
260 chemin <code>/usr/local/apache2/htdocs/bar</code>.</p>
263 <dt>Une URL absolue</dt>
265 <highlight language="config">
266 RewriteRule ^/produits/vues$ http://site2.example.com/voirproduits.html [R]
268 <p>Ceci informe le client qu'il doit effectuer une nouvelle requête vers
269 l'URL spécifiée.</p>
273 <p>La chaîne de <var>Substitution</var> peut aussi contenir des
274 <em>références arrières</em> vers des parties du chemin d'URL entrant
275 correspondant au <var>Modèle</var>. Considérons ce qui suit :</p>
276 <highlight language="config">
277 RewriteRule ^/produits/(.*)/view$ /var/web/produitsdb/$1
279 <p>La variable <code>$1</code> sera remplacée par tout texte
280 correspondant à l'expression située entre les parenthèses dans le
281 <var>Modèle</var>. Par exemple, une requête pour
282 <code>http://example.com/produits/r14df/vue</code> correspondra au
283 chemin <code>/var/web/produitsdb/r14df</code>.</p>
285 <p>S'il y a plus d'une expression entre parenthèses, elle seront
286 accessibles selon leur ordre d'apparition via les variables
287 <code>$1</code>, <code>$2</code>, <code>$3</code>, etc...</p>
292 <section id="flags"><title>Drapeaux de réécriture</title>
293 <p>Le comportement d'une règle <directive
294 module="mod_rewrite">RewriteRule</directive> peut être modifié par la
295 présence d'un ou plusieurs drapeaux en fin de règle. Par exemple, les
296 conditions de correspondance d'une règle peuvent être rendues
297 insensibles à la casse par la présence du drapeau <code>[NC]</code> :
299 <highlight language="config">
300 RewriteRule ^puppy.html petitchien.html [NC]
303 <p>Pour une liste des drapeaux disponibles, leurs significations, et des
304 exemples, voir le document <a href="flags.html">Drapeaux de
305 réécriture</a>.</p>
310 <section id="rewritecond"><title>Conditions de réécriture</title>
311 <p>Il est possible d'utiliser une ou plusieurs directives <directive
312 module="mod_rewrite">RewriteCond</directive> pour restreindre les types
313 de requêtes auxquelles devra s'appliquer la règle <directive
314 module="mod_rewrite">RewriteRule</directive> suivante. Le premier
315 argument est une variable décrivant une caractéristique de la requête,
316 le second argument est une <a href="#regex">expression rationnelle</a>
317 qui doit correspondre à la variable, et un troisième argument optionnel
318 est une liste de drapeaux qui modifient la manière dont la
319 correspondance est évaluée.</p>
322 <img src="../images/syntax_rewritecond.png"
323 alt="Syntaxe de la directive RewriteCond" /><br />
324 <dfn>Figure 3 :</dfn> Syntaxe de la directive RewriteCond
328 <p>Par exemple, pour renvoyer toutes les requêtes en provenance d'une
329 certaine tranche d'adresses IP vers un autre serveur, vous pouvez
331 <highlight language="config">
332 RewriteCond %{REMOTE_ADDR} ^10\.2\.
333 RewriteRule (.*) http://intranet.example.com$1
336 <p>Si vous spécifiez plus d'une directive <directive
337 module="mod_rewrite">RewriteCond</directive>, ces directives
338 doivent toutes être satisfaites pour que la règle <directive
339 module="mod_rewrite">RewriteRule</directive> suivante s'applique. Par exemple,
340 pour interdire les requêtes qui contiennent le mot "hack" dans la chaîne
341 de requête, sauf si elles contiennent aussi un cookie contenant le mot
342 "go", vous pouvez utiliser :</p>
343 <highlight language="config">
344 RewriteCond %{QUERY_STRING} hack
345 RewriteCond %{HTTP_COOKIE} !go
348 <p>Notez que le point d'exclamation indique une correspondance négative
349 ; ainsi, la règle n'est appliquée que si le cookie ne contient pas "go"</p>
351 <p>Les correspondances dans les expressions rationnelles contenues dans
352 les directives <directive module="mod_rewrite">RewriteCond</directive>
353 peuvent constituer des parties de la chaîne de <var>Substitution</var>
354 de la règle <directive module="mod_rewrite">RewriteRule</directive> via
355 les variables <code>%1</code>, <code>%2</code>, etc... Par
356 exemple, ce qui suit va diriger la requête vers un répertoire différent
357 en fonction du nom d'hôte utilisé pour accéder au site :</p>
358 <highlight language="config">
359 RewriteCond %{HTTP_HOST} (.*)
360 RewriteRule ^/(.*) /sites/%1/$1
362 <p>Si la requête concernait <code>http://example.com/foo/bar</code>,
363 alors <code>%1</code> contiendrait <code>example.com</code> et
364 <code>$1</code> contiendrait <code>foo/bar</code>.</p>
370 <section id="rewritemap"><title>Tables de réécriture</title>
372 <p>La directive <directive module="mod_rewrite">RewriteMap</directive>
373 permet en quelque sorte de faire appel à une fonction externe pour
374 effectuer la réécriture à votre place. Tout ceci est décrit plus en
375 détails dans la <a href="rewritemap.html">Documentation
376 supplémentaire sur RewriteMap</a>.</p>
379 <section id="htaccess"><title>Fichiers .htaccess</title>
381 <p>La réécriture est en général définie au niveau de la configuration du
382 serveur principal (en dehors de toute section <directive type="section"
383 module="core">Directory</directive>) ou dans une section <directive
384 type="section" module="core">VirtualHost</directive>. Il s'agit là de la
385 manière la plus simple de mettre en oeuvre la réécriture et nous la
386 recommandons. Il est possible, cependant, de mettre en oeuvre la
387 réécriture au sein d'une section <directive type="section"
388 module="core">Directory</directive> ou d'un fichier <a
389 href="../howto/htaccess.html"><code>.htaccess</code></a> ; ce type de
390 configuration est cependant plus complexe. Cette technique est appelée
391 réécriture par répertoire.</p>
393 <p>La principale différence avec les réécritures au niveau du serveur réside
394 dans le fait que le préfixe du chemin du répertoire contenant le fichier
395 <code>.htaccess</code> est supprimé avant la mise en correspondance dans
396 la règle <directive module="mod_rewrite">RewriteRule</directive>. De
397 plus, on doit utiliser la directive <directive
398 module="mod_rewrite">RewriteBase</directive> pour s'assurer que la
399 requête est correctement mise en correspondance.</p>
projects / apache / blob