[doc] updated english and french docs with source and weight options.

doc/haproxy-en.txt

@@ -2,9 +2,9 @@
                              H A - P r o x y
                             Reference  Manual
                            -------------------
-                              version 1.2.9
+                              version 1.2.12
                               willy tarreau
-                                2006/03/01
+                                2006/04/15
 
 ============
 | Abstract |
@@ -42,11 +42,14 @@ There are only a few command line options :
        exits with code 1 if a syntax error was found.
     -p <pidfile> asks the process to write down each of its children's
        pids to this file in daemon mode.
+    -sf specifies a list of pids to send a FINISH signal to after startup.
+    -st specifies a list of pids to send a TERMINATE signal to after startup.
     -s shows statistics (only if compiled in)
     -l shows even more statistics (implies '-s')
     -de disables use of epoll()
     -dp disables use of poll()
-
+    -db disables background mode (stays in foreground, useful for debugging)
+    -m <megs> enforces a memory usage limit to a maximum of <megs> megabytes.
 
 The maximal number of connections per proxy is used as the default parameter for
 each instance for which the 'maxconn' paramter is not set in the 'listen' section.
@@ -59,9 +62,24 @@ section. When the proxy runs in this mode, it dumps every connections,
 disconnections, timestamps, and HTTP headers to stdout. This should NEVER
 be used in an init script since it will prevent the system from starting up.
 
+For debugging, the '-db' option is very useful as it temporarily disables
+daemon mode and multi-process mode. The service can then be stopped by simply
+pressing Ctrl-C, without having to edit the config nor run full debug.
+
 Statistics are only available if compiled in with the 'STATTIME' option. It's
 only used during code optimization phases.
 
+The '-st' and '-sf' options are used to inform previously running processes
+that a configuration is being reloaded. They will receive the SIGTTOU signal to
+ask them to temporarily stop listening to the ports so that the new process
+can grab them. If anything wrong happens, the new process will send them a
+SIGTTIN to tell them to re-listen to the ports and continue their normal
+work. Otherwise, it will either ask them to finish (-sf) their work then softly
+exit, or immediately terminate (-st), breaking existing sessions. A typical use
+of this allows a configuration reload without service interruption :
+
+ # haproxy -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)
+
 ======================
 | Configuration file |
 ======================
@@ -219,7 +237,7 @@ Example :
 
 1.4) Startup modes
 ------------------
-The service can start in several different :
+The service can start in several different modes :
   - foreground / background
   - quiet / normal / debug
 
@@ -230,6 +248,9 @@ returns immediately after forking. That's accomplished by the 'daemon' option
 in the 'global' section, which is the equivalent of the '-D' command line
 argument.
 
+The '-db' command line argument overrides the 'daemon' and 'nbproc' global
+options to make the process run in normal, foreground mode.
+
 Moreover, certain alert messages are still sent to the standard output even
 in 'daemon' mode. To make them disappear, simply add the 'quiet' option in the
 'global' section. This option has no command-line equivalent.
@@ -282,6 +303,9 @@ Example :
     # to stop only those processes among others :
     # kill $(</var/run/haproxy-private.pid)
 
+    # to reload a new configuration with minimal service impact and without
+    # breaking existing sessions :
+    # haproxy -f haproxy.cfg -p $(</var/run/haproxy-private.pid) -st $(</var/run/haproxy-private.pid)
 
 1.7) Polling mechanisms
 -----------------------
@@ -479,7 +503,7 @@ amount of simultaneous ones. When the limit is reached, it simply stops
 listening, but the system may still be accepting them because of the back log
 queue. These connections will be processed later when other ones have freed
 some slots. This provides a serialization effect which helps very fragile
-servers resist to high loads. Se further for system limitations.
+servers resist to high loads. See further for system limitations.
 
 Example :
 ---------
@@ -528,6 +552,8 @@ Please note that the 'grace' parameter is ignored for SIGTTOU, as well as for
 SIGUSR1 when the process was in the pause mode. Please also note that it would
 be useful to save the pidfile before starting a new instance.
 
