-------------------
                                 HAProxy
                           Manuel de rfrence
                           -------------------
                              version 1.3.2
                              willy tarreau
                                2006/09/03


 !!!!  NOTE: CE DOCUMENT EST PERIME  !!!!

 Veuillez utiliser le fichier "configuration.txt" situ dans le mme
 rpertoire, ou tlcharger une version  jour  l'emplacement ci-dessous :

        http://haproxy.1wt.eu/download/1.4/doc/configuration.txt


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

HAProxy 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 en-ttes 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.
  - maintenir des clients sur le bon serveur serveur d'application en fonction
    de cookies applicatifs.
  - fournir des rapports d'tat en HTML  des utilisateurs authentifis, 
    travers des URI de l'application interceptes.

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>
       = 'maxconn' dans la section 'global'
    -N <nombre maximal de connexions simultanes par instance>
       = 'maxconn' dans les sections 'listen' ou 'default'
    -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.
    -sf specifie une liste de PIDs auxquels envoyer un signal FINISH
    -st specifie une liste de PIDs auxquels envoyer un signal TERMINATE
    -s affiche les statistiques (si option compile)
    -l ajoute des informations aux statistiques
    -dk dsactive l'utilisation de kqueue()
    -ds dsactive l'utilisation de epoll() speculatif
    -de dsactive l'utilisation de epoll()
    -dp dsactive l'utilisation de poll()
    -db dsactive la mise en arrire-plan (utile pour dbugger)
    -m <megs> applique une limitation de <megs> Mo d'utilisation mmoire

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'en-ttes HTTP
sont affichs.

Pour debugger, l'option '-db' est trs pratique car elle dsactive
temporairement le mode daemon et le mode multi-processus. Le service peut alors
tre arrt par un simple appui sur Ctrl-C, sans avoir  modifier la
configuration ni  activer le mode debug complet.

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, et sont amenes  disparaitre.

Les paramtres '-st' et '-sf' sont utiliss pour la reconfiguration  chaud.
Voir la section  ce sujet.

============================
| 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>
  - user <nom d'utilisateur>
  - group <nom de groupe>
  - chroot <rpertoire>
  - nbproc <nombre>
  - daemon
  - debug
  - nokqueue
  - nosepoll
  - noepoll
  - nopoll
  - quiet
  - pidfile <fichier>
  - ulimit-n <nombre>
  - tune.maxpollevents <nombre>


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  l'aide du mot cl global 'maxconn'. 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). A partir des versions 1.1.32/1.2.6,
il est possible de spcifier cette limite dans la configuration  l'aide du
mot-cl global 'ulimit-n',  condition bien entendu que le proxy ait t
dmarr sous le compte root (ou avec des droits suffisants pour lever le
nombre de descripteurs de fichiers). Cette solution met un terme au problme
rcurrent d'incertitude de l'adquation entre les limites systmes lors de la
dernire relance du proxessus et les limites en nombre de connexions. Noter que
cette limite s'applique par processus.

Exemple :
---------
    global
        maxconn 32000
        ulimit-n 65536


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. Dans le cas o il ne serait pas possible de spcifier un identifiant
numrique pour l'uid, il est possible de spcifier un nom d'utilisateur aprs
le mot-cl 'user'. De la mme manire, il est possible de prciser un nom de
groupe aprs le mot-cl 'group'.

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

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

    # with user/group
    global
        user    haproxy
        group   public
        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.

Le paramtre de ligne de commande '-db' inhibe les options globales 'daemon'
et 'nbproc' pour faire fonctionner le processus en mode normal, avant-plan.

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'. Un usage dj rencontr pour ce paramtre fut de dpasser
la limite de nombre de descripteurs de fichiers alloue par processus sous
Solaris.

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)

    # pour recharger une configuration avec un impact minimal sur le service,
    # et sans casser les sessions existantes :
    # haproxy -f haproxy.cfg -p /var/run/haproxy-private.pid -sf $(</var/run/haproxy-private.pid)

1.7) Mcanismes de traitements des vnements
---------------------------------------------
A partir de la version 1.2.5, haproxy supporte les mcanismes poll() et
epoll(). Sur les systems o select() est limit par FD_SETSIZE (comme Solaris),
poll() peut tre une alternative intressante. Des tests de performance
montrent que les performances de poll() ne dcroissent pas aussi vite que le
nombre de sockets augmente, ce qui en fait une solution sre pour les fortes
charges. Cela dit, Soalris utilise dj poll() pour muler select(), donc tant
que le nombre de sockets ne dpasse pas FD_SETSIZE, poll() ne devrait pas
apporter de performances supplmentaires. Sur les systmes  base Linux
incluant le patch epoll() (ou tous les Linux 2.6), haproxy utilisera epoll()
qui est extrmement rapide indpendamment du nombre de sockets. Les tests sur
haproxy ont montr une performance constante de 1  40000 sessions simultanes.
La version 1.3.9 a introduit le support de kqueue() pour FreeBSD/OpenBSD, ainsi
qu'une variante appele "speculative epoll()" consistant  tenter d'effectuer
les oprations d'entres/sorties avant de chaner les vnements par les appels
systme.

Afin d'optimiser la latence, il est dsormais possible de limiter le nombre
d'vnements remonts  chaque appel. La limite par dfaut est fixe  200. Si
une latence plus petite est recherche, il peut tre justifi d'abaisser cette
limite par l'utilisation du paramtre 'tune.maxpollevents' dans la section
'global'. L'augmenter permettra d'conomiser un peu le processeur en prsence
de trs grands nombres de connexions simultanes.

Haproxy utilisera kqueue() ou speculative epoll() lorsque ce sera disponible,
puis epoll(), et se repliera sur poll(), puis en dernier lieu sur select().
Cependant, si pour une raison quelconque il s'avrait ncessaire de dsactiver
epoll() ou poll() (p.ex:  cause d'un bug ou juste pour comparer les
performances), de nouvelles options globales ont t ajoutes dans ce but :
'nosepoll', 'nokqueue', 'noepoll' et 'nopoll'.

Exemple :
---------
    global
        # utiliser seulement select()
        noepoll
        nopoll
        tune.maxpollevents 100

Remarque :
----------
Dans le but d'assurer une portabilit maximale des configurations, ces options
sont acceptes et ignores si les mcanismes poll() ou epoll() n'ont pas t
activs lors de la compilation.

Afin de simplifier la rsolution de problmes, le paramtre '-de' en ligne de
commande dsactive epoll(), le paramtre '-dp' dsactive poll(), '-dk' kqueue()
et '-ds' dsactive speculative epoll(). Ils sont respectivement quivalents 
'noepoll', 'nopoll', 'nokqueue' et 'nosepoll'.


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
  - tat de sant

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 en-ttes 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.2.1 Supervision
-----------------
Les versions 1.1.32 et 1.2.6 apportent une nouvelle solution pour valider le
bon fonctionnement du proxy sans perturber le service. Le mot-cl 'monitor-net'
a t cr dans le butd de spcifier un rseau d'quipements qui ne PEUVENT PAS
utiliser le service pour autre chose que des tests de fonctionnement. C'est
particulirement adapt aux proxies TCP, car cela empche le proxy de relayer
des tablissements de connexion mis par un outil de surveillance.

Lorsque c'est utilis sur un proxy TCP, la connexion est accepte puis referme
et rien n'est logu. C'est suffisant pour qu'un rpartiteur de charge en amont
dtecte que le service est disponible.

Lorsque c'est utilis sur un proxy HTTP, la connexion est accepte, rien n'est
logu, puis la rponse suivante est envoye et la session referme :
"HTTP/1.0 200 OK". C'est normalement suffisant pour qu'un rpartiteur de charge
HTTP en amont dtecte le service comme oprationnel, aussi bien  travers des
tests TCP que HTTP.

Les proxies utilisant le mot-cl 'monitor-net' peuvent accessoirement se passer
de l'option 'dontlognull', ce qui permettra de loguer les connexions vides
mises depuis d'autres adresses que celles du rseau de tests.

Exemple :
---------

    listen tse-proxy
       bind :3389,:1494,:5900  # TSE, ICA and VNC at once.
       mode tcp
       balance roundrobin
       server tse-farm 192.168.1.10
       monitor-net 192.168.1.252/31   # L4 load-balancers on .252 and .253


Lorsque le systme effectuant les tests est situ derrire un proxy, le mot-cl
'monitor-net' n'est pas utilisable du fait que haproxy verra toujours la mme
adresse pour le proxy. Pour pallier  cette limitation, la version 1.2.15 a
apport le mot-cl 'monitor-uri'. Il dfinit une URI qui ne sera ni retransmise
ni loge, mais pour laquelle haproxy retournera immdiatement une rponse
"HTTP/1.0 200 OK". Cela rend possibles les tests de validit d'une chane
reverse-proxy->haproxy en une requte HTTP. Cela peut tre utilis pour valider
une combinaision de stunnel+haproxy  l'aide de tests HTTPS par exemple. Bien
entendu, ce mot-cl n'est valide qu'en mode HTTP, sinon il n'y a pas de notion
d'URI. Noter que la mthode et la version HTTP sont simplement ignores.

