
         		     H A - P r o x y
         		     ---------------
         		      version 1.1.28
			      willy tarreau
			       2004/06/06

================
| Introduction |
================

HA-Proxy est un relais TCP/HTTP offrant des facilits d'intgration en
environnement hautement disponible. En effet, il est capable de :
  - effectuer un aiguillage statique dfini par des cookies ;
  - effectuer une rpartition de charge avec cration de cookies pour assurer la
    persistence de session ; 
  - fournir une visibilit externe de son tat de sant ;
  - s'arrter en douceur sans perte brutale de service ;
  - modifier/ajouter/supprimer des enttes dans la requte et la rponse ;
  - interdire des requtes qui vrifient certaines conditions ;
  - utiliser des serveurs de secours lorsque les serveurs principaux sont hors
    d'usage.

Il requiert peu de ressources, et son architecture vnementielle mono-processus
lui permet facilement de grer plusieurs milliers de connexions simultanes sur
plusieurs relais sans effondrer le systme.


===========================
| Paramtres de lancement |
===========================

Les options de lancement sont peu nombreuses :

    -f <fichier de configuration>
    -n <nombre maximal total de connexions simultanes>
    -N <nombre maximal de connexions simultanes par proxy>
    -d active le mode debug
    -D passe en daemon
    -q dsactive l'affichage de messages sur la sortie standard.
    -V affiche les messages sur la sortie standard, mme si -q ou 'quiet' sont
       spcifis.
    -c vrifie le fichier de configuration puis quitte avec un code de retour 0
       si aucune erreur n'a t trouve, ou 1 si une erreur de syntaxe a t
       dtecte.
    -p <fichier> indique au processus pre qu'il doit crire les PIDs de ses
       fils dans ce fichier en mode dmon.
    -s affiche les statistiques (si option compile)
    -l ajoute des informations aux statistiques

Le nombre maximal de connexion simultanes par proxy est le paramtre par dfaut
pour les proxies pour lesquels ce paramtre n'est pas prcis dans le fichier de
configuration. Il s'agit du paramtre 'maxconn' dans les sections 'listen'.

Le nombre maximal total de connexions simultanes limite le nombre de connexions
TCP utilisables  un instant donn par le processus, tous proxies confondus. Ce
paramtre remplace le paramtre 'maxconn' de la section 'global'.

Le mode debug correspond  l'option 'debug' de la section 'global'. Dans ce
mode, toutes les connexions, dconnexions, et tous les changes d'enttes HTTP
sont affichs.

Les statistiques ne sont disponibles que si le programme a t compil avec
l'option "STATTIME". Il s'agit principalement de donnes brutes n'ayant
d'utilit que lors de benchmarks par exemple.


============================
| Fichier de configuration |
============================

Structure
=========

L'analyseur du fichier de configuration ignore des lignes vides, les espaces,
les tabulations, et tout ce qui est compris entre le symbole '#' (s'il n'est pas
prcd d'un '\'), et la fin de la ligne, ce qui constitue un commentaire.

Le fichier de configuration est dcoup en sections rpres par des mots cls
tels que :

  - 'global'
  - 'listen'
  - 'defaults'

Tous les paramtres font rfrence  la section dfinie par le dernier mot cl
reconnu.


1) Paramtres globaux
=====================

Il s'agit des paramtres agissant sur le processus, ou bien sur l'ensemble des
proxies. Ils sont tous spcifis dans la section 'global'. Les paramtres
supports sont :

  - log <adresse> <catgorie> [niveau_max]
  - maxconn <nombre>
  - uid <identifiant>
  - gid <identifiant>
  - chroot <rpertoire>
  - nbproc <nombre>
  - daemon
  - debug
  - quiet
  - pidfile <fichier>

1.1) Journalisation des vnements
----------------------------------
La plupart des vnements sont journaliss : dmarrages, arrts, disparition et
apparition de serveurs, connexions, erreurs. Tous les messages sont envoys en
syslog vers un ou deux serveurs. La syntaxe est la suivante :

    log <adresse_ip> <catgorie> [niveau_max]

Les connexions sont envoyes en niveau "info". Les dmarrages de service et de
serveurs seront envoys en "notice", les signaux d'arrts en "warning" et les
arrts dfinitifs de services et de serveurs en "alert". Ceci est valable aussi
bien pour les proxies que pour les serveurs tests par les proxies. Le paramtre
optionnel <niveau_max> dfinit le niveau maximal de traces mises parmi les 8
valeurs suivantes  :
    emerg, alert, crit, err, warning, notice, info, debug

Par compatibilit avec les versions 1.1.16 et antrieures, la valeur par dfaut
est "debug" si l'option n'est pas prcise.

Les catgories possibles sont :
    kern, user, mail, daemon, auth, syslog, lpr, news,
    uucp, cron, auth2, ftp, ntp, audit, alert, cron2,
    local0, local1, local2, local3, local4, local5, local6, local7

Conformment  la RFC3164, les messages mis sont limits  1024 caractres.

Exemple :
---------
    global
	log 192.168.2.200 local3
	log 127.0.0.1     local4 notice

1.2) limitation du nombre de connexions
---------------------------------------
Il est possible et conseill de limiter le nombre global de connexions par
processus. Les connexions sont comprises au sens 'acceptation de connexion',
donc il faut s'attendre en rgle gnral  avoir un peu plus du double de
sessions TCP que le maximum de connexions fix. C'est important pour fixer le
paramtre 'ulimit -n' avant de lancer le proxy. Pour comptabiliser le nombre
de sockets ncessaires, il faut prendre en compte ces paramtres :
  - 1 socket par connexion entrante
  - 1 socket par connexion sortante
  - 1 socket par couple adresse/port d'coute par proxy
  - 1 socket pour chaque serveur en cours de health-check
  - 1 socket pour les logs (tous serveurs confondus)

Dans le cas o chaque proxy n'coute que sur un couple adresse/port, positionner
la limite du nombre de descripteurs de fichiers (ulimit -n)  
(2 * maxconn + nbproxy + nbserveurs + 1). Dans une future version, haproxy sera
capable de positionner lui-mme cette limite.

1.3) Diminution des privilges
------------------------------
Afin de rduire les risques d'attaques dans le cas o une faille non identifie
serait exploite, il est possible de diminuer les privilges du processus, et
de l'isoler dans un rpertoire sans risque.

Dans la section 'global', le paramtre 'uid' permet de spcifier un identifiant
numrique d'utilisateur. La valeur 0, correspondant normalement au super-
utilisateur, possde ici une signification particulire car elle indique que
l'on ne souhaite pas changer cet identifiant et conserver la valeur courante.
C'est la valeur par dfaut. De la mme manire, le paramtre 'gid' correspond 
un identifiant de groupe, et utilise par dfaut la valeur 0 pour ne rien
changer. Il est particulirement dconseill d'utiliser des comptes gnriques
tels que 'nobody' car cette pratique revient  utiliser 'root' si d'autres
processus utilisent les mmes identifiants.

Le paramtre 'chroot' autorise  changer la racine du processus une fois le
programme lanc, de sorte que ni le processus, ni l'un de ses descendants ne
puissent remonter de nouveau  la racine. Ce type de cloisonnement (chroot) est
gnralement contournable sur certains OS (Linux, Solaris) pour peu que
l'attaquant possde des droits 'root' et soit en mesure d'utiliser ou de crer
un rpertoire. Aussi, il est important d'utiliser un rpertoire spcifique au
service pour cet usage, et de ne pas mutualiser un mme rpertoire pour
plusieurs services de nature diffrente. Pour rendre l'isolement plus robuste,
il est conseill d'utiliser un rpertoire vide, sans aucun droit, et de changer
l'uid du processus de sorte qu'il ne puisse rien faire dans ledit rpertoire.

Remarque: dans le cas o une telle faille serait mise en vidence, il est fort
probable que les premires tentatives de son exploitation provoquent un arrt du
programme,  cause d'un signal de type 'Segmentation Fault', 'Bus Error' ou
encore 'Illegal Instruction'. Mme s'il est vrai que faire tourner le serveur en
environnement limit rduit les risques d'intrusion, il est parfois bien utile
dans ces circonstances de connatre les conditions d'apparition du problme, via
l'obtention d'un fichier 'core'. La plupart des systmes, pour des raisons de
scurit, dsactivent la gnration du fichier 'core' aprs un changement
d'identifiant pour le processus. Il faudra donc soit lancer le processus 
partir d'un compte utilisateur aux droits rduits (mais ne pouvant pas effectuer
le chroot), ou bien le faire en root sans rduction des droits (uid 0). Dans ce
cas, le fichier se trouvera soit dans le rpertoire de lancement, soit dans le
rpertoire spcifi aprs l'option 'chroot'. Ne pas oublier la commande suivante
pour autoriser la gnration du fichier avant de lancer le programme :

