haproxy/doc/haproxy.txt

         		     H A - P r o x y
         		     ---------------
         		      version 1.1.14
			      willy tarreau
			       2002/07/20

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

HA-Proxy est un relais TCP/HTTP offrant des facilit<69>s d'int<6E>gration en
environnement hautement disponible. En effet, il est capable de :
  - effectuer un aiguillage statique d<>fini par des cookies ;
  - effectuer une r<>partition de charge avec cr<63>ation de cookies pour assurer la
    persistence de session ; 
  - fournir une visibilit<69> externe de son <20>tat de sant<6E> ;
  - s'arr<72>ter en douceur sans perte brutale de service.
  - modifier/ajouter/supprimer des ent<6E>tes dans la requ<71>te et la r<>ponse.
  - interdire des requ<71>tes qui v<>rifient certaines conditions.

Il requiert peu de ressources, et son architecture <20>v<EFBFBD>nementielle mono-processus
lui permet facilement de g<>rer plusieurs milliers de connexions simultan<61>es sur
plusieurs relais sans effondrer le syst<73>me.


===========================
| Param<61>tres de lancement |
===========================

Les options de lancement sont peu nombreuses :

    -f <fichier de configuration>
    -n <nombre maximal total de connexions simultan<61>es>
    -N <nombre maximal de connexions simultan<61>es par proxy>
    -d active le mode debug
    -D passe en daemon
    -s affiche les statistiques (si option compil<69>e)
    -l ajoute des informations aux statistiques

Le nombre maximal de connexion simultan<61>es par proxy est le param<61>tre par d<>faut
pour les proxies pour lesquels ce param<61>tre n'est pas pr<70>cis<69> dans le fichier de
configuration. Il s'agit du param<61>tre 'maxconn' dans les sections 'listen'.

Le nombre maximal total de connexions simultan<61>es limite le nombre de connexions
TCP utilisables <20> un instant donn<6E> par le processus, tous proxies confondus. Ce
param<EFBFBD>tre remplace le param<61>tre 'maxconn' de la section 'global'.

Le mode debug correspond <20> l'option 'debug' de la section 'global'. Dans ce
mode, toutes les connexions, d<>connexions, et tous les <20>changes d'ent<6E>tes HTTP
sont affich<63>s.

Les statistiques ne sont disponibles que si le programme a <20>t<EFBFBD> compil<69> avec
l'option "STATTIME". Il s'agit principalement de donn<6E>es brutes n'ayant
d'utilit<69> que lors de benchmarks par exemple.


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

Structure
=========

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

Le fichier de configuration est d<>coup<75> en sections r<>p<EFBFBD>r<EFBFBD>es par des mots cl<63>s
tels que :

  - 'global'
  - 'listen'

Tous les param<61>tres font r<>f<EFBFBD>rence <20> la section d<>finie par le dernier mot cl<63>
reconnu.


1) Param<61>tres globaux
=====================

Il s'agit des param<61>tres agissant sur le processus, ou bien sur l'ensemble des
proxies. Ils sont tous sp<73>cifi<66>s dans la section 'global'. Les param<61>tres
support<EFBFBD>s sont :

  - log <adresse> <cat<61>gorie>
  - maxconn <nombre>
  - uid <identifiant>
  - gid <identifiant>
  - chroot <r<>pertoire>
  - nbproc <nombre>
  - daemon
  - debug
  - quiet

1.1) Journalisation des <20>v<EFBFBD>nements
----------------------------------
La plupart des <20>v<EFBFBD>nements sont journalis<69>s : d<>marrages, arr<72>ts, disparition et
apparition de serveurs, connexions, erreurs. Tous les messages sont envoy<6F>s en
syslog vers un ou deux serveurs. La syntaxe est la suivante :

    log <adresse_ip> <facility>

Les connexions sont envoy<6F>es en niveau "info". Les d<>marrages de service et de
serveurs seront envoy<6F>s en "notice", les signaux d'arr<72>ts en "warning" et les
arr<EFBFBD>ts d<>finitifs de services et de serveurs en "alert". Ceci est valable aussi
bien pour les proxies que pour les serveurs test<73>s par les proxies.

