<-
Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

Module Apache mod_rewrite

Langues Disponibles:  en  |  fr 

Description:Ce module fournit un moteur de r��criture � base de r�gles permettant de r��crire les URLs des requ�tes � la vol�e
Statut:Extension
Identificateur�de�Module:rewrite_module
Fichier�Source:mod_rewrite.c

Sommaire

Le module mod_rewrite utilise un moteur de r��criture � base de r�gles, bas� sur un interpr�teur d'expressions rationnelles PCRE, pour r��crire les URLs � la vol�e. Par d�faut, mod_rewrite met en correspondance une URL avec le syst�me de fichiers. Cependant, on peut aussi l'utiliser pour rediriger une URL vers une autre URL, ou pour invoquer une requ�te interne � destination du mandataire.

mod_rewrite fournit une m�thode souple et puissante pour manipuler les URLs en utilisant un nombre illimit� de r�gles. Chaque r�gle peut �tre associ�e � un nombre illimit� de conditions, afin de vous permettre de r��crire les URLs en fonction de variables du serveur, de variables d'environnement, d'en-t�tes HTTP, ou de rep�res temporels.

mod_rewrite agit sur la totalit� de l'URL, y compris la partie chemin. Une r�gle de r��criture peut �tre invoqu�e dans apache2.conf ou dans un fichier .htaccess. Le chemin g�n�r� par une r�gle de r��criture peut inclure une cha�ne de param�tres, ou peut renvoyer vers un traitement secondaire interne, une redirection vers une requ�te externe ou vers le mandataire interne.

Vous trouverez d'avantage de d�tails, discussions et exemples dans la documentation d�taill�e sur mod_rewrite.

Directives

Sujets

top

Journalisation

mod_rewrite offre une journalisation d�taill�e de ses actions aux niveaux de journalisation trace1 � trace8. Le niveau de journalisation peut �tre d�fini de mani�re sp�cifique � mod_rewrite via la directive LogLevel : jusqu'au niveau debug aucune action n'est journalis�e, alors qu'elles le sont pratiquement toutes au niveau trace8.

L'utilisation d'un niveau de journalisation �lev� pour mod_rewrite va ralentir votre serveur HTTP Apache de mani�re dramatique ! N'utilisez un niveau de journalisation sup�rieur � trace2 qu'� des fins de d�bogage !

Exemple

LogLevel alert rewrite:trace3

RewriteLog

Ceux qui sont familiers avec les versions pr�c�dentes de mod_rewrite vont probablement rechercher en vain les directives RewriteLog et RewriteLogLevel. Elles ont �t� en effet remplac�es par une configuration de la journalisation par module, comme mentionn� plus haut.

Pour extraire les traces sp�cifiques � mod_rewrite, affichez le fichier journal en redirigeant la sortie vers grep :

tail -f error_log|fgrep '[rewrite:'

top

RewriteBase Directive

Description:D�finit l'URL de base pour les r��critures au niveau r�pertoire
Syntaxe:RewriteBase chemin_URL
D�faut:Pas de valeur par d�faut
Contexte:r�pertoire, .htaccess
AllowOverride:FileInfo
Statut:Extension
Module:mod_rewrite

La directive RewriteBase permet de sp�cifier le pr�fixe d'URL � utiliser dans un contexte de r�pertoire (htaccess) pour les directives RewriteRule qui r��crivent vers un chemin relatif.

Cette directive est obligatoire si vous utilisez un chemin relatif dans une substitution, et dans un contexte de r�pertoire (htaccess), sauf si au moins une de ces conditions est v�rifi�e :

Dans l'exemple ci-dessous, la directive RewriteBase est n�cessaire afin d'�viter une r��criture en http://example.com/opt/myapp-1.2.3/welcome.html car la ressource n'�tait pas relative � la racine des documents. Cette erreur de configuration aurait conduit le serveur � rechercher un r�pertoire "opt" � la racine des documents.

DocumentRoot /var/www/example.com
Alias /myapp /opt/myapp-1.2.3
<Directory /opt/myapp-1.2.3>
 RewriteEngine On
    RewriteBase /myapp/
    RewriteRule ^index\.html$  welcome.html
</Directory>
top

RewriteCond Directive

Description:D�finit une condition qui devra �tre satisfaite pour que la r��criture soit effectu�e
Syntaxe: RewriteCond cha�ne_de_test expression_de_comparaison
Contexte:configuration du serveur, serveur virtuel, r�pertoire, .htaccess
AllowOverride:FileInfo
Statut:Extension
Module:mod_rewrite

La directive RewriteCond permet de d�finir une condition d'ex�cution d'une r�gle. Une ou plusieurs conditions RewriteCond peuvent pr�c�der une directive RewriteRule. La r�gle de r��criture correspondante n'est ainsi ex�cut�e que si ces conditions sont satisfaites, et si l'URI correspond au mod�le sp�cifi� dans la r�gle.

TestString est une cha�ne qui peut contenir les extensions suivantes en plus du texte simple :

Si cha�ne_de_test contient la valeur sp�ciale expr, expression_de_comparaison sera trait� en tant qu'expression rationnelle de type ap_expr. Si des en-t�tes HTTP sont r�f�renc�s dans l'expression rationnelle, et si le drapeau novary n'est pas activ�, ils seront ajout�s � l'en-t�te Vary.

