[doc] updated english and french docs with source and weight options.
diff --git a/doc/haproxy-en.txt b/doc/haproxy-en.txt
index 335cff8..59cba68 100644
--- a/doc/haproxy-en.txt
+++ b/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 @@
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 @@
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 @@
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 @@
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 @@
# 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 @@
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 @@
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 @@
# 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 @@
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 @@
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 @@
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
=======================