doc/haproxy.txt

         		     H A - P r o x y
         		     ---------------
         		      version 1.1.8
			      willy tarreau
			       2002/04/16

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

HA-Proxy est un relais TCP/HTTP offrant des facilités d'inté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éation de cookies pour assurer la
    persistence de session ; 
  - fournir une visibilité externe de son état de santé ;
  - s'arrêter en douceur sans perte brutale de service.
  - modifier/ajouter/supprimer des entêtes dans la requête et la réponse.
  - interdire des requêtes qui vérifient certaines conditions.

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


===========================
| Paramètres de lancement |
===========================

Les options de lancement sont peu nombreuses :

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

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

Le nombre maximal total de connexions simultanées limite le nombre de connexions
TCP utilisables à un instant par le processus, tous proxies confondus. Ce
paramètre remplace le paramètre 'maxconn' de la section 'global'.


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

Le fichier de configuration est découpé en sections répérées par des mots clés
tels que :

  - 'global'
  - 'listen'

Tous les paramètres font référence à la section définie par le dernier mot clé
reconnu.


1) Paramètres généraux
======================

Il s'agit des paramètres agissant sur le processus, ou bien sur l'ensemble des
proxies. Ils sont tous spécifiés dans la section 'global'. Les paramètres
supportés sont :

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

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

    log <adresse_ip> <facility>

Les connexions sont envoyées en niveau "info". Les démarrages de service et de
serveurs seront envoyés en "notice", les signaux d'arrêts en "warning" et les
arrêts définitifs de services et de serveurs en "alert". Ceci est valable aussi
bien pour les proxies que pour les serveurs testés au sein des proxies.

Les caté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é 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éral à avoir un peu plus du double de
sessions TCP que le maximum de connexions fixé. C'est important pour fixer le
paramètre 'ulimit -n' avant de lancer le proxy. Pour comptabiliser le nombre
de sockets nécessaires, il faut prendre en compte ces paramè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

Positionner la limite du nombre de descripteurs de fichiers (ulimit -n) à
2 * maxconn + nbproxy + nbserveurs + 1.

1.3) Changement d'uid et de gid
-------------------------------



Serveur
=======

Le fichier de configuration contient des sections repérées par le mot
clé "listen" :

    listen <nom_instance> <adresse_IP>:<port>

<nom_instance> est le nom de l'instance décrite. 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 recommandé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éro de port TCP sur lequel le relais attend ses
connexions. Le couple <adresse_IP>:<port> doit être unique pour toutes
les instances d'une même machine. L'attachement à un port inférieur à
1024 nécessite un niveau de privilège particulier.

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


Inhibition
==========

Un serveur peut être désactivé 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

Mode
====

Un serveur peut fonctionner dans trois modes différents :
  - TCP
  - HTTP
  - supervision

Mode TCP
--------
Dans ce mode, le service relaye, dès 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
<adresse_source:port_source> <adresse_destination:port_destination>.
Pour l'utiliser, pré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êtes HTTP sont analysés pour y trouver
un éventuel cookie, et certains d'entre-eux peuvent être modifiés par
le biais d'expressions régulières. Pour activer ce mode, pré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 à 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
répartiteurs de charge évolués pour déterminer quels sont les services
utilisables. Pour activer ce mode, préciser le mode HEALTH sous la
déclaration du relais :

    listen health_check 0.0.0.0:60000
	mode health


Limitation du nombre de connexions simultanées
==============================================

Le paramètre "maxconn" permet de fixer la limite acceptable en nombre
de connexions simultanées par proxy. Chaque proxy qui atteint cette
valeur cesse d'écouter jusqu'à libération d'une connexion. Voir plus
loin concernant les limitations liées au système. Exemple:

     maxconn 16000


Arrêt en douceur
================

Il est possible d'arrêter les services en douceur en envoyant un
signal SIG_USR1 au processus relais. Tous les services seront alors
mis en phase d'arrêt, mais pourront continuer d'accepter des connexions
pendant un temps défini par le paramètre "grace" (en millisecondes).
Cela permet par exemple, de faire savoir rapidement à 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ées. Dans le pire des cas, il
faudra attendre en plus leur expiration avant l'arrêt total du
processus. La valeur par défaut est 0 (pas de grâce).

Exemple :
---------

    # le service tournera encore 10 secondes après la demande d'arrê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étrer certaines durées d'expiration au niveau