Autres points � conna�tre ::

  1. Les variables SCRIPT_FILENAME et REQUEST_FILENAME contiennent toutes deux la valeur du champ filename de la structure interne request_recdu serveur HTTP Apache. Le premier nom correspond au nom de variable bien connu CGI, alors que le second est l'�quivalent de REQUEST_URI (qui contient la valeur du champ uri de request_rec).

    Si une substitution intervient et si la r��criture se poursuit, la valeur des deux variables sera mise � jour en cons�quence.

    Dans le contexte du serveur principal (c'est � dire avant que la requ�te ne soit mise en correspondance avec le syst�me de fichiers), SCRIPT_FILENAME et REQUEST_FILENAME ne peuvent pas contenir le chemin entier dans le syst�me de fichiers local car ce chemin b'est pas connu � ce stade du traitement. Dans ce cas, les deux variables contiendront la valeur de REQUEST_URI. Pour obtenir le chemin complet de la requ�te dans le syst�me de fichiers local dans le contexte du serveur principal, utilisez une r�f�rence avant � base d'URL %{LA-U:REQUEST_FILENAME} pour d�terminer la valeur finale de REQUEST_FILENAME.

  2. %{ENV:variable}, o� variable peut correspondre � une variable d'environnement quelconque.
  3. %{ENV:variable} est aussi disponible, o� variable peut correspondre � toute variable d'environnement. Peut �tre consult� via des structures internes d'Apache httpd et (si on ne les trouve pas ici) via la fonction getenv() � partir du processus du serveur Apache httpd.
  4. Que mod_ssl soit charg� ou non, on peut utiliser %{SSL:variable}, o� variable peut �tre remplac� par le nom d'une variable d'environnement SSL . Si mod_ssl n'est pas charg�, cette variable contiendra toujours une cha�ne vide. Exemple : %{SSL:SSL_CIPHER_USEKEYSIZE} pourra contenir la valeur 128.
  5. On peut utiliser %{HTTP:en-t�te}, o� en-t�te peut correspondre � tout nom d'en-t�te MIME HTTP, pour extraire la valeur d'un en-t�te envoy� dans la requ�te HTTP. Par exemple, %{HTTP:Proxy-Connection} contiendra la valeur de l'en-t�te HTTP "Proxy-Connection:". Si on utilise un en-t�te HTTP dans une condition, et si cette condition est �valu�e � vrai pour la requ�te, cet en-t�te sera ajout� � l'en-t�te Vary de la r�ponse. Il ne le sera pas si la condition est �valu�e � faux. L'ajout de l'en-t�te HTTP � l'en-t�te Vary est n�cessaire � une mise en cache appropri�e.

    Il faut garder � l'esprit que les conditions suivent une logique de cout-circuit si le drapeau 'ornext|OR' est utilis�, et que de ce fait, certaines d'entre elles ne seront pas �valu�es.

  6. A des fins de r�f�rence avant, on peut utiliser, %{LA-U:variable}, qui permet d'effectuer une sous-requ�te interne � base d'URL, afin de d�terminer la valeur finale de variable. Ceci permet d'acc�der � la valeur d'une variable pour la r��criture inconnue � ce stade du traitement, mais qui sera d�finie au cours d'une phase ult�rieure.

    Par exemple, pour effectuer une r��criture d�pendant de la variable REMOTE_USER dans le contexte du serveur principal (fichier apache2.conf), vous devez utiliser %{LA-U:REMOTE_USER} - cette variable est d�finie par la phase d'autorisation qui intervient apr�s la phase de traduction d'URL (pendant laquelle mod_rewrite op�re).

    Par contre, comme mod_rewrite impl�mente son contexte de r�pertoire (fichier .htaccess) via la phase Fixup de l'API, et comme la phase d'autorisation intervient avant cette derni�re, vous pouvez vous contenter d'utiliser %{REMOTE_USER} dans ce contexte.

  7. %{LA-F:variable} peut �tre utilis�e pour effectuer une sous-requ�te interne (bas�e sur le nom de fichier), afin de d�terminer la valeur finale de variable. La plupart du temps, elle est identique � LA-U (voir ci-dessus).

expression_de_comparaison est une expression rationnelle qui est appliqu�e � l'instance actuelle de cha�ne_de_test. cha�ne_de_test est d'abord �valu�e, puis compar�e � l'expression_de_comparaison.

expression_de_comparaison est en g�n�ral une expression rationnelle compatible perl, mais vous disposez des syntaxes suppl�mentaires suivantes pour effectuer d'autres tests utiles sur cha�ne_de_test :

  1. Vous pouvez pr�fixer l'expression avec un caract�re '!' (point d'exclamation) pour inverser le r�sultat de la condition, quelle que soit l'expression_de_comparaison utilis�e.
  2. Vous pouvez effectuer des comparaisons lexicographiques de cha�nes :
    • '<expression' (inf�rieur au sens lexicographique)
      Traite l'expression comme une cha�ne de caract�res et la compare lexicographiquement � cha�ne_de_test. La condition est satisfaite si cha�ne_de_test est inf�rieure au sens lexicographique � l'expression.
    • '>expression' (sup�rieur au sens lexicographique)
      Traite l'expression comme une cha�ne de caract�res et la compare lexicographiquement � cha�ne_de_test. La condition est satisfaite si cha�ne_de_test est sup�rieure au sens lexicographique � l'expression.
    • '=expression' (�gal au sens lexicographique)
      Traite l'expression comme une cha�ne de caract�res et la compare lexicographiquement � cha�ne_de_test. La condition est satisfaite si cha�ne_de_test est �gale au sens lexicographique � l'expression (les deux cha�nes sont exactement identiques, caract�re pour caract�re). Si expression est "" (deux guillemets), cha�ne_de_test est compar�e � la cha�ne vide.
    • '<=expression_de_comparaison' (inf�rieur ou �gal � au sens lexicographique)
      Consid�re l'expression_de_comparaison comme une cha�ne de caract�res et la compare au sens lexicographique � la cha�ne_de_test. Vrai si cha�ne_de_test pr�c�de lexicographiquement expression_de_comparaison, ou est �gale � expression_de_comparaison (les deux cha�nes sont identiques, caract�re pour caract�re).
    • '>=expression_de_comparaison' (sup�rieur ou �gal � au sens lexicographique)
      Consid�re l'expression_de_comparaison comme une cha�ne de caract�res et la compare au sens lexicographique � la cha�ne_de_test. Vrai si cha�ne_de_test suit lexicographiquement expression_de_comparaison, ou est �gale � expression_de_comparaison (les deux cha�nes sont identiques, caract�re pour caract�re).
  3. Vous pouvez effectuer des comparaisons d'entiers :
    • '-eq' (est num�riquement �gal �)
      La cha�ne_de_test est consid�r�e comme un entier, et est compar�e num�riquement � l'expression_de_comparaison. Vrai si les deux expressions sont num�riquement �gales.
    • '-ge' (est num�riquement sup�rieur ou �gal �)
      La cha�ne_de_test est consid�r�e comme un entier, et est compar�e num�riquement � l'expression_de_comparaison. Vrai si cha�ne_de_test est num�riquement sup�rieure ou �gale � expression_de_comparaison.
    • '-gt' (est num�riquement sup�rieur �)
      La cha�ne_de_test est consid�r�e comme un entier, et est compar�e num�riquement � l'expression_de_comparaison. Vrai si cha�ne_de_test est num�riquement sup�rieure � expression_de_comparaison.
    • '-le' (est num�riquement inf�rieur ou �gal �)
      La cha�ne_de_test est consid�r�e comme un entier, et est compar�e num�riquement � l'expression_de_comparaison. Vrai si cha�ne_de_test est num�riquement inf�rieure ou �gale � expression_de_comparaison. Attention � la confusion avec le drapeau -l en utilisant la variante the -L ou -h.
    • '-lt' (est num�riquement inf�rieur �)
      La cha�ne_de_test est consid�r�e comme un entier, et est compar�e num�riquement � l'expression_de_comparaison. Vrai si cha�ne_de_test est num�riquement inf�rieure � expression_de_comparaison. Attention � la confusion avec le drapeau -l en utilisant la variante the -L ou -h.
  4. Vous pouvez effectuer diff�rents tests sur les attributs de fichier :
    • '-d' (est un r�pertoire - directory)
      Traite cha�ne_de_test comme un chemin et v�rifie s'il existe ou pas, et s'il s'agit d'un r�pertoire.
    • '-f' (est un fichier r�gulier)
      Traite cha�ne_de_test comme un chemin et v�rifie s'il existe ou pas, et s'il s'agit d'un fichier r�gulier.
    • '-F' (test de l'existence d'un fichier via une sous-requ�te)
      V�rifie si cha�ne_de_test est un fichier valide, accessible � travers tous les contr�les d'acc�s du serveur actuellement configur�s pour ce chemin. C'est une sous-requ�te interne qui effectue cette v�rification - � utiliser avec pr�cautions car les performances du serveur peuvent s'en trouver affect�es !
    • '-H' (est un lien symbolique, selon la convention bash)
      Voir -l.
    • '-l' (est un lien symbolique)
      Consid�re la cha�ne_de_test comme un chemin et v�rifie son existence et si elle est un lien symbolique. On peut aussi utiliser la convention bash -L ou -h lorsqu'il y a risque de confusion avec les tests -lt ou -le.
    • '-L' (est un lien symbolique, selon la convention bash)
      Voir -l.
    • '-s' (est un fichier r�gulier d'une certaine taille)
      Consid�re la cha�ne_de_test comme un chemin et v�rifie son existence et si elle est un fichier r�gulier d'une taille sup�rieure � z�ro.
    • '-U' (test de l'existence d'une URL via une sous-requ�te)
      V�rifie si cha�ne_de_test est une URL valide, accessible � travers tous les contr�les d'acc�s du serveur actuellement configur�s pour ce chemin. C'est une sous-requ�te interne qui effectue cette v�rification - � utiliser avec pr�cautions car les performances du serveur peuvent s'en trouver affect�es !

      Ce drapeau ne renvoie que des informations concernant le contr�le d'acc�s, l'authentification et l'autorisation. Il ne renvoie pas d'informations concernant le code d'�tat que le gestionnaire configur� (static file, CGI, proxy, etc...) aurait, quant � lui, retourn�.

    • '-x' (a l'attribut d'ex�cution positionn�)
      Consid�re la cha�ne_de_test comme un chemin et v�rifie son existence et si elle a son attribut d'ex�cution positionn�. Ce positionnement est d�termin� en fonction de l'OS sous-jacent.
  5. Si la cha�ne_de_test contient la valeur sp�ciale expr, la cha�ne_de_comparaison sera trait�e en tant qu'expression rationnelle de type ap_expr.

    Dans l'exemple ci-dessous, on utilise -strmatch pour comparer le REFERER avec le nom d'h�te du site afin de bloquer le hotlinking (r�f�rencement direct) non d�sir�.

               RewriteCond expr "! %{HTTP_REFERER} -strmatch '*://%{HTTP_HOST}/*'"
    RewriteRule ^/images - [F]
  6. Vous pouvez aussi d�finir certains drapeaux pour l'expression_de_comparaison en ajoutant ces [drapeaux] comme troisi�me argument de la directive RewriteCond, o� drapeaux est un sous-ensemble s�par� par des virgules des drapeaux suivants :
    • 'nocase|NC' (no case)
      Rend le test insensible � la casse - il n'est pas fait de distinction entre majuscules et minuscules, � la fois dans le d�veloppement de cha�ne_de_test et dans expression_de_comparaison. Ce drapeau n'est pris en compte que lors d'une comparaison entre cha�ne_de_test et expression_de_comparaison. Il ne l'est pas pour les v�rification par sous-requ�tes ou sur le syst�me de fichiers.
    • 'ornext|OR' (ou condition suivante)
      Permet de cha�ner les conditions de r�gles avec un OU au lieu du AND implicite. Exemple typique :
      RewriteCond %{REMOTE_HOST}  ^host1  [OR]
      RewriteCond %{REMOTE_HOST}  ^host2  [OR]
      RewriteCond %{REMOTE_HOST}  ^host3
      RewriteRule ...r�gles concernant tous ces h�tes...
      Sans ce drapeau, les paires condition/r�gle devraient �tre �crites trois fois.
    • 'novary|NV' (no vary)
      Si la condition contient un en-t�te HTTP, ce drapeau emp�che ce dernier d'�tre ajout� � l'en-t�te Vary de la r�ponse.
      L'utilisation de ce drapeau peut provoquer une mise en cache incorrecte de la r�ponse, si la repr�sentation de cette r�ponse varie avec la valeur de l'en-t�te consid�r�. Ce drapeau ne devrait donc �tre utilis� que si l'on ma�trise parfaitement le fonctionnement de l'en-t�te Vary.

Exemple :

Pour r��crire la page d'accueil d'un site en fonction de l'en-t�te ``User-Agent:'' de la requ�te, vous pouvez utiliser ce qui suit :

RewriteCond  %{HTTP_USER_AGENT}  (iPhone|Blackberry|Android)
RewriteRule  ^/$                 /homepage.mobile.html  [L]

RewriteRule  ^/$                 /homepage.std.html  [L]

Explications : si vous utilisez un navigateur qui s'identifie comme un navigateur de mobile (notez que cet exemple est incomplet car il existe de nombreuses autres plateformes mobiles), c'est la version mobile de la page d'accueil qui sera servie. Dans le cas contraire, vous verrez s'afficher la page d'accueil standard.

top

RewriteEngine Directive

Description:Active ou d�sactive l'ex�cution du moteur de r��criture
Syntaxe:RewriteEngine on|off
D�faut:RewriteEngine off
Contexte:configuration du serveur, serveur virtuel, r�pertoire, .htaccess
AllowOverride:FileInfo
Statut:Extension
Module:mod_rewrite

La directive RewriteEngine active ou d�sactive l'ex�cution du moteur de r��criture. Si sa valeur est off, ce module n'ex�cutera aucun traitement et ne mettra pas � jour les variables d'environnement SCRIPT_URx.

Plut�t que de commenter toutes les directives RewriteRule, il est pr�f�rable d'utiliser cette directive si l'on souhaite d�sactiver les r�gles de r��criture dans un contexte particulier.

Notez que les h�tes virtuels n'h�ritent pas des configurations de r��criture. Ceci implique que vous devez ins�rer une directive RewriteEngine on dans chaque h�te virtuel pour lequel vous souhaitez utiliser des r�gles de r��criture.

Les directives RewriteMap du type prg ne sont pas prises en compte au cours de l'initialisation du serveur si elle ont �t� d�finies dans un contexte o� la directive RewriteEngine n'a pas �t� d�finie � on.

top

RewriteMap Directive

Description:D�finit une fonction de mise en correspondance pour la recherche de mots-cl�s
Syntaxe:RewriteMap nom_de_la_correspondance type_de_correspondance:source_de_la_correspondance
Contexte:configuration du serveur, serveur virtuel
Statut:Extension
Module:mod_rewrite

La directive RewriteMap d�finit une Table de correspondance pour la r��criture que les fonctions de mise en correspondance peuvent utiliser dans les cha�nes de substitution des r�gles pour ins�rer/substituer des champs en recherchant des mots-cl�s. La source utilis�e pour cette recherche peut �tre de plusieurs types.

nom_de_la_correspondance est le nom de la table de correspondance et servira � sp�cifier une fonction de mise en correspondance pour les cha�nes de substitution d'une r�gle de r��criture selon une des constructions suivantes :

${ nom_de_la_correspondance : mot-cl� }
${ nom_de_la_correspondance : mot-cl� | valeur par d�faut }

Lorsqu'une telle construction est rencontr�e, la table de correspondance Nom_de_la_correspondance est consult�e et la cl� mot-cl� recherch�e. Si la cl� est trouv�e, la construction est remplac�e par la valeur de remplacement. Si la cl� n'est pas trouv�e, elle est remplac�e par la valeur par d�faut, ou par une cha�ne vide si aucune valeur par d�faut n'est sp�cifi�e. La valeur vide se comporte comme si la cl� �tait absente ; il est donc impossible de distinguer une valeur vide d'une absence de cl�.

Par exemple, vous pouvez d�finir une directive RewriteMap comme suit

RewriteMap map-exemple txt:/chemin/vers/fichier/map.txt

Vous pourrez ensuite utiliser cette table dans une directive RewriteRule comme suit :

RewriteRule ^/ex/(.*) ${map-exemple:$1}

Les combinaisons suivantes pour type de correspondance et source de la correspondance peuvent �tre utilis�es :

txt
Un fichier texte contenant des paires cl�-valeur s�par�es par des espaces, une paire par ligne (D�tails ...).
rnd
S�lection al�atoire d'une entr�e depuis un fichier texte (D�tails ...).
dbm
Recherche une entr�e dans un fichier dbm contenant des paires nom-valeur. Le condens� hash est �labor� � partir d'un format de fichier texte via l'utilitaire httxt2dbm (D�tails ...).
int
Une des quatre fonctions internes disponibles que fournit RewriteMap: toupper, tolower, escape ou unescape (D�tails ...).
prg
Appelle un programme externe ou un script pour effectuer la r��criture (D�tails ...).
dbd or fastdbd
Une commande SQL SELECT � ex�cuter pour rechercher la cible de r��criture (D�tails ...).

Vous trouverez plus de d�tails et de nombreux exemples dans le RewriteMap HowTo.

top

RewriteOptions Directive

Description:Configure certaines options sp�ciales pour le moteur de r��criture
Syntaxe:RewriteOptions Options
Contexte:configuration du serveur, serveur virtuel, r�pertoire, .htaccess
AllowOverride:FileInfo
Statut:Extension
Module:mod_rewrite
Compatibilit�:MaxRedirects n'est plus disponible depuis la version version 2.1

La directive RewriteOptions d�finit certaines options sp�ciales pour la configuration au niveau du serveur ou du r�pertoire. La cha�ne de caract�res Option ne peut actuellement prendre qu'une des valeurs suivantes :

Inherit

Ceci force la configuration locale � h�riter de la configuration du niveau sup�rieur. Dans le contexte des h�tes virtuels, cela signifie que les correspondances, conditions et r�gles du serveur principal sont h�rit�es. Dans le contexte des r�pertoires, cela signifie que les conditions et r�gles de la configuration .htaccess ou les sections <Directory> du r�pertoire parent sont h�rit�es. Les r�gles h�rit�es sont virtuellement copi�es dans la section o� cette directive est utilis�e. Si elles sont utilis�es avec des r�gles locales, les r�gles h�rit�es sont plac�es apr�s ces derni�res. La place de cette directive - avant ou apr�s les r�gles locales - n'a aucune influence sur ce comportement. Si des r�gles locales ont forc� l'arr�t de la r��criture, les r�gles h�rit�es ne seront pas trait�es.

Les r�gles h�rit�es du niveau parent sont appliqu�es after apr�s les r�gles sp�cifi�es dans le niveau enfant.
InheritBefore

M�me effet que l'option Inherit ci-dessus, mais les r�gles sp�cifi�es dans le niveau parent s'appliquent avant les r�gles sp�cifi�es dans le niveau enfant.
Disponible depuis la version 2.3.10 du serveur HTTP Apache.

InheritDown

Si cette option est activ�e, toutes les configurations enfants h�riteront de la configuration courante. Il en est de m�me si l'on sp�cifie RewriteOptions Inherit dans toutes les configurations enfants. Voir l'option Inherit pour plus de d�tails � propos de la mani�re dont les relations parent-enfants sont trait�es.
Cette option est disponible � partir de la version 2.4.8 du serveur HTTP Apache.

InheritDownBefore

L'effet de cette option est �quivalent � celui de l'option InheritDown ci-dessus, mais les r�gles de la configuration parente s'appliquent avant toute r�gle de la configuration enfant.
Cette option est disponible � partir de la version 2.4.8 du serveur HTTP Apache.

IgnoreInherit

Si cette option est activ�e, les configurations courante et enfants ignoreront toute r�gle h�rit�e d'une configuration parente via les options InheritDown ou InheritDownBefore.
Cette option est disponible � partir de la version 2.4.8 du serveur HTTP Apache.

AllowNoSlash

Par d�faut, mod_rewrite ignore les URLs qui correspondent � un r�pertoire sur disque, mais ne comportent pas de slash final, afin que le module mod_dir redirige le client vers l'URL canonique avec un slash final.

Lorsque la directive DirectorySlash est d�finie � off, il est possible de sp�cifier l'option AllowNoSlash pour s'assurer que les r�gles de r��criture ne soient plus ignor�es. Si on le souhaite, cette option permet de faire s'appliquer des r�gles de r��criture qui correspondent � un r�pertoire sans slash final au sein de fichiers .htaccess.
Elle est disponible � partir de la version 2.4.0 du serveur HTTP Apache.

AllowAnyURI

A partir de la version 2.2.22 de httpd, lorsqu'une directive RewriteRule se situe dans un contexte de serveur virtuel ou de serveur principal, mod_rewrite ne traitera les r�gles de r��criture que si l'URI de la requ�te respecte la syntaxe d'un chemin URL. Ceci permet d'�viter certains probl�mes de s�curit� o� des r�gles particuli�res pourraient permettre des d�veloppements de mod�les inattendus (voir CVE-2011-3368 et CVE-2011-4317). Pour s'affranchir de la restriction relative � la syntaxe des chemins URL, on peut utiliser l'option AllowAnyURI, afin de permettre � mod_rewrite d'appliquer le jeu de r�gles � toute cha�ne de requ�te URI, sans v�rifier si cette derni�re respecte la grammaire des chemins URL d�finie dans la sp�cification HTTP.
Disponible depuis la version 2.4.3 du serveur HTTP Apache.

Avertissement � propos de la s�curit�

L'utilisation de cette option rendra le serveur vuln�rable � certains probl�mes de s�curit� si les r�gles de r��critures concern�es n'ont pas �t� r�dig�es avec soin. Il est par cons�quent fortement recommand� de ne pas utiliser cette option. En particulier, pr�tez attention aux cha�nes en entr�e contenant le caract�re '@', qui peuvent modifier l'interpr�tation de l'URI r��crite, comme indiqu� dans les liens ci-dessus.

MergeBase

Avec cette option, la valeur de la directive RewriteBase est copi�e depuis le r�pertoire o� elle est explicitement d�finie dans tout sous-r�pertoire qui ne d�finit pas sa propre directive RewriteBase. C'�tait le comportement par d�faut de la version 2.4.0 � la version 2.4.3, et cette option permet de le r�tablir � partir de la version 2.4.4 du serveur HTTP Apache.

top

RewriteRule Directive

Description:D�finit les r�gles pour le moteur de r��criture
Syntaxe:RewriteRule Mod�le Substitution [drapeaux]
Contexte:configuration du serveur, serveur virtuel, r�pertoire, .htaccess
AllowOverride:FileInfo
Statut:Extension
Module:mod_rewrite

La directive RewriteRule est le v�ritable cheval de trait de la r��criture. La directive peut appara�tre plusieurs fois, chaque instance d�finissant une r�gle de r��criture particuli�re. L'ordre dans lequel ces r�gles sont d�finies est important - il s'agit de l'ordre dans lequel les r�gles seront appliqu�es au cours du processus de r��criture.

Mod�le est une expression rationnelle compatible perl. Dans la premi�re r�gle de r��criture, l'expression est compar�e au (%-decoded) chemin de l'URL (ou au chemin fichier, en fonction du contexte) de la requ�te. Les expressions suivantes sont compar�es � la sortie de la derni�re r�gle de r��criture qui correspondait.

Qu'est-ce qui est compar� ?

Dans un contexte de serveur virtuel VirtualHost, le mod�le est tout d'abord compar� � la portion de l'URL situ�e entre le nom d'h�te �ventuellement accompagn� du port, et la cha�ne de param�tres (par exemple "/app1/index.html").

Dans les contextes de r�pertoire Directory et htaccess, le mod�le est tout d'abord compar� au chemin du syst�me de fichiers, apr�s suppression du pr�fixe ou chemin de base ayant conduit le serveur vers la r�gle RewriteRule (par exemple "app1/index.html" ou "index.html" selon l'endroit o� les directives sont d�finies).