# ulimit -c unlimited

Exemple :
---------

    global
	uid	30000
	gid	30000
	chroot  /var/chroot/haproxy

1.4) Modes de fonctionnement
----------------------------
Le service peut fonctionner dans plusieurs modes :
  - avant- / arrire-plan
  - silencieux / normal / debug

Le mode par dfaut est normal, avant-plan, c'est  dire que le programme ne rend
pas la main une fois lanc. Il ne faut surtout pas le lancer comme ceci dans un
script de dmarrage du systme, sinon le systme ne finirait pas son
initialisation. Il faut le mettre en arrire-plan, de sorte qu'il rende la main
au processus appelant. C'est ce que fait l'option 'daemon' de la section
'global', et qui est l'quivalent du paramtre '-D' de la ligne de commande.

Par ailleurs, certains messages d'alerte sont toujours envoys sur la sortie
standard, mme en mode 'daemon'. Pour ne plus les voir ailleurs que dans les
logs, il suffit de passer en mode silencieux par l'ajout de l'option 'quiet'.
Cette option n'a pas d'quivalent en ligne de commande.

Enfin, le mode 'debug' permet de diagnostiquer les origines de certains
problmes en affichant les connexions, dconnexions et changes d'en-ttes HTTP
entre les clients et les serveurs. Ce mode est incompatible avec les options
'daemon' et 'quiet' pour des raisons de bon sens.

1.5) Accroissement de la capacit de traitement
-----------------------------------------------
Sur des machines multi-processeurs, il peut sembler gch de n'utiliser qu'un
processeur pour effectuer les tches de relayage, mme si les charges
ncessaires  saturer un processeur actuel sont bien au-del des ordres de
grandeur couramment rencontrs. Cependant, pour des besoins particuliers, le
programme sait dmarrer plusieurs processus se rpartissant la charge de
travail. Ce nombre de processus est spcifi par le paramtre 'nbproc' de la
section 'global'. Sa valeur par dfaut est naturellement 1. Ceci ne fonctionne
qu'en mode 'daemon'.

Exemple :
---------

    global
	daemon
	quiet
	nbproc	2

1.6) Simplification de la gestion des processus
-----------------------------------------------
Haproxy supporte dornavant la notion de fichiers de pid (-> pidfiles). Si le
paramtre '-p' de ligne de commande, ou l'option globale 'pidfile' sont suivis
d'un nom de fichier, alors ce fichier sera supprim puis recr et contiendra
le numro de PID des processus fils,  raison d'un par ligne (valable
uniquement en mode dmon). Ce fichier n'est PAS relatif au cloisonnement chroot
afin de rester compatible avec un rpertoire protg en lecture seule. Il
appartiendra  l'utilisateur ayant lanc le processus, et disposera des droits
0644.

Exemple :
---------

    global
        daemon
        quiet
        nbproc 2
        pidfile /var/run/haproxy-private.pid

    # pour stopper seulement ces processus parmi d'autres :
    # kill $(</var/run/haproxy-private.pid)


2) Dfinition d'un service en coute
====================================

Les sections de service dbutent par le mot cl "listen" :

    listen <nom_instance> [ <adresse_IP>:<plage_ports>[,...] ]

- <nom_instance> est le nom de l'instance dcrite. Ce nom sera envoy dans les
  logs, donc il est souhaitable d'utiliser un nom relatif au service relay. Aucun
  test n'est effectu concernant l'unicit de ce nom, qui n'est pas obligatoire,
  mais fortement recommande.

- <adresse_IP> est l'adresse IP sur laquelle le relais attend ses connexions.
  L'absence d'adresse ainsi que l'adresse 0.0.0.0 signifient que les connexions
  pourront s'effectuer sur toutes les adresses de la machine.

- <plage_ports> correspond soit  un port, soit  une plage de ports sur
  lesquels le relais acceptera des connexions pour l'adresse IP spcifie.
  Cette plage peut tre :
    - soit un port numrique (ex: '80')
    - soit une plage constitue de deux valeurs spares par un tiret
      (ex: '2000-2100') reprsentant les extrmits incluses dans la
      plage.
  Il faut faire attention  l'usage des plages, car chaque combinaison
  <adresse_IP>:<port> consomme une socket, donc un descripteur de fichier.
  Le couple <adresse_IP>:<port> doit tre unique pour toutes les  instances
  d'une mme machine. L'attachement  un port infrieur  1024 ncessite un
  niveau de privilge particulier lors du lancement du programme (indpendamment
  du paramtre 'uid' de la section 'global').

- le couple <adresse_IP>:<plage_ports> peut tre rpt indfiniment pour
  demander au relais d'couter galement sur d'autres adresses et/ou d'autres
  plages de ports. Pour cela, il suffit de sparer les couples par une virgule.

Exemples :
---------
    listen http_proxy :80
    listen x11_proxy 127.0.0.1:6000-6009
    listen smtp_proxy 127.0.0.1:25,127.0.0.1:587
    listen ldap_proxy :389,:663

Si toutes les adresses ne tiennent pas sur une ligne, il est possible d'en
rajouter  l'aide du mot cl 'bind'. Dans ce cas, il n'est mme pas ncessaire
de spcifier la premire adresse sur la ligne listen, ce qui facilite parfois
l'criture de configurations :

    bind [ <adresse_IP>:<plage_ports>[,...] ]

Exemples :
----------
    listen http_proxy
        bind :80,:443
	bind 10.0.0.1:10080,10.0.0.1:10443

2.1) Inhibition d'un service
----------------------------
Un service peut tre dsactiv pour des besoins de maintenance, sans avoir 
commenter toute une partie du fichier. Il suffit de positionner le mot cl
"disabled" dans sa section :

    listen smtp_proxy 0.0.0.0:25
	disabled

Remarque: le mot cl 'enabled' permet de ractiver un service pralablement
	  dsactiv par le mot cl 'disabled', par exemple  cause d'une
	  configuration par dfaut.

2.2) Mode de fonctionnement
---------------------------
Un service peut fonctionner dans trois modes diffrents :
  - TCP
  - HTTP
  - supervision

Mode TCP
--------
Dans ce mode, le service relaye, ds leur tablissement, les connexions TCP vers
un ou plusieurs serveurs. Aucun traitement n'est effectu sur le flux. Il s'agit
simplement d'une association source<adresse:port> -> destination<adresse:port>.
Pour l'utiliser, prciser le mode TCP sous la dclaration du relais.

Exemple :
---------
    listen smtp_proxy 0.0.0.0:25
	mode tcp

Mode HTTP
---------
Dans ce mode, le service relaye les connexions TCP vers un ou plusieurs
serveurs, une fois qu'il dispose d'assez d'informations pour en prendre la
dcision. Les enttes HTTP sont analyss pour y trouver un ventuel cookie, et
certains d'entre-eux peuvent tre modifis par le biais d'expressions
rgulires. Pour activer ce mode, prciser le mode HTTP sous la dclaration du
relais.

Exemple :
---------
    listen http_proxy 0.0.0.0:80
	mode http

Mode supervision
----------------
Il s'agit d'un mode offrant  un composant externe une visibilit de l'tat de
sant du service. Il se contente de retourner "OK"  tout client se connectant
sur son port. Il peut tre utilis avec des rpartiteurs de charge volus pour
dterminer quels sont les services utilisables. Si l'option 'httpchk' est
active, alors la rponse changera en 'HTTP/1.0 200 OK' pour satisfaire les
attentes de composants sachant tester en HTTP. Pour activer ce mode, prciser
le mode HEALTH sous la dclaration du relais.

Exemple :
---------
    # rponse simple : 'OK'
    listen health_check 0.0.0.0:60000
	mode health

    # rponse HTTP : 'HTTP/1.0 200 OK'
    listen http_health_check 0.0.0.0:60001
	mode health
	option httpchk


2.3) Limitation du nombre de connexions simultanes
---------------------------------------------------
Le paramtre "maxconn" permet de fixer la limite acceptable en nombre de
connexions simultanes par proxy. Chaque proxy qui atteint cette valeur cesse
d'couter jusqu' libration d'une connexion. Voir plus loin concernant les
limitations lies au systme.