des connexions TCP. Trois temps indépendants sont configurables et
acceptent des valeurs en millisecondes. Si l'une de ces trois
temporisations est dépassée, la session est terminée à chaque
extrémité.

  - temps d'attente d'une donnée de la part du client, ou de la
    possibilité de lui envoyer des données : "clitimeout" :

	# time-out client à 2mn30.
	clitimeout	150000

  - temps d'attente d'une donnée de la part du serveur, ou de la
    possibilité de lui envoyer des données : "srvtimeout" :

	# time-out client à 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 après 3 secondes
	contimeout	3000

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

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 répartition
de charge). Le nombre de nouvelles tentatives infructueuses avant
abandon est fourni par le paramètre "retries" :

	# on essaie encore trois fois maxi
	retries 3

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

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

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

Remarque: ce paramètre n'a pas d'utilité pour un serveur en mode "health".

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ête utilisateur. Le nom du
cookie est donné par le paramè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-à-vis des applications relayées. Il est possible,notamment
de supprimer ou réécrire un cookie retourné par un serveur accédé en direct,
et d'insérer un cookie dans une réponse HTTP orientée vers un serveur
sélectionné en répartition de charge.

Pour ne conserver le cookie qu'en accès indirect, donc à travers le
dispatcheur, et le supprimer lors des accès directs :

	cookie SERVERID indirect

Pour réécrire le nom du serveur dans un cookie lors d'un accès direct :

	cookie SERVERID rewrite

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

	cookie SERVERID insert

Remarque: Il est possible de combiner 'insert' avec 'indirect' ou 'rewrite'
pour s'adapter à des applications générant déjà le cookie, avec un contenu
invalide. Il suffit pour cela de les spécifier sur la même ligne.

Assignation d'un serveur à une valeur de cookie
===============================================

En mode HTTP, il est possible d'associer des serveurs à des valeurs de
cookie par le paramètre "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 (erreurs...).
<adresse_ip>:<port> le couple adresse-port sur lequel le serveur écoute.
<valeur> est la valeur trouvé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é depuis la version 1.0.
---------

Répartiteur de charge interne
=============================

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

Exemple : même que précé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'état des serveurs n'est testé que par é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é dans le processus de répartition de charge
interne. Pour activer la surveillance, ajouter le mot clé 'check' à la
fin de la déclaration du serveur. Il est possible de spécifier
l'intervalle (en millisecondes) séparant deux tests du serveur par le
paramètre "inter", le nombre d'échecs acceptés par le paramètre "fall",
et le nombre de succès avant reprise par le paramètre "rise".
Les paramètres non précisés prennent les valeurs suivantes par défaut :
 - inter : 2000
 - rise  : 2
 - fall  : 3

Exemple : même que précé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'échec direct
=====================================================

En mode HTTP, si un serveur défini par un cookie ne répond plus, les
clients seront définitivement aiguillés dessus à cause de leur cookie,
et de ce fait, définitivement privés de service. La spécification du
paramètre "redispatch" autorise dans ce cas à renvoyer les connexions
échouées vers le répartiteur (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 serveur HS.

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

En mode HTTP, le mot clé "transparent" permet d'intercepter des
sessions routées à travers la machine hébergeant le proxy. Dans
ce mode, on ne précise pas l'adresse de répartition "dispatch",
car celle-ci est tirée de l'adresse destination de la session
détournée. Le systè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 à 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érisent. Ultérieurement, les URLs seront loguées en mode HTTP,
tout comme les arrêts de service. Tous les messages sont envoyé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ées en niveau "info". Les démarrages de
service seront envoyés en "notice", les signaux d'arrêts en "warning"
et les arrêts définitifs en "alert". Ceci est valable aussi bien
pour les proxies que pour les serveurs testés au sein des proxies.

Les caté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êtes HTTP
=============================

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

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

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


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

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


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

<string> représente une chaîne qui sera ajoutée systématiquement après la
dernière ligne d'entête.

Remarques :
---------
  - la première ligne de la requête et celle de la réponse sont traitées comme
    des entêtes, ce qui permet de réécrire 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 supportés mais déconseillés.
  - pour des raisons de performances, le nombre total de caractères ajoutés sur
    une requête ou une réponse 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
    entê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é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ère
pratiquement transparente pour les applications. Le principe est simple :
  - assigner un cookie à chaque serveur
  - effectuer une répartition interne
  - insé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étrage systè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 32768 > /proc/sys/net/ipv4/ip_queue_maxlen
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 --