Si vous souhaitez faire une comparaison sur le nom d'h�te, le port, ou la cha�ne de requ�te, utilisez une directive RewriteCond comportant respectivement les variables %{HTTP_HOST}, %{SERVER_PORT}, ou %{QUERY_STRING}.

R��critures dans un contexte de r�pertoire

  • L'utilisation du moteur de r��criture dans les fichiers .htaccess et les sections <Directory> est un peu plus complexe.
  • Pour activer le moteur de r��criture dans ces contextes, vous devez d�finir "RewriteEngine On" et "Options FollowSymLinks". Si l'administrateur a d�sactiv� la possibilit� de modifier l'option FollowSymLinks au niveau du r�pertoire d'un utilisateur, vous ne pouvez pas utiliser le moteur de r��criture. Cette restriction a �t� instaur�e � des fins de s�curit�.
  • Lorsqu'on utilise le moteur de r��criture dans un fichier .htaccess, le chemin de base du r�pertoire courant (qui est toujours le m�me pour ce m�me r�pertoire) est automatiquement supprim� au cours de la comparaison avec le mod�le de la r�gle de r��criture, et automatiquement ajout� lorsqu'une substitution relative (ne d�butant pas par un slash ou un nom de protocole) arrive � la fin d'un jeu de r�gles. Voir la directive RewriteBase pour plus de d�tails � propos de l'ajout du pr�fixe apr�s les substitutions relatives.
  • Si vous souhaitez effectuer une comparaison en prenant en compte l'int�gralit� du chemin de l'URL dans un contexte de r�pertoire (htaccess), vous devez utiliser la variable %{REQUEST_URI} dans la directive RewriteCond.
  • Le prefixe supprim� se termine toujours par un slash, ce qui signifie que la comparaison s'effectue avec une cha�ne qui ne comporte jamais de slash de d�but. Ainsi, un mod�le contenant ^/ ne correspondra jamais dans un contexte de r�pertoire.
  • Bien que les r�gles de r��criture soient permises du point de vue de la syntaxe dans les sections <Location> et <Files>, elles n'y sont pas prises en compte, et n'y sont � priori d'aucune utilit�.

