Module Apache mod_rewrite

RewriteBase Directive

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 :

• La requ�te initiale, ainsi que la substitution, sont dans la DocumentRoot (c'est � dire que pour y acc�der, il n'est pas n�cessaire d'utiliser une directive telle qu'Alias).
• Le chemin du syst�me de fichiers vers le r�pertoire contenant la RewriteRule, suffix� par la substitution relative est aussi valide en tant qu'URL sur le serveur (ce qui est rare).

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>

RewriteCond Directive

La directive RewriteCond d�finit une condition d'application d'une certaine r�gle. Une ou plusieurs directives RewriteCond peuvent pr�c�der une directive RewriteRule. La r�gle qui suit n'est appliqu�e que si l'�tat actuel de l'URI correspond � son mod�le, et si les conditions sont satisfaites.

cha�ne de test est une cha�ne de caract�res qui peut contenir, en plus du plein texte, les constructions �tendues suivantes :

• r�f�rences arri�res de r�gle de r��criture : ce sont des r�f�rences arri�res de la forme $N (0 <= N <= 9), qui donnent acc�s aux parties group�es (entre parenth�ses) du mod�le tir� de la RewriteRule assujettie au jeu de conditions concern�.
• R�f�rences arri�res de condition de r��criture : ce sont des r�f�rences arri�res de la forme %N (1 <= N <= 9), qui donnent acc�s aux parties group�es (l� aussi entre parenth�ses) du mod�le de la derni�re condition satisfaite du jeu de conditions concern�.
• extensions de table de r��criture : ce sont des extensions de la forme ${nomTable:cl�|d�faut}. Voir la documentation de RewriteMap pour plus de d�tails.
• Variables du serveur : ce sont des variables de la forme %{ NOM_DE_VARIABLE } %{ NOM_DE_VARIABLE } o� NOM_DE_VARIABLE peut �tre une cha�ne de caract�res faisant partie de la liste suivante :

  En-t�tes HTTP :	connexion & requ�te:
  HTTP_USER_AGENT HTTP_REFERER HTTP_COOKIE HTTP_FORWARDED HTTP_HOST HTTP_PROXY_CONNECTION HTTP_ACCEPT	REMOTE_ADDR REMOTE_HOST REMOTE_PORT REMOTE_USER REMOTE_IDENT REQUEST_METHOD SCRIPT_FILENAME PATH_INFO QUERY_STRING AUTH_TYPE
  variables internes au serveur :	date et heure :	sp�ciaux :
  DOCUMENT_ROOT SERVER_ADMIN SERVER_NAME SERVER_ADDR SERVER_PORT SERVER_PROTOCOL SERVER_SOFTWARE	TIME_YEAR TIME_MON TIME_DAY TIME_HOUR TIME_MIN TIME_SEC TIME_WDAY TIME	API_VERSION THE_REQUEST REQUEST_URI REQUEST_FILENAME IS_SUBREQ HTTPS

  Toutes ces variables correspondent nom pour nom aux en-t�tes MIME HTTP, aux variables C du serveur Apache ou aux champs struct tm du syst�me Unix. La plupart sont document�es dans une autre partie du manuel ou dans la sp�cification CGI.

  SERVER_NAME et SERVER_PORT d�pendent respectivement des valeurs des directives UseCanonicalName et UseCanonicalPhysicalPort.

  Parmi les variables sp�cifiques � mod_rewrite, ou trouve les suivantes :

  IS_SUBREQ

  Contiendra le texte "true" si la requ�te en cours de traitement est une sous-requ�te, "false" dans le cas contraire. Une sous-requ�te est g�n�r�e quand un module a besoin de se r�f�rer � des fichiers ou URIs addidionnels pour pouvoir mener � bien sa t�che.

  API_VERSION

  Il s'agit de la version de l'API des modules Apache (l'interface interne entre le serveur et les modules) dans la construction actuelle de httpd, telle qu'elle est d�finie dans include/ap_mmn.h. La version de l'API des modules correspond � la version d'Apache utilis�e (pour Apache 1.3.14, par exemple, la version de l'API sera 19990320:10), mais cette information int�resse principalement les d�veloppeurs de modules.

  THE_REQUEST

  La ligne de requ�te HTTP compl�te envoy�e par le navigateur au serveur (par exemple, "GET /index.html HTTP/1.1"), � l'exclusion de tout en-t�te ajout� par le navigateur. Cette valeur n'a pas �t� d�s�chapp�e (d�cod�e), � la diff�rence de la plupart des variables suivantes.

  REQUEST_URI

  La partie chemin de l'URI de la requ�te, comme "/index.html". En particulier, ceci exclut la cha�ne de param�tres qui est quant � elle disponible via sa propre variable QUERY_STRING.

  REQUEST_FILENAME

  Le chemin complet local au syst�me de fichiers du fichier ou du script correspondant � la requ�te, s'il a d�j� �t� d�termin� par le serveur au moment o� on y fait r�f�rence. Dans le cas contraire, et en particulier dans le cas d'un serveur virtuel, REQUEST_FILENAME contient la valeur de REQUEST_URI.

  HTTPS

  Contiendra le texte "on" si la connexion utilise SSL/TLS, "off" dans le cas contraire (L'utilisation de cette variable est pertinente, ind�pendamment du fait que mod_ssl soit charg� ou non).

Autres points � conna�tre :

1. Les variables SCRIPT_FILENAME et REQUEST_FILENAME ont la m�me valeur - celle du champ filename de la structure interne du serveur Apache request_rec. Le premier nom est bien connu en tant que variable CGI, alors que le second est �quivalent � REQUEST_URI (qui contient la valeur du champ uri de la structure request_rec).

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

   Dans un contexte de serveur principal (c'est � dire avant que la requ�te n'ait �t� mise en relation avec le syst�me de fichiers), SCRIPT_FILENAME et REQUEST_FILENAME ne peuvent pas contenir le chemin local entier dans le syst�me de fichiers, car celui-ci n'a pas encore �t� d�termin� � ce stade du traitement. Les deux variables contiennent alors la valeur de REQUEST_URI. Pour obtenir le chemin local entier associ� � la requ�te dans le syst�me de fichiers dans un contexte de serveur principal, utilisez une recherche avant %{LA-U:REQUEST_FILENAME} pour d�terminer la valeur finale de REQUEST_FILENAME.

2. On peut aussi utiliser %{ENV:variable}, o� variable peut �tre remplac� par toute variable d'environnement. Ces variables sont recherch�es dans les structures internes d'Apache, et (si elles n'y figurent pas) via getenv() depuis le processus du serveur Apache.
3. 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, mais la valeur produite sera toujours une cha�ne de caract�res vide si mod_ssl n'est pas charg�. Exemple : %{SSL:SSL_CIPHER_USEKEYSIZE} peut correspondre � 128.
4. Pour obtenir la valeur d'un en-t�te contenu dans une requ�te HTTP, on peut toujours utiliser %{HTTP:header}, o� header peut �tre remplac� par tout nom d'en-t�te MIME HTTP. Exemple : %{HTTP:Proxy-Connection} est la valeur de l'en-t�te HTTP ``Proxy-Connection:''.

   Si une condition contient un en-t�te HTTP, il est ajout� � l'en-t�te Vary de la r�ponse dans le cas o� la condition est �valu�e � true pour la requ�te. Dans le cas contraire, il n'est pas ajout�. L'ajout de l'en-t�te HTTP � l'en-t�te Vary de la r�ponse s'av�re n�cessaire pour une mise en cache correcte.

   Il faut garder � l'esprit que les conditions suivent une logique de court-circuit en cas de pr�sence du drapeau 'ornext|OR', si bien que certaines d'entre elles sont susceptibles de ne pas �tre �valu�es du tout.

5. On peut utiliser %{LA-U:variable} pour les recherches en avant qui effectuent une sous-requ�te interne (bas�e sur l'URL), pour d�terminer la valeur finale de variable. Cela peut servir � acc�der � une variable (n�cessaire pour une r��criture) qui n'est pas disponible dans la situation pr�sente, mais le sera dans une phase ult�rieure.

   Par exemple, pour effectuer une r��criture qui tient compte de la variable REMOTE_USER dans un contexte niveau serveur (fichier httpd.conf), vous devez utiliser %{LA-U:REMOTE_USER} ; cette variable est d�finie au cours des phases d'autorisation, qui interviennent apr�s la phase de traduction de l'URL (pendant laquelle agit mod_rewrite).

   Par contre, comme mod_rewrite impl�mente son contexte niveau r�pertoire (fichier .htaccess) via la phase Fixup de l'API, et comme les phases d'autorisation interviennent avant cette phase, vous ne pouvez utiliser %{REMOTE_USER} que dans le contexte niveau serveur.

6. On peut utiliser %{LA-F:variable} pour effectuer une sous-requ�te interne (bas�e sur un nom de fichier), pour d�terminer la valeur finale de variable. La plupart du temps, elle est identique � LA-U vue pr�c�demment.

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.

A savoir : expression de comparaison est une expression rationnelle compatible perl avec quelques extensions :

1. Vous pouvez pr�fixer l'expression avec un caract�re '!' (point d'exclamation) pour indiquer une expression de non-correspondance.
2. Il existe certaines variantes sp�ciales d'expressions de comparaison. A la place d'une expression rationnelle, vous pouvez utiliser :
   • '<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.
   • '-d' (est un r�pertoire)
     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.
   • '-s' (est un fichier r�gulier d'une certaine taille)
     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 dont la taille est sup�rieure � z�ro.
   • '-l' (est un lien symbolique)
     Traite cha�ne de test comme un chemin et v�rifie s'il existe ou pas, et s'il s'agit d'un lien symbolique.
   • '-x' (a le droit d'ex�cussion)
     Traite cha�ne de test comme un chemin et v�rifie s'il existe ou pas, et a le droit d'ex�cution. Ce droit est d�termin� en accord avec le syst�me d'exploitation sous-jacent.
   • '-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 !

   • '-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�.

   Note :

   Tous ces tests peuvent aussi �tre pr�fix�s par un point d'exclamation ('!') pour inverser leur signification.
3. 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}  ^hote1  [OR]
     RewriteCond %{REMOTE_HOST}  ^hote2  [OR]
     RewriteCond %{REMOTE_HOST}  ^hote3
     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}  ^Mozilla
RewriteRule  ^/$                 /homepage.max.html  [L]

RewriteCond  %{HTTP_USER_AGENT}  ^Lynx
RewriteRule  ^/$                 /homepage.min.html  [L]

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

Explications : si vous utilisez un navigateur (Netscape Navigator, Mozilla etc) qui s'identifie comme 'Mozilla', vous acc�derez � la page d'accueil max (qui peut contenir des frames, ou d'autres ressources particuli�res). Si vous utilisez le navigateur Lynx (qui est un navigateur bas� sur le texte), vous acc�derez � une page d'accueil min (qui peut �tre une version con�ue pour une navigation simple bas�e sur le texte). Si aucune de ces conditions n'est satisfaite (vous utilisez tout autre navigateur, ou votre navigateur s'identifie de mani�re non standard), vous acc�derez � la page d'accueil std (standard).

RewriteEngine Directive

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.

Pour d�sactiver le module, il vaut mieux utiliser cette directive que commenter toutes les directives RewriteRule !

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.

RewriteLock Directive

Cette directive d�finit le nom du fichier utilis� comme fichier verrou de synchronisation n�cessaire � mod_rewrite pour communiquer avec les programmes li�s � RewriteMap. D�finissez ce fichier verrou dans un chemin local (et non sur un montage NFS) si vous voulez utiliser un programme de comparaison pour la r��criture. Il n'est pas n�cessaire pour les autres types de comparaison pour la r��criture.

RewriteLog Directive

La directive RewriteLog d�finit le nom du fichier dans lequel le serveur journalise tout processus de r��criture qu'il effectue. Si le nom ne commence pas par un slash ('/'), il est consid�r� comme relatif � la Racine du serveur. Cette directive ne doit appara�tre qu'une seule fois dans la configuration du serveur.

Le format de fichier journal RewriteLog se pr�sente comme suit :

RewriteLogLevel Directive

La directive RewriteLogLevel d�finit le niveau de verbosit� du fichier journal de r��criture. Le niveau par d�faut 0 signifie aucune journalisation, tandis que 9 ou plus signifie que pratiquement toutes les actions sont journalis�es.

Pour d�sactiver la journalisation des actions de r��criture, positionnez simplement niveau � 0. Ceci d�sactive toute journalisation des actions de r��criture.

RewriteMap Directive

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

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

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

• Format texte standard
  type de correspondance : txt, source de la correspondance : chemin du syst�me de fichiers Unix vers un fichier r�gulier valide

  Il s'agit de la mise en oeuvre standard de la table de correspondance pour la r��criture o� source de la correspondance est un fichier ASCII dont les diff�rentes lignes sont soit des lignes vides, soit des lignes de commentaires (commen�ant par un caract�re "#"), soit des paires de valeurs (une seule paire par ligne) comme suit :

  mot-cl� valeur de remplacement

  Exemple

  ##
  ##  map.txt -- table de correspondance pour la r��criture
  ##
  
  Ralf.S.Engelschall    rse   # Bastard Operator From Hell
  (traduction � votre convenance)
  Mr.Joe.Average        joe   # Mr. Average

  RewriteMap real-to-user txt:/chemin/vers/fichier/map.txt

• Format texte avec valeurs al�atoires
  type de correspondance: rnd, source de la correspondance : chemin du syst�me de fichiers Unix vers un fichier r�gulier valide

  Ce format se diff�rencie du format texte standard pr�c�dent par l'ajout d'un traitement suppl�mentaire : en plus de la recherche de cl�s, le fichier est interpr�t� en tenant compte de la pr�sence �ventuelle dans les valeurs de remplacement de caract�res ``|'' signifiant ``ou''. En d'autres termes, ces caract�res ``|'' permettent de sp�cifier un jeu de valeurs parmi lesquelles la valeur de retour sera choisie al�atoirement. Par exemple, vous pouvez utiliser les fichier de correspondance et directives suivants pour mettre en oeuvre une r�partition de charge al�atoire entre plusieurs serveurs en arri�re-plan, via un mandataire inverse. Les images sont envoy�es � un des serveurs de l'ensemble "statique", tandis que tout le reste est envoy� � un des serveurs de l'ensemble "dynamique".

  Exemple:

  Fichier de correspondances pour la r��criture

  ##
  ##  map.txt -- correspondances pour la r��criture
  ##
  
  static   www1|www2|www3|www4
  dynamic  www5|www6

  Directives de configuration

  RewriteMap serveurs rnd:/chemin/vers/fichier/map.txt

RewriteRule ^/(.*\.(png|gif|jpg)) http://${serveurs:static}/$1 [NC,P,L]
RewriteRule ^/(.*) http://${serveurs:dynamic}/$1 [P,L]

• Fichier � acc�s direct (Hash file)
  type de correspondance : dbm[=type], source de la correspondance : chemin du syst�me de fichiers Unix vers un fichier r�gulier valide

  Ici, la source de la correspondance est un fichier binaire au format DBM contenant les m�mes donn�es qu'un fichier au format Plein texte, mais selon une repr�sentation particuli�re optimis�e en vue d'une recherche tr�s rapide. Le type peut �tre sdbm, gdbm, ndbm, ou db selon la configuration � la compilation . Si type est omis, la valeur retenue sera la valeur par d�faut d�finie � la compilation.

  La cr�ation du fichier dbm � partir d'un fichier texte s'effectue � l'aide de l'utilitaire httxt2dbm.

  $ httxt2dbm -i fichier-source.txt -o fichier-dbm.map

• Fonction interne
  type de la correspondance : int, source de la correspondance : fonction interne � Apache

  Ici, la source de la correspondance est une fonction interne � Apache. Les d�veloppeurs de modules peuvent fournir des fonctions internes suppl�mentaires en les enregistrant via l'API ap_register_rewrite_mapfunc. Les fonctions fournies par d�faut sont :

  • toupper:
    Convertit tous les caract�res de la cl� en majuscules.
  • tolower:
    Convertit tous les caract�res de la cl� en minuscules.
  • escape:
    Traduit les caract�res sp�ciaux que contient la cl� en s�quences hexad�cimales.
  • unescape:
    Reconvertit les s�quences hexad�cimales que contient la cl� en caract�res sp�ciaux.
• Programme de r��criture externe
  type de la correspondance : prg, source de la correspondance : chemin du syst�me de fichiers Unix vers un fichier r�gulier valide

  Ici, la source n'est pas un fichier de correspondances, mais un programme. Pour le cr�er, vous pouvez utiliser le langage de votre choix, mais le programme doit �tre un ex�cutable (soit du code objet, soit un script contenant le fameux "#!/chemin/vers/interpr�teur" au d�but de sa premi�re ligne).

  Ce programme est lanc� une seule fois au d�marrage du serveur Apache, puis communique avec le moteur de r��criture via ses entr�e et sortie standards (stdin et stdout). A chaque recherche effectu�e par la fonction de correspondance, il re�oit sur son entr�e standard la cl� � rechercher sous la forme d'une cha�ne de caract�res termin�e par le caract�re "nouvelle ligne". Il doit ensuite renvoyer sur sa sortie standard la valeur recherch�e sous la forme d'une cha�ne de caract�res termin�e par le caract�re "nouvelle ligne", ou la cha�ne de quatre caract�res ``NULL'' en cas d'�chec (c'est � dire si aucune valeur ne correspond � la cl� fournie). Voici un exemple de ce pourrait �tre un programme trivial qui impl�menterait une correspondance 1:1 (c'est � dire, cl� == valeur) :

  Les programmes de r��criture externes ne seront pas lanc�s s'ils ont �t� d�finis dans un contexte o� la directive RewriteEngine n'a pas �t� d�finie � on.

  #!/usr/bin/perl
  $| = 1;
  while (<STDIN>) {
      # ...ins�rer ici le code de transformation ou de recherche...
      print $_;
  }

  Mais soyez tr�s prudent :

  1. ``Ce programme doit �tre simple, basique'' (MERCI). Si ce programme se bloque, il bloquera aussi Apache lorsqu'il tentera d'utiliser la r�gle de r��criture correspondante.
  2. L'utilisation d'entr�es/sorties avec tampon sur stdout est une erreur courante. Ceci est � proscrire sous peine de cr�er une boucle infernale ! Pour �viter ceci, on utilise ``$|=1'' comme dans l'exemple ci-dessus.
  3. On peut d�finir la directive RewriteLock pour sp�cifier un fichier verrou que mod_rewrite pourra utiliser pour synchroniser les communications avec le programme de correspondance. Par d�faut, aucune synchronisation de ce type n'est mise en oeuvre.

La directive RewriteMap peut appara�tre plusieurs fois. Utilisez une directive RewriteMap par fonction de correspondance pour d�clarer son fichier de correspondance pour la r��criture. Bien que vous ne puissiez pas d�clarer une table de correspondance dans un contexte de r�pertoire, vous pouvez bien entendu utiliser cette table dans un contexte de r�pertoire.

RewriteOptions Directive

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 du r�pertoire parent sont h�rit�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.

AllowAnyURI

A partir de la version 2.2.23 de httpd, lorsqu'une directive RewriteRule est utilis�e dans un contexte de serveur virtuel ou de serveur principal, mod_rewrite ne la traitera que si l'URI de la requ�te correspond � un chemin d'URL. Ceci permet d'�viter certains probl�mes de s�curit� o� certaines r�gles peuvent permettre l'expansion de mod�les inattendus (voir CVE-2011-3368 et CVE-2011-4317). Pour lever cette restriction, on peut activer l'option AllowAnyURI, et mod_rewrite va alors appliquer le jeu de r�gles � tout URI de requ�te, sans v�rifier si la cha�ne respecte la grammaire des chemins d'URL d�finie dans la sp�cification HTTP.

Avertissement en mati�re de s�curit�

L'activation de cette option expose le serveur � des probl�mes de s�curit� si les r�gles de r��criture n'ont pas �t� r�dig�es avec soin. Il est donc fortement recommand� de ne pas utiliser cette option. En particulier, prenez garde aux cha�nes d'entr�e contenant le caract�re '@' qui peut modifier l'interpr�tation de l'URI transform�, comme indiqu� dans les CVE ci-dessus.

MergeBase

Avec cette option, la valeur de RewriteBase est copi�e depuis une origine explicitement d�finie dans tout sous-r�pertoire qui ne d�finit pas sa propre RewriteBase. Par d�faut, jusqu'� la version 2.2.22, cette valeur n'�tait pas copi�e, alors qu'elle l'�tait avec la version 2.2.23 du serveur HTTP Apache. Le drapeau permettant de contr�ler explicitement ce comportement est disponible depuis la version 2.2.24.

RewriteRule Directive

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 chemin de l'URL de la requ�te (%-decoded) ; les expressions suivantes sont compar�es � la sortie de la derni�re r�gle de r��criture qui a �t� appliqu�e.

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.

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 chemin du syst�me de fichiers que si les r�gles sont d�finies dans un contexte de serveur (virtualhost), et si le premier �l�ment de ce chemin 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. L'URL 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.

En outre, vous pouvez sp�cifier des actions sp�ciales � effectuer en ajoutant des [drapeaux] comme troisi�me argument de la directive RewriteRule. Flags est une liste de valeurs d�par�es par des virgules, d�limit�e par des crochets, choisies parmi les drapeaux de la table suivante. Vous trouverez plus de d�tails et d'exemples, pour chaque drapeau, dans la documentation sur les drapeaux de r��criture.

Voici toutes les combinaisons de substitution et leurs significations :

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

R�gle                          R�sultat de la substitution
----------------------------------------------  ----------------------------------
^/chemin(.*) autre-chemin$1                      non valide, non support�

^/chemin(.*) autre-chemin$1  [R]                 non valide, non support�

^/chemin(.*) autre-chemin$1  [P]                 non valide, non support�
----------------------------------------------  ----------------------------------
^/chemin(.*) /autre-chemin$1                     /autre-chemin/infochemin

^/chemin(.*) /autre-chemin$1 [R]                 http://cet-h�te/autre-chemin/infochemin
                                                via redirection externe

^/chemin(.*) /autre-chemin$1 [P]                 n'a pas lieu d'�tre, non support�
----------------------------------------------  ----------------------------------
^/chemin(.*) http://cet-h�te/autre-chemin$1      /autre-chemin/infochemin

^/chemin(.*) http://cet-h�te/autre-chemin$1 [R]  http://cet-h�te/autre-chemin/infochemin
                                                via redirection externe

^/chemin(.*) http://cet-h�te/autre-chemin$1 [P]  n'a pas lieu d'�tre, non support�
----------------------------------------------  ----------------------------------
^/chemin(.*) http://autre h�te/autre-chemin$1     http://autre h�te/autre-chemin/infochemin
                                                via redirection externe

^/chemin(.*) http://autre h�te/autre-chemin$1 [R] http://autre h�te/autre-chemin/infochemin
                                                via redirection externe
                                                (le drapeau [R] est
						redondant)

^/chemin(.*) http://autre h�te/autre-chemin$1 [P] http://autre h�te/autre-chemin/infochemin
                                                via un mandataire interne

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