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

Module Apache mod_proxy_html

Langues Disponibles:  en  |  fr 

Description:Réécrit les liens HTML afin de s'assurer qu'ils soient bien adressables depuis les réseaux des clients dans un contexte de mandataire.
Statut:Base
Identificateur de Module:proxy_html_module
Fichier Source:mod_proxy_html.c
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures

Sommaire

Ce module fournit un filtre en sortie permettant de réécrire les liens HTML dans un contexte de mandataire, afin de s'assurer que ces liens fonctionnent pour les utilisateurs en dehors du mandataire. Il accomplit la même tâche que la directive ProxyPassReverse d'Apache accomplit pour les en-têtes HTTP, et fait partie des composants essentiels d'un mandataire inverse.

Par exemple, si une entreprise possède un serveur d'applications nommé appserver.example.com qui n'est visible que depuis son réseau interne, et un serveur web public www.example.com, il peut être souhaitable de fournir une passerelle vers le serveur d'application à l'adresse http://www.example.com/appserver/. Lorsque le serveur d'applications présente un lien vers lui-même, ce lien doit être réécrit pour fonctionner à travers la passerelle. A cet effet, mod_proxy_html permet de réécrire <a href="http://appserver.example.com/foo/bar.html">foobar</a> en <a href="http://www.example.com/appserver/foo/bar.html">foobar</a>, ce qui permet de rendre le serveur d'applications accessible depuis l'extérieur.

Sujets

Directives

Traitement des bugs

Voir aussi

top

Introduction

mod_proxy_html est apparu en tant que module tiers avec les versions 2.0.x du serveur HTTP Apache. Il a ensuite été donné à l'ASF en 2011 avec le module mod_xml2enc (voir Internationalisation), et fait maintenant partie des modules standards de HTTPD 2.4 et de ses versions de développement.

top

Interprétation HTML personnalisée

mod_proxy_html utilise en interne le module HTMLParser fourni par la bibliothèque tierce libxml2. A la différence des autres interpréteurs libxml2, HTMLParser traite les documents HTML sans imposer à ces derniers d'être bien formés du point de vue XML. En particulier, il sait gérer les tags implicites - comme le </p> fermant - et les insère dans le flux des évènements SAX utilisé par mod_proxy_html. Il possède aussi une connaissance explicite des standards HTML 4 et XHTML 1 du W3C, et peut en corriger certaines erreurs.

mod_proxy_html offre toute une panoplie d'options permettant de contrôler l'interprétation du code HTML. La correction d'erreur peut être activée (selon votre choix de standard HTML) ou désactivée via la directive ProxyHTMLDocType. Et à la demande générale, il peut être configuré pour traiter les éléments et attributs non standards en tant que liens qui devront peut-être être réécrits, et pour réécrire les liens dans les contenus embarqués non-HTML (feuilles de style et scripts). Notez que ce module ne convient pas pour traiter les feuilles de style ou scripts externes ; pour ces derniers, vous devez utiliser un autre interpréteur comme mod_substitute ou mod_sed. Les principales directives permettant de personnaliser l'interprétation du code HTML sont ProxyHTMLLinks et ProxyHTMLEvents. Par défaut, elles sont définies dans le fichier de configuration proxy-html.conf qui contient aussi des commentaires pour vous aider à personnaliser votre interpréteur si nécessaire.

Pour des raisons historiques, configurer mod_proxy_html pour réécrire les URLs dans les évènements de scripting n'entraîne pas par défaut la réécriture des URLs dans les feuilles de style. Ce comportement peut être modifié en décommentant la ligne correspondante du fichier proxy-html.conf comme indiqué dans la documentation que contient ce dernier.
top

Internationalisation

mod_proxy_html utilise en interne un interpréteur HTML intelligent fourni par la bibliothèque tierce libxml2. L'interpréteur utilise Unicode (UTF-8) en interne. Ceci complexifie la gestion des autres encodages nécessaires pour traiter de nombreux sites web dont le langage est autre que l'anglais. Si ce traitement n'est pas effectué de manière appropriée, les sites web qui utilisent des caractères non-ASCII dans un codage autre que UTF-8 (Unicode) ne s'afficheront pas correctement.