Les cat<61>gories 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

Exemple :
---------
    global
	log 192.168.2.200 local3
	log 192.168.2.201 local4

1.2) limitation du nombre de connexions
---------------------------------------
Il est possible et conseill<6C> de limiter le nombre global de connexions par
processus. Les connexions sont comprises au sens 'acceptation de connexion',
donc il faut s'attendre en r<>gle g<>n<EFBFBD>ral <20> avoir un peu plus du double de
sessions TCP que le maximum de connexions fix<69>. C'est important pour fixer le
param<EFBFBD>tre 'ulimit -n' avant de lancer le proxy. Pour comptabiliser le nombre
de sockets n<>cessaires, il faut prendre en compte ces param<61>tres :
  - 1 socket par connexion entrante
  - 1 socket par connexion sortante
  - 1 socket par proxy
  - 1 socket pour chaque serveur en cours de health-check
  - 1 socket pour les logs (tous serveurs confondus)

Positionner la limite du nombre de descripteurs de fichiers (ulimit -n) <20>
2 * maxconn + nbproxy + nbserveurs + 1. Dans une future version, haproxy sera
capable de positionner lui-m<>me cette limite.

1.3) Diminution des privil<69>ges
------------------------------
Afin de r<>duire les risques d'attaques dans le cas o<> une faille non identifi<66>e
serait exploit<69>e, il est possible de diminuer les privil<69>ges du processus, et
de le cloisonner.

Dans la section 'global', le param<61>tre 'uid' permet de sp<73>cifier un identifiant
num<EFBFBD>rique d'utilisateur. La valeur 0, correspondant normalement au super-
utilisateur, poss<73>de ici une signification particuli<6C>re car elle indique que
l'on ne souhaite pas changer cet identifiant et conserver la valeur courante.
C'est la valeur par d<>faut. De la m<>me mani<6E>re, le param<61>tre 'gid' correspond <20>
un identifiant de groupe, et utilise par d<>faut la valeur 0 pour ne rien
changer. Il est particuli<6C>rement d<>conseill<6C> d'utiliser des comptes g<>n<EFBFBD>riques
tels que 'nobody' car cette pratique revient <20> utiliser 'root' si d'autres
processus utilisent les m<>mes identifiants.

Le param<61>tre 'chroot' autorise <20> changer la racine du processus une fois le
programme lanc<6E>, de sorte que ni le processus, ni l'un de ses descendants ne
puisse remonter de nouveau <20> la racine. Ce type de cloisonnement (chroot) est
parfois contournable sur certains OS (Linux 2.2, Solaris), mais visiblement
fiable sur d'autres (Linux 2.4). Aussi, il est important d'utiliser un
r<EFBFBD>pertoire sp<73>cifique au service pour cet usage, et de ne pas mutualiser un m<>me
r<EFBFBD>pertoire pour plusieurs services de nature diff<66>rente.

Remarque: dans le cas o<> une telle faille serait mise en <20>vidence, il est fort
probable que les premi<6D>res tentatives de son exploitation provoquent un arr<72>t du
programme, <20> cause d'un signal de type 'Segmentation Fault', 'Bus Error' ou
encore 'Illegal Instruction'. M<>me s'il est vrai que faire tourner le serveur en
environnement limit<69> r<>duit les risques d'intrusion, il est parfois bien utile
dans ces circonstances de conna<6E>tre les conditions d'apparition du probl<62>me, via
l'obtention d'un fichier 'core'. La plupart des syst<73>mes, pour des raisons de
s<EFBFBD>curit<EFBFBD>, d<>sactivent la g<>n<EFBFBD>ration du fichier 'core' apr<70>s un changement
d'identifiant pour le processus. Il faudra donc soit lancer le processus <20>
partir d'un compte utilisateur aux droits r<>duits (mais ne pouvant pas effectuer
le chroot), ou bien le faire en root sans r<>duction des droits (uid 0). Dans ce
cas, le fichier se trouvera soit dans le r<>pertoire de lancement, soit dans le
r<EFBFBD>pertoire sp<73>cifi<66> apr<70>s l'option 'chroot'. Ne pas oublier la commande suivante
pour autoriser la g<>n<EFBFBD>ration du fichier avant de lancer le programme :