+This mechanism fully exploited since 1.2.11 with the '-st' and '-sf' options
+(see above).
 
 2.5) Connections expiration time
 --------------------------------
@@ -576,6 +602,9 @@ Example :
         # we can retry 3 times max after a failure
         retries 3
 
+Please note that the reconnection attempt may lead to getting the connection
+sent to a new server if the original one died between connection attempts.
+
 
 2.7) Address of the dispatch server (deprecated)
 ------------------------------------------------
@@ -766,9 +795,10 @@ The proxy can perform the load-balancing itself, both in TCP and in HTTP modes.
 This is the most interesting mode which obsoletes the old 'dispatch' mode
 described above. It has advantages such as server health monitoring, multiple
 port binding and port mapping. To use this mode, the 'balance' keyword is used,
-followed by the selected algorithm. As of version 1.1.23, only 'roundrobin' is
+followed by the selected algorithm. Up to version 1.2.11, only 'roundrobin' was
-available, which is also the default value if unspecified. In this mode, there
+available, which is also the default value if unspecified. Starting with
-will be no dispatch address, but the proxy needs at least one server.
+version 1.2.12, a new 'source' keyword appeared. In this mode, there will be no
+dispatch address, but the proxy needs at least one server.
 
 Example : same as the last one, with internal load balancer
 ---------
@@ -829,6 +859,42 @@ Examples :
         server srv1 192.168.1.1:+1000
         server srv2 192.168.1.2:+1000
 
+As previously stated, version 1.2.12 brought the 'source' keyword. When this
+keyword is used, the client's IP address is hashed and evenly distributed among
+the available servers so that a same source IP will always go to the same
+server as long as there are no change in the number of available servers. This
+can be used for instance to bind HTTP and HTTPS to the same server. It can also
+be used to improve stickyness when one part of the client population does not
+accept cookies. In this case, only those ones will be perturbated should a
+server fail.
+
+NOTE: It is important to consider the fact that many clients surf the net
+      through proxy farms which assign different IP addresses for each
+      request. Others use dialup connections with a different IP at each
+      connection. Thus, the 'source' parameter should be used with extreme
+      care.
+
+Examples :
+----------
+
+# make a same IP go to the same server whatever the service
+
+    listen http_proxy
+        bind :80,:443
+        mode http
+        balance source
+        server web1 192.168.1.1
+        server web2 192.168.1.2
+
+# try to improve client-server binding by using both source IP and cookie :
+
+    listen http_proxy :80
+        mode http
+        cookie SERVERID
+        balance source
+        server web1 192.168.1.1 cookie server01
+        server web2 192.168.1.2 cookie server02
+
 
 3.1) Server monitoring
 ----------------------
@@ -1029,6 +1095,54 @@ option :
         redispatch # send back to dispatch in case of connection failure
 
 
+3.3) Assigning different weights to servers
+-------------------------------------------
+Sometimes you will need to bring new servers to increase your server farm's
+capacity, but the new server will be either smaller (emergency use of anything
+that fits) or bigger (when investing in new hardware). For this reason, it
+might be wise to be able to send more clients to biggest servers. Till version
+1.2.11, it was necessary to replicate the same server multiple times in the
+configuration. Starting with 1.2.12, the 'weight' option is available. HAProxy
+then computes the most homogenous possible map of servers based on their
+weights so that the load gets distributed as smoothly as possible among
+them. The weight, between 1 and 256, should reflect one server's capacity
+relative to others. This way, if a server fails, the remaining capacities are
+still respected.
+
+Example :
+---------
+# fair distribution among two opterons and one old pentium3
+
+    listen web_appl 0.0.0.0:80
+        mode http
+        cookie SERVERID insert nocache indirect
+        balance roundrobin
+        server pentium3-800 192.168.1.1:80 cookie server01 weight  8 check
+        server opteron-2.0G 192.168.1.2:80 cookie server02 weight 20 check
+        server opteron-2.4G 192.168.1.3:80 cookie server03 weight 24 check
+        server web-backup1 192.168.2.1:80 cookie server04 check backup
+        server web-excuse 192.168.3.1:80 check backup
+
+Notes :
+-------
+  - if unspecified, the default weight is 1
+
+  - the weight does not impact health checks, so it is cleaner to use weights
+    than replicating the same server several times
+
+  - weights also work on backup servers if the 'allbackups' option is used
+
+  - the weights also apply to the source address load balancing
+    ('balance source').
+
+  - whatever the weights, the first server will always be assigned first. This
+    is helpful for troubleshooting.
+
+  - for the purists, the map calculation algorithm gives precedence to first
+    server, so the map is the most uniform when servers are declared in
+    ascending order relative to their weights.
+
+
 4) Additionnal features
 =======================
 