Entre sa première version en 2003 et sa donnation à Apache en 2011, le support de l'internationalisation (i18n) est parti de rien pour arriver à une structure sophistiquée capable d'appliquer des règles issues de HTTP, HTML et XML pour détecter le codage d'un document et ainsi le traiter correctement. Ce traitement était cependant commun à mod_proxy_html et à d'autres modules utilisant libxml2, et plutôt que de le maintenir au niveau de chacun de ces modules, il parut sensé de l'extraire de ces derniers pour en faire un module à part entière. Ce module est mod_xml2enc et il doit être chargé pour que l'internationalisation fonctionne.

L'interaction entre mod_proxy_html et mod_xml2enc est trop complexe pour être configurée en utilisant les règles de filtrage classiques, y compris les directives de mod_filter. Ainsi, même si mod_proxy_html peut quand-même être configuré via les directives de filtrage classiques, ce ne sera pas suffisant pour le support de l'internationalisation. A cet effet, on a introduit la nouvelle directive ProxyHTMLEnable qui permet de configurer à la fois le filtre de mod_proxy_html et mod_xml2enc. Il est d'ailleurs recommandé de toujours utiliser ProxyHTMLEnable, même si le support de l'internationalisation n'est pas nécessaire. Notez que ceci constitue un changement par rapport aux précédentes versions où mod_proxy_html était activé via les directives de filtrage.

top

Directive ProxyHTMLBufSize

Description:Définit l'incrément de la taille du tampon, ainsi que sa taille initiale, pour la mise en tampon des scripts en ligne et des feuilles de style.
Syntaxe:ProxyHTMLBufSize nb-octets
Défaut:ProxyHTMLBufSize 8192
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Pour pouvoir interpréter du contenu non HTML (feuilles de style et scripts) embarqué dans des documents HTML, mod_proxy_html doit le lire et le mémoriser en entier dans un tampon. Ce tampon devra être étendu autant que nécessaire afin de pouvoir accueillir le plus grand script ou la plus grande feuille de style de la page, selon un incrément de nb-octets que cette directive permet de définir.

