haproxy/doc/haproxy.txt

         		     H A - P r o x y
         		     ---------------
         		      version 1.1.1
			      willy tarreau
			       2002/03/13

==============
|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 :
  - assurer un aiguillage statique d<>fini par des cookies ;
  - assurer 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.

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<EFBFBD>cis<EFBFBD> dans le fichier de configuration.

Le nombre maximal total de connexions simultan<61>es limite le nombre de
connexions TCP utilisables <20> un instant par le processus, tous proxies
confondus.

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


Commentaires
============

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<70>c<EFBFBD>d<EFBFBD> d'un '\'), et la fin de la ligne.


Serveur
=======

Le fichier de configuration contient des sections rep<65>r<EFBFBD>es par le mot
cl<EFBFBD> "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.

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


Inhibition
==========

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

Mode
====

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<EFBFBD> sur le flux. Il s'agit simplement d'une association
<adresse_source:port_source> <adresse_destination:port_destination>.
Pour l'utiliser, pr<70>ciser le mode TCP sous la d<>claration du relais :

    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<>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<>guli<6C>res. Pour activer ce mode, pr<70>ciser le
mode HTTP sous la d<>claration du relais :

    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<6E> 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<EFBFBD>partiteurs de charge <20>volu<6C>s pour d<>terminer quels sont les services
utilisables. Pour activer ce mode, pr<70>ciser le mode HEALTH sous la
d<EFBFBD>claration du relais :

    listen health_check 0.0.0.0:60000
	mode health


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:

     maxconn 16000


Arr<EFBFBD>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<61>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).

Exemple :
---------

    # 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

    listen health_check 0.0.0.0:60000
	mode health
	grace 0


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<EFBFBD>mit<EFBFBD>.

  - 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 client <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 3 secondes
	contimeout	3000

Remarque: "contimeout" et "srvtimeout" n'ont pas d'utilit<69> dans le cas
du serveur de type "health".

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

	# on essaie encore trois fois maxi
	retries 3

Adresse du serveur
==================

Le serveur vers lequel sont redirig<69>es les connexions est d<>fini par
le param<61>tre "dispatch" sous la forme <adresse_ip>:<port> :

   	# 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".

D<EFBFBD>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" :

    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<><72>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 orient<6E>e vers un serveur
s<EFBFBD>lectionn<EFBFBD> en r<>partition de charge.

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

	cookie SERVERID indirect

Pour r<><72>crire le nom du serveur dans un cookie lors d'un acc<63>s direct :

	cookie SERVERID rewrite

Pour cr<63>er un cookie comportant le nom du serveur lors d'un acc<63>s en
r<EFBFBD>partition de charge interne. Dans ce cas, il est indispensable que tous les
serveurs aient un cookie renseign<67>.

	cookie SERVERID insert

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

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 (erreurs...).
<adresse_ip>:<port> le couple adresse-port sur lequel le serveur <20>coute.
<valeur> est la valeur trouv<75>e 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.
---------

R<EFBFBD>partiteur de charge interne
=============================

Le relais peut effectuer lui-m<>me la r<>partition de charge entre les
diff<EFBFBD>rents serveurs d<>crits 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<EFBFBD>finition du service, <20>ventuellement suivi du nom d'un algorithme de
r<EFBFBD>partition. En version 1.1.0, 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<73>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


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.

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


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<>finitivement priv<69>s de service. La sp<73>cification du
param<EFBFBD>tre "redispatch" autorise dans ce cas <20> renvoyer les connexions
<EFBFBD>chou<EFBFBD>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.

Fonctionnement en mode transparent
==================================

En mode HTTP, le mot cl<63> "transparent" permet d'intercepter des
sessions rout<75>es <20> 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<EFBFBD>tourn<EFBFBD>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

Journalisation des connexions
=============================

Les connexions TCP et HTTP peuvent donner lieu <20> une journalisation
sommaire indiquant, pour chaque connexion, la date, l'heure, les adresses
IP source et destination, et les ports source et destination qui la
caract<EFBFBD>risent. Ult<6C>rieurement, les URLs seront logu<67>es en mode HTTP,
tout comme les arr<72>ts de service. Tous les messages sont envoy<6F>s en
syslog vers un ou deux serveurs. La syntaxe est la suivante :

    log <adresse_ip> <facility>

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<6F>s en "notice", les signaux d'arr<72>ts en "warning"
et les arr<72>ts d<>finitifs en "alert".

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


Modification des ent<6E>tes HTTP
=============================

En mode HTTP uniquement, il est possible de remplacer certains ent<6E>tes
dans la requ<71>te et/ou la r<>ponse <20> partir d'expressions r<>guli<6C>res. Une
limitation cependant : les ent<6E>tes fournis au milieu de connexions
persistentes (keep-alive) ne sont pas vus. Les donn<6E>es ne sont pas
affect<EFBFBD>es, ceci ne s'applique qu'aux ent<6E>tes.

La syntaxe est :
   reqadd <string>             pour ajouter un ent<6E>te dans la requ<71>te
   reqrep <search> <replace>   pour modifier la requ<71>te
   reqrep <search>             pour supprimer un ent<6E>te dans la requ<71>te

   rspadd <string>             pour ajouter un ent<6E>te dans la r<>ponse
   rsprep <search> <replace>   pour modifier la r<>ponse
   rsprep <search>             pour supprimer un ent<6E>te dans la r<>ponse


<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'ent<6E>te.

Remarques :
---------
  - la premi<6D>re ligne de la requ<71>te et celle de la r<>ponse sont trait<69>es comme
    des ent<6E>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> 256. 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
	reqrep	^Proxy-Connection:.*	Proxy-Connection:\ close
	rsprep	^Server:.* Server:\ Tux-2.0
	rsprep	^(Location:\ )([^:]*://[^/]*)(.*) \1\3
	rspdel  ^Connection:.*
	rspadd	Connection:\ close


R<EFBFBD>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 :
  - assigner un cookie <20> chaque serveur
  - effectuer une r<>partition interne
  - ins<6E>rer un cookie dans les r<>ponses issues d'une r<>partition

Exemple :
-------
    listen application 0.0.0.0:80
	mode http
	cookie SERVERID insert 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
==============

echo 131072 > /proc/sys/fs/file-max
echo 65536 > /proc/sys/net/ipv4/ip_conntrack_max
echo 1024 60999 > /proc/sys/net/ipv4/ip_local_port_range
echo 32768 > /proc/sys/net/ipv4/ip_queue_maxlen
echo 60 > /proc/sys/net/ipv4/tcp_fin_timeout
echo 262144 > /proc/sys/net/ipv4/tcp_max_orphans
echo 16384 > /proc/sys/net/ipv4/tcp_max_syn_backlog
echo 262144 > /proc/sys/net/ipv4/tcp_max_tw_buckets
echo 1 > /proc/sys/net/ipv4/tcp_tw_recycle
echo 0 > /proc/sys/net/ipv4/tcp_timestamps
echo 0 > /proc/sys/net/ipv4/tcp_sack
echo 0 > /proc/sys/net/ipv4/tcp_ecn
ulimit -n 131072

-- fin --