doc/haproxy-fr.txt

@@ -2,9 +2,9 @@
                              H A - P r o x y
                            Manuel de référence
                            -------------------
-                              version 1.2.9
+                              version 1.2.12
                               willy tarreau
-                                2006/03/01
+                                2006/04/15
 
 ================
 | Introduction |
@@ -46,10 +46,14 @@ Les options de lancement sont peu nombreuses :
        détectée.
     -p <fichier> indique au processus père qu'il doit écrire les PIDs de ses
        fils dans ce fichier en mode démon.
+    -sf specifie une liste de PIDs auxquels envoyer un signal FINISH
+    -st specifie une liste de PIDs auxquels envoyer un signal TERMINATE
     -s affiche les statistiques (si option compilée)
     -l ajoute des informations aux statistiques
     -de désactive l'utilisation de epoll()
     -dp désactive l'utilisation de poll()
+    -db désactive la mise en arrière-plan (utile pour débugger)
+    -m <megs> applique une limitation de <megs> Mo d'utilisation mémoire
 
 Le nombre maximal de connexion simultanées par proxy est le paramètre par
 défaut pour les proxies pour lesquels ce paramètre n'est pas précisé dans le
@@ -64,10 +68,27 @@ Le mode debug correspond
 mode, toutes les connexions, déconnexions, et tous les échanges d'en-têtes HTTP
 sont affichés.
 
+Pour debugger, l'option '-db' est très pratique car elle désactive
+temporairement le mode daemon et le mode multi-processus. Le service peut alors
+être arrêté par un simple appui sur Ctrl-C, sans avoir à modifier la
+configuration ni à activer le mode debug complet.
+
 Les statistiques ne sont disponibles que si le programme a été compilé avec
 l'option "STATTIME". Il s'agit principalement de données brutes n'ayant
 d'utilité que lors de benchmarks par exemple.
 
+Les paramètres '-st' et '-sf' sont utilisés pour informer des processus
+existants que la configuration va être rechargée. Ils recevront le signal
+SIGTTOU, leur demandant de libérer les ports en écoute afin que le nouveau
+processus puisse les prendre. Si quoi que ce soit se passe mal, le nouveau
+processus leur enverra un signal SIGTTIN pour leur indiquer qu'ils peuvent
+se remettre en écoute et continuer leur travail. En revanche, si la
+configuration se charge correctement, alors ils recevront un signal de demande
+de fin de travail en douceur (-sf), ou de terminaison immédiate (-st) qui
+coupera les sessions en cours. Un usage typique tel que celui-ci permet de
+recharger une configuration sans interruption de service :
+
+ # haproxy -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)
 
 ============================
 | Fichier de configuration |
@@ -247,6 +268,9 @@ initialisation. Il faut le mettre en arri
 au processus appelant. C'est ce que fait l'option 'daemon' de la section
 'global', et qui est l'équivalent du paramètre '-D' de la ligne de commande.
 
+Le paramètre de ligne de commande '-db' inhibe les options globales 'daemon'
+et 'nbproc' pour faire fonctionner le processus en mode normal, avant-plan.
+
 Par ailleurs, certains messages d'alerte sont toujours envoyés sur la sortie
 standard, même en mode 'daemon'. Pour ne plus les voir ailleurs que dans les
 logs, il suffit de passer en mode silencieux par l'ajout de l'option 'quiet'.