# ulimit -c unlimited

Exemple :
---------

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

1.4) modes de fonctionnement
----------------------------
Le service peut fonctionner dans plusieurs modes :
  - avant- / arri<72>re-plan
  - silencieux / normal / debug

Le mode par d<>faut est normal, avant-plan, c'est <20> dire que le programme ne rend
pas la main une fois lanc<6E>. Il ne faut surtout pas le lancer comme ceci dans un
script de d<>marrage du syst<73>me, sinon le syst<73>me ne finirait pas son
initialisation. Il faut le mettre en arri<72>re-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'<27>quivalent du param<61>tre '-D' de la ligne de commande.

Par ailleurs, certains messages d'alerte sont toujours envoy<6F>s sur la sortie
standard, m<>me 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'<27>quivalent en ligne de commande.

Enfin, le mode 'debug' permet de diagnostiquer les origines de certains
probl<EFBFBD>mes en affichant les connexions, d<>connexions et <20>changes d'en-t<>tes 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<69> de traitement
-----------------------------------------------
Sur des machines multi-processeurs, il peut sembler g<>ch<63> de n'utiliser qu'un
processeur pour effectuer les t<>ches de relayage, m<>me si les charges
n<EFBFBD>cessaires <20> saturer un processeur actuel sont bien au-del<65> des ordres de
grandeur couramment rencontr<74>s. Cependant, pour des besoins particuliers, le
programme sait d<>marrer plusieurs processus se r<>partissant la charge de
travail. Ce nombre de processus est sp<73>cifi<66> par le param<61>tre 'nbproc' de la
section 'global'. Sa valeur par d<>faut est naturellement 1. Ceci ne fonctionne
qu'en mode 'daemon'.

Exemple :
---------

    global
	daemon
	quiet
	nbproc	2


2) D<>finition d'un service en <20>coute
====================================

Les sections de service d<>butent par le mot cl<63> "listen" :

    listen <nom_instance> <adresse_IP>:<port>

- <nom_instance> est le nom de l'instance d<>crite. Ce nom sera envoy<6F> dans les
  logs, donc il est souhaitable d'utiliser un nom relatif au service relay<61>. Aucun
  test n'est effectu<74> concernant l'unicit<69> de ce nom, qui n'est pas obligatoire,
  mais fortement recommand<6E>e. 

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

- <port> est le num<75>ro de port TCP sur lequel le relais attend ses
  connexions. Le couple <adresse_IP>:<port> doit <20>tre unique pour toutes les
  instances d'une m<>me machine. L'attachement <20> un port inf<6E>rieur <20> 1024
  n<>cessite un niveau de privil<69>ge particulier lors du lancement du programme
  (ind<6E>pendamment du param<61>tre 'uid' de la section 'global').

Exemple :
---------
    listen http_proxy 127.0.0.1:80


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

    listen smtp_proxy 0.0.0.0:25
	disabled

2.2) Mode de fonctionnement
---------------------------
Un serveur peut fonctionner dans trois modes diff<66>rents :
  - TCP
  - HTTP
  - supervision

Mode TCP
--------
Dans ce mode, le service relaye, d<>s leur <20>tablissement, les connexions TCP vers
un ou plusieurs serveurs. Aucun traitement n'est effectu<74> sur le flux. Il s'agit
simplement d'une association source<adresse:port> -> destination<adresse:port>.
Pour l'utiliser, pr<70>ciser le mode TCP sous la d<>claration 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
d<EFBFBD>cision. Les ent<6E>tes HTTP sont analys<79>s pour y trouver un <20>ventuel cookie, et
certains d'entre-eux peuvent <20>tre modifi<66>s par le biais d'expressions
r<EFBFBD>guli<EFBFBD>res. Pour activer ce mode, pr<70>ciser le mode HTTP sous la d<>claration du
relais.

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