Pour quelques conseils � propos des expressions rationnelles, voir le document Introduction � mod_rewrite.

Dans mod_rewrite, on peut aussi utiliser le caract�re NON ('!') comme pr�fixe de mod�le. Ceci vous permet d'inverser la signification d'un mod�le, soit pour dire ``si l'URL consid�r�e ne correspond PAS � ce mod�le''. Le caract�re NON peut donc �tre utilis� � titre exceptionnel, lorsqu'il est plus simple d'effectuer une comparaison avec le mod�le invers�, ou dans la derni�re r�gle par d�faut.

Note

Si vous utilisez le caract�re NON pour inverser la signification d'un mod�le, vous ne pouvez pas inclure de parties g�n�riques group�es dans le mod�le. Ceci est d� au fait que, lorsque le mod�le ne correspond pas (autrement dit, sa n�gation correspond), les groupes sont vides. Ainsi, si vous utilisez des mod�les invers�s, vous ne pouvez pas vous r�f�rer aux groupes par $N dans la cha�ne de substitution !

Dans une r�gle de r��criture, Substitution est la cha�ne de caract�res qui remplace le chemin de l'URL original qui correspondait au Mod�le. Substitution peut �tre :

un chemin du syst�me de fichiers
Il indique alors la localisation dans le syst�me de fichiers de la ressource qui doit �tre envoy�e au client. Les substitutions ne sont trait�es en tant que chemins du syst�me de fichiers que si la r�gle est configur�e dans un contexte de serveur (serveur virtuel), et si le premier composant du chemin dans la substitution existe dans le syst�me de fichiers.
chemin d'URL
Un chemin relatif � la valeur de DocumentRoot vers la ressource qui doit �tre servie. Notez que mod_rewrite essaie de deviner si vous avez sp�cifi� un chemin du syst�me de fichiers ou un chemin d'URL en v�rifiant si la premi�re partie du chemin existe � la racine du syst�me de fichiers. Par exemple, si vous avez sp�cifi� comme cha�ne de Substitution /www/file.html, cette derni�re sera trait�e comme un chemin d'URL � moins qu'un r�pertoire nomm� www n'existe � la racine de votre syst�me de fichiers (ou dans le cas d'une r��criture au sein d'un fichier .htaccess, relativement � la racine des documents), auquel cas la cha�ne de substitution sera trait�e comme un chemin du syst�me de fichiers. Si vous d�sirez que d'autres directives de correspondance d'URL (comme la directive Alias) soient appliqu�es au chemin d'URL r�sultant, utilisez le drapeau [PT] comme d�crit ci-dessous.
URL absolue
Si une URL absolue est sp�cifi�e, mod_rewrite v�rifie si le nom d'h�te correspond � celui de l'h�te local. Si c'est le cas, le protocole et le nom d'h�te sont supprim�s, et ce qui reste est trait� comme un chemin d'URL. Dans le cas contraire, une redirection externe vers l'URL indiqu�e est effectu�e. Pour forcer une redirection externe vers l'h�te local, voir le drapeau [R] ci-dessous.
- (tiret)
Un tiret indique qu'aucune substitution ne doit �tre effectu�e (le chemin consid�r� est transmis sans changement). Ceci est utile quand un drapeau doit �tre appliqu� sans modifier le chemin (voir ci-dessous).