Exemple :
---------
    listen tiny_server 0.0.0.0:80
        maxconn 10


2.4) Arrt en douceur
---------------------
Il est possible d'arrter les services en douceur en envoyant un signal SIG_USR1
au processus relais. Tous les services seront alors mis en phase d'arrt, mais
pourront continuer d'accepter des connexions pendant un temps dfini par le
paramtre 'grace' (en millisecondes). Cela permet par exemple, de faire savoir
rapidement  un rpartiteur de charge qu'il ne doit plus utiliser un relais,
tout en continuant d'assurer le service le temps qu'il s'en rende compte.
Remarque : les connexions actives ne sont jamais casses. Dans le pire des cas,
il faudra attendre en plus leur expiration avant l'arrt total du processus. La
valeur par dfaut est 0 (pas de grce, arrt immdiat de l'coute).

Exemple :
---------
    # arrter en douceur par 'killall -USR1 haproxy'
    # le service tournera encore 10 secondes aprs la demande d'arrt
    listen http_proxy 0.0.0.0:80
	mode http
	grace 10000

    # ce port n'est test que par un rpartiteur de charge.
    listen health_check 0.0.0.0:60000
	mode health
	grace 0


2.5) Temps d'expiration des connexions
--------------------------------------
Il est possible de paramtrer certaines dures d'expiration au niveau des
connexions TCP. Trois temps indpendants sont configurables et acceptent des
valeurs en millisecondes. Si l'une de ces trois temporisations est dpasse, la
session est termine  chaque extrmit.

  - temps d'attente d'une donne de la part du client, ou de la
    possibilit de lui envoyer des donnes : "clitimeout" :

	# time-out client  2mn30.
	clitimeout	150000

  - temps d'attente d'une donne de la part du serveur, ou de la
    possibilit de lui envoyer des donnes : "srvtimeout" :

	# time-out serveur  30s.
	srvtimeout	30000

  - temps d'attente de l'tablissement d'une connexion vers un serveur
    "contimeout" :

        # on abandonne si la connexion n'est pas tablie aprs 4 secondes
	contimeout	4000

Remarques :
-----------
  - "contimeout" et "srvtimeout" n'ont pas d'utilit dans le cas du serveur de
    type "health".
  - sous de fortes charges, ou sur un rseau satur ou dfectueux, il est
    possible de perdre des paquets. Du fait que la premire retransmission TCP
    n'ait lieu qu'au bout de 3 secoudes, fixer un timeout de connexion infrieur
     3 secondes ne permet pas de se rattraper sur la perte de paquets car la
    session aura t abandonne avant la premire retransmission. Une valeur de
    4 secondes rduira considrablement le nombre d'checs de connexion.

2.6) Tentatives de reconnexion
------------------------------
Lors d'un chec de connexion vers un serveur, il est possible de
retenter (potentiellement vers un autre serveur, en cas de rpartition
de charge). Le nombre de nouvelles tentatives infructueuses avant
abandon est fourni par le paramtre "retries".

Exemple :
---------
	# on essaie encore trois fois maxi
	retries 3


2.7) Adresse du serveur
-----------------------
Le serveur vers lequel sont rediriges les nouvelles connexions est dfini par
le paramtre "dispatch" sous la forme <adresse_ip>:<port>. Il correspond  un
serveur d'assignation de cookie dans le cas o le service consiste  assurer
uniquement une persistence HTTP, ou bien simplement au serveur destination dans
le cas de relayage TCP simple. Cet ancien mode ne permet pas de tester l'tat
du serveur distant, et il est maintenant recommand d'utiliser de prfrence
le mode 'balance'.

Exemple :
---------
   	# on envoie toutes les nouvelles connexions ici
	dispatch 192.168.1.2:80

Remarque :
----------
Ce paramtre n'a pas d'utilit pour un serveur en mode 'health', ni en mode
'balance'.


2.8) Adresse de sortie
----------------------
Il est possible de forcer l'adresse utilise pour tablir les connexions vers
les serveurs  l'aide du paramtre "source". Il est mme possible de forcer le
port, bien que cette fonctionnalit se limite  des usages trs spcifiques.
C'est particulirement utile en cas d'adressage multiple, et plus gnralement
pour permettre aux serveurs de trouver le chemin de retour dans des contextes de
routage difficiles. Si l'adresse est '0.0.0.0' ou '*' ou vide, elle sera choisie
librement par le systeme. Si le port est '0' ou vide, il sera choisi librement
par le systme. Il est  noter que depuis la version 1.1.18, les tests de bon
fonctionnement des serveurs seront aussi effectus  partir de la source
spcifie par ce paramtre.

Exemples :
----------
    listen http_proxy *:80
   	# toutes les connexions prennent l'adresse 192.168.1.200
	source 192.168.1.200:0

    listen rlogin_proxy *:513
   	# utiliser l'adresse 192.168.1.200 et le port rserv 900
	source 192.168.1.200:900


2.9) Dfinition du nom du cookie
--------------------------------
En mode HTTP, il est possible de rechercher la valeur d'un cookie pour savoir
vers quel serveur aiguiller la requte utilisateur. Le nom du cookie est donn
par le paramtre "cookie".

Exemple :
---------
    listen http_proxy :80
	mode http
	cookie SERVERID

On peut modifier l'utilisation du cookie pour la rendre plus intelligente
vis--vis des applications relayes. Il est possible, notamment de supprimer ou
rcrire un cookie retourn par un serveur accd en direct, et d'insrer un
cookie dans une rponse HTTP adresse  un serveur slectionn en rpartition
de charge, et mme de signaler aux proxies amont de ne pas cacher le cookie
insr.

Exemples :
----------

Pour ne conserver le cookie qu'en accs indirect, donc  travers le
dispatcheur, et supprimer toutes ses ventuelles occurences lors des accs
directs :

	cookie SERVERID indirect

Pour remplacer la valeur d'un cookie existant par celle attribue  un serveur,
lors d'un accs direct :

	cookie SERVERID rewrite

Pour crer un cookie comportant la valeur attribue  un serveur lors d'un accs
en rpartition de charge interne. Dans ce cas, il est souhaitable que tous les
serveurs aient un cookie renseign. Un serveur non assign d'un cookie
retournera un cookie vide (cookie de suppression) :

	cookie SERVERID insert

Pour insrer un cookie, en s'assurant qu'un cache en amont ne le stockera pas,
ajouter le mot cl 'nocache' aprs 'insert' :

	cookie SERVERID insert nocache

Pour insrer un cookie seulement suite aux requtes de type POST, ajouter le mot
cl 'postonly' aprs 'insert' :

	cookie SERVERID insert postonly


Remarques :
-----------
- Il est possible de combiner 'insert' avec 'indirect' ou 'rewrite' pour s'adapter
   des applications gnrant dj le cookie, avec un contenu invalide. Il suffit
  pour cela de les spcifier sur la mme ligne.

- dans le cas o 'insert' et 'indirect' sont spcifis, le cookie n'est jamais
  transmis au serveur vu qu'il n'en a pas connaissance et ne pourrait pas le
  comprendre.

- il est particulirement recommand d'utiliser 'nocache' en mode insertion si
  des caches peuvent se trouver entre les clients et l'instance du proxy. Dans
  le cas contraire, un cache HTTP 1.0 pourrait cacher la rponse, incluant le
  cookie de persistence insr, donc provoquer des changements de serveurs pour
  des clients partageant le mme cache.

- lorsque l'application est bien connue, et que les parties ncessitant de la
  persistence sont systmatiquement accdes par un formulaire en mode POST,
  il est plus efficace encore de combiner le mot cl "postonly" avec "insert"
  et "indirect", car la page d'accueil reste cachable, et c'est l'application
  qui gre le 'cache-control'.

2.10) Assignation d'un serveur  une valeur de cookie
----------------------------------------------------
En mode HTTP, il est possible d'associer des valeurs de cookie  des serveurs
par le paramtre 'server'. La syntaxe est :

    server <identifiant> <adresse_ip>:<port> cookie <valeur>

- <identifiant> est un nom quelconque de serveur utilis pour l'identifier dans la
  configuration et les logs.
- <adresse_ip>:<port> est le couple adresse-port sur lequel le serveur coute.
- <valeur> est la valeur  reconnatre ou positionner dans le cookie.

Exemple : le cookie SERVERID peut contenir server01 ou server02
---------
    listen http_proxy :80
	mode http
	cookie SERVERID
	dispatch 192.168.1.100:80
	server web1 192.168.1.1:80 cookie server01
	server web2 192.168.1.2:80 cookie server02