Mode supervision
----------------
Il s'agit d'un mode offrant <20> un composant externe une visibilit<69> de l'<27>tat de
sant<EFBFBD> du service. Il se contente de retourner "OK" <20> tout client se connectant
sur son port. Il peut <20>tre utilis<69> avec des r<>partiteurs de charge <20>volu<6C>s pour
d<EFBFBD>terminer quels sont les services utilisables. Pour activer ce mode, pr<70>ciser
le mode HEALTH sous la d<>claration du relais.

Exemple :
---------
    listen health_check 0.0.0.0:60000
	mode health


2.3) Limitation du nombre de connexions simultan<61>es
---------------------------------------------------
Le param<61>tre "maxconn" permet de fixer la limite acceptable en nombre de
connexions simultan<61>es par proxy. Chaque proxy qui atteint cette valeur cesse
d'<27>couter jusqu'<27> lib<69>ration d'une connexion. Voir plus loin concernant les
limitations li<6C>es au syst<73>me.

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


2.4) Arr<72>t en douceur
---------------------
Il est possible d'arr<72>ter les services en douceur en envoyant un signal SIG_USR1
au processus relais. Tous les services seront alors mis en phase d'arr<72>t, mais
pourront continuer d'accepter des connexions pendant un temps d<>fini par le
param<EFBFBD>tre 'grace' (en millisecondes). Cela permet par exemple, de faire savoir
rapidement <20> un r<>partiteur 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 cass<73>es. Dans le pire des cas,
il faudra attendre en plus leur expiration avant l'arr<72>t total du processus. La
valeur par d<>faut est 0 (pas de gr<67>ce, arr<72>t imm<6D>diat de l'<27>coute).

Exemple :
---------
    # arr<72>ter en douceur par 'killall -USR1 haproxy'
    # le service tournera encore 10 secondes apr<70>s la demande d'arr<72>t
    listen http_proxy 0.0.0.0:80
	mode http
	grace 10000

    # ce port n'est test<73> que par un r<>partiteur de charge.
    listen health_check 0.0.0.0:60000
	mode health
	grace 0


2.5) Temps d'expiration des connexions
--------------------------------------
Il est possible de param<61>trer certaines dur<75>es d'expiration au niveau des
connexions TCP. Trois temps ind<6E>pendants sont configurables et acceptent des
valeurs en millisecondes. Si l'une de ces trois temporisations est d<>pass<73>e, la
session est termin<69>e <20> chaque extr<74>mit<69>.

  - temps d'attente d'une donn<6E>e de la part du client, ou de la
    possibilit<69> de lui envoyer des donn<6E>es : "clitimeout" :

	# time-out client <20> 2mn30.
	clitimeout	150000

  - temps d'attente d'une donn<6E>e de la part du serveur, ou de la
    possibilit<69> de lui envoyer des donn<6E>es : "srvtimeout" :

	# time-out serveur <20> 30s.
	srvtimeout	30000

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

        # on abandonne si la connexion n'est pas <20>tablie apr<70>s 4 secondes
	contimeout	4000

Remarques :
-----------
  - "contimeout" et "srvtimeout" n'ont pas d'utilit<69> dans le cas du serveur de
    type "health".
  - sous de fortes charges, ou sur un r<>seau satur<75> ou d<>fectueux, il est
    possible de perdre des paquets. Du fait que la premi<6D>re retransmission TCP
    n'ait lieu qu'au bout de 3 secoudes, fixer un timeout de connexion inf<6E>rieur
    <20> 3 secondes ne permet pas de se rattraper sur la perte de paquets car la
    session aura <20>t<EFBFBD> abandonn<6E>e avant la premi<6D>re retransmission. Une valeur de
    4 secondes r<>duira consid<69>rablement le nombre d'<27>checs de connexion.