En plus du texte, la cha�ne Substition peut comporter :

  1. des r�f�rences arri�res ($N) vers le mod�le d'une directive RewriteRule
  2. des r�f�rences arri�res (%N) vers le dernier mod�le d'une directive RewriteCond qui correspondait
  3. des variables du serveur comme dans les cha�nes de test de condition d'une r�gle (%{VARNAME})
  4. des appels de fonctions de comparaison (${nom correspondance:cl�|d�faut})

Les r�f�rences arri�res sont des identificateurs de la forme $N (N=0..9), qui seront remplac�s par le contenu du N�me groupe du Mod�le qui correspondait. Les variables du serveur sont les m�mes que dans la Cha�ne de test d'une directive RewriteCond. Les fonctions de comparaison sont issues de la directive RewriteMap dans la section de laquelle elles sont d�crites. Ces trois types de variables sont �valu�es dans l'ordre ci-dessus.

Chaque r�gle de r��criture s'applique au r�sultat de la r�gle pr�c�dente, selon l'ordre dans lequel elles ont �t� d�finies dans le fichier de configuration. Le chemin de l'URL ou du syst�me de fichier (voir ci-dessus Qu'est-ce qui est compar� ?) est int�gralement remplac�e par la cha�ne de Substitution et le processus de r��criture se poursuit jusqu'� ce que toutes les r�gles aient �t� appliqu�es, ou qu'il soit explicitement stopp� par un drapeau L, ou par un autre drapeau qui implique un arr�t imm�diat, comme END ou F.

