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

Module Apache mod_proxy_ajp

Langues Disponibles:  en  |  fr  |  ja 

Description:Module de support AJP pour mod_proxy
Statut:Extension
Identificateur�de�Module:proxy_ajp_module
Fichier�Source:mod_proxy_ajp.c
Compatibilit�:Disponible depuis la version 2.1 d'Apache

Sommaire

Ce module n�cessite le chargement de mod_proxy. Il fournit le support du Protocole Apache JServ version 1.3 (nomm� dans la suite de ce document AJP13).

Pour �tre en mesure d'exploiter le protocole AJP13, il est donc n�cessaire de charger les modules mod_proxy et mod_proxy_ajp.

Avertissement

N'activez pas la fonctionnalit� de mandataire avant d'avoir s�curis� votre serveur. Les serveurs mandataires ouverts sont dangereux non seulement pour votre r�seau, mais aussi pour l'Internet au sens large.

Directives

Ce module ne fournit aucune directive.

Sujets

Voir aussi

top

Utilisation

Ce module permet de mandater en inverse un serveur d'application d'arri�re-plan (comme Apache Tomcat) qui utilise le protocole AJP13. Son utilisation est similaire � celle d'un mandataire inverse HTTP, mais s'appuie sur le prefixe ajp:// :

Mandataire inverse simple

ProxyPass /app ajp://backend.example.com:8009/app

On peut aussi configurer un r�partiteur de charge :

Mandataire inverse avec r�partiteur de charge

<Proxy balancer://cluster>
    BalancerMember ajp://app1.example.com:8009 loadfactor=1
    BalancerMember ajp://app2.example.com:8009 loadfactor=2
    ProxySet lbmethod=bytraffic
</Proxy>
ProxyPass /app balancer://cluster/app

Notez qu'en g�n�ral, la directive ProxyPassReverse n'est pas n�cessaire. La requ�te AJP inclut l'en-t�te host original fourni au mandataire, et le serveur d'application est sens� g�n�rer des en-t�tes auto-r�f�ren�ants relatifs � cet h�te ; aucune r��criture n'est donc n�cessaire.

