Serveur HTTP Apache Version 2.4
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 |
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.
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
.
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 !
LogLevel alert rewrite:trace3
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:'
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 :
DocumentRoot
(c'est à
dire que pour y accéder, il n'est pas nécessaire d'utiliser
une directive telle qu'Alias
).RewriteRule
, suffixé par
la substitution relative est aussi valide en tant qu'URL sur
le serveur (ce qui est rare).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>
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 :
$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.%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.${nomTable:clé|défaut}
. Voir la href="#mapfunc">documentation sur RewriteMap
pour plus de détails.
%{
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
CONN_REMOTE_ADDR
mod_remoteip
).HTTPS
mod_ssl
soit chargé ou non).IS_SUBREQ
REMOTE_ADDR
mod_remoteip
).REQUEST_FILENAME
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
ServerName
.REQUEST_URI
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
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_rec
du 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.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
. Ces variables sont
disponibles même si l'option StdEnvVars
de la
directive SSLOptions
n'a
pas été définie.%{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.
%{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 httpd.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.
%{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 :
!
' (point d'exclamation) pour inverser le résultat
de la condition, quelle que soit l'expression de
comparaison utilisée.""
(deux guillemets),
chaîne_de_test est comparée à la
chaîne vide.RewriteCond %{HTTP_USER_AGENT} "=This Robot/1.0"
!-eq
.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é.
RewriteCond /var/www/%{REQUEST_URI} !-f RewriteRule ^(.+) /other/archive/$1 [R]
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]
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)ornext|OR
'
(ou condition suivante)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)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 plateforme mobile (notez que l'exemple est incomplet car il existe de nombreuses autres plateformes mobiles), c'est la version pour mobile de la page d'accueil qui sera renvoyée. Dans le cas contraire, ce sera la page d'accueil standard.
Par défaut, plusieurs directives RewriteCond
sont évaluées de manière séquentielle et combinées à l'aide d'un
ET logique. Si une condition n'est pas vérifiée et en
l'absence d'un opérateur logique OU
,
l'ensemble du jeu de règles est abandonné et les conditions restantes ne
sont pas évaluées.
Description: | Active ou désactive l'exécution du moteur de réécriture |
---|---|
Syntaxe: | RewriteEngine on|off |
Défaut: | RewriteEngine off |
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess |
Surcharges autorisées: | 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
.
Description: | Définit une fonction de mise en correspondance pour la recherche de mots-clés |
---|---|
Syntaxe: | RewriteMap MapName MapType:MapSource [MapTypeOptions]
|
Contexte: | configuration globale, serveur virtuel |
Statut: | Extension |
Module: | mod_rewrite |
Compatibilité: | Le troisième paramètre, MapTypeOptions, est disponible à partir de la version 2.4.29 du serveur HTTP Apache |
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.
MapName 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 :
${
MapName :
mot-clé }
${
MapName :
mot-clé |
valeur par défaut
}
Lorsqu'une telle construction est rencontrée, la table de correspondance MapName 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}"
La signification de l'argument MapTypeOptions dépend du MapType spécifié. Veuillez vous référer au document Utiliser RewriteMap pour plus de détails.
Les combinaisons suivantes pour type de correspondance et MapSource peuvent être utilisées :
httxt2dbm
(Détails ...).RewriteMap
: toupper, tolower, escape ou unescape
(Détails ...).Vous trouverez plus de détails et de nombreux exemples dans le RewriteMap HowTo.
Description: | Configure certaines options spéciales pour le moteur de réécriture |
---|---|
Syntaxe: | RewriteOptions Options |
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess |
Surcharges autorisées: | FileInfo |
Statut: | Extension |
Module: | mod_rewrite |
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.
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.
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 recopiée depuis
une valeur explicitement définie dans tout sous-répertoire qui ne
définit pas sa propre directive RewriteBase
. Il s'agissait du
comportement par défaut avec les versions 2.4.0 à 2.4.3, et ce
drapeau qui permet de retrouver ce comportement est disponible
depuis la version 2.4.4 du serveur HTTP Apache.
IgnoreContextInfo
Lors d'une
substitution relative dans un contexte de répertoire (htaccess),
et si la directive RewriteBase
n'a pas été définie,
ce module utilise des informations en provenance d'une extension
d'URL et du contexte du système de fichiers pour transformer la
sustitution relative en URL. Par exemple, les modules
mod_userdir
et mod_alias
utilisent ces informations de contexte étendu. Disponible à partir de la
version 2.4.16 du serveur HTTP Apache.
LegacyPrefixDocRoot
Avant la version 2.4.26, si une substitution était une URL absolue qui
correspondait au serveur virtuel courant, l'URL pouvait être tout d'abord
réduite à sa partie chemin, puis enfin en chemin local. Comme l'URL peut
être réduite en chemin local, le chemin doit être préfixé par la
valeur de la directive DocumentRoot, ce qui permet d'interdire l'accès à
un fichier tel que /tmp/myfile suite à une requête pour
http://host/file/myfile avec la RewriteRule
suivante :
RewriteRule /file/(.*) http://localhost/tmp/$1
Cette option permet de restaurer l'ancien comportement lorsqu'un chemin local obtenu à partir de la réduction d'une URL n'est pas préfixé par la valeur de la directive DocumentRoot. Disponible à partir de la version 2.4.26 du serveur HTTP Apache.
Description: | Définit les règles pour le moteur de réécriture |
---|---|
Syntaxe: | RewriteRule
Modèle Substitution [drapeaux] |
Contexte: | configuration globale, serveur virtuel, répertoire, .htaccess |
Surcharges autorisées: | 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. Ce avec quoi ce modèle est comparé dépend de l'endroit où
la directive RewriteRule
est définie.
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"). Il s'agit du URL-path décodé de sa valeur "%xx".
Dans un contexte de répertoire (sections Directory
et fichiers .htaccess), le
Modèle est comparé avec une partie de chemin ; par exemple une
requête pour "/app1/index.html" entraînera une comparaison avec
"app1/index.html" ou "index.html" selon l'endroit où la directive
RewriteRule
est définie.
Le chemin où la règle est défini est supprimé du chemin correspondant du système de fichiers avant comparaison (jusqu'au slash final compris). En conséquence de cette suppression, les règles définies dans ce contexte n'effectuent des comparaisons qu'avec la portion du chemin du système de fichiers "en dessous" de l'endroit où la règle est définie.
Le chemin correspondant actuel du système de fichiers est déterminé par
des directives telles que DocumentRoot
et
Alias
, ou même le résultat de
substitutions dans des règles RewriteRule
précédentes.
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}
.
<Directory>
est un peu plus
complexe.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é.RewriteBase
pour plus de détails à
propos de l'ajout du préfixe après les substitutions relatives.%{REQUEST_URI}
dans la directive
RewriteCond
.^/
ne correspondra jamais dans un contexte de répertoire.<Location>
et <Files>
(y compris leurs versions sous forme
d'expression rationnelle), elles n'y sont pas prises en compte, et
n'y sont à priori d'aucune utilité. Les substitutions
relatives sont une fonctionnalité qui n'est, elle non-plus pas supportée
dans ce genre de contexte.If
suivent les règles
du contexte de répertoire.RewriteOptions
pour définir par
exemple l'option Inherit.RewriteOptions
permet aussi de contrôler le comportement des sections définies au même niveau
d'imbrication dans la configuration. Dans l'exemple suivant, par défaut seule la
règle RewriteRules définie dans le second bloc If
est prise en compte car celle définie dans le
premier bloc est écrasée. Définir RewriteOptions
Inherit force mod_rewrite à
combiner les deux sections en prenant en compte les deux règles et pas seulement
la dernière.<If "true"> # Sans RewriteOptions Inherit, cette règle est écrasée par celle de la section # suivante et aucune redirection ne sera effectuée pour les URIs contenant # 'foo' RewriteRule foo http://example.com/foo [R] </If> <If "true"> RewriteRule bar http://example.com/bar [R] </If>
Pour quelques conseils à propos des expressions rationnelles, voir le document Introduction à mod_rewrite.
Dans mod_rewrite
, on peut aussi utiliser le caractère
NOT ('!
') 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.
$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 :
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.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.
Notez qu'une redirection (implicite ou non) qui utilise une URI
absolue inclura la chaîne de paramètres de la requête ; pour éviter
ceci, voir le drapeau [QSD]
ci-dessous.
-
(tiret)En plus du texte, la chaîne Substitution peut comporter :
$N
) vers le modèle
d'une directive RewriteRule%N
) vers le dernier
modèle d'une directive RewriteCond qui correspondait%{VARNAME}
)${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
.
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 dans les références arrières avant d'appliquer la transformation. Pour un échappement similaire des variables du serveur, voir la fonction de mappage "escape".détails ... |
BCTLS | Identique à [B], mais n'échappe que les espaces et les caractères de contrôle. détails ... |
BNE | Les caractères de [B] ou [BCTLS] qui ne doivent pas être échappés. détails ... |
backrefnoplus|BNP | Avec ce drapeau, si les références arrières sont échappées, les espaces seront échappés en %20 au lieu de +. Ceci s'avère utile lorsqu'une référence arrière est utilisée dans la partie chemin, et non dans la chaîne de paramètres de la requête ; pour plus de détails, voir ici. |
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[samesite]]]]] 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 des réécritures qui aboutissent à une redirection. 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 ... |
qslast|QSL | Interprète le dernier (le plus à droite) point d'interrogation comme le délimiteur de la chaîne de paramètres de la requête, au lieu du premier (le plus à gauche) comme c'est le cas habituellement. Disponble à partir de la version 2.4.19 du serveur HTTP Apache. 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 ... |
UnsafeAllow3F | Autorise les substitutions à partir d’URL potentiellement non fiables. détails ... |
UnsafePrefixStat | Autorise les substitutions potentiellement non fiables à partir d’une variable de tête ou d’une référence arrière vers un chemin du système de fichiers. détails ... |
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
(httpd.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 |