Exemple :
---------

    listen stunnel_backend :8080
       mode http
       balance roundrobin
       server web1 192.168.1.10:80 check
       server web2 192.168.1.11:80 check
       monitor-uri /haproxy_test


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
SIGUSR1 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, ou bien tuer
manuellement le processus par l'envoi d'un signal SIGTERM. La valeur par dfaut
du paramtre 'grace' 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

A partir de la version 1.2.8, un nouveau mcanisme de reconfiguration  chaud
a t introduit. Il est dsormais possible de mettre les proxies en "pause" en
envoyant un signal SIGTTOU aux processus. Cela dsactivera les sockets d'coute
sans casser les sessions existantes. Suite  cela, l'envoi d'un signal SIGTTIN
ractivera les sockets d'coute. Ceci est trs pratique pour tenter de charger
une nouvelle configuration ou mme une nouvelle version de haproxy sans casser
les connexions existantes. Si le rechargement s'effectue correctement, il ne
reste plus qu' envoyer un signal SIGUSR1 aux anciens processus, ce qui
provoquera leur arrt immdiat ds que leurs connexions seront termines ; en
revanche, si le rechargement choue, il suffit d'envoyer un signal SIGTTIN pour
remettre les ports en coute et rtablir le service immdiatement. Veuillez
noter que le paramtre 'grace' est ignor pour le signal SIGTTOU ainsi que le
signal SIGUSR1 une fois le processus en pause. Aussi, il peut s'avrer trs
utile de sauver le fichier de pid avant de dmarrer une nouvelle instance.

Ce mcanisme est pleinement exploit  partir de la version 1.2.11 avec les
options '-st' et '-sf' (voir ci-dessous).

2.4) Reconfiguration  chaud
----------------------------
Les paramtres '-st' et '-sf' sont utiliss pour informer des processus
existants que la configuration va tre recharge. Ils recevront le signal
SIGTTOU, leur demandant de librer les ports en coute afin que le nouveau
processus puisse les prendre. Si quoi que ce soit se passe mal, le nouveau
processus leur enverra un signal SIGTTIN pour leur indiquer qu'ils peuvent
se remettre en coute et continuer leur travail. En revanche, si la
configuration se charge correctement, alors ils recevront un signal de demande
de fin de travail en douceur (-sf), ou de terminaison immdiate (-st) qui
coupera les sessions en cours. Un usage typique tel que celui-ci permet de
recharger une configuration sans interruption de service :

 # haproxy -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)


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.
  - A compter de la version 1.3.14, il est possible de spcifier les dures
    d'expiration dans des units de temps arbitraires  choisir parmi
    { us, ms, s, m, h, d }. Pour cela, la valeur entire doit tre suffixe
    de l'unit.

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

Il est  noter que la tentative de reconnexion peut amener  utiliser un autre
serveur si le premier a disparu entre deux tentatives de connexion.


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 rutiliser un cookie applicatif et lui prfixer l'identifiant du serveur,
puis le supprimer dans les requtes suivantes, utiliser l'option 'prefix'. Elle
permet d'insrer une instance de haproxy devant une application sans risquer
d'incompatibilits des  des clients qui ne supporteraient pas d'apprendre
plus d'un cookie :

       cookie JSESSIONID prefix

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.

- le mode 'prefix' ne ncessite pas d'utiliser 'indirect', 'nocache', ni
  'postonly', car tout comme le mode 'rewrite', il s'appuie sur un cookie
  prsent par l'application qui est cense savoir  quel moment il peut
  tre mis sans risque. Toutefois, comme il ncessite de rectifier le cookie
  prsent par le client dans chaque requte ultrieure, il est indispensable
  de s'assurer que le client et le serveur communiqueront sans "keep-alive
  HTTP". Dans le doute, il est recommand d'utiliser l'option "httpclose".

- 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. Jusqu' la version
1.2.11, seul 'roundrobin' tait gr, et c'est aussi la valeur implicite par
dfaut. Avec la version 1.2.12, le nouveau mot cl 'source' est apparu. La
version 1.3.10 a galement apport le mot cl 'uri'. 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

Comme indiqu prcdemment, la version 1.2.12 apporta le nouveau mot cl
'source'. Lorsque celui-ci est utilis, l'adresse IP du client est hache et
distribue de manire homogne parmi les serveurs disponibles, de sorte qu'une
mme adresse IP aille toujours sur le mme serveur tant qu'il n'y a aucun
changement dans le nombre de serveurs disponibles. Ceci peut tre utilis par
exemple pour attacher le HTTP et le HTTPS sur un mme serveur pour un mme
client. Cela peut galement tre utilis pour amliorer la persistance
lorsqu'une partie de la population des clients n'accepte pas les cookies. Dans
ce cas, seuls ces derniers seront perturbs par la perte d'un serveur.

NOTE: il est important de prendre en compte le fait que beaucoup d'internautes
      naviguent  travers des fermes de proxies qui assignent des adresses IP
      diffrentes  chaque requte. D'autres internautes utilisent des liens 
      la demande et obtiennent une adresse IP diffrente  chaque connexion. De
      ce fait, le paramtre 'source' doit tre utilis avec une extrme
      prcaution.

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

# assurer qu'une mme adresse IP ira sur le mme serveur pour tout service

    listen http_proxy
        bind :80,:443
        mode http
        balance source
        server web1 192.168.1.1
        server web2 192.168.1.2

# amliorer la persistance par l'utilisation de la source en plus du cookie :

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

De plus, tel qu'indiqu ci-dessus, la version 1.3.10 a introduit le mot cl
'uri'. Il est trs pratique dans le cas de rpartition de charge entre des
reverse-proxy-caches, parce qu'il utilisera le rsultat d'un hachage de l'URI
pour choisir un serveur, ce qui aura pour effet d'optimiser le taux de cache
du fait que la mme URI sera toujours envoye au mme cache. Ce mot-cl n'est
autoris qu'en mode HTTP.

Example :
---------

# Envoie toujours une URI donne au mme serveur

    listen http_proxy
        bind :3128
        mode http
        balance uri
        server squid1 192.168.1.1
        server squid2 192.168.1.2

La version 1.3.14 a apport une nouvelle mthode 'balance url_param'. Elle
consiste  se baser sur un paramtre pass dans l'URL pour effectuer un hachage
utilis pour dterminer le serveur  utiliser. Ceci est principalement utile
pour des applications n'ayant pas une exigence stricte de persistance, mais
pour lesquelles elle procure un gain de performance notable dans des
environnements o il n'est pas toujours possible d'utiliser des cookies. En cas
d'absence du paramtre dans l'URL, alors une rpartition de type 'round robin'
est effectue.

Example :
---------

