blob: 0e367249a5372ff381c32ec084d4362171ef5756 [file] [log] [blame]
willy tarreau0174f312005-12-18 01:02:42 +01001 -------------------
Willy Tarreau94b45912006-05-31 06:40:15 +02002 HAProxy
willy tarreau0174f312005-12-18 01:02:42 +01003 Manuel de référence
4 -------------------
Willy Tarreau2272dc12006-09-03 10:19:38 +02005 version 1.3.2
willy tarreauc5f73ed2005-12-18 01:26:38 +01006 willy tarreau
Willy Tarreau2272dc12006-09-03 10:19:38 +02007 2006/09/03
willy tarreau0f7af912005-12-17 12:21:26 +01008
Willy Tarreaua080eca2009-10-14 20:30:15 +02009
10 !!!! NOTE: CE DOCUMENT EST PERIME !!!!
11
12 Veuillez utiliser le fichier "configuration.txt" situé dans le même
13 répertoire, ou télécharger une version à jour à l'emplacement ci-dessous :
14
Willy Tarreaube6008f2009-10-14 22:22:03 +020015 http://haproxy.1wt.eu/download/1.4/doc/configuration.txt
Willy Tarreaua080eca2009-10-14 20:30:15 +020016
17
willy tarreaub719f002005-12-17 12:55:07 +010018================
19| Introduction |
20================
willy tarreau0f7af912005-12-17 12:21:26 +010021
Willy Tarreau94b45912006-05-31 06:40:15 +020022HAProxy est un relais TCP/HTTP offrant des facilités d'intégration en
willy tarreau0f7af912005-12-17 12:21:26 +010023environnement hautement disponible. En effet, il est capable de :
willy tarreauc29948c2005-12-17 13:10:27 +010024 - effectuer un aiguillage statique défini par des cookies ;
willy tarreau64a3cc32005-12-18 01:13:11 +010025 - effectuer une répartition de charge avec création de cookies pour assurer
26 la persistence de session ;
willy tarreau0f7af912005-12-17 12:21:26 +010027 - fournir une visibilité externe de son état de santé ;
willy tarreau8337c6b2005-12-17 13:41:01 +010028 - s'arrêter en douceur sans perte brutale de service ;
willy tarreauc5f73ed2005-12-18 01:26:38 +010029 - modifier/ajouter/supprimer des en-têtes dans la requête et la réponse ;
willy tarreau8337c6b2005-12-17 13:41:01 +010030 - interdire des requêtes qui vérifient certaines conditions ;
31 - utiliser des serveurs de secours lorsque les serveurs principaux sont hors
32 d'usage.
willy tarreau532bb552006-05-13 18:40:37 +020033 - maintenir des clients sur le bon serveur serveur d'application en fonction
34 de cookies applicatifs.
willy tarreau8f635a42006-05-21 23:05:54 +020035 - fournir des rapports d'état en HTML à des utilisateurs authentifiés, à
36 travers des URI de l'application interceptées.
willy tarreau0f7af912005-12-17 12:21:26 +010037
willy tarreau64a3cc32005-12-18 01:13:11 +010038Il requiert peu de ressources, et son architecture événementielle mono-
39processus lui permet facilement de gérer plusieurs milliers de connexions
40simultanées sur plusieurs relais sans effondrer le système.
willy tarreaua1598082005-12-17 13:08:06 +010041
willy tarreau0f7af912005-12-17 12:21:26 +010042
43===========================
44| Paramètres de lancement |
45===========================
46
47Les options de lancement sont peu nombreuses :
48
49 -f <fichier de configuration>
50 -n <nombre maximal total de connexions simultanées>
willy tarreau532bb552006-05-13 18:40:37 +020051 = 'maxconn' dans la section 'global'
52 -N <nombre maximal de connexions simultanées par instance>
53 = 'maxconn' dans les sections 'listen' ou 'default'
willy tarreau0f7af912005-12-17 12:21:26 +010054 -d active le mode debug
55 -D passe en daemon
Marc-Antoine Perennou992709b2013-02-12 10:53:52 +010056 -Ds passe en daemon systemd
willy tarreau982249e2005-12-18 00:57:06 +010057 -q désactive l'affichage de messages sur la sortie standard.
58 -V affiche les messages sur la sortie standard, même si -q ou 'quiet' sont
59 spécifiés.
60 -c vérifie le fichier de configuration puis quitte avec un code de retour 0
61 si aucune erreur n'a été trouvée, ou 1 si une erreur de syntaxe a été
62 détectée.
willy tarreaufe2c5c12005-12-17 14:14:34 +010063 -p <fichier> indique au processus père qu'il doit écrire les PIDs de ses
64 fils dans ce fichier en mode démon.
willy tarreau34f45302006-04-15 21:37:14 +020065 -sf specifie une liste de PIDs auxquels envoyer un signal FINISH
66 -st specifie une liste de PIDs auxquels envoyer un signal TERMINATE
willy tarreau0f7af912005-12-17 12:21:26 +010067 -s affiche les statistiques (si option compilée)
68 -l ajoute des informations aux statistiques
Willy Tarreaude99e992007-04-16 00:53:59 +020069 -dk désactive l'utilisation de kqueue()
70 -ds désactive l'utilisation de epoll() speculatif
willy tarreau64a3cc32005-12-18 01:13:11 +010071 -de désactive l'utilisation de epoll()
72 -dp désactive l'utilisation de poll()
willy tarreau34f45302006-04-15 21:37:14 +020073 -db désactive la mise en arrière-plan (utile pour débugger)
74 -m <megs> applique une limitation de <megs> Mo d'utilisation mémoire
willy tarreau0f7af912005-12-17 12:21:26 +010075
willy tarreau64a3cc32005-12-18 01:13:11 +010076Le nombre maximal de connexion simultanées par proxy est le paramètre par
77défaut pour les proxies pour lesquels ce paramètre n'est pas précisé dans le
78fichier de configuration. Il s'agit du paramètre 'maxconn' dans les sections
79'listen'.
willy tarreau0f7af912005-12-17 12:21:26 +010080
willy tarreau64a3cc32005-12-18 01:13:11 +010081Le nombre maximal total de connexions simultanées limite le nombre de
82connexions TCP utilisables à un instant donné par le processus, tous proxies
83confondus. Ce paramètre remplace le paramètre 'maxconn' de la section 'global'.
willy tarreaua1598082005-12-17 13:08:06 +010084
willy tarreauc29948c2005-12-17 13:10:27 +010085Le mode debug correspond à l'option 'debug' de la section 'global'. Dans ce
willy tarreauc5f73ed2005-12-18 01:26:38 +010086mode, toutes les connexions, déconnexions, et tous les échanges d'en-têtes HTTP
willy tarreauc29948c2005-12-17 13:10:27 +010087sont affichés.
88
willy tarreau34f45302006-04-15 21:37:14 +020089Pour debugger, l'option '-db' est très pratique car elle désactive
90temporairement le mode daemon et le mode multi-processus. Le service peut alors
91être arrêté par un simple appui sur Ctrl-C, sans avoir à modifier la
92configuration ni à activer le mode debug complet.
93
willy tarreauc29948c2005-12-17 13:10:27 +010094Les statistiques ne sont disponibles que si le programme a été compilé avec
95l'option "STATTIME". Il s'agit principalement de données brutes n'ayant
willy tarreau8f635a42006-05-21 23:05:54 +020096d'utilité que lors de benchmarks par exemple, et sont amenées à disparaitre.
willy tarreauc29948c2005-12-17 13:10:27 +010097
willy tarreau532bb552006-05-13 18:40:37 +020098Les paramètres '-st' et '-sf' sont utilisés pour la reconfiguration à chaud.
99Voir la section à ce sujet.
willy tarreau0f7af912005-12-17 12:21:26 +0100100
101============================
102| Fichier de configuration |
103============================
104
willy tarreauc29948c2005-12-17 13:10:27 +0100105Structure
106=========
willy tarreau0f7af912005-12-17 12:21:26 +0100107
willy tarreaua1598082005-12-17 13:08:06 +0100108L'analyseur du fichier de configuration ignore des lignes vides, les espaces,
willy tarreau64a3cc32005-12-18 01:13:11 +0100109les tabulations, et tout ce qui est compris entre le symbole '#' (s'il n'est
110pas précédé d'un '\'), et la fin de la ligne, ce qui constitue un commentaire.
willy tarreaua1598082005-12-17 13:08:06 +0100111
112Le fichier de configuration est découpé en sections répérées par des mots clés
113tels que :
114
115 - 'global'
116 - 'listen'
willy tarreaua41a8b42005-12-17 14:02:24 +0100117 - 'defaults'
willy tarreaua1598082005-12-17 13:08:06 +0100118
119Tous les paramètres font référence à la section définie par le dernier mot clé
120reconnu.
121
122
willy tarreauc29948c2005-12-17 13:10:27 +01001231) Paramètres globaux
124=====================
willy tarreaua1598082005-12-17 13:08:06 +0100125
126Il s'agit des paramètres agissant sur le processus, ou bien sur l'ensemble des
127proxies. Ils sont tous spécifiés dans la section 'global'. Les paramètres
128supportés sont :
129
willy tarreau8337c6b2005-12-17 13:41:01 +0100130 - log <adresse> <catégorie> [niveau_max]
willy tarreaua1598082005-12-17 13:08:06 +0100131 - maxconn <nombre>
132 - uid <identifiant>
133 - gid <identifiant>
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200134 - user <nom d'utilisateur>
135 - group <nom de groupe>
willy tarreaua1598082005-12-17 13:08:06 +0100136 - chroot <répertoire>
137 - nbproc <nombre>
138 - daemon
139 - debug
Willy Tarreaude99e992007-04-16 00:53:59 +0200140 - nokqueue
willy tarreau64a3cc32005-12-18 01:13:11 +0100141 - noepoll
142 - nopoll
willy tarreaua1598082005-12-17 13:08:06 +0100143 - quiet
willy tarreaufe2c5c12005-12-17 14:14:34 +0100144 - pidfile <fichier>
willy tarreauc5f73ed2005-12-18 01:26:38 +0100145 - ulimit-n <nombre>
Willy Tarreau1db37712007-06-03 17:16:49 +0200146 - tune.maxpollevents <nombre>
willy tarreauc5f73ed2005-12-18 01:26:38 +0100147
willy tarreaua1598082005-12-17 13:08:06 +0100148
1491.1) Journalisation des événements
150----------------------------------
151La plupart des événements sont journalisés : démarrages, arrêts, disparition et
152apparition de serveurs, connexions, erreurs. Tous les messages sont envoyés en
153syslog vers un ou deux serveurs. La syntaxe est la suivante :
154
willy tarreau8337c6b2005-12-17 13:41:01 +0100155 log <adresse_ip> <catégorie> [niveau_max]
willy tarreaua1598082005-12-17 13:08:06 +0100156
157Les connexions sont envoyées en niveau "info". Les démarrages de service et de
158serveurs seront envoyés en "notice", les signaux d'arrêts en "warning" et les
159arrêts définitifs de services et de serveurs en "alert". Ceci est valable aussi
willy tarreau64a3cc32005-12-18 01:13:11 +0100160bien pour les proxies que pour les serveurs testés par les proxies. Le
161paramètre optionnel <niveau_max> définit le niveau maximal de traces émises
162parmi les 8 valeurs suivantes :
willy tarreau8337c6b2005-12-17 13:41:01 +0100163 emerg, alert, crit, err, warning, notice, info, debug
164
willy tarreaueedaa9f2005-12-17 14:08:03 +0100165Par compatibilité avec les versions 1.1.16 et antérieures, la valeur par défaut
willy tarreau8337c6b2005-12-17 13:41:01 +0100166est "debug" si l'option n'est pas précisée.
willy tarreaua1598082005-12-17 13:08:06 +0100167
168Les catégories possibles sont :
169 kern, user, mail, daemon, auth, syslog, lpr, news,
170 uucp, cron, auth2, ftp, ntp, audit, alert, cron2,
171 local0, local1, local2, local3, local4, local5, local6, local7
172
willy tarreau036e1ce2005-12-17 13:46:33 +0100173Conformément à la RFC3164, les messages émis sont limités à 1024 caractères.
174
willy tarreaua1598082005-12-17 13:08:06 +0100175Exemple :
176---------
177 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100178 log 192.168.2.200 local3
179 log 127.0.0.1 local4 notice
willy tarreaua1598082005-12-17 13:08:06 +0100180
1811.2) limitation du nombre de connexions
182---------------------------------------
183Il est possible et conseillé de limiter le nombre global de connexions par
willy tarreauc5f73ed2005-12-18 01:26:38 +0100184processus à l'aide du mot clé global 'maxconn'. Les connexions sont comprises
185au sens 'acceptation de connexion', donc il faut s'attendre en règle général à
186avoir un peu plus du double de sessions TCP que le maximum de connexions fixé.
187C'est important pour fixer le paramètre 'ulimit -n' avant de lancer le proxy.
188Pour comptabiliser le nombre de sockets nécessaires, il faut prendre en compte
189ces paramètres :
190
willy tarreaua1598082005-12-17 13:08:06 +0100191 - 1 socket par connexion entrante
192 - 1 socket par connexion sortante
willy tarreaueedaa9f2005-12-17 14:08:03 +0100193 - 1 socket par couple adresse/port d'écoute par proxy
willy tarreaua1598082005-12-17 13:08:06 +0100194 - 1 socket pour chaque serveur en cours de health-check
willy tarreauc29948c2005-12-17 13:10:27 +0100195 - 1 socket pour les logs (tous serveurs confondus)
willy tarreaua1598082005-12-17 13:08:06 +0100196
willy tarreau64a3cc32005-12-18 01:13:11 +0100197Dans le cas où chaque proxy n'écoute que sur un couple adresse/port,
willy tarreauc5f73ed2005-12-18 01:26:38 +0100198positionner la limite du nombre de descripteurs de fichiers (ulimit -n) à
199(2 * maxconn + nbproxy + nbserveurs + 1). A partir des versions 1.1.32/1.2.6,
200il est possible de spécifier cette limite dans la configuration à l'aide du
201mot-clé global 'ulimit-n', à condition bien entendu que le proxy ait été
202démarré sous le compte root (ou avec des droits suffisants pour élever le
203nombre de descripteurs de fichiers). Cette solution met un terme au problème
204récurrent d'incertitude de l'adéquation entre les limites systèmes lors de la
205dernière relance du proxessus et les limites en nombre de connexions. Noter que
206cette limite s'applique par processus.
207
208Exemple :
209---------
210 global
211 maxconn 32000
212 ulimit-n 65536
213
willy tarreauc29948c2005-12-17 13:10:27 +0100214
2151.3) Diminution des privilèges
216------------------------------
217Afin de réduire les risques d'attaques dans le cas où une faille non identifiée
218serait exploitée, il est possible de diminuer les privilèges du processus, et
willy tarreau8337c6b2005-12-17 13:41:01 +0100219de l'isoler dans un répertoire sans risque.
willy tarreaua1598082005-12-17 13:08:06 +0100220
willy tarreauc29948c2005-12-17 13:10:27 +0100221Dans la section 'global', le paramètre 'uid' permet de spécifier un identifiant
222numérique d'utilisateur. La valeur 0, correspondant normalement au super-
223utilisateur, possède ici une signification particulière car elle indique que
224l'on ne souhaite pas changer cet identifiant et conserver la valeur courante.
225C'est la valeur par défaut. De la même manière, le paramètre 'gid' correspond à
226un identifiant de groupe, et utilise par défaut la valeur 0 pour ne rien
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200227changer. Dans le cas où il ne serait pas possible de spécifier un identifiant
228numérique pour l'uid, il est possible de spécifier un nom d'utilisateur après
229le mot-clé 'user'. De la même manière, il est possible de préciser un nom de
230groupe après le mot-clé 'group'.
231
232Il est particulièrement déconseillé d'utiliser des comptes génériques tels que
233'nobody' car cette pratique revient à utiliser 'root' si d'autres processus
234utilisent les mêmes identifiants.
willy tarreauc29948c2005-12-17 13:10:27 +0100235
236Le paramètre 'chroot' autorise à changer la racine du processus une fois le
237programme lancé, de sorte que ni le processus, ni l'un de ses descendants ne
willy tarreau8337c6b2005-12-17 13:41:01 +0100238puissent remonter de nouveau à la racine. Ce type de cloisonnement (chroot) est
willy tarreaueedaa9f2005-12-17 14:08:03 +0100239généralement contournable sur certains OS (Linux, Solaris) pour peu que
240l'attaquant possède des droits 'root' et soit en mesure d'utiliser ou de créer
241un répertoire. Aussi, il est important d'utiliser un répertoire spécifique au
242service pour cet usage, et de ne pas mutualiser un même répertoire pour
243plusieurs services de nature différente. Pour rendre l'isolement plus robuste,
244il est conseillé d'utiliser un répertoire vide, sans aucun droit, et de changer
245l'uid du processus de sorte qu'il ne puisse rien faire dans ledit répertoire.
willy tarreauc29948c2005-12-17 13:10:27 +0100246
willy tarreau64a3cc32005-12-18 01:13:11 +0100247Remarque importante :
248---------------------
249Dans le cas où une telle faille serait mise en évidence, il est fort probable
250que les premières tentatives de son exploitation provoquent un arrêt du
willy tarreauc29948c2005-12-17 13:10:27 +0100251programme, à cause d'un signal de type 'Segmentation Fault', 'Bus Error' ou
willy tarreau64a3cc32005-12-18 01:13:11 +0100252encore 'Illegal Instruction'. Même s'il est vrai que faire tourner le serveur
253en environnement limité réduit les risques d'intrusion, il est parfois bien
254utile dans ces circonstances de connaître les conditions d'apparition du
255problème, via l'obtention d'un fichier 'core'. La plupart des systèmes, pour
256des raisons de sécurité, désactivent la génération du fichier 'core' après un
257changement d'identifiant pour le processus. Il faudra donc soit lancer le
258processus à partir d'un compte utilisateur aux droits réduits (mais ne pouvant
259pas effectuer le chroot), ou bien le faire en root sans réduction des droits
260(uid 0). Dans ce cas, le fichier se trouvera soit dans le répertoire de
261lancement, soit dans le répertoire spécifié après l'option 'chroot'. Ne pas
262oublier la commande suivante pour autoriser la génération du fichier avant de
263lancer le programme :
willy tarreauc29948c2005-12-17 13:10:27 +0100264
265# ulimit -c unlimited
willy tarreaua1598082005-12-17 13:08:06 +0100266
willy tarreauc29948c2005-12-17 13:10:27 +0100267Exemple :
268---------
269
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200270 # with uid/gid
willy tarreauc29948c2005-12-17 13:10:27 +0100271 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100272 uid 30000
273 gid 30000
274 chroot /var/chroot/haproxy
willy tarreauc29948c2005-12-17 13:10:27 +0100275
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200276 # with user/group
277 global
278 user haproxy
279 group public
280 chroot /var/chroot/haproxy
281
282
willy tarreaufe2c5c12005-12-17 14:14:34 +01002831.4) Modes de fonctionnement
willy tarreauc29948c2005-12-17 13:10:27 +0100284----------------------------
285Le service peut fonctionner dans plusieurs modes :
286 - avant- / arrière-plan
287 - silencieux / normal / debug
willy tarreau0f7af912005-12-17 12:21:26 +0100288
willy tarreau64a3cc32005-12-18 01:13:11 +0100289Le mode par défaut est normal, avant-plan, c'est à dire que le programme ne
290rend pas la main une fois lancé. Il ne faut surtout pas le lancer comme ceci
291dans un script de démarrage du système, sinon le système ne finirait pas son
willy tarreauc29948c2005-12-17 13:10:27 +0100292initialisation. Il faut le mettre en arrière-plan, de sorte qu'il rende la main
293au processus appelant. C'est ce que fait l'option 'daemon' de la section
294'global', et qui est l'équivalent du paramètre '-D' de la ligne de commande.
willy tarreau0f7af912005-12-17 12:21:26 +0100295
willy tarreau34f45302006-04-15 21:37:14 +0200296Le paramètre de ligne de commande '-db' inhibe les options globales 'daemon'
297et 'nbproc' pour faire fonctionner le processus en mode normal, avant-plan.
298
willy tarreauc29948c2005-12-17 13:10:27 +0100299Par ailleurs, certains messages d'alerte sont toujours envoyés sur la sortie
300standard, même en mode 'daemon'. Pour ne plus les voir ailleurs que dans les
301logs, il suffit de passer en mode silencieux par l'ajout de l'option 'quiet'.
302Cette option n'a pas d'équivalent en ligne de commande.
willy tarreau0f7af912005-12-17 12:21:26 +0100303
willy tarreauc29948c2005-12-17 13:10:27 +0100304Enfin, le mode 'debug' permet de diagnostiquer les origines de certains
305problèmes en affichant les connexions, déconnexions et échanges d'en-têtes HTTP
306entre les clients et les serveurs. Ce mode est incompatible avec les options
307'daemon' et 'quiet' pour des raisons de bon sens.
308
willy tarreaufe2c5c12005-12-17 14:14:34 +01003091.5) Accroissement de la capacité de traitement
willy tarreauc29948c2005-12-17 13:10:27 +0100310-----------------------------------------------
311Sur des machines multi-processeurs, il peut sembler gâché de n'utiliser qu'un
312processeur pour effectuer les tâches de relayage, même si les charges
313nécessaires à saturer un processeur actuel sont bien au-delà des ordres de
314grandeur couramment rencontrés. Cependant, pour des besoins particuliers, le
315programme sait démarrer plusieurs processus se répartissant la charge de
316travail. Ce nombre de processus est spécifié par le paramètre 'nbproc' de la
317section 'global'. Sa valeur par défaut est naturellement 1. Ceci ne fonctionne
willy tarreau4302f492005-12-18 01:00:37 +0100318qu'en mode 'daemon'. Un usage déjà rencontré pour ce paramètre fut de dépasser
319la limite de nombre de descripteurs de fichiers allouée par processus sous
320Solaris.
willy tarreauc29948c2005-12-17 13:10:27 +0100321
322Exemple :
323---------
324
325 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100326 daemon
327 quiet
328 nbproc 2
willy tarreauc29948c2005-12-17 13:10:27 +0100329
willy tarreaufe2c5c12005-12-17 14:14:34 +01003301.6) Simplification de la gestion des processus
331-----------------------------------------------
332Haproxy supporte dorénavant la notion de fichiers de pid (-> pidfiles). Si le
333paramètre '-p' de ligne de commande, ou l'option globale 'pidfile' sont suivis
334d'un nom de fichier, alors ce fichier sera supprimé puis recréé et contiendra
335le numéro de PID des processus fils, à raison d'un par ligne (valable
336uniquement en mode démon). Ce fichier n'est PAS relatif au cloisonnement chroot
337afin de rester compatible avec un répertoire protégé en lecture seule. Il
338appartiendra à l'utilisateur ayant lancé le processus, et disposera des droits
3390644.
340
341Exemple :
342---------
343
344 global
345 daemon
346 quiet
347 nbproc 2
348 pidfile /var/run/haproxy-private.pid
349
350 # pour stopper seulement ces processus parmi d'autres :
351 # kill $(</var/run/haproxy-private.pid)
352
willy tarreau34f45302006-04-15 21:37:14 +0200353 # pour recharger une configuration avec un impact minimal sur le service,
354 # et sans casser les sessions existantes :
Willy Tarreau10806d52007-09-09 23:49:18 +0200355 # haproxy -f haproxy.cfg -p /var/run/haproxy-private.pid -sf $(</var/run/haproxy-private.pid)
willy tarreauc29948c2005-12-17 13:10:27 +0100356
willy tarreau64a3cc32005-12-18 01:13:11 +01003571.7) Mécanismes de traitements des événements
358---------------------------------------------
359A partir de la version 1.2.5, haproxy supporte les mécanismes poll() et
360epoll(). Sur les systems où select() est limité par FD_SETSIZE (comme Solaris),
361poll() peut être une alternative intéressante. Des tests de performance
362montrent que les performances de poll() ne décroissent pas aussi vite que le
363nombre de sockets augmente, ce qui en fait une solution sûre pour les fortes
364charges. Cela dit, Soalris utilise déjà poll() pour émuler select(), donc tant
365que le nombre de sockets ne dépasse pas FD_SETSIZE, poll() ne devrait pas
366apporter de performances supplémentaires. Sur les systèmes à base Linux
367incluant le patch epoll() (ou tous les Linux 2.6), haproxy utilisera epoll()
368qui est extrèmement rapide indépendamment du nombre de sockets. Les tests sur
369haproxy ont montré une performance constante de 1 à 40000 sessions simultanées.
Willy Tarreaude99e992007-04-16 00:53:59 +0200370La version 1.3.9 a introduit le support de kqueue() pour FreeBSD/OpenBSD, ainsi
371qu'une variante appelée "speculative epoll()" consistant à tenter d'effectuer
372les opérations d'entrées/sorties avant de chaîner les événements par les appels
373système.
willy tarreau64a3cc32005-12-18 01:13:11 +0100374
Willy Tarreau1db37712007-06-03 17:16:49 +0200375Afin d'optimiser la latence, il est désormais possible de limiter le nombre
376d'événements remontés à chaque appel. La limite par défaut est fixée à 200. Si
377une latence plus petite est recherchée, il peut être justifié d'abaisser cette
378limite par l'utilisation du paramètre 'tune.maxpollevents' dans la section
379'global'. L'augmenter permettra d'économiser un peu le processeur en présence
380de très grands nombres de connexions simultanées.
381
Willy Tarreaude99e992007-04-16 00:53:59 +0200382Haproxy utilisera kqueue() ou speculative epoll() lorsque ce sera disponible,
383puis epoll(), et se repliera sur poll(), puis en dernier lieu sur select().
384Cependant, si pour une raison quelconque il s'avérait nécessaire de désactiver
385epoll() ou poll() (p.ex: à cause d'un bug ou juste pour comparer les
386performances), de nouvelles options globales ont été ajoutées dans ce but :
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100387'nokqueue', 'noepoll' et 'nopoll'.
willy tarreau64a3cc32005-12-18 01:13:11 +0100388
389Exemple :
390---------
391 global
392 # utiliser seulement select()
393 noepoll
394 nopoll
Willy Tarreau1db37712007-06-03 17:16:49 +0200395 tune.maxpollevents 100
willy tarreau64a3cc32005-12-18 01:13:11 +0100396
397Remarque :
398----------
399Dans le but d'assurer une portabilité maximale des configurations, ces options
400sont acceptées et ignorées si les mécanismes poll() ou epoll() n'ont pas été
401activés lors de la compilation.
402
403Afin de simplifier la résolution de problèmes, le paramètre '-de' en ligne de
Willy Tarreaude99e992007-04-16 00:53:59 +0200404commande désactive epoll(), le paramètre '-dp' désactive poll(), '-dk' kqueue()
405et '-ds' désactive speculative epoll(). Ils sont respectivement équivalents à
Willy Tarreaue9f49e72012-11-11 17:42:00 +0100406'noepoll', 'nopoll', et 'nokqueue'.
willy tarreau64a3cc32005-12-18 01:13:11 +0100407
408
willy tarreauc29948c2005-12-17 13:10:27 +01004092) Définition d'un service en écoute
410====================================
411
412Les sections de service débutent par le mot clé "listen" :
willy tarreau0f7af912005-12-17 12:21:26 +0100413
willy tarreaua41a8b42005-12-17 14:02:24 +0100414 listen <nom_instance> [ <adresse_IP>:<plage_ports>[,...] ]
willy tarreau0f7af912005-12-17 12:21:26 +0100415
willy tarreauc29948c2005-12-17 13:10:27 +0100416- <nom_instance> est le nom de l'instance décrite. Ce nom sera envoyé dans les
willy tarreau64a3cc32005-12-18 01:13:11 +0100417 logs, donc il est souhaitable d'utiliser un nom relatif au service relayé.
418 Aucun test n'est effectué concernant l'unicité de ce nom, qui n'est pas
419 obligatoire, mais fortement recommandée.
willy tarreau0f7af912005-12-17 12:21:26 +0100420
willy tarreaua41a8b42005-12-17 14:02:24 +0100421- <adresse_IP> est l'adresse IP sur laquelle le relais attend ses connexions.
422 L'absence d'adresse ainsi que l'adresse 0.0.0.0 signifient que les connexions
423 pourront s'effectuer sur toutes les adresses de la machine.
willy tarreau0f7af912005-12-17 12:21:26 +0100424
willy tarreaua41a8b42005-12-17 14:02:24 +0100425- <plage_ports> correspond soit à un port, soit à une plage de ports sur
426 lesquels le relais acceptera des connexions pour l'adresse IP spécifiée.
427 Cette plage peut être :
428 - soit un port numérique (ex: '80')
429 - soit une plage constituée de deux valeurs séparées par un tiret
430 (ex: '2000-2100') représentant les extrémités incluses dans la
431 plage.
432 Il faut faire attention à l'usage des plages, car chaque combinaison
433 <adresse_IP>:<port> consomme une socket, donc un descripteur de fichier.
434 Le couple <adresse_IP>:<port> doit être unique pour toutes les instances
435 d'une même machine. L'attachement à un port inférieur à 1024 nécessite un
willy tarreau64a3cc32005-12-18 01:13:11 +0100436 niveau de privilège particulier lors du lancement du programme
437 (indépendamment du paramètre 'uid' de la section 'global').
willy tarreau0f7af912005-12-17 12:21:26 +0100438
willy tarreaua41a8b42005-12-17 14:02:24 +0100439- le couple <adresse_IP>:<plage_ports> peut être répété indéfiniment pour
440 demander au relais d'écouter également sur d'autres adresses et/ou d'autres
441 plages de ports. Pour cela, il suffit de séparer les couples par une virgule.
442
443Exemples :
willy tarreau0f7af912005-12-17 12:21:26 +0100444---------
willy tarreaua41a8b42005-12-17 14:02:24 +0100445 listen http_proxy :80
446 listen x11_proxy 127.0.0.1:6000-6009
447 listen smtp_proxy 127.0.0.1:25,127.0.0.1:587
448 listen ldap_proxy :389,:663
willy tarreau0f7af912005-12-17 12:21:26 +0100449
willy tarreaua41a8b42005-12-17 14:02:24 +0100450Si toutes les adresses ne tiennent pas sur une ligne, il est possible d'en
451rajouter à l'aide du mot clé 'bind'. Dans ce cas, il n'est même pas nécessaire
452de spécifier la première adresse sur la ligne listen, ce qui facilite parfois
453l'écriture de configurations :
454
455 bind [ <adresse_IP>:<plage_ports>[,...] ]
456
457Exemples :
458----------
459 listen http_proxy
460 bind :80,:443
willy tarreauc5f73ed2005-12-18 01:26:38 +0100461 bind 10.0.0.1:10080,10.0.0.1:10443
willy tarreau0f7af912005-12-17 12:21:26 +0100462
willy tarreauc29948c2005-12-17 13:10:27 +01004632.1) Inhibition d'un service
464----------------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +0100465Un service peut être désactivé pour des besoins de maintenance, sans avoir à
willy tarreauc29948c2005-12-17 13:10:27 +0100466commenter toute une partie du fichier. Il suffit de positionner le mot clé
467"disabled" dans sa section :
willy tarreau0f7af912005-12-17 12:21:26 +0100468
469 listen smtp_proxy 0.0.0.0:25
willy tarreauc5f73ed2005-12-18 01:26:38 +0100470 disabled
willy tarreau0f7af912005-12-17 12:21:26 +0100471
willy tarreaueedaa9f2005-12-17 14:08:03 +0100472Remarque: le mot clé 'enabled' permet de réactiver un service préalablement
willy tarreauc5f73ed2005-12-18 01:26:38 +0100473 désactivé par le mot clé 'disabled', par exemple à cause d'une
474 configuration par défaut.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100475
willy tarreauc29948c2005-12-17 13:10:27 +01004762.2) Mode de fonctionnement
477---------------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +0100478Un service peut fonctionner dans trois modes différents :
willy tarreau0f7af912005-12-17 12:21:26 +0100479 - TCP
480 - HTTP
willy tarreau532bb552006-05-13 18:40:37 +0200481 - état de santé
willy tarreau0f7af912005-12-17 12:21:26 +0100482
483Mode TCP
484--------
willy tarreau64a3cc32005-12-18 01:13:11 +0100485Dans ce mode, le service relaye, dès leur établissement, les connexions TCP
486vers un ou plusieurs serveurs. Aucun traitement n'est effectué sur le flux. Il
487s'agit simplement d'une association
488 source<adresse:port> -> destination<adresse:port>.
willy tarreauc29948c2005-12-17 13:10:27 +0100489Pour l'utiliser, préciser le mode TCP sous la déclaration du relais.
willy tarreau0f7af912005-12-17 12:21:26 +0100490
willy tarreauc29948c2005-12-17 13:10:27 +0100491Exemple :
492---------
willy tarreau0f7af912005-12-17 12:21:26 +0100493 listen smtp_proxy 0.0.0.0:25
willy tarreauc5f73ed2005-12-18 01:26:38 +0100494 mode tcp
willy tarreau0f7af912005-12-17 12:21:26 +0100495
496Mode HTTP
497---------
willy tarreauc29948c2005-12-17 13:10:27 +0100498Dans ce mode, le service relaye les connexions TCP vers un ou plusieurs
499serveurs, une fois qu'il dispose d'assez d'informations pour en prendre la
willy tarreauc5f73ed2005-12-18 01:26:38 +0100500décision. Les en-têtes HTTP sont analysés pour y trouver un éventuel cookie, et
willy tarreauc29948c2005-12-17 13:10:27 +0100501certains d'entre-eux peuvent être modifiés par le biais d'expressions
502régulières. Pour activer ce mode, préciser le mode HTTP sous la déclaration du
503relais.
willy tarreau0f7af912005-12-17 12:21:26 +0100504
willy tarreauc29948c2005-12-17 13:10:27 +0100505Exemple :
506---------
willy tarreau0f7af912005-12-17 12:21:26 +0100507 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100508 mode http
willy tarreau0f7af912005-12-17 12:21:26 +0100509
510Mode supervision
511----------------
willy tarreauc29948c2005-12-17 13:10:27 +0100512Il s'agit d'un mode offrant à un composant externe une visibilité de l'état de
513santé du service. Il se contente de retourner "OK" à tout client se connectant
514sur son port. Il peut être utilisé avec des répartiteurs de charge évolués pour
willy tarreau197e8ec2005-12-17 14:10:59 +0100515déterminer quels sont les services utilisables. Si l'option 'httpchk' est
516activée, alors la réponse changera en 'HTTP/1.0 200 OK' pour satisfaire les
517attentes de composants sachant tester en HTTP. Pour activer ce mode, préciser
willy tarreauc29948c2005-12-17 13:10:27 +0100518le mode HEALTH sous la déclaration du relais.
willy tarreau0f7af912005-12-17 12:21:26 +0100519
willy tarreauc29948c2005-12-17 13:10:27 +0100520Exemple :
521---------
willy tarreau197e8ec2005-12-17 14:10:59 +0100522 # réponse simple : 'OK'
willy tarreau0f7af912005-12-17 12:21:26 +0100523 listen health_check 0.0.0.0:60000
willy tarreauc5f73ed2005-12-18 01:26:38 +0100524 mode health
willy tarreau0f7af912005-12-17 12:21:26 +0100525
willy tarreau197e8ec2005-12-17 14:10:59 +0100526 # réponse HTTP : 'HTTP/1.0 200 OK'
527 listen http_health_check 0.0.0.0:60001
willy tarreauc5f73ed2005-12-18 01:26:38 +0100528 mode health
529 option httpchk
willy tarreau197e8ec2005-12-17 14:10:59 +0100530
willy tarreau0f7af912005-12-17 12:21:26 +0100531
willy tarreau532bb552006-05-13 18:40:37 +02005322.2.1 Supervision
533-----------------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100534Les versions 1.1.32 et 1.2.6 apportent une nouvelle solution pour valider le
535bon fonctionnement du proxy sans perturber le service. Le mot-clé 'monitor-net'
536a été créé dans le butd de spécifier un réseau d'équipements qui ne PEUVENT PAS
537utiliser le service pour autre chose que des tests de fonctionnement. C'est
538particulièrement adapté aux proxies TCP, car cela empêche le proxy de relayer
539des établissements de connexion émis par un outil de surveillance.
540
541Lorsque c'est utilisé sur un proxy TCP, la connexion est acceptée puis refermée
542et rien n'est logué. C'est suffisant pour qu'un répartiteur de charge en amont
543détecte que le service est disponible.
544
545Lorsque c'est utilisé sur un proxy HTTP, la connexion est acceptée, rien n'est
546logué, puis la réponse suivante est envoyée et la session refermée :
547"HTTP/1.0 200 OK". C'est normalement suffisant pour qu'un répartiteur de charge
548HTTP en amont détecte le service comme opérationnel, aussi bien à travers des
549tests TCP que HTTP.
550
551Les proxies utilisant le mot-clé 'monitor-net' peuvent accessoirement se passer
552de l'option 'dontlognull', ce qui permettra de loguer les connexions vides
553émises depuis d'autres adresses que celles du réseau de tests.
554
555Exemple :
556---------
557
558 listen tse-proxy
559 bind :3389,:1494,:5900 # TSE, ICA and VNC at once.
560 mode tcp
561 balance roundrobin
562 server tse-farm 192.168.1.10
563 monitor-net 192.168.1.252/31 # L4 load-balancers on .252 and .253
564
565
Willy Tarreau1c47f852006-07-09 08:22:27 +0200566Lorsque le système effectuant les tests est situé derrière un proxy, le mot-clé
567'monitor-net' n'est pas utilisable du fait que haproxy verra toujours la même
568adresse pour le proxy. Pour pallier à cette limitation, la version 1.2.15 a
569apporté le mot-clé 'monitor-uri'. Il définit une URI qui ne sera ni retransmise
570ni logée, mais pour laquelle haproxy retournera immédiatement une réponse
571"HTTP/1.0 200 OK". Cela rend possibles les tests de validité d'une chaîne
572reverse-proxy->haproxy en une requête HTTP. Cela peut être utilisé pour valider
573une combinaision de stunnel+haproxy à l'aide de tests HTTPS par exemple. Bien
574entendu, ce mot-clé n'est valide qu'en mode HTTP, sinon il n'y a pas de notion
575d'URI. Noter que la méthode et la version HTTP sont simplement ignorées.
576
577Exemple :
578---------
579
580 listen stunnel_backend :8080
581 mode http
582 balance roundrobin
583 server web1 192.168.1.10:80 check
584 server web2 192.168.1.11:80 check
585 monitor-uri /haproxy_test
586
587
willy tarreauc29948c2005-12-17 13:10:27 +01005882.3) Limitation du nombre de connexions simultanées
589---------------------------------------------------
590Le paramètre "maxconn" permet de fixer la limite acceptable en nombre de
591connexions simultanées par proxy. Chaque proxy qui atteint cette valeur cesse
592d'écouter jusqu'à libération d'une connexion. Voir plus loin concernant les
593limitations liées au système.
willy tarreau0f7af912005-12-17 12:21:26 +0100594
willy tarreauc29948c2005-12-17 13:10:27 +0100595Exemple :
596---------
597 listen tiny_server 0.0.0.0:80
598 maxconn 10
willy tarreau0f7af912005-12-17 12:21:26 +0100599
600
willy tarreauc29948c2005-12-17 13:10:27 +01006012.4) Arrêt en douceur
602---------------------
willy tarreau64a3cc32005-12-18 01:13:11 +0100603Il est possible d'arrêter les services en douceur en envoyant un signal
willy tarreau22739ef2006-01-20 20:43:32 +0100604SIGUSR1 au processus relais. Tous les services seront alors mis en phase
willy tarreau64a3cc32005-12-18 01:13:11 +0100605d'arrêt, mais pourront continuer d'accepter des connexions pendant un temps
606défini par le paramètre 'grace' (en millisecondes). Cela permet par exemple,
607de faire savoir rapidement à un répartiteur de charge qu'il ne doit plus
608utiliser un relais, tout en continuant d'assurer le service le temps qu'il
609s'en rende compte.
610
611Remarque :
612----------
613Les connexions actives ne sont jamais cassées. Dans le pire des cas, il faudra
willy tarreau22739ef2006-01-20 20:43:32 +0100614attendre en plus leur expiration avant l'arrêt total du processus, ou bien tuer
615manuellement le processus par l'envoi d'un signal SIGTERM. La valeur par défaut
616du paramètre 'grace' est 0 (pas de grâce, arrêt immédiat de l'écoute).
willy tarreau0f7af912005-12-17 12:21:26 +0100617
618Exemple :
619---------
willy tarreauc29948c2005-12-17 13:10:27 +0100620 # arrêter en douceur par 'killall -USR1 haproxy'
willy tarreau0f7af912005-12-17 12:21:26 +0100621 # le service tournera encore 10 secondes après la demande d'arrêt
622 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100623 mode http
624 grace 10000
willy tarreau0f7af912005-12-17 12:21:26 +0100625
willy tarreauc29948c2005-12-17 13:10:27 +0100626 # ce port n'est testé que par un répartiteur de charge.
willy tarreau0f7af912005-12-17 12:21:26 +0100627 listen health_check 0.0.0.0:60000
willy tarreauc5f73ed2005-12-18 01:26:38 +0100628 mode health
629 grace 0
willy tarreau0f7af912005-12-17 12:21:26 +0100630
willy tarreau39df2dc2006-01-29 21:56:05 +0100631A partir de la version 1.2.8, un nouveau mécanisme de reconfiguration à chaud
willy tarreau22739ef2006-01-20 20:43:32 +0100632a été introduit. Il est désormais possible de mettre les proxies en "pause" en
633envoyant un signal SIGTTOU aux processus. Cela désactivera les sockets d'écoute
634sans casser les sessions existantes. Suite à cela, l'envoi d'un signal SIGTTIN
635réactivera les sockets d'écoute. Ceci est très pratique pour tenter de charger
636une nouvelle configuration ou même une nouvelle version de haproxy sans casser
637les connexions existantes. Si le rechargement s'effectue correctement, il ne
638reste plus qu'à envoyer un signal SIGUSR1 aux anciens processus, ce qui
639provoquera leur arrêt immédiat dès que leurs connexions seront terminées ; en
640revanche, si le rechargement échoue, il suffit d'envoyer un signal SIGTTIN pour
641remettre les ports en écoute et rétablir le service immédiatement. Veuillez
642noter que le paramètre 'grace' est ignoré pour le signal SIGTTOU ainsi que le
643signal SIGUSR1 une fois le processus en pause. Aussi, il peut s'avérer très
644utile de sauver le fichier de pid avant de démarrer une nouvelle instance.
645
willy tarreau34f45302006-04-15 21:37:14 +0200646Ce mécanisme est pleinement exploité à partir de la version 1.2.11 avec les
willy tarreau532bb552006-05-13 18:40:37 +0200647options '-st' et '-sf' (voir ci-dessous).
648
6492.4) Reconfiguration à chaud
650----------------------------
651Les paramètres '-st' et '-sf' sont utilisés pour informer des processus
652existants que la configuration va être rechargée. Ils recevront le signal
653SIGTTOU, leur demandant de libérer les ports en écoute afin que le nouveau
654processus puisse les prendre. Si quoi que ce soit se passe mal, le nouveau
655processus leur enverra un signal SIGTTIN pour leur indiquer qu'ils peuvent
656se remettre en écoute et continuer leur travail. En revanche, si la
657configuration se charge correctement, alors ils recevront un signal de demande
658de fin de travail en douceur (-sf), ou de terminaison immédiate (-st) qui
659coupera les sessions en cours. Un usage typique tel que celui-ci permet de
660recharger une configuration sans interruption de service :
661
662 # haproxy -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)
663
willy tarreau0f7af912005-12-17 12:21:26 +0100664
willy tarreauc29948c2005-12-17 13:10:27 +01006652.5) Temps d'expiration des connexions
666--------------------------------------
667Il est possible de paramétrer certaines durées d'expiration au niveau des
668connexions TCP. Trois temps indépendants sont configurables et acceptent des
669valeurs en millisecondes. Si l'une de ces trois temporisations est dépassée, la
670session est terminée à chaque extrémité.
willy tarreau0f7af912005-12-17 12:21:26 +0100671
672 - temps d'attente d'une donnée de la part du client, ou de la
673 possibilité de lui envoyer des données : "clitimeout" :
674
willy tarreauc5f73ed2005-12-18 01:26:38 +0100675 # time-out client à 2mn30.
676 clitimeout 150000
willy tarreau0f7af912005-12-17 12:21:26 +0100677
678 - temps d'attente d'une donnée de la part du serveur, ou de la
679 possibilité de lui envoyer des données : "srvtimeout" :
680
willy tarreauc5f73ed2005-12-18 01:26:38 +0100681 # time-out serveur à 30s.
682 srvtimeout 30000
willy tarreau0f7af912005-12-17 12:21:26 +0100683
684 - temps d'attente de l'établissement d'une connexion vers un serveur
685 "contimeout" :
686
willy tarreauc29948c2005-12-17 13:10:27 +0100687 # on abandonne si la connexion n'est pas établie après 4 secondes
willy tarreauc5f73ed2005-12-18 01:26:38 +0100688 contimeout 4000
willy tarreau0f7af912005-12-17 12:21:26 +0100689
willy tarreauc29948c2005-12-17 13:10:27 +0100690Remarques :
691-----------
692 - "contimeout" et "srvtimeout" n'ont pas d'utilité dans le cas du serveur de
693 type "health".
694 - sous de fortes charges, ou sur un réseau saturé ou défectueux, il est
willy tarreau64a3cc32005-12-18 01:13:11 +0100695 possible de perdre des paquets. Du fait que la première retransmission
696 TCP n'ait lieu qu'au bout de 3 secoudes, fixer un timeout de connexion
697 inférieur à 3 secondes ne permet pas de se rattraper sur la perte
698 de paquets car la session aura été abandonnée avant la première
699 retransmission. Une valeur de 4 secondes réduira considérablement
700 le nombre d'échecs de connexion.
Willy Tarreaubefdff12007-12-02 22:27:38 +0100701 - A compter de la version 1.3.14, il est possible de spécifier les durées
702 d'expiration dans des unités de temps arbitraires à choisir parmi
703 { us, ms, s, m, h, d }. Pour cela, la valeur entière doit être suffixée
704 de l'unité.
willy tarreau0f7af912005-12-17 12:21:26 +0100705
willy tarreauc29948c2005-12-17 13:10:27 +01007062.6) Tentatives de reconnexion
707------------------------------
willy tarreau0f7af912005-12-17 12:21:26 +0100708Lors d'un échec de connexion vers un serveur, il est possible de
709retenter (potentiellement vers un autre serveur, en cas de répartition
710de charge). Le nombre de nouvelles tentatives infructueuses avant
willy tarreauc29948c2005-12-17 13:10:27 +0100711abandon est fourni par le paramètre "retries".
willy tarreau0f7af912005-12-17 12:21:26 +0100712
willy tarreauc29948c2005-12-17 13:10:27 +0100713Exemple :
714---------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100715 # on essaie encore trois fois maxi
716 retries 3
willy tarreau0f7af912005-12-17 12:21:26 +0100717
willy tarreau34f45302006-04-15 21:37:14 +0200718Il est à noter que la tentative de reconnexion peut amener à utiliser un autre
719serveur si le premier a disparu entre deux tentatives de connexion.
720
willy tarreau0f7af912005-12-17 12:21:26 +0100721
willy tarreauc29948c2005-12-17 13:10:27 +01007222.7) Adresse du serveur
723-----------------------
724Le serveur vers lequel sont redirigées les nouvelles connexions est défini par
725le paramètre "dispatch" sous la forme <adresse_ip>:<port>. Il correspond à un
726serveur d'assignation de cookie dans le cas où le service consiste à assurer
727uniquement une persistence HTTP, ou bien simplement au serveur destination dans
willy tarreaua41a8b42005-12-17 14:02:24 +0100728le cas de relayage TCP simple. Cet ancien mode ne permet pas de tester l'état
729du serveur distant, et il est maintenant recommandé d'utiliser de préférence
730le mode 'balance'.
willy tarreau0f7af912005-12-17 12:21:26 +0100731
willy tarreauc29948c2005-12-17 13:10:27 +0100732Exemple :
733---------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100734 # on envoie toutes les nouvelles connexions ici
735 dispatch 192.168.1.2:80
willy tarreau0f7af912005-12-17 12:21:26 +0100736
willy tarreauc29948c2005-12-17 13:10:27 +0100737Remarque :
738----------
739Ce paramètre n'a pas d'utilité pour un serveur en mode 'health', ni en mode
740'balance'.
willy tarreau0f7af912005-12-17 12:21:26 +0100741
willy tarreau0f7af912005-12-17 12:21:26 +0100742
willy tarreau240afa62005-12-17 13:14:35 +01007432.8) Adresse de sortie
744----------------------
willy tarreaua41a8b42005-12-17 14:02:24 +0100745Il est possible de forcer l'adresse utilisée pour établir les connexions vers
746les serveurs à l'aide du paramètre "source". Il est même possible de forcer le
747port, bien que cette fonctionnalité se limite à des usages très spécifiques.
748C'est particulièrement utile en cas d'adressage multiple, et plus généralement
willy tarreau64a3cc32005-12-18 01:13:11 +0100749pour permettre aux serveurs de trouver le chemin de retour dans des contextes
750de routage difficiles. Si l'adresse est '0.0.0.0' ou '*' ou vide, elle sera
751choisie librement par le systeme. Si le port est '0' ou vide, il sera choisi
752librement par le système. Il est à noter que depuis la version 1.1.18, les
753tests de bon fonctionnement des serveurs seront aussi effectués à partir de la
754source spécifiée par ce paramètre.
willy tarreau240afa62005-12-17 13:14:35 +0100755
756Exemples :
757----------
willy tarreaua41a8b42005-12-17 14:02:24 +0100758 listen http_proxy *:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100759 # toutes les connexions prennent l'adresse 192.168.1.200
760 source 192.168.1.200:0
willy tarreau240afa62005-12-17 13:14:35 +0100761
willy tarreaua41a8b42005-12-17 14:02:24 +0100762 listen rlogin_proxy *:513
willy tarreauc5f73ed2005-12-18 01:26:38 +0100763 # utiliser l'adresse 192.168.1.200 et le port réservé 900
764 source 192.168.1.200:900
willy tarreau240afa62005-12-17 13:14:35 +0100765
766
7672.9) Définition du nom du cookie
willy tarreauc29948c2005-12-17 13:10:27 +0100768--------------------------------
769En mode HTTP, il est possible de rechercher la valeur d'un cookie pour savoir
770vers quel serveur aiguiller la requête utilisateur. Le nom du cookie est donné
771par le paramètre "cookie".
willy tarreau0f7af912005-12-17 12:21:26 +0100772
willy tarreauc29948c2005-12-17 13:10:27 +0100773Exemple :
774---------
willy tarreaua41a8b42005-12-17 14:02:24 +0100775 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100776 mode http
777 cookie SERVERID
willy tarreau0f7af912005-12-17 12:21:26 +0100778
willy tarreauc29948c2005-12-17 13:10:27 +0100779On peut modifier l'utilisation du cookie pour la rendre plus intelligente
780vis-à-vis des applications relayées. Il est possible, notamment de supprimer ou
781réécrire un cookie retourné par un serveur accédé en direct, et d'insérer un
782cookie dans une réponse HTTP adressée à un serveur sélectionné en répartition
willy tarreau240afa62005-12-17 13:14:35 +0100783de charge, et même de signaler aux proxies amont de ne pas cacher le cookie
784inséré.
willy tarreauc29948c2005-12-17 13:10:27 +0100785
786Exemples :
787----------
willy tarreau5cbea6f2005-12-17 12:48:26 +0100788
789Pour ne conserver le cookie qu'en accès indirect, donc à travers le
willy tarreauc29948c2005-12-17 13:10:27 +0100790dispatcheur, et supprimer toutes ses éventuelles occurences lors des accès
791directs :
willy tarreau5cbea6f2005-12-17 12:48:26 +0100792
willy tarreauc5f73ed2005-12-18 01:26:38 +0100793 cookie SERVERID indirect
willy tarreau5cbea6f2005-12-17 12:48:26 +0100794
willy tarreauc29948c2005-12-17 13:10:27 +0100795Pour remplacer la valeur d'un cookie existant par celle attribuée à un serveur,
796lors d'un accès direct :
willy tarreau5cbea6f2005-12-17 12:48:26 +0100797
willy tarreauc5f73ed2005-12-18 01:26:38 +0100798 cookie SERVERID rewrite
willy tarreau5cbea6f2005-12-17 12:48:26 +0100799
willy tarreau64a3cc32005-12-18 01:13:11 +0100800Pour créer un cookie comportant la valeur attribuée à un serveur lors d'un
801accès en répartition de charge interne. Dans ce cas, il est souhaitable que
802tous les serveurs aient un cookie renseigné. Un serveur non assigné d'un cookie
willy tarreau8337c6b2005-12-17 13:41:01 +0100803retournera un cookie vide (cookie de suppression) :
willy tarreau5cbea6f2005-12-17 12:48:26 +0100804
willy tarreauc5f73ed2005-12-18 01:26:38 +0100805 cookie SERVERID insert
willy tarreau5cbea6f2005-12-17 12:48:26 +0100806
willy tarreau0174f312005-12-18 01:02:42 +0100807Pour réutiliser un cookie applicatif et lui préfixer l'identifiant du serveur,
808puis le supprimer dans les requêtes suivantes, utiliser l'option 'prefix'. Elle
809permet d'insérer une instance de haproxy devant une application sans risquer
810d'incompatibilités dûes à des clients qui ne supporteraient pas d'apprendre
811plus d'un cookie :
812
813 cookie JSESSIONID prefix
814
willy tarreau240afa62005-12-17 13:14:35 +0100815Pour insérer un cookie, en s'assurant qu'un cache en amont ne le stockera pas,
816ajouter le mot clé 'nocache' après 'insert' :
817
willy tarreauc5f73ed2005-12-18 01:26:38 +0100818 cookie SERVERID insert nocache
willy tarreau240afa62005-12-17 13:14:35 +0100819
willy tarreau64a3cc32005-12-18 01:13:11 +0100820Pour insérer un cookie seulement suite aux requêtes de type POST, ajouter le
821mot clé 'postonly' après 'insert' :
willy tarreaucd878942005-12-17 13:27:43 +0100822
willy tarreauc5f73ed2005-12-18 01:26:38 +0100823 cookie SERVERID insert postonly
willy tarreaucd878942005-12-17 13:27:43 +0100824
willy tarreau240afa62005-12-17 13:14:35 +0100825
willy tarreau96d40372005-12-17 13:11:56 +0100826Remarques :
827-----------
willy tarreau64a3cc32005-12-18 01:13:11 +0100828- Il est possible de combiner 'insert' avec 'indirect' ou 'rewrite' pour
829 s'adapter à des applications générant déjà le cookie, avec un contenu
830 invalide. Il suffit pour cela de les spécifier sur la même ligne.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100831
willy tarreau96d40372005-12-17 13:11:56 +0100832- dans le cas où 'insert' et 'indirect' sont spécifiés, le cookie n'est jamais
833 transmis au serveur vu qu'il n'en a pas connaissance et ne pourrait pas le
834 comprendre.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100835
willy tarreau240afa62005-12-17 13:14:35 +0100836- il est particulièrement recommandé d'utiliser 'nocache' en mode insertion si
837 des caches peuvent se trouver entre les clients et l'instance du proxy. Dans
838 le cas contraire, un cache HTTP 1.0 pourrait cacher la réponse, incluant le
839 cookie de persistence inséré, donc provoquer des changements de serveurs pour
840 des clients partageant le même cache.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100841
willy tarreau0174f312005-12-18 01:02:42 +0100842- le mode 'prefix' ne nécessite pas d'utiliser 'indirect', 'nocache', ni
843 'postonly', car tout comme le mode 'rewrite', il s'appuie sur un cookie
844 présenté par l'application qui est censée savoir à quel moment il peut
845 être émis sans risque. Toutefois, comme il nécessite de rectifier le cookie
846 présenté par le client dans chaque requête ultérieure, il est indispensable
847 de s'assurer que le client et le serveur communiqueront sans "keep-alive
848 HTTP". Dans le doute, il est recommandé d'utiliser l'option "httpclose".
849
willy tarreaucd878942005-12-17 13:27:43 +0100850- lorsque l'application est bien connue, et que les parties nécessitant de la
851 persistence sont systématiquement accédées par un formulaire en mode POST,
852 il est plus efficace encore de combiner le mot clé "postonly" avec "insert"
853 et "indirect", car la page d'accueil reste cachable, et c'est l'application
854 qui gère le 'cache-control'.
willy tarreau0f7af912005-12-17 12:21:26 +0100855
willy tarreau240afa62005-12-17 13:14:35 +01008562.10) Assignation d'un serveur à une valeur de cookie
willy tarreauc29948c2005-12-17 13:10:27 +0100857----------------------------------------------------
willy tarreau8337c6b2005-12-17 13:41:01 +0100858En mode HTTP, il est possible d'associer des valeurs de cookie à des serveurs
859par le paramètre 'server'. La syntaxe est :
willy tarreau0f7af912005-12-17 12:21:26 +0100860
willy tarreau5cbea6f2005-12-17 12:48:26 +0100861 server <identifiant> <adresse_ip>:<port> cookie <valeur>
willy tarreau0f7af912005-12-17 12:21:26 +0100862
willy tarreauc29948c2005-12-17 13:10:27 +0100863- <identifiant> est un nom quelconque de serveur utilisé pour l'identifier dans la
864 configuration et les logs.
865- <adresse_ip>:<port> est le couple adresse-port sur lequel le serveur écoute.
866- <valeur> est la valeur à reconnaître ou positionner dans le cookie.
willy tarreau0f7af912005-12-17 12:21:26 +0100867
868Exemple : le cookie SERVERID peut contenir server01 ou server02
willy tarreauc29948c2005-12-17 13:10:27 +0100869---------
willy tarreaua41a8b42005-12-17 14:02:24 +0100870 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100871 mode http
872 cookie SERVERID
873 dispatch 192.168.1.100:80
874 server web1 192.168.1.1:80 cookie server01
875 server web2 192.168.1.2:80 cookie server02
willy tarreau5cbea6f2005-12-17 12:48:26 +0100876
877Attention : la syntaxe a changé depuis la version 1.0.
willy tarreauc29948c2005-12-17 13:10:27 +0100878-----------
willy tarreau5cbea6f2005-12-17 12:48:26 +0100879
willy tarreaua41a8b42005-12-17 14:02:24 +01008803) Répartiteur de charge autonome
willy tarreauc29948c2005-12-17 13:10:27 +0100881=================================
willy tarreau5cbea6f2005-12-17 12:48:26 +0100882
willy tarreauc29948c2005-12-17 13:10:27 +0100883Le relais peut effectuer lui-même la répartition de charge entre les différents
884serveurs définis pour un service donné, en mode TCP comme en mode HTTP. Pour
885cela, on précise le mot clé 'balance' dans la définition du service,
willy tarreau34f45302006-04-15 21:37:14 +0200886éventuellement suivi du nom d'un algorithme de répartition. Jusqu'à la version
8871.2.11, seul 'roundrobin' était géré, et c'est aussi la valeur implicite par
Willy Tarreau2fcb5002007-05-08 13:35:26 +0200888défaut. Avec la version 1.2.12, le nouveau mot clé 'source' est apparu. La
889version 1.3.10 a également apporté le mot clé 'uri'. Il est évident qu'en cas
890d'utilisation du répartiteur interne, il ne faudra pas spécifier d'adresse de
891dispatch, et qu'il faudra au moins un serveur.
willy tarreau5cbea6f2005-12-17 12:48:26 +0100892
893Exemple : même que précédemment en répartition interne
willy tarreauc29948c2005-12-17 13:10:27 +0100894---------
willy tarreau5cbea6f2005-12-17 12:48:26 +0100895
willy tarreaua41a8b42005-12-17 14:02:24 +0100896 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100897 mode http
898 cookie SERVERID
899 balance roundrobin
900 server web1 192.168.1.1:80 cookie server01
901 server web2 192.168.1.2:80 cookie server02
willy tarreau5cbea6f2005-12-17 12:48:26 +0100902
willy tarreaua41a8b42005-12-17 14:02:24 +0100903Depuis la version 1.1.22, il est possible de déterminer automatiquement le port
904du serveur vers lequel sera envoyée la connexion, en fonction du port d'écoute
905sur lequel le client s'est connecté. En effet, il y a 4 possibilités pour le
906champ <port> de l'adresse serveur :
907
908 - non spécifié ou nul :
909 la connexion sera envoyée au serveur sur le même port que celui sur
910 lequel le relais a reçu la connexion.
911
912 - valeur numérique (seul cas supporté pour les versions antérieures) :
913 le serveur recevra la connexion sur le port désigné.
914
915 - valeur numérique précédée d'un signe '+' :
916 la connexion sera envoyée au serveur sur le même port que celui sur
917 lequel le relais a reçu la connexion, auquel on ajoute la valeur désignée.
918
919 - valeur numérique précédée d'un signe '-' :
920 la connexion sera envoyée au serveur sur le même port que celui sur
921 lequel le relais a reçu la connexion, duquel on soustrait la valeur
922 désignée.
923
924Exemples :
925----------
926
927# même que précédemment
928
929 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100930 mode http
931 cookie SERVERID
932 balance roundrobin
933 server web1 192.168.1.1 cookie server01
934 server web2 192.168.1.2 cookie server02
willy tarreaua41a8b42005-12-17 14:02:24 +0100935
936# relayage simultané des ports 80 et 81 et 8080-8089
937
938 listen http_proxy :80,:81,:8080-8089
willy tarreauc5f73ed2005-12-18 01:26:38 +0100939 mode http
940 cookie SERVERID
941 balance roundrobin
942 server web1 192.168.1.1 cookie server01
943 server web2 192.168.1.2 cookie server02
willy tarreaua41a8b42005-12-17 14:02:24 +0100944
945# relayage TCP des ports 25, 389 et 663 vers les ports 1025, 1389 et 1663
946
947 listen http_proxy :25,:389,:663
willy tarreauc5f73ed2005-12-18 01:26:38 +0100948 mode tcp
949 balance roundrobin
950 server srv1 192.168.1.1:+1000
951 server srv2 192.168.1.2:+1000
willy tarreaua41a8b42005-12-17 14:02:24 +0100952
willy tarreau34f45302006-04-15 21:37:14 +0200953Comme indiqué précédemment, la version 1.2.12 apporta le nouveau mot clé
954'source'. Lorsque celui-ci est utilisé, l'adresse IP du client est hachée et
955distribuée de manière homogène parmi les serveurs disponibles, de sorte qu'une
956même adresse IP aille toujours sur le même serveur tant qu'il n'y a aucun
957changement dans le nombre de serveurs disponibles. Ceci peut être utilisé par
958exemple pour attacher le HTTP et le HTTPS sur un même serveur pour un même
959client. Cela peut également être utilisé pour améliorer la persistance
960lorsqu'une partie de la population des clients n'accepte pas les cookies. Dans
961ce cas, seuls ces derniers seront perturbés par la perte d'un serveur.
962
963NOTE: il est important de prendre en compte le fait que beaucoup d'internautes
964 naviguent à travers des fermes de proxies qui assignent des adresses IP
965 différentes à chaque requête. D'autres internautes utilisent des liens à
966 la demande et obtiennent une adresse IP différente à chaque connexion. De
967 ce fait, le paramètre 'source' doit être utilisé avec une extrème
968 précaution.
969
970Exemples :
971----------
972
973# assurer qu'une même adresse IP ira sur le même serveur pour tout service
974
975 listen http_proxy
976 bind :80,:443
977 mode http
978 balance source
979 server web1 192.168.1.1
980 server web2 192.168.1.2
981
982# améliorer la persistance par l'utilisation de la source en plus du cookie :
983
984 listen http_proxy :80
985 mode http
986 cookie SERVERID
987 balance source
988 server web1 192.168.1.1 cookie server01
989 server web2 192.168.1.2 cookie server02
990
Willy Tarreau2fcb5002007-05-08 13:35:26 +0200991De plus, tel qu'indiqué ci-dessus, la version 1.3.10 a introduit le mot clé
992'uri'. Il est très pratique dans le cas de répartition de charge entre des
993reverse-proxy-caches, parce qu'il utilisera le résultat d'un hachage de l'URI
994pour choisir un serveur, ce qui aura pour effet d'optimiser le taux de cache
995du fait que la même URI sera toujours envoyée au même cache. Ce mot-clé n'est
996autorisé qu'en mode HTTP.
997
998Example :
999---------
1000
1001# Envoie toujours une URI donnée au même serveur
1002
1003 listen http_proxy
1004 bind :3128
1005 mode http
1006 balance uri
1007 server squid1 192.168.1.1
1008 server squid2 192.168.1.2
1009
Willy Tarreau01732802007-11-01 22:48:15 +01001010La version 1.3.14 a apporté une nouvelle méthode 'balance url_param'. Elle
1011consiste à se baser sur un paramètre passé dans l'URL pour effectuer un hachage
1012utilisé pour déterminer le serveur à utiliser. Ceci est principalement utile
1013pour des applications n'ayant pas une exigence stricte de persistance, mais
1014pour lesquelles elle procure un gain de performance notable dans des
1015environnements où il n'est pas toujours possible d'utiliser des cookies. En cas
1016d'absence du paramètre dans l'URL, alors une répartition de type 'round robin'
1017est effectuée.
1018
1019Example :
1020---------
1021
1022# hache le paramètre "basket_id" dans l'URL pour déterminer le serveur
1023
1024 listen http_proxy
1025 bind :3128
1026 mode http
1027 balance url_param basket_id
1028 server ebiz1 192.168.1.1
1029 server ebiz2 192.168.1.2
1030
willy tarreau0f7af912005-12-17 12:21:26 +01001031
willy tarreauc29948c2005-12-17 13:10:27 +010010323.1) Surveillance des serveurs
1033------------------------------
willy tarreau64a3cc32005-12-18 01:13:11 +01001034Il est possible de tester l'état des serveurs par établissement de connexion
1035TCP ou par envoi d'une requête HTTP. Un serveur hors d'usage ne sera pas
1036utilisé dans le processus de répartition de charge interne. Pour activer la
1037surveillance, ajouter le mot clé 'check' à la fin de la déclaration du serveur.
1038Il est possible de spécifier l'intervalle (en millisecondes) séparant deux
1039tests du serveur par le paramètre "inter", le nombre d'échecs acceptés par le
1040paramètre "fall", et le nombre de succès avant reprise par le paramètre "rise".
1041Les paramètres non précisés prennent les valeurs suivantes par défaut :
willy tarreau34f45302006-04-15 21:37:14 +02001042
willy tarreaue47c8d72005-12-17 12:55:52 +01001043 - inter : 2000
1044 - rise : 2
1045 - fall : 3
willy tarreaua41a8b42005-12-17 14:02:24 +01001046 - port : port de connexion du serveur
Willy Tarreau2ea3abb2007-03-25 16:45:16 +02001047 - addr : adresse de connexion du serveur (par defaut: adresse du serveur)
1048
willy tarreaubc4e1fb2005-12-17 13:32:07 +01001049Le mode par défaut consiste à établir des connexions TCP uniquement. Dans
willy tarreau64a3cc32005-12-18 01:13:11 +01001050certains cas de pannes, des serveurs peuvent continuer à accepter les
1051connexions sans les traiter. Depuis la version 1.1.16, haproxy est en mesure
1052d'envoyer des requêtes HTTP courtes et très peu coûteuses. Les versions 1.1.16
1053et 1.1.17 utilisent "OPTIONS / HTTP/1.0". Dans les versions 1.1.18 à 1.1.20,
1054les requêtes ont été changées en "OPTIONS * HTTP/1.0" pour des raisons de
1055contrôle d'accès aux ressources. Cependant, cette requête documentée dans la
1056RFC2068 n'est pas comprise par tous les serveurs. Donc à partir de la version
10571.1.21, la requête par défaut est revenue à "OPTIONS / HTTP/1.0", mais il est
1058possible de paramétrer la partie URI. Les requêtes OPTIONS présentent
1059l'avantage d'être facilement extractibles des logs, et de ne pas induire
1060d'accès aux fichiers côté serveur. Seules les réponses 2xx et 3xx sont
1061considérées valides, les autres (y compris non-réponses) aboutissent à un
1062échec. Le temps maximal imparti pour une réponse est égal à l'intervalle entre
1063deux tests (paramètre "inter"). Pour activer ce mode, spécifier l'option
1064"httpchk", éventuellement suivie d'une méthode et d'une URI. L'option "httpchk"
1065accepte donc 4 formes :
willy tarreau34f45302006-04-15 21:37:14 +02001066
willy tarreaueedaa9f2005-12-17 14:08:03 +01001067 - option httpchk -> OPTIONS / HTTP/1.0
1068 - option httpchk URI -> OPTIONS <URI> HTTP/1.0
1069 - option httpchk METH URI -> <METH> <URI> HTTP/1.0
1070 - option httpchk METH URI VER -> <METH> <URI> <VER>
willy tarreau34f45302006-04-15 21:37:14 +02001071
Willy Tarreauf3c69202006-07-09 16:42:34 +02001072HAProxy est souvent utilisé pour relayer divers protocoles reposant sur TCP,
1073tels que HTTPS, SMTP ou LDAP, le plus commun étant HTTPS. Un problème assez
1074couramment rencontré dans les data centers est le besoin de relayer du trafic
1075vers des serveurs lointains tout en maintenant la possibilité de basculer sur
1076un serveur de secours. Les tests purement TCP ne suffisent pas toujours dans
1077ces situations car l'on trouve souvent, dans la chaîne, des proxies, firewalls
1078ou répartiteurs de charge qui peuvent acquitter la connexion avant qu'elle
1079n'atteigne le serveur. La seule solution à ce problème est d'envoyer des tests
1080applicatifs. Comme la demande pour les tests HTTPS est élevée, ce test a été
1081implémenté en version 1.2.15 sur la base de messages SSLv3 CLIENT HELLO. Pour
1082l'activer, utiliser "option ssl-hello-chk". Ceci enverra des messages SSLv3
1083CLIENT HELLO aux serveurs, en annonçant un support pour la majorité des
1084algorithmes de chiffrement. Si en retour, le serveur envoie ce qui ressemble à
1085une réponse SSLv3 SERVER HELLO ou ALERT (refus des algorithmes), alors la
1086réponse sera considérée comme valide. Noter qu'Apache ne produit pas de log
1087lorsqu'il reçoit des messages HELLO, ce qui en fait un type de message
1088parfaitement adapté à ce besoin.
1089
Willy Tarreau23677902007-05-08 23:50:35 +02001090La version 1.3.10 est accompagnée d'un nouveau test d'état pour le SMTP. Par
1091défaut, il consiste à envoyer "HELO localhost" aux serveurs, et à attendre le
1092message "250" en retour. Notez qu'il peut aussi envoyer une requête plus
1093spécifique :
1094
1095 - option smtpchk -> envoie "HELO localhost"
1096 - option smtpchk EHLO mail.mydomain.com -> envoie ce message ESMTP
1097
willy tarreauc5f73ed2005-12-18 01:26:38 +01001098Voir les exemples ci-après.
willy tarreaubc4e1fb2005-12-17 13:32:07 +01001099
willy tarreau8337c6b2005-12-17 13:41:01 +01001100Depuis la version 1.1.17, il est possible de définir des serveurs de secours,
1101utilisés uniquement lorsqu'aucun des autres serveurs ne fonctionne. Pour cela,
1102ajouter le mot clé "backup" sur la ligne de définition du serveur. Un serveur
1103de secours n'est appelé que lorsque tous les serveurs normaux, ainsi que tous
1104les serveurs de secours qui le précèdent sont hors d'usage. Il n'y a donc pas
Willy TARREAU3481c462006-03-01 22:37:57 +01001105de répartition de charge entre des serveurs de secours par défaut. A partir
1106de la version 1.2.9, il est possible de les utiliser simultanément grâce à
1107l'option 'allbackups'. Ce type de serveurs peut servir à retourner des pages
1108d'indisponibilité de service. Dans ce cas, il est préférable de ne pas affecter
1109de cookie, afin que les clients qui le rencontrent n'y soient pas affectés
1110définitivement. Le fait de ne pas mettre de cookie envoie un cookie vide, ce
1111qui a pour effet de supprimer un éventuel cookie affecté précédemment.
willy tarreau8337c6b2005-12-17 13:41:01 +01001112
willy tarreaua41a8b42005-12-17 14:02:24 +01001113Depuis la version 1.1.22, il est possible d'envoyer les tests de fonctionnement
1114vers un port différent de celui de service. C'est nécessaire principalement
1115pour les configurations où le serveur n'a pas de port prédéfini, par exemple
1116lorsqu'il est déduit du port d'acceptation de la connexion. Pour cela, utiliser
Willy Tarreau2ea3abb2007-03-25 16:45:16 +02001117le paramètre 'port' suivi du numéro de port devant répondre aux requêtes. Il
1118est possible d'envoyer les tests de fonctionnement vers une adresse différente
1119de celle de service. Cela permet d'utiliser, sur la machine faisant fonctionner
1120HAproxy, un démon permettant des tests specifiques ( REGEX sur un résultat et
1121basculement de plusieurs fermes en cas d'erreur sur l'une d'elles).
willy tarreaua41a8b42005-12-17 14:02:24 +01001122
willy tarreau64a3cc32005-12-18 01:13:11 +01001123Enfin, depuis la version 1.1.17, il est possible de visualiser rapidement
1124l'état courant de tous les serveurs. Pour cela, il suffit d'envoyer un signal
1125SIGHUP au processus proxy. L'état de tous les serveurs de tous les proxies est
1126envoyé dans les logs en niveau "notice", ainsi que sur la sortie d'erreurs si
1127elle est active. C'est une bonne raison pour avoir au moins un serveur de logs
1128local en niveau notice.
willy tarreau8337c6b2005-12-17 13:41:01 +01001129
willy tarreau982249e2005-12-18 00:57:06 +01001130Depuis la version 1.1.18 (et 1.2.1), un message d'urgence est envoyé dans les
1131logs en niveau 'emerg' si tous les serveurs d'une même instance sont tombés,
1132afin de notifier l'administrateur qu'il faut prendre une action immédiate.
1133
willy tarreau0174f312005-12-18 01:02:42 +01001134Depuis les versions 1.1.30 et 1.2.3, plusieurs serveurs peuvent partager la
1135même valeur de cookie. C'est particulièrement utile en mode backup, pour
1136sélectionner des chemins alternatifs pour un serveur donné, pour mettre en
1137oeuvre l'arrêt en douceur d'un serveur, ou pour diriger les clients
1138temporairement vers une page d'erreur en attendant le redémarrage d'une
1139application. Le principe est que lorsqu'un serveur est détecté comme inopérant,
1140le proxy cherchera le prochain serveur possédant la même valeur de cookie pour
1141chaque client qui le demandera. S'il ne trouve pas de serveur normal, alors il
1142le cherchera parmi les serveurs de backup. Consulter le guide d'architecture
1143pour plus d'informations.
1144
willy tarreauc29948c2005-12-17 13:10:27 +01001145Exemples :
1146----------
willy tarreaua41a8b42005-12-17 14:02:24 +01001147# conf du paragraphe 3) avec surveillance TCP
willy tarreaubc4e1fb2005-12-17 13:32:07 +01001148 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001149 mode http
1150 cookie SERVERID
1151 balance roundrobin
1152 server web1 192.168.1.1:80 cookie server01 check
1153 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaubc4e1fb2005-12-17 13:32:07 +01001154
willy tarreau2f6ba652005-12-17 13:57:42 +01001155# même que précédemment avec surveillance HTTP par 'OPTIONS / HTTP/1.0'
willy tarreau5cbea6f2005-12-17 12:48:26 +01001156 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001157 mode http
1158 cookie SERVERID
1159 balance roundrobin
1160 option httpchk
1161 server web1 192.168.1.1:80 cookie server01 check
1162 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreau5cbea6f2005-12-17 12:48:26 +01001163
willy tarreau2f6ba652005-12-17 13:57:42 +01001164# même que précédemment avec surveillance HTTP par 'OPTIONS /index.html HTTP/1.0'
1165 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001166 mode http
1167 cookie SERVERID
1168 balance roundrobin
1169 option httpchk /index.html
1170 server web1 192.168.1.1:80 cookie server01 check
1171 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreau2f6ba652005-12-17 13:57:42 +01001172
willy tarreaueedaa9f2005-12-17 14:08:03 +01001173# idem avec surveillance HTTP par 'HEAD /index.jsp? HTTP/1.1\r\nHost: www'
1174 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001175 mode http
1176 cookie SERVERID
1177 balance roundrobin
1178 option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
1179 server web1 192.168.1.1:80 cookie server01 check
1180 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +01001181
willy tarreau0174f312005-12-18 01:02:42 +01001182# répartition avec persistence basée sur le préfixe de cookie, et arrêt en
1183# douceur utilisant un second port (81) juste pour les health-checks.
1184 listen http_proxy 0.0.0.0:80
1185 mode http
1186 cookie JSESSIONID prefix
1187 balance roundrobin
1188 option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
1189 server web1-norm 192.168.1.1:80 cookie s1 check port 81
1190 server web2-norm 192.168.1.2:80 cookie s2 check port 81
1191 server web1-stop 192.168.1.1:80 cookie s1 check port 80 backup
1192 server web2-stop 192.168.1.2:80 cookie s2 check port 80 backup
1193
willy tarreau96d40372005-12-17 13:11:56 +01001194# Insertion automatique de cookie dans la réponse du serveur, et suppression
willy tarreau240afa62005-12-17 13:14:35 +01001195# automatique dans la requête, tout en indiquant aux caches de ne pas garder
1196# ce cookie.
willy tarreauc29948c2005-12-17 13:10:27 +01001197 listen web_appl 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001198 mode http
1199 cookie SERVERID insert nocache indirect
1200 balance roundrobin
1201 server web1 192.168.1.1:80 cookie server01 check
1202 server web2 192.168.1.2:80 cookie server02 check
willy tarreau8337c6b2005-12-17 13:41:01 +01001203
willy tarreaueedaa9f2005-12-17 14:08:03 +01001204# idem avec serveur applicatif de secours sur autre site, et serveur de pages d'erreurs
willy tarreau8337c6b2005-12-17 13:41:01 +01001205 listen web_appl 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001206 mode http
1207 cookie SERVERID insert nocache indirect
1208 balance roundrobin
1209 server web1 192.168.1.1:80 cookie server01 check
1210 server web2 192.168.1.2:80 cookie server02 check
1211 server web-backup 192.168.2.1:80 cookie server03 check backup
1212 server web-excuse 192.168.3.1:80 check backup
willy tarreau5cbea6f2005-12-17 12:48:26 +01001213
willy tarreaua41a8b42005-12-17 14:02:24 +01001214# relayage SMTP+TLS avec test du serveur et serveur de backup
1215
1216 listen http_proxy :25,:587
willy tarreauc5f73ed2005-12-18 01:26:38 +01001217 mode tcp
1218 balance roundrobin
1219 server srv1 192.168.1.1 check port 25 inter 30000 rise 1 fall 2
1220 server srv2 192.168.1.2 backup
willy tarreaua41a8b42005-12-17 14:02:24 +01001221
Willy Tarreauf3c69202006-07-09 16:42:34 +02001222# relayage HTTPS avec test du serveur et serveur de backup
1223
1224 listen http_proxy :443
1225 mode tcp
1226 option ssl-hello-chk
1227 balance roundrobin
1228 server srv1 192.168.1.1 check inter 30000 rise 1 fall 2
1229 server srv2 192.168.1.2 backup
1230
Willy TARREAU3481c462006-03-01 22:37:57 +01001231# Utilisation d'un groupe de serveurs pour le backup (nécessite haproxy 1.2.9)
1232 listen http_proxy 0.0.0.0:80
1233 mode http
1234 balance roundrobin
1235 option httpchk
1236 server inst1 192.168.1.1:80 cookie s1 check
1237 server inst2 192.168.1.2:80 cookie s2 check
1238 server inst3 192.168.1.3:80 cookie s3 check
1239 server back1 192.168.1.10:80 check backup
1240 server back2 192.168.1.11:80 check backup
1241 option allbackups # all backups will be used
1242
willy tarreau0f7af912005-12-17 12:21:26 +01001243
willy tarreauc29948c2005-12-17 13:10:27 +010012443.2) Reconnexion vers un répartiteur en cas d'échec direct
1245----------------------------------------------------------
1246En mode HTTP, si un serveur défini par un cookie ne répond plus, les clients
1247seront définitivement aiguillés dessus à cause de leur cookie, et de ce fait,
1248définitivement privés de service. La spécification du paramètre 'redispatch'
1249autorise dans ce cas à renvoyer les connexions échouées vers le répartiteur
1250(externe ou interne) afin d'assigner un nouveau serveur à ces clients.
willy tarreau0f7af912005-12-17 12:21:26 +01001251
1252Exemple :
willy tarreauc29948c2005-12-17 13:10:27 +01001253---------
willy tarreau0f7af912005-12-17 12:21:26 +01001254 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001255 mode http
1256 cookie SERVERID
1257 dispatch 192.168.1.100:80
1258 server web1 192.168.1.1:80 cookie server01
1259 server web2 192.168.1.2:80 cookie server02
1260 redispatch # renvoyer vers dispatch si refus de connexion.
willy tarreau8337c6b2005-12-17 13:41:01 +01001261
willy tarreau64a3cc32005-12-18 01:13:11 +01001262Par défaut (et dans les versions 1.1.16 et antérieures), le paramètre
1263redispatch ne s'applique qu'aux échecs de connexion au serveur. Depuis la
1264version 1.1.17, il s'applique aussi aux connexions destinées à des serveurs
1265identifiés comme hors d'usage par la surveillance. Si l'on souhaite malgré
1266tout qu'un client disposant d'un cookie correspondant à un serveur défectueux
1267tente de s'y connecter, il faut préciser l'option "persist" :
willy tarreau8337c6b2005-12-17 13:41:01 +01001268
1269 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001270 mode http
1271 option persist
1272 cookie SERVERID
1273 dispatch 192.168.1.100:80
1274 server web1 192.168.1.1:80 cookie server01
1275 server web2 192.168.1.2:80 cookie server02
1276 redispatch # renvoyer vers dispatch si serveur HS.
willy tarreau5cbea6f2005-12-17 12:48:26 +01001277
willy tarreauc29948c2005-12-17 13:10:27 +01001278
willy tarreau34f45302006-04-15 21:37:14 +020012793.3) Assignation de poids différents à des serveurs
1280---------------------------------------------------
1281Parfois il arrive d'ajouter de nouveaux serveurs pour accroître la capacité
1282d'une ferme de serveur, mais le nouveau serveur est soit beaucoup plus petit
1283que les autres (dans le cas d'un ajout d'urgence de matériel de récupération),
1284soit plus puissant (lors d'un investissement dans du matériel neuf). Pour cette
1285raison, il semble parfois judicieux de pouvoir envoyer plus de clients vers les
1286plus gros serveurs. Jusqu'à la version 1.2.11, il était nécessaire de répliquer
1287plusieurs fois les définitions des serveurs pour augmenter leur poids. Depuis
1288la version 1.2.12, l'option 'weight' est disponible. HAProxy construit alors
1289une vue des serveurs disponibles la plus homogène possible en se basant sur
1290leur poids de sorte que la charge se distribue de la manière la plus lisse
1291possible. Le poids compris entre 1 et 256 doit refléter la capacité d'un
willy tarreau532bb552006-05-13 18:40:37 +02001292serveur par rapport aux autres. Le poids de 1 donne la fréquence d'apparition
1293la plus faible, et 256 la fréquence la plus élevée. De cette manière, si un
1294serveur disparait, les capacités restantes sont toujours respectées.
willy tarreau34f45302006-04-15 21:37:14 +02001295
1296
1297Exemple :
1298---------
1299# distribution équitable sur 2 opteron and un ancien pentium3
1300
1301 listen web_appl 0.0.0.0:80
1302 mode http
1303 cookie SERVERID insert nocache indirect
1304 balance roundrobin
1305 server pentium3-800 192.168.1.1:80 cookie server01 weight 8 check
1306 server opteron-2.0G 192.168.1.2:80 cookie server02 weight 20 check
1307 server opteron-2.4G 192.168.1.3:80 cookie server03 weight 24 check
1308 server web-backup1 192.168.2.1:80 cookie server04 check backup
1309 server web-excuse 192.168.3.1:80 check backup
1310
1311Notes :
1312-------
1313 - lorsque le poids n'est pas spécifié, la valeur par défaut est à 1
1314
1315 - le poids n'impacte pas les tests de fonctionnement (health checks), donc il
1316 est plus propre d'utiliser les poids que de répliquer le même serveur
1317 plusieurs fois.
1318
1319 - les poids s'appliquent également aux serveurs de backup si l'option
1320 'allbackups' est positionnée.
1321
1322 - le poids s'applique aussi à la répartition selon la source
1323 ('balance source').
1324
1325 - quels que soient les poids, le premier serveur sera toujours assigné en
1326 premier. Cette règle facilite les diagnostics.
1327
1328 - pour les puristes, l'algorithme de calculation de la vue des serveurs donne
1329 une priorité aux premiers serveurs, donc la vue est la plus uniforme si les
1330 serveurs sont déclarés dans l'ordre croissant de leurs poids.
1331
willy tarreau532bb552006-05-13 18:40:37 +02001332La distribution du trafic suivra exactement le séquencement suivant :
1333
1334 Request| 1 1 1 1
1335 number | 1 2 3 4 5 6 7 8 9 0 1 2 3
1336 --------+---------------------------
1337 p3-800 | X . . . . . . X . . . . .
1338 opt-20 | . X . X . X . . . X . X .
1339 opt-24 | . . X . X . X . X . X . X
1340
1341
13423.4) Limitation du nombre de sessions concurrentes par serveur
1343--------------------------------------------------------------
1344Certains serveurs web multi-processus tels qu'Apache souffrent dès qu'il y a
1345trop de sessions concurrentes, parce qu'il est très coûteux de faire
1346fonctionner des centaines ou des milliers de processus sur un système. Une
1347solution consiste à augmenter le nombre de serveurs et de répartir la charge
1348entre eux, mais cela pose un problème lorsque le but est uniquement de résister
1349à des pics de charge occasionnels.
1350
1351Pour résoudre ce problème, une nouvelle fonctionnalité a été implémentée dans
1352HAProxy 1.2.13. Il s'agit d'une limite "maxconn" par serveur, associée à une
1353file d'attente par serveur et par proxy. Ceci transforme HAProxy en un tampon
1354entre des milliers de clients et quelques serveurs. Dans bien des cas, le fait
1355de diminuer la valeur maxconn améliorera notablement les performances des
1356serveurs et diminuera les temps de réponse simplement parce que les serveurs
1357seront moins congestionnés.
1358
1359Quand une requête cherche à joindre n'importe quel serveur, le premier serveur
1360non saturé est utilisé, en respectant l'algorithme de répartition de charge. Si
1361tous les serveurs sont saturés, alors la requête sera mise dans la file
1362d'attente globale de l'instance. Elle sortira de cette file d'attente lorsque
1363toutes les requêtes précédentes auront été libérées et qu'un serveur aura été
1364libéré d'une connexion pour la traiter.
1365
1366Si une requête fait référence à un serveur en particulier (p.ex: hachage d'IP
1367source, ou persistance par cookie), et que ce server est saturé, alors la
1368requête sera mise dans la file d'attente dédiée à ce serveur. Cette file
1369d'attente est prioritaire sur la file d'attente globale, de sorte qu'il soit
1370plus facile d'atteindre le site pour les utilisateurs qui s'y trouvent déjà
1371que pour les nouveaux utilisateurs.
1372
1373Pour cela, les logs ont dû être enrichis pour indiquer le nombre de sessions
1374par serveur, la position de la requête dans les files d'attentes, et le temps
1375passé en file d'attente. Ceci aide considérablement à faire de la prévision de
1376capacité. Voir la section 'logs' plus bas pour plus d'informations.
1377
1378Exemple :
1379---------
1380 # Prendre soin du P3 qui n'a que 256 Mo de RAM.
1381 listen web_appl 0.0.0.0:80
1382 maxconn 10000
1383 mode http
1384 cookie SERVERID insert nocache indirect
1385 balance roundrobin
1386 server pentium3-800 192.168.1.1:80 cookie s1 weight 8 maxconn 100 check
1387 server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 maxconn 300 check
1388 server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 maxconn 300 check
1389 server web-backup1 192.168.2.1:80 cookie s4 check maxconn 200 backup
1390 server web-excuse 192.168.3.1:80 check backup
1391
willy tarreau8f635a42006-05-21 23:05:54 +02001392Cette option se montra si efficace pour réduire les temps de réponse des
1393serveurs que certains utilisateurs voulaient utiliser des valeurs trop basses
1394pour améliorer les performances de leurs serveurs. Seulement, ils n'étaient
1395alors plus en mesure de supporter de très fortes charges parce qu'il n'était
1396plus possible de les saturer. Pour cette raison, la version 1.2.14 a apporté la
1397limitation dynamique de connexions avec l'addition du paramètre "minconn".
1398Lorsque ce paramètre est associé à "maxconn", il active la limitation dynamique
1399basée sur la charge de l'instance. Le nombre maximal de sessions concurrentes
1400sur un serveur devient alors proportionnel au nombre de sessions de l'instance
1401par rapport à son 'maxconn'. Un minimum de <minconn> sessions sera toujours
1402permis quelle que soit la charge. Ceci assurera que les serveurs travailleront
1403au meilleur de leurs performances sous des charges normales, et qu'ils seront
1404tout de même capables de supporter de fortes pointes lorsque nécessaire. La
1405limite dynamique est calculée comme ceci :
1406
1407 srv.dyn_limit = max(srv.minconn, srv.maxconn * inst.sess / inst.maxconn)
1408
1409Exemple :
1410---------
1411 # Prendre soin du P3 qui n'a que 256 Mo de RAM.
1412 listen web_appl 0.0.0.0:80
1413 maxconn 10000
1414 mode http
1415 cookie SERVERID insert nocache indirect
1416 balance roundrobin
1417 server pentium3-800 192.168.1.1:80 cookie s1 weight 8 minconn 10 maxconn 100 check
1418 server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 minconn 30 maxconn 300 check
1419 server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 minconn 30 maxconn 300 check
1420 server web-backup1 192.168.2.1:80 cookie s4 check maxconn 200 backup
1421 server web-excuse 192.168.3.1:80 check backup
1422
1423Dans l'exemple ci-dessus, le serveur "pentium3-800' recevra au plus 100
1424connexions simultanées lorsque l'instance du proxy en atteindra 10000, et
1425recevra seulement 10 connexions simultanées tant que le proxy sera sous les 1000
1426sessions.
1427
Elijah Epifanovacafc5f2007-10-25 20:15:38 +02001428Il est possible de limiter la taille de la file d'attente dans le but de
1429redistribuer les connexions destinées à un serveur en particulier qui sont trop
1430loin pour avoir une chance d'être servies en un temps raisonnable. Ceci n'est
1431acceptable que dans le cas où l'affinité entre le client et le serveur n'est
1432pas obligatoire, mais motivée uniquement par des raisons de performances, par
1433exemple, par l'utilisation d'un cache local au serveur. L'option 'maxqueue'
1434permet de préciser la limite par serveur, tel que dans l'exemple ci-dessous :
1435
1436... (même exemple que précédemment)
1437 server pentium3-800 192.168.1.1:80 cookie s1 weight 8 minconn 10 maxconn 100 check maxqueue 50
1438 server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 minconn 30 maxconn 300 check maxqueue 200
1439 server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 minconn 30 maxconn 300 check
1440
1441En l'absence du paramètre 'maxqueue', la file d'un serveur n'a pas de limite
1442définie. Dans le cas contraire, lorsque la file atteint la limite fixée par
1443'maxqueue', les clients sont déplacés vers la file globale.
1444
willy tarreau532bb552006-05-13 18:40:37 +02001445Notes :
1446-------
1447 - la requête ne restera pas indéfiniment en file d'attente, elle est
1448 assujétie au paramètre 'contimeout', et si une requête ne peut pas
1449 sortir de la file avant ce time-out, soit parce que le serveur est
1450 saturé, soit parce qu'il y a trop de requêtes en file d'attente,
1451 alors elle expirera avec une erreur 503.
1452
willy tarreau8f635a42006-05-21 23:05:54 +02001453 - si seul <minconn> est spécifié, il a le même effet que <maxconn>
1454
willy tarreau532bb552006-05-13 18:40:37 +02001455 - positionner des valeurs trop basses pour 'maxconn' peut améliorer les
1456 performances mais aussi permettre à des utilisateurs trop lents de bloquer
1457 un serveur pour les autres utilisateurs.
1458
willy tarreau34f45302006-04-15 21:37:14 +02001459
willy tarreau8f635a42006-05-21 23:05:54 +020014603.5) Abandon des requêtes abortées
1461----------------------------------
1462En présence de très fortes charges, les serveurs mettront un certain temps à
1463répondre. La file d'attente du proxy se remplira, et les temps de réponse
1464suivront une croissance proportionnelle à la taille de file d'attente fois
1465le temps moyen de réponse par session. Lorsque les clients attendront plus de
1466quelques secondes, ils cliqueront souvent sur le bouton 'STOP' de leur
1467navigateur, laissant des requêtes inutiles en file d'attente et ralentissant
1468donc les autres utilisateurs.
1469
1470Comme il n'y a aucun moyen de distinguer un vrai clic sur STOP d'une simple
1471fermeture du canal de sortie sur le client (shutdown(SHUT_WR)), les agents HTTP
1472doivent être conservateurs et considérer que le client n'a probablement fermé
1473que le canal de sortie en attendant la réponse. Toutefois, ceci introduit des
1474risques de congestion lorsque beaucoup d'utilisateurs font de même, et s'avère
1475aujourd'hui complètement inutile car probablement aucun client ne referme la
1476session en attendant la réponse. Certains agents HTTP supportent ceci (Squid,
1477Apache, HAProxy), et d'autres ne le supportent pas (TUX, et la plupart des
1478répartiteurs de charge matériels). Donc la probabilité pour qu'une notification
1479de fermeture d'un canal d'entrée côté client représente un utilisateur cliquant
1480sur 'STOP' est proche de 100%, et il est vraiment tentant d'abandonner la
1481requête prématurément sans polluer les serveurs.
1482
1483Pour cette raison, une nouvelle option "abortonclose" a été introduite en
1484version 1.2.14. Par défaut (sans l'option), le comportement reste conforme à
1485HTTP. Mais lorsque l'option est spécifiée, une session dont le canal entrant
1486est fermé sera abortée si cela est possible, c'est à dire que la requête est
1487soit en file d'attente, soit en tentative de connexion. Ceci réduit
1488considérablement la longueur des files d'attentes et la charge sur les serveurs
1489saturés lorsque les utilisateurs sont tentés de cliquer sur 'STOP', ce qui à
1490son tour, réduit les temps de réponse pour les autres utilisateurs.
1491
1492Exemple :
1493---------
1494 listen web_appl 0.0.0.0:80
1495 maxconn 10000
1496 mode http
1497 cookie SERVERID insert nocache indirect
1498 balance roundrobin
1499 server web1 192.168.1.1:80 cookie s1 weight 10 maxconn 100 check
1500 server web2 192.168.1.2:80 cookie s2 weight 10 maxconn 100 check
1501 server web3 192.168.1.3:80 cookie s3 weight 10 maxconn 100 check
1502 server bck1 192.168.2.1:80 cookie s4 check maxconn 200 backup
1503 option abortonclose
1504
1505
willy tarreauc29948c2005-12-17 13:10:27 +010015064) Fonctionnalités additionnelles
1507=================================
1508
1509D'autres fonctionnalités d'usage moins courant sont disponibles. Il s'agit
willy tarreau8f635a42006-05-21 23:05:54 +02001510principalement du mode transparent, de la journalisation des connexions, de la
1511réécriture des en-têtes, et du statut sous forme de page HTML.
1512
willy tarreau5cbea6f2005-12-17 12:48:26 +01001513
willy tarreau0174f312005-12-18 01:02:42 +010015144.1) Fonctionnalités réseau
1515---------------------------
15164.1.1) Fonctionnement en mode transparent
willy tarreauc29948c2005-12-17 13:10:27 +01001517---------------------------------------
willy tarreau64a3cc32005-12-18 01:13:11 +01001518En mode HTTP, le mot clé 'transparent' permet d'intercepter des sessions
1519routées à travers la machine hébergeant le proxy. Dans ce mode, on ne précise
1520pas l'adresse de répartition 'dispatch', car celle-ci est tirée de l'adresse
willy tarreauc29948c2005-12-17 13:10:27 +01001521destination de la session détournée. Le système doit permettre de rediriger les
1522paquets vers un processus local.
willy tarreau5cbea6f2005-12-17 12:48:26 +01001523
1524Exemple :
willy tarreauc29948c2005-12-17 13:10:27 +01001525---------
willy tarreau5cbea6f2005-12-17 12:48:26 +01001526 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001527 mode http
1528 transparent
1529 cookie SERVERID
1530 server server01 192.168.1.1:80
1531 server server02 192.168.1.2:80
willy tarreau5cbea6f2005-12-17 12:48:26 +01001532
1533 # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
1534 --dport 80 -j REDIRECT --to-ports 65000
willy tarreau0f7af912005-12-17 12:21:26 +01001535
willy tarreaua41a8b42005-12-17 14:02:24 +01001536Remarque :
1537----------
willy tarreau64a3cc32005-12-18 01:13:11 +01001538Si le port n'est pas spécifié sur le serveur, c'est le port auquel s'est
1539adressé le client qui sera utilisé. Cela permet de relayer tous les ports TCP
1540d'une même adresse avec une même instance et sans utiliser directement le mode
1541transparent.
willy tarreaua41a8b42005-12-17 14:02:24 +01001542
1543Exemple :
1544---------
1545 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001546 mode tcp
1547 server server01 192.168.1.1 check port 60000
1548 server server02 192.168.1.2 check port 60000
willy tarreaua41a8b42005-12-17 14:02:24 +01001549
1550 # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
1551 -j REDIRECT --to-ports 65000
1552
willy tarreau0174f312005-12-18 01:02:42 +01001553
15544.1.2) Choix d'une adresse source par serveur
1555---------------------------------------------------
1556Avec les versions 1.1.30 et 1.2.3, il devient possible de spécifier une adresse
1557IP source pour joindre chaque serveur. C'est utile pour joindre des serveurs de
1558backup à partir d'un LAN différent, ou pour utiliser des chemins alternatifs
1559pour joindre le même serveur. C'est également utilisable pour faciliter une
1560répartition de charge selon l'adresse IP source pour des connexions sortantes.
1561Bien entendu, la même adresse est utilisée pour les health-checks.
1562
1563Exemple :
1564---------
1565 # utiliser une adresse particulière pour joindre les 2 serveur
1566 listen http_proxy 0.0.0.0:65000
1567 mode http
1568 balance roundrobin
1569 server server01 192.168.1.1:80 source 192.168.2.13
1570 server server02 192.168.1.2:80 source 192.168.2.13
1571
1572Exemple :
1573---------
1574 # utiliser une adresse particulière pour joindre chaque serveur
1575 listen http_proxy 0.0.0.0:65000
1576 mode http
1577 balance roundrobin
1578 server server01 192.168.1.1:80 source 192.168.1.1
1579 server server02 192.168.2.1:80 source 192.168.2.1
1580
1581Exemple :
1582---------
1583 # faire une répartition d'adresse sources pour joindre le même proxy à
1584 # travers deux liens WAN
1585 listen http_proxy 0.0.0.0:65000
1586 mode http
1587 balance roundrobin
1588 server remote-proxy-way1 192.168.1.1:3128 source 192.168.2.1
1589 server remote-proxy-way2 192.168.1.1:3128 source 192.168.3.1
1590
1591Exemple :
1592---------
1593 # forcer une connexion TCP à s'attacher à un port particulier
1594 listen http_proxy 0.0.0.0:2000
1595 mode tcp
1596 balance roundrobin
1597 server srv1 192.168.1.1:80 source 192.168.2.1:20
1598 server srv2 192.168.1.2:80 source 192.168.2.1:20
1599
willy tarreaub952e1d2005-12-18 01:31:20 +010016004.1.3) Maintien de session TCP (keep-alive)
1601-------------------------------------------
1602Avec la version 1.2.7, il devient possible d'activer le maintien de session
1603TCP (TCP keep-alive) à la fois côté client et côté serveur. Cela permet
1604d'empêcher des sessions longues d'expirer sur des équipements de niveau 4
1605externes tels que des firewalls ou des répartiteurs de charge. Cela permet
1606aussi au système de détecter et terminer des sessions figées lorsqu'aucun
1607time-out n'a été positionné (fortement déconseillé). Le proxy ne peut pas
1608positionner l'intervalle entre les annonces ni le nombre maximal, veuillez
1609vous référer au manuel du système d'exploitation pour cela. Il existe 3 options
1610pour activer le maintien de session TCP :
1611
1612 option tcpka # active le keep-alive côté client et côté serveur
1613 option clitcpka # active le keep-alive côté client
1614 option srvtcpka # active le keep-alive côté serveur
1615
Alexandre Cassen87ea5482007-10-11 20:48:58 +020016164.1.4) Rémanence des données TCP (lingering)
1617--------------------------------------------
1618Il est possible de désactiver la conservation de données non acquittées par un
1619client à la fin d'une session. Cela peut parfois s'avérer nécessaire lorsque
1620haproxy est utilisé en face d'un grand nombre de clients non fiables et qu'un
1621nombre élevé de sockets en état FIN_WAIT est observé sur la machine. L'option
1622peut être utilisée dans un frontend pour ajuster les connexions vers les
1623clients, et dans un backend pour ajuster les connexions vers les serveurs :
1624
1625 option nolinger # désactive la conservation de données
1626
willy tarreau0f7af912005-12-17 12:21:26 +01001627
willy tarreauc29948c2005-12-17 13:10:27 +010016284.2) Journalisation des connexions
1629----------------------------------
willy tarreauc5f73ed2005-12-18 01:26:38 +01001630
1631L'un des points forts de HAProxy est indéniablement la précision de ses logs.
1632Il fournit probablement le plus fin niveau d'information disponible pour un
1633tel outil, ce qui est très important pour les diagnostics en environnements
1634complexes. En standard, les informations journalisées incluent le port client,
1635les chronométrages des états TCP/HTTP, des états de session précis au moment de
1636la terminaison et sa cause, des informations sur les décisions d'aiguillage du
1637trafic vers un serveur, et bien sûr la possibilité de capturer des en-têtes
1638arbitraires.
1639
1640Dans le but d'améliorer la réactivité des administrateurs, il offre une grande
1641transparence sur les problèmes rencontrés, à la fois internes et externes, et
1642il est possible d'envoyer les logs vers des serveurs différents en même temps
1643avec des niveaux de filtrage différents :
1644
1645 - logs globaux au niveau processus (erreurs système, arrêts/démarrages, ...)
1646 - erreurs système et internes par instance (manque de ressources, bugs, ...)
1647 - problèmes externes par instance (arrêts/relance serveurs, limites, ...)
1648 - activité par instance (connexions clients), aussi bien lors de leur
1649 établissement qu'à leur terminaison.
1650
1651La possibilité de distribuer différents niveaux de logs à différents serveurs
1652permet à plusieurs équipes de production d'intéragir et de corriger leurs
1653problèmes le plus tôt possible. Par exemple, l'équipe système peut surveiller
1654occasionnellement les erreurs système, pendant que l'équipe application
1655surveille les alertes d'arrêts/démarrages de ses serveurs en temps réel, et
1656que l'équipe sécurité analyse l'activité en différé d'une heure.
1657
1658
willy tarreauc1cae632005-12-17 14:12:23 +010016594.2.1) Niveaux de log
1660---------------------
willy tarreauc29948c2005-12-17 13:10:27 +01001661Les connexions TCP et HTTP peuvent donner lieu à une journalisation sommaire ou
1662détaillée indiquant, pour chaque connexion, la date, l'heure, l'adresse IP
1663source, le serveur destination, la durée de la connexion, les temps de réponse,
willy tarreau8337c6b2005-12-17 13:41:01 +01001664la requête HTTP, le code de retour, la quantité de données transmises, et même
1665dans certains cas, la valeur d'un cookie permettant de suivre les sessions.
1666Tous les messages sont envoyés en syslog vers un ou deux serveurs. Se référer à
1667la section 1.1 pour plus d'information sur les catégories de logs. La syntaxe
willy tarreauc29948c2005-12-17 13:10:27 +01001668est la suivante :
willy tarreau0f7af912005-12-17 12:21:26 +01001669
willy tarreau8337c6b2005-12-17 13:41:01 +01001670 log <adresse_ip_1> <catégorie_1> [niveau_max_1]
1671 log <adresse_ip_2> <catégorie_2> [niveau_max_2]
willy tarreauc29948c2005-12-17 13:10:27 +01001672ou
1673 log global
1674
1675Remarque :
1676----------
1677La syntaxe spécifique 'log global' indique que l'on souhaite utiliser les
1678paramètres de journalisation définis dans la section 'global'.
willy tarreau0f7af912005-12-17 12:21:26 +01001679
1680Exemple :
1681---------
1682 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001683 mode http
1684 log 192.168.2.200 local3
1685 log 192.168.2.201 local4
willy tarreau0f7af912005-12-17 12:21:26 +01001686
willy tarreauc1cae632005-12-17 14:12:23 +010016874.2.2) Format des logs
1688----------------------
1689Par défaut, les connexions sont journalisées au niveau TCP dès l'établissement
1690de la session entre le client et le relais. En précisant l'option 'tcplog',
1691la connexion ne sera journalisée qu'en fin de session, ajoutant des précisions
1692sur son état lors de la déconnexion, ainsi que le temps de connexion et la
willy tarreau532bb552006-05-13 18:40:37 +02001693durée totale de la session. Le nombre de sessions restantes après la
1694déconnexion est également indiqué (pour le serveur, l'instance et le process).
willy tarreauc1cae632005-12-17 14:12:23 +01001695
willy tarreauc5f73ed2005-12-18 01:26:38 +01001696Exemple de journalisation TCP :
1697-------------------------------
willy tarreau982249e2005-12-18 00:57:06 +01001698 listen relais-tcp 0.0.0.0:8000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001699 mode tcp
1700 option tcplog
1701 log 192.168.2.200 local3
willy tarreau982249e2005-12-18 00:57:06 +01001702
willy tarreau532bb552006-05-13 18:40:37 +02001703>>> 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
willy tarreauc5f73ed2005-12-18 01:26:38 +01001704
willy tarreau532bb552006-05-13 18:40:37 +02001705 Champ Format / Description Exemple
1706
1707 1 nom_processus '[' pid ']:' haproxy[18989]:
1708 2 ip_client ':' port_client 127.0.0.1:34550
1709 3 '[' date ']' [15/Oct/2003:15:24:28]
1710 4 nom_instance relais-tcp
1711 5 nom_serveur Srv1
1712 6 temps_file '/' temps_connect '/' temps_total 0/0/5007
1713 7 octets lus 0
1714 8 etat_terminaison --
1715 9 conn_srv '/' conns_inst '/' conns_processus 1/1/1
1716 10 position en file d'attente srv '/' globale 0/0
willy tarreau982249e2005-12-18 00:57:06 +01001717
willy tarreauc1cae632005-12-17 14:12:23 +01001718Une autre option, 'httplog', fournit plus de détails sur le protocole HTTP,
1719notamment la requête et l'état des cookies. Dans les cas où un mécanisme de
1720surveillance effectuant des connexions et déconnexions fréquentes, polluerait
1721les logs, il suffit d'ajouter l'option 'dontlognull', pour ne plus obtenir une
1722ligne de log pour les sessions n'ayant pas donné lieu à un échange de données
1723(requête ou réponse).
willy tarreauc29948c2005-12-17 13:10:27 +01001724
willy tarreauc5f73ed2005-12-18 01:26:38 +01001725Exemple de journalisation HTTP :
1726--------------------------------
willy tarreau036e1ce2005-12-17 13:46:33 +01001727 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001728 mode http
1729 option httplog
1730 option dontlognull
1731 log 192.168.2.200 local3
1732
willy tarreau532bb552006-05-13 18:40:37 +02001733>>> 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"
willy tarreauc5f73ed2005-12-18 01:26:38 +01001734
1735Exemple plus complet :
willy tarreau036e1ce2005-12-17 13:46:33 +01001736
willy tarreau532bb552006-05-13 18:40:37 +02001737 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"
willy tarreauc5f73ed2005-12-18 01:26:38 +01001738
willy tarreau532bb552006-05-13 18:40:37 +02001739 Champ Format / Description Exemple
1740
1741 1 nom_processus '[' pid ']:' haproxy[18989]:
1742 2 ip_client ':' port_client 10.0.0.1:34552
1743 3 '[' date ']' [15/Oct/2003:15:26:31]
1744 4 nom_instance relais-http
1745 5 nom_serveur Srv1
1746 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt 3183/-1/-1/-1/11215
1747 7 Code_retour_HTTP 503
1748 8 octets lus 0
1749 9 cookies_requête_capturés -
1750 10 cookies_reponse_capturés -
1751 11 etat_terminaison SC--
1752 12 conns_srv '/' conns_inst '/' conns_processus 137/202/205
1753 13 position file serveur '/' globale 0/0
1754 14 '{' entetes_requête_capturés '}' {w.ods.org|Mozilla}
1755 15 '{' entetes_reponse_capturés '}' {}
1756 16 '"' requête_HTTP '"' "HEAD / HTTP/1.0"
willy tarreauc5f73ed2005-12-18 01:26:38 +01001757
1758Note pour les analyseurs de logs : l'URI est TOUJOURS le dernier champ de la ligne, et
1759 commence par un guillemet '"'.
willy tarreau982249e2005-12-18 00:57:06 +01001760
1761Le problème de loguer uniquement en fin de session, c'est qu'il est impossible
1762de savoir ce qui se passe durant de gros transferts ou des sessions longues.
1763Pour pallier à ce problème, une nouvelle option 'logasap' a été introduite dans
willy tarreau64a3cc32005-12-18 01:13:11 +01001764la version 1.1.28 (1.2.1). Lorsqu'elle est activée, le proxy loguera le plus
1765tôt possible, c'est à dire juste avant que ne débutent les transferts de
1766données. Cela signifie, dans le cas du TCP, qu'il loguera toujours le résultat
1767de la connexion vers le serveur, et dans le cas HTTP, qu'il loguera en fin de
willy tarreauc5f73ed2005-12-18 01:26:38 +01001768traitement des en-têtes de la réponse du serveur, auquel cas le nombre d'octets
1769représentera la taille des en-têtes retournés au client.
willy tarreau982249e2005-12-18 00:57:06 +01001770
willy tarreau64a3cc32005-12-18 01:13:11 +01001771Afin d'éviter toute confusion avec les logs normaux, le temps total de
1772transfert et le nombre d'octets transférés sont préfixés d'un signe '+'
willy tarreauc5f73ed2005-12-18 01:26:38 +01001773rappelant que les valeurs réelles sont certainement plus élevées.
willy tarreau982249e2005-12-18 00:57:06 +01001774
1775Exemple :
1776---------
1777
1778 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001779 mode http
1780 option httplog
1781 option dontlognull
1782 option logasap
1783 log 192.168.2.200 local3
willy tarreau982249e2005-12-18 00:57:06 +01001784
willy tarreauc5f73ed2005-12-18 01:26:38 +01001785>>> 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"
willy tarreau982249e2005-12-18 00:57:06 +01001786
1787
willy tarreauc1cae632005-12-17 14:12:23 +010017884.2.3) Chronométrage des événements
1789-----------------------------------
1790Pour déceler des problèmes réseau, les mesures du temps écoulé entre certains
1791événements sont d'une très grande utilité. Tous les temps sont mesurés en
1792millisecondes (ms). En mode HTTP, quatre points de mesure sont rapportés sous
willy tarreau532bb552006-05-13 18:40:37 +02001793la forme Tq/Tw/Tc/Tr/Tt :
willy tarreauc1cae632005-12-17 14:12:23 +01001794
1795 - Tq: temps total de réception de la requête HTTP de la part du client.
1796 C'est le temps qui s'est écoulé entre le moment où le client a établi
1797 sa connexion vers le relais, et le moment où ce dernier a reçu le dernier
1798 en-tête HTTP validant la fin de la requête. Une valeur '-1' ici indique
1799 que la requête complète n'a jamais été reçue.
1800
willy tarreau532bb552006-05-13 18:40:37 +02001801 - Tw: temps total passé dans les files d'attente avant d'obtenir une place
1802 vers un serveur. Ceci tient compte à la fois de la file d'attente globale
1803 et de celle du serveur, et dépend du nombre de requêtes dans la file et du
1804 temps nécessaire au serveur pour compléter les sessions précédentes. La
1805 valeur '-1' indique que la requête a été détruite avant d'atteindre une
1806 file.
1807
willy tarreauc1cae632005-12-17 14:12:23 +01001808 - Tc: temps d'établissement de la connexion TCP du relais vers le serveur.
1809 C'est le temps écoulé entre le moment ou le relais a initié la demande de
1810 connexion vers le serveur, et le moment où ce dernier l'a acquittée, c'est
1811 à dire le temps entre l'envoi du paquet TCP SYN la réception du SYN/ACK.
1812 Une valeur '-1' ici indique que la connexion n'a jamais pu être établie
1813 vers le serveur.
1814
1815 - Tr: temps de réponse du serveur. C'est le temps que le serveur a mis pour
willy tarreauc5f73ed2005-12-18 01:26:38 +01001816 renvoyer la totalité des en-têtes HTTP à partir du moment où il a acquitté
willy tarreauc1cae632005-12-17 14:12:23 +01001817 la connexion. Ca représente exactement le temps de traitement de la
1818 transaction sans le transfert des données associées. Une valeur '-1'
willy tarreauc5f73ed2005-12-18 01:26:38 +01001819 indique que le serveur n'a pas envoyé la totalité de l'en-tête HTTP.
willy tarreauc1cae632005-12-17 14:12:23 +01001820
1821 - Tt: durée de vie totale de la session, entre le moment où la demande de
1822 connexion du client a été acquittée et le moment où la connexion a été
willy tarreau982249e2005-12-18 00:57:06 +01001823 refermée aux deux extrémités (client et serveur). La signification change
1824 un peu si l'option 'logasap' est présente. Dans ce cas, le temps correspond
willy tarreau532bb552006-05-13 18:40:37 +02001825 uniquement à (Tq + Tw + Tc + Tr), et se trouve préfixé d'un signe '+'. On
1826 peut donc déduire Td, le temps de transfert des données, en excluant les
1827 autres temps :
willy tarreauc1cae632005-12-17 14:12:23 +01001828
willy tarreau532bb552006-05-13 18:40:37 +02001829 Td = Tt - (Tq + Tw + Tc + Tr)
willy tarreauc1cae632005-12-17 14:12:23 +01001830
1831 Les temps rapportés à '-1' sont simplement à éliminer de cette équation.
1832
willy tarreau532bb552006-05-13 18:40:37 +02001833En mode TCP ('option tcplog'), seuls les deux indicateurs Tw, Tc et Tt sont
willy tarreauc1cae632005-12-17 14:12:23 +01001834rapportés.
1835
1836Ces temps fournissent de précieux renseignement sur des causes probables de
1837problèmes. Du fait que le protocole TCP définisse des temps de retransmission
1838de 3 secondes, puis 6, 12, etc..., l'observation de temps proches de multiples
1839de 3 secondes indique pratiquement toujours des pertes de paquets liés à un
1840problème réseau (câble ou négociation). De plus, si <Tt> est proche d'une
1841valeur de time-out dans la configuration, c'est souvent qu'une session a été
1842abandonnée sur expiration d'un time-out.
1843
1844Cas les plus fréquents :
1845
1846 - Si Tq est proche de 3000, un paquet a très certainement été perdu entre
1847 le client et le relais.
1848 - Si Tc est proche de 3000, un paquet a très certainement été perdu entre
1849 le relais et le serveur durant la phase de connexion. Cet indicateur
1850 devrait normalement toujours être très bas (moins de quelques dizaines).
1851 - Si Tr est presque toujours inférieur à 3000, et que certaines valeurs
1852 semblent proches de la valeur moyenne majorée de 3000, il y a peut-être
1853 de pertes entre le relais et le serveur.
1854 - Si Tt est légèrement supérieur au time-out, c'est souvent parce que le
1855 client et le serveur utilisent du keep-alive HTTP entre eux et que la
1856 session est maintenue après la fin des échanges. Voir plus loin pour
1857 savoir comment désactiver le keep-alive HTTP.
1858
1859Autres cas ('xx' représentant une valeur quelconque à ignorer) :
willy tarreau532bb552006-05-13 18:40:37 +02001860 -1/xx/xx/xx/Tt: le client n'a pas envoyé sa requête dans le temps imparti ou
willy tarreauc5f73ed2005-12-18 01:26:38 +01001861 a refermé sa connexion sans compléter la requête.
willy tarreau532bb552006-05-13 18:40:37 +02001862 Tq/-1/xx/xx/Tt: Il n'était pas possible de traiter la request, probablement
1863 parce que tous les serveurs étaient hors d'usage.
1864 Tq/Tw/-1/xx/Tt: la connexion n'a pas pu s'établir vers le serveur (refus ou
1865 time-out au bout de Tt-(Tq+Tw) ms).
1866 Tq/Tw/Tc/-1/Tt: le serveur a accepté la connexion mais n'a pas répondu dans
willy tarreauc5f73ed2005-12-18 01:26:38 +01001867 les temps ou bien a refermé sa connexion trop tôt, au bout
willy tarreau532bb552006-05-13 18:40:37 +02001868 de Tt-(Tq+Tw+Tc) ms.
willy tarreauc1cae632005-12-17 14:12:23 +01001869
18704.2.4) Conditions de déconnexion
1871--------------------------------
willy tarreauc5f73ed2005-12-18 01:26:38 +01001872Les logs TCP et HTTP fournissent un indicateur de complétude de la session dans
1873le champ 'etat_terminaison', juste avant le nombre de connexions actives. C'est
1874un champ long de 2 caractères en TCP et de 4 caractères en HTTP, chacun ayant
1875une signification précise :
1876
1877 - sur le premier caractère, un code précisant le premier événement qui a causé
1878 la terminaison de la session :
1879
1880 C : fermeture inattendue de la session TCP de la part du client.
1881
1882 S : fermeture inattendue de la session TCP de la part du serveur, ou
1883 refus explicite de connexion de la part de ce dernier.
1884
1885 P : terminaison prématurée des sessions par le proxy, pour cause
1886 d'imposition d'une limite sur le nombre de connexions, pour cause
1887 de configuration (ex: filtre d'URL), ou parce qu'un contrôle de
1888 sécurité a détecté et bloqué une anomalie dans la réponse du
1889 serveur qui aurait pu causer une fuite d'informations (par exemple,
1890 un cookie cachable).
willy tarreau036e1ce2005-12-17 13:46:33 +01001891
willy tarreauc5f73ed2005-12-18 01:26:38 +01001892 R : une ressource sur le proxy a été épuisée (mémoire, sockets, ports
1893 source, ...). Généralement, cela arrive au cours de l'établissement
1894 d'une connexion, et les logs système doivent contenir une copie de
1895 l'érreur précise.
willy tarreau036e1ce2005-12-17 13:46:33 +01001896
willy tarreauc5f73ed2005-12-18 01:26:38 +01001897 I : une erreur interne a été identifiée par le proxy à la suite d'un
1898 auto-contrôle. Ceci ne doit JAMAIS arriver, et vous êtes encouragés
1899 à remonter n'importe quel log contenant ceci car il s'agira un bug.
willy tarreau036e1ce2005-12-17 13:46:33 +01001900
willy tarreauc5f73ed2005-12-18 01:26:38 +01001901 c : le délai maximal d'attente du client a expiré (clitimeout).
1902
1903 s : le délai maximal d'attente du serveur a expiré (srvtimeout et contimeout)
1904
1905 - : terminaison normale de session.
1906
1907 - sur le second caractère, l'état d'avancement de la session TCP/HTTP lors de
1908 la fermeture :
1909
1910 R : attente d'une REQUETE HTTP complète de la part du client. Rien n'a
1911 été transmis au serveur.
1912
willy tarreau532bb552006-05-13 18:40:37 +02001913 Q : attente en file d'attente (QUEUE) d'une place pour avoir une
1914 connexion vers un serveur. Ne peut apparaître que sur un serveur
1915 possédant un paramètre 'maxconn'. Aucune connexion n'a été envoyée
1916 au serveur.
1917
willy tarreauc5f73ed2005-12-18 01:26:38 +01001918 C : attente de l'établissement d'une CONNEXION vers le serveur. Le
1919 serveur peut au plus avoir vu la tentative de connexion, mais
1920 aucune donnée n'a été échangée.
1921
1922 H : attente, réception ou traitement des en-têtes HTTP ("HEADERS").
1923
1924 D : transfert des DONNEES du serveur vers le client.
1925
1926 L : transfert des dernières ("LAST") données du proxy vers le client,
1927 alors que le serveur a déjà fini.
1928
Willy Tarreau2272dc12006-09-03 10:19:38 +02001929 T : requête bloquée en mode "tarpit" par le proxy. Elle a été maintenue
Willy Tarreau08fa2e32006-09-03 10:47:37 +02001930 ouverte vers le client pendant toute la durée du contimeout ou
1931 jusqu'à l'abandon de la part du client.
Willy Tarreau2272dc12006-09-03 10:19:38 +02001932
willy tarreauc5f73ed2005-12-18 01:26:38 +01001933 - : terminaison normale, après fin de transfert des données.
willy tarreau036e1ce2005-12-17 13:46:33 +01001934
1935 - le troisième caractère indique l'éventuelle identification d'un cookie de
willy tarreauc1cae632005-12-17 14:12:23 +01001936 persistence (uniquement en mode HTTP) :
willy tarreau036e1ce2005-12-17 13:46:33 +01001937
willy tarreauc5f73ed2005-12-18 01:26:38 +01001938 N : aucun cookie de persistence n'a été présenté. C'est généralement le
1939 cas sur les NOUVELLES connexions clients.
1940
1941 I : le client a présenté un cookie INVALIDE ne correspondant à aucun
1942 serveur connu. Ceci peut être dû à un changement de configuration
1943 récent, à des mélanges de noms de cookies entre sites HTTP/HTTPS,
1944 ou à une attaque.
willy tarreau036e1ce2005-12-17 13:46:33 +01001945
willy tarreauc5f73ed2005-12-18 01:26:38 +01001946 D : le client a présenté un cookie correspondant à un serveur hors
1947 d'usage ("DOWN"). Suivant l'option 'persist', il a été renvoyé vers
1948 un autre serveur ou a tout de même tenté de se connecter sur celui
1949 correspondant au cookie.
willy tarreau036e1ce2005-12-17 13:46:33 +01001950
willy tarreauc5f73ed2005-12-18 01:26:38 +01001951 V : le client a présenté un cookie VALIDE et a pu se connecter au
1952 serveur correspondant.
1953
1954 - : non appliquable (pas de cookie positionné dans la configuration).
1955
1956 - le dernier caractère indique l'éventuel traitement effectué sur un cookie de
1957 persistence retrourné par le serveur (uniquement en mode HTTP) :
1958
1959 N : aucun cookie de persistance n'a été fourni par le serveur, et aucun
1960 n'a été inséré.
1961
1962 I : aucun cookie de persistance n'a été fourni par le serveur, et le
1963 proxy en a INSERE un.
1964
willy tarreau197e8ec2005-12-17 14:10:59 +01001965 P : un cookie de persistence a été fourni par le serveur et transmis
willy tarreauc5f73ed2005-12-18 01:26:38 +01001966 tel quel ("PASSIF").
1967
1968 R : le cookie retourné par le serveur a été REECRIT par le proxy.
1969
1970 D : le cookie présenté par le serveur a été DETRUIT par le proxy pour
1971 ne pas être retourné au client.
1972
1973 - : non appliquable
1974
1975
1976La combinaison des deux premiers indicateurs fournit une grande quantitié
1977d'informations sur ce qui se passait lorsque la session s'est terminée. Cela
1978peut notamment aider à détecter une saturation de serveur, des troubles réseau,
1979des épuisements de ressources système locales, des attaques, etc...
willy tarreau036e1ce2005-12-17 13:46:33 +01001980
willy tarreauc5f73ed2005-12-18 01:26:38 +01001981Les combinaisons d'indicateurs les plus fréquentes sont énumérées ici.
1982
1983 Indic Raison
1984 CR Le client a abandonné avant d'émettre une requête complète. Il est
1985 très probable que la requête ait été tapée à la main dans un client
1986 telnet et abortée trop tôt.
1987
1988 cR Le temps imparti au client a expiré avant réception d'une requête
1989 complète. Ceci est parfois causé par un paramètre TCP MSS trop élevé
1990 sur le client pour des réseaux PPPoE sur ADSL qui ne peuvent pas
1991 transporter des paquets entiers, ou par des clients qui énvoient des
1992 requêtes à la main et ne tapent pas assez vite.
1993
1994 SC Le serveur a explicitement refusé la connexion (le proxy a reçu un
1995 RST TCP ou un message ICMP en retour). Dans certains cas, cela peut
1996 être la couche réseau qui indique au proxy que le serveur n'est pas
1997 joignable (p.ex: pas de route, pas de réponse ARP en local, etc...)
1998
1999 sC La connexion au serveur n'a pas pu s'établir dans le temps imparti.
2000
2001 PC Le proxy a refusé d'établir une connexion au serveur parce que le
2002 nombre de connexions a atteint la limite 'maxconn' (global ou de
2003 l'instance). Le paramètre 'maxconn' de l'instance pourrait être
2004 augmenté, tout comme le paramètre 'maxconn' global.
2005
2006 RC Une ressource locale a été épuisée (mémoire, sockets, ports source),
2007 empêchant la connexion au serveur de s'établir. Les logs d'erreurs
2008 diront précisément ce qui manquait. Dans tous les cas, le seul remède
2009 consiste à affiner le paramétrage système.
2010
2011 cH Le temps imparti au client a expiré au cours d'une requête POST. Ceci
2012 est parfois causé par un paramètre TCP MSS trop élevé sur le client
2013 pour des réseaux PPPoE sur ADSL qui ne peuvent pas transporter des
2014 paquets entiers.
2015
willy tarreau078c79a2006-05-13 12:23:58 +02002016 CH Le client a abandonné alors qu'il attendait un début de réponse de la
2017 part du serveur. Cela peut être causé par le serveur qui mettait trop
2018 de temps à répondre, ou par un client cliquant précipitamment sur le
2019 bouton 'Stop'.
2020
2021 CQ Le client a abandonné alors que sa session était mise en file
2022 d'attente pour obtenir un serveur avec suffisamment de connexions
2023 libres pour l'accepter. Cela signifie soit que l'ensemble des
2024 serveurs étaient saturés, soit que le serveur assigné a mis trop de
2025 temps à répondre.
2026
Willy Tarreau08fa2e32006-09-03 10:47:37 +02002027 CT Le client a abandonné alors que sa session était bloquée en mode
2028 tarpit.
2029
willy tarreau078c79a2006-05-13 12:23:58 +02002030 sQ La session a attendu trop longtemps en file d'attente et a été
2031 expirée.
2032
willy tarreauc5f73ed2005-12-18 01:26:38 +01002033 SH Le serveur a aborté brutalement alors qu'il devait envoyer ses
2034 en-têtes. En général, cela indique qu'il a crashé.
2035
2036 sH Le serveur n'a pas pu répondre durant le temps imparti, ce qui montre
2037 des transactions trop longues, probablement causées par un back-end
2038 saturé. Les seules solutions sont de corriger le problème sur
2039 l'application, d'accroître le paramètre 'srvtimeout' pour supporter
2040 des attentes plus longues au risque que les clients abandonnent à
2041 leur tour, ou bien d'ajouter des serveurs.
2042
2043 PR Le proxy a bloqué une requête du client, soit à cause d'une syntaxe
2044 HTTP invalide, auquel cas il a renvoyé une erreur HTTP 400 au client,
2045 soit à cause d'une requête validant un filtre d'interdiction, auquel
2046 cas le proxy a renvoyé une erreur HTTP 403.
2047
2048 PH Le proxy a bloqué la réponse du serveur parce qu'elle était invalide,
2049 incomplète, dangereuse ('cache control'), ou parce qu'elle validait
2050 un filtre de sécurité. Dans tous les cas, une erreur HTTP 502 est
2051 renvoyée au client.
2052
Willy Tarreau2272dc12006-09-03 10:19:38 +02002053 PT Le proxy a bloqué une requête du client et a maintenu sa connection
2054 ouverte avant de lui retourner une erreur "500 server error". Rien
2055 n'a été envoyé au serveur.
2056
willy tarreauc5f73ed2005-12-18 01:26:38 +01002057 cD Le client n'a pas lu de données pendant le temps qui lui était
2058 imparti. Ceci est souvent causé par des problèmes réseau côté client.
2059
2060 CD Le client a aborté sa connection de manière inattendue pendant le
2061 transfert des données. Ceci est provoqué soit par le crash d'un
2062 navigateur, ou par une session en HTTP keep-alive entre le serveur
2063 et le client terminée en premier par le client.
2064
2065 sD Le serveur n'a rien fait durant le temps imparti par le paramètre
2066 'srvtimeout'. Ceci est souvent causé par des timeouts trop courts
2067 sur des équipements de niveau 4 (firewalls, répartiteurs de charge)
2068 situés entre le proxy et le serveur.
2069
20704.2.5) Caractères non-imprimables
2071---------------------------------
2072Depuis la version 1.1.29, les caractères non-imprimables ne sont plus envoyés
2073tels quels dans les lignes de logs, mais inscrits sous la forme de deux chiffres
2074hexadécimaux, préfixés du caractère d'échappement '#'. Les seuls caractères
2075dorénavant logués tels quels sont compris entre 32 et 126. Bien évidemment, le
2076caractère d'échappement '#' est lui-même encodé afin de lever l'ambiguité. Il en
2077est de même pour le caractère '"', ainsi que les caractères '{', '|' et '}' pour
2078les en-têtes.
2079
20804.2.6) Capture d'en-têtes HTTP et de cookies
2081--------------------------------------------
2082La version 1.1.23 a apporté la capture des cookies, et la version 1.1.29 la
2083capture d'en-têtes. Tout ceci est effectué en utilisant le mot-clé 'capture'.
2084
2085Les captures de cookies facilitent le suivi et la reconstitution d'une session
2086utilisateur. La syntaxe est la suivante :
willy tarreau8337c6b2005-12-17 13:41:01 +01002087
2088 capture cookie <préfixe_cookie> len <longueur_capture>
2089
willy tarreauc5f73ed2005-12-18 01:26:38 +01002090Ceci activera la capture de cookies à la fois dans les requêtes et dans les
2091réponses. De cette manière, il devient facile de détecter lorsqu'un utilisateur
2092bascule sur une nouvelle session par exemple, car le serveur lui réassignera un
2093nouveau cookie.
2094
willy tarreau8337c6b2005-12-17 13:41:01 +01002095Le premier cookie dont le nom commencera par <préfixe_cookie> sera capturé, et
2096transmis sous la forme "NOM=valeur", sans toutefois, excéder <longueur_capture>
2097caractères (64 au maximum). Lorsque le nom du cookie est fixe et connu, on peut
2098le suffixer du signe "=" pour s'assurer qu'aucun autre cookie ne prendra sa
2099place dans les logs.
2100
2101Exemples :
2102----------
2103 # capture du premier cookie dont le nom commence par "ASPSESSION"
2104 capture cookie ASPSESSION len 32
2105
2106 # capture du premier cookie dont le nom est exactement "vgnvisitor"
2107 capture cookie vgnvisitor= len 32
2108
willy tarreau036e1ce2005-12-17 13:46:33 +01002109Dans les logs, le champ précédant l'indicateur de complétude contient le cookie
willy tarreau64a3cc32005-12-18 01:13:11 +01002110positionné par le serveur, précédé du cookie positionné par le client. Chacun
2111de ces champs est remplacé par le signe "-" lorsqu'aucun cookie n'est fourni
willy tarreauc5f73ed2005-12-18 01:26:38 +01002112par le client ou le serveur, ou lorsque l'option est désactivée..
2113
2114Les captures d'en-têtes ont un rôle complètement différent. Elles sont utiles
2115pour suivre un identifiant de requête globalement unique positionné par un
2116autre proxy en amont, pour journaliser les noms de serveurs virtuels, les types
2117de clients web, la longueur des POST, les 'referrers', etc. Dans la réponse, on
2118peut chercher des informations relatives à la longueur annoncée de la réponse,
2119le fonctionnement attendu du cache, ou encore la localisation d'un objet en cas
2120de redirection. Tout comme pour les captures de cookies, il est possible
2121d'inclure les en-têtes de requêtes et de réponse simultanément. La syntaxe est
2122la suivante :
2123
2124 capture request header <nom> len <longueur max>
2125 capture response header <nom> len <longueur max>
2126
2127Note: Les noms d'en-têtes ne sont pas sensibles à la casse.
willy tarreau8337c6b2005-12-17 13:41:01 +01002128
willy tarreauc5f73ed2005-12-18 01:26:38 +01002129Exemples:
2130---------
2131 # conserver le nom du serveur virtuel accédé par le client
2132 capture request header Host len 20
2133 # noter la longueur des données envoyées dans un POST
2134 capture request header Content-Length len 10
2135
2136 # noter le fonctionnement attendu du cache par le serveur
2137 capture response header Cache-Control len 8
2138 # noter l'URL de redirection
2139 capture response header Location len 20
2140
2141Les en-têtes non trouvés sont logués à vide, et si un en-tête apparait plusieurs
2142fois, seule la dernière occurence sera conservée. Les en-têtes de requête sont
2143regroupés entre deux accolades '{' et '}' dans l'ordre de leur déclaration, et
2144chacun séparés par une barre verticale '|', sans aucun espace. Les en-têtes de
2145réponse sont présentés de la même manière, mais après un espace suivant le bloc
2146d'en-tête de requête. Le tout précède la requête HTTP. Exemple :
2147
2148 Config:
2149
2150 capture request header Host len 20
2151 capture request header Content-Length len 10
2152 capture request header Referer len 20
2153 capture response header Server len 20
2154 capture response header Content-Length len 10
2155 capture response header Cache-Control len 8
2156 capture response header Via len 20
2157 capture response header Location len 20
2158
2159 Log :
2160
willy tarreau532bb552006-05-13 18:40:37 +02002161 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/"
2162 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"
2163 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"
willy tarreauc5f73ed2005-12-18 01:26:38 +01002164
21654.2.7) Exemples de logs
willy tarreauc1cae632005-12-17 14:12:23 +01002166-----------------------
willy tarreau532bb552006-05-13 18:40:37 +02002167- 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"
willy tarreauc1cae632005-12-17 14:12:23 +01002168 => requête longue (6.5s) saisie à la main avec un client telnet. Le serveur a
2169 répondu en 147 ms et la session s'est terminée normalement ('----')
willy tarreauc29948c2005-12-17 13:10:27 +01002170
willy tarreau532bb552006-05-13 18:40:37 +02002171- 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"
2172 => Idem, mais la requête a été mise en attente dans la file globale derrière
2173 9 autres requêtes déjà présentes, et y a attendu 1230 ms.
2174
2175- 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"
willy tarreau982249e2005-12-18 00:57:06 +01002176 => requête pour un long transfert. L'option 'logasap' était spécifiée donc le
2177 log a été généré juste avant le transfert de données. Le serveur a répondu
willy tarreauc5f73ed2005-12-18 01:26:38 +01002178 en 14 ms, 243 octets d'en-têtes ont été transférés au client, et le temps
willy tarreau982249e2005-12-18 00:57:06 +01002179 total entre l'accept() et le premier octet de donnée est de 30 ms.
2180
willy tarreau532bb552006-05-13 18:40:37 +02002181- 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"
willy tarreau982249e2005-12-18 00:57:06 +01002182 => le proxy a bloqué une réponse du serveur soit à cause d'un filtre 'rspdeny'
2183 ou 'rspideny', soit parce qu'il a détecté un risque de fuite sensible
2184 d'informations risquant d'être cachées. Dans ce cas, la réponse est
2185 remplacée par '502 bad gateway'.
2186
willy tarreau532bb552006-05-13 18:40:37 +02002187- 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 ""
willy tarreauc1cae632005-12-17 14:12:23 +01002188 => Le client n'a pas envoyé sa requête et a refermé la connexion lui-même
willy tarreauc5f73ed2005-12-18 01:26:38 +01002189 ('C---') au bout de 8.5s, alors que le relais attendait l'en-tête ('-R--').
willy tarreauc1cae632005-12-17 14:12:23 +01002190 Aucune connexion n'a été envoyée vers le serveur.
willy tarreau0f7af912005-12-17 12:21:26 +01002191
willy tarreau532bb552006-05-13 18:40:37 +02002192- 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 ""
willy tarreauc1cae632005-12-17 14:12:23 +01002193 => Le client n'a pas envoyé sa requête et son time-out a expiré ('c---') au
willy tarreauc5f73ed2005-12-18 01:26:38 +01002194 bout de 50s, alors que le relais attendait l'en-tête ('-R--'). Aucune
willy tarreauc1cae632005-12-17 14:12:23 +01002195 connexion n'a été envoyée vers le serveur, mais le relais a tout de même
2196 pu renvoyer un message 408 au client.
2197
willy tarreauc5f73ed2005-12-18 01:26:38 +01002198- haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28] relais-tcp Srv1 0/5007 0 cD
2199 => log en mode 'tcplog'. Expiration du time-out côté client ('cD') au bout de
2200 5s.
willy tarreauc1cae632005-12-17 14:12:23 +01002201
willy tarreau532bb552006-05-13 18:40:37 +02002202- 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"
willy tarreauc1cae632005-12-17 14:12:23 +01002203 => La requête client met 3s à entrer (peut-être un problème réseau), et la
2204 connexion ('SC--') vers le serveur échoue au bout de 4 tentatives de 2
willy tarreau532bb552006-05-13 18:40:37 +02002205 secondes (retries 3 dans la conf), puis un code 503 est retourné au
2206 client. Il y avait 115 connexions sur ce serveur, 202 connexions sur cette
2207 instance, et 205 sur l'ensemble des instances pour ce processus. Il est
2208 possible que le serveur ait refusé la connexion parce qu'il y en avait
2209 déjà trop d'établies.
willy tarreau4302f492005-12-18 01:00:37 +01002210
willy tarreau4302f492005-12-18 01:00:37 +01002211
willy tarreauc5f73ed2005-12-18 01:26:38 +010022124.3) Modification des en-têtes HTTP
willy tarreauc29948c2005-12-17 13:10:27 +01002213----------------------------------
2214En mode HTTP uniquement, il est possible de remplacer certains en-têtes dans la
2215requête et/ou la réponse à partir d'expressions régulières. Il est également
willy tarreau64a3cc32005-12-18 01:13:11 +01002216possible de bloquer certaines requêtes en fonction du contenu des en-têtes ou
2217de la requête. Une limitation cependant : les en-têtes fournis au milieu de
willy tarreauc29948c2005-12-17 13:10:27 +01002218connexions persistentes (keep-alive) ne sont pas vus car ils sont considérés
2219comme faisant partie des échanges de données consécutifs à la première requête.
2220Les données ne sont pas affectées, ceci ne s'applique qu'aux en-têtes.
willy tarreau0f7af912005-12-17 12:21:26 +01002221
2222La syntaxe est :
willy tarreauc29948c2005-12-17 13:10:27 +01002223 reqadd <string> pour ajouter un en-tête dans la requête
2224 reqrep <search> <replace> pour modifier la requête
2225 reqirep <search> <replace> idem sans distinction majuscules/minuscules
2226 reqdel <search> pour supprimer un en-tête dans la requête
2227 reqidel <search> idem sans distinction majuscules/minuscules
willy tarreauc5f73ed2005-12-18 01:26:38 +01002228 reqallow <search> autoriser la requête si un en-tête valide <search>
willy tarreauc29948c2005-12-17 13:10:27 +01002229 reqiallow <search> idem sans distinction majuscules/minuscules
willy tarreauc5f73ed2005-12-18 01:26:38 +01002230 reqdeny <search> interdire la requête si un en-tête valide <search>
willy tarreau240afa62005-12-17 13:14:35 +01002231 reqideny <search> idem sans distinction majuscules/minuscules
willy tarreauc5f73ed2005-12-18 01:26:38 +01002232 reqpass <search> inhibe ces actions sur les en-têtes validant <search>
willy tarreau036e1ce2005-12-17 13:46:33 +01002233 reqipass <search> idem sans distinction majuscules/minuscules
Willy Tarreau2272dc12006-09-03 10:19:38 +02002234 reqtarpit <search> bloquer et maintenir une request validant <search>
2235 reqitarpit <search> idem sans distinction majuscules/minuscules
willy tarreau5cbea6f2005-12-17 12:48:26 +01002236
willy tarreau036e1ce2005-12-17 13:46:33 +01002237 rspadd <string> pour ajouter un en-tête dans la réponse
2238 rsprep <search> <replace> pour modifier la réponse
2239 rspirep <search> <replace> idem sans distinction majuscules/minuscules
2240 rspdel <search> pour supprimer un en-tête dans la réponse
2241 rspidel <search> idem sans distinction majuscules/minuscules
willy tarreau982249e2005-12-18 00:57:06 +01002242 rspdeny <search> remplace la réponse par un HTTP 502 si un
willy tarreauc5f73ed2005-12-18 01:26:38 +01002243 en-tête valide <search>
willy tarreau982249e2005-12-18 00:57:06 +01002244 rspideny <search> idem sans distinction majuscules/minuscules
willy tarreau5cbea6f2005-12-17 12:48:26 +01002245
willy tarreau0f7af912005-12-17 12:21:26 +01002246
willy tarreau036e1ce2005-12-17 13:46:33 +01002247<search> est une expression régulière compatible POSIX regexp supportant le
2248groupage par parenthèses (sans les '\'). Les espaces et autres séparateurs
2249doivent êtres précédés d'un '\' pour ne pas être confondus avec la fin de la
2250chaîne. De plus, certains caractères spéciaux peuvent être précédés d'un
2251backslach ('\') :
willy tarreau5cbea6f2005-12-17 12:48:26 +01002252
2253 \t pour une tabulation
2254 \r pour un retour charriot
2255 \n pour un saut de ligne
2256 \ pour différencier un espace d'un séparateur
2257 \# pour différencier un dièse d'un commentaire
willy tarreau036e1ce2005-12-17 13:46:33 +01002258 \\ pour utiliser un backslash dans la regex
2259 \\\\ pour utiliser un backslash dans le texte
willy tarreau5cbea6f2005-12-17 12:48:26 +01002260 \xXX pour un caractère spécifique XX (comme en C)
willy tarreau0f7af912005-12-17 12:21:26 +01002261
willy tarreau0f7af912005-12-17 12:21:26 +01002262
willy tarreau5cbea6f2005-12-17 12:48:26 +01002263<replace> contient la chaîne remplaçant la portion vérifiée par l'expression.
2264Elle peut inclure les caractères spéciaux ci-dessus, faire référence à un
2265groupe délimité par des parenthèses dans l'expression régulière, par sa
Willy Tarreau2272dc12006-09-03 10:19:38 +02002266position numérale. Les positions vont de 0 à 9, et sont codées par un '\'
2267suivi du chiffre désiré (0 désignant la ligne complète). Il est également
2268possible d'insérer un caractère non imprimable (utile pour le saut de ligne)
2269inscrivant '\x' suivi du code hexadécimal de ce caractère (comme en C).
willy tarreau5cbea6f2005-12-17 12:48:26 +01002270
2271<string> représente une chaîne qui sera ajoutée systématiquement après la
willy tarreauc29948c2005-12-17 13:10:27 +01002272dernière ligne d'en-tête.
willy tarreau5cbea6f2005-12-17 12:48:26 +01002273
2274Remarques :
willy tarreau197e8ec2005-12-17 14:10:59 +01002275-----------
willy tarreau5cbea6f2005-12-17 12:48:26 +01002276 - la première ligne de la requête et celle de la réponse sont traitées comme
willy tarreauc29948c2005-12-17 13:10:27 +01002277 des en-têtes, ce qui permet de réécrire des URL et des codes d'erreur.
willy tarreau5cbea6f2005-12-17 12:48:26 +01002278 - 'reqrep' est l'équivalent de 'cliexp' en version 1.0, et 'rsprep' celui de
2279 'srvexp'. Ces noms sont toujours supportés mais déconseillés.
2280 - pour des raisons de performances, le nombre total de caractères ajoutés sur
willy tarreau535ae7a2005-12-17 12:58:00 +01002281 une requête ou une réponse est limité à 4096 depuis la version 1.1.5 (cette
2282 limite était à 256 auparavant). Cette valeur est modifiable dans le code.
2283 Pour un usage temporaire, on peut gagner de la place en supprimant quelques
willy tarreauc5f73ed2005-12-18 01:26:38 +01002284 en-têtes inutiles avant les ajouts.
willy tarreau982249e2005-12-18 00:57:06 +01002285 - une requête bloquée produira une réponse "HTTP 403 forbidden" tandis qu'une
2286 réponse bloquée produira une réponse "HTTP 502 Bad gateway".
Willy Tarreau2272dc12006-09-03 10:19:38 +02002287 - une requête bloquée par 'reqtarpit' sera maintenue pendant une durée égale
Willy Tarreau08fa2e32006-09-03 10:47:37 +02002288 au paramètre 'contimeout', ou jusqu'à l'abandon du client. Rien ne sera
2289 envoyé au serveur. Lorsque le temps alloué expire, le proxy répondra avec
2290 une réponse "500 server error" de sorte que l'attaquant ne suspecte pas
2291 qu'il ait été bloqué. Les logs rapporteront aussi ce code 500, mais les
2292 flags de terminaison indiqueront "PT".
willy tarreau0f7af912005-12-17 12:21:26 +01002293
2294Exemples :
willy tarreau197e8ec2005-12-17 14:10:59 +01002295----------
willy tarreauc5f73ed2005-12-18 01:26:38 +01002296 ###### a few examples ######
willy tarreau197e8ec2005-12-17 14:10:59 +01002297
willy tarreauc5f73ed2005-12-18 01:26:38 +01002298 # rewrite 'online.fr' instead of 'free.fr' for GET and POST requests
2299 reqrep ^(GET\ .*)(.free.fr)(.*) \1.online.fr\3
2300 reqrep ^(POST\ .*)(.free.fr)(.*) \1.online.fr\3
willy tarreau197e8ec2005-12-17 14:10:59 +01002301
willy tarreauc5f73ed2005-12-18 01:26:38 +01002302 # force proxy connections to close
2303 reqirep ^Proxy-Connection:.* Proxy-Connection:\ close
2304 # rewrite locations
2305 rspirep ^(Location:\ )([^:]*://[^/]*)(.*) \1\3
willy tarreau197e8ec2005-12-17 14:10:59 +01002306
willy tarreauc5f73ed2005-12-18 01:26:38 +01002307 ###### A full configuration being used on production ######
willy tarreau0f7af912005-12-17 12:21:26 +01002308
willy tarreau197e8ec2005-12-17 14:10:59 +01002309 # Every header should end with a colon followed by one space.
2310 reqideny ^[^:\ ]*[\ ]*$
2311
2312 # block Apache chunk exploit
2313 reqideny ^Transfer-Encoding:[\ ]*chunked
2314 reqideny ^Host:\ apache-
2315
2316 # block annoying worms that fill the logs...
2317 reqideny ^[^:\ ]*\ .*(\.|%2e)(\.|%2e)(%2f|%5c|/|\\\\)
2318 reqideny ^[^:\ ]*\ ([^\ ]*\ [^\ ]*\ |.*%00)
2319 reqideny ^[^:\ ]*\ .*<script
2320 reqideny ^[^:\ ]*\ .*/(root\.exe\?|cmd\.exe\?|default\.ida\?)
2321
Willy Tarreau2272dc12006-09-03 10:19:38 +02002322 # tarpit attacks on the login page.
2323 reqtarpit ^[^:\ ]*\ .*\.php?login=[^0-9]
2324
willy tarreau197e8ec2005-12-17 14:10:59 +01002325 # allow other syntactically valid requests, and block any other method
2326 reqipass ^(GET|POST|HEAD|OPTIONS)\ /.*\ HTTP/1\.[01]$
2327 reqipass ^OPTIONS\ \\*\ HTTP/1\.[01]$
2328 reqideny ^[^:\ ]*\
2329
2330 # force connection:close, thus disabling HTTP keep-alive
willy tarreauc5f73ed2005-12-18 01:26:38 +01002331 option httpclos
willy tarreau197e8ec2005-12-17 14:10:59 +01002332
willy tarreauc5f73ed2005-12-18 01:26:38 +01002333 # change the server name
willy tarreau197e8ec2005-12-17 14:10:59 +01002334 rspidel ^Server:\
2335 rspadd Server:\ Formilux/0.1.8
2336
willy tarreau0f7af912005-12-17 12:21:26 +01002337
willy tarreau982249e2005-12-18 00:57:06 +01002338De plus, l'option 'forwardfor' ajoute l'adresse IP du client dans un champ
willy tarreauc1cae632005-12-17 14:12:23 +01002339'X-Forwarded-For' de la requête, ce qui permet à un serveur web final de
Willy Tarreau7ac51f62007-03-25 16:00:04 +02002340connaître l'adresse IP du client initial. Depuis la version 1.3.8, il est
2341possible de préciser le mot-clé "except" suivi d'une adresse ou un réseau
2342IP source pour lequel l'entête ne sera pas ajouté. C'est très pratique dans le
2343cas où un autre reverse-proxy ajoutant déjà l'entête est installé sur la même
2344machine ou dans une DMZ connue. Le cas le plus fréquent est lié à l'utilisation
2345de stunnel en local.
willy tarreauc1cae632005-12-17 14:12:23 +01002346
willy tarreau982249e2005-12-18 00:57:06 +01002347Enfin, l'option 'httpclose' apparue dans la version 1.1.28/1.2.1 supprime tout
willy tarreauc5f73ed2005-12-18 01:26:38 +01002348en-tête de type 'Connection:' et ajoute 'Connection: close' dans les deux sens.
willy tarreau982249e2005-12-18 00:57:06 +01002349Ceci simplifie la désactivation du keep-alive HTTP par rapport à l'ancienne
2350méthode impliquant 4 règles.
2351
willy tarreauc1cae632005-12-17 14:12:23 +01002352Exemple :
2353---------
2354 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01002355 mode http
2356 log global
2357 option httplog
2358 option dontlognull
Willy Tarreau7ac51f62007-03-25 16:00:04 +02002359 option forwardfor except 127.0.0.1/8
willy tarreauc5f73ed2005-12-18 01:26:38 +01002360 option httpclose
willy tarreauc1cae632005-12-17 14:12:23 +01002361
Willy TARREAU767ba712006-03-01 22:40:50 +01002362Notons que certains serveurs HTTP ne referment pas nécessairement la session
2363TCP en fin de traitement lorsqu'ils reçoivent un entête 'Connection: close',
2364ce qui se traduit par des grands nombres de sessions établies et des temps
2365globaux très longs sur les requêtes. Pour contourner ce problème, la version
23661.2.9 apporte une nouvelle option 'forceclose' qui referme la connexion sortant
2367vers le serveur dès qu'il commence à répondre et seulement si le tampon de
2368requête est vide. Attention toutefois à ne PAS utiliser cette option si des
2369méthodes CONNECT sont attendues entre le client et le serveur. L'option
2370'forceclose' implique l'option 'httpclose'.
2371
2372Exemple :
2373---------
2374 listen http_proxy 0.0.0.0:80
2375 mode http
2376 log global
2377 option httplog
2378 option dontlognull
2379 option forwardfor
2380 option forceclose
2381
2382
willy tarreauc29948c2005-12-17 13:10:27 +010023834.4) Répartition avec persistence
2384---------------------------------
willy tarreau5cbea6f2005-12-17 12:48:26 +01002385La combinaison de l'insertion de cookie avec la répartition de charge interne
2386permet d'assurer une persistence dans les sessions HTTP d'une manière
2387pratiquement transparente pour les applications. Le principe est simple :
willy tarreau96d40372005-12-17 13:11:56 +01002388 - attribuer une valeur d'un cookie à chaque serveur
willy tarreau5cbea6f2005-12-17 12:48:26 +01002389 - effectuer une répartition interne
willy tarreau240afa62005-12-17 13:14:35 +01002390 - insérer un cookie dans les réponses issues d'une répartition uniquement,
2391 et faire en sorte que des caches ne mémorisent pas ce cookie.
2392 - cacher ce cookie à l'application lors des requêtes ultérieures.
willy tarreau5cbea6f2005-12-17 12:48:26 +01002393
2394Exemple :
willy tarreau8337c6b2005-12-17 13:41:01 +01002395---------
willy tarreau5cbea6f2005-12-17 12:48:26 +01002396 listen application 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01002397 mode http
2398 cookie SERVERID insert nocache indirect
2399 balance roundrobin
2400 server srv1 192.168.1.1:80 cookie server01 check
2401 server srv2 192.168.1.2:80 cookie server02 check
willy tarreau5cbea6f2005-12-17 12:48:26 +01002402
willy tarreau0174f312005-12-18 01:02:42 +01002403L'autre solution apportée par les versions 1.1.30 et 1.2.3 est de réutiliser un
2404cookie en provenance du serveur et de lui préfixer l'identifiant du serveur.
2405Dans ce cas, ne pas oublier de forcer le mode "httpclose" pour empêcher le
2406client et le serveur de travailler en mode "keep-alive" afin que le proxy
2407puisse corriger le nom du cookie dans toutes les futures requêtes.
2408
2409 listen application 0.0.0.0:80
2410 mode http
2411 cookie JSESSIONID prefix
2412 balance roundrobin
willy tarreau598da412005-12-18 01:07:29 +01002413 server srv1 192.168.1.1:80 cookie srv1 check
2414 server srv2 192.168.1.2:80 cookie srv2 check
willy tarreau0174f312005-12-18 01:02:42 +01002415 option httpclose
2416
2417
willy tarreau982249e2005-12-18 00:57:06 +010024184.5) Protection contre les fuites d'informations du serveur
2419-----------------------------------------------------------
willy tarreau64a3cc32005-12-18 01:13:11 +01002420Dans les versions 1.1.28 et 1.2.1, une nouvelle option 'checkcache' a été
willy tarreauc5f73ed2005-12-18 01:26:38 +01002421créée. Elle sert à inspecter minutieusement les en-têtes 'Cache-control',
willy tarreau64a3cc32005-12-18 01:13:11 +01002422'Pragma', et 'Set-cookie' dans les réponses serveur pour déterminer s'il y a
2423un risque de cacher un cookie sur un proxy côté client. Quand cette option est
2424activée, les seules réponses qui peuvent être retournées au client sont :
willy tarreauc5f73ed2005-12-18 01:26:38 +01002425 - toutes celles qui n'ont pas d'en-tête 'Set-cookie' ;
willy tarreau982249e2005-12-18 00:57:06 +01002426 - toutes celles qui ont un code de retour autre que 200, 203, 206, 300, 301,
willy tarreauc5f73ed2005-12-18 01:26:38 +01002427 410, sauf si le serveur a positionné un en-tête 'Cache-control: public' ;
willy tarreau982249e2005-12-18 00:57:06 +01002428 - celles qui font suite à une requête POST, sauf si le serveur a positionné
willy tarreauc5f73ed2005-12-18 01:26:38 +01002429 un en-tête 'Cache-control: public' ;
2430 - celles qui ont un en-tête 'Pragma: no-cache' ;
2431 - celles qui ont un en-tête 'Cache-control: private' ;
2432 - celles qui ont un en-tête 'Cache-control: no-store' ;
2433 - celles qui ont un en-tête 'Cache-control: max-age=0' ;
2434 - celles qui ont un en-tête 'Cache-control: s-maxage=0' ;
2435 - celles qui ont un en-tête 'Cache-control: no-cache' ;
2436 - celles qui ont un en-tête 'Cache-control: no-cache="set-cookie"' ;
2437 - celles qui ont un en-tête 'Cache-control: no-cache="set-cookie,'
willy tarreau982249e2005-12-18 00:57:06 +01002438 (autorisant d'autres champs après set-cookie).
willy tarreau8337c6b2005-12-17 13:41:01 +01002439
willy tarreau982249e2005-12-18 00:57:06 +01002440Si une réponse ne respecte pas ces pré-requis, alors elle sera bloquée de la
2441même manière que s'il s'agissait d'un filtre 'rspdeny', avec en retour un
2442message "HTTP 502 bad gateway". L'état de session montre "PH--" ce qui veut
2443dire que c'est le proxy qui a bloqué la réponse durant le traitement des
willy tarreauc5f73ed2005-12-18 01:26:38 +01002444en-têtes. De plus, un message d'alerte sera envoyé dans les logs de sorte que
willy tarreau982249e2005-12-18 00:57:06 +01002445l'administrateur sache qu'il y a une action correctrice à entreprendre.
2446
24474.6) Personalisation des erreurs
2448--------------------------------
willy tarreau8337c6b2005-12-17 13:41:01 +01002449Certaines situations conduisent à retourner une erreur HTTP au client :
2450 - requête invalide ou trop longue => code HTTP 400
2451 - requête mettant trop de temps à venir => code HTTP 408
2452 - requête interdite (bloquée par un reqideny) => code HTTP 403
2453 - erreur interne du proxy => code HTTP 500
2454 - le serveur a retourné une réponse incomplète ou invalide => code HTTP 502
2455 - aucun serveur disponible pour cette requête => code HTTP 503
2456 - le serveur n'a pas répondu dans le temps imparti => code HTTP 504
2457
2458Un message d'erreur succint tiré de la RFC accompagne ces codes de retour.
2459Cependant, en fonction du type de clientèle, on peut préférer retourner des
Willy Tarreau3f49b302007-06-11 00:29:26 +02002460pages personnalisées. Ceci est possible de deux manières, l'une reposant sur
2461une redirection vers un serveur connu, et l'autre consistant à retourner un
2462fichier local.
2463
24644.6.1) Redirection
2465------------------
2466Une redirection d'erreur est assurée par le biais de la commande "errorloc" :
willy tarreau8337c6b2005-12-17 13:41:01 +01002467
2468 errorloc <code_HTTP> <location>
2469
2470Au lieu de générer une erreur HTTP <code_HTTP> parmi les codes cités ci-dessus,
2471le proxy génèrera un code de redirection temporaire (HTTP 302) vers l'adresse
2472d'une page précisée dans <location>. Cette adresse peut être relative au site,
2473ou absolue. Comme cette réponse est traîtée par le navigateur du client
2474lui-même, il est indispensable que l'adresse fournie lui soit accessible.
2475
2476Exemple :
2477---------
2478 listen application 0.0.0.0:80
2479 errorloc 400 /badrequest.html