2.6) Tentatives de reconnexion
------------------------------
Lors d'un <20>chec de connexion vers un serveur, il est possible de
retenter (potentiellement vers un autre serveur, en cas de r<>partition
de charge). Le nombre de nouvelles tentatives infructueuses avant
abandon est fourni par le param<61>tre "retries".

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


2.7) Adresse du serveur
-----------------------
Le serveur vers lequel sont redirig<69>es les nouvelles connexions est d<>fini par
le param<61>tre "dispatch" sous la forme <adresse_ip>:<port>. Il correspond <20> un
serveur d'assignation de cookie dans le cas o<> le service consiste <20> assurer
uniquement une persistence HTTP, ou bien simplement au serveur destination dans
le cas de relayage TCP simple.

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

Remarque :
----------
Ce param<61>tre n'a pas d'utilit<69> pour un serveur en mode 'health', ni en mode
'balance'.


2.8) Adresse de sortie
----------------------
Il est possible de forcer l'adresse utilis<69>e pour <20>tablir les connexions
vers les serveurs <20> l'aide du param<61>tre "source". Il est m<>me possible de
forcer le port, bien que cette fonctionnalit<69> se limite <20> des usages tr<74>s
sp<EFBFBD>cifiques. C'est particuli<6C>rement utile en cas d'adressage multiple, et
plus g<>n<EFBFBD>ralement pour permettre aux serveurs de trouver le chemin de
retour dans des contextes de routage difficiles. Si l'adresse est 0.0.0.0,
elle sera choisie librement par le systeme. Si le port est 0, il
sera choisi librement par le syst<73>me.

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

    listen rlogin_proxy 0.0.0.0:513
   	# utiliser l'adresse 192.168.1.200 et le port r<>serv<72> 900
	source 192.168.1.200:900


2.9) D<>finition du nom du cookie
--------------------------------
En mode HTTP, il est possible de rechercher la valeur d'un cookie pour savoir
vers quel serveur aiguiller la requ<71>te utilisateur. Le nom du cookie est donn<6E>
par le param<61>tre "cookie".

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

On peut modifier l'utilisation du cookie pour la rendre plus intelligente
vis-<2D>-vis des applications relay<61>es. Il est possible, notamment de supprimer ou
r<EFBFBD><EFBFBD>crire un cookie retourn<72> par un serveur acc<63>d<EFBFBD> en direct, et d'ins<6E>rer un
cookie dans une r<>ponse HTTP adress<73>e <20> un serveur s<>lectionn<6E> en r<>partition
de charge, et m<>me de signaler aux proxies amont de ne pas cacher le cookie
ins<EFBFBD>r<EFBFBD>.

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

Pour ne conserver le cookie qu'en acc<63>s indirect, donc <20> travers le
dispatcheur, et supprimer toutes ses <20>ventuelles occurences lors des acc<63>s
directs :

	cookie SERVERID indirect

Pour remplacer la valeur d'un cookie existant par celle attribu<62>e <20> un serveur,
lors d'un acc<63>s direct :

	cookie SERVERID rewrite

Pour cr<63>er un cookie comportant la valeur attribu<62>e <20> un serveur lors d'un acc<63>s
en r<>partition de charge interne. Dans ce cas, il est indispensable que tous les
serveurs aient un cookie renseign<67> :

	cookie SERVERID insert

Pour ins<6E>rer un cookie, en s'assurant qu'un cache en amont ne le stockera pas,
ajouter le mot cl<63> 'nocache' apr<70>s 'insert' :

	cookie SERVERID insert nocache

Pour ins<6E>rer un cookie seulement suite aux requ<71>tes de type POST, ajouter le mot
cl<EFBFBD> 'postonly' apr<70>s 'insert' :

	cookie SERVERID insert postonly


Remarques :
-----------
- Il est possible de combiner 'insert' avec 'indirect' ou 'rewrite' pour s'adapter
  <20> des applications g<>n<EFBFBD>rant d<>j<EFBFBD> le cookie, avec un contenu invalide. Il suffit
  pour cela de les sp<73>cifier sur la m<>me ligne.