# hache le paramtre "basket_id" dans l'URL pour dterminer le serveur

    listen http_proxy
        bind :3128
        mode http
        balance url_param basket_id
        server ebiz1 192.168.1.1
        server ebiz2 192.168.1.2


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
 - addr  : adresse de connexion du serveur (par defaut: adresse 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>

HAProxy est souvent utilis pour relayer divers protocoles reposant sur TCP,
tels que HTTPS, SMTP ou LDAP, le plus commun tant HTTPS. Un problme assez
couramment rencontr dans les data centers est le besoin de relayer du trafic
vers des serveurs lointains tout en maintenant la possibilit de basculer sur
un serveur de secours. Les tests purement TCP ne suffisent pas toujours dans
ces situations car l'on trouve souvent, dans la chane, des proxies, firewalls
ou rpartiteurs de charge qui peuvent acquitter la connexion avant qu'elle
n'atteigne le serveur. La seule solution  ce problme est d'envoyer des tests
applicatifs. Comme la demande pour les tests HTTPS est leve, ce test a t
implment en version 1.2.15 sur la base de messages SSLv3 CLIENT HELLO. Pour
l'activer, utiliser "option ssl-hello-chk". Ceci enverra des messages SSLv3
CLIENT HELLO aux serveurs, en annonant un support pour la majorit des
algorithmes de chiffrement. Si en retour, le serveur envoie ce qui ressemble 
une rponse SSLv3 SERVER HELLO ou ALERT (refus des algorithmes), alors la
rponse sera considre comme valide. Noter qu'Apache ne produit pas de log
lorsqu'il reoit des messages HELLO, ce qui en fait un type de message
parfaitement adapt  ce besoin.

La version 1.3.10 est accompagne d'un nouveau test d'tat pour le SMTP. Par
dfaut, il consiste  envoyer "HELO localhost" aux serveurs, et  attendre le
message "250" en retour. Notez qu'il peut aussi envoyer une requte plus
spcifique :

  - option smtpchk                         -> envoie "HELO localhost"
  - option smtpchk EHLO mail.mydomain.com  -> envoie ce message ESMTP

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 par dfaut. A partir
de la version 1.2.9, il est possible de les utiliser simultanment grce 
l'option 'allbackups'. 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. Il
est possible d'envoyer les tests de fonctionnement vers une adresse diffrente 
de celle de service. Cela permet d'utiliser, sur la machine faisant fonctionner
HAproxy, un dmon permettant des tests specifiques ( REGEX sur un rsultat et
basculement de plusieurs fermes en cas d'erreur sur l'une d'elles).

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.

Depuis les versions 1.1.30 et 1.2.3, plusieurs serveurs peuvent partager la
mme valeur de cookie. C'est particulirement utile en mode backup, pour
slectionner des chemins alternatifs pour un serveur donn, pour mettre en
oeuvre l'arrt en douceur d'un serveur, ou pour diriger les clients
temporairement vers une page d'erreur en attendant le redmarrage d'une
application. Le principe est que lorsqu'un serveur est dtect comme inoprant,
le proxy cherchera le prochain serveur possdant la mme valeur de cookie pour
chaque client qui le demandera. S'il ne trouve pas de serveur normal, alors il
le cherchera parmi les serveurs de backup. Consulter le guide d'architecture
pour plus d'informations.

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

# rpartition avec persistence base sur le prfixe de cookie, et arrt en
# douceur utilisant un second port (81) juste pour les health-checks.
    listen http_proxy 0.0.0.0:80
       mode http
       cookie JSESSIONID prefix
       balance roundrobin
       option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
       server web1-norm 192.168.1.1:80 cookie s1 check port 81
       server web2-norm 192.168.1.2:80 cookie s2 check port 81
       server web1-stop 192.168.1.1:80 cookie s1 check port 80 backup
       server web2-stop 192.168.1.2:80 cookie s2 check port 80 backup

# 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

# relayage HTTPS avec test du serveur et serveur de backup

    listen http_proxy :443
        mode tcp
	option ssl-hello-chk
        balance roundrobin
        server srv1 192.168.1.1 check inter 30000 rise 1 fall 2
        server srv2 192.168.1.2 backup

# Utilisation d'un groupe de serveurs pour le backup (ncessite haproxy 1.2.9)
    listen http_proxy 0.0.0.0:80
        mode http
        balance roundrobin
        option httpchk
        server inst1 192.168.1.1:80 cookie s1 check
        server inst2 192.168.1.2:80 cookie s2 check
        server inst3 192.168.1.3:80 cookie s3 check
        server back1 192.168.1.10:80 check backup
        server back2 192.168.1.11:80 check backup
        option allbackups  # all backups will be used


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.


3.3) Assignation de poids diffrents  des serveurs
---------------------------------------------------
Parfois il arrive d'ajouter de nouveaux serveurs pour accrotre la capacit
d'une ferme de serveur, mais le nouveau serveur est soit beaucoup plus petit
que les autres (dans le cas d'un ajout d'urgence de matriel de rcupration),
soit plus puissant (lors d'un investissement dans du matriel neuf). Pour cette
raison, il semble parfois judicieux de pouvoir envoyer plus de clients vers les
plus gros serveurs. Jusqu' la version 1.2.11, il tait ncessaire de rpliquer
plusieurs fois les dfinitions des serveurs pour augmenter leur poids. Depuis
la version 1.2.12, l'option 'weight' est disponible. HAProxy construit alors
une vue des serveurs disponibles la plus homogne possible en se basant sur
leur poids de sorte que la charge se distribue de la manire la plus lisse
possible. Le poids compris entre 1 et 256 doit reflter la capacit d'un
serveur par rapport aux autres. Le poids de 1 donne la frquence d'apparition
la plus faible, et 256 la frquence la plus leve. De cette manire, si un
serveur disparait, les capacits restantes sont toujours respectes.


Exemple :
---------
# distribution quitable sur 2 opteron and un ancien pentium3

    listen web_appl 0.0.0.0:80
        mode http
        cookie SERVERID insert nocache indirect
        balance roundrobin
        server pentium3-800 192.168.1.1:80 cookie server01 weight  8 check
        server opteron-2.0G 192.168.1.2:80 cookie server02 weight 20 check
        server opteron-2.4G 192.168.1.3:80 cookie server03 weight 24 check
        server web-backup1 192.168.2.1:80 cookie server04 check backup
        server web-excuse 192.168.3.1:80 check backup

Notes :
-------
  - lorsque le poids n'est pas spcifi, la valeur par dfaut est  1

  - le poids n'impacte pas les tests de fonctionnement (health checks), donc il
    est plus propre d'utiliser les poids que de rpliquer le mme serveur
    plusieurs fois.

  - les poids s'appliquent galement aux serveurs de backup si l'option
    'allbackups' est positionne.

  - le poids s'applique aussi  la rpartition selon la source
    ('balance source').

  - quels que soient les poids, le premier serveur sera toujours assign en
    premier. Cette rgle facilite les diagnostics.

  - pour les puristes, l'algorithme de calculation de la vue des serveurs donne
    une priorit aux premiers serveurs, donc la vue est la plus uniforme si les
    serveurs sont dclars dans l'ordre croissant de leurs poids.

La distribution du trafic suivra exactement le squencement suivant :

        Request|                   1 1 1 1
        number | 1 2 3 4 5 6 7 8 9 0 1 2 3
       --------+---------------------------
        p3-800 | X . . . . . . X . . . . .
        opt-20 | . X . X . X . . . X . X .
        opt-24 | . . X . X . X . X . X . X


3.4) Limitation du nombre de sessions concurrentes par serveur
--------------------------------------------------------------
Certains serveurs web multi-processus tels qu'Apache souffrent ds qu'il y a
trop de sessions concurrentes, parce qu'il est trs coteux de faire
fonctionner des centaines ou des milliers de processus sur un systme. Une
solution consiste  augmenter le nombre de serveurs et de rpartir la charge
entre eux, mais cela pose un problme lorsque le but est uniquement de rsister
 des pics de charge occasionnels.

Pour rsoudre ce problme, une nouvelle fonctionnalit a t implmente dans
HAProxy 1.2.13. Il s'agit d'une limite "maxconn" par serveur, associe  une
file d'attente par serveur et par proxy. Ceci transforme HAProxy en un tampon
entre des milliers de clients et quelques serveurs. Dans bien des cas, le fait
de diminuer la valeur maxconn amliorera notablement les performances des
serveurs et diminuera les temps de rponse simplement parce que les serveurs
seront moins congestionns.

Quand une requte cherche  joindre n'importe quel serveur, le premier serveur
non satur est utilis, en respectant l'algorithme de rpartition de charge. Si
tous les serveurs sont saturs, alors la requte sera mise dans la file
d'attente globale de l'instance. Elle sortira de cette file d'attente lorsque
toutes les requtes prcdentes auront t libres et qu'un serveur aura t
libr d'une connexion pour la traiter.

Si une requte fait rfrence  un serveur en particulier (p.ex: hachage d'IP
source, ou persistance par cookie), et que ce server est satur, alors la
requte sera mise dans la file d'attente ddie  ce serveur. Cette file
d'attente est prioritaire sur la file d'attente globale, de sorte qu'il soit
plus facile d'atteindre le site pour les utilisateurs qui s'y trouvent dj
que pour les nouveaux utilisateurs.

Pour cela, les logs ont d tre enrichis pour indiquer le nombre de sessions
par serveur, la position de la requte dans les files d'attentes, et le temps
pass en file d'attente. Ceci aide considrablement  faire de la prvision de
capacit. Voir la section 'logs' plus bas pour plus d'informations.

Exemple :
---------
    # Prendre soin du P3 qui n'a que 256 Mo de RAM.
    listen web_appl 0.0.0.0:80
        maxconn 10000
        mode http
        cookie SERVERID insert nocache indirect
        balance roundrobin
        server pentium3-800 192.168.1.1:80 cookie s1 weight  8 maxconn 100 check
        server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 maxconn 300 check
        server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 maxconn 300 check
        server web-backup1 192.168.2.1:80 cookie s4 check maxconn 200 backup
        server web-excuse 192.168.3.1:80 check backup

Cette option se montra si efficace pour rduire les temps de rponse des
serveurs que certains utilisateurs voulaient utiliser des valeurs trop basses
pour amliorer les performances de leurs serveurs. Seulement, ils n'taient
alors plus en mesure de supporter de trs fortes charges parce qu'il n'tait
plus possible de les saturer. Pour cette raison, la version 1.2.14 a apport la
limitation dynamique de connexions avec l'addition du paramtre "minconn".
Lorsque ce paramtre est associ  "maxconn", il active la limitation dynamique
base sur la charge de l'instance. Le nombre maximal de sessions concurrentes
sur un serveur devient alors proportionnel au nombre de sessions de l'instance
par rapport  son 'maxconn'. Un minimum de <minconn> sessions sera toujours
permis quelle que soit la charge. Ceci assurera que les serveurs travailleront
au meilleur de leurs performances sous des charges normales, et qu'ils seront
tout de mme capables de supporter de fortes pointes lorsque ncessaire. La
limite dynamique est calcule comme ceci :

    srv.dyn_limit = max(srv.minconn, srv.maxconn * inst.sess / inst.maxconn)

Exemple :
---------
    # Prendre soin du P3 qui n'a que 256 Mo de RAM.
    listen web_appl 0.0.0.0:80
        maxconn 10000
        mode http
        cookie SERVERID insert nocache indirect
        balance roundrobin
        server pentium3-800 192.168.1.1:80 cookie s1 weight  8 minconn 10 maxconn 100 check
        server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 minconn 30 maxconn 300 check
        server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 minconn 30 maxconn 300 check
        server web-backup1 192.168.2.1:80 cookie s4 check maxconn 200 backup
        server web-excuse 192.168.3.1:80 check backup

Dans l'exemple ci-dessus, le serveur "pentium3-800' recevra au plus 100
connexions simultanes lorsque l'instance du proxy en atteindra 10000, et
recevra seulement 10 connexions simultanes tant que le proxy sera sous les 1000
sessions.

Il est possible de limiter la taille de la file d'attente dans le but de
redistribuer les connexions destines  un serveur en particulier qui sont trop
loin pour avoir une chance d'tre servies en un temps raisonnable. Ceci n'est
acceptable que dans le cas o l'affinit entre le client et le serveur n'est
pas obligatoire, mais motive uniquement par des raisons de performances, par
exemple, par l'utilisation d'un cache local au serveur. L'option 'maxqueue'
permet de prciser la limite par serveur, tel que dans l'exemple ci-dessous :

... (mme exemple que prcdemment)
        server pentium3-800 192.168.1.1:80 cookie s1 weight  8 minconn 10 maxconn 100 check maxqueue 50
        server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 minconn 30 maxconn 300 check maxqueue 200
        server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 minconn 30 maxconn 300 check

En l'absence du paramtre 'maxqueue', la file d'un serveur n'a pas de limite
dfinie. Dans le cas contraire, lorsque la file atteint la limite fixe par
'maxqueue', les clients sont dplacs vers la file globale.

Notes :
-------
  - la requte ne restera pas indfiniment en file d'attente, elle est
    assujtie au paramtre 'contimeout', et si une requte ne peut pas
    sortir de la file avant ce time-out, soit parce que le serveur est
    satur, soit parce qu'il y a trop de requtes en file d'attente,
    alors elle expirera avec une erreur 503.

  - si seul <minconn> est spcifi, il a le mme effet que <maxconn>

  - positionner des valeurs trop basses pour 'maxconn' peut amliorer les
    performances mais aussi permettre  des utilisateurs trop lents de bloquer
    un serveur pour les autres utilisateurs.


3.5) Abandon des requtes abortes
----------------------------------
En prsence de trs fortes charges, les serveurs mettront un certain temps 
rpondre. La file d'attente du proxy se remplira, et les temps de rponse
suivront une croissance proportionnelle  la taille de file d'attente fois
le temps moyen de rponse par session. Lorsque les clients attendront plus de
quelques secondes, ils cliqueront souvent sur le bouton 'STOP' de leur
navigateur, laissant des requtes inutiles en file d'attente et ralentissant
donc les autres utilisateurs.

Comme il n'y a aucun moyen de distinguer un vrai clic sur STOP d'une simple
fermeture du canal de sortie sur le client (shutdown(SHUT_WR)), les agents HTTP
doivent tre conservateurs et considrer que le client n'a probablement ferm
que le canal de sortie en attendant la rponse. Toutefois, ceci introduit des
risques de congestion lorsque beaucoup d'utilisateurs font de mme, et s'avre
aujourd'hui compltement inutile car probablement aucun client ne referme la
session en attendant la rponse. Certains agents HTTP supportent ceci (Squid,
Apache, HAProxy), et d'autres ne le supportent pas (TUX, et la plupart des
rpartiteurs de charge matriels). Donc la probabilit pour qu'une notification
de fermeture d'un canal d'entre ct client reprsente un utilisateur cliquant
sur 'STOP' est proche de 100%, et il est vraiment tentant d'abandonner la
requte prmaturment sans polluer les serveurs.

Pour cette raison, une nouvelle option "abortonclose" a t introduite en
version 1.2.14. Par dfaut (sans l'option), le comportement reste conforme 
HTTP. Mais lorsque l'option est spcifie, une session dont le canal entrant
est ferm sera aborte si cela est possible, c'est  dire que la requte est
soit en file d'attente, soit en tentative de connexion. Ceci rduit
considrablement la longueur des files d'attentes et la charge sur les serveurs
saturs lorsque les utilisateurs sont tents de cliquer sur 'STOP', ce qui 
son tour, rduit les temps de rponse pour les autres utilisateurs.

Exemple :
---------
    listen web_appl 0.0.0.0:80
        maxconn 10000
        mode http
        cookie SERVERID insert nocache indirect
        balance roundrobin
        server web1 192.168.1.1:80 cookie s1 weight 10 maxconn 100 check
        server web2 192.168.1.2:80 cookie s2 weight 10 maxconn 100 check
        server web3 192.168.1.3:80 cookie s3 weight 10 maxconn 100 check
        server bck1 192.168.2.1:80 cookie s4 check maxconn 200 backup
        option abortonclose


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

D'autres fonctionnalits d'usage moins courant sont disponibles. Il s'agit
principalement du mode transparent, de la journalisation des connexions, de la
rcriture des en-ttes, et du statut sous forme de page HTML.


4.1) Fonctionnalits rseau
---------------------------
4.1.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.1.2) Choix d'une adresse source par serveur
---------------------------------------------------
Avec les versions 1.1.30 et 1.2.3, il devient possible de spcifier une adresse
IP source pour joindre chaque serveur. C'est utile pour joindre des serveurs de
backup  partir d'un LAN diffrent, ou pour utiliser des chemins alternatifs
pour joindre le mme serveur. C'est galement utilisable pour faciliter une
rpartition de charge selon l'adresse IP source pour des connexions sortantes.
Bien entendu, la mme adresse est utilise pour les health-checks.

Exemple :
---------
    # utiliser une adresse particulire pour joindre les 2 serveur
    listen http_proxy 0.0.0.0:65000
       mode http
       balance roundrobin
       server server01 192.168.1.1:80 source 192.168.2.13
       server server02 192.168.1.2:80 source 192.168.2.13

Exemple :
---------
    # utiliser une adresse particulire pour joindre chaque serveur
    listen http_proxy 0.0.0.0:65000
       mode http
       balance roundrobin
       server server01 192.168.1.1:80 source 192.168.1.1
       server server02 192.168.2.1:80 source 192.168.2.1

Exemple :
---------
    # faire une rpartition d'adresse sources pour joindre le mme proxy 
    # travers deux liens WAN 
    listen http_proxy 0.0.0.0:65000
       mode http
       balance roundrobin
       server remote-proxy-way1 192.168.1.1:3128 source 192.168.2.1
       server remote-proxy-way2 192.168.1.1:3128 source 192.168.3.1

Exemple :
---------
    # forcer une connexion TCP  s'attacher  un port particulier
    listen http_proxy 0.0.0.0:2000
       mode tcp
       balance roundrobin
       server srv1 192.168.1.1:80 source 192.168.2.1:20
       server srv2 192.168.1.2:80 source 192.168.2.1:20

4.1.3) Maintien de session TCP (keep-alive)
-------------------------------------------
Avec la version 1.2.7, il devient possible d'activer le maintien de session
TCP (TCP keep-alive)  la fois ct client et ct serveur. Cela permet
d'empcher des sessions longues d'expirer sur des quipements de niveau 4
externes tels que des firewalls ou des rpartiteurs de charge. Cela permet
aussi au systme de dtecter et terminer des sessions figes lorsqu'aucun
time-out n'a t positionn (fortement dconseill). Le proxy ne peut pas
positionner l'intervalle entre les annonces ni le nombre maximal, veuillez
vous rfrer au manuel du systme d'exploitation pour cela. Il existe 3 options
pour activer le maintien de session TCP :

	option tcpka	# active le keep-alive ct client et ct serveur
	option clitcpka	# active le keep-alive ct client
	option srvtcpka	# active le keep-alive ct serveur

4.1.4) Rmanence des donnes TCP (lingering)
--------------------------------------------
Il est possible de dsactiver la conservation de donnes non acquittes par un
client  la fin d'une session. Cela peut parfois s'avrer ncessaire lorsque
haproxy est utilis en face d'un grand nombre de clients non fiables et qu'un
nombre lev de sockets en tat FIN_WAIT est observ sur la machine. L'option
peut tre utilise dans un frontend pour ajuster les connexions vers les
clients, et dans un backend pour ajuster les connexions vers les serveurs :

	option nolinger	# dsactive la conservation de donnes


4.2) Journalisation des connexions
----------------------------------

L'un des points forts de HAProxy est indniablement la prcision de ses logs.
Il fournit probablement le plus fin niveau d'information disponible pour un
tel outil, ce qui est trs important pour les diagnostics en environnements
complexes. En standard, les informations journalises incluent le port client,
les chronomtrages des tats TCP/HTTP, des tats de session prcis au moment de
la terminaison et sa cause, des informations sur les dcisions d'aiguillage du
trafic vers un serveur, et bien sr la possibilit de capturer des en-ttes
arbitraires.

Dans le but d'amliorer la ractivit des administrateurs, il offre une grande
transparence sur les problmes rencontrs,  la fois internes et externes, et
il est possible d'envoyer les logs vers des serveurs diffrents en mme temps
avec des niveaux de filtrage diffrents :

  - logs globaux au niveau processus (erreurs systme, arrts/dmarrages, ...)
  - erreurs systme et internes par instance (manque de ressources, bugs, ...)
  - problmes externes par instance (arrts/relance serveurs, limites, ...)
  - activit par instance (connexions clients), aussi bien lors de leur
    tablissement qu' leur terminaison.

La possibilit de distribuer diffrents niveaux de logs  diffrents serveurs
permet  plusieurs quipes de production d'intragir et de corriger leurs
problmes le plus tt possible. Par exemple, l'quipe systme peut surveiller
occasionnellement les erreurs systme, pendant que l'quipe application
surveille les alertes d'arrts/dmarrages de ses serveurs en temps rel, et
que l'quipe scurit analyse l'activit en diffr d'une heure.


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. Le nombre de sessions restantes aprs la
dconnexion est galement indiqu (pour le serveur, l'instance et le process).

Exemple de journalisation TCP :
-------------------------------
    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/0/5007 0 -- 1/1/1 0/0
  
    Champ  Format / Description                          Exemple

        1  nom_processus '[' pid ']:'                    haproxy[18989]:
        2  ip_client ':' port_client                     127.0.0.1:34550
        3  '[' date ']'                                  [15/Oct/2003:15:24:28]
        4  nom_instance                                  relais-tcp
        5  nom_serveur                                   Srv1
        6  temps_file '/' temps_connect '/' temps_total  0/0/5007
        7  octets lus                                    0
        8  etat_terminaison                              --
        9  conn_srv '/' conns_inst '/' conns_processus   1/1/1
       10  position en file d'attente srv '/' globale    0/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 de journalisation HTTP :
--------------------------------
    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/0/7/147/723 200 243 - - ---- 2/3/3 0/0 "HEAD / HTTP/1.0"

Exemple plus complet :

    haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31] relais-http Srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 137/202/205 0/0 {w.ods.org|Mozilla} {} "HEAD / HTTP/1.0" 

    Champ  Format / Description                          Exemple

        1  nom_processus '[' pid ']:'                    haproxy[18989]:
        2  ip_client ':' port_client                     10.0.0.1:34552
        3  '[' date ']'                                  [15/Oct/2003:15:26:31]
        4  nom_instance                                  relais-http
        5  nom_serveur                                   Srv1
        6  Tq '/' Tw '/' Tc '/' Tr '/' Tt                3183/-1/-1/-1/11215
        7  Code_retour_HTTP                              503
        8  octets lus                                    0
        9  cookies_requte_capturs                      -
       10  cookies_reponse_capturs                      -
       11  etat_terminaison                              SC--
       12  conns_srv '/' conns_inst '/' conns_processus  137/202/205
       13  position file serveur '/' globale             0/0
       14  '{' entetes_requte_capturs '}'              {w.ods.org|Mozilla}
       15  '{' entetes_reponse_capturs '}'              {}
       16  '"' requte_HTTP '"'                          "HEAD / HTTP/1.0"
  
Note pour les analyseurs de logs : l'URI est TOUJOURS le dernier champ de la ligne, et
                                   commence par un guillemet '"'.

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 en-ttes de la rponse du serveur, auquel cas le nombre d'octets
reprsentera la taille des en-ttes 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 '+'
rappelant 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 - - ---- 3/3 "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/Tw/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.

  - Tw: temps total pass dans les files d'attente avant d'obtenir une place
    vers un serveur. Ceci tient compte  la fois de la file d'attente globale
    et de celle du serveur, et dpend du nombre de requtes dans la file et du
    temps ncessaire au serveur pour complter les sessions prcdentes. La
    valeur '-1' indique que la requte a t dtruite avant d'atteindre une
    file.

  - 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 en-ttes 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'en-tte 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 + Tw + 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 + Tw + Tc + Tr)

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

En mode TCP ('option tcplog'), seuls les deux indicateurs Tw, 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/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/xx/Tt: Il n'tait pas possible de traiter la request, probablement
                  parce que tous les serveurs taient hors d'usage.
  Tq/Tw/-1/xx/Tt: la connexion n'a pas pu s'tablir vers le serveur (refus ou
                  time-out au bout de Tt-(Tq+Tw) ms).
  Tq/Tw/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+Tw+Tc) ms.
     
4.2.4) Conditions de dconnexion
--------------------------------
Les logs TCP et HTTP fournissent un indicateur de compltude de la session dans
le champ 'etat_terminaison', juste avant le nombre de connexions actives. C'est
un champ long de 2 caractres en TCP et de 4 caractres en HTTP, chacun ayant
une signification prcise :

  - sur le premier caractre, un code prcisant le premier vnement qui a caus
    la terminaison de la session :

        C : fermeture inattendue de la session TCP de la part du client.

        S : fermeture inattendue de la session TCP de la part du serveur, ou
            refus explicite de connexion de la part de ce dernier.

        P : terminaison prmature des sessions par le proxy, pour cause
            d'imposition d'une limite sur le nombre de connexions, pour cause
            de configuration (ex: filtre d'URL), ou parce qu'un contrle de
            scurit a dtect et bloqu une anomalie dans la rponse du
            serveur qui aurait pu causer une fuite d'informations (par exemple,
            un cookie cachable).

        R : une ressource sur le proxy a t puise (mmoire, sockets, ports
            source, ...). Gnralement, cela arrive au cours de l'tablissement
            d'une connexion, et les logs systme doivent contenir une copie de
            l'rreur prcise.

        I : une erreur interne a t identifie par le proxy  la suite d'un
            auto-contrle. Ceci ne doit JAMAIS arriver, et vous tes encourags
             remonter n'importe quel log contenant ceci car il s'agira un bug.

        c : le dlai maximal d'attente du client a expir (clitimeout).

        s : le dlai maximal d'attente du serveur a expir (srvtimeout et contimeout)

        - : terminaison normale de session.

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

        R : attente d'une REQUETE HTTP complte de la part du client. Rien n'a
            t transmis au serveur.

        Q : attente en file d'attente (QUEUE) d'une place pour avoir une
            connexion vers un serveur. Ne peut apparatre que sur un serveur
            possdant un paramtre 'maxconn'. Aucune connexion n'a t envoye
            au serveur.

        C : attente de l'tablissement d'une CONNEXION vers le serveur. Le
            serveur peut au plus avoir vu la tentative de connexion, mais
            aucune donne n'a t change.

        H : attente, rception ou traitement des en-ttes HTTP ("HEADERS").

        D : transfert des DONNEES du serveur vers le client.

        L : transfert des dernires ("LAST") donnes du proxy vers le client,
            alors que le serveur a dj fini.

        T : requte bloque en mode "tarpit" par le proxy. Elle a t maintenue
            ouverte vers le client pendant toute la dure du contimeout ou
            jusqu' l'abandon de la part du client.

        - : 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. C'est gnralement le
            cas sur les NOUVELLES connexions clients.

        I : le client a prsent un cookie INVALIDE ne correspondant  aucun
            serveur connu. Ceci peut tre d  un changement de configuration
            rcent,  des mlanges de noms de cookies entre sites HTTP/HTTPS,
            ou  une attaque.

        D : le client a prsent un cookie correspondant  un serveur hors
            d'usage ("DOWN"). 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 (pas de cookie positionn dans la configuration).

  - 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 persistance n'a t fourni par le serveur, et aucun
            n'a t insr.

        I : aucun cookie de persistance n'a t fourni par le serveur, et le
            proxy en a INSERE un.

        P : un cookie de persistence a t fourni par le serveur et transmis
            tel quel ("PASSIF").

        R : le cookie retourn par le serveur a t REECRIT par le proxy.

        D : le cookie prsent par le serveur a t DETRUIT par le proxy pour
            ne pas tre retourn au client.

        - : non appliquable


La combinaison des deux premiers indicateurs fournit une grande quantiti
d'informations sur ce qui se passait lorsque la session s'est termine. Cela
peut notamment aider  dtecter une saturation de serveur, des troubles rseau,
des puisements de ressources systme locales, des attaques, etc...

Les combinaisons d'indicateurs les plus frquentes sont numres ici.

   Indic  Raison
      CR  Le client a abandonn avant d'mettre une requte complte. Il est
          trs probable que la requte ait t tape  la main dans un client
          telnet et aborte trop tt.

      cR  Le temps imparti au client a expir avant rception d'une requte
          complte. Ceci est parfois caus par un paramtre TCP MSS trop lev
          sur le client pour des rseaux PPPoE sur ADSL qui ne peuvent pas
          transporter des paquets entiers, ou par des clients qui nvoient des
          requtes  la main et ne tapent pas assez vite.

      SC  Le serveur a explicitement refus la connexion (le proxy a reu un
          RST TCP ou un message ICMP en retour). Dans certains cas, cela peut
          tre la couche rseau qui indique au proxy que le serveur n'est pas
          joignable (p.ex: pas de route, pas de rponse ARP en local, etc...)

      sC  La connexion au serveur n'a pas pu s'tablir dans le temps imparti.

      PC  Le proxy a refus d'tablir une connexion au serveur parce que le
          nombre de connexions a atteint la limite 'maxconn' (global ou de
          l'instance). Le paramtre 'maxconn' de l'instance pourrait tre
          augment, tout comme le paramtre 'maxconn' global.

      RC  Une ressource locale a t puise (mmoire, sockets, ports source),
          empchant la connexion au serveur de s'tablir. Les logs d'erreurs
          diront prcisment ce qui manquait. Dans tous les cas, le seul remde
          consiste  affiner le paramtrage systme.

      cH  Le temps imparti au client a expir au cours d'une requte POST. Ceci
          est parfois caus par un paramtre TCP MSS trop lev sur le client
          pour des rseaux PPPoE sur ADSL qui ne peuvent pas transporter des
          paquets entiers.

      CH  Le client a abandonn alors qu'il attendait un dbut de rponse de la
          part du serveur. Cela peut tre caus par le serveur qui mettait trop
          de temps  rpondre, ou par un client cliquant prcipitamment sur le
          bouton 'Stop'.

      CQ  Le client a abandonn alors que sa session tait mise en file
          d'attente pour obtenir un serveur avec suffisamment de connexions
          libres pour l'accepter. Cela signifie soit que l'ensemble des
          serveurs taient saturs, soit que le serveur assign a mis trop de
          temps  rpondre.

      CT  Le client a abandonn alors que sa session tait bloque en mode
          tarpit.

      sQ  La session a attendu trop longtemps en file d'attente et a t
          expire.

      SH  Le serveur a abort brutalement alors qu'il devait envoyer ses
          en-ttes. En gnral, cela indique qu'il a crash.

      sH  Le serveur n'a pas pu rpondre durant le temps imparti, ce qui montre
          des transactions trop longues, probablement causes par un back-end
          satur. Les seules solutions sont de corriger le problme sur
          l'application, d'accrotre le paramtre 'srvtimeout' pour supporter
          des attentes plus longues au risque que les clients abandonnent 
          leur tour, ou bien d'ajouter des serveurs.
      
      PR  Le proxy a bloqu une requte du client, soit  cause d'une syntaxe
          HTTP invalide, auquel cas il a renvoy une erreur HTTP 400 au client,
          soit  cause d'une requte validant un filtre d'interdiction, auquel
          cas le proxy a renvoy une erreur HTTP 403.

      PH  Le proxy a bloqu la rponse du serveur parce qu'elle tait invalide,
          incomplte, dangereuse ('cache control'), ou parce qu'elle validait
          un filtre de scurit. Dans tous les cas, une erreur HTTP 502 est
          renvoye au client.

      PT  Le proxy a bloqu une requte du client et a maintenu sa connection
          ouverte avant de lui retourner une erreur "500 server error". Rien
          n'a t envoy au serveur.

      cD  Le client n'a pas lu de donnes pendant le temps qui lui tait
          imparti. Ceci est souvent caus par des problmes rseau ct client.

      CD  Le client a abort sa connection de manire inattendue pendant le
          transfert des donnes. Ceci est provoqu soit par le crash d'un
          navigateur, ou par une session en HTTP keep-alive entre le serveur
          et le client termine en premier par le client.

      sD  Le serveur n'a rien fait durant le temps imparti par le paramtre
          'srvtimeout'. Ceci est souvent caus par des timeouts trop courts
          sur des quipements de niveau 4 (firewalls, rpartiteurs de charge)
          situs entre le proxy et le serveur.

4.2.5) Caractres non-imprimables
---------------------------------
Depuis la version 1.1.29, les caractres non-imprimables ne sont plus envoys
tels quels dans les lignes de logs, mais inscrits sous la forme de deux chiffres
hexadcimaux, prfixs du caractre d'chappement '#'. Les seuls caractres
dornavant logus tels quels sont compris entre 32 et 126. Bien videmment, le
caractre d'chappement '#' est lui-mme encod afin de lever l'ambiguit. Il en
est de mme pour le caractre '"', ainsi que les caractres '{', '|' et '}' pour
les en-ttes.

4.2.6) Capture d'en-ttes HTTP et de cookies
--------------------------------------------
La version 1.1.23 a apport la capture des cookies, et la version 1.1.29 la
capture d'en-ttes. Tout ceci est effectu en utilisant le mot-cl 'capture'.

Les captures de cookies facilitent le suivi et la reconstitution d'une session
utilisateur. La syntaxe est la suivante :

    capture cookie <prfixe_cookie> len <longueur_capture>

Ceci activera la capture de cookies  la fois dans les requtes et dans les
rponses. De cette manire, il devient facile de dtecter lorsqu'un utilisateur
bascule sur une nouvelle session par exemple, car le serveur lui rassignera un
nouveau cookie.

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, ou lorsque l'option est dsactive..

Les captures d'en-ttes ont un rle compltement diffrent. Elles sont utiles
pour suivre un identifiant de requte globalement unique positionn par un
autre proxy en amont, pour journaliser les noms de serveurs virtuels, les types
de clients web, la longueur des POST, les 'referrers', etc. Dans la rponse, on
peut chercher des informations relatives  la longueur annonce de la rponse,
le fonctionnement attendu du cache, ou encore la localisation d'un objet en cas
de redirection. Tout comme pour les captures de cookies, il est possible
d'inclure les en-ttes de requtes et de rponse simultanment. La syntaxe est
la suivante :

    capture request  header <nom> len <longueur max>
    capture response header <nom> len <longueur max>

Note: Les noms d'en-ttes ne sont pas sensibles  la casse.

Exemples:
---------
    # conserver le nom du serveur virtuel accd par le client
    capture request  header Host len 20
    # noter la longueur des donnes envoyes dans un POST
    capture request  header Content-Length len 10

    # noter le fonctionnement attendu du cache par le serveur
    capture response header Cache-Control len 8
    # noter l'URL de redirection
    capture response header Location len 20

Les en-ttes non trouvs sont logus  vide, et si un en-tte apparait plusieurs
fois, seule la dernire occurence sera conserve. Les en-ttes de requte sont
regroups entre deux accolades '{' et '}' dans l'ordre de leur dclaration, et
chacun spars par une barre verticale '|', sans aucun espace. Les en-ttes de
rponse sont prsents de la mme manire, mais aprs un espace suivant le bloc
d'en-tte de requte. Le tout prcde la requte HTTP. Exemple :

  Config:

    capture request  header Host len 20
    capture request  header Content-Length len 10
    capture request  header Referer len 20
    capture response header Server len 20
    capture response header Content-Length len 10
    capture response header Cache-Control len 8
    capture response header Via len 20
    capture response header Location len 20

  Log :

    Aug  9 20:26:09 localhost haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] relais-http netcache 0/0/0/162/+162 200 +350 - - ---- 0/0/0 0/0 {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} "GET http://fr.adserver.yahoo.com/"
    Aug  9 20:30:46 localhost haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] relais-http netcache 0/0/0/182/+182 200 +279 - - ---- 0/0/0 0/0 {w.ods.org||} {Formilux/0.1.8|3495|||} "GET http://w.ods.org/sytadin.html HTTP/1.1" 
    Aug  9 20:30:46 localhost haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] relais-http netcache 0/0/2/126/+128 200 +223 - - ---- 0/0/0 0/0 {www.infotrafic.com||http://w.ods.org/syt} {Apache/2.0.40 (Red H|9068|||} "GET http://www.infotrafic.com/images/live/cartesidf/grandes/idf_ne.png HTTP/1.1" 

4.2.7) Exemples de logs
-----------------------
- haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57] relais-http Srv1 6559/0/7/147/6723 200 243 - - ---- 1/3/5  0/0"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:33319 [15/Oct/2003:08:31:57] relais-http Srv1 6559/1230/7/147/6870 200 243 - - ---- 99/239/324 0/9 "HEAD / HTTP/1.0"
  => Idem, mais la requte a t mise en attente dans la file globale derrire
     9 autres requtes dj prsentes, et y a attendu 1230 ms.

- haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/0/7/14/+30 200 +243 - - ---- 1/3/3 0/0 "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'en-ttes 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/0/7/14/30 502 243 - - PH-- 0/2/3 0/0 "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/-1/8490 -1 0 - - CR-- 0/2/2 0/0 "" 
  => 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'en-tte ('-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/-1/50001 408 0 - - cR-- 0/2/2 0/0 "" 
  => 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'en-tte ('-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 ('cD') au bout de
     5s.

- haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31] relais-http Srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 115/202/205 0/0 "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. Il y avait 115 connexions sur ce serveur, 202 connexions sur cette
     instance, et 205 sur l'ensemble des instances pour ce processus. Il est
     possible que le serveur ait refus la connexion parce qu'il y en avait
     dj trop d'tablies.


4.3) Modification des en-ttes 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 en-tte valide <search>
   reqiallow <search>             idem sans distinction majuscules/minuscules
   reqdeny   <search>             interdire la requte si un en-tte valide <search>
   reqideny  <search>             idem sans distinction majuscules/minuscules
   reqpass   <search>             inhibe ces actions sur les en-ttes validant <search>
   reqipass  <search>             idem sans distinction majuscules/minuscules
   reqtarpit <search>             bloquer et maintenir une request validant <search>
   reqitarpit <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
                                  en-tte 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 0  9, et sont codes par un '\'
suivi du chiffre dsir (0 dsignant la ligne complte). 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
    en-ttes 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".
  - une requte bloque par 'reqtarpit' sera maintenue pendant une dure gale
    au paramtre 'contimeout', ou jusqu' l'abandon du client. Rien ne sera
    envoy au serveur. Lorsque le temps allou expire, le proxy rpondra avec
    une rponse "500 server error" de sorte que l'attaquant ne suspecte pas
    qu'il ait t bloqu. Les logs rapporteront aussi ce code 500, mais les
    flags de terminaison indiqueront "PT".

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\?)

	# tarpit attacks on the login page.
        reqtarpit     ^[^:\ ]*\ .*\.php?login=[^0-9]

        # 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. Depuis la version 1.3.8, il est
possible de prciser le mot-cl "except" suivi d'une adresse ou un rseau
IP source pour lequel l'entte ne sera pas ajout. C'est trs pratique dans le
cas o un autre reverse-proxy ajoutant dj l'entte est install sur la mme
machine ou dans une DMZ connue. Le cas le plus frquent est li  l'utilisation
de stunnel en local.

Enfin, l'option 'httpclose' apparue dans la version 1.1.28/1.2.1 supprime tout
en-tte 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 except 127.0.0.1/8
        option httpclose

Notons que certains serveurs HTTP ne referment pas ncessairement la session
TCP en fin de traitement lorsqu'ils reoivent un entte 'Connection: close',
ce qui se traduit par des grands nombres de sessions tablies et des temps
globaux trs longs sur les requtes. Pour contourner ce problme, la version
1.2.9 apporte une nouvelle option 'forceclose' qui referme la connexion sortant
vers le serveur ds qu'il commence  rpondre et seulement si le tampon de
requte est vide. Attention toutefois  ne PAS utiliser cette option si des
mthodes CONNECT sont attendues entre le client et le serveur. L'option
'forceclose' implique l'option 'httpclose'.

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


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 srv1 192.168.1.1:80 cookie server01 check
        server srv2 192.168.1.2:80 cookie server02 check

L'autre solution apporte par les versions 1.1.30 et 1.2.3 est de rutiliser un
cookie en provenance du serveur et de lui prfixer l'identifiant du serveur.
Dans ce cas, ne pas oublier de forcer le mode "httpclose" pour empcher le
client et le serveur de travailler en mode "keep-alive" afin que le proxy
puisse corriger le nom du cookie dans toutes les futures requtes.

    listen application 0.0.0.0:80
       mode http
       cookie JSESSIONID prefix
       balance roundrobin
       server srv1 192.168.1.1:80 cookie srv1 check
       server srv2 192.168.1.2:80 cookie srv2 check
       option httpclose


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 en-ttes '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'en-tte 'Set-cookie' ;
  - toutes celles qui ont un code de retour autre que 200, 203, 206, 300, 301, 
    410, sauf si le serveur a positionn un en-tte 'Cache-control: public' ;
  - celles qui font suite  une requte POST, sauf si le serveur a positionn
    un en-tte 'Cache-control: public' ;
  - celles qui ont un en-tte 'Pragma: no-cache' ;
  - celles qui ont un en-tte 'Cache-control: private' ; 
  - celles qui ont un en-tte 'Cache-control: no-store' ; 
  - celles qui ont un en-tte 'Cache-control: max-age=0' ;
  - celles qui ont un en-tte 'Cache-control: s-maxage=0' ;
  - celles qui ont un en-tte 'Cache-control: no-cache' ;
  - celles qui ont un en-tte 'Cache-control: no-cache="set-cookie"' ;
  - celles qui ont un en-tte '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
en-ttes. 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 de deux manires, l'une reposant sur
une redirection vers un serveur connu, et l'autre consistant  retourner un
fichier local.

4.6.1) Redirection
------------------
Une redirection d'erreur est assure 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

Note: la RFC2616 stipule qu'un client doit rutiliser la mme mthode pour
accder  l'URL de redirection que celle qui l'a retourne, ce qui pose des
problmes avec les requtes POST. Le code de retour 303 a t cr exprs pour
rgler ce problme, indiquant au client qu'il doit accder  l'URL retourne
dans le champ Location avec la mthode GET uniquement. Seulement, certains
navigateurs antrieurs  HTTP/1.1 ne connaissent pas ce code de retour. De
plus, la plupart des navigateurs se comportent dj avec le code 302 comme ils
devraient le faire avec le 303. Donc, dans le but de laisser le choix 
l'utilisateur, les versions 1.1.31 et 1.2.5 apportent deux nouvelles commandes
visant  remplacer 'errorloc' : 'errorloc302' et 'errorloc303'.

Leur usage non ambig est recommand  la place de la commande 'errorloc' (qui
utilise toujours 302). Dans le doute, prfrez l'utilisation de 'errorloc303'
ds que vous savez que vos clients supportent le code de retour HTTP 303.

4.6.2) Fichiers locaux
----------------------
Parfois il est souhaitable de changer l'erreur retourne sans recourir  des
redirections. La seconde mthode consiste  charger des fichiers locaux lors
du dmarrage et  les envoyer en guise de pur contenu HTTP en cas d'erreur.
C'est ce que fait le mot cl 'errorfile'.

Attention, il y a des piges  prendre en compte :
 - les fichiers sont chargs durant l'analyse de la configuration, avant de
   faire le chroot(). Donc ils sont relatifs au systme de fichiers rel. Pour
   cette raison, il est recommand de toujours passer un chemin absolu vers ces
   fichiers.

 - le contenu de ces fichiers n'est pas du HTML mais vraiment du protocole HTTP
   avec potentiellement un corps HTML. Donc la premire ligne et les en-ttes
   sont obligatoires. Idalement, chaque ligne dans la partie HTTP devrait se
   terminer par un CR-LF pour un maximum de compatibilit.

 - les rponses sont limites  une taille de buffer (BUFSIZE), gnralement 8
   ou 16 ko.

 - les rponses ne devraient pas inclure de rfrences aux serveurs locaux,
   afin de ne pas risquer de crer des boucles infinies sur le navigateur dans
   le cas d'une panne locale.

Exemple :
---------
        errorfile 400 /etc/haproxy/errorfiles/400badreq.http
        errorfile 403 /etc/haproxy/errorfiles/403forbid.http
        errorfile 503 /etc/haproxy/errorfiles/503sorry.http


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.


4.8) Rapport d'tat sous forme de page HTML
-------------------------------------------
Avec la version 1.2.14, il devient possible pour haproxy d'interceptre des
requtes pour une URI particulire et de retourner un rapport complet d'tat de
l'activit du proxy, et des statistiques sur les serveurs. Ceci est disponible
via le mot cl "stats" associ  n'importe laquelle de ces options :

   - stats enable
   - stats uri <uri prefix>
   - stats realm <authentication realm>
   - stats auth <user:password>
   - stats scope <proxy_id> | '.'


Par dfaut, le rapport est dsactiv. Le fait de spcifier une des combinaision
ci-dessus active le rapport pour l'instance de proxy qui le rfrence. La
solution la plus simple est d'utiliser "stats enable" qui activera le rapport
avec les paramtres par dfaut suivant :

   - default URI   : "/haproxy?stats"        (CONFIG_STATS_DEFAULT_URI)
   - default auth  : non spcifi (pas d'authentication)
   - default realm : "HAProxy Statistics"    (CONFIG_STATS_DEFAULT_REALM)
   - default scope : non specifi (accs  toutes les instances)

L'option "stats uri <uri_prefix>" permet d'intercepter un autre prfixe d'URI
que celui par dfaut. Noter que n'importe quelle URI qui COMMENCE avec cette
chane sera valide. Par exemple, une instance pourrait tre ddie  la page
d'tat seulement et rpondre  toute URI.

Example :
---------
    # intercepte n'importe quelle URI et retourne la page d'tat.
    listen stats :8080
        mode http
        stats uri /


L'option "stats auth <user:password>" active l'authentification "Basic" et
ajoute un couple "user:password" valide  la liste des comptes autoriss.
L'utilisateur <user> et le mot de passe <password> doivent tre prciss
en clair dans le fichier de configuration, et comme ceci est de
l'authentification HTTP "Basic", il faut tre conscient qu'ils transitent en
clair sur le rseau, donc il ne faut pas utiliser de compte sensible. La liste
est illimite dans le but de pouvoir fournir des accs facilement  des
dveloppeurs ou  des clients.

L'option "stats realm <realm>" dfinit le "domaine" ("realm") de validit du
mot de passe qui sera prsent dans la bote de dialogue du navigateur
lorsqu'il demandera un compte utilisateur et un mot de passe. Il est important
de s'assurer que celui-ci soit diffrent de ceux utiliss par l'application,
autrement le navigateur tentera d'en utiliser un cach depuis l'application.
Noter que les espaces dans le nom de "realm" doivent tre protgs par un
backslash ('\').

L'option "stats scope <proxy_id>" limite la porte du rapport d'tat. Par
dfaut, toutes les instances proxy sont listes. Mais dans certaines
circonstances, il serait prfrable de ne lister que certains proxies ou
simplement le proxy courant. C'est ce que fait cette option. Le nom spcial "."
(un simple point) rfrence le proxy courant. Cette option peut tre rpte
autant de fois que ncessaire pour autoriser d'autres proxies, mme pour des
noms rfrencs plus loin dans la configuration ou bien des noms qui n'existent
pas encore. Le nom prcis est celui qui apparait aprs le mot cl "listen".

Exemple :
---------
    # simple application embarquant la page d'tat authentifie
    listen app1 192.168.1.100:80
        mode http
        option httpclose
        balance roundrobin
        cookie SERVERID postonly insert indirect
        server srv1 192.168.1.1:8080 cookie srv1 check inter 1000
        server srv1 192.168.1.2:8080 cookie srv2 check inter 1000
        stats uri /my_stats
        stats realm Statistics\ for\ MyApp1-2
        stats auth guest:guest
        stats auth admin:AdMiN123
        stats scope .
        stats scope app2

    # simple application embarquant la page d'tat sans authentification
    listen app2 192.168.2.100:80
        mode http
        option httpclose
        balance roundrobin
        cookie SERVERID postonly insert indirect
        server srv1 192.168.2.1:8080 cookie srv1 check inter 1000
        server srv1 192.168.2.2:8080 cookie srv2 check inter 1000
        stats uri /my_stats
        stats realm Statistics\ for\ MyApp2
        stats scope .

    listen admin_page :8080
        mode http
        stats uri /my_stats
        stats realm Global\ statistics
        stats auth admin:AdMiN123

Notes :
-------
  - les options "stats" peuvent aussi tre spcifies dans une section
    "defaults", auquel cas la mme configuration exactement sera fournie 
    toutes les instances suivantes, d'o l'utilit du scope ".". Toutefois, si
    une instance redfinit n'importe quel paramtre "stats", alors les dfauts
    ne lui seront pas appliqus.

  - l'authentification "Basic" est trs simpliste et non scurise contre la
    capture rseau. Aucun mot de passe sensible ne doit tre utilis, et il
    est bon de savoir qu'il n'existe pas de moyen de le supprimer du navigateur
    aprs usage, donc il sera envoy tel quel  l'application au cours des
    accs successifs.

  - Il est trs important de prciser l'option "httpclose", sinon le proxy ne
    sera pas en mesure de dtecter les URI dans les sessions keep-alive
    maintenues entre le navigateur et les serveurs, donc les URI de stats
    seront transmises telles quelles aux serveurs comme si l'option n'tait
    pas prcise.


5) Listes d'accs
=================

Avec la version 1.3.10, un nouveau concept de listes d'accs (ACL) a vu le
jour. Comme il n'tait pas ncessaire de rinventer la roue, et du fait que
toutes les rflexions passes aboutissaient  des propositions non
satisfaisantes, il a finalement t dcid que quelque chose de proche de ce
que Squid offre serait un bon compromis entre une richesse fonctionnelle et une
facilit d'utilisation

Le principe est trs simple : les ACLs sont dclares avec un nom, un test et
une liste de valeurs valides  tester. Des conditions sont appliques sur
diverses actions, et ces conditions effectuent un ET logique entre les ACLs. La
condition n'est donc valide que si toutes les ACLs sont vraies.

Il est galement possible d'utiliser le mot rserv "OR" dans les conditions,
et il est possible pour une ACL d'tre spcifie plusieurs fois, mme avec des
tests diffrents, auquel cas le premier test russi validera l'ACL.

Au stade de la version 1.3.12, seuls les tests suivants ont t implments :

   Niveaux 3/4 :
     src       <ipv4_address>[/mask] ... : match IPv4 source address
     dst       <ipv4_address>[/mask] ... : match IPv4 destination address
     src_port  <range> ...               : match source port range
     dst_port  <range> ...               : match destination port range
     dst_conn  <range> ...               : match #connections on frontend

   Niveau 7 :
     method    <HTTP method> ...  : match HTTP method
     req_ver   <1.0|1.1> ...      : match HTTP request version
     resp_ver  <1.0|1.1> ...      : match HTTP response version
     status    <range> ...        : match HTTP response status code in range
     url       <string> ... : exact string match on URI
     url_reg   <regex>  ... : regex string match on URI
     url_beg   <string> ... : true if URI begins with <string>
     url_end   <string> ... : true if URI ends with <string>
     url_sub   <string> ... : true if URI contains <string>
     url_dir   <string> ... : true if URI contains <string> between slashes
     url_dom   <string> ... : true if URI contains <string> between slashes or dots

Une plage ('range') est constitue d'un ou deux entiers qui peuvent tre
prfixs d'un oprateur. La syntaxe est :

  [<op>] <min>[:<max>]

Avec <op> pouvant tre :
  'eq' : la valeur doit galer <min> ou tre comprise entre <min> et <max>
  'le' : la valeur doit tre infrieure ou gale  <min>
  'lt' : la valeur doit tre strictement infrieure  <min>
  'ge' : la valeur doit tre suprieure ou gale  <min>
  'gt' : la valeur doit tre strictement suprieure  <min>

Lorsqu'aucun oprateur n'est dfini, 'eq' est employ. Noter que lorsqu'un
oprateur est spcifi, il s'applique  toutes les plages de valeurs suivantes
jusqu' la fin de la ligne ou bien jusqu' ce qu'un nouvel oprateur soit
prcis. Exemple :

  acl status_error  status   400:599
  acl saturated_frt dst_conn ge 1000
  acl invalid_ports src_port lt 512 ge 65535

D'autres tests arrivent (enttes, cookies, heure, authentification), c'est
juste une question de temps. Il est aussi prvu de permettre de lire les
valeurs depuis un fichier, ainsi que d'ignorer la casse pour certains tests.

La seule commande supportant les conditions d'ACL  ce jour est la nouvelle
commande "block" qui bloque une requte et retourne un statut 403 si sa
condition est valide (cas du "if") ou invalide (cas du "unless").

Exemple :
---------

    acl options_uris  url *
    acl meth_option   method OPTIONS
    acl http_1.1      req_ver 1.1
    acl allowed_meth  method GET HEAD POST OPTIONS CONNECT
    acl connect_meth  method CONNECT
    acl proxy_url     url_beg http://

    # block if reserved URI "*" used with a method other than "OPTIONS"
    block if options_uris !meth_option

    # block if the OPTIONS method is used with HTTP 1.0
    block if meth_option !http_1.1

    # allow non-proxy url with anything but the CONNECT method
    block if !connect_meth !proxy_url

    # block all unknown methods
    block unless allowed_meth

Note: Cette documentation est embryonnaire mais doit permettre de dmarrer et
surtout d'avancer sur le projet sans tre trop ralenti par la documentation.


=======================
| 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 1 > /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 --