La valeur par défaut est 8192 et sera suffisante pour la plupart des pages. Cependant, si vous savez que vous allez mandater des pages contenant des feuilles de style et/ou scripts plus grands que 8k (cette taille s'entend pour chaque script ou feuilles de style, non pour leur ensemble), il sera plus efficace de définir une taille de tampon initiale plus grande afin d'éviter d'avoir à le redimensionner dynamiquement au cours du traitement d'une requête.

top

Directive ProxyHTMLCharsetOut

Description:Spécifie un jeu de caractères pour la sortie de mod_proxy_html.
Syntaxe:ProxyHTMLCharsetOut jeu-de-caractères | *
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet de spécifier un jeu de caractères pour la sortie de mod_proxy_html. Elle ne devrait jamais être utilisée, car tout changement par rapport à la valeur par défaut UTF-8 (Unicode - utilisé en interne par libxml2) induit une charge supplémentaire de traitement. La définition spéciale ProxyHTMLCharsetOut * permet de générer une sortie qui utilisera le même encodage que l'entrée.

Notez que tout ceci ne fonctionne que si le module mod_xml2enc est chargé.

Cette directive ne supporte pas les entités HTML. Si un document contient des caractères qui ne peuvent pas être représentés dans le jeu de caractères cible, la directive échouera et le document sera probablement corrompu (et ceci même si ces caractères sont représentés par des entités HTML).

top

Directive ProxyHTMLDocType

Description:Définit une déclaration de type de document HTML ou XHTML.
Syntaxe:ProxyHTMLDocType HTML|XHTML [Legacy]
OR
ProxyHTMLDocType fpi [SGML|XML]
OR
ProxyHTMLDocType html5
OR
ProxyHTMLDocType auto
Défaut:ProxyHTMLDocType auto (2.5/trunk versions); no FPI (2.4.x)
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Avec la première syntaxe, les documents seront déclarés de type HTML 4.01 ou XHTML 1.0 selon l'option spécifiée. Cette option détermine aussi si la syntaxe utilisée en sortie est HTML ou XHTML. Notez que le format des documents en provenance du serveur d'arrière-plan n'est pas important, car l'interpréteur le détectera automatiquement. Si le second argument optionnel est défini à "Legacy", les documents seront déclarés de type "Transitional" ; cette option peut être nécessaire si vous mandatez du contenu datant d'avant 1998, ou si vous travaillez avec des outils de création/publication déficients.

Avec la deuxième syntaxe, cette directive vous permet d'insérer votre propre FPI (Formal Public Identifier). Le second argument optionnel détermine si la syntaxe utilisée sera SGML/HTML ou XML/XHTML.

La troisième syntaxe attribue le type HTML 5 aux documents.

La quatrième syntaxe est nouvelle dans la branche trunk de HTTPD et n'est pas encore disponible dans les versions stables ; elle utilise l'interpréteur HTML de libxml2 pour déterminer le type de document.

Avec la première syntaxe, mod_proxy_html va aussi mettre le code HTML en conformité avec le standard spécifié. Il ne pourra pas corriger toutes les erreurs, mais il va supprimer les éléments et attributs non conformes. Il peut aussi journaliser les autres erreurs si la directive LogLevel est définie à Debug.

top

Directive ProxyHTMLEnable

Description:Permet d'activer/désactiver le filtre proxy_html.
Syntaxe:ProxyHTMLEnable On|Off
Défaut:ProxyHTMLEnable Off
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive est un simple commutateur permettant d'activer/désactiver le filtre proxy_html. Si mod_xml2enc est chargé, elle va aussi activer automatiquement le support de l'internationalisation.

Notez que le filtre proxy_html s'agira que si les données sont de type HTML (Content-Type text/html ou application/xhtml+xml), et si elles passent par un mandataire. Vous pouvez passer outre ces contraintes (à vos risques et périls) en définissant la variable d'environnement PROXY_HTML_FORCE.

top

Directive ProxyHTMLEvents

Description:Spécifie les attributs à traiter comme des évènements de type scripting.
Syntaxe:ProxyHTMLEvents attribut [attribut ...]
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet de spécifier un ou plusieurs attributs à traiter comme des évènements de type scripting et de leur appliquer les règles ProxyHTMLURLMap lorsqu'elles ont été définies. Vous pouvez spécifier un nombre quelconque d'attributs dans une ou plusieurs directives ProxyHTMLEvents.

Normalement, cette directive est définie globalement. Si vous définissez ProxyHTMLEvents à plusieurs niveaux, certains niveaux l'emportant sur d'autres, vous devrez spécifier un jeu complet d'évènements pour chaque niveau.

Le fichier proxy-html.conf fournit une configuration par défaut et définit les évènements selon les standards HTML 4 et XHTML 1. Cette configuration peut être adaptée pour s'appliquer aux URLs embarquées dans les attributs des feuilles de style CSS en ajoutant l'attribut style à ProxyHTMLEvents, même s'il n'existe pas dans la configuration par défaut.

top

Directive ProxyHTMLExtended

Description:Détermine si l'on doit corriger les liens dans les scripts en ligne, les feuilles de style et les évènements de type scripting.
Syntaxe:ProxyHTMLExtended On|Off
Défaut:ProxyHTMLExtended Off
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Si cette directive est définie à Off, les liens HTML sont réécrits en fonction des directives ProxyHTMLURLMap, mais les liens qui apparaissent dans le code Javascript et les feuilles de style restent inchangés.

Si elle est définie à On, tous les évènements de type scripting (définis par la directive ProxyHTMLEvents) et les scripts inclus ou les feuilles de style sont aussi traités par les règles ProxyHTMLURLMap, en fonction des drapeaux définis pour chacune d'entre elles. Ne définissez cette directive à On qu'en cas de nécessité absolue, car la charge supplémentaire induite impacte les performances.

Vous devez aussi prêter attention aux modèles de comparaison, car l'interpréteur n'a aucune notion de la forme que pourrait prendre une URL dans un script embarqué ou une feuille de style. En particulier, la comparaison étendus du caractère / a de fortes chances d'induire des correspondances erronées.

top

Directive ProxyHTMLFixups

Description:Corrige les erreurs HTML simples.
Syntaxe:ProxyHTMLFixups [lowercase] [dospath] [reset]
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive accepte un à trois arguments parmi les suivants :

Cette directive doit être utilisée avec prudence. Elle peut corriger certaines erreurs de création, mais risque aussi de modifier par erreur des liens corrects. Ne l'utilisez que si vous êtes sûr que le serveur d'arrière-plan est déficient.

top

Directive ProxyHTMLInterp

Description:Active la réinterprétation des règles ProxyHTMLURLMap pour chaque requête.
Syntaxe:ProxyHTMLInterp On|Off
Défaut:ProxyHTMLInterp Off
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet d'activer le réinterprétation pour chaque requête des modèles source et cible de la directive ProxyHTMLURLMap.

Si la réinterprétation n'est pas activée, toutes les règles sont précompilées au démarrage du serveur. Si elle est activée, les règles doivent être recompilées pour chaque requête, ce qui induit une charge de traitement supplémentaire. Elle ne doit donc être activée que si cela s'avère nécessaire.

top

Directive ProxyHTMLLinks

Description:Spécifie les éléments HTML dont les attributs d'URL doivent être réécrits.
Syntaxe:ProxyHTMLLinks élément attribut [attribut2 ...]
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Cette directive permet de spécifier les éléments dont les attributs d'URL doivent être réécrits en utilisant les règles standards ProxyHTMLURLMap. Vous devez définir une directive ProxyHTMLLinks pour chaque élément, mais chacune d'entre elles peut spécifier un nombre quelconque d'attributs

Normalement, cette directive est définie globalement. Si vous définissez ProxyHTMLLinks à plusieurs niveaux, certains niveaux l'emportant sur d'autres, vous devrez spécifier un jeu complet de liens pour chaque niveau.

Le fichier proxy-html.conf fournit une configuration par défaut et définit les liens HTML selon les standards HTML 4 et XHTML 1.

Exemples issus de proxy-html.conf

ProxyHTMLLinks  a          href
ProxyHTMLLinks  area       href
ProxyHTMLLinks  link       href
ProxyHTMLLinks  img        src longdesc usemap
ProxyHTMLLinks  object     classid codebase data usemap
ProxyHTMLLinks  q          cite
ProxyHTMLLinks  blockquote cite
ProxyHTMLLinks  ins        cite
ProxyHTMLLinks  del        cite
ProxyHTMLLinks  form       action
ProxyHTMLLinks  input      src usemap
ProxyHTMLLinks  head       profile
ProxyHTMLLinks  base       href
ProxyHTMLLinks  script     src for
top

Directive ProxyHTMLMeta

Description:Active ou désactive une préinterprétation supplémentaire des métadonnées dans les sections HTML <head>.
Syntaxe:ProxyHTMLMeta On|Off
Défaut:ProxyHTMLMeta Off
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible à partir de la version 2.4 du serveur HTTP Apache ; proposé en tant que module tiers dans les versions 2.x précédentes.

Dans les versions précédentes de mod_proxy_html (y compris celles de HTTPD 2.0 et 2.2), ProxyHTMLMeta faisait partie du support i18n. Cette fonctionnalité est maintenant assurée par le module mod_xml2enc, et ProxyHTMLMeta n'est à l'heure actuelle plus utile dans le cadre d'un serveur opérationnel ; elle peut cependant aider les développeurs à tester/déboguer des logiciels tels que les navigateurs.

Cette directive permet d'activer ou désactiver une préinterprétation supplémentaire des métadonnées dans les sections HTML <head>.

L'activation de ProxyHTMLMeta va entraîner l'interprétation de toutes les déclarations <meta http-equiv=...> et leur conversion en en-têtes HTTP, afin de conserver le but original de cette forme de métaélément HTML.

Avertissement

Compte tenu du fait que la directive ProxyHTMLMeta promeut tous les éléments http-equiv au rang d'en-têtes HTTP, il est conseillé de ne l'activer que si vous faites autant confiance au contenu HTML qu'à votre serveur mandataire. Avec cette directive en effet, si ce contenu est géré par des gens malintentionnés, ces derniers seront en mesure d'injecter des en-têtes HTTP arbitraires et peut-être malveillants dans les réponses de votre serveur.
top

Directive ProxyHTMLStripComments

Description:Détermine si les commentaires HTML doivent être supprimés.
Syntaxe:ProxyHTMLStripComments On|Off
Défaut:ProxyHTMLStripComments Off
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Si cette directive est définie à On, mod_proxy_html supprimera les commentaires HTML. Notez que cela supprimera aussi tout script ou style inclus dans les commentaires (une monstruosité introduite en 1995/1996 avec Netscape 2 pour les navigateurs plus anciens, et encore utilisée de nos jours). Cette directive peut aussi interférer avec des processeurs basés sur les commentaires comme SSI ou ESI : assurez-vous d'exécuter ces derniers avant mod_proxy_html dans la chaîne de filtrage si vous supprimez les commentaires !

top

Directive ProxyHTMLURLMap

Description:Définit une règle de réécriture des liens HTML
Syntaxe:ProxyHTMLURLMap modèle-source modèle-cible [drapeaux] [cond]
Contexte:configuration globale, serveur virtuel, répertoire
Statut:Base
Module:mod_proxy_html
Compatibilité:Disponible depuis la version 2.4 du serveur HTTP Apache. Disponible en tant que module tiers dans les versions 2.x antérieures.

Il s'agit de la directive la plus importante pour la réécriture des liens HTML. Lors de l'interprétation d'un document, chaque fois qu'un lien correspond à modèle-source, la partie du lien concernée sera réécrite en modèle-cible, en tenant compte des modifications induites par les drapeaux éventuellement spécifiés et par la directive ProxyHTMLExtended. Ne seront considérés comme des liens HTML que les éléments spécifiés via la directive ProxyHTMLLinks.

Le troisième argument optionnel permet de définir un des drapeaux suivants (les drapeaux sont sensibles à la casse) :

h

Ignore les liens HTML (les traverse sans les modifier)

e

Ignore les évènements de scripting (les traverse sans les modifier)

c

Traverse les sections de type style ou script sans les modifier.

L

Last-match. Si cette règle s'applique, aucune autre règle ne sera prise en compte (notez qu'il s'agit du comportement automatique pour les liens HTML).

l

L'opposé de L. Passe outre le comportement par défaut du changement unique pour les liens HTML.

R

Utilise des expressions rationnelles pour les modèles. modèle-source est une expression rationnelle, et modèle-cible une chaîne de remplacement qui peut être basée elle aussi sur une expression rationnelle. La mémorisation dans les expressions rationnelles est supportée : vous pouvez utiliser des parenthèses () dans le modèle-source, et récupérer la correspondance de leur contenu via les variables $1 à $9 dans le modèle-cible.

Si le drapeau R n'est pas fourni, la directive utilisera des chaînes littérales pour les différents modèles de recherche/remplacement. La logique de recherche est "commence par" dans les liens HTML, et "contient" dans les évènements de scripting et les sections de type style ou script.

x

Utilise les expressions rationnelles étendues POSIX. Ne s'applique qu'avec R.

i

Recherche de correspondance sensible à la casse. Ne s'applique qu'avec R.

n

Désactive la mémorisation dans les expressions rationnelles (pour améliorer les performances). Ne s'applique qu'avec R.

s

Recherche de correspondance dans les expressions rationnelles basée sur la ligne. Ne s'applique qu'avec R.

^

Recherche de correspondance au début seulement. Ne concerne que les recherches de correspondance par rapport à des chaînes, et ne s'applique pas aux liens HTML.

$

Recherche de correspondance à la fin seulement. Ne concerne que les recherches de correspondance par rapport à des chaînes, et ne s'applique pas aux liens HTML.

V

Insère des variables d'environnement dans le modèle-cible. Un modèle-cible de la forme ${varname|default} sera remplacé par la valeur de la variable d'environnement varname. Si cette dernière n'est pas définie, modèle-cible sera remplacé par default. La spécification de |default est facultative.

NOTE: l'insertion de variables d'environnement n'est possible que si la directive ProxyHTMLInterp a été définie à On.

v

Insère des variables d'environnement dans le modèle-source. La syntaxe du modèle est identique à la syntaxe précédente.

NOTE: l'insertion de variables d'environnement n'est possible que si la directive ProxyHTMLInterp a été définie à On.

Le quatrième argument optionnel cond définit une condition qui sera évaluée pour chaque requête, sous réserve que la directive ProxyHTMLInterp ait été définie à On. Si la condition est évaluée à FALSE, la règle ne sera pas appliquée à la requête. Si elle est évaluée à TRUE, ou si aucune condition n'est définie, la règle s'applique.

La condition est évaluée par l'interpréteur d'expression. La syntaxe simple des conditions dans mod_proxy_html 3.x pour HTTPD 2.0 et 2.2 est aussi supportée.

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 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 Libera.chat, or sent to our mailing lists.