mirror of
http://git.haproxy.org/git/haproxy.git/
synced 2025-02-25 15:11:10 +00:00
[doc] updated english and french docs with source and weight options.
This commit is contained in:
willy tarreau
parent
2c51373bfa
commit
34f4530c3a
@ -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
|
||||
available, which is also the default value if unspecified. In this mode, there
|
||||
will be no dispatch address, but the proxy needs at least one server.
|
||||
followed by the selected algorithm. Up to version 1.2.11, only 'roundrobin' was
|
||||
available, which is also the default value if unspecified. Starting with
|
||||
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
|
||||
=======================
|
||||
|
||||
|
||||
@ -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,
|
||||
seul 'roundrobin' est géré, et c'est aussi la valeur implicite par défaut. Il
|
||||
est évident qu'en cas d'utilisation du répartiteur interne, il ne faudra pas
|
||||
éventuellement suivi du nom d'un algorithme de répartition. Jusqu'à la version
|
||||
1.2.11, seul 'roundrobin' était géré, et c'est aussi la valeur implicite par
|
||||
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
|
||||
=================================
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user