Attention : la syntaxe a chang depuis la version 1.0.
-----------

3) Rpartiteur de charge autonome
=================================

Le relais peut effectuer lui-mme la rpartition de charge entre les diffrents
serveurs dfinis pour un service donn, en mode TCP comme en mode HTTP. Pour
cela, on prcise le mot cl 'balance' dans la dfinition du service,
ventuellement suivi du nom d'un algorithme de rpartition. En version 1.1.9,
seul 'roundrobin' est gr, et c'est aussi la valeur implicite par dfaut. Il
est vident qu'en cas d'utilisation du rpartiteur interne, il ne faudra pas
spcifier d'adresse de dispatch, et qu'il faudra au moins un serveur.

Exemple : mme que prcdemment en rpartition interne
---------

    listen http_proxy :80
	mode http
	cookie SERVERID
	balance roundrobin
	server web1 192.168.1.1:80 cookie server01
	server web2 192.168.1.2:80 cookie server02

Depuis la version 1.1.22, il est possible de dterminer automatiquement le port
du serveur vers lequel sera envoye la connexion, en fonction du port d'coute
sur lequel le client s'est connect. En effet, il y a 4 possibilits pour le
champ <port> de l'adresse serveur :

  - non spcifi ou nul :
    la connexion sera envoye au serveur sur le mme port que celui sur
    lequel le relais a reu la connexion.

  - valeur numrique (seul cas support pour les versions antrieures) :
    le serveur recevra la connexion sur le port dsign.

  - valeur numrique prcde d'un signe '+' :
    la connexion sera envoye au serveur sur le mme port que celui sur
    lequel le relais a reu la connexion, auquel on ajoute la valeur dsigne.
    
  - valeur numrique prcde d'un signe '-' :
    la connexion sera envoye au serveur sur le mme port que celui sur
    lequel le relais a reu la connexion, duquel on soustrait la valeur
    dsigne.
    
Exemples :
----------

# mme que prcdemment

    listen http_proxy :80
	mode http
	cookie SERVERID
	balance roundrobin
	server web1 192.168.1.1 cookie server01
	server web2 192.168.1.2 cookie server02

# relayage simultan des ports 80 et 81 et 8080-8089

    listen http_proxy :80,:81,:8080-8089
	mode http
	cookie SERVERID
	balance roundrobin
	server web1 192.168.1.1 cookie server01
	server web2 192.168.1.2 cookie server02

# relayage TCP des ports 25, 389 et 663 vers les ports 1025, 1389 et 1663

    listen http_proxy :25,:389,:663
	mode tcp
	balance roundrobin
	server srv1 192.168.1.1:+1000
	server srv2 192.168.1.2:+1000


3.1) Surveillance des serveurs
------------------------------
Il est possible de tester l'tat des serveurs par tablissement de connexion TCP
ou par envoi d'une requte HTTP. Un serveur hors d'usage ne sera pas utilis
dans le processus de rpartition de charge interne. Pour activer la surveillance,
ajouter le mot cl 'check'  la fin de la dclaration du serveur. Il est
possible de spcifier l'intervalle (en millisecondes) sparant deux tests du
serveur par le paramtre "inter", le nombre d'checs accepts par le paramtre
"fall", et le nombre de succs avant reprise par le paramtre "rise". Les
paramtres non prciss prennent les valeurs suivantes par dfaut :
 - inter : 2000
 - rise  : 2
 - fall  : 3
 - port  : port de connexion du serveur

Le mode par dfaut consiste  tablir des connexions TCP uniquement. Dans
certains cas de pannes, des serveurs peuvent continuer  accepter les connexions
sans les traiter. Depuis la version 1.1.16, haproxy est en mesure d'envoyer des
requtes HTTP courtes et trs peu coteuses. Les versions 1.1.16 et 1.1.17
utilisent "OPTIONS / HTTP/1.0". Dans les versions 1.1.18  1.1.20, les requtes
ont t changes en "OPTIONS * HTTP/1.0" pour des raisons de contrle d'accs aux
ressources. Cependant, cette requte documente dans la RFC2068 n'est pas
comprise par tous les serveurs. Donc  partir de la version 1.1.21, la requte
par dfaut est revenue  "OPTIONS / HTTP/1.0", mais il est possible de
paramtrer la partie URI. Les requtes OPTIONS prsentent l'avantage d'tre
facilement extractibles des logs, et de ne pas induire d'accs aux fichiers ct
serveur. Seules les rponses 2xx et 3xx sont considres valides, les autres (y
compris non-rponses) aboutissent  un chec. Le temps maximal imparti pour une
rponse est gal  l'intervalle entre deux tests (paramtre "inter"). Pour
activer ce mode, spcifier l'option "httpchk", ventuellement suivie d'une
mthode et d'une URI. L'option "httpchk" accepte donc 4 formes :
  - option httpchk               -> OPTIONS / HTTP/1.0
  - option httpchk URI           -> OPTIONS <URI> HTTP/1.0
  - option httpchk METH URI      -> <METH> <URI> HTTP/1.0
  - option httpchk METH URI VER  -> <METH> <URI> <VER>
Voir les exemples ci-aprs.	

Depuis la version 1.1.17, il est possible de dfinir des serveurs de secours,
utiliss uniquement lorsqu'aucun des autres serveurs ne fonctionne. Pour cela,
ajouter le mot cl "backup" sur la ligne de dfinition du serveur. Un serveur
de secours n'est appel que lorsque tous les serveurs normaux, ainsi que tous
les serveurs de secours qui le prcdent sont hors d'usage. Il n'y a donc pas
de rpartition de charge entre des serveurs de secours. Ce type de serveurs
peut servir  retourner des pages d'indisponibilit de service. Dans ce cas,
il est prfrable de ne pas affecter de cookie, afin que les clients qui le
rencontrent n'y soient pas affects dfinitivement. Le fait de ne pas mettre
de cookie envoie un cookie vide, ce qui a pour effet de supprimer un ventuel
cookie affect prcdemment.

Depuis la version 1.1.22, il est possible d'envoyer les tests de fonctionnement
vers un port diffrent de celui de service. C'est ncessaire principalement
pour les configurations o le serveur n'a pas de port prdfini, par exemple
lorsqu'il est dduit du port d'acceptation de la connexion. Pour cela, utiliser
le paramtre 'port' suivi du numro de port devant rpondre aux requtes.

Enfin, depuis la version 1.1.17, il est possible de visualiser rapidement l'tat
courant de tous les serveurs. Pour cela, il suffit d'envoyer un signal SIGHUP au
processus proxy. L'tat de tous les serveurs de tous les proxies est envoy dans
les logs en niveau "notice", ainsi que sur la sortie d'erreurs si elle est
active. C'est une bonne raison pour avoir au moins un serveur de logs local en
niveau notice.

Depuis la version 1.1.18 (et 1.2.1), un message d'urgence est envoy dans les
logs en niveau 'emerg' si tous les serveurs d'une mme instance sont tombs,
afin de notifier l'administrateur qu'il faut prendre une action immdiate.

Exemples :
----------
# conf du paragraphe 3) avec surveillance TCP
    listen http_proxy 0.0.0.0:80
	mode http
	cookie SERVERID
	balance roundrobin
	server web1 192.168.1.1:80 cookie server01 check
	server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2

# mme que prcdemment avec surveillance HTTP par 'OPTIONS / HTTP/1.0'
    listen http_proxy 0.0.0.0:80
	mode http
	cookie SERVERID
	balance roundrobin
	option httpchk
	server web1 192.168.1.1:80 cookie server01 check
	server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2

# mme que prcdemment avec surveillance HTTP par 'OPTIONS /index.html HTTP/1.0'
    listen http_proxy 0.0.0.0:80
	mode http
	cookie SERVERID
	balance roundrobin
	option httpchk /index.html
	server web1 192.168.1.1:80 cookie server01 check
	server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2

# idem avec surveillance HTTP par 'HEAD /index.jsp? HTTP/1.1\r\nHost: www'
    listen http_proxy 0.0.0.0:80
	mode http
	cookie SERVERID
	balance roundrobin
	option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
	server web1 192.168.1.1:80 cookie server01 check
	server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2

# Insertion automatique de cookie dans la rponse du serveur, et suppression
# automatique dans la requte, tout en indiquant aux caches de ne pas garder
# ce cookie.
    listen web_appl 0.0.0.0:80
	mode http
	cookie SERVERID insert nocache indirect
	balance roundrobin
	server web1 192.168.1.1:80 cookie server01 check
	server web2 192.168.1.2:80 cookie server02 check