La situation la plus courante dans laquelle la directive ProxyPassReverse est n�cessaire se rencontre lorsque le chemin de l'URL au niveau du mandataire est diff�rente de celle du serveur d'arri�re-plan. Dans ce cas, un en-t�te redirect peut �tre r��crit relativement � l'URL de l'h�te original (et non du serveur d'arri�re-plan ajp:// URL) ; par exemple :

R��criture d'un chemin mandat�

ProxyPass /apps/foo ajp://backend.example.com:8009/foo
ProxyPassReverse /apps/foo http://www.example.com/foo

Il est cependant pr�f�rable en g�n�ral de d�ployer l'application sur le serveur d'arri�re-plan avec le m�me chemin que sur le mandataire.

top

Variables d'environnement

Les variables d'environnement dont le nom poss�de le pr�fixe AJP_ sont transmises au serveur original en tant qu'attributs de requ�te AJP (le pr�fixe AJP_ �tant supprim� du nom de la cl�).

top

Vue d'ensemble du protocole

Le protocole AJP13 est orient� paquet. Le format binaire a �t� pr�f�r�, probablement pour des raisons de performances, au format texte pourtant plus lisible. Le serveur web communique avec le conteneur de servlets sur une connexion TCP. Pour diminuer la charge induite par le processus de cr�ation de socket, le serveur web va tenter d'utiliser des connexions TCP persistantes avec le conteneur de servlets, et de r�utiliser les connexions pendant plusieurs cycles requ�tes/r�ponse.

Lorsqu'une connexion a �t� assign�e � une requ�te particuli�re, elle ne sera utilis�e pour aucune autre jusqu'� ce que le cycle de traitement de la requ�te se soit termin�. En d'autres termes, il n'y a pas de multiplexage des requ�tes sur une connexion. Ceci se traduit par un code beaucoup plus simple � chaque extr�mit� de la connexion, un nombre plus important de connexions �tant cependant ouvertes en m�me temps.

Lorsque le serveur web a ouvert une connexion vers le conteneur de servlets, celle-ci peut se trouver dans l'un des �tats suivants :

Lorsqu'une connexion est assign�e au traitement d'une requ�te particuli�re, les informations de base de cette derni�re (comme les en-t�tes HTTP, etc...) sont envoy�es sur la connexion sous une forme tr�s condens�e (par exemple les cha�nes courantes sont cod�es sous forme d'entiers). Vous trouverez des d�tails sur ce format plus loin dans la structure des paquets de requ�te. Si la requ�te poss�de un corps (content-length > 0), il est envoy� dans un paquet s�par� imm�diatement apr�s.

A ce moment, le conteneur est probablement pr�t � traiter la requ�te. Au cours de ce traitement, il peut renvoyer les messages suivants au serveur web :

Chaque message est associ� � un paquet de donn�es format� diff�remment. Voir plus loin les structures des paquets de r�ponses pour plus de d�tails.

top

Structure de base des paquets

Ce protocole h�rite en partie de XDR, mais il diff�re sur de nombreux points (pas d'alignement sur 4 bits, par exemple).

Ordre des octets : je ne suis pas s�r du type endian des octets individuels. Je suppose qu'ils sont de type little-endian, car cela correspond � la sp�cification XDR, et je suppose aussi que la biblioth�que sys/socket fonctionne ainsi automatiquement (du point de vue du langage C). Il serait souhaitable que quelqu'un poss�dant une meilleure connaissance des appels socket puisse prendre le relai.

Le protocole comporte quatre types de donn�es : octets, bool�ens, entiers et cha�nes de caract�res.

Octet
Un seul octet.
Bool�en
Un seul octet, 1 = vrai, 0 = faux. L'utilisation d'autres valeurs non nulles (dans le style C) peut fonctionner dans certains cas, mais pas dans certains autres..
Entier
Un nombre compris entre 0 et 2^16 (32768), stock� sur 2 octets en d�butant par l'octet de poids forts.
Cha�ne
Une cha�ne de taille variable (longueur limit�e � 2^16). Elle est cod�e comme suit : les deux premiers octets repr�sentent la longueur de la cha�ne, les octets suivants constituent la cha�ne proprement dite (y compris le '\0' final). Notez que la longueur encod�e dans les deux premiers octets ne prend pas en compte le '\0' final, de la m�me mani�re que strlen. Cela peut pr�ter � confusion du point de vue de Java qui est surcharg� de d�clarations d'autoincr�mentation �tranges destin�es � traiter ces terminateurs. Je suppose que le but dans lequel cela a �t� con�u ainsi �tait de permettre au code C d'�tre plus efficace lors de la lecture de cha�nes en provenance du conteneur de servlets -- avec le caract�re \0 final, le code C peut transmettre des r�f�rences dans un seul tampon, sans avoir � effectuer de copie. En l'absence du caract�re \0 final, le code C doit effectuer une copie afin de pouvoir tenir compte de sa notion de cha�ne.

Taille du paquet

Selon la majorit� du code, la taille maximale du paquet est de 8 * 1024 bytes (8K). La taille r�elle du paquet est encod�e dans l'en-t�te.

En-t�tes de paquet

Les paquets envoy�s par le serveur vers le conteneur commencent par 0x1234. Les paquets envoy�s par le conteneur vers le serveur commencent par AB (c'est � dire le code ASCII de A suivi du code ASCII de B). Ensuite, vient un entier (cod� comme ci-dessus) repr�sentant la longueur des donn�es transmises. Bien que ceci puisse faire croire que la taille maximale des donn�es est de 2^16, le code d�finit en fait ce maximum � 8K.

Format du paquet (Serveur->Conteneur)
Octet 0 1 2 3 4...(n+3)
Contenu 0x12 0x34 Taille des donn�es (n) Data
Format du paquet (Conteneur->Serveur)
Octet 0 1 2 3 4...(n+3)
Contenu A B Taille des donn�es (n) Data

Pour la plupart des paquets, le premier octet de la charge utile encode le type de message, � l'exception des paquets contenant un corps de requ�te envoy�s du serveur vers le conteneur -- ils comportent un en-t�te standard (0x1234 suivi de la taille du paquet), mais celui-ci n'est suivi d'aucun pr�fixe.

Le serveur web peut envoyer les messages suivants au conteneur de servlets :

Code Type de paquet Signification
2 Fait suivre la requ�te D�bute le cycle de traitement de la requ�te avec les donn�es qui suivent.
7 Arr�t Le serveur web demande au conteneur de s'arr�ter.
8 Ping Le serveur web demande au conteneur de prendre le contr�le (phase de connexion s�curis�e).
10 CPing Le serveur web demande au conteneur de r�pondre rapidement avec un CPong.
none Donn�es Taille (2 octets) et les donn�es correspondantes.

� des fins de s�curit�, le conteneur n'effectuera r�ellement son Arr�t que si la demande provient de la machine par laquelle il est h�berg�.

Le premier paquet Donn�es est envoy� imm�diatement apr�s le paquet Faire suivre la requ�te par le serveur web.

Le conteneur de servlets peut envoyer les types de messages suivants au serveur web :

Code Type de paquet Signification
3 Envoi d'un tron�on de corps Envoi d'un tron�on de corps depuis le conteneur de servlets vers le serveur web (et probablement vers le navigateur).
4 Envoie les en-t�tes Envoi des en-t�tes de r�ponse depuis le conteneur de servlets vers le serveur web (et probablement vers le navigateur).
5 Fin de la r�ponse Marque la fin de la r�ponse (et par cons�quent du cycle de traitement de la requ�te).
6 R�ception du tron�on de corps suivant R�ception de la suite des donn�es de la requ�te si elles n'ont pas encore �t� enti�rement transmises.
9 R�ponse CPong La r�ponse � une requ�te CPing

Chacun des messages ci-dessus poss�de une structure interne diff�rente dont vous trouverez les d�tails ci-dessous.

top

Structure des paquets de requ�te

Pour les messages de type Faire suivre la requ�te depuis le serveur vers le conteneur :

AJP13_FORWARD_REQUEST :=
    prefix_code      (byte) 0x02 = JK_AJP13_FORWARD_REQUEST
    method           (byte)
    protocol         (string)
    req_uri          (string)
    remote_addr      (string)
    remote_host      (string)
    server_name      (string)
    server_port      (integer)
    is_ssl           (boolean)
    num_headers      (integer)
    request_headers *(req_header_name req_header_value)
    attributes      *(attribut_name attribute_value)
    request_terminator (byte) OxFF

Les request_headers poss�dent la structure suivante :

req_header_name :=
    sc_req_header_name | (string)  [voir ci-dessous pour la mani�re dont
    ceci est interpr�t�]

sc_req_header_name := 0xA0xx (integer)

req_header_value := (string)

Les attributes sont optionnels et poss�dent la structure suivante :

attribute_name := sc_a_name | (sc_a_req_attribute string)

attribute_value := (string)

Un des en-t�tes les plus importants est content-length, car il indique si le conteneur doit ou non attendre un autre paquet imm�diatement.

Description d�taill�e de la requ�te que le serveur fait suivre vers le conteneur

Pr�fixe de la requ�te

Pour toutes les requ�tes, ce pr�fixe est 2. Voir ci-dessus pour les d�tails des autres codes de pr�fixes.

M�thode

La m�thode HTTP, encod�e sous la forme d'un seul octet :

Nom commandeCode
OPTIONS1
GET2
HEAD3
POST4
PUT5
DELETE6
TRACE7
PROPFIND8
PROPPATCH9
MKCOL10
COPY11
MOVE12
LOCK13
UNLOCK14
ACL15
REPORT16
VERSION-CONTROL17
CHECKIN18
CHECKOUT19
UNCHECKOUT20
SEARCH21
MKWORKSPACE22
UPDATE23
LABEL24
MERGE25
BASELINE_CONTROL26
MKACTIVITY27

Les versions futures d'ajp13 pourront transmettre des m�thodes suppl�mentaires, m�me si elles ne font pas partie de cette liste.

protocol, req_uri, remote_addr, remote_host, server_name, server_port, is_ssl

Les significations de ces �l�ments sont triviales. Ils sont tous obligatoires et seront envoy�s avec chaque requ�te.

En-t�tes

La structure de request_headers est la suivante : tout d'abord, le nombre d'en-t�tes num_headers est encod�, suivi d'une liste de paires nom d'en-t�te req_header_name / valeur req_header_value. Les noms d'en-t�tes courants sont cod�s sous forme d'entiers afin de gagner de la place. Si le nom d'en-t�te ne fait partie de la liste des en-t�tes courants, il est encod� normalement (une cha�ne de caract�res pr�fix�e par la taille). La liste des en-t�tes courants sc_req_header_name avec leurs codes se pr�sente comme suit (il sont tous sensibles � la casse) :

NomValeur du codeNom du code
accept0xA001SC_REQ_ACCEPT
accept-charset0xA002SC_REQ_ACCEPT_CHARSET
accept-encoding0xA003SC_REQ_ACCEPT_ENCODING
accept-language0xA004SC_REQ_ACCEPT_LANGUAGE
authorization0xA005SC_REQ_AUTHORIZATION
connection0xA006SC_REQ_CONNECTION
content-type0xA007SC_REQ_CONTENT_TYPE
content-length0xA008SC_REQ_CONTENT_LENGTH
cookie0xA009SC_REQ_COOKIE
cookie20xA00ASC_REQ_COOKIE2
host0xA00BSC_REQ_HOST
pragma0xA00CSC_REQ_PRAGMA
referer0xA00DSC_REQ_REFERER
user-agent0xA00ESC_REQ_USER_AGENT

Le code Java qui lit ceci extrait l'entier repr�sent� par les deux premiers octets, et si le premier octet est '0xA0', il utilise l'entier repr�sent� par le deuxi�me octet comme index d'un tableau de noms d'en-t�tes. Si le premier octet n'est pas 0xA0, l'entier repr�sent� par les deux octets est consid�r� comme la longueur d'une cha�ne qui est alors lue.

Ceci ne peut fonctionner que si aucun nom d'en-t�te ne poss�de une taille sup�rieure � 0x9FFF (==0xA000 - 1), ce qui est vraisemblable, bien qu'un peu arbitraire.

Note:

L'en-t�te content-length est extr�mement important. S'il est pr�sent et non nul, le conteneur consid�re que la requ�te poss�de un corps (une requ�te POST, par exemple), et lit imm�diatement le paquet suivant dans le flux d'entr�e pour extraire ce corps.

Attributs

Les attributs pr�fix�s par ? (par exemple ?context) sont tous optionnels. Chacun d'eux est repr�sent� par un octet correspondant au type de l'attribut et par sa valeur (cha�ne ou entier). Ils peuvent �tre envoy�s dans un ordre quelconque (bien que le code C les envoie dans l'ordre ci-dessous). Un code de terminaison sp�cial est envoy� pour signaler la fin de la liste des attributs optionnels. La liste des codes est la suivante :

InformationValeur codeType de valeurNote
?context0x01-Non impl�ment� actuellement
?servlet_path0x02-Non impl�ment� actuellement
?remote_user0x03String
?auth_type0x04String
?query_string0x05String
?jvm_route0x06String
?ssl_cert0x07String
?ssl_cipher0x08String
?ssl_session0x09String
?req_attribute0x0AStringNom (le nom de l'attribut vient ensuite)
?ssl_key_size0x0BInteger
are_done0xFF-request_terminator

context et servlet_path ne sont pas d�finis actuellement par le code C, et la majorit� du code Java ignore compl�tement ce qui est envoy� par l'interm�diaire de ces champs (il va m�me parfois s'interrompre si une cha�ne est envoy�e apr�s un de ces codes). Je ne sais pas si c'est une bogue ou une fonctionnalit� non impl�ment�e, ou tout simplement du code obsol�te, mais en tout cas, il n'est pris en charge par aucune des deux extr�mit�s de la connexion.

remote_user et auth_type concernent probablement l'authentification au niveau HTTP, et contiennent le nom de l'utilisateur distant ainsi que le type d'authentification utilis�e pour �tablir son identit� (� savoir Basic, Digest).

query_string, ssl_cert, ssl_cipher et ssl_session contiennent les �l�ments HTTP et HTTPS correspondants.

jvm_route est utilis� dans le cadre des sessions persistantes, en associant une session utilisateur � une instance Tomcat particuli�re en pr�sence de plusieurs r�partiteurs de charge.

Au del� de cette liste de base, tout autre attribut suppl�mentaire peut �tre envoy� via le code req_attribute 0x0A. Une paire de cha�nes repr�sentant le nom et la valeur de l'attribut est envoy�e imm�diatement apr�s chaque instance de ce code. Les variables d'environnement sont transmises par cette m�thode.

Enfin, lorsque tous les attributs ont �t� transmis, le terminateur d'attributs, 0xFF, est envoy�. Ce dernier indique � la fois la fin de la liste d'attributs et la fin du paquet de la requ�te

top

Structure du paquet de la r�ponse

Pour les messages que le conteneur peut renvoyer au serveur.

AJP13_SEND_BODY_CHUNK :=
  prefix_code   3
  chunk_length  (integer)
  chunk        *(byte)
  chunk_terminator (byte) Ox00


AJP13_SEND_HEADERS :=
  prefix_code       4
  http_status_code  (integer)
  http_status_msg   (string)
  num_headers       (integer)
  response_headers *(res_header_name header_value)

res_header_name :=
    sc_res_header_name | (string)   [voir ci-dessous pour la mani�re
    dont ceci est interpr�t�]

sc_res_header_name := 0xA0 (byte)

header_value := (string)

AJP13_END_RESPONSE :=
  prefix_code       5
  reuse             (boolean)


AJP13_GET_BODY_CHUNK :=
  prefix_code       6
  requested_length  (integer)

D�tails:

Envoi d'un tron�on de corps

Le tron�on se compose essentiellement de donn�es binaires et est renvoy� directement au navigateur.

Envoi des en-t�tes

Les code et message d'�tat correspondent aux code et message HTTP habituels (par exemple 200 et OK). Les noms d'en-t�tes de r�ponses sont cod�s de la m�me fa�on que les noms d'en-t�tes de requ�tes. Voir ci-dessus le codage des en-t�tes pour plus de d�tails � propos de la mani�re dont les codes se distinguent des cha�nes.
Les codes des en-t�tes courants sont ::

NomValeur code
Content-Type0xA001
Content-Language0xA002
Content-Length0xA003
Date0xA004
Last-Modified0xA005
Location0xA006
Set-Cookie0xA007
Set-Cookie20xA008
Servlet-Engine0xA009
Status0xA00A
WWW-Authenticate0xA00B

La valeur de l'en-t�te est cod�e imm�diatement apr�s le code ou la cha�ne du nom d'en-t�te.

Fin de la r�ponse

Signale la fin de ce cycle de traitement de requ�te. Si le drapeau reuse est � true (==1), cette connexion TCP peut �tre r�utilis�e pour traiter de nouvelles requ�tes entrantes. Si reuse est � false (toute autre valeur que 1 dans le v�ritable code C), la connexion sera ferm�e.

R�ception d'un tron�on de corps

Le conteneur r�clame la suite des donn�es de la requ�te (dans le cas o� la taille du corps �tait trop importante pour pouvoir �tre contenue dans le premier paquet envoy�, o� lorsque la requ�te est fractionn�e). Le serveur va alors envoyer un paquet contenant une quantit� de donn�es correspondant au minimum de la request_length, la taille maximale de corps envoy�e (8186 (8 Koctets - 6)), et le nombre r�el d'octets restants � envoyer pour ce corps de requ�te.
S'il ne reste plus de donn�es � transmettre pour ce corps de requ�te (c'est � dire si le conteneur de servlets tente de lire au del� de la fin du corps), le serveur va renvoyer un paquet vide dont la charge utile est de longueur 0 et se pr�sentant sous la forme (0x12,0x34,0x00,0x00).

Langues Disponibles:  en  |  fr  |  ja 

top

Commentaires

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