- dans le cas o<> 'insert' et 'indirect' sont sp<73>cifi<66>s, le cookie n'est jamais
  transmis au serveur vu qu'il n'en a pas connaissance et ne pourrait pas le
  comprendre.
- il est particuli<6C>rement recommand<6E> 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 r<>ponse, incluant le
  cookie de persistence ins<6E>r<EFBFBD>, donc provoquer des changements de serveurs pour
  des clients partageant le m<>me cache.
- lorsque l'application est bien connue, et que les parties n<>cessitant de la
  persistence sont syst<73>matiquement acc<63>d<EFBFBD>es par un formulaire en mode POST,
  il est plus efficace encore de combiner le mot cl<63> "postonly" avec "insert"
  et "indirect", car la page d'accueil reste cachable, et c'est l'application
  qui g<>re le 'cache-control'.

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

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

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

Exemple : le cookie SERVERID peut contenir server01 ou server02
---------
    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

Attention : la syntaxe a chang<6E> depuis la version 1.0.
-----------

3) R<>partiteur de charge interne
=================================

Le relais peut effectuer lui-m<>me la r<>partition de charge entre les diff<66>rents
serveurs d<>finis pour un service donn<6E>, en mode TCP comme en mode HTTP. Pour
cela, on pr<70>cise le mot cl<63> 'balance' dans la d<>finition du service,
<EFBFBD>ventuellement suivi du nom d'un algorithme de r<>partition. En version 1.1.9,
seul 'roundrobin' est g<>r<EFBFBD>, et c'est aussi la valeur implicite par d<>faut. Il
est <20>vident qu'en cas d'utilisation du r<>partiteur interne, il ne faudra pas
sp<EFBFBD>cifier d'adresse de dispatch, et qu'il faudra au moins un serveur.

Exemple : m<>me que pr<70>c<EFBFBD>demment en r<>partition interne
---------

    listen http_proxy 0.0.0.0: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


3.1) Surveillance des serveurs
------------------------------
A cette date, l'<27>tat des serveurs n'est test<73> que par <20>tablissement de connexion
TCP toutes les 2 secondes, avec 3 essais pour d<>clarer un serveur en panne, 2
pour le d<>clarer utilisable. Un serveur hors d'usage ne sera pas utilis<69> dans le
processus de r<>partition de charge interne. Pour activer la surveillance,
ajouter le mot cl<63> 'check' <20> la fin de la d<>claration du serveur. Il est
possible de sp<73>cifier l'intervalle (en millisecondes) s<>parant deux tests du
serveur par le param<61>tre "inter", le nombre d'<27>checs accept<70>s par le param<61>tre
"fall", et le nombre de succ<63>s avant reprise par le param<61>tre "rise". Les
param<EFBFBD>tres non pr<70>cis<69>s prennent les valeurs suivantes par d<>faut :
 - inter : 2000
 - rise  : 2
 - fall  : 3

Exemples :
----------
# m<>me que pr<70>c<EFBFBD>demment avec surveillance
    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

# Insertion automatique de cookie dans la r<>ponse du serveur, et suppression
# automatique dans la requ<71>te, 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


3.2) Reconnexion vers un r<>partiteur en cas d'<27>chec direct
----------------------------------------------------------
En mode HTTP, si un serveur d<>fini par un cookie ne r<>pond plus, les clients
seront d<>finitivement aiguill<6C>s dessus <20> cause de leur cookie, et de ce fait,
d<EFBFBD>finitivement priv<69>s de service. La sp<73>cification du param<61>tre 'redispatch'
autorise dans ce cas <20> renvoyer les connexions <20>chou<6F>es vers le r<>partiteur
(externe ou interne) afin d'assigner un nouveau serveur <20> 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 serveur HS.


4) Fonctionnalit<69>s additionnelles
=================================

D'autres fonctionnalit<69>s d'usage moins courant sont disponibles. Il s'agit
principalement du mode transparent, de la journalisation des connexions, et de
la r<><72>criture des ent<6E>tes.