# idem avec serveur applicatif de secours sur autre site, et serveur de pages d'erreurs
    listen web_appl 0.0.0.0:80
	mode http
	cookie SERVERID insert nocache indirect
	balance roundrobin
	server web1 192.168.1.1:80 cookie server01 check
	server web2 192.168.1.2:80 cookie server02 check
	server web-backup 192.168.2.1:80 cookie server03 check backup
	server web-excuse 192.168.3.1:80 check backup

# relayage SMTP+TLS avec test du serveur et serveur de backup

    listen http_proxy :25,:587
	mode tcp
	balance roundrobin
	server srv1 192.168.1.1 check port 25 inter 30000 rise 1 fall 2
	server srv2 192.168.1.2 backup


3.2) Reconnexion vers un rpartiteur en cas d'chec direct
----------------------------------------------------------
En mode HTTP, si un serveur dfini par un cookie ne rpond plus, les clients
seront dfinitivement aiguills dessus  cause de leur cookie, et de ce fait,
dfinitivement privs de service. La spcification du paramtre 'redispatch'
autorise dans ce cas  renvoyer les connexions choues vers le rpartiteur
(externe ou interne) afin d'assigner un nouveau serveur  ces clients.

Exemple :
---------
    listen http_proxy 0.0.0.0:80
	mode http
	cookie SERVERID
	dispatch 192.168.1.100:80
	server web1 192.168.1.1:80 cookie server01
	server web2 192.168.1.2:80 cookie server02
	redispatch # renvoyer vers dispatch si refus de connexion.

Par dfaut (et dans les versions 1.1.16 et antrieures), le paramtre redispatch
ne s'applique qu'aux checs de connexion au serveur. Depuis la version 1.1.17,
il s'applique aussi aux connexions destines  des serveurs identifis comme
hors d'usage par la surveillance. Si l'on souhaite malgr tout qu'un client
disposant d'un cookie correspondant  un serveur dfectueux tente de s'y
connecter, il faut prciser l'option "persist" :

    listen http_proxy 0.0.0.0:80
	mode http
	option persist
	cookie SERVERID
	dispatch 192.168.1.100:80
	server web1 192.168.1.1:80 cookie server01
	server web2 192.168.1.2:80 cookie server02
	redispatch # renvoyer vers dispatch si serveur HS.


4) Fonctionnalits additionnelles
=================================

D'autres fonctionnalits d'usage moins courant sont disponibles. Il s'agit
principalement du mode transparent, de la journalisation des connexions, et de
la rcriture des enttes.

4.1) Fonctionnement en mode transparent
---------------------------------------
En mode HTTP, le mot cl 'transparent' permet d'intercepter des sessions routes
 travers la machine hbergeant le proxy. Dans ce mode, on ne prcise pas
l'adresse de rpartition 'dispatch', car celle-ci est tire de l'adresse
destination de la session dtourne. Le systme doit permettre de rediriger les
paquets vers un processus local.

Exemple :
---------
    listen http_proxy 0.0.0.0:65000
	mode http
	transparent
	cookie SERVERID
	server server01 192.168.1.1:80
	server server02 192.168.1.2:80

    # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
      --dport 80 -j REDIRECT --to-ports 65000

Remarque :
----------
Si le port n'est pas spcifi sur le serveur, c'est le port auquel s'est adress
le client qui sera utilis. Cela permet de relayer tous les ports TCP d'une mme
adresse avec une mme instance et sans utiliser directement le mode transparent.

Exemple :
---------
    listen http_proxy 0.0.0.0:65000
	mode tcp
	server server01 192.168.1.1 check port 60000
	server server02 192.168.1.2 check port 60000

    # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
      -j REDIRECT --to-ports 65000


4.2) Journalisation des connexions
----------------------------------
4.2.1) Niveaux de log
---------------------
Les connexions TCP et HTTP peuvent donner lieu  une journalisation sommaire ou
dtaille indiquant, pour chaque connexion, la date, l'heure, l'adresse IP
source, le serveur destination, la dure de la connexion, les temps de rponse,
la requte HTTP, le code de retour, la quantit de donnes transmises, et mme
dans certains cas, la valeur d'un cookie permettant de suivre les sessions.
Tous les messages sont envoys en syslog vers un ou deux serveurs. Se rfrer 
la section 1.1 pour plus d'information sur les catgories de logs.  La syntaxe
est la suivante :

    log <adresse_ip_1> <catgorie_1> [niveau_max_1]
    log <adresse_ip_2> <catgorie_2> [niveau_max_2]
ou
    log global

Remarque :
----------
La syntaxe spcifique 'log global' indique que l'on souhaite utiliser les
paramtres de journalisation dfinis dans la section 'global'.

Exemple :
---------
    listen http_proxy 0.0.0.0:80
	mode http
	log 192.168.2.200 local3
	log 192.168.2.201 local4

4.2.2) Format des logs
----------------------
Par dfaut, les connexions sont journalises au niveau TCP ds l'tablissement
de la session entre le client et le relais. En prcisant l'option 'tcplog',
la connexion ne sera journalise qu'en fin de session, ajoutant des prcisions
sur son tat lors de la dconnexion, ainsi que le temps de connexion et la
dure totale de la session.

Exemple :
---------
    listen relais-tcp 0.0.0.0:8000
	mode tcp
	option tcplog
	log 192.168.2.200 local3

>>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28] relais-tcp Srv1 0/5007 0 --

Une autre option, 'httplog', fournit plus de dtails sur le protocole HTTP,
notamment la requte et l'tat des cookies. Dans les cas o un mcanisme de
surveillance effectuant des connexions et dconnexions frquentes, polluerait
les logs, il suffit d'ajouter l'option 'dontlognull', pour ne plus obtenir une
ligne de log pour les sessions n'ayant pas donn lieu  un change de donnes
(requte ou rponse).

Exemple :
---------
    listen http_proxy 0.0.0.0:80
	mode http
	option httplog
	option dontlognull
	log 192.168.2.200 local3

>>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57] relais-http Srv1 9/7/147/723 200 243 - - ---- "HEAD / HTTP/1.0"

Le problme de loguer uniquement en fin de session, c'est qu'il est impossible
de savoir ce qui se passe durant de gros transferts ou des sessions longues.
Pour pallier  ce problme, une nouvelle option 'logasap' a t introduite dans
la version 1.1.28 (1.2.1). Lorsqu'elle est active, le proxy loguera le plus tt
possible, c'est  dire juste avant que ne dbutent les transferts de donnes.
Cela signifie, dans le cas du TCP, qu'il loguera toujours le rsultat de la
connexion vers le serveur, et dans le cas HTTP, qu'il loguera en fin de
traitement des enttes de la rponse du serveur, auquel cas le nombre d'octets
reprsentera la taille des enttes retourns au client.

Afin d'viter toute confusion avec les logs normaux, le temps total de transfert
et le nombre d'octets transfrs sont prfixs d'un signe '+' rappeleant que les
valeurs relles sont certainement plus leves.

Exemple :
---------

    listen http_proxy 0.0.0.0:80
	mode http
	option httplog
	option dontlognull
	option logasap
	log 192.168.2.200 local3

>>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/7/14/+30 200 +243 - - ---- "GET /image.iso HTTP/1.0"


4.2.3) Chronomtrage des vnements
-----------------------------------
Pour dceler des problmes rseau, les mesures du temps coul entre certains
vnements sont d'une trs grande utilit. Tous les temps sont mesurs en
millisecondes (ms). En mode HTTP, quatre points de mesure sont rapports sous
la forme Tq/Tc/Tr/Tt :

  - Tq: temps total de rception de la requte HTTP de la part du client.
    C'est le temps qui s'est coul entre le moment o le client a tabli
    sa connexion vers le relais, et le moment o ce dernier a reu le dernier
    en-tte HTTP validant la fin de la requte. Une valeur '-1' ici indique
    que la requte complte n'a jamais t reue.

  - Tc: temps d'tablissement de la connexion TCP du relais vers le serveur.
    C'est le temps coul entre le moment ou le relais a initi la demande de
    connexion vers le serveur, et le moment o ce dernier l'a acquitte, c'est
     dire le temps entre l'envoi du paquet TCP SYN la rception du SYN/ACK.
    Une valeur '-1' ici indique que la connexion n'a jamais pu tre tablie
    vers le serveur.

  - Tr: temps de rponse du serveur. C'est le temps que le serveur a mis pour
    renvoyer la totalit des enttes HTTP  partir du moment o il a acquitt
    la connexion. Ca reprsente exactement le temps de traitement de la
    transaction sans le transfert des donnes associes. Une valeur '-1'
    indique que le serveur n'a pas envoy la totalit de l'entte HTTP.

  - Tt: dure de vie totale de la session, entre le moment o la demande de
    connexion du client a t acquitte et le moment o la connexion a t
    referme aux deux extrmits (client et serveur). La signification change
    un peu si l'option 'logasap' est prsente. Dans ce cas, le temps correspond
    uniquement  (Tq + Tc + Tr), et se trouve prfix d'un signe '+'. On peut
    donc dduire Td, le temps de transfert des donnes, en excluant les autres
    temps :

        Td = Tt - (Tq + Tc + Tr)

    Les temps rapports  '-1' sont simplement  liminer de cette quation.

