2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision : 1422375 -->
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 <modulesynopsis metafile="mod_alias.xml.meta">
27 <name>mod_alias</name>
28 <description>Permet d'atteindre différentes parties du système de
29 fichiers depuis l'arborescence des documents du site web, ainsi que la
30 redirection d'URL</description>
32 <sourcefile>mod_alias.c</sourcefile>
33 <identifier>alias_module</identifier>
36 <p>Les directives fournies par ce module permettent de manipuler et
37 de contrôler les URLs à l'arrivée des requêtes sur le serveur. Les
38 directives <directive module="mod_alias">Alias</directive> et
39 <directive module="mod_alias">ScriptAlias</directive> permettent de
40 faire correspondre des URLs avec des chemins du système de fichiers.
41 Ceci permet de servir des contenus qui ne sont pas situés dans
42 l'arborescence de <directive
43 module="core">DocumentRoot</directive> comme s'ils y étaient
44 réellement. La directive <directive
45 module="mod_alias">ScriptAlias</directive> a pour effet
46 supplémentaire de marquer le répertoire cible comme conteneur de
49 <p>Les directives <directive module="mod_alias">Redirect</directive>
50 indiquent aux clients qu'ils doivent effectuer une nouvelle requête
51 avec une URL différente. Elles sont souvent utilisées lorsqu'une
52 ressource a été déplacée.</p>
54 <p><module>mod_alias</module> est conçu pour traiter des tâches
55 simples de manipulation d'URL. Pour des tâches plus complexes comme
56 la manipulation des chaînes d'arguments des requêtes, utilisez
57 plutôt les outils fournis par le module <module>mod_rewrite</module></p>
61 <seealso><module>mod_rewrite</module></seealso> <seealso><a
62 href="../urlmapping.html">Mise en correspondance des URLs avec le
63 système de fichiers</a></seealso>
65 <section id="order"><title>Chronologie du traitement</title>
67 <p>Les alias et redirections apparaissant dans différents contextes
68 sont traités comme les autres directives en respectant les <a
69 href="../sections.html#mergin">règles de fusion</a> standards. Par
70 contre, ils sont traités selon une chronologie particulière
71 lorsqu'ils apparaissent dans le même contexte (par exemple, dans la
72 même section <directive type="section"
73 module="core">VirtualHost</directive>).</p>
75 <p>Premièrement, toutes les redirections sont traitées avant les
76 alias, et ainsi, une requête qui correspond à une directive
77 <directive module="mod_alias">Redirect</directive> ou <directive
78 module="mod_alias">RedirectMatch</directive> ne se verra jamais
79 appliquer d'alias. Deuxièmement, les alias et redirections sont
80 traités selon l'ordre dans lequel ils apparaissent dans le fichier
81 de configuration, seule la première correspondance étant prise en
84 <p>Ainsi, lorsqu'une ou plusieurs de ces directives s'appliquent au
85 même sous-répertoire, vous devez classer les chemins du plus précis
86 au moins précis afin que toutes les directives puissent
87 éventuellement s'appliquer, comme dans l'exemple suivant :</p>
89 <highlight language="config">
94 <p>Si l'ordre des directives était inversé, la directive <directive
95 module="mod_alias">Alias</directive> ayant pour argument
96 <code>/foo</code> serait toujours appliquée avant la directive
97 <directive module="mod_alias">Alias</directive> ayant pour argument
98 <code>/foo/bar</code>, et cette dernière serait toujours
105 <description>Met en correspondance des URLs avec des chemins du système
106 de fichiers</description>
107 <syntax>Alias <var>chemin URL</var>
108 <var>chemin fichier</var>|<var>chemin répertoire</var></syntax>
109 <contextlist><context>server config</context><context>virtual host</context>
114 <p>La directive <directive>Alias</directive> permet de stocker des
115 documents (destinés à être servis) dans des zones du système de
116 fichiers situées en dehors de l'arborescence du site web <directive
117 module="core">DocumentRoot</directive>. Les URLs dont le chemin
118 (décodé avec caractères %) commence par <var>chemin URL</var> seront
119 mises en correspondance avec des fichiers locaux dont le chemin
120 commence par <var>chemin répertoire</var>. Le <var>chemin URL</var>
121 est sensible à la casse, même sur les systèmes de fichiers
122 insensibles à la casse.</p>
124 <highlight language="config">
125 Alias /image /ftp/pub/image
128 <p>Une requête pour <code>http://example.com/image/foo.gif</code> fera
129 renvoyer par le serveur le fichier
130 <code>/ftp/pub/image/foo.gif</code>. Seuls les éléments de chemin
131 complets sont testés ; ainsi l'alias précédent ne conviendra pas
132 pour une requête du style <code>http://example.com/imagefoo.gif</code>.
133 Pour des mises en correspondance plus complexes faisant intervenir
134 les expressions rationnelles, veuillez vous reporter à la directive
135 <directive module="mod_alias">AliasMatch</directive>.</p>
137 <p>Notez que si vous ajoutez un slash de fin au <var>chemin
138 URL</var>, vous devrez aussi ajouter un slash de fin au chemin de la
139 requête. Autrement dit, si vous définissez</p>
141 <dl><dd><code>Alias /icons/ /usr/local/apache/icons/</code></dd></dl>
143 <p>l'alias précédent ne s'appliquera pas à l'url
144 <code>/icons</code> à cause de l'absence du slash final. Ainsi, si
145 le slash final est absent du <var>chemin de l'URL</var>, il doit
146 aussi l'être du <var>chemin du fichier</var>.</p>
148 <p>Notez qu'il pourra s'avérer nécessaire de définir des sections
149 <directive type="section" module="core">Directory</directive>
150 supplémentaires qui couvriront la <em>destination</em> des alias.
151 Le traitement des alias intervenant avant le traitement des sections
152 <directive type="section" module="core">Directory</directive>,
153 seules les cibles des alias sont affectées (Notez cependant
154 que les sections <directive type="section"
155 module="core">Location</directive> sont traitées avant les alias, et
156 s'appliqueront donc).</p>
158 <p>En particulier, si vous créez un alias ayant pour cible un
159 répertoire situé en dehors de l'arborescence de votre site web
160 <directive module="core">DocumentRoot</directive>, vous devrez
161 probablement permettre explicitement l'accès à ce répertoire.</p>
163 <highlight language="config">
164 Alias /image /ftp/pub/image
165 <Directory /ftp/pub/image>
170 <p>Le nombre de slashes dans le paramètre <var>chemin URL</var> doit
171 correspondre au nombre de slashes dans le chemin URL de la requête.</p>
177 <name>AliasMatch</name>
178 <description>Met en correspondance des URLs avec le système de fichiers
179 en faisant intervenir les expressions rationnelles</description>
180 <syntax>AliasMatch <var>regex</var>
181 <var>chemin fichier</var>|<var>chemin répertoire</var></syntax>
182 <contextlist><context>server config</context><context>virtual host</context>
186 <p>Cette directive est identique à la directive <directive
187 module="mod_alias">Alias</directive>, mais fait appel aux <glossary
188 ref="regex">expressions rationnelles</glossary>, à la place d'une
189 simple mise en correspondance de préfixe. L'expression rationnelle
190 fournie est mise en correspondance avec le chemin URL, et si elle
191 correspond, le serveur va substituer toute partie de chemin
192 correspondant à l'expression entre parenthèses dans la chaîne
193 fournie et l'utiliser comme nom de fichier.
194 Par exemple, pour activer le répertoire <code>/icons</code>, on peut
197 <highlight language="config">
198 AliasMatch ^/icons(.*) /usr/local/apache/icons$1
201 <p>Toute la puissance des <glossary ref="regex">expressions
202 rationnelles</glossary> peut être mise à contribution. Par exemple,
203 il est possible de construire un alias avec un modèle de chemin URL
204 insensible à la casse :</p>
206 <highlight language="config">
207 AliasMatch (?i)^/image(.*) /ftp/pub/image$1
210 <p>Il existe une différence subtile entre <directive
211 module="mod_alias">Alias</directive> et <directive
212 module="mod_alias">AliasMatch</directive> : <directive
213 module="mod_alias">Alias</directive> copie automatiquement toute
214 portion supplémentaire de l'URI située après la partie du modèle qui
215 correspond, à la fin du chemin du fichier de la partie droite, alors
216 que <directive module="mod_alias">AliasMatch</directive> ne le fait
217 pas. Cela signifie qu'il sera préférable dans la plupart des cas de
218 comparer l'expression rationnelle du modèle à la totalité de l'URI
219 de la requête, et d'utiliser les substitutions dans la partie
222 <p>En d'autres termes, le remplacement d'<directive
223 module="mod_alias">Alias</directive> par <directive
224 module="mod_alias">AliasMatch</directive> ne produira pas le même
225 résultat. Au minimum, vous devez ajouter <code>^</code> au début de
226 l'expression rationnelle, <code>(.*)$</code> à sa fin et
227 <code>$1</code> à la fin de la chaîne de remplacement.</p>
229 <p>Par exemple, supposons que nous voulions reformuler cet alias
230 avec AliasMatch :</p>
232 <highlight language="config">
233 Alias /image/ /ftp/pub/image/
236 <p>Le simple remplacement d'Alias par AliasMatch ne produira pas le
237 même résultat. Ainsi, ce qui suit va rediriger toutes les requêtes
238 qui contiennent /image/ vers /ftp/pub/image/ :</p>
240 <highlight language="config">
241 AliasMatch /image/ /ftp/pub/image/
244 <p>Voici la directive AliasMatch qui produira le même résultat que
245 la directive Alias ci-dessus :</p>
247 <highlight language="config">
248 AliasMatch ^/image/(.*)$ /ftp/pub/image/$1
251 <p>Bien entendu, il n'y a aucune raison d'utiliser <directive
252 module="mod_alias">AliasMatch</directive> dans le cas où <directive
253 module="mod_alias">Alias</directive> suffit. <directive
254 module="mod_alias">AliasMatch</directive> vous permet d'effectuer
255 des choses beaucoup plus sophistiquées. Par exemple, vous pouvez
256 servir différentes sortes de fichiers à partir de répertoires
257 différents :</p>
259 <highlight language="config">
260 AliasMatch ^/image/(.*)\.jpg$ /fichiers/jpg.images/$1.jpg<br/>
261 AliasMatch ^/image/(.*)\.gif$ /fichiers/gif.images/$1.gif
264 <p>Les éventuels slashes de tête multiples seront supprimés par le
265 serveur avant que les directives de ce module n'effectuent des
266 comparaisons avec le chemin URL de la requête.
273 <name>Redirect</name>
274 <description>Envoie une redirection externe demandant au client
275 d'effectuer une autre requête avec une URL différente</description>
276 <syntax>Redirect [<var>état</var>] <var>chemin URL</var>
277 <var>URL</var></syntax>
278 <contextlist><context>server config</context><context>virtual host</context>
279 <context>directory</context><context>.htaccess</context></contextlist>
280 <override>FileInfo</override>
283 <p>La directive Redirect permet de faire correspondre une ancienne
284 URL à une nouvelle en demandant au client d'aller chercher la ressource à
285 une autre localisation.</p>
287 <p>L'ancien <em>chemin URL</em> est un chemin sensible à la casse
288 (décodé à l'aide de caractères %) commençant par un slash. Les
289 chemins relatifs ne sont pas autorisés.</p>
291 <p>La nouvelle <em>URL</em>
292 peut être une URL absolue commençant par un protocole et un nom
293 d'hôte, mais on peut aussi utiliser un chemin URL commençant par un
294 slash, auquel cas le protocole et le nom d'hôte du serveur local
295 seront ajoutés.</p>
297 <p>Ensuite, toute requête commençant par <em>chemin URL</em> va
298 renvoyer une redirection au client vers l'<em>URL</em> cible. Tout
299 élément de chemin supplémentaire situé en aval du <em>chemin
300 URL</em> sera ajouté à l'URL cible.</p>
302 <highlight language="config">
303 # Redirige vers une URL sur un serveur différent
304 Redirect /service http://foo2.example.com/service
306 # Redirige vers une URL sur le même serveur
310 <p>Si le client effectue une requête pour l'URL
311 <code>http://example.com/service/foo.txt</code>, il lui sera demandé
312 d'en effectuer une autre pour l'URL
313 <code>http://foo2.example.com/service/foo.txt</code>. Ceci concerne
314 les requêtes avec paramètres <code>GET</code>, comme
315 <code>http://example.com/service/foo.pl?q=23&a=42</code>, qui
316 seront redirigées vers
317 <code>http://foo2.example.com/service/foo.pl?q=23&a=42</code>.
318 Notez que les <code>POST</code>s seront ignorés.<br />
320 éléments de chemin complets sont testés, si bien que l'exemple
321 précédent ne s'appliquera pas à l'URL
322 <code>http://example.com/servicefoo.txt</code>. Pour des mises en
323 correspondance plus complexes faisant intervenir les expressions
324 rationnelles, veuillez vous reporter à la directive <directive
325 module="mod_alias">RedirectMatch</directive>.</p>
328 <note><title>Note</title>
329 <p>Les directives de redirection ont priorité sur les directives
330 Alias et ScriptAlias, quel que soit leur ordre d'apparition dans le
331 fichier de configuration.</p></note>
333 <p>Si aucun argument <var>état</var> n'est spécifié, la
334 redirection sera temporaire (code HTTP 302). Le client est alors
335 informé que la ressource a été temporairement déplacée. On peut
336 utiliser l'argument <var>état</var> pour renvoyer d'autres codes HTTP :</p>
341 <dd>Renvoie un code de redirection permanente (301), indiquant
342 que la ressource a été définitivement déplacée.</dd>
346 <dd>Renvoie un code de redirection temporaire (302). C'est le
347 comportement par défaut.</dd>
351 <dd>Renvoie un code "See Other" (303) indiquant que la ressource
352 a été remplacée par une autre.</dd>
356 <dd>Renvoie un code "Gone" (410) indiquant que la ressource a
357 été définitivement supprimée. Lorsque
358 ce code est utilisé, on ne
359 doit pas utiliser l'argument <var>URL</var>.</dd>
362 <p>On peut renvoyer d'autres codes en spécifiant le code
363 numérique comme valeur de l'argument of <var>état</var>.
364 Si le code est compris entre 300 et 399, l'argument
365 <var>URL</var> doit être présent. Si le code
366 n'est <em>pas</em> compris entre 300 et 399, l'argument
367 <var>URL</var> ne doit pas apparaître. Le code doit être un code
368 HTTP valide, connu du serveur HTTP Apache (voir la
369 fonction <code>send_error_response</code> dans
370 http_protocol.c).</p>
372 <highlight language="config">
373 Redirect permanent /one http://example.com/two
374 Redirect 303 /three http://example.com/other
381 <name>RedirectMatch</name>
382 <description>Envoie une redirection externe faisant appel aux
383 expressions rationnelles pour la mise en correspondance de l'URL
384 courante</description>
385 <syntax>RedirectMatch [<var>état</var>] <var>regex</var>
386 <var>URL</var></syntax>
387 <contextlist><context>server config</context><context>virtual host</context>
388 <context>directory</context><context>.htaccess</context></contextlist>
389 <override>FileInfo</override>
392 <p>Cette directive est identique à la directive <directive
393 module="mod_alias">Redirect</directive>, mais fait appel aux
394 <glossary ref="regex">expressions rationnelles</glossary>, à la
395 place d'une simple mise en correspondance de préfixe. L'expression
396 rationnelle fournie est mise en correspondance avec le chemin URL,
397 et si elle correspond, le serveur va substituer toute partie de
398 chemin correspondante entre parenthèses dans la chaîne spécifiée et
399 l'utiliser comme nom de fichier. Par exemple, pour rediriger tous
400 les fichiers GIF vers les fichiers JPEG de même nom sur un autre
401 serveur, on peut utiliser :</p>
403 <highlight language="config">
404 RedirectMatch (.*)\.gif$ http://autre.example.com$1.jpg
407 <p>Les remarques à propos de la différence entre <directive
408 module="mod_alias">Alias</directive> et <directive
409 module="mod_alias">AliasMatch</directive> s'appliquent aussi à la
410 différence entre les directives <directive
411 module="mod_alias">Redirect</directive> et <directive
412 module="mod_alias">RedirectMatch</directive>. Voir la directive
413 <directive module="mod_alias">AliasMatch</directive> pour plus de
420 <name>RedirectTemp</name>
421 <description>Envoie une redirection externe temporaire demandant au
422 client d'effectuer une nouvelle requête avec une URL
423 différente</description>
424 <syntax>RedirectTemp <var>chemin URL</var> <var>URL</var></syntax>
425 <contextlist><context>server config</context><context>virtual host</context>
426 <context>directory</context><context>.htaccess</context></contextlist>
427 <override>FileInfo</override>
430 <p>Cette directive informe le client que la redirection n'est
431 que temporaire (code 302). Son comportement est exactement le même
432 que celui de <code>Redirect temp</code>.</p>
437 <name>RedirectPermanent</name>
438 <description>Envoie une redirection externe permanente demandant au
439 client d'effectuer une nouvelle requête avec une URL
440 différente</description>
441 <syntax>RedirectPermanent <var>chemin URL</var> <var>URL</var></syntax>
442 <contextlist><context>server config</context><context>virtual host</context>
443 <context>directory</context><context>.htaccess</context></contextlist>
444 <override>FileInfo</override>
447 <p>Cette directive informe le client que la redirection est
448 permanente (code 301). Son comportement est exactement le même
449 que celui de <code>Redirect permanent</code>.</p>
454 <name>ScriptAlias</name>
455 <description>Fait correspondre une URL à une zone du système de fichiers
456 et désigne la cible comme script CGI</description>
457 <syntax>ScriptAlias <var>chemin URL</var>
458 <var>chemin fichier</var>|<var>chemin répertoire</var></syntax>
459 <contextlist><context>server config</context><context>virtual host</context>
463 <p>La directive <directive>ScriptAlias</directive> présente le même
464 comportement que la directive <directive
465 module="mod_alias">Alias</directive>, mais désigne en plus le
466 répertoire cible comme conteneur de scripts CGI qui seront traitées
467 par le gestionnaire cgi-script du module <module>mod_cgi</module>.
468 Les URLs dont le chemin URL sensible à la casse (décodé avec
469 caractères %) commence par <var>chemin URL</var> seront mises en
470 correspondance avec les scripts dont le chemin commence par le
471 second argument, qui est un chemin complet dans le système de
474 <highlight language="config">
475 ScriptAlias /cgi-bin/ /web/cgi-bin/
478 <p>Une requête pour <code>http://example.com/cgi-bin/foo</code>
479 ferait exécuter par le serveur le script
480 <code>/web/cgi-bin/foo</code>. Cette configuration est sensiblement
481 équivalente à :</p>
482 <highlight language="config">
483 Alias /cgi-bin/ /web/cgi-bin/
484 <Location /cgi-bin >
485 SetHandler cgi-script
490 <p>Vous pouvez aussi utiliser <directive>ScriptAlias</directive>
491 avec un script ou gestionnaire de votre cru. Par exemple :</p>
493 <highlight language="config">
494 ScriptAlias /cgi-bin/ /web/cgi-handler.pl
497 <p>Dans ce scénario, tous les fichiers faisant l'objet d'une requête
498 dans <code>/cgi-bin/</code> seront traités par le fichier que vous
499 avez spécifié, ce qui vous permet d'utiliser votre propre
500 gestionnaire. Vous pouvez l'utiliser comme enveloppe (wrapper) pour
501 les scripts CGI afin d'ajouter du contenu, ou autre action "maison".</p>
503 <note type="warning">Il est préférable d'éviter de placer les
504 scripts CGI dans l'arborescence de <directive
505 module="core">DocumentRoot</directive> afin d'éviter de révéler
506 accidentellement leur code source lors d'une modification de
507 configuration. On y parvient aisément avec
508 <directive>ScriptAlias</directive> en mettant en correspondance une
509 URL et en désignant la cible comme scripts CGI par la même occasion.
510 Si vous choisissez de placer vos scripts CGI dans un répertoire
511 accessible depuis le web, n'utilisez pas
512 <directive>ScriptAlias</directive>. Utilisez plutôt <directive
513 module="core" type="section">Directory</directive>, <directive
514 module="core">SetHandler</directive>, et <directive
515 module="core">Options</directive> comme dans l'exemple suivant :
516 <highlight language="config">
517 <Directory /usr/local/apache2/htdocs/cgi-bin >
518 SetHandler cgi-script
522 Ceci est nécessaire car plusieurs <var>chemins URL</var> peuvent
523 correspondre à la même zone du système de fichiers, court-circuitant
524 ainsi la directive <directive>ScriptAlias</directive> et révélant le
525 code source des scripts CGI s'ils ne sont pas protégés par une
526 section <directive module="core">Directory</directive>.</note>
529 <seealso><a href="../howto/cgi.html">Tutoriel CGI</a></seealso>
533 <name>ScriptAliasMatch</name>
534 <description>Fait correspondre une URL à une zone du système de fichiers
535 en faisant appel aux expressions rationnelles et en désignant la cible
536 comme un script CGI</description>
537 <syntax>ScriptAliasMatch <var>regex</var>
538 <var>chemin fichier</var>|<var>chemin répertoire</var></syntax>
539 <contextlist><context>server config</context><context>virtual host</context>
543 <p>Cette directive est équivalente à la directive <directive
544 module="mod_alias">ScriptAlias</directive>, mais fait appel aux
545 <glossary ref="regex">expressions rationnelles</glossary>, à la
546 place d'une simple mise en correspondance de préfixe. L'expression
547 rationnelle fournie est mise en correspondance avec le chemin URL,
548 et si elle correspond, le serveur va substituer toute partie de
549 chemin entre parenthèses dans la chaîne spécifiée et l'utiliser
550 comme nom de fichier. Par exemple, pour activer le répertoire
551 standard <code>/cgi-bin</code>, on peut utiliser :</p>
553 <highlight language="config">
554 ScriptAliasMatch ^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
557 <p>Comme dans le cas d'AliasMatch, toute la puissance des <glossary
558 ref="rexex">expressions rationnelles</glossary> peut être mise à
559 contribution. Par exemple, il est possible de construire un alias
560 avec une comparaison du modèle du chemin URL insensible à la casse :</p>
562 <highlight language="config">
563 ScriptAliasMatch (?i)^/cgi-bin(.*) /usr/local/apache/cgi-bin$1
566 <p>Les remarques à propos de la différence entre <directive
567 module="mod_alias">Alias</directive> et <directive
568 module="mod_alias">AliasMatch</directive> s'appliquent aussi à la
569 différence entre les directives <directive
570 module="mod_alias">ScriptAlias</directive> et <directive
571 module="mod_alias">ScriptAliasMatch</directive>. Voir la directive
572 <directive module="mod_alias">AliasMatch</directive> pour plus de