Modifier la cha�ne de requ�te

Par d�faut, la cha�ne de requ�te est transmise sans modification. Vous pouvez cependant cr�er dans la cha�ne de substitution des URLs dont une partie constitue une cha�ne de requ�te. Pour cela, ajoutez simplement un point d'interrogation dans la cha�ne de substitution pour indiquer que le texte qui suit doit �tre r�inject� dans la cha�ne de requ�te. Pour supprimer une cha�ne de requ�te, terminez simplement la cha�ne de substitution par un point d'interrogation. Pour combiner les nouvelles cha�nes de requ�te avec les anciennes, utilisez le drapeau [QSA].

En outre, vous pouvez sp�cifier des actions sp�ciales � effectuer en ajoutant des [drapeaux] comme troisi�me argument de la directive RewriteRule. S�par�s par des virgules au sein d'une liste encadr�e par des crochets, les drapeaux peuvent �tre choisis dans la table suivante. Vous trouverez plus de d�tails, et des exemples pour chaque drapeau dans le document � propos des drapeaux de r��criture.

Drapeaux et syntaxe Fonction
B Echappe les caract�res non-alphanum�riques avant d'appliquer la transformation. d�tails ...
chain|C La r�gle est cha�n�e avec la r�gle suivante. Si la r�gle �choue, la ou les r�gles avec lesquelles elle est est cha�n�e seront saut�es. d�tails ...
cookie|CO=NAME:VAL D�finit un cookie au niveau du navigateur client. La syntaxe compl�te est : CO=NAME:VAL:domain[:lifetime[:path[:secure[:httponly]]]] details ... d�tails ...
discardpath|DPI Supprime la partie PATH_INFO de l'URI r��crit. d�tails ...
END Stoppe le processus de r��criture imm�diatement et n'applique plus aucune r�gle. Emp�che aussi l'application ult�rieure de r�gles de r��criture dans les contextes de r�pertoire et de fichier .htaccess (disponible � partir de la version 2.3.9 du serveur HTTP Apache). d�tails ...
env|E=[!]VAR[:VAL] D�finit la variable d'environnement VAR (� la valeur VAL si elle est fournie). La variante !VAR annule la d�finition de la variable VAR.d�tails ...
forbidden|F Renvoie une r�ponse 403 FORBIDDEN au navigateur client. d�tails ...
gone|G Renvoie un message d'erreur 410 GONE au navigateur client. d�tails ...
Handler|H=Gestionnaire de contenu L'URI r�sultant est envoy� au Gestionnaire de contenu pour traitement. d�tails ...
last|L Arr�te le processus de r��criture imm�diatement et n'applique plus aucune r�gle. Pr�tez une attention particuli�re aux mises en garde concernant les contextes de niveau r�pertoire et .htaccess (voir aussi le drapeau END). d�tails ...
next|N R�ex�cute le processus de r��criture � partir de la premi�re r�gle, en utilisant le r�sultat du jeu de r�gles, sous r�serve qu'il y ait un point de d�part. d�tails ...
nocase|NC Rend la comparaison entre mod�les insensible � la casse. d�tails ...
noescape|NE Emp�che mod_rewrite d'effectuer un �chappement hexad�cimal des caract�res sp�ciaux dans le r�sultat de la r��criture. d�tails ...
nosubreq|NS La r�gle est saut�e si la requ�te courante est une sous-requ�te interne. d�tails ...
proxy|P Force l'envoi en interne de l'URL de substitution en tant que requ�te mandataire. d�tails ...
passthrough|PT L'URI r�sultant est repass� au moteur de mise en correspondance des URLs pour y �tre trait� par d'autres traducteurs URI-vers-nom de fichier, comme Alias ou Redirect. d�tails ...
qsappend|QSA Ajoute toute cha�ne de param�tres pr�sente dans l'URL de la requ�te originale � toute cha�ne de param�tres cr��e dans la cible de r��criture. d�tails ...
qsdiscard|QSD Supprime toute cha�ne de param�tres de l'URI entrant. d�tails ...
redirect|R[=code] Force une redirection externe, avec un code de statut HTTP optionnel. d�tails ...
skip|S=nombre Si la r�gle courante s'applique, le moteur de r��criture doit sauter les nombre r�gles suivantes. d�tails ...
type|T=MIME-type Force l'attribution du Type-MIME sp�cifi� au fichier cible. d�tails ...