En mode TCP ('option tcplog'), seuls les deux indicateurs Tc et Tt sont
rapports.

Ces temps fournissent de prcieux renseignement sur des causes probables de
problmes. Du fait que le protocole TCP dfinisse des temps de retransmission
de 3 secondes, puis 6, 12, etc..., l'observation de temps proches de multiples
de 3 secondes indique pratiquement toujours des pertes de paquets lis  un
problme rseau (cble ou ngociation). De plus, si <Tt> est proche d'une
valeur de time-out dans la configuration, c'est souvent qu'une session a t
abandonne sur expiration d'un time-out.

Cas les plus frquents :

  - Si Tq est proche de 3000, un paquet a trs certainement t perdu entre
    le client et le relais.
  - Si Tc est proche de 3000, un paquet a trs certainement t perdu entre
    le relais et le serveur durant la phase de connexion. Cet indicateur
    devrait normalement toujours tre trs bas (moins de quelques dizaines).
  - Si Tr est presque toujours infrieur  3000, et que certaines valeurs
    semblent proches de la valeur moyenne majore de 3000, il y a peut-tre
    de pertes entre le relais et le serveur.
  - Si Tt est lgrement suprieur au time-out, c'est souvent parce que le
    client et le serveur utilisent du keep-alive HTTP entre eux et que la
    session est maintenue aprs la fin des changes. Voir plus loin pour
    savoir comment dsactiver le keep-alive HTTP.

Autres cas ('xx' reprsentant une valeur quelconque  ignorer) :
    -1/xx/xx/Tt : le client n'a pas envoy sa requte dans le temps imparti ou
		  a referm sa connexion sans complter la requte.
    Tq/-1/xx/Tt : la connexion n'a pas pu s'tablir vers le serveur (refus ou
                  time-out au bout de Tt-Tq ms).
    Tq/Tc/-1/Tt : le serveur a accept la connexion mais n'a pas rpondu dans
		  les temps ou bien a referm sa connexion trop tt, au bout
		  de Tt-(Tq+Tc) ms.
     
4.2.4) Conditions de dconnexion
--------------------------------
Les logs TCP et HTTP fournissent un indicateur de compltude de la session.
C'est un champ de 4 caractres (2 en TCP) prcdant la requte HTTP, indiquant :
  - sur le premier caractre, un code prcisant le premier vnement qui a caus
    la terminaison de la session :

        C : fermeture de la session TCP de la part du client
	S : fermeture de la session TCP de la part du serveur, ou refus de connexion
	P : terminaison prmature des sessions par le proxy, pour cas d'erreur
	    interne, de configuration (ex: filtre d'URL), ou parce qu'un
	    contrle de scurit a dtect une anomalie dans la rponse du
	    serveur.
	c : expiration du dlai d'attente ct client : clitimeout
	s : expiration du dlai d'attente ct serveur: srvtimeout et contimeout
	- : terminaison normale.

  - sur le second caractre, l'tat d'avancement de la session HTTP lors de la
    fermeture :

        R : terminaison en attendant la rception totale de la requte du client
	C : terminaison en attendant la connexion vers le serveur
	H : terminaison en traitant les enttes du serveur
	D : terminaison durant le transfert des donnes du serveur vers le client
	L : terminaison durant le transfert des dernires donnes du proxy vers
	    le client, alors que le serveur a dj fini.
	- : terminaison normale, aprs fin de transfert des donnes

  - le troisime caractre indique l'ventuelle identification d'un cookie de
    persistence (uniquement en mode HTTP) :

        N : aucun cookie de persistence n'a t prsent.
	I : le client a prsent un cookie ne correspondant  aucun serveur
	    connu.
	D : le client a prsent un cookie correspondant  un serveur hors
	    d'usage. Suivant l'option 'persist', il a t renvoy vers un
	    autre serveur ou a tout de mme tent de se connecter sur celui
	    correspondant au cookie.
	V : le client a prsent un cookie valide et a pu se connecter au
	    serveur correspondant.
	- : non appliquable

  - le dernier caractre indique l'ventuel traitement effectu sur un cookie de
    persistence retrourn par le serveur (uniquement en mode HTTP) :

        N : aucun cookie de persistence n'a t fourni par le serveur.
        P : un cookie de persistence a t fourni par le serveur et transmis
	    tel quel.
	I : aucun cookie n'a t fourni par le serveur, il a t insr par le
	    proxy.
	D : le cookie prsent par le serveur a t supprim par le proxy pour
	    ne pas tre retourn au client.
	R : le cookie retourn par le serveur a t modifi par le proxy.
	- : non appliquable

Le mot cl "capture" permet d'ajouter dans des logs HTTP des informations
captures dans les changes. La version 1.1.17 supporte uniquement une capture
de cookies client et serveur, ce qui permet dans bien des cas, de reconstituer
la session d'un utilisateur. La syntaxe est la suivante :

    capture cookie <prfixe_cookie> len <longueur_capture>

Le premier cookie dont le nom commencera par <prfixe_cookie> sera captur, et
transmis sous la forme "NOM=valeur", sans toutefois, excder <longueur_capture>
caractres (64 au maximum). Lorsque le nom du cookie est fixe et connu, on peut
le suffixer du signe "=" pour s'assurer qu'aucun autre cookie ne prendra sa
place dans les logs.

Exemples :
----------
    # capture du premier cookie dont le nom commence par "ASPSESSION"
    capture cookie ASPSESSION len 32

    # capture du premier cookie dont le nom est exactement "vgnvisitor"
    capture cookie vgnvisitor= len 32

Dans les logs, le champ prcdant l'indicateur de compltude contient le cookie
positionn par le serveur, prcd du cookie positionn par le client. Chacun de
ces champs est remplac par le signe "-" lorsqu'aucun cookie n'est fourni par le
client ou le serveur.

4.2.5) Exemples de logs
-----------------------
- haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57] relais-http Srv1 6559/7/147/6723 200 243 - - ---- "HEAD / HTTP/1.0"
  => requte longue (6.5s) saisie  la main avec un client telnet. Le serveur a
     rpondu en 147 ms et la session s'est termine normalement ('----')

- haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/7/14/+30 200 +243 - - ---- "GET /image.iso HTTP/1.0"
  => requte pour un long transfert. L'option 'logasap' tait spcifie donc le
     log a t gnr juste avant le transfert de donnes. Le serveur a rpondu
     en 14 ms, 243 octets d'enttes ont t transfrs au client, et le temps
     total entre l'accept() et le premier octet de donne est de 30 ms.

- haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/7/14/30 502 243 - - PH-- "GET /cgi-bin/bug.cgi? HTTP/1.0"
  => le proxy a bloqu une rponse du serveur soit  cause d'un filtre 'rspdeny'
     ou 'rspideny', soit parce qu'il a dtect un risque de fuite sensible
     d'informations risquant d'tre caches. Dans ce cas, la rponse est
     remplace par '502 bad gateway'.

- haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55] relais-http <NOSRV> -1/-1/-1/8490 -1 0 - - CR-- "" 
  => Le client n'a pas envoy sa requte et a referm la connexion lui-mme
     ('C---') au bout de 8.5s, alors que le relais attendait l'entte ('-R--').
     Aucune connexion n'a t envoye vers le serveur.

- haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06] relais-http <NOSRV> -1/-1/-1/50001 408 0 - - cR-- "" 
  => Le client n'a pas envoy sa requte et son time-out a expir ('c---') au
     bout de 50s, alors que le relais attendait l'entte ('-R--'). Aucune
     connexion n'a t envoye vers le serveur, mais le relais a tout de mme
     pu renvoyer un message 408 au client.

- haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28] relais-tcp Srv1 0/5007 0 cD 
  => log en mode 'tcplog'. Expiration du time-out ct client ('c----') au bout
     de 5s.

- haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31] relais-http Srv1 3183/-1/-1/11215 503 0 - - SC-- "HEAD / HTTP/1.0" 
  => La requte client met 3s  entrer (peut-tre un problme rseau), et la
     connexion ('SC--') vers le serveur choue au bout de 4 tentatives de 2
     secondes (retries 3 dans la conf), puis un code 503 est retourn au client.

4.3) Modification des enttes HTTP
----------------------------------
En mode HTTP uniquement, il est possible de remplacer certains en-ttes dans la
requte et/ou la rponse  partir d'expressions rgulires. Il est galement
possible de bloquer certaines requtes en fonction du contenu des en-ttes ou de
la requte. Une limitation cependant : les en-ttes fournis au milieu de
connexions persistentes (keep-alive) ne sont pas vus car ils sont considrs
comme faisant partie des changes de donnes conscutifs  la premire requte.
Les donnes ne sont pas affectes, ceci ne s'applique qu'aux en-ttes. 

La syntaxe est :
   reqadd    <string>             pour ajouter un en-tte dans la requte
   reqrep    <search> <replace>   pour modifier la requte
   reqirep   <search> <replace>   idem sans distinction majuscules/minuscules
   reqdel    <search>             pour supprimer un en-tte dans la requte
   reqidel   <search>             idem sans distinction majuscules/minuscules
   reqallow  <search>             autoriser la requte si un entte valide <search>
   reqiallow <search>             idem sans distinction majuscules/minuscules
   reqdeny   <search>             interdire la requte si un entte valide <search>
   reqideny  <search>             idem sans distinction majuscules/minuscules
   reqpass   <search>             inhibe ces actions sur les enttes validant <search>
   reqipass  <search>             idem sans distinction majuscules/minuscules

   rspadd   <string>              pour ajouter un en-tte dans la rponse
   rsprep   <search> <replace>    pour modifier la rponse
   rspirep  <search> <replace>    idem sans distinction majuscules/minuscules
   rspdel   <search>              pour supprimer un en-tte dans la rponse
   rspidel  <search>              idem sans distinction majuscules/minuscules
   rspdeny  <search>              remplace la rponse par un HTTP 502 si un
				  entte valide <search>
   rspideny <search>              idem sans distinction majuscules/minuscules


<search> est une expression rgulire compatible POSIX regexp supportant le
groupage par parenthses (sans les '\'). Les espaces et autres sparateurs
doivent tres prcds d'un '\' pour ne pas tre confondus avec la fin de la
chane. De plus, certains caractres spciaux peuvent tre prcds d'un
backslach ('\') :

  \t   pour une tabulation
  \r   pour un retour charriot
  \n   pour un saut de ligne
  \    pour diffrencier un espace d'un sparateur
  \#   pour diffrencier un dise d'un commentaire
  \\   pour utiliser un backslash dans la regex
  \\\\ pour utiliser un backslash dans le texte
  \xXX pour un caractre spcifique XX (comme en C)


<replace> contient la chane remplaant la portion vrifie par l'expression.
Elle peut inclure les caractres spciaux ci-dessus, faire rfrence  un
groupe dlimit par des parenthses dans l'expression rgulire, par sa
position numrale. Les positions vont de 1  9, et sont codes par un '\'
suivi du chiffre dsir. Il est galement possible d'insrer un caractre non
imprimable (utile pour le saut de ligne) inscrivant '\x' suivi du code
hexadcimal de ce caractre (comme en C).

<string> reprsente une chane qui sera ajoute systmatiquement aprs la
dernire ligne d'en-tte.

Remarques :
-----------
  - la premire ligne de la requte et celle de la rponse sont traites comme
    des en-ttes, ce qui permet de rcrire des URL et des codes d'erreur.
  - 'reqrep' est l'quivalent de 'cliexp' en version 1.0, et 'rsprep' celui de
    'srvexp'. Ces noms sont toujours supports mais dconseills.
  - pour des raisons de performances, le nombre total de caractres ajouts sur
    une requte ou une rponse est limit  4096 depuis la version 1.1.5 (cette
    limite tait  256 auparavant). Cette valeur est modifiable dans le code.
    Pour un usage temporaire, on peut gagner de la place en supprimant quelques
    enttes inutiles avant les ajouts.
  - une requte bloque produira une rponse "HTTP 403 forbidden" tandis qu'une
    rponse bloque produira une rponse "HTTP 502 Bad gateway".

Exemples :
----------
	###### a few examples ######

	# rewrite 'online.fr' instead of 'free.fr' for GET and POST requests
	reqrep	^(GET\ .*)(.free.fr)(.*) \1.online.fr\3
	reqrep	^(POST\ .*)(.free.fr)(.*) \1.online.fr\3

	# force proxy connections to close
	reqirep	^Proxy-Connection:.*	Proxy-Connection:\ close
	# rewrite locations
	rspirep	^(Location:\ )([^:]*://[^/]*)(.*) \1\3

	###### A full configuration being used on production ######

        # Every header should end with a colon followed by one space.
        reqideny        ^[^:\ ]*[\ ]*$

        # block Apache chunk exploit
        reqideny        ^Transfer-Encoding:[\ ]*chunked
        reqideny        ^Host:\ apache-

        # block annoying worms that fill the logs...
        reqideny        ^[^:\ ]*\ .*(\.|%2e)(\.|%2e)(%2f|%5c|/|\\\\)
        reqideny        ^[^:\ ]*\ ([^\ ]*\ [^\ ]*\ |.*%00)
        reqideny        ^[^:\ ]*\ .*<script
        reqideny        ^[^:\ ]*\ .*/(root\.exe\?|cmd\.exe\?|default\.ida\?)

        # allow other syntactically valid requests, and block any other method
        reqipass        ^(GET|POST|HEAD|OPTIONS)\ /.*\ HTTP/1\.[01]$
        reqipass        ^OPTIONS\ \\*\ HTTP/1\.[01]$
        reqideny        ^[^:\ ]*\ 

        # force connection:close, thus disabling HTTP keep-alive
	option		httpclos

	# change the server name
        rspidel         ^Server:\ 
        rspadd          Server:\ Formilux/0.1.8


De plus, l'option 'forwardfor' ajoute l'adresse IP du client dans un champ
'X-Forwarded-For' de la requte, ce qui permet  un serveur web final de
connatre l'adresse IP du client initial.

Enfin, l'option 'httpclose' apparue dans la version 1.1.28/1.2.1 supprime tout
entte de type 'Connection:' et ajoute 'Connection: close' dans les deux sens.
Ceci simplifie la dsactivation du keep-alive HTTP par rapport  l'ancienne
mthode impliquant 4 rgles.

Exemple :
---------
    listen http_proxy 0.0.0.0:80
	mode http
	log  global
	option httplog
	option dontlognull
	option forwardfor
	option httpclose

4.4) Rpartition avec persistence
---------------------------------
La combinaison de l'insertion de cookie avec la rpartition de charge interne
permet d'assurer une persistence dans les sessions HTTP d'une manire
pratiquement transparente pour les applications. Le principe est simple :
  - attribuer une valeur d'un cookie  chaque serveur
  - effectuer une rpartition interne
  - insrer un cookie dans les rponses issues d'une rpartition uniquement,
    et faire en sorte que des caches ne mmorisent pas ce cookie.
  - cacher ce cookie  l'application lors des requtes ultrieures.

Exemple :
---------
    listen application 0.0.0.0:80
	mode http
	cookie SERVERID insert nocache indirect
	balance roundrobin
	server 192.168.1.1:80 cookie server01 check
	server 192.168.1.2:80 cookie server02 check

4.5) Protection contre les fuites d'informations du serveur
-----------------------------------------------------------
Dans les versions 1.1.28 et 1.2.1, une nouvelle option 'checkcache' a t cre.
Elle sert  inspecter minutieusement les enttes 'Cache-control', 'Pragma', et
'Set-cookie' dans les rponses serveur pour dterminer s'il y a un risque de
cacher un cookie sur un proxy ct client. Quand cette option est active, les
seules rponses qui peuvent tre retournes au client sont :
  - toutes celles qui n'ont pas d'entte 'Set-cookie' ;
  - toutes celles qui ont un code de retour autre que 200, 203, 206, 300, 301, 
    410, sauf si le server a positionn un entte 'Cache-control: public' ;
  - celles qui font suite  une requte POST, sauf si le serveur a positionn
    un entte 'Cache-control: public' ;
  - celles qui ont un entte 'Pragma: no-cache' ;
  - celles qui ont un entte 'Cache-control: private' ; 
  - celles qui ont un entte 'Cache-control: no-store' ; 
  - celles qui ont un entte 'Cache-control: max-age=0' ;
  - celles qui ont un entte 'Cache-control: s-maxage=0' ;
  - celles qui ont un entte 'Cache-control: no-cache' ;
  - celles qui ont un entte 'Cache-control: no-cache="set-cookie"' ;
  - celles qui ont un entte 'Cache-control: no-cache="set-cookie,'
    (autorisant d'autres champs aprs set-cookie).

Si une rponse ne respecte pas ces pr-requis, alors elle sera bloque de la
mme manire que s'il s'agissait d'un filtre 'rspdeny', avec en retour un
message "HTTP 502 bad gateway". L'tat de session montre "PH--" ce qui veut
dire que c'est le proxy qui a bloqu la rponse durant le traitement des
enttes. De plus, un message d'alerte sera envoy dans les logs de sorte que
l'administrateur sache qu'il y a une action correctrice  entreprendre.

4.6) Personalisation des erreurs
--------------------------------
Certaines situations conduisent  retourner une erreur HTTP au client :
  - requte invalide ou trop longue => code HTTP 400
  - requte mettant trop de temps  venir => code HTTP 408
  - requte interdite (bloque par un reqideny) => code HTTP 403
  - erreur interne du proxy => code HTTP 500
  - le serveur a retourn une rponse incomplte ou invalide => code HTTP 502
  - aucun serveur disponible pour cette requte => code HTTP 503
  - le serveur n'a pas rpondu dans le temps imparti => code HTTP 504

Un message d'erreur succint tir de la RFC accompagne ces codes de retour.
Cependant, en fonction du type de clientle, on peut prfrer retourner des
pages personnalises. Ceci est possible par le biais de la commande "errorloc" :

    errorloc <code_HTTP> <location>

Au lieu de gnrer une erreur HTTP <code_HTTP> parmi les codes cits ci-dessus,
le proxy gnrera un code de redirection temporaire (HTTP 302) vers l'adresse
d'une page prcise dans <location>. Cette adresse peut tre relative au site,
ou absolue. Comme cette rponse est trate par le navigateur du client
lui-mme, il est indispensable que l'adresse fournie lui soit accessible.

Exemple :
---------
    listen application 0.0.0.0:80
        errorloc 400 /badrequest.html
        errorloc 403 /forbidden.html
        errorloc 408 /toolong.html
	errorloc 500 http://haproxy.domain.net/bugreport.html
        errorloc 502 http://192.168.114.58/error50x.html
        errorloc 503 http://192.168.114.58/error50x.html
        errorloc 504 http://192.168.114.58/error50x.html

4.7) Changement des valeurs par dfaut
--------------------------------------
Dans la version 1.1.22 est apparue la notion de valeurs par dfaut, ce qui vite
de rpter des paramtres communs  toutes les instances, tels que les timeouts,
adresses de log, modes de fonctionnement, etc.