@@ -301,6 +325,9 @@ Exemple :
     # pour stopper seulement ces processus parmi d'autres :
     # kill $(</var/run/haproxy-private.pid)
 
+    # pour recharger une configuration avec un impact minimal sur le service,
+    # et sans casser les sessions existantes :
+    # haproxy -f haproxy.cfg -p $(</var/run/haproxy-private.pid) -st $(</var/run/haproxy-private.pid)
 
 1.7) Mécanismes de traitements des événements
 ---------------------------------------------
@@ -553,6 +580,8 @@ noter que le param
 signal SIGUSR1 une fois le processus en pause. Aussi, il peut s'avérer très
 utile de sauver le fichier de pid avant de démarrer une nouvelle instance.
 
+Ce mécanisme est pleinement exploité à partir de la version 1.2.11 avec les
+options '-st' et '-sf' (voir plus haut).
 
 2.5) Temps d'expiration des connexions
 --------------------------------------
@@ -603,6 +632,9 @@ Exemple :
         # on essaie encore trois fois maxi
         retries 3
 
+Il est à noter que la tentative de reconnexion peut amener à utiliser un autre
+serveur si le premier a disparu entre deux tentatives de connexion.
+
 
 2.7) Adresse du serveur
 -----------------------
@@ -768,9 +800,10 @@ Attention : la syntaxe a chang
 Le relais peut effectuer lui-même la répartition de charge entre les différents
 serveurs définis pour un service donné, en mode TCP comme en mode HTTP. Pour
 cela, on précise le mot clé 'balance' dans la définition du service,
-éventuellement suivi du nom d'un algorithme de répartition. En version 1.1.9,
+éventuellement suivi du nom d'un algorithme de répartition. Jusqu'à la version
-seul 'roundrobin' est géré, et c'est aussi la valeur implicite par défaut. Il
+1.2.11, seul 'roundrobin' était géré, et c'est aussi la valeur implicite par
-est évident qu'en cas d'utilisation du répartiteur interne, il ne faudra pas
+défaut. Avec la version 1.2.12, le nouveau mot clé 'source' est apparu. Il est
+évident qu'en cas d'utilisation du répartiteur interne, il ne faudra pas
 spécifier d'adresse de dispatch, et qu'il faudra au moins un serveur.
 
 Exemple : même que précédemment en répartition interne
@@ -833,6 +866,44 @@ Exemples :
         server srv1 192.168.1.1:+1000
         server srv2 192.168.1.2:+1000
 
+Comme indiqué précédemment, la version 1.2.12 apporta le nouveau mot clé
+'source'. Lorsque celui-ci est utilisé, l'adresse IP du client est hachée et
+distribuée de manière homogène parmi les serveurs disponibles, de sorte qu'une
+même adresse IP aille toujours sur le même serveur tant qu'il n'y a aucun
+changement dans le nombre de serveurs disponibles. Ceci peut être utilisé par
+exemple pour attacher le HTTP et le HTTPS sur un même serveur pour un même
+client. Cela peut également être utilisé pour améliorer la persistance
+lorsqu'une partie de la population des clients n'accepte pas les cookies. Dans
+ce cas, seuls ces derniers seront perturbés par la perte d'un serveur.
+
+NOTE: il est important de prendre en compte le fait que beaucoup d'internautes
+      naviguent à travers des fermes de proxies qui assignent des adresses IP
+      différentes à chaque requête. D'autres internautes utilisent des liens à
+      la demande et obtiennent une adresse IP différente à chaque connexion. De
+      ce fait, le paramètre 'source' doit être utilisé avec une extrème
+      précaution.
+
+Exemples :
+----------
+
+# assurer qu'une même adresse IP ira sur le même serveur pour tout service
+
+    listen http_proxy
+        bind :80,:443
+        mode http
+        balance source
+        server web1 192.168.1.1
+        server web2 192.168.1.2
+
+# améliorer la persistance par l'utilisation de la source en plus du cookie :
+
+    listen http_proxy :80
+        mode http
+        cookie SERVERID
+        balance source
+        server web1 192.168.1.1 cookie server01
+        server web2 192.168.1.2 cookie server02
+
 
 3.1) Surveillance des serveurs
 ------------------------------