D�veloppement du r�pertoire home

Quand la cha�ne de substitution commence par quelque chose comme "/~user" (de mani�re explicite ou par r�f�rences arri�res), mod_rewrite d�veloppe le r�pertoire home sans tenir compte de la pr�sence ou de la configuration du module mod_userdir.

Ce d�veloppement n'est pas effectu� si le drapeau PT est utilis� dans la directive RewriteRule

Voici toutes les combinaisons de substitution et leurs significations :

Dans la configuration au niveau du serveur principal (apache2.conf)
pour la requ�te ``GET /chemin/infochemin'':

R�gle R�sultat de la substitution
^/un_chemin(.*) autre_chemin$1 invalide, non support�
^/un_chemin(.*) autre_chemin$1 [R] invalide, non support�
^/un_chemin(.*) autre_chemin$1 [P] invalide, non support�
^/un_chemin(.*) /autre_chemin$1 /autre_chemin/info_chemin
^/un_chemin(.*) /autre_chemin$1 [R] http://cet_hote/autre_chemin/info_chemin via une redirection externe
^/un_chemin(.*) /autre_chemin$1 [P] sans objet, non support�
^/un_chemin(.*) http://cet_hote/autre_chemin$1 /autre_chemin/info_chemin
^/un_chemin(.*) http://cet_hote/autre_chemin$1 [R] http://cet_hote/autre_chemin/info_chemin via une redirection externe
^/un_chemin(.*) http://cet_hote/autre_chemin$1 [P] sans objet, non support�
^/un_chemin(.*) http://autre_hote/autre_chemin$1 http://autre_hote/autre_chemin/info_chemin via une redirection externe
^/un_chemin(.*) http://autre_hote/autre_chemin$1 [R] http://autre_hote/autre_chemin/info_chemin (le drapeau [R] est redondant)
^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo via internal proxy