Les valeurs par dfaut sont positionnes dans la dernire section 'defaults'
prcdent l'instance qui les utilisera. On peut donc mettre autant de sections
'defaults' que l'on veut. Il faut juste se rappeler que la prsence d'une telle
section implique une annulation de tous les paramtres par dfaut positionns
prcdemment, dans le but de les remplacer.

La section 'defaults' utilise la mme syntaxe que la section 'listen', aux
paramtres prs qui ne sont pas supports. Le mot cl 'defaults' peut accepter
un commentaire en guise paramtre.

Dans la version 1.1.28/1.2.1, seuls les paramtres suivants peuvent tre
positionns dans une section 'defaults' :
  - log (le premier et le second)
  - mode { tcp, http, health }
  - balance { roundrobin }
  - disabled (pour dsactiver toutes les instances qui suivent)
  - enabled (pour faire l'opration inverse, mais c'est le cas par dfaut)
  - contimeout, clitimeout, srvtimeout, grace, retries, maxconn
  - option { redispatch, transparent, keepalive, forwardfor, logasap, httpclose,
             checkcache, httplog, tcplog, dontlognull, persist, httpchk }
  - redispatch, redisp, transparent, source { addr:port }
  - cookie, capture
  - errorloc

Ne sont pas supports dans cette version, les adresses de dispatch et les
configurations de serveurs, ainsi que tous les filtres bass sur les
expressions rgulires :
  - dispatch, server,
  - req*, rsp*

Enfin, il n'y a pas le moyen, pour le moment, d'invalider un paramtre boolen
positionn par dfaut. Donc si une option est spcifie dans les paramtres par
dfaut, le seul moyen de la dsactiver pour une instance, c'est de changer les
paramtres par dfaut avant la dclaration de l'instance.

Exemples :
----------
    defaults applications TCP
	log global
	mode tcp
	balance roundrobin
	clitimeout 180000
	srvtimeout 180000
	contimeout 4000
	retries 3
	redispatch

    listen app_tcp1 10.0.0.1:6000-6063
	server srv1 192.168.1.1 check port 6000 inter 10000
	server srv2 192.168.1.2 backup

    listen app_tcp2 10.0.0.2:6000-6063
	server srv1 192.168.2.1 check port 6000 inter 10000
	server srv2 192.168.2.2 backup
    
    defaults applications HTTP
	log global
	mode http
	option httplog
	option forwardfor
	option dontlognull
	balance roundrobin
	clitimeout 20000
	srvtimeout 20000
	contimeout 4000
	retries 3

    listen app_http1 10.0.0.1:80-81
	cookie SERVERID postonly insert indirect
	capture cookie userid= len 10
	server srv1 192.168.1.1:+8000 cookie srv1 check port 8080 inter 1000
	server srv1 192.168.1.2:+8000 cookie srv2 check port 8080 inter 1000

    defaults
	# section vide qui annule tous les paramtes par dfaut.

=======================
| Paramtrage systme |
=======================

Sous Linux 2.4
==============

-- cut here --
#!/bin/sh
# set this to about 256/4M (16384 for 256M machine)
MAXFILES=16384
echo $MAXFILES > /proc/sys/fs/file-max
ulimit -n $MAXFILES

if [ -e /proc/sys/net/ipv4/ip_conntrack_max ]; then
	echo 65536 > /proc/sys/net/ipv4/ip_conntrack_max
fi

if [ -e /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_fin_wait ]; then
	# 30 seconds for fin, 15 for time wait
	echo 3000 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_fin_wait
	echo 1500 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_time_wait
	echo 0 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_log_invalid_scale
	echo 0 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_log_out_of_window
fi

echo 1024 60999 > /proc/sys/net/ipv4/ip_local_port_range
echo 30 > /proc/sys/net/ipv4/tcp_fin_timeout
echo 4096 > /proc/sys/net/ipv4/tcp_max_syn_backlog
echo 262144 > /proc/sys/net/ipv4/tcp_max_tw_buckets
echo 262144 > /proc/sys/net/ipv4/tcp_max_orphans
echo 300 > /proc/sys/net/ipv4/tcp_keepalive_time
echo 1 > /proc/sys/net/ipv4/tcp_tw_recycle
echo 0 > /proc/sys/net/ipv4/tcp_timestamps
echo 0 > /proc/sys/net/ipv4/tcp_ecn
echo 0 > /proc/sys/net/ipv4/tcp_sack
echo 0 > /proc/sys/net/ipv4/tcp_dsack

# auto-tuned on 2.4
#echo 262143 > /proc/sys/net/core/rmem_max
#echo 262143 > /proc/sys/net/core/rmem_default

echo 16384 65536 524288 > /proc/sys/net/ipv4/tcp_rmem
echo 16384 349520 699040 > /proc/sys/net/ipv4/tcp_wmem

-- cut here --

Sous FreeBSD
============

Un port de HA-Proxy sous FreeBSD est dsormais disponible, grce 
Clement Laforet <sheepkiller@cultdeadsheep.org>.

Pour plus d'informations :
http://www.freebsd.org/cgi/url.cgi?ports/net/haproxy/pkg-descr
http://www.freebsd.org/cgi/cvsweb.cgi/ports/net/haproxy/
http://www.freshports.org/net/haproxy


-- fin --
