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 httpd.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.

Sujets

Journalisation

Traitement des bugs

Voir aussi

Commentaires

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:'

Directive RewriteBase

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
Surcharges autorisées:	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 :

La requête initiale, ainsi que la substitution, se situent par raport à la valeur de la directive 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).
A partir de la version 2.4.16 du serveur HTTP Apache, cette directive peut être omise lorsque la requête est mise en correspondance avec le système de fichiers via la directive Alias ou le module mod_userdir.

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"
AliasMatch "^/myapp" "/opt/myapp-1.2.3"
<Directory "/opt/myapp-1.2.3">
 RewriteEngine On
    RewriteBase "/myapp/"
    RewriteRule "^index\.html$"  "welcome.html"
</Directory>

Directive RewriteCond

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 [drapeaux]`
Contexte:	configuration globale, serveur virtuel, répertoire, .htaccess
Surcharges autorisées:	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 :

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). $1 à $9 permettent d'accéder aux parties regroupées (entre parenthèses) du modèle, issues de la RewriteRule concernée par le jeu de conditions RewriteCond courant. $0 donne accès à l'ensemble de la chaîne correspondant au modèle.
Références arrières de condition de réécriture : ce sont des références arrières de la forme %N (0 <= N <= 9). %1 à %9 permettent d'accéder aux parties regroupées (entre parenthèses) du modèle, issues de la dernière condition RewriteCond satisfaite du jeu de conditions RewriteCond courant. %0 donne accès à l'ensemble de la chaîne correspondant au modèle.
extensions de table de réécriture : ce sont des extensions de la forme ${nomTable:clé|défaut}. Voir la href="#mapfunc">documentation sur RewriteMap pour plus de détails.

Variables du serveur : ce sont des variables de la forme %{ NAME_OF_VARIABLE }, où NOM_DE_VARIABLE peut contenir une chaîne issue de la liste suivante :

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

Ces variables correspondent toutes aux en-têtes MIME HTTP de mêmes noms, au variables C du serveur HTTP Apache, ou aux champs struct tm du système Unix. La plupart d'entre elles sont documentées ici, dans la spécification CGI ou ailleurs dans le manuel.

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 :

API_VERSION: C'est la version de l'API des modules Apache httpd (l'interface interne entre le serveur et les modules) pour la construction courante de httpd, telle qu'elle est définie dans include/ap_mmn.h. La version de l'API des modules correspond à la version du serveur Apache httpd utilisé (par exemple, pour la version 1.3.14 d'Apache httpd, il s'agit de la version 19990320:10), mais intéresse principalement les auteurs de modules.
CONN_REMOTE_ADDR: A partir de la version 2.4.8 : l'adresse IP distante de la connexion (voir le module mod_remoteip).
HTTPS: Contient le texte "on" si la connexion utilise SSL/TLS, "off" dans le cas contraire (Cette variable peut être utilisée sans problème, que mod_ssl soit chargé ou non).
IS_SUBREQ: Contient 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.
REMOTE_ADDR: L'adresse IP de l'hôte distant (se référer au module mod_remoteip).
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. En fonction de la valeur de la directive AcceptPathInfo, le serveur peut n'utiliser que certains éléments de tête du REQUEST_URI pour déterminer à quel fichier correspond la requête.
REQUEST_SCHEME: Contient le protocole de la requête (en général "http" ou "https"). La valeur peut être modifiée par la directive ServerName.
REQUEST_URI: La partie chemin de l'URI de la requête, comme "/index.html". Ceci exclut en particulier la chaîne de paramètres de la requête qui est contenue dans la variable QUERY_STRING. La valeur renvoyée pour REQUEST_URI a déjà été %-décodée ; pour la recoder, passez-la à la fonction de mappage "escape".
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.

Si la 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 ::

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.
%{ENV:variable}, où variable peut correspondre à une variable d'environnement quelconque.
%{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.
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