Dans une configuration de niveau r�pertoire pour /chemin
(/chemin/physique/vers/chemin/.htacccess, avec RewriteBase /chemin)
pour la requ�te ``GET /chemin/chemin-local/infochemin'':

R�gle R�sultat de la substitution
^chemin-local(.*) autre-chemin$1 /chemin/autre-chemin/infochemin
^chemin-local(.*) autre-chemin$1 [R] http://cet-h�te/chemin/autre-chemin/infochemin via redirection externe
^chemin-local(.*) autre-chemin$1 [P] n'a pas lieu d'�tre, non support�
^chemin-local(.*) /autre-chemin$1 /autre-chemin/infochemin
^chemin-local(.*) /autre-chemin$1 [R] http://cet-h�te/autre-chemin/infochemin via redirection externe
^chemin-local(.*) /autre-chemin$1 [P] n'a pas lieu d'�tre, non support�
^chemin-local(.*) http://cet-h�te/autre-chemin$1 /autre-chemin/infochemin
^chemin-local(.*) http://cet-h�te/autre-chemin$1 [R] http://cet-h�te/autre-chemin/infochemin via redirection externe
^chemin-local(.*) http://cet-h�te/autre-chemin$1 [P] n'a pas lieu d'�tre, non support�
^chemin-local(.*) http://autre h�te/autre-chemin$1 http://autre h�te/autre-chemin/infochemin via redirection externe
^chemin-local(.*) http://autre h�te/autre-chemin$1 [R] http://autre h�te/autre-chemin/infochemin via redirection externe (le drapeau [R] est redondant)
^chemin-local(.*) http://autre h�te/autre-chemin$1 [P] http://autre h�te/autre-chemin/infochemin via un mandataire interne

Langues Disponibles:  en  |  fr 

top

Commentaires

Notice:
This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our mailing lists.