Module Apache mod_proxy_ajp

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

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

On peut aussi configurer un 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 :

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.

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�).

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 :

• Idle
  Aucune requ�te n'est trait�e sur cette connexion.
• Assigned
  La connexion fait l'objet d'un traitement de requ�te.

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 :

• SEND_HEADERS
  Renvoie un jeu d'en-t�tes au navigateur.
• SEND_BODY_CHUNK
  Renvoie un tron�on de corps de requ�te au navigateur.
• GET_BODY_CHUNK
  Re�oit un autre tron�on de donn�es de la requ�te si elle n'a pas encore �t� transmise int�gralement. Ce type de transmission est n�cessaire car les paquets poss�dent une taille maximale fixe, et des quantit�s quelconques de donn�es peuvent �tre contenues dans le corps de la requ�te (pour un chargement de fichier, par exemple). Notez que cela n'a rien � voir avec le transfert HTTP fractionn�.
• END_RESPONSE
  Termine le cycle du traitement de la requ�te.

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.

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.

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 :

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

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

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 :

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

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.

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 :

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

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

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