@@ -844,6 +915,7 @@ Il est possible de sp
 tests du serveur par le paramètre "inter", le nombre d'échecs acceptés par le
 paramètre "fall", et le nombre de succès avant reprise par le paramètre "rise".
 Les paramètres non précisés prennent les valeurs suivantes par défaut :
+
  - inter : 2000
  - rise  : 2
  - fall  : 3
@@ -866,10 +938,12 @@ consid
 deux tests (paramètre "inter"). Pour activer ce mode, spécifier l'option
 "httpchk", éventuellement suivie d'une méthode et d'une URI. L'option "httpchk"
 accepte donc 4 formes :
+
   - option httpchk               -> OPTIONS / HTTP/1.0
   - option httpchk URI           -> OPTIONS <URI> HTTP/1.0
   - option httpchk METH URI      -> <METH> <URI> HTTP/1.0
   - option httpchk METH URI VER  -> <METH> <URI> <VER>
+
 Voir les exemples ci-après.        
 
 Depuis la version 1.1.17, il est possible de définir des serveurs de secours,
@@ -1038,6 +1112,59 @@ tente de s'y connecter, il faut pr
         redispatch # renvoyer vers dispatch si serveur HS.
 
 
+3.3) Assignation de poids différents à des serveurs
+---------------------------------------------------
+Parfois il arrive d'ajouter de nouveaux serveurs pour accroître la capacité
+d'une ferme de serveur, mais le nouveau serveur est soit beaucoup plus petit
+que les autres (dans le cas d'un ajout d'urgence de matériel de récupération),
+soit plus puissant (lors d'un investissement dans du matériel neuf). Pour cette
+raison, il semble parfois judicieux de pouvoir envoyer plus de clients vers les
+plus gros serveurs. Jusqu'à la version 1.2.11, il était nécessaire de répliquer
+plusieurs fois les définitions des serveurs pour augmenter leur poids. Depuis
+la version 1.2.12, l'option 'weight' est disponible. HAProxy construit alors
+une vue des serveurs disponibles la plus homogène possible en se basant sur
+leur poids de sorte que la charge se distribue de la manière la plus lisse
+possible. Le poids compris entre 1 et 256 doit refléter la capacité d'un
+serveur par rapport aux autres. De cette manière, si un serveur disparait, les
+capacités restantes sont toujours respectées.
+
+
+Exemple :
+---------
+# distribution équitable sur 2 opteron and un ancien pentium3
+
+    listen web_appl 0.0.0.0:80
+        mode http
+        cookie SERVERID insert nocache indirect
+        balance roundrobin
+        server pentium3-800 192.168.1.1:80 cookie server01 weight  8 check
+        server opteron-2.0G 192.168.1.2:80 cookie server02 weight 20 check
+        server opteron-2.4G 192.168.1.3:80 cookie server03 weight 24 check
+        server web-backup1 192.168.2.1:80 cookie server04 check backup
+        server web-excuse 192.168.3.1:80 check backup
+
+Notes :
+-------
+  - lorsque le poids n'est pas spécifié, la valeur par défaut est à 1
+
+  - le poids n'impacte pas les tests de fonctionnement (health checks), donc il
+    est plus propre d'utiliser les poids que de répliquer le même serveur
+    plusieurs fois.
+
+  - les poids s'appliquent également aux serveurs de backup si l'option
+    'allbackups' est positionnée.
+
+  - le poids s'applique aussi à la répartition selon la source
+    ('balance source').
+
+  - quels que soient les poids, le premier serveur sera toujours assigné en
+    premier. Cette règle facilite les diagnostics.
+
+  - pour les puristes, l'algorithme de calculation de la vue des serveurs donne
+    une priorité aux premiers serveurs, donc la vue est la plus uniforme si les
+    serveurs sont déclarés dans l'ordre croissant de leurs poids.
+
+
 4) Fonctionnalités additionnelles
 =================================