4.1) Fonctionnement en mode transparent
---------------------------------------
En mode HTTP, le mot cl<63> 'transparent' permet d'intercepter des sessions rout<75>es
<EFBFBD> travers la machine h<>bergeant le proxy. Dans ce mode, on ne pr<70>cise pas
l'adresse de r<>partition 'dispatch', car celle-ci est tir<69>e de l'adresse
destination de la session d<>tourn<72>e. Le syst<73>me 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


4.2) Journalisation des connexions
----------------------------------
Les connexions TCP et HTTP peuvent donner lieu <20> une journalisation sommaire ou
d<EFBFBD>taill<EFBFBD>e indiquant, pour chaque connexion, la date, l'heure, l'adresse IP
source, le serveur destination, la dur<75>e de la connexion, les temps de r<>ponse,
la requ<71>te HTTP, le code de retour, la quantit<69> de donn<6E>es transmise.
Tous les messages sont envoy<6F>s en syslog vers un ou deux serveurs. La syntaxe
est la suivante :

    log <adresse_ip> <facility>
    log <adresse_ip> <facility>
ou
    log global

Remarque :
----------
La syntaxe sp<73>cifique 'log global' indique que l'on souhaite utiliser les
param<EFBFBD>tres de journalisation d<>finis 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

Les connexions sont envoy<6F>es en niveau "info". Les d<>marrages de service seront
envoy<EFBFBD>s en "notice", les signaux d'arr<72>ts en "warning" et les arr<72>ts d<>finitifs
en "alert". Ceci est valable aussi bien pour les proxies que pour les serveurs
test<EFBFBD>s au sein des proxies. Les cat<61>gories 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

Par d<>faut, les informations contenues dans les logs se situent au niveau TCP
uniquement. Il faut pr<70>ciser l'option 'httplog' pour obtenir les d<>tails du
protocole HTTP. Dans les cas o<> un m<>canisme de surveillance effectuant des
connexions et d<>connexions fr<66>quentes, 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<6E> lieu <20> un <20>change de donn<6E>es (requ<71>te ou r<>ponse).

Enfin, l'option 'forwardfor' ajoute l'adresse IP du client dans un champ
'X-Forwarded-For' de la requ<71>te, ce qui permet <20> un serveur web final de
conna<EFBFBD>tre l'adresse IP du client initial.

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


4.3) Modification des ent<6E>tes HTTP
----------------------------------
En mode HTTP uniquement, il est possible de remplacer certains en-t<>tes dans la
requ<EFBFBD>te et/ou la r<>ponse <20> partir d'expressions r<>guli<6C>res. Il est <20>galement
possible de bloquer certaines requ<71>tes en fonction du contenu des en-t<>tes ou de
la requ<71>te. Une limitation cependant : les en-t<>tes fournis au milieu de
connexions persistentes (keep-alive) ne sont pas vus car ils sont consid<69>r<EFBFBD>s
comme faisant partie des <20>changes de donn<6E>es cons<6E>cutifs <20> la premi<6D>re requ<71>te.
Les donn<6E>es ne sont pas affect<63>es, ceci ne s'applique qu'aux en-t<>tes. 

La syntaxe est :
   reqadd    <string>             pour ajouter un en-t<>te dans la requ<71>te
   reqrep    <search> <replace>   pour modifier la requ<71>te
   reqirep   <search> <replace>   idem sans distinction majuscules/minuscules
   reqdel    <search>             pour supprimer un en-t<>te dans la requ<71>te
   reqidel   <search>             idem sans distinction majuscules/minuscules
   reqallow  <search>             autoriser une requ<71>te qui valide <search>
   reqiallow <search>             idem sans distinction majuscules/minuscules
   reqdeny   <search>             interdire une requ<71>te qui valide <search>
   reqideny  <search>             idem sans distinction majuscules/minuscules

   rspadd   <string>             pour ajouter un en-t<>te dans la r<>ponse
   rsprep   <search> <replace>   pour modifier la r<>ponse
   rspirep  <search> <replace>   idem sans distinction majuscules/minuscules
   rspdel   <search>             pour supprimer un en-t<>te dans la r<>ponse
   rspidel  <search>             idem sans distinction majuscules/minuscules


<search> est une expression r<>guli<6C>re compatible GNU regexp supportant
le groupage par parenth<74>ses (sans les '\'). Les espaces et autres
s<EFBFBD>parateurs doivent <20>tres pr<70>c<EFBFBD>d<EFBFBD>s d'un '\' pour ne pas <20>tre confondus
avec la fin de la cha<68>ne. De plus, certains caract<63>res sp<73>ciaux peuvent
<EFBFBD>tre pr<70>c<EFBFBD>d<EFBFBD>s d'un backslach ('\') :

  \t   pour une tabulation
  \r   pour un retour charriot
  \n   pour un saut de ligne
  \    pour diff<66>rencier un espace d'un s<>parateur
  \#   pour diff<66>rencier un di<64>se d'un commentaire
  \\   pour un backslash
  \xXX pour un caract<63>re sp<73>cifique XX (comme en C)


<replace> contient la cha<68>ne rempla<6C>ant la portion v<>rifi<66>e par l'expression.
Elle peut inclure les caract<63>res sp<73>ciaux ci-dessus, faire r<>f<EFBFBD>rence <20> un
groupe d<>limit<69> par des parenth<74>ses dans l'expression r<>guli<6C>re, par sa
position num<75>rale. Les positions vont de 1 <20> 9, et sont cod<6F>es par un '\'
suivi du chiffre d<>sir<69>. Il est <20>galement possible d'ins<6E>rer un caract<63>re non
imprimable (utile pour le saut de ligne) inscrivant '\x' suivi du code
hexad<EFBFBD>cimal de ce caract<63>re (comme en C).

<string> repr<70>sente une cha<68>ne qui sera ajout<75>e syst<73>matiquement apr<70>s la
derni<EFBFBD>re ligne d'en-t<>te.

Remarques :
---------
  - la premi<6D>re ligne de la requ<71>te et celle de la r<>ponse sont trait<69>es comme
    des en-t<>tes, ce qui permet de r<><72>crire des URL et des codes d'erreur.
  - 'reqrep' est l'<27>quivalent de 'cliexp' en version 1.0, et 'rsprep' celui de
    'srvexp'. Ces noms sont toujours support<72>s mais d<>conseill<6C>s.
  - pour des raisons de performances, le nombre total de caract<63>res ajout<75>s sur
    une requ<71>te ou une r<>ponse est limit<69> <20> 4096 depuis la version 1.1.5 (cette
    limite <20>tait <20> 256 auparavant). Cette valeur est modifiable dans le code.
    Pour un usage temporaire, on peut gagner de la place en supprimant quelques
    ent<6E>tes inutiles avant les ajouts.

Exemples :
--------
	reqrep	^(GET.*)(.free.fr)(.*) \1.online.fr\3
	reqrep	^(POST.*)(.free.fr)(.*) \1.online.fr\3
	reqirep	^Proxy-Connection:.*	Proxy-Connection:\ close
	rspirep	^Server:.* Server:\ Tux-2.0
	rspirep	^(Location:\ )([^:]*://[^/]*)(.*) \1\3
	rspidel  ^Connection:
	rspadd	Connection:\ close


4.4) R<>partition avec persistence
---------------------------------

La combinaison de l'insertion de cookie avec la r<>partition de charge interne
permet d'assurer une persistence dans les sessions HTTP d'une mani<6E>re
pratiquement transparente pour les applications. Le principe est simple :
  - attribuer une valeur d'un cookie <20> chaque serveur
  - effectuer une r<>partition interne
  - ins<6E>rer un cookie dans les r<>ponses issues d'une r<>partition uniquement,
    et faire en sorte que des caches ne m<>morisent pas ce cookie.
  - cacher ce cookie <20> l'application lors des requ<71>tes ult<6C>rieures.

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

=======================
| Param<61>trage syst<73>me |
=======================

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

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

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

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

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

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

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

-- cut here --

-- fin --