blob: 6a7aa01d5d06dcf2d47d47ab9062b95609a4c87f [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 Reference Manual
4 -------------------
Willy Tarreau7b4c5ae2008-04-19 21:06:14 +02005 version 1.3.15
willy tarreauc5f73ed2005-12-18 01:26:38 +01006 willy tarreau
Willy Tarreau7b4c5ae2008-04-19 21:06:14 +02007 2008/04/19
willy tarreaueedaa9f2005-12-17 14:08:03 +01008
Willy Tarreaua080eca2009-10-14 20:30:15 +02009
10 !!!! NOTE: THIS DOCUMENT IS OUTDATED !!!!
11
12 Please use "configuration.txt" from the same directory, or download
13 an up-to-date version from the following location :
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 tarreaueedaa9f2005-12-17 14:08:03 +010018============
19| Abstract |
20============
21
Willy Tarreau94b45912006-05-31 06:40:15 +020022HAProxy is a TCP/HTTP reverse proxy which is particularly suited for high
willy tarreaueedaa9f2005-12-17 14:08:03 +010023availability environments. Indeed, it can :
24 - route HTTP requests depending on statically assigned cookies ;
25 - spread the load among several servers while assuring server persistence
26 through the use of HTTP cookies ;
27 - switch to backup servers in the event a main one fails ;
28 - accept connections to special ports dedicated to service monitoring ;
29 - stop accepting connections without breaking existing ones ;
30 - add/modify/delete HTTP headers both ways ;
31 - block requests matching a particular pattern ;
willy tarreau532bb552006-05-13 18:40:37 +020032 - hold clients to the right application server depending on application
33 cookies
willy tarreau481132e2006-05-21 21:43:10 +020034 - report detailed status as HTML pages to authenticated users from an URI
35 intercepted from the application.
willy tarreaueedaa9f2005-12-17 14:08:03 +010036
37It needs very little resource. Its event-driven architecture allows it to easily
38handle thousands of simultaneous connections on hundreds of instances without
39risking the system's stability.
40
41====================
42| Start parameters |
43====================
44
45There are only a few command line options :
46
47 -f <configuration file>
48 -n <high limit for the total number of simultaneous connections>
willy tarreau532bb552006-05-13 18:40:37 +020049 = 'maxconn' in 'global' section
50 -N <high limit for the per-listener number of simultaneous connections>
51 = 'maxconn' in 'listen' or 'default' sections
willy tarreaueedaa9f2005-12-17 14:08:03 +010052 -d starts in foregreound with debugging mode enabled
53 -D starts in daemon mode
willy tarreau982249e2005-12-18 00:57:06 +010054 -q disable messages on output
55 -V displays messages on output even when -q or 'quiet' are specified.
56 -c only checks config file and exits with code 0 if no error was found, or
57 exits with code 1 if a syntax error was found.
willy tarreaufe2c5c12005-12-17 14:14:34 +010058 -p <pidfile> asks the process to write down each of its children's
59 pids to this file in daemon mode.
willy tarreau34f45302006-04-15 21:37:14 +020060 -sf specifies a list of pids to send a FINISH signal to after startup.
61 -st specifies a list of pids to send a TERMINATE signal to after startup.
willy tarreaueedaa9f2005-12-17 14:08:03 +010062 -s shows statistics (only if compiled in)
63 -l shows even more statistics (implies '-s')
Willy Tarreaude99e992007-04-16 00:53:59 +020064 -dk disables use of kqueue()
65 -ds disables use of speculative epoll()
willy tarreau64a3cc32005-12-18 01:13:11 +010066 -de disables use of epoll()
67 -dp disables use of poll()
willy tarreau34f45302006-04-15 21:37:14 +020068 -db disables background mode (stays in foreground, useful for debugging)
69 -m <megs> enforces a memory usage limit to a maximum of <megs> megabytes.
willy tarreaueedaa9f2005-12-17 14:08:03 +010070
willy tarreau532bb552006-05-13 18:40:37 +020071The maximal number of connections per proxy instance is used as the default
72parameter for each instance for which the 'maxconn' paramter is not set in the
73'listen' section.
willy tarreaueedaa9f2005-12-17 14:08:03 +010074
75The maximal number of total connections limits the number of connections used by
76the whole process if the 'maxconn' parameter is not set in the 'global' section.
77
78The debugging mode has the same effect as the 'debug' option in the 'global'
79section. When the proxy runs in this mode, it dumps every connections,
80disconnections, timestamps, and HTTP headers to stdout. This should NEVER
81be used in an init script since it will prevent the system from starting up.
82
willy tarreau34f45302006-04-15 21:37:14 +020083For debugging, the '-db' option is very useful as it temporarily disables
84daemon mode and multi-process mode. The service can then be stopped by simply
85pressing Ctrl-C, without having to edit the config nor run full debug.
86
willy tarreaueedaa9f2005-12-17 14:08:03 +010087Statistics are only available if compiled in with the 'STATTIME' option. It's
willy tarreau481132e2006-05-21 21:43:10 +020088only used during code optimization phases, and will soon disappear.
willy tarreaueedaa9f2005-12-17 14:08:03 +010089
willy tarreau532bb552006-05-13 18:40:37 +020090The '-st' and '-sf' options are used for hot reconfiguration (see below).
willy tarreau34f45302006-04-15 21:37:14 +020091
willy tarreaueedaa9f2005-12-17 14:08:03 +010092======================
93| Configuration file |
94======================
95
96Structure
97=========
98
99The configuration file parser ignores empty lines, spaces, tabs. Anything
100between a sharp ('#') not following a backslash ('\'), and the end of a line
101constitutes a comment and is ignored too.
102
103The configuration file is segmented in sections. A section begins whenever
104one of these 3 keywords are encountered :
105
106 - 'global'
107 - 'listen'
108 - 'defaults'
109
110Every parameter refer to the section beginning at the last one of these 3
111keywords.
112
113
1141) Global parameters
115====================
116
117Global parameters affect the whole process behaviour. They are all set in the
118'global' section. There may be several 'global' sections if needed, but their
119parameters will only be merged. Allowed parameters in 'global' section include
120the following ones :
121
122 - log <address> <facility> [max_level]
123 - maxconn <number>
124 - uid <user id>
125 - gid <group id>
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200126 - user <user name>
127 - group <group name>
willy tarreaueedaa9f2005-12-17 14:08:03 +0100128 - chroot <directory>
129 - nbproc <number>
130 - daemon
131 - debug
Willy Tarreaude99e992007-04-16 00:53:59 +0200132 - nokqueue
133 - nosepoll
willy tarreau64a3cc32005-12-18 01:13:11 +0100134 - noepoll
135 - nopoll
willy tarreaueedaa9f2005-12-17 14:08:03 +0100136 - quiet
willy tarreaufe2c5c12005-12-17 14:14:34 +0100137 - pidfile <file>
willy tarreauc5f73ed2005-12-18 01:26:38 +0100138 - ulimit-n <number>
willy tarreau598da412005-12-18 01:07:29 +0100139 - stats
Willy Tarreau1db37712007-06-03 17:16:49 +0200140 - tune.maxpollevents <number>
willy tarreaueedaa9f2005-12-17 14:08:03 +0100141
willy tarreauc5f73ed2005-12-18 01:26:38 +0100142
willy tarreaueedaa9f2005-12-17 14:08:03 +01001431.1) Event logging
144------------------
145Most events are logged : start, stop, servers going up and down, connections and
146errors. Each event generates a syslog message which can be sent to up to 2
147servers. The syntax is :
148
149 log <ip_address> <facility> [max_level]
150
151Connections are logged at level "info". Services initialization and servers
152going up are logged at level "notice", termination signals are logged at
153"warning", and definitive service termination, as well as loss of servers are
154logged at level "alert". The optional parameter <max_level> specifies above
155what level messages should be sent. Level can take one of these 8 values :
156
157 emerg, alert, crit, err, warning, notice, info, debug
158
159For backwards compatibility with versions 1.1.16 and earlier, the default level
160value is "debug" if not specified.
161
162Permitted facilities are :
163 kern, user, mail, daemon, auth, syslog, lpr, news,
164 uucp, cron, auth2, ftp, ntp, audit, alert, cron2,
165 local0, local1, local2, local3, local4, local5, local6, local7
166
167According to RFC3164, messages are truncated to 1024 bytes before being emitted.
168
169Example :
170---------
171 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100172 log 192.168.2.200 local3
173 log 127.0.0.1 local4 notice
174
willy tarreaueedaa9f2005-12-17 14:08:03 +0100175
1761.2) limiting the number of connections
177---------------------------------------
178It is possible and recommended to limit the global number of per-process
willy tarreauc5f73ed2005-12-18 01:26:38 +0100179connections using the 'maxconn' global keyword. Since one connection includes
180both a client and a server, it means that the max number of TCP sessions will
181be about the double of this number. It's important to understand this when
182trying to find best values for 'ulimit -n' before starting the proxy. To
183anticipate the number of sockets needed, all these parameters must be counted :
willy tarreaueedaa9f2005-12-17 14:08:03 +0100184
185 - 1 socket per incoming connection
186 - 1 socket per outgoing connection
187 - 1 socket per address/port/proxy tuple.
188 - 1 socket per server being health-checked
189 - 1 socket for all logs
190
191In simple configurations where each proxy only listens one one address/port,
willy tarreauc5f73ed2005-12-18 01:26:38 +0100192set the limit of file descriptors (ulimit -n) to
193(2 * maxconn + nbproxies + nbservers + 1). Starting with versions 1.1.32/1.2.6,
194it is now possible to set the limit in the configuration using the 'ulimit-n'
195global keyword, provided the proxy is started as root. This puts an end to the
196recurrent problem of ensuring that the system limits are adapted to the proxy
197values. Note that these limits are per-process.
198
199Example :
200---------
201 global
202 maxconn 32000
203 ulimit-n 65536
204
willy tarreaueedaa9f2005-12-17 14:08:03 +0100205
2061.3) Drop of priviledges
207------------------------
208In order to reduce the risk and consequences of attacks, in the event where a
209yet non-identified vulnerability would be successfully exploited, it's possible
210to lower the process priviledges and even isolate it in a riskless directory.
211
212In the 'global' section, the 'uid' parameter sets a numerical user identifier
213which the process will switch to after binding its listening sockets. The value
214'0', which normally represents the super-user, here indicates that the UID must
215not change during startup. It's the default behaviour. The 'gid' parameter does
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200216the same for the group identifier. If setting an uid is not possible because of
217deployment constraints, it is possible to set a user name with the 'user'
218keyword followed by a valid user name. The same is true for the gid. It is
219possible to specify a group name after the 'group' keyword.
220
221It is particularly advised against use of generic accounts such as 'nobody'
222because it has the same consequences as using 'root' if other services use
223them.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100224
225The 'chroot' parameter makes the process isolate itself in an empty directory
226just before switching its UID. This type of isolation (chroot) can sometimes
227be worked around on certain OS (Linux, Solaris), provided that the attacker
228has gained 'root' priviledges and has the ability to use or create a directory.
229For this reason, it's capital to use a dedicated directory and not to share one
230between several services of different nature. To make isolation more resistant,
231it's recommended to use an empty directory without any right, and to change the
232UID of the process so that it cannot do anything there.
233
234Note: in the event where such a vulnerability would be exploited, it's most
235likely that first attempts would kill the process due to 'Segmentation Fault',
236'Bus Error' or 'Illegal Instruction' signals. Eventhough it's true that
237isolating the server reduces the risks of intrusion, it's sometimes useful to
238find why a process dies, via the analysis of a 'core' file, although very rare
239(the last bug of this sort was fixed in 1.1.9). For security reasons, most
240systems disable the generation of core file when a process changes its UID. So
241the two workarounds are either to start the process from a restricted user
242account, which will not be able to chroot itself, or start it as root and not
243change the UID. In both cases the core will be either in the start or the chroot
244directories. Do not forget to allow core dumps prior to start the process :
245
246# ulimit -c unlimited
247
248Example :
249---------
250
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200251 # with uid/gid
willy tarreaueedaa9f2005-12-17 14:08:03 +0100252 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100253 uid 30000
254 gid 30000
255 chroot /var/chroot/haproxy
256
Willy Tarreau95c20ac2007-03-25 15:39:23 +0200257 # with user/group
258 global
259 user haproxy
260 group public
261 chroot /var/chroot/haproxy
262
willy tarreaueedaa9f2005-12-17 14:08:03 +0100263
2641.4) Startup modes
265------------------
willy tarreau34f45302006-04-15 21:37:14 +0200266The service can start in several different modes :
willy tarreaueedaa9f2005-12-17 14:08:03 +0100267 - foreground / background
268 - quiet / normal / debug
269
270The default mode is normal, foreground, which means that the program doesn't
271return once started. NEVER EVER use this mode in a system startup script, or
272the system won't boot. It needs to be started in background, so that it
273returns immediately after forking. That's accomplished by the 'daemon' option
274in the 'global' section, which is the equivalent of the '-D' command line
275argument.
276
willy tarreau34f45302006-04-15 21:37:14 +0200277The '-db' command line argument overrides the 'daemon' and 'nbproc' global
278options to make the process run in normal, foreground mode.
279
willy tarreaueedaa9f2005-12-17 14:08:03 +0100280Moreover, certain alert messages are still sent to the standard output even
281in 'daemon' mode. To make them disappear, simply add the 'quiet' option in the
282'global' section. This option has no command-line equivalent.
283
284Last, the 'debug' mode, enabled with the 'debug' option in the 'global' section,
285and which is equivalent of the '-d' option, allows deep TCP/HTTP analysis, with
286timestamped display of each connection, disconnection, and HTTP headers for both
287ways. This mode is incompatible with 'daemon' and 'quiet' modes for obvious
288reasons.
289
willy tarreauc5f73ed2005-12-18 01:26:38 +0100290
willy tarreaueedaa9f2005-12-17 14:08:03 +01002911.5) Increasing the overall processing power
292--------------------------------------------
293On multi-processor systems, it may seem to be a shame to use only one processor,
willy tarreau982249e2005-12-18 00:57:06 +0100294eventhough the load needed to saturate a recent processor is far above common
willy tarreaueedaa9f2005-12-17 14:08:03 +0100295usage. Anyway, for very specific needs, the proxy can start several processes
296between which the operating system will spread the incoming connections. The
297number of processes is controlled by the 'nbproc' parameter in the 'global'
willy tarreau4302f492005-12-18 01:00:37 +0100298section. It defaults to 1, and obviously works only in 'daemon' mode. One
299typical usage of this parameter has been to workaround the default per-process
300file-descriptor limit that Solaris imposes to user processes.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100301
302Example :
303---------
304
305 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100306 daemon
307 quiet
308 nbproc 2
willy tarreaueedaa9f2005-12-17 14:08:03 +0100309
310
willy tarreaufe2c5c12005-12-17 14:14:34 +01003111.6) Helping process management
312-------------------------------
313Haproxy now supports the notion of pidfile. If the '-p' command line argument,
314or the 'pidfile' global option is followed with a file name, this file will be
315removed, then filled with all children's pids, one per line (only in daemon
316mode). This file is NOT within the chroot, which allows to work with a readonly
317 chroot. It will be owned by the user starting the process, and will have
318permissions 0644.
319
320Example :
321---------
322
323 global
324 daemon
325 quiet
willy tarreauc5f73ed2005-12-18 01:26:38 +0100326 nbproc 2
willy tarreaufe2c5c12005-12-17 14:14:34 +0100327 pidfile /var/run/haproxy-private.pid
328
329 # to stop only those processes among others :
330 # kill $(</var/run/haproxy-private.pid)
331
willy tarreau34f45302006-04-15 21:37:14 +0200332 # to reload a new configuration with minimal service impact and without
333 # breaking existing sessions :
Willy Tarreau10806d52007-09-09 23:49:18 +0200334 # haproxy -f haproxy.cfg -p /var/run/haproxy-private.pid -sf $(</var/run/haproxy-private.pid)
willy tarreaufe2c5c12005-12-17 14:14:34 +0100335
willy tarreau64a3cc32005-12-18 01:13:11 +01003361.7) Polling mechanisms
337-----------------------
338Starting from version 1.2.5, haproxy supports the poll() and epoll() polling
339mechanisms. On systems where select() is limited by FD_SETSIZE (like Solaris),
340poll() can be an interesting alternative. Performance tests show that Solaris'
341poll() performance does not decay as fast as the numbers of sockets increase,
342making it a safe solution for high loads. However, Solaris already uses poll()
343to emulate select(), so as long as the number of sockets has no reason to go
344higher than FD_SETSIZE, poll() should not provide any better performance. On
345Linux systems with the epoll() patch (or any 2.6 version), haproxy will use
346epoll() which is extremely fast and non dependant on the number of sockets.
347Tests have shown constant performance from 1 to 20000 simultaneous sessions.
Willy Tarreaude99e992007-04-16 00:53:59 +0200348Version 1.3.9 introduced kqueue() for FreeBSD/OpenBSD, and speculative epoll()
349which consists in trying to perform I/O before queuing the events via syscalls.
willy tarreau64a3cc32005-12-18 01:13:11 +0100350
Willy Tarreau1db37712007-06-03 17:16:49 +0200351In order to optimize latency, it is now possible to limit the number of events
352returned by a single call to poll. The limit is fixed to 200 by default. If a
353smaller latency is seeked, it may be useful to reduce this value by using the
354'tune.maxpollevents' parameter in the 'global' section. Increasing it will
355slightly save CPU cycles in presence of large number of connections.
356
Willy Tarreaude99e992007-04-16 00:53:59 +0200357Haproxy will use kqueue() or speculative epoll() when available, then epoll(),
358and will fall back to poll(), then to select(). However, if for any reason you
359need to disable epoll() or poll() (eg. because of a bug or just to compare
360performance), new global options have been created for this matter : 'nosepoll',
361'nokqueue', 'noepoll' and 'nopoll'.
willy tarreau64a3cc32005-12-18 01:13:11 +0100362
363Example :
364---------
365
366 global
367 # use only select()
368 noepoll
369 nopoll
Willy Tarreau1db37712007-06-03 17:16:49 +0200370 tune.maxpollevents 100
willy tarreau64a3cc32005-12-18 01:13:11 +0100371
372Note :
373------
374For the sake of configuration file portability, these options are accepted but
375ignored if the poll() or epoll() mechanisms have not been enabled at compile
376time.
377
Willy Tarreaude99e992007-04-16 00:53:59 +0200378To make debugging easier, the '-de' runtime argument disables epoll support,
379the '-dp' argument disables poll support, '-dk' disables kqueue and '-ds'
380disables speculative epoll(). They are respectively equivalent to 'noepoll',
381'nopoll', 'nokqueue' and 'nosepoll'.
willy tarreau64a3cc32005-12-18 01:13:11 +0100382
383
willy tarreaueedaa9f2005-12-17 14:08:03 +01003842) Declaration of a listening service
385=====================================
386
387Service sections start with the 'listen' keyword :
388
389 listen <instance_name> [ <IP_address>:<port_range>[,...] ]
390
391- <instance_name> is the name of the instance. This name will be reported in
392 logs, so it is good to have it reflect the proxied service. No unicity test
393 is done on this name, and it's not mandatory for it to be unique, but highly
394 recommended.
395
396- <IP_address> is the IP address the proxy binds to. Empty address, '*' and
397 '0.0.0.0' all mean that the proxy listens to all valid addresses on the
398 system.
399
400- <port_range> is either a unique port, or a port range for which the proxy will
401 accept connections for the IP address specified above. This range can be :
402 - a numerical port (ex: '80')
403 - a dash-delimited ports range explicitly stating the lower and upper bounds
404 (ex: '2000-2100') which are included in the range.
405
406 Particular care must be taken against port ranges, because every <addr:port>
407 couple consumes one socket (=a file descriptor), so it's easy to eat lots of
408 descriptors with a simple range. The <addr:port> couple must be used only once
409 among all instances running on a same system. Please note that attaching to
410 ports lower than 1024 need particular priviledges to start the program, which
Jamie Gloudon801a0a32012-08-25 00:18:33 -0400411 are independent of the 'uid' parameter.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100412
413- the <IP_address>:<port_range> couple may be repeated indefinitely to require
414 the proxy to listen to other addresses and/or ports. To achieve this, simply
415 separate them with a coma.
416
417Examples :
418---------
419 listen http_proxy :80
420 listen x11_proxy 127.0.0.1:6000-6009
421 listen smtp_proxy 127.0.0.1:25,127.0.0.1:587
422 listen ldap_proxy :389,:663
423
424In the event that all addresses do not fit line width, it's preferable to
425detach secondary addresses on other lines with the 'bind' keyword. If this
426keyword is used, it's not even necessary to specify the first address on the
427'listen' line, which sometimes makes multiple configuration handling easier :
428
429 bind [ <IP_address>:<port_range>[,...] ]
430
431Examples :
432----------
433 listen http_proxy
434 bind :80,:443
willy tarreauc5f73ed2005-12-18 01:26:38 +0100435 bind 10.0.0.1:10080,10.0.0.1:10443
436
willy tarreaueedaa9f2005-12-17 14:08:03 +0100437
4382.1) Inhibiting a service
439-------------------------
440A service may be disabled for maintenance reasons, without needing to comment
441out the whole section, simply by specifying the 'disabled' keyword in the
442section to be disabled :
443
444 listen smtp_proxy 0.0.0.0:25
willy tarreauc5f73ed2005-12-18 01:26:38 +0100445 disabled
willy tarreaueedaa9f2005-12-17 14:08:03 +0100446
447Note: the 'enabled' keyword allows to enable a service which has been disabled
448 previously by a default configuration.
449
willy tarreauc5f73ed2005-12-18 01:26:38 +0100450
willy tarreaueedaa9f2005-12-17 14:08:03 +01004512.2) Modes of operation
452-----------------------
453A service can work in 3 different distinct modes :
454 - TCP
455 - HTTP
willy tarreau532bb552006-05-13 18:40:37 +0200456 - health
willy tarreaueedaa9f2005-12-17 14:08:03 +0100457
458TCP mode
459--------
460In this mode, the service relays TCP connections as soon as they're established,
461towards one or several servers. No processing is done on the stream. It's only
462an association of source(addr:port) -> destination(addr:port). To use this mode,
463you must specify 'mode tcp' in the 'listen' section. This is the default mode.
464
465Example :
466---------
467 listen smtp_proxy 0.0.0.0:25
willy tarreauc5f73ed2005-12-18 01:26:38 +0100468 mode tcp
willy tarreaueedaa9f2005-12-17 14:08:03 +0100469
470HTTP mode
471---------
472In this mode, the service relays TCP connections towards one or several servers,
473when it has enough informations to decide, which normally means that all HTTP
474headers have been read. Some of them may be scanned for a cookie or a pattern
475matching a regex. To use this mode, specify 'mode http' in the 'listen' section.
476
477Example :
478---------
479 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100480 mode http
willy tarreaueedaa9f2005-12-17 14:08:03 +0100481
482Health-checking mode
483--------------------
484This mode provides a way for external components to check the proxy's health.
485It is meant to be used with intelligent load-balancers which can use send/expect
486scripts to check for all of their servers' availability. This one simply accepts
willy tarreau197e8ec2005-12-17 14:10:59 +0100487the connection, returns the word 'OK' and closes it. If the 'option httpchk' is
488set, then the reply will be 'HTTP/1.0 200 OK' with no data, so that it can be
489tested from a tool which supports HTTP health-checks. To enable it, simply
willy tarreaueedaa9f2005-12-17 14:08:03 +0100490specify 'health' as the working mode :
491
492Example :
493---------
willy tarreau197e8ec2005-12-17 14:10:59 +0100494 # simple response : 'OK'
willy tarreaueedaa9f2005-12-17 14:08:03 +0100495 listen health_check 0.0.0.0:60000
willy tarreauc5f73ed2005-12-18 01:26:38 +0100496 mode health
willy tarreaueedaa9f2005-12-17 14:08:03 +0100497
willy tarreau197e8ec2005-12-17 14:10:59 +0100498 # HTTP response : 'HTTP/1.0 200 OK'
499 listen http_health_check 0.0.0.0:60001
willy tarreauc5f73ed2005-12-18 01:26:38 +0100500 mode health
501 option httpchk
502
willy tarreau532bb552006-05-13 18:40:37 +02005032.2.1 Monitoring
504----------------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100505Versions 1.1.32 and 1.2.6 provide a new solution to check the proxy's
506availability without perturbating the service. The 'monitor-net' keyword was
507created to specify a network of equipments which CANNOT use the service for
508anything but health-checks. This is particularly suited to TCP proxies, because
509it prevents the proxy from relaying the monitor's connection to the remote
510server.
511
512When used with TCP, the connection is accepted then closed and nothing is
513logged. This is enough for a front-end load-balancer to detect the service as
514available.
willy tarreau197e8ec2005-12-17 14:10:59 +0100515
willy tarreauc5f73ed2005-12-18 01:26:38 +0100516When used with HTTP, the connection is accepted, nothing is logged, the
517following response is sent, then the session is closed : "HTTP/1.0 200 OK".
518This is normally enough for any front-end HTTP load-balancer to detect the
519service as available too, both with TCP and HTTP checks.
520
521Proxies using the "monitor-net" keyword can remove the "option dontlognull", as
522it will make them log empty connections from hosts outside the monitoring
523network.
524
525Example :
526---------
527
528 listen tse-proxy
529 bind :3389,:1494,:5900 # TSE, ICA and VNC at once.
530 mode tcp
531 balance roundrobin
532 server tse-farm 192.168.1.10
533 monitor-net 192.168.1.252/31 # L4 load-balancers on .252 and .253
534
willy tarreaueedaa9f2005-12-17 14:08:03 +0100535
Willy Tarreau1c47f852006-07-09 08:22:27 +0200536When the system executing the checks is located behind a proxy, the monitor-net
537keyword cannot be used because haproxy will always see the proxy's address. To
538overcome this limitation, version 1.2.15 brought the 'monitor-uri' keyword. It
539defines an URI which will not be forwarded nor logged, but for which haproxy
540will immediately send an "HTTP/1.0 200 OK" response. This makes it possible to
541check the validity of the reverse-proxy->haproxy chain with one request. It can
542be used in HTTPS checks in front of an stunnel -> haproxy combination for
543instance. Obviously, this keyword is only valid in HTTP mode, otherwise there
544is no notion of URI. Note that the method and HTTP versions are simply ignored.
545
546Example :
547---------
548
549 listen stunnel_backend :8080
550 mode http
551 balance roundrobin
552 server web1 192.168.1.10:80 check
553 server web2 192.168.1.11:80 check
554 monitor-uri /haproxy_test
555
556
willy tarreaueedaa9f2005-12-17 14:08:03 +01005572.3) Limiting the number of simultaneous connections
558----------------------------------------------------
559The 'maxconn' parameter allows a proxy to refuse connections above a certain
560amount of simultaneous ones. When the limit is reached, it simply stops
561listening, but the system may still be accepting them because of the back log
willy tarreau982249e2005-12-18 00:57:06 +0100562queue. These connections will be processed later when other ones have freed
willy tarreaueedaa9f2005-12-17 14:08:03 +0100563some slots. This provides a serialization effect which helps very fragile
willy tarreau34f45302006-04-15 21:37:14 +0200564servers resist to high loads. See further for system limitations.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100565
566Example :
567---------
568 listen tiny_server 0.0.0.0:80
569 maxconn 10
570
571
5722.4) Soft stop
573--------------
574It is possible to stop services without breaking existing connections by the
willy tarreau22739ef2006-01-20 20:43:32 +0100575sending of the SIGUSR1 signal to the process. All services are then put into
willy tarreaueedaa9f2005-12-17 14:08:03 +0100576soft-stop state, which means that they will refuse to accept new connections,
577except for those which have a non-zero value in the 'grace' parameter, in which
578case they will still accept connections for the specified amount of time, in
willy tarreau22739ef2006-01-20 20:43:32 +0100579milliseconds. This makes it possible to tell a load-balancer that the service
580is failing, while still doing the job during the time it needs to detect it.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100581
582Note: active connections are never killed. In the worst case, the user will have
583to wait for all of them to close or to time-out, or simply kill the process
willy tarreau22739ef2006-01-20 20:43:32 +0100584normally (SIGTERM). The default 'grace' value is '0'.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100585
586Example :
587---------
588 # enter soft stop after 'killall -USR1 haproxy'
589 # the service will still run 10 seconds after the signal
590 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100591 mode http
592 grace 10000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100593
594 # this port is dedicated to a load-balancer, and must fail immediately
595 listen health_check 0.0.0.0:60000
willy tarreauc5f73ed2005-12-18 01:26:38 +0100596 mode health
597 grace 0
willy tarreaueedaa9f2005-12-17 14:08:03 +0100598
599
willy tarreau39df2dc2006-01-29 21:56:05 +0100600As of version 1.2.8, a new soft-reconfiguration mechanism has been introduced.
willy tarreau22739ef2006-01-20 20:43:32 +0100601It is now possible to "pause" all the proxies by sending a SIGTTOU signal to
602the processes. This will disable the listening socket without breaking existing
603connections. After that, sending a SIGTTIN signal to those processes enables
604the listening sockets again. This is very useful to try to load a new
605configuration or even a new version of haproxy without breaking existing
606connections. If the load succeeds, then simply send a SIGUSR1 which will make
607the previous proxies exit immediately once their sessions are closed ; and if
608the load fails, then simply send a SIGTTIN to restore the service immediately.
609Please note that the 'grace' parameter is ignored for SIGTTOU, as well as for
610SIGUSR1 when the process was in the pause mode. Please also note that it would
611be useful to save the pidfile before starting a new instance.
612
willy tarreau34f45302006-04-15 21:37:14 +0200613This mechanism fully exploited since 1.2.11 with the '-st' and '-sf' options
willy tarreau532bb552006-05-13 18:40:37 +0200614(see below).
615
6162.4.1) Hot reconfiguration
617--------------------------
618The '-st' and '-sf' command line options are used to inform previously running
619processes that a configuration is being reloaded. They will receive the SIGTTOU
620signal to ask them to temporarily stop listening to the ports so that the new
621process can grab them. If anything wrong happens, the new process will send
622them a SIGTTIN to tell them to re-listen to the ports and continue their normal
623work. Otherwise, it will either ask them to finish (-sf) their work then softly
624exit, or immediately terminate (-st), breaking existing sessions. A typical use
625of this allows a configuration reload without service interruption :
626
627 # haproxy -p /var/run/haproxy.pid -sf $(cat /var/run/haproxy.pid)
628
willy tarreau22739ef2006-01-20 20:43:32 +0100629
willy tarreaueedaa9f2005-12-17 14:08:03 +01006302.5) Connections expiration time
631--------------------------------
632It is possible (and recommended) to configure several time-outs on TCP
Jamie Gloudon801a0a32012-08-25 00:18:33 -0400633connections. Three independent timers are adjustable with values specified
willy tarreaueedaa9f2005-12-17 14:08:03 +0100634in milliseconds. A session will be terminated if either one of these timers
635expire.
636
637 - the time we accept to wait for data from the client, or for the client to
638 accept data : 'clitimeout' :
639
willy tarreauc5f73ed2005-12-18 01:26:38 +0100640 # client time-out set to 2mn30.
641 clitimeout 150000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100642
643 - the time we accept to wait for data from the server, or for the server to
644 accept data : 'srvtimeout' :
645
willy tarreauc5f73ed2005-12-18 01:26:38 +0100646 # server time-out set to 30s.
647 srvtimeout 30000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100648
649 - the time we accept to wait for a connection to establish on a server :
650 'contimeout' :
651
652 # we give up if the connection does not complete within 4 seconds
willy tarreauc5f73ed2005-12-18 01:26:38 +0100653 contimeout 4000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100654
655Notes :
656-------
657 - 'contimeout' and 'srvtimeout' have no sense on 'health' mode servers ;
658 - under high loads, or with a saturated or defective network, it's possible
659 that some packets get lost. Since the first TCP retransmit only happens
660 after 3 seconds, a time-out equal to, or lower than 3 seconds cannot
661 compensate for a packet loss. A 4 seconds time-out seems a reasonable
662 minimum which will considerably reduce connection failures.
Willy Tarreaubefdff12007-12-02 22:27:38 +0100663 - starting with version 1.3.14, it is possible to specify timeouts in
664 arbitrary time units among { us, ms, s, m, h, d }. For this, the integer
665 value just has to be suffixed with the unit.
willy tarreauc5f73ed2005-12-18 01:26:38 +0100666
willy tarreaueedaa9f2005-12-17 14:08:03 +01006672.6) Attempts to reconnect
668--------------------------
669After a connection failure to a server, it is possible to retry, potentially
670on another server. This is useful if health-checks are too rare and you don't
671want the clients to see the failures. The number of attempts to reconnect is
672set by the 'retries' paramter.
673
674Example :
675---------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100676 # we can retry 3 times max after a failure
677 retries 3
willy tarreaueedaa9f2005-12-17 14:08:03 +0100678
willy tarreau34f45302006-04-15 21:37:14 +0200679Please note that the reconnection attempt may lead to getting the connection
680sent to a new server if the original one died between connection attempts.
681
willy tarreaueedaa9f2005-12-17 14:08:03 +0100682
6832.7) Address of the dispatch server (deprecated)
684------------------------------------------------
685The server which will be sent all new connections is defined by the 'dispatch'
686parameter, in the form <address>:<port>. It generally is dedicated to unknown
687connections and will assign them a cookie, in case of HTTP persistence mode,
688or simply is a single server in case of generic TCP proxy. This old mode is only
689provided for backwards compatibility, but doesn't allow to check remote servers
690state, and has a rather limited usage. All new setups should switch to 'balance'
691mode. The principle of the dispatcher is to be able to perform the load
692balancing itself, but work only on new clients so that the server doesn't need
693to be a big machine.
694
695Example :
696---------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100697 # all new connections go there
698 dispatch 192.168.1.2:80
willy tarreaueedaa9f2005-12-17 14:08:03 +0100699
700Note :
701------
702This parameter has no sense for 'health' servers, and is incompatible with
703'balance' mode.
704
705
7062.8) Outgoing source address
707----------------------------
708It is often necessary to bind to a particular address when connecting to some
709remote hosts. This is done via the 'source' parameter which is a per-proxy
710parameter. A newer version may allow to fix different sources to reach different
711servers. The syntax is 'source <address>[:<port>]', where <address> is a valid
712local address (or '0.0.0.0' or '*' or empty to let the system choose), and
713<port> is an optional parameter allowing the user to force the source port for
714very specific needs. If the port is not specified or is '0', the system will
715choose a free port. Note that as of version 1.1.18, the servers health checks
716are also performed from the same source.
717
718Examples :
719----------
720 listen http_proxy *:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100721 # all connections take 192.168.1.200 as source address
722 source 192.168.1.200:0
willy tarreaueedaa9f2005-12-17 14:08:03 +0100723
724 listen rlogin_proxy *:513
willy tarreauc5f73ed2005-12-18 01:26:38 +0100725 # use address 192.168.1.200 and the reserved port 900 (needs to be root)
726 source 192.168.1.200:900
willy tarreaueedaa9f2005-12-17 14:08:03 +0100727
728
7292.9) Setting the cookie name
730----------------------------
731In HTTP mode, it is possible to look for a particular cookie which will contain
732a server identifier which should handle the connection. The cookie name is set
733via the 'cookie' parameter.
734
735Example :
736---------
737 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100738 mode http
739 cookie SERVERID
willy tarreaueedaa9f2005-12-17 14:08:03 +0100740
741It is possible to change the cookie behaviour to get a smarter persistence,
742depending on applications. It is notably possible to delete or modify a cookie
743emitted by a server, insert a cookie identifying the server in an HTTP response
744and even add a header to tell upstream caches not to cache this response.
745
746Examples :
747----------
748
749To remove the cookie for direct accesses (ie when the server matches the one
750which was specified in the client cookie) :
751
willy tarreauc5f73ed2005-12-18 01:26:38 +0100752 cookie SERVERID indirect
willy tarreaueedaa9f2005-12-17 14:08:03 +0100753
754To replace the cookie value with the one assigned to the server if any (no
755cookie will be created if the server does not provide one, nor if the
756configuration does not provide one). This lets the application put the cookie
757exactly on certain pages (eg: successful authentication) :
758
willy tarreauc5f73ed2005-12-18 01:26:38 +0100759 cookie SERVERID rewrite
willy tarreaueedaa9f2005-12-17 14:08:03 +0100760
761To create a new cookie and assign the server identifier to it (in this case, all
762servers should be associated with a valid cookie, since no cookie will simply
763delete the cookie from the client's browser) :
764
willy tarreauc5f73ed2005-12-18 01:26:38 +0100765 cookie SERVERID insert
willy tarreaueedaa9f2005-12-17 14:08:03 +0100766
willy tarreau0174f312005-12-18 01:02:42 +0100767To reuse an existing application cookie and prefix it with the server's
768identifier, and remove it in the request, use the 'prefix' option. This allows
769to insert a haproxy in front of an application without risking to break clients
770which does not support more than one cookie :
771
willy tarreauc5f73ed2005-12-18 01:26:38 +0100772 cookie JSESSIONID prefix
willy tarreau0174f312005-12-18 01:02:42 +0100773
willy tarreaueedaa9f2005-12-17 14:08:03 +0100774To insert a cookie and ensure that no upstream cache will store it, add the
775'nocache' option :
776
willy tarreauc5f73ed2005-12-18 01:26:38 +0100777 cookie SERVERID insert nocache
willy tarreaueedaa9f2005-12-17 14:08:03 +0100778
779To insert a cookie only after a POST request, add 'postonly' after 'insert'.
780This has the advantage that there's no risk of caching, and that all pages
781seen before the POST one can still be cached :
782
willy tarreauc5f73ed2005-12-18 01:26:38 +0100783 cookie SERVERID insert postonly
willy tarreaueedaa9f2005-12-17 14:08:03 +0100784
785Notes :
786-----------
787- it is possible to combine 'insert' with 'indirect' or 'rewrite' to adapt to
788 applications which already generate the cookie with an invalid content.
789
790- in the case where 'insert' and 'indirect' are both specified, the cookie is
willy tarreau0174f312005-12-18 01:02:42 +0100791 never transmitted to the server, since it wouldn't understand it. This is the
792 most application-transparent mode.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100793
794- it is particularly recommended to use 'nocache' in 'insert' mode if any
795 upstream HTTP/1.0 cache is susceptible to cache the result, because this may
796 lead to many clients going to the same server, or even worse, some clients
797 having their server changed while retrieving a page from the cache.
798
willy tarreau0174f312005-12-18 01:02:42 +0100799- the 'prefix' mode normally does not need 'indirect', 'nocache', nor
800 'postonly', because just as in the 'rewrite' mode, it relies on the
801 application to know when a cookie can be emitted. However, since it has to
802 fix the cookie name in every subsequent requests, you must ensure that the
803 proxy will be used without any "HTTP keep-alive". Use option "httpclose" if
804 unsure.
805
willy tarreaueedaa9f2005-12-17 14:08:03 +0100806- when the application is well known and controlled, the best method is to
807 only add the persistence cookie on a POST form because it's up to the
willy tarreau0174f312005-12-18 01:02:42 +0100808 application to select which page it wants the upstream servers to cache. In
809 this case, you would use 'insert postonly indirect'.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100810
willy tarreauc5f73ed2005-12-18 01:26:38 +0100811
willy tarreaueedaa9f2005-12-17 14:08:03 +01008122.10) Associating a cookie value with a server
813----------------------------------------------
814In HTTP mode, it's possible to associate a cookie value to each server. This
815was initially used in combination with 'dispatch' mode to handle direct accesses
816but it is now the standard way of doing the load balancing. The syntax is :
817
818 server <identifier> <address>:<port> cookie <value>
819
820- <identifier> is any name which can be used to identify the server in the logs.
821- <address>:<port> specifies where the server is bound.
822- <value> is the value to put in or to read from the cookie.
823
824Example : the 'SERVERID' cookie can be either 'server01' or 'server02'
825---------
826 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100827 mode http
828 cookie SERVERID
829 dispatch 192.168.1.100:80
830 server web1 192.168.1.1:80 cookie server01
831 server web2 192.168.1.2:80 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100832
833Warning : the syntax has changed since version 1.0 !
834---------
835
willy tarreauc5f73ed2005-12-18 01:26:38 +0100836
willy tarreau598da412005-12-18 01:07:29 +01008372.11) Application Cookies
838-------------------------
839Since 1.2.4 it is possible to catch the cookie that comes from an
840application server in order to apply "application session stickyness".
841The server's response is searched for 'appsession' cookie, the first
842'len' bytes are used for matching and it is stored for a period of
843'timeout'.
844The syntax is:
845
willy tarreau532bb552006-05-13 18:40:37 +0200846 appsession <session_cookie> len <match_length> timeout <holdtime>
willy tarreau598da412005-12-18 01:07:29 +0100847
willy tarreau532bb552006-05-13 18:40:37 +0200848- <session_cookie> is the cookie, the server uses for it's session-handling
849- <match_length> how many bytes/characters should be used for matching equal
willy tarreau598da412005-12-18 01:07:29 +0100850 sessions
willy tarreau532bb552006-05-13 18:40:37 +0200851- <holdtime> after this inactivaty time, in ms, the cookie will be deleted
willy tarreau598da412005-12-18 01:07:29 +0100852 from the sessionstore
Willy Tarreaubefdff12007-12-02 22:27:38 +0100853- starting with version 1.3.14, it is possible to specify timeouts in
854 arbitrary time units among { us, ms, s, m, h, d }. For this, the integer
855 value just has to be prefixed with the unit.
willy tarreau598da412005-12-18 01:07:29 +0100856
857The appsession is only per 'listen' section possible.
858
859Example :
860---------
willy tarreau532bb552006-05-13 18:40:37 +0200861 listen http_lb1 192.168.3.4:80
862 mode http
863 capture request header Cookie len 200
864 # Havind a ServerID cookie on the client allows him to reach
865 # the right server even after expiration of the appsession.
866 cookie ServerID insert nocache indirect
867 # Will memorize 52 bytes of the cookie 'JSESSIONID' and keep them
868 # for 3 hours. It will match it in the cookie and the URL field.
Willy Tarreaubefdff12007-12-02 22:27:38 +0100869 appsession JSESSIONID len 52 timeout 3h
willy tarreau532bb552006-05-13 18:40:37 +0200870 server first1 10.3.9.2:10805 check inter 3000 cookie first
871 server secon1 10.3.9.3:10805 check inter 3000 cookie secon
872 server first1 10.3.9.4:10805 check inter 3000 cookie first
873 server secon2 10.3.9.5:10805 check inter 3000 cookie secon
874 option httpchk GET /test.jsp
willy tarreau598da412005-12-18 01:07:29 +0100875
willy tarreauc5f73ed2005-12-18 01:26:38 +0100876
willy tarreaueedaa9f2005-12-17 14:08:03 +01008773) Autonomous load balancer
878===========================
879
880The proxy can perform the load-balancing itself, both in TCP and in HTTP modes.
881This is the most interesting mode which obsoletes the old 'dispatch' mode
882described above. It has advantages such as server health monitoring, multiple
883port binding and port mapping. To use this mode, the 'balance' keyword is used,
willy tarreau34f45302006-04-15 21:37:14 +0200884followed by the selected algorithm. Up to version 1.2.11, only 'roundrobin' was
885available, which is also the default value if unspecified. Starting with
Willy Tarreau2fcb5002007-05-08 13:35:26 +0200886version 1.2.12, a new 'source' keyword appeared. A new 'uri' keyword was added
887in version 1.3.10. In this mode, there will be no dispatch address, but the
888proxy needs at least one server.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100889
890Example : same as the last one, with internal load balancer
891---------
892
893 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100894 mode http
895 cookie SERVERID
896 balance roundrobin
897 server web1 192.168.1.1:80 cookie server01
898 server web2 192.168.1.2:80 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100899
900
901Since version 1.1.22, it is possible to automatically determine on which port
902the server will get the connection, depending on the port the client connected
903to. Indeed, there now are 4 possible combinations for the server's <port> field:
904
905 - unspecified or '0' :
906 the connection will be sent to the same port as the one on which the proxy
907 received the client connection itself.
908
909 - numerical value (the only one supported in versions earlier than 1.1.22) :
910 the connection will always be sent to the specified port.
911
912 - '+' followed by a numerical value :
913 the connection will be sent to the same port as the one on which the proxy
914 received the connection, plus this value.
915
916 - '-' followed by a numerical value :
917 the connection will be sent to the same port as the one on which the proxy
918 received the connection, minus this value.
919
920Examples :
921----------
922
923# same as previous example
924
925 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100926 mode http
927 cookie SERVERID
928 balance roundrobin
929 server web1 192.168.1.1 cookie server01
930 server web2 192.168.1.2 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100931
932# simultaneous relaying of ports 80, 81 and 8080-8089
933
934 listen http_proxy :80,:81,:8080-8089
willy tarreauc5f73ed2005-12-18 01:26:38 +0100935 mode http
936 cookie SERVERID
937 balance roundrobin
938 server web1 192.168.1.1 cookie server01
939 server web2 192.168.1.2 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100940
941# relaying of TCP ports 25, 389 and 663 to ports 1025, 1389 and 1663
942
943 listen http_proxy :25,:389,:663
willy tarreauc5f73ed2005-12-18 01:26:38 +0100944 mode tcp
945 balance roundrobin
946 server srv1 192.168.1.1:+1000
947 server srv2 192.168.1.2:+1000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100948
willy tarreau34f45302006-04-15 21:37:14 +0200949As previously stated, version 1.2.12 brought the 'source' keyword. When this
950keyword is used, the client's IP address is hashed and evenly distributed among
951the available servers so that a same source IP will always go to the same
952server as long as there are no change in the number of available servers. This
953can be used for instance to bind HTTP and HTTPS to the same server. It can also
954be used to improve stickyness when one part of the client population does not
955accept cookies. In this case, only those ones will be perturbated should a
956server fail.
957
958NOTE: It is important to consider the fact that many clients surf the net
959 through proxy farms which assign different IP addresses for each
960 request. Others use dialup connections with a different IP at each
961 connection. Thus, the 'source' parameter should be used with extreme
962 care.
963
964Examples :
965----------
966
967# make a same IP go to the same server whatever the service
968
969 listen http_proxy
970 bind :80,:443
971 mode http
972 balance source
973 server web1 192.168.1.1
974 server web2 192.168.1.2
975
976# try to improve client-server binding by using both source IP and cookie :
977
978 listen http_proxy :80
979 mode http
980 cookie SERVERID
981 balance source
982 server web1 192.168.1.1 cookie server01
983 server web2 192.168.1.2 cookie server02
984
Willy Tarreau2fcb5002007-05-08 13:35:26 +0200985As indicated above, the 'uri' keyword was introduced in version 1.3.10. It is
986useful when load-balancing between reverse proxy-caches, because it will hash
987the URI and use the hash result to select a server, thus optimizing the hit
988rate on the caches, because the same URI will always reach the same cache. This
989keyword is only allowed in HTTP mode.
990
991Example :
992---------
993
994# Always send a given URI to the same server
995
996 listen http_proxy
997 bind :3128
998 mode http
999 balance uri
1000 server squid1 192.168.1.1
1001 server squid2 192.168.1.2
1002
Willy Tarreau01732802007-11-01 22:48:15 +01001003Version 1.3.14 introduced the "balance url_param" method. It consists in
1004relying on a parameter passed in the URL to perform a hash. This is mostly
1005useful for applications which do not have strict persistence requirements,
1006but for which it still provides a performance boost due to local caching.
1007Some of these applications may not be able to use a cookie for whatever reason,
1008but may be able to look for a parameter passed in the URL. If the parameter is
1009missing from the URL, then the 'round robin' method applies.
1010
matt.farnsworth@nokia.com1c2ab962008-04-14 20:47:37 +02001011A modifier may be added to specify that parameters in POST requests may be
1012found in the messsage body if the URL lacks a '?' separator character.
1013A wait limit may also be applied, if no limit is requested then
1014the default value is 48 octets, the minimum is 3. HAProxy may wait, until 48
1015octets are received. If Content-Length is missing, or zero it need not
1016wait for more data then the client promissed to send. When Content-Length is
1017present, and more than <max_wait>; then waiting is limited and it is assumed this
1018will be enough data to search for the presence of a parameter. If
1019Transfer-Encoding: chunked is used (unlikely), then the length of the first chunk
1020is the maximum number of bytes to wait for.
1021
1022balance url_param <param> [check_post [<max_wait>]]
1023
1024Caveats for using the check_post extension:
1025
1026 - all POST requests are eligable for consideration, because there is
1027 no way to determine if the parameters will be found in the body or
1028 entity which may contain binary data. Therefore another method may be
1029 required to restrict consideration of POST requests that have no URL
1030 parameters in the body. (see acl reqideny http_end)
1031
1032Limitations on inspecting the entity body of a POST:
1033
1034 - Content-Encoding is not supported, the parameter search will probably fail;
1035 and load balancing will fall back to Round Robin.
1036
1037 - Expect: 100-continue is not supported, load balancing will fall back to
1038 Round Robin.
1039
1040 - Transfer-Encoding(RFC2616 3.6.1) is only supported in the first chunk. If
1041 the entire parameter value is not present in the first chunk, the selection
1042 of server is undefined (actually, defined by how little actually appeared in
1043 the first chunk).
1044
1045 - This feature does not support generation of a 100, 411 or 501 response.
1046
1047 - In some cases, requesting check_post MAY attempt to scan the entire contents
1048 of a message body. Scaning normally terminates when linear white space or
1049 control characters are found, indicating the end of what might be a URL parameter
1050 list. This is probably not a concern with SGML type message bodies.
1051
1052
Willy Tarreau01732802007-11-01 22:48:15 +01001053Example :
1054---------
1055
1056# Hash the "basket_id" argument from the URL to determine the server
1057
1058 listen http_proxy
1059 bind :3128
1060 mode http
1061 balance url_param basket_id
1062 server ebiz1 192.168.1.1
1063 server ebiz2 192.168.1.2
1064
willy tarreaueedaa9f2005-12-17 14:08:03 +01001065
willy tarreau197e8ec2005-12-17 14:10:59 +010010663.1) Server monitoring
1067----------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +01001068It is possible to check the servers status by trying to establish TCP
1069connections or even sending HTTP requests to them. A server which fails to
1070reply to health checks as expected will not be used by the load balancing
1071algorithms. To enable monitoring, add the 'check' keyword on a server line.
1072It is possible to specify the interval between tests (in milliseconds) with
1073the 'inter' parameter, the number of failures supported before declaring that
1074the server has fallen down with the 'fall' parameter, and the number of valid
1075checks needed for the server to fully get up with the 'rise' parameter. Since
1076version 1.1.22, it is also possible to send checks to a different port
1077(mandatory when none is specified) with the 'port' parameter. The default
1078values are the following ones :
1079
1080 - inter : 2000
1081 - rise : 2
1082 - fall : 3
1083 - port : default server port
Willy Tarreau2ea3abb2007-03-25 16:45:16 +02001084 - addr : specific address for the test (default = address server)
1085
willy tarreaueedaa9f2005-12-17 14:08:03 +01001086The default mode consists in establishing TCP connections only. But in certain
1087types of application failures, it is often that the server continues to accept
1088connections because the system does it itself while the application is running
1089an endless loop, or is completely stuck. So in version 1.1.16 were introduced
1090HTTP health checks which only performed simple lightweight requests and analysed
1091the response. Now, as of version 1.1.23, it is possible to change the HTTP
1092method, the URI, and the HTTP version string (which even allows to send headers
1093with a dirty trick). To enable HTTP health-checks, use 'option httpchk'.
1094
1095By default, requests use the 'OPTIONS' method because it's very light and easy
1096to filter from logs, and does it on '/'. Only HTTP responses 2xx and 3xx are
1097considered valid ones, and only if they come before the time to send a new
1098request is reached ('inter' parameter). If some servers block this type of
1099request, 3 other forms help to forge a request :
1100
1101 - option httpchk -> OPTIONS / HTTP/1.0
1102 - option httpchk URI -> OPTIONS <URI> HTTP/1.0
1103 - option httpchk METH URI -> <METH> <URI> HTTP/1.0
1104 - option httpchk METH URI VER -> <METH> <URI> <VER>
1105
Willy Tarreauf3c69202006-07-09 16:42:34 +02001106Some people are using HAProxy to relay various TCP-based protocols such as
1107HTTPS, SMTP or LDAP, with the most common one being HTTPS. One problem commonly
1108encountered in data centers is the need to forward the traffic to far remote
1109servers while providing server fail-over. Often, TCP-only checks are not enough
1110because intermediate firewalls, load balancers or proxies might acknowledge the
1111connection before it reaches the real server. The only solution to this problem
1112is to send application-level health checks. Since the demand for HTTPS checks
1113is high, it has been implemented in 1.2.15 based on SSLv3 Client Hello packets.
1114To enable it, use 'option ssl-hello-chk'. It will send SSL CLIENT HELLO packets
1115to the servers, announcing support for most common cipher suites. If the server
1116responds what looks like a SERVER HELLO or an ALERT (refuses the ciphers) then
1117the response is considered as valid. Note that Apache does not generate a log
1118when it receives only an HELLO message, which makes this type of message
1119perfectly suit this need.
1120
Willy Tarreau23677902007-05-08 23:50:35 +02001121Version 1.3.10 introduced the SMTP health check. By default, it sends
1122"HELO localhost" to the servers, and waits for the 250 message. Note that it
1123can also send a specific request :
1124
1125 - option smtpchk -> sends "HELO localhost"
1126 - option smtpchk EHLO mail.mydomain.com -> sends this ESMTP greeting
1127
willy tarreaueedaa9f2005-12-17 14:08:03 +01001128See examples below.
1129
1130Since version 1.1.17, it is possible to specify backup servers. These servers
1131are only sollicited when no other server is available. This may only be useful
1132to serve a maintenance page, or define one active and one backup server (seldom
1133used in TCP mode). To make a server a backup one, simply add the 'backup' option
1134on its line. These servers also support cookies, so if a cookie is specified for
1135a backup server, clients assigned to this server will stick to it even when the
1136other ones come back. Conversely, if no cookie is assigned to such a server,
1137the clients will get their cookies removed (empty cookie = removal), and will
1138be balanced against other servers once they come back. Please note that there
Willy TARREAU3481c462006-03-01 22:37:57 +01001139is no load-balancing among backup servers by default. If there are several
1140backup servers, the second one will only be used when the first one dies, and
1141so on. To force load-balancing between backup servers, specify the 'allbackups'
1142option.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001143
Willy Tarreau2ea3abb2007-03-25 16:45:16 +02001144Since version 1.1.22, it is possible to send health checks to a different port
1145than the service. It is mainly needed in setups where the server does not have
1146any predefined port, for instance when the port is deduced from the listening
1147port. For this, use the 'port' parameter followed by the port number which must
1148respond to health checks. It is also possible to send health checks to a
1149different address than the service. It makes it easier to use a dedicated check
1150daemon on the servers, for instance, check return contents and stop several
1151farms at once in the event of an error anywhere.
1152
willy tarreaueedaa9f2005-12-17 14:08:03 +01001153Since version 1.1.17, it is also possible to visually check the status of all
1154servers at once. For this, you just have to send a SIGHUP signal to the proxy.
1155The servers status will be dumped into the logs at the 'notice' level, as well
1156as on <stderr> if not closed. For this reason, it's always a good idea to have
1157one local log server at the 'notice' level.
1158
willy tarreau982249e2005-12-18 00:57:06 +01001159Since version 1.1.28 and 1.2.1, if an instance loses all its servers, an
willy tarreau0174f312005-12-18 01:02:42 +01001160emergency message will be sent in the logs to inform the administator that an
willy tarreau982249e2005-12-18 00:57:06 +01001161immediate action must be taken.
1162
willy tarreau0174f312005-12-18 01:02:42 +01001163Since version 1.1.30 and 1.2.3, several servers can share the same cookie
1164value. This is particularly useful in backup mode, to select alternate paths
1165for a given server for example, to provide soft-stop, or to direct the clients
1166to a temporary page during an application restart. The principle is that when
1167a server is dead, the proxy will first look for another server which shares the
1168same cookie value for every client which presents the cookie. If there is no
1169standard server for this cookie, it will then look for a backup server which
1170shares the same name. Please consult the architecture guide for more information.
willy tarreau982249e2005-12-18 00:57:06 +01001171
willy tarreaueedaa9f2005-12-17 14:08:03 +01001172Examples :
1173----------
1174# same setup as in paragraph 3) with TCP monitoring
1175 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001176 mode http
1177 cookie SERVERID
1178 balance roundrobin
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
1182# same with HTTP monitoring via 'OPTIONS / HTTP/1.0'
1183 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001184 mode http
1185 cookie SERVERID
1186 balance roundrobin
1187 option httpchk
1188 server web1 192.168.1.1:80 cookie server01 check
1189 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +01001190
1191# same with HTTP monitoring via 'OPTIONS /index.html HTTP/1.0'
1192 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001193 mode http
1194 cookie SERVERID
1195 balance roundrobin
1196 option httpchk /index.html
1197 server web1 192.168.1.1:80 cookie server01 check
1198 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +01001199
1200# same with HTTP monitoring via 'HEAD /index.jsp? HTTP/1.1\r\nHost: www'
1201 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001202 mode http
1203 cookie SERVERID
1204 balance roundrobin
1205 option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
1206 server web1 192.168.1.1:80 cookie server01 check
1207 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +01001208
willy tarreau0174f312005-12-18 01:02:42 +01001209# Load-balancing with 'prefixed cookie' persistence, and soft-stop using an
1210# alternate port 81 on the server for health-checks.
1211 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001212 mode http
1213 cookie JSESSIONID prefix
1214 balance roundrobin
1215 option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
1216 server web1-norm 192.168.1.1:80 cookie s1 check port 81
1217 server web2-norm 192.168.1.2:80 cookie s2 check port 81
1218 server web1-stop 192.168.1.1:80 cookie s1 check port 80 backup
1219 server web2-stop 192.168.1.2:80 cookie s2 check port 80 backup
willy tarreau0174f312005-12-18 01:02:42 +01001220
willy tarreaueedaa9f2005-12-17 14:08:03 +01001221# automatic insertion of a cookie in the server's response, and automatic
1222# deletion of the cookie in the client request, while asking upstream caches
1223# not to cache replies.
1224 listen web_appl 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001225 mode http
1226 cookie SERVERID insert nocache indirect
1227 balance roundrobin
1228 server web1 192.168.1.1:80 cookie server01 check
1229 server web2 192.168.1.2:80 cookie server02 check
willy tarreaueedaa9f2005-12-17 14:08:03 +01001230
1231# same with off-site application backup and local error pages server
1232 listen web_appl 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001233 mode http
1234 cookie SERVERID insert nocache indirect
1235 balance roundrobin
1236 server web1 192.168.1.1:80 cookie server01 check
1237 server web2 192.168.1.2:80 cookie server02 check
1238 server web-backup 192.168.2.1:80 cookie server03 check backup
1239 server web-excuse 192.168.3.1:80 check backup
willy tarreaueedaa9f2005-12-17 14:08:03 +01001240
willy tarreauc5f73ed2005-12-18 01:26:38 +01001241# SMTP+TLS relaying with health-checks and backup servers
willy tarreaueedaa9f2005-12-17 14:08:03 +01001242
1243 listen http_proxy :25,:587
willy tarreauc5f73ed2005-12-18 01:26:38 +01001244 mode tcp
1245 balance roundrobin
1246 server srv1 192.168.1.1 check port 25 inter 30000 rise 1 fall 2
1247 server srv2 192.168.1.2 backup
willy tarreaueedaa9f2005-12-17 14:08:03 +01001248
Willy Tarreauf3c69202006-07-09 16:42:34 +02001249# HTTPS relaying with health-checks and backup servers
1250
1251 listen http_proxy :443
1252 mode tcp
1253 option ssl-hello-chk
1254 balance roundrobin
1255 server srv1 192.168.1.1 check inter 30000 rise 1 fall 2
1256 server srv2 192.168.1.2 backup
1257
Willy TARREAU3481c462006-03-01 22:37:57 +01001258# Load-balancing using a backup pool (requires haproxy 1.2.9)
1259 listen http_proxy 0.0.0.0:80
1260 mode http
1261 balance roundrobin
1262 option httpchk
1263 server inst1 192.168.1.1:80 cookie s1 check
1264 server inst2 192.168.1.2:80 cookie s2 check
1265 server inst3 192.168.1.3:80 cookie s3 check
1266 server back1 192.168.1.10:80 check backup
1267 server back2 192.168.1.11:80 check backup
1268 option allbackups # all backups will be used
1269
willy tarreaueedaa9f2005-12-17 14:08:03 +01001270
12713.2) Redistribute connections in case of failure
1272------------------------------------------------
1273In HTTP mode, if a server designated by a cookie does not respond, the clients
1274may definitely stick to it because they cannot flush the cookie, so they will
1275not be able to access the service anymore. Specifying 'redispatch' will allow
1276the proxy to break their persistence and redistribute them to working servers.
1277
1278Example :
1279---------
1280 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001281 mode http
1282 cookie SERVERID
1283 dispatch 192.168.1.100:80
1284 server web1 192.168.1.1:80 cookie server01
1285 server web2 192.168.1.2:80 cookie server02
1286 redispatch # send back to dispatch in case of connection failure
willy tarreaueedaa9f2005-12-17 14:08:03 +01001287
1288Up to, and including version 1.1.16, this parameter only applied to connection
1289failures. Since version 1.1.17, it also applies to servers which have been
1290detected as failed by the health check mechanism. Indeed, a server may be broken
1291but still accepting connections, which would not solve every case. But it is
1292possible to conserve the old behaviour, that is, make a client insist on trying
1293to connect to a server even if it is said to be down, by setting the 'persist'
1294option :
1295
1296 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001297 mode http
1298 option persist
1299 cookie SERVERID
1300 dispatch 192.168.1.100:80
1301 server web1 192.168.1.1:80 cookie server01
1302 server web2 192.168.1.2:80 cookie server02
1303 redispatch # send back to dispatch in case of connection failure
willy tarreaueedaa9f2005-12-17 14:08:03 +01001304
1305
willy tarreau34f45302006-04-15 21:37:14 +020013063.3) Assigning different weights to servers
1307-------------------------------------------
1308Sometimes you will need to bring new servers to increase your server farm's
1309capacity, but the new server will be either smaller (emergency use of anything
1310that fits) or bigger (when investing in new hardware). For this reason, it
1311might be wise to be able to send more clients to biggest servers. Till version
13121.2.11, it was necessary to replicate the same server multiple times in the
1313configuration. Starting with 1.2.12, the 'weight' option is available. HAProxy
1314then computes the most homogenous possible map of servers based on their
willy tarreau532bb552006-05-13 18:40:37 +02001315weights so that the load gets distributed as smoothly as possible among them.
1316The weight, between 1 and 256, should reflect one server's capacity relative to
1317others. Weight 1 represents the lowest frequency and 256 the highest. This way,
1318if a server fails, the remaining capacities are still respected.
willy tarreau34f45302006-04-15 21:37:14 +02001319
1320Example :
1321---------
1322# fair distribution among two opterons and one old pentium3
1323
1324 listen web_appl 0.0.0.0:80
1325 mode http
1326 cookie SERVERID insert nocache indirect
1327 balance roundrobin
1328 server pentium3-800 192.168.1.1:80 cookie server01 weight 8 check
1329 server opteron-2.0G 192.168.1.2:80 cookie server02 weight 20 check
1330 server opteron-2.4G 192.168.1.3:80 cookie server03 weight 24 check
1331 server web-backup1 192.168.2.1:80 cookie server04 check backup
1332 server web-excuse 192.168.3.1:80 check backup
1333
1334Notes :
1335-------
1336 - if unspecified, the default weight is 1
1337
1338 - the weight does not impact health checks, so it is cleaner to use weights
1339 than replicating the same server several times
1340
1341 - weights also work on backup servers if the 'allbackups' option is used
1342
1343 - the weights also apply to the source address load balancing
1344 ('balance source').
1345
1346 - whatever the weights, the first server will always be assigned first. This
1347 is helpful for troubleshooting.
1348
1349 - for the purists, the map calculation algorithm gives precedence to first
1350 server, so the map is the most uniform when servers are declared in
1351 ascending order relative to their weights.
1352
willy tarreau532bb552006-05-13 18:40:37 +02001353The load distribution will follow exactly this sequence :
1354
1355 Request| 1 1 1 1
1356 number | 1 2 3 4 5 6 7 8 9 0 1 2 3
1357 --------+---------------------------
1358 p3-800 | X . . . . . . X . . . . .
1359 opt-20 | . X . X . X . . . X . X .
1360 opt-24 | . . X . X . X . X . X . X
1361
1362
13633.4) Limiting the number of concurrent sessions on each server
1364--------------------------------------------------------------
1365Some pre-forked servers such as Apache suffer from too many concurrent
1366sessions, because it's very expensive to run hundreds or thousands of
1367processes on one system. One solution is to increase the number of servers
1368and load-balance between them, but it is a problem when the only goal is
1369to resist to short surges.
1370
1371To solve this problem, a new feature was implemented in HAProxy 1.2.13.
1372It's a per-server 'maxconn', associated with a per-server and a per-proxy
1373queue. This transforms haproxy into a request buffer between the thousands of
1374clients and the few servers. On many circumstances, lowering the maxconn value
1375will increase the server's performance and decrease the overall response times
1376because the servers will be less congested.
1377
1378When a request tries to reach any server, the first non-saturated server is
1379used, respective to the load balancing algorithm. If all servers are saturated,
1380then the request gets queued into the instance's global queue. It will be
1381dequeued once a server will have freed a session and all previously queued
1382requests have been processed.
1383
1384If a request references a particular server (eg: source hashing, or persistence
1385cookie), and if this server is full, then the request will be queued into the
1386server's dedicated queue. This queue has higher priority than the global queue,
1387so it's easier for already registered users to enter the site than for new
1388users.
1389
1390For this, the logs have been enhanced to show the number of sessions per
1391server, the request's position in the queue and the time spent in the queue.
1392This helps doing capacity planning. See the 'logs' section below for more info.
1393
1394Example :
1395---------
1396 # be nice with P3 which only has 256 MB of RAM.
1397 listen web_appl 0.0.0.0:80
1398 maxconn 10000
1399 mode http
1400 cookie SERVERID insert nocache indirect
1401 balance roundrobin
1402 server pentium3-800 192.168.1.1:80 cookie s1 weight 8 maxconn 100 check
1403 server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 maxconn 300 check
1404 server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 maxconn 300 check
1405 server web-backup1 192.168.2.1:80 cookie s4 check maxconn 200 backup
1406 server web-excuse 192.168.3.1:80 check backup
1407
willy tarreauf76e6ca2006-05-21 21:09:55 +02001408
1409This was so much efficient at reducing the server's response time that some
1410users wanted to use low values to improve their server's performance. However,
1411they were not able anymore to handle very large loads because it was not
1412possible anymore to saturate the servers. For this reason, version 1.2.14 has
1413brought dynamic limitation with the addition of the parameter 'minconn'. When
1414this parameter is set along with maxconn, it will enable dynamic limitation
1415based on the instance's load. The maximum number of concurrent sessions on a
1416server will be proportionnal to the number of sessions on the instance relative
1417to its maxconn. A minimum of <minconn> will be allowed whatever the load. This
1418will ensure that servers will perform at their best level under normal loads,
1419while still handling surges when needed. The dynamic limit is computed like
1420this :
1421
1422 srv.dyn_limit = max(srv.minconn, srv.maxconn * inst.sess / inst.maxconn)
1423
1424Example :
1425---------
1426 # be nice with P3 which only has 256 MB of RAM.
1427 listen web_appl 0.0.0.0:80
1428 maxconn 10000
1429 mode http
1430 cookie SERVERID insert nocache indirect
1431 balance roundrobin
1432 server pentium3-800 192.168.1.1:80 cookie s1 weight 8 minconn 10 maxconn 100 check
1433 server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 minconn 30 maxconn 300 check
1434 server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 minconn 30 maxconn 300 check
1435 server web-backup1 192.168.2.1:80 cookie s4 check maxconn 200 backup
1436 server web-excuse 192.168.3.1:80 check backup
1437
1438In the example above, the server 'pentium3-800' will receive at most 100
1439simultaneous sessions when the proxy instance will reach 10000 sessions, and
1440will receive only 10 simultaneous sessions when the proxy will be under 1000
1441sessions.
1442
Elijah Epifanovacafc5f2007-10-25 20:15:38 +02001443It is possible to limit server queue length in order to rebalance excess
1444sessions between less busy application servers IF session affinity isn't
1445hard functional requirement (for example it just gives huge performance boost
1446by keeping server-local caches hot and compact). 'maxqueue' option sets a
1447queue limit on a server, as in example below:
1448
1449... (just the same as in example above)
1450 server pentium3-800 192.168.1.1:80 cookie s1 weight 8 minconn 10 maxconn 100 check maxqueue 50
1451 server opteron-2.0G 192.168.1.2:80 cookie s2 weight 20 minconn 30 maxconn 300 check maxqueue 200
1452 server opteron-2.4G 192.168.1.3:80 cookie s3 weight 24 minconn 30 maxconn 300 check
1453
1454Absence of 'maxqueue' option means unlimited queue. When queue gets filled
1455up to 'maxqueue' client session is moved from server-local queue to a global
1456one.
1457
willy tarreau532bb552006-05-13 18:40:37 +02001458Notes :
1459-------
1460 - The requests will not stay indefinitely in the queue, they follow the
1461 'contimeout' parameter, and if a request cannot be dequeued within this
1462 timeout because the server is saturated or because the queue is filled,
1463 the session will expire with a 503 error.
1464
willy tarreauf76e6ca2006-05-21 21:09:55 +02001465 - if only <minconn> is specified, it has the same effect as <maxconn>
1466
willy tarreau532bb552006-05-13 18:40:37 +02001467 - setting too low values for maxconn might improve performance but might also
1468 allow slow users to block access to the server for other users.
1469
willy tarreau34f45302006-04-15 21:37:14 +02001470
willy tarreaue0bdd622006-05-21 20:51:54 +020014713.5) Dropping aborted requests
1472------------------------------
1473In presence of very high loads, the servers will take some time to respond. The
1474per-proxy's connection queue will inflate, and the response time will increase
1475respective to the size of the queue times the average per-session response
1476time. When clients will wait for more than a few seconds, they will often hit
1477the 'STOP' button on their browser, leaving a useless request in the queue, and
1478slowing down other users.
1479
1480As there is no way to distinguish between a full STOP and a simple
1481shutdown(SHUT_WR) on the client side, HTTP agents should be conservative and
1482consider that the client might only have closed its output channel while
1483waiting for the response. However, this introduces risks of congestion when
1484lots of users do the same, and is completely useless nowadays because probably
1485no client at all will close the session while waiting for the response. Some
1486HTTP agents support this (Squid, Apache, HAProxy), and others do not (TUX, most
1487hardware-based load balancers). So the probability for a closed input channel
1488to represent a user hitting the 'STOP' button is close to 100%, and it is very
1489tempting to be able to abort the session early without polluting the servers.
1490
1491For this reason, a new option "abortonclose" was introduced in version 1.2.14.
1492By default (without the option) the behaviour is HTTP-compliant. But when the
1493option is specified, a session with an incoming channel closed will be aborted
1494if it's still possible, which means that it's either waiting for a connect() to
1495establish or it is queued waiting for a connection slot. This considerably
1496reduces the queue size and the load on saturated servers when users are tempted
1497to click on STOP, which in turn reduces the response time for other users.
1498
1499Example :
1500---------
1501 listen web_appl 0.0.0.0:80
1502 maxconn 10000
1503 mode http
1504 cookie SERVERID insert nocache indirect
1505 balance roundrobin
1506 server web1 192.168.1.1:80 cookie s1 weight 10 maxconn 100 check
1507 server web2 192.168.1.2:80 cookie s2 weight 10 maxconn 100 check
1508 server web3 192.168.1.3:80 cookie s3 weight 10 maxconn 100 check
1509 server bck1 192.168.2.1:80 cookie s4 check maxconn 200 backup
1510 option abortonclose
1511
1512
willy tarreaueedaa9f2005-12-17 14:08:03 +010015134) Additionnal features
1514=======================
1515
willy tarreau481132e2006-05-21 21:43:10 +02001516Other features are available. They are transparent mode, event logging, header
1517rewriting/filtering, and the status as an HTML page.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001518
willy tarreauc5f73ed2005-12-18 01:26:38 +01001519
willy tarreau0174f312005-12-18 01:02:42 +010015204.1) Network features
willy tarreaueedaa9f2005-12-17 14:08:03 +01001521---------------------
willy tarreau0174f312005-12-18 01:02:42 +010015224.1.1) Transparent mode
1523-----------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +01001524In HTTP mode, the 'transparent' keyword allows to intercept sessions which are
1525routed through the system hosting the proxy. This mode was implemented as a
1526replacement for the 'dispatch' mode, since connections without cookie will be
1527sent to the original address while known cookies will be sent to the servers.
1528This mode implies that the system can redirect sessions to a local port.
1529
1530Example :
1531---------
1532 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001533 mode http
1534 transparent
1535 cookie SERVERID
1536 server server01 192.168.1.1:80
1537 server server02 192.168.1.2:80
willy tarreaueedaa9f2005-12-17 14:08:03 +01001538
1539 # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
1540 --dport 80 -j REDIRECT --to-ports 65000
1541
1542Note :
1543------
1544If the port is left unspecified on the server, the port the client connected to
1545will be used. This allows to relay a full port range without using transparent
1546mode nor thousands of file descriptors, provided that the system can redirect
1547sessions to local ports.
1548
1549Example :
1550---------
1551 # redirect all ports to local port 65000, then forward to the server on the
1552 # original port.
1553 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001554 mode tcp
1555 server server01 192.168.1.1 check port 60000
1556 server server02 192.168.1.2 check port 60000
willy tarreaueedaa9f2005-12-17 14:08:03 +01001557
1558 # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
1559 -j REDIRECT --to-ports 65000
1560
willy tarreau0174f312005-12-18 01:02:42 +010015614.1.2) Per-server source address binding
1562----------------------------------------
1563As of versions 1.1.30 and 1.2.3, it is possible to specify a particular source
1564to reach each server. This is useful when reaching backup servers from a
1565different LAN, or to use an alternate path to reach the same server. It is also
1566usable to provide source load-balancing for outgoing connections. Obviously,
1567the same source address is used to send health-checks.
1568
1569Example :
1570---------
1571 # use a particular source to reach both servers
1572 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001573 mode http
1574 balance roundrobin
1575 server server01 192.168.1.1:80 source 192.168.2.13
1576 server server02 192.168.1.2:80 source 192.168.2.13
willy tarreau0174f312005-12-18 01:02:42 +01001577
1578Example :
1579---------
1580 # use a particular source to reach each servers
1581 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001582 mode http
1583 balance roundrobin
1584 server server01 192.168.1.1:80 source 192.168.1.1
1585 server server02 192.168.2.1:80 source 192.168.2.1
willy tarreau0174f312005-12-18 01:02:42 +01001586
1587Example :
1588---------
1589 # provide source load-balancing to reach the same proxy through 2 WAN links
1590 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001591 mode http
1592 balance roundrobin
1593 server remote-proxy-way1 192.168.1.1:3128 source 192.168.2.1
1594 server remote-proxy-way2 192.168.1.1:3128 source 192.168.3.1
willy tarreau0174f312005-12-18 01:02:42 +01001595
1596Example :
1597---------
1598 # force a TCP connection to bind to a specific port
1599 listen http_proxy 0.0.0.0:2000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001600 mode tcp
1601 balance roundrobin
1602 server srv1 192.168.1.1:80 source 192.168.2.1:20
1603 server srv2 192.168.1.2:80 source 192.168.2.1:20
willy tarreau0174f312005-12-18 01:02:42 +01001604
willy tarreaub952e1d2005-12-18 01:31:20 +010016054.1.3) TCP keep-alive
1606---------------------
1607With version 1.2.7, it becomes possible to enable TCP keep-alives on both the
1608client and server sides. This makes it possible to prevent long sessions from
1609expiring on external layer 4 components such as firewalls and load-balancers.
1610It also allows the system to terminate dead sessions when no timeout has been
1611set (not recommanded). The proxy cannot set the keep-alive probes intervals nor
1612maximal count, consult your operating system manual for this. There are 3
1613options to enable TCP keep-alive :
1614
1615 option tcpka # enables keep-alive both on client and server side
1616 option clitcpka # enables keep-alive only on client side
1617 option srvtcpka # enables keep-alive only on server side
1618
Alexandre Cassen87ea5482007-10-11 20:48:58 +020016194.1.4) TCP lingering
1620--------------------
1621It is possible to disable the system's lingering of data unacked by the client
1622at the end of a session. This is sometimes required when haproxy is used as a
1623front-end with lots of unreliable clients, and you observe thousands of sockets
1624in the FIN_WAIT state on the machine. This may be used in a frontend to affect
1625the client-side connection, as well as in a backend for the server-side
1626connection :
1627
1628 option nolinger # disables data lingering
1629
willy tarreaueedaa9f2005-12-17 14:08:03 +01001630
16314.2) Event logging
1632------------------
willy tarreauc5f73ed2005-12-18 01:26:38 +01001633
1634HAProxy's strength certainly lies in its precise logs. It probably provides the
1635finest level of information available for such a product, which is very
1636important for troubleshooting complex environments. Standard log information
1637include client ports, TCP/HTTP state timers, precise session state at
1638termination and precise termination cause, information about decisions to
1639direct trafic to a server, and of course the ability to capture arbitrary
1640headers.
1641
1642In order to improve administrators reactivity, it offers a great transparency
1643about encountered problems, both internal and external, and it is possible to
1644send logs to different sources at the same time with different level filters :
1645
1646 - global process-level logs (system errors, start/stop, etc..)
1647 - per-listener system and internal errors (lack of resource, bugs, ...)
1648 - per-listener external troubles (servers up/down, max connections)
1649 - per-listener activity (client connections), either at the establishment or
1650 at the termination.
1651
1652The ability to distribute different levels of logs to different log servers
1653allow several production teams to interact and to fix their problems as soon
1654as possible. For example, the system team might monitor system-wide errors,
1655while the application team might be monitoring the up/down for their servers in
1656real time, and the security team might analyze the activity logs with one hour
1657delay.
1658
willy tarreauc1cae632005-12-17 14:12:23 +010016594.2.1) Log levels
1660-----------------
willy tarreau197e8ec2005-12-17 14:10:59 +01001661TCP and HTTP connections can be logged with informations such as date, time,
1662source IP address, destination address, connection duration, response times,
1663HTTP request, the HTTP return code, number of bytes transmitted, the conditions
1664in which the session ended, and even exchanged cookies values, to track a
1665particular user's problems for example. All messages are sent to up to two
1666syslog servers. Consult section 1.1 for more info about log facilities. The
1667syntax follows :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001668
willy tarreau197e8ec2005-12-17 14:10:59 +01001669 log <address_1> <facility_1> [max_level_1]
1670 log <address_2> <facility_2> [max_level_2]
1671or
willy tarreaueedaa9f2005-12-17 14:08:03 +01001672 log global
1673
willy tarreau197e8ec2005-12-17 14:10:59 +01001674Note :
1675------
1676The particular syntax 'log global' means that the same log configuration as the
1677'global' section will be used.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001678
willy tarreau197e8ec2005-12-17 14:10:59 +01001679Example :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001680---------
1681 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001682 mode http
1683 log 192.168.2.200 local3
1684 log 192.168.2.201 local4
willy tarreaueedaa9f2005-12-17 14:08:03 +01001685
willy tarreauc1cae632005-12-17 14:12:23 +010016864.2.2) Log format
1687-----------------
1688By default, connections are logged at the TCP level, as soon as the session
1689establishes between the client and the proxy. By enabling the 'tcplog' option,
1690the proxy will wait until the session ends to generate an enhanced log
1691containing more information such as session duration and its state during the
willy tarreau532bb552006-05-13 18:40:37 +02001692disconnection. The number of remaining session after disconnection is also
1693indicated (for the server, the listener, and the process).
willy tarreauc1cae632005-12-17 14:12:23 +01001694
willy tarreauc5f73ed2005-12-18 01:26:38 +01001695Example of TCP logging :
1696------------------------
willy tarreau982249e2005-12-18 00:57:06 +01001697 listen relais-tcp 0.0.0.0:8000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001698 mode tcp
1699 option tcplog
1700 log 192.168.2.200 local3
willy tarreau982249e2005-12-18 00:57:06 +01001701
willy tarreau532bb552006-05-13 18:40:37 +02001702>>> 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 +01001703
willy tarreau532bb552006-05-13 18:40:37 +02001704 Field Format Example
willy tarreauc5f73ed2005-12-18 01:26:38 +01001705
willy tarreau532bb552006-05-13 18:40:37 +02001706 1 process_name '[' pid ']:' haproxy[18989]:
1707 2 client_ip ':' client_port 127.0.0.1:34550
1708 3 '[' date ']' [15/Oct/2003:15:24:28]
1709 4 listener_name relais-tcp
1710 5 server_name Srv1
1711 6 queue_time '/' connect_time '/' total_time 0/0/5007
1712 7 bytes_read 0
1713 8 termination_state --
1714 9 srv_conn '/' listener_conn '/' process_conn 1/1/1
1715 10 position in srv_queue / listener_queue 0/0
1716
willy tarreau982249e2005-12-18 00:57:06 +01001717
willy tarreauc1cae632005-12-17 14:12:23 +01001718Another option, 'httplog', provides more detailed information about HTTP
1719contents, such as the request and some cookies. In the event where an external
1720component would establish frequent connections to check the service, logs may be
1721full of useless lines. So it is possible not to log any session which didn't
1722transfer any data, by the setting of the 'dontlognull' option. This only has
1723effect on sessions which are established then closed.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001724
willy tarreauc5f73ed2005-12-18 01:26:38 +01001725Example of HTTP logging :
1726-------------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +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
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01001733>>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57] relais-http Srv1 9/0/7/147/723 200 243 - - ---- 34/34/15/8/3 0/0 "HEAD / HTTP/1.0"
willy tarreaueedaa9f2005-12-17 14:08:03 +01001734
willy tarreauc5f73ed2005-12-18 01:26:38 +01001735More complete example
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01001736 haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31] relais-http Srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/150/137/+4 0/0 {w.ods.org|Mozilla} {} "HEAD / HTTP/1.0"
willy tarreauc5f73ed2005-12-18 01:26:38 +01001737
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01001738 Field Format Example
willy tarreauc5f73ed2005-12-18 01:26:38 +01001739
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01001740 1 process_name '[' pid ']:' haproxy[18989]:
1741 2 client_ip ':' client_port 10.0.0.1:34552
1742 3 '[' date ']' [15/Oct/2003:15:26:31]
1743 4 listener_name relais-http
1744 5 server_name Srv1
1745 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt 3183/-1/-1/-1/11215
1746 7 HTTP_return_code 503
1747 8 bytes_read 0
1748 9 captured_request_cookie -
1749 10 captured_response_cookie -
1750 11 termination_state SC--
1751 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries 205/202/150/137/+4
1752 13 position in srv_queue / listener_queue 0/0
1753 14 '{' captured_request_headers '}' {w.ods.org|Mozilla}
1754 15 '{' captured_response_headers '}' {}
1755 16 '"' HTTP_request '"' "HEAD / HTTP/1.0"
willy tarreauc5f73ed2005-12-18 01:26:38 +01001756
1757Note for log parsers: the URI is ALWAYS the end of the line starting with the
1758 first double quote '"'.
willy tarreau982249e2005-12-18 00:57:06 +01001759
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01001760The retries count may have additional '+' sign means that the connection had been
1761redispatched from one server to another shortly before retries limit (retries 4
1762in above example) was depleted.
1763
willy tarreau982249e2005-12-18 00:57:06 +01001764The problem when logging at end of connection is that you have no clue about
1765what is happening during very long sessions. To workaround this problem, a
1766new option 'logasap' has been introduced in 1.1.28/1.2.1. When specified, the
1767proxy will log as soon as possible, just before data transfer begins. This means
1768that in case of TCP, it will still log the connection status to the server, and
1769in case of HTTP, it will log just after processing the server headers. In this
1770case, the number of bytes reported is the number of header bytes sent to the
1771client.
1772
1773In order to avoid confusion with normal logs, the total time field and the
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01001774number of bytes are prefixed with a '+' sign which means that real numbers are
willy tarreau982249e2005-12-18 00:57:06 +01001775certainly bigger.
1776
1777Example :
1778---------
1779
1780 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001781 mode http
1782 option httplog
1783 option dontlognull
1784 option logasap
1785 log 192.168.2.200 local3
willy tarreau982249e2005-12-18 00:57:06 +01001786
Krzysztof Piotr Oledzki25b501a2008-01-06 16:36:16 +01001787>>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 "GET /image.iso HTTP/1.0"
willy tarreau982249e2005-12-18 00:57:06 +01001788
willy tarreauc1cae632005-12-17 14:12:23 +010017894.2.3) Timing events
1790--------------------
1791Timers provide a great help in trouble shooting network problems. All values
1792are reported in milliseconds (ms). In HTTP mode, four control points are
willy tarreau532bb552006-05-13 18:40:37 +02001793reported under the form 'Tq/Tw/Tc/Tr/Tt' :
willy tarreauc1cae632005-12-17 14:12:23 +01001794
1795 - Tq: total time to get the client request.
1796 It's the time elapsed between the moment the client connection was accepted
1797 and the moment the proxy received the last HTTP header. The value '-1'
1798 indicates that the end of headers (empty line) has never been seen.
1799
willy tarreau532bb552006-05-13 18:40:37 +02001800 - Tw: total time spent in the queues waiting for a connection slot. It
1801 accounts for listener's queue as well as the server's queue, and depends
1802 on the queue size, and the time needed for the server to complete previous
1803 sessions. The value '-1' means that the request was killed before reaching
1804 the queue.
1805
willy tarreauc1cae632005-12-17 14:12:23 +01001806 - Tc: total time to establish the TCP connection to the server.
1807 It's the time elapsed between the moment the proxy sent the connection
1808 request, and the moment it was acknowledged, or between the TCP SYN packet
1809 and the matching SYN/ACK in return. The value '-1' means that the
1810 connection never established.
1811
1812 - Tr: server response time. It's the time elapsed between the moment the
1813 TCP connection was established to the server and the moment it send its
1814 complete response header. It purely shows its request processing time,
1815 without the network overhead due to the data transmission. The value '-1'
1816 means that the last the response header (empty line) was never seen.
1817
1818 - Tt: total session duration time, between the moment the proxy accepted it
willy tarreau982249e2005-12-18 00:57:06 +01001819 and the moment both ends were closed. The exception is when the 'logasap'
willy tarreau532bb552006-05-13 18:40:37 +02001820 option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is
willy tarreau982249e2005-12-18 00:57:06 +01001821 prefixed with a '+' sign. From this field, we can deduce Td, the data
1822 transmission time, by substracting other timers when valid :
willy tarreauc1cae632005-12-17 14:12:23 +01001823
willy tarreau532bb552006-05-13 18:40:37 +02001824 Td = Tt - (Tq + Tw + Tc + Tr)
willy tarreauc1cae632005-12-17 14:12:23 +01001825
1826 Timers with '-1' values have to be excluded from this equation.
1827
willy tarreau532bb552006-05-13 18:40:37 +02001828In TCP mode ('option tcplog'), only Tw, Tc and Tt are reported.
willy tarreauc1cae632005-12-17 14:12:23 +01001829
1830These timers provide precious indications on trouble causes. Since the TCP
1831protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
1832that timers close to multiples of 3s are nearly always related to packets lost
1833due to network problems (wires or negociation). Moreover, if <Tt> is close to
1834a timeout value specified in the configuration, it often means that a session
1835has been aborted on time-out.
1836
1837Most common cases :
1838
1839 - If Tq is close to 3000, a packet has probably been lost between the client
1840 and the proxy.
1841 - If Tc is close to 3000, a packet has probably been lost between the server
1842 and the proxy during the server connection phase. This one should always be
1843 very low (less than a few tens).
1844 - If Tr is nearly always lower than 3000 except some rare values which seem to
1845 be the average majored by 3000, there are probably some packets lost between
1846 the proxy and the server.
1847 - If Tt is often slightly higher than a time-out, it's often because the
1848 client and the server use HTTP keep-alive and the session is maintained
1849 after the response ends. Se further for how to disable HTTP keep-alive.
1850
1851Other cases ('xx' means any value to be ignored) :
willy tarreau532bb552006-05-13 18:40:37 +02001852 -1/xx/xx/xx/Tt: the client was not able to send its complete request in time,
1853 or that it aborted it too early.
1854 Tq/-1/xx/xx/Tt: it was not possible to process the request, maybe because
1855 servers were out of order.
1856 Tq/Tw/-1/xx/Tt: the connection could not establish on the server. Either it
1857 refused it or it timed out after Tt-(Tq+Tw) ms.
1858 Tq/Tw/Tc/-1/Tt: the server has accepted the connection but did not return a
1859 complete response in time, or it closed its connexion
1860 unexpectedly, after Tt-(Tq+Tw+Tc) ms.
willy tarreauc1cae632005-12-17 14:12:23 +01001861
18624.2.4) Session state at disconnection
1863-------------------------------------
willy tarreauc5f73ed2005-12-18 01:26:38 +01001864TCP and HTTP logs provide a session completion indicator in the
1865<termination_state> field, just before the number of active
1866connections. It is 2-characters long in TCP, and 4-characters long in
1867HTTP, each of which has a special meaning :
1868
willy tarreau197e8ec2005-12-17 14:10:59 +01001869 - On the first character, a code reporting the first event which caused the
1870 session to terminate :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001871
willy tarreauc5f73ed2005-12-18 01:26:38 +01001872 C : the TCP session was unexpectedly aborted by the client.
1873
1874 S : the TCP session was unexpectedly aborted by the server, or the
1875 server explicitly refused it.
1876
1877 P : the session was prematurely aborted by the proxy, because of a
1878 connection limit enforcement, because a DENY filter was matched,
1879 or because of a security check which detected and blocked a
1880 dangerous error in server response which might have caused
1881 information leak (eg: cacheable cookie).
1882
1883 R : a resource on the proxy has been exhausted (memory, sockets, source
1884 ports, ...). Usually, this appears during the connection phase, and
1885 system logs should contain a copy of the precise error.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001886
willy tarreauc5f73ed2005-12-18 01:26:38 +01001887 I : an internal error was identified by the proxy during a self-check.
1888 This should NEVER happen, and you are encouraged to report any log
1889 containing this, because this is a bug.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001890
willy tarreauc5f73ed2005-12-18 01:26:38 +01001891 c : the client-side time-out expired first.
1892
1893 s : the server-side time-out expired first.
1894
1895 - : normal session completion.
1896
1897 - on the second character, the TCP/HTTP session state when it was closed :
1898
1899 R : waiting for complete REQUEST from the client (HTTP only). Nothing
1900 was sent to any server.
1901
willy tarreau532bb552006-05-13 18:40:37 +02001902 Q : waiting in the QUEUE for a connection slot. This can only happen on
1903 servers which have a 'maxconn' parameter set. No connection attempt
1904 was made to any server.
1905
willy tarreauc5f73ed2005-12-18 01:26:38 +01001906 C : waiting for CONNECTION to establish on the server. The server might
1907 at most have noticed a connection attempt.
1908
1909 H : waiting for, receiving and processing server HEADERS (HTTP only).
1910
1911 D : the session was in the DATA phase.
1912
1913 L : the proxy was still transmitting LAST data to the client while the
1914 server had already finished.
1915
Willy Tarreau2272dc12006-09-03 10:19:38 +02001916 T : the request was tarpitted. It has been held open on with the client
Willy Tarreau08fa2e32006-09-03 10:47:37 +02001917 during the whole contimeout duration or untill the client closed.
Willy Tarreau2272dc12006-09-03 10:19:38 +02001918
willy tarreauc5f73ed2005-12-18 01:26:38 +01001919 - : normal session completion after end of data transfer.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001920
willy tarreau197e8ec2005-12-17 14:10:59 +01001921 - the third character tells whether the persistence cookie was provided by
willy tarreauc1cae632005-12-17 14:12:23 +01001922 the client (only in HTTP mode) :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001923
willy tarreauc5f73ed2005-12-18 01:26:38 +01001924 N : the client provided NO cookie. This is usually the case on new
1925 connections.
1926
1927 I : the client provided an INVALID cookie matching no known
1928 server. This might be caused by a recent configuration change,
1929 mixed cookies between HTTP/HTTPS sites, or an attack.
1930
1931 D : the client provided a cookie designating a server which was DOWN,
1932 so either the 'persist' option was used and the client was sent to
1933 this server, or it was not set and the client was redispatched to
1934 another server.
1935
1936 V : the client provided a valid cookie, and was sent to the associated
1937 server.
1938
1939 - : does not apply (no cookie set in configuration).
willy tarreaueedaa9f2005-12-17 14:08:03 +01001940
willy tarreau197e8ec2005-12-17 14:10:59 +01001941 - the last character reports what operations were performed on the persistence
willy tarreauc1cae632005-12-17 14:12:23 +01001942 cookie returned by the server (only in HTTP mode) :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001943
willy tarreauc5f73ed2005-12-18 01:26:38 +01001944 N : NO cookie was provided by the server, and none was inserted either.
1945
1946 I : no cookie was provided by the server, and the proxy INSERTED one.
1947
willy tarreau197e8ec2005-12-17 14:10:59 +01001948 P : a cookie was PROVIDED by the server and transmitted as-is.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001949
willy tarreauc5f73ed2005-12-18 01:26:38 +01001950 R : the cookie provided by the server was REWRITTEN by the proxy.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001951
willy tarreauc5f73ed2005-12-18 01:26:38 +01001952 D : the cookie provided by the server was DELETED by the proxy.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001953
willy tarreauc5f73ed2005-12-18 01:26:38 +01001954 - : does not apply (no cookie set in configuration).
willy tarreaueedaa9f2005-12-17 14:08:03 +01001955
willy tarreauc5f73ed2005-12-18 01:26:38 +01001956The combination of the two first flags give a lot of information about what was
1957happening when the session terminated. It can be helpful to detect server
1958saturation, network troubles, local system resource starvation, attacks, etc...
willy tarreaueedaa9f2005-12-17 14:08:03 +01001959
willy tarreauc5f73ed2005-12-18 01:26:38 +01001960The most common termination flags combinations are indicated here.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001961
willy tarreauc5f73ed2005-12-18 01:26:38 +01001962 Flags Reason
1963 CR The client aborted before sending a full request. Most probably the
1964 request was done by hand using a telnet client, and aborted early.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001965
willy tarreauc5f73ed2005-12-18 01:26:38 +01001966 cR The client timed out before sending a full request. This is sometimes
1967 caused by too large TCP MSS values on the client side for PPPoE
1968 networks which cannot transport full-sized packets, or by clients
1969 sending requests by hand and not typing fast enough.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001970
willy tarreauc5f73ed2005-12-18 01:26:38 +01001971 SC The server explicitly refused the connection (the proxy received a
1972 TCP RST or an ICMP in return). Under some circumstances, it can
1973 also be the network stack telling the proxy that the server is
1974 unreachable (eg: no route, or no ARP response on local network).
willy tarreau982249e2005-12-18 00:57:06 +01001975
willy tarreauc5f73ed2005-12-18 01:26:38 +01001976 sC The connection to the server did not complete during contimeout.
willy tarreau982249e2005-12-18 00:57:06 +01001977
willy tarreauc5f73ed2005-12-18 01:26:38 +01001978 PC The proxy refused to establish a connection to the server because the
1979 maxconn limit has been reached. The listener's maxconn parameter may
1980 be increased in the proxy configuration, as well as the global
1981 maxconn parameter.
willy tarreauc1cae632005-12-17 14:12:23 +01001982
willy tarreauc5f73ed2005-12-18 01:26:38 +01001983 RC A local resource has been exhausted (memory, sockets, source ports)
1984 preventing the connection to the server from establishing. The error
1985 logs will tell precisely what was missing. Anyway, this can only be
1986 solved by system tuning.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001987
willy tarreauc5f73ed2005-12-18 01:26:38 +01001988 cH The client timed out during a POST request. This is sometimes caused
1989 by too large TCP MSS values for PPPoE networks which cannot transport
1990 full-sized packets.
willy tarreauc1cae632005-12-17 14:12:23 +01001991
willy tarreau078c79a2006-05-13 12:23:58 +02001992 CH The client aborted while waiting for the server to start responding.
1993 It might be the server taking too long to respond or the client
1994 clicking the 'Stop' button too fast.
1995
1996 CQ The client aborted while its session was queued, waiting for a server
1997 with enough empty slots to accept it. It might be that either all the
1998 servers were saturated or the assigned server taking too long to
1999 respond.
2000
Willy Tarreau08fa2e32006-09-03 10:47:37 +02002001 CT The client aborted while its session was tarpitted.
2002
willy tarreau078c79a2006-05-13 12:23:58 +02002003 sQ The session spent too much time in queue and has been expired.
2004
willy tarreauc5f73ed2005-12-18 01:26:38 +01002005 SH The server aborted before sending its full headers, or it crashed.
willy tarreaueedaa9f2005-12-17 14:08:03 +01002006
willy tarreauc5f73ed2005-12-18 01:26:38 +01002007 sH The server failed to reply during the srvtimeout delay, which
2008 indicates too long transactions, probably caused by back-end
2009 saturation. The only solutions are to fix the problem on the
2010 application or to increase the 'srvtimeout' parameter to support
2011 longer delays (at the risk of the client giving up anyway).
2012
2013 PR The proxy blocked the client's request, either because of an invalid
2014 HTTP syntax, in which case it returned an HTTP 400 error to the
2015 client, or because a deny filter matched, in which case it returned
2016 an HTTP 403 error.
2017
2018 PH The proxy blocked the server's response, because it was invalid,
2019 incomplete, dangerous (cache control), or matched a security filter.
2020 In any case, an HTTP 502 error is sent to the client.
2021
Willy Tarreau2272dc12006-09-03 10:19:38 +02002022 PT The proxy blocked the client's request and has tarpitted its
2023 connection before returning it a 500 server error. Nothing was sent
2024 to the server.
2025
willy tarreauc5f73ed2005-12-18 01:26:38 +01002026 cD The client did not read any data for as long as the clitimeout delay.
2027 This is often caused by network failures on the client side.
2028
2029 CD The client unexpectedly aborted during data transfer. This is either
2030 caused by a browser crash, or by a keep-alive session between the
2031 server and the client terminated first by the client.
2032
2033 sD The server did nothing during the srvtimeout delay. This is often
2034 caused by too short timeouts on L4 equipements before the server
2035 (firewalls, load-balancers, ...).
2036
20374.2.5) Non-printable characters
willy tarreau4302f492005-12-18 01:00:37 +01002038-------------------------------
2039As of version 1.1.29, non-printable characters are not sent as-is into log
2040files, but are converted to their two-digits hexadecimal representation,
2041prefixed by the character '#'. The only characters that can now be logged
2042without being escaped are between 32 and 126 (inclusive). Obviously, the
2043escape character '#' is also encoded to avoid any ambiguity. It is the same for
2044the character '"', as well as '{', '|' and '}' when logging headers.
2045
willy tarreauc5f73ed2005-12-18 01:26:38 +010020464.2.6) Capturing HTTP headers and cookies
2047-----------------------------------------
2048Version 1.1.23 brought cookie capture, and 1.1.29 the header capture. All this
2049is performed using the 'capture' keyword.
2050
2051Cookie capture makes it easy to track a complete user session. The syntax is :
2052
2053 capture cookie <cookie_prefix> len <capture_length>
2054
2055This will enable cookie capture from both requests and responses. This way,
2056it's easy to detect when a user switches to a new session for example, because
2057the server will reassign it a new cookie.
2058
2059The FIRST cookie whose name starts with <cookie_prefix> will be captured, and
2060logged as 'NAME=value', without exceeding <capture_length> characters (64 max).
2061When the cookie name is fixed and known, it's preferable to suffix '=' to it to
2062ensure that no other cookie will be logged.
2063
2064Examples :
2065----------
2066 # capture the first cookie whose name starts with "ASPSESSION"
2067 capture cookie ASPSESSION len 32
2068
2069 # capture the first cookie whose name is exactly "vgnvisitor"
2070 capture cookie vgnvisitor= len 32
2071
2072In the logs, the field preceeding the completion indicator contains the cookie
2073value as sent by the server, preceeded by the cookie value as sent by the
2074client. Each of these field is replaced with '-' when no cookie was seen or
2075when the option is disabled.
2076
2077Header captures have a different goal. They are useful to track unique request
2078identifiers set by a previous proxy, virtual host names, user-agents, POST
2079content-length, referrers, etc. In the response, one can search for information
2080about the response length, how the server asked the cache to behave, or an
2081object location during a redirection. As for cookie captures, it is both
2082possible to include request headers and response headers at the same time. The
2083syntax is :
willy tarreau4302f492005-12-18 01:00:37 +01002084
2085 capture request header <name> len <max length>
2086 capture response header <name> len <max length>
2087
2088Note: Header names are not case-sensitive.
2089
2090Examples:
2091---------
2092 # keep the name of the virtual server
2093 capture request header Host len 20
2094 # keep the amount of data uploaded during a POST
2095 capture request header Content-Length len 10
2096
2097 # note the expected cache behaviour on the response
2098 capture response header Cache-Control len 8
2099 # note the URL location during a redirection
2100 capture response header Location len 20
2101
2102Non-existant headers are logged as empty strings, and if one header appears more
2103than once, only its last occurence will be kept. Request headers are grouped
2104within braces '{' and '}' in the same order as they were declared, and delimited
2105with a vertical bar '|' without any space. Response headers follow the same
2106representation, but are displayed after a space following the request headers
2107block. These blocks are displayed just before the HTTP request in the logs.
willy tarreauc5f73ed2005-12-18 01:26:38 +01002108
willy tarreau4302f492005-12-18 01:00:37 +01002109Example :
2110
willy tarreauc5f73ed2005-12-18 01:26:38 +01002111 Config:
2112
2113 capture request header Host len 20
2114 capture request header Content-Length len 10
2115 capture request header Referer len 20
2116 capture response header Server len 20
2117 capture response header Content-Length len 10
2118 capture response header Cache-Control len 8
2119 capture response header Via len 20
2120 capture response header Location len 20
2121
2122 Log :
2123
willy tarreau532bb552006-05-13 18:40:37 +02002124 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/"
2125 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"
2126 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 +01002127
2128
21294.2.7) Examples of logs
2130-----------------------
willy tarreau532bb552006-05-13 18:40:37 +02002131- 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 tarreauc5f73ed2005-12-18 01:26:38 +01002132 => long request (6.5s) entered by hand through 'telnet'. The server replied
2133 in 147 ms, and the session ended normally ('----')
2134
willy tarreau532bb552006-05-13 18:40:37 +02002135- 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"
2136 => Idem, but the request was queued in the global queue behind 9 other
2137 requests, and waited there for 1230 ms.
2138
2139- 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 tarreauc5f73ed2005-12-18 01:26:38 +01002140 => request for a long data transfer. The 'logasap' option was specified, so
2141 the log was produced just before transfering data. The server replied in
2142 14 ms, 243 bytes of headers were sent to the client, and total time from
2143 accept to first data byte is 30 ms.
2144
willy tarreau532bb552006-05-13 18:40:37 +02002145- 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 tarreauc5f73ed2005-12-18 01:26:38 +01002146 => the proxy blocked a server response either because of an 'rspdeny' or
2147 'rspideny' filter, or because it blocked sensible information which risked
2148 being cached. In this case, the response is replaced with a '502 bad
2149 gateway'.
2150
willy tarreau532bb552006-05-13 18:40:37 +02002151- 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 tarreauc5f73ed2005-12-18 01:26:38 +01002152 => the client never completed its request and aborted itself ('C---') after
2153 8.5s, while the proxy was waiting for the request headers ('-R--').
2154 Nothing was sent to the server.
2155
willy tarreau532bb552006-05-13 18:40:37 +02002156- haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06] relais-http <NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2 0/0 ""
willy tarreauc5f73ed2005-12-18 01:26:38 +01002157 => The client never completed its request, which was aborted by the time-out
2158 ('c---') after 50s, while the proxy was waiting for the request headers ('-R--').
2159 Nothing was sent to the server, but the proxy could send a 408 return code
2160 to the client.
willy tarreau4302f492005-12-18 01:00:37 +01002161
willy tarreau532bb552006-05-13 18:40:37 +02002162- haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28] relais-tcp Srv1 0/0/5007 0 cD 0/0/0 0/0
willy tarreauc5f73ed2005-12-18 01:26:38 +01002163 => This is a 'tcplog' entry. Client-side time-out ('c----') occured after 5s.
willy tarreau4302f492005-12-18 01:00:37 +01002164
willy tarreau532bb552006-05-13 18:40:37 +02002165- 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 tarreauc5f73ed2005-12-18 01:26:38 +01002166 => The request took 3s to complete (probably a network problem), and the
2167 connection to the server failed ('SC--') after 4 attemps of 2 seconds
2168 (config says 'retries 3'), then a 503 error code was sent to the client.
willy tarreau532bb552006-05-13 18:40:37 +02002169 There were 115 connections on this server, 202 connections on this proxy,
2170 and 205 on the global process. It is possible that the server refused the
2171 connection because of too many already established.
willy tarreau4302f492005-12-18 01:00:37 +01002172
willy tarreau4302f492005-12-18 01:00:37 +01002173
willy tarreau197e8ec2005-12-17 14:10:59 +010021744.3) HTTP header manipulation
2175-----------------------------
2176In HTTP mode, it is possible to rewrite, add or delete some of the request and
2177response headers based on regular expressions. It is also possible to block a
2178request or a response if a particular header matches a regular expression,
2179which is enough to stops most elementary protocol attacks, and to protect
2180against information leak from the internal network. But there is a limitation
2181to this : since haproxy's HTTP engine knows nothing about keep-alive, only
2182headers passed during the first request of a TCP session will be seen. All
2183subsequent headers will be considered data only and not analyzed. Furthermore,
2184haproxy doesn't touch data contents, it stops at the end of headers.
willy tarreaueedaa9f2005-12-17 14:08:03 +01002185
willy tarreau197e8ec2005-12-17 14:10:59 +01002186The syntax is :
2187 reqadd <string> to add a header to the request
2188 reqrep <search> <replace> to modify the request
2189 reqirep <search> <replace> same, but ignoring the case
2190 reqdel <search> to delete a header in the request
2191 reqidel <search> same, but ignoring the case
2192 reqallow <search> definitely allow a request if a header matches <search>
2193 reqiallow <search> same, but ignoring the case
2194 reqdeny <search> denies a request if a header matches <search>
2195 reqideny <search> same, but ignoring the case
2196 reqpass <search> ignore a header matching <search>
2197 reqipass <search> same, but ignoring the case
Willy Tarreau2272dc12006-09-03 10:19:38 +02002198 reqtarpit <search> tarpit a request matching <search>
2199 reqitarpit <search> same, but ignoring the case
willy tarreaueedaa9f2005-12-17 14:08:03 +01002200
willy tarreau197e8ec2005-12-17 14:10:59 +01002201 rspadd <string> to add a header to the response
2202 rsprep <search> <replace> to modify the response
2203 rspirep <search> <replace> same, but ignoring the case
2204 rspdel <search> to delete the response
2205 rspidel <search> same, but ignoring the case
willy tarreau982249e2005-12-18 00:57:06 +01002206 rspdeny <search> replaces a response with a HTTP 502 if a header matches <search>
2207 rspideny <search> same, but ignoring the case
willy tarreaueedaa9f2005-12-17 14:08:03 +01002208
2209
willy tarreau197e8ec2005-12-17 14:10:59 +01002210<search> is a POSIX regular expression (regex) which supports grouping through
2211parenthesis (without the backslash). Spaces and other delimiters must be
2212prefixed with a backslash ('\') to avoid confusion with a field delimiter.
2213Other characters may be prefixed with a backslash to change their meaning :
willy tarreaueedaa9f2005-12-17 14:08:03 +01002214
willy tarreau197e8ec2005-12-17 14:10:59 +01002215 \t for a tab
2216 \r for a carriage return (CR)
2217 \n for a new line (LF)
2218 \ to mark a space and differentiate it from a delimiter
2219 \# to mark a sharp and differentiate it from a comment
2220 \\ to use a backslash in a regex
2221 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
2222 \xXX to write the ASCII hex code XX as in the C language
willy tarreaueedaa9f2005-12-17 14:08:03 +01002223
2224
Willy Tarreau2272dc12006-09-03 10:19:38 +02002225<replace> contains the string to be used to replace the largest portion of text
willy tarreau197e8ec2005-12-17 14:10:59 +01002226matching the regex. It can make use of the special characters above, and can
2227reference a substring delimited by parenthesis in the regex, by the group
Willy Tarreau2272dc12006-09-03 10:19:38 +02002228numerical order from 0 to 9 (0 being the entire line). In this case, you would
2229write a backslash ('\') immediately followed by one digit indicating the group
2230position.
willy tarreaueedaa9f2005-12-17 14:08:03 +01002231
willy tarreau197e8ec2005-12-17 14:10:59 +01002232<string> represents the string which will systematically be added after the last
2233header line. It can also use special characters above.
willy tarreaueedaa9f2005-12-17 14:08:03 +01002234
willy tarreau197e8ec2005-12-17 14:10:59 +01002235Notes :
2236-------
2237 - the first line is considered as a header, which makes it possible to rewrite
2238 or filter HTTP requests URIs or response codes.
2239 - 'reqrep' is the equivalent of 'cliexp' in version 1.0, and 'rsprep' is the
2240 equivalent of 'srvexp' in 1.0. Those names are still supported but
2241 deprecated.
2242 - for performances reasons, the number of characters added to a request or to
2243 a response is limited to 4096 since version 1.1.5 (it was 256 before). This
2244 value is easy to modify in the code if needed (#define). If it is too short
2245 on occasional uses, it is possible to gain some space by removing some
2246 useless headers before adding new ones.
willy tarreau982249e2005-12-18 00:57:06 +01002247 - a denied request will generate an "HTTP 403 forbidden" response, while a
2248 denied response will generate an "HTTP 502 Bad gateway" response.
Willy Tarreau2272dc12006-09-03 10:19:38 +02002249 - a tarpitted request will be held open on the client side for a duration
Willy Tarreau08fa2e32006-09-03 10:47:37 +02002250 defined in the contimeout parameter, or untill the client aborts. Nothing
2251 will be sent to any server. When the timeout is reached, the proxy will
2252 reply with a 500 server error response so that the attacker does not
2253 suspect it has been tarpitted. The logs may report the 500, but the
2254 termination flags will indicate 'PT' in this case.
Willy Tarreau2272dc12006-09-03 10:19:38 +02002255
willy tarreaueedaa9f2005-12-17 14:08:03 +01002256
willy tarreau197e8ec2005-12-17 14:10:59 +01002257Examples :
2258----------
willy tarreauc5f73ed2005-12-18 01:26:38 +01002259 ###### a few examples ######
willy tarreau197e8ec2005-12-17 14:10:59 +01002260
willy tarreauc5f73ed2005-12-18 01:26:38 +01002261 # rewrite 'online.fr' instead of 'free.fr' for GET and POST requests
2262 reqrep ^(GET\ .*)(.free.fr)(.*) \1.online.fr\3
2263 reqrep ^(POST\ .*)(.free.fr)(.*) \1.online.fr\3
willy tarreau197e8ec2005-12-17 14:10:59 +01002264
willy tarreauc5f73ed2005-12-18 01:26:38 +01002265 # force proxy connections to close
2266 reqirep ^Proxy-Connection:.* Proxy-Connection:\ close
2267 # rewrite locations
2268 rspirep ^(Location:\ )([^:]*://[^/]*)(.*) \1\3
willy tarreaueedaa9f2005-12-17 14:08:03 +01002269
willy tarreauc5f73ed2005-12-18 01:26:38 +01002270 ###### A full configuration being used on production ######
willy tarreaueedaa9f2005-12-17 14:08:03 +01002271
willy tarreau197e8ec2005-12-17 14:10:59 +01002272 # Every header should end with a colon followed by one space.
willy tarreauc5f73ed2005-12-18 01:26:38 +01002273 reqideny ^[^:\ ]*[\ ]*$
willy tarreaueedaa9f2005-12-17 14:08:03 +01002274
willy tarreau197e8ec2005-12-17 14:10:59 +01002275 # block Apache chunk exploit
willy tarreauc5f73ed2005-12-18 01:26:38 +01002276 reqideny ^Transfer-Encoding:[\ ]*chunked
2277 reqideny ^Host:\ apache-
willy tarreaueedaa9f2005-12-17 14:08:03 +01002278
willy tarreau197e8ec2005-12-17 14:10:59 +01002279 # block annoying worms that fill the logs...
willy tarreauc5f73ed2005-12-18 01:26:38 +01002280 reqideny ^[^:\ ]*\ .*(\.|%2e)(\.|%2e)(%2f|%5c|/|\\\\)
2281 reqideny ^[^:\ ]*\ ([^\ ]*\ [^\ ]*\ |.*%00)
2282 reqideny ^[^:\ ]*\ .*<script
2283 reqideny ^[^:\ ]*\ .*/(root\.exe\?|cmd\.exe\?|default\.ida\?)
willy tarreau197e8ec2005-12-17 14:10:59 +01002284
Willy Tarreau2272dc12006-09-03 10:19:38 +02002285 # tarpit attacks on the login page.
2286 reqtarpit ^[^:\ ]*\ .*\.php?login=[^0-9]
2287
willy tarreau197e8ec2005-12-17 14:10:59 +01002288 # allow other syntactically valid requests, and block any other method
willy tarreauc5f73ed2005-12-18 01:26:38 +01002289 reqipass ^(GET|POST|HEAD|OPTIONS)\ /.*\ HTTP/1\.[01]$
2290 reqipass ^OPTIONS\ \\*\ HTTP/1\.[01]$
2291 reqideny ^[^:\ ]*\
willy tarreau197e8ec2005-12-17 14:10:59 +01002292
2293 # force connection:close, thus disabling HTTP keep-alive
willy tarreauc5f73ed2005-12-18 01:26:38 +01002294 option httpclose
willy tarreau197e8ec2005-12-17 14:10:59 +01002295
willy tarreauc5f73ed2005-12-18 01:26:38 +01002296 # change the server name
2297 rspidel ^Server:\
2298 rspadd Server:\ Formilux/0.1.8
willy tarreau197e8ec2005-12-17 14:10:59 +01002299
2300
willy tarreau982249e2005-12-18 00:57:06 +01002301Also, the 'forwardfor' option creates an HTTP 'X-Forwarded-For' header which
willy tarreauc1cae632005-12-17 14:12:23 +01002302contains the client's IP address. This is useful to let the final web server
Willy Tarreau7ac51f62007-03-25 16:00:04 +02002303know what the client address was (eg for statistics on domains). Starting with
2304version 1.3.8, it is possible to specify the "except" keyword followed by a
2305source IP address or network for which no header will be added. This is very
2306useful when another reverse-proxy which already adds the header runs on the
2307same machine or in a known DMZ, the most common case being the local use of
2308stunnel on the same system.
willy tarreauc1cae632005-12-17 14:12:23 +01002309
willy tarreau982249e2005-12-18 00:57:06 +01002310Last, the 'httpclose' option removes any 'Connection' header both ways, and
2311adds a 'Connection: close' header in each direction. This makes it easier to
Willy TARREAU767ba712006-03-01 22:40:50 +01002312disable HTTP keep-alive than the previous 4-rules block.
willy tarreau982249e2005-12-18 00:57:06 +01002313
willy tarreauc1cae632005-12-17 14:12:23 +01002314Example :
2315---------
2316 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01002317 mode http
2318 log global
2319 option httplog
2320 option dontlognull
Willy Tarreau7ac51f62007-03-25 16:00:04 +02002321 option forwardfor except 127.0.0.1/8
willy tarreauc5f73ed2005-12-18 01:26:38 +01002322 option httpclose
2323
Willy TARREAU767ba712006-03-01 22:40:50 +01002324Note that some HTTP servers do not necessarily close the connections when they
2325receive the 'Connection: close', and if the client does not close either, then
2326the connection will be maintained up to the time-out. This translates into high
2327number of simultaneous sessions and high global session times in the logs. To
2328workaround this, a new option 'forceclose' appeared in version 1.2.9 to enforce
2329the closing of the outgoing server channel as soon as the server begins to
2330reply and only if the request buffer is empty. Note that this should NOT be
2331used if CONNECT requests are expected between the client and the server. The
2332'forceclose' option implies the 'httpclose' option.
2333
2334Example :
2335---------
2336 listen http_proxy 0.0.0.0:80
2337 mode http
2338 log global
2339 option httplog
2340 option dontlognull
2341 option forwardfor
2342 option forceclose
2343
willy tarreau197e8ec2005-12-17 14:10:59 +01002344
23454.4) Load balancing with persistence
2346------------------------------------
willy tarreau197e8ec2005-12-17 14:10:59 +01002347Combining cookie insertion with internal load balancing allows to transparently
2348bring persistence to applications. The principle is quite simple :
2349 - assign a cookie value to each server
2350 - enable the load balancing between servers
2351 - insert a cookie into responses resulting from the balancing algorithm
2352 (indirect accesses), end ensure that no upstream proxy will cache it.
2353 - remove the cookie in the request headers so that the application never sees
2354 it.
2355
2356Example :
willy tarreaueedaa9f2005-12-17 14:08:03 +01002357---------
2358 listen application 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01002359 mode http
2360 cookie SERVERID insert nocache indirect
2361 balance roundrobin
2362 server srv1 192.168.1.1:80 cookie server01 check
2363 server srv2 192.168.1.2:80 cookie server02 check
willy tarreaueedaa9f2005-12-17 14:08:03 +01002364
willy tarreau0174f312005-12-18 01:02:42 +01002365The other solution brought by versions 1.1.30 and 1.2.3 is to reuse a cookie
2366from the server, and prefix the server's name to it. In this case, don't forget
2367to force "httpclose" mode so that you can be assured that every subsequent
2368request will have its cookie fixed.
2369
2370 listen application 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01002371 mode http
2372 cookie JSESSIONID prefix
2373 balance roundrobin
2374 server srv1 192.168.1.1:80 cookie srv1 check
2375 server srv2 192.168.1.2:80 cookie srv2 check
2376 option httpclose
willy tarreau0174f312005-12-18 01:02:42 +01002377
2378
willy tarreau982249e2005-12-18 00:57:06 +010023794.5) Protection against information leak from the servers
2380---------------------------------------------------------
2381In versions 1.1.28/1.2.1, a new option 'checkcache' was created. It carefully
2382checks 'Cache-control', 'Pragma' and 'Set-cookie' headers in server response
2383to check if there's a risk of caching a cookie on a client-side proxy. When this
2384option is enabled, the only responses which can be delivered to the client are :
2385 - all those without 'Set-Cookie' header ;
2386 - all those with a return code other than 200, 203, 206, 300, 301, 410,
2387 provided that the server has not set a 'Cache-control: public' header ;
2388 - all those that come from a POST request, provided that the server has not
2389 set a 'Cache-Control: public' header ;
2390 - those with a 'Pragma: no-cache' header
2391 - those with a 'Cache-control: private' header
2392 - those with a 'Cache-control: no-store' header
2393 - those with a 'Cache-control: max-age=0' header
2394 - those with a 'Cache-control: s-maxage=0' header
2395 - those with a 'Cache-control: no-cache' header
2396 - those with a 'Cache-control: no-cache="set-cookie"' header
2397 - those with a 'Cache-control: no-cache="set-cookie,' header
2398 (allowing other fields after set-cookie)
willy tarreaueedaa9f2005-12-17 14:08:03 +01002399
willy tarreau982249e2005-12-18 00:57:06 +01002400If a response doesn't respect these requirements, then it will be blocked just
2401as if it was from an 'rspdeny' filter, with an "HTTP 502 bad gateway". The
2402session state shows "PH--" meaning that the proxy blocked the response during
2403headers processing. Additionnaly, an alert will be sent in the logs so that
2404admins are told that there's something to be done.
2405
willy tarreauc5f73ed2005-12-18 01:26:38 +01002406
willy tarreau982249e2005-12-18 00:57:06 +010024074.6) Customizing errors
2408-----------------------
willy tarreau197e8ec2005-12-17 14:10:59 +01002409Some situations can make haproxy return an HTTP error code to the client :
2410 - invalid or too long request => HTTP 400
2411 - request not completely sent in time => HTTP 408
2412 - forbidden request (matches a deny filter) => HTTP 403
2413 - internal error in haproxy => HTTP 500
2414 - the server returned an invalid or incomplete response => HTTP 502
2415 - no server was available to handle the request => HTTP 503
2416 - the server failed to reply in time => HTTP 504
willy tarreaueedaa9f2005-12-17 14:08:03 +01002417
willy tarreau197e8ec2005-12-17 14:10:59 +01002418A succint error message taken from the RFC accompanies these return codes.
2419But depending on the clients knowledge, it may be better to return custom, user
Willy Tarreau3f49b302007-06-11 00:29:26 +02002420friendly, error pages. This is made possible in two ways, one involving a
2421redirection to a known server, and another one consisting in returning a local
2422file.
2423
24244.6.1) Relocation
2425-----------------
2426An error relocation is achieved using the 'errorloc' command :
willy tarreaueedaa9f2005-12-17 14:08:03 +01002427
willy tarreau197e8ec2005-12-17 14:10:59 +01002428 errorloc <HTTP_code> <location>
willy tarreaueedaa9f2005-12-17 14:08:03 +01002429
willy tarreau197e8ec2005-12-17 14:10:59 +01002430Instead of generating an HTTP error <HTTP_code> among those above, the proxy
2431will return a temporary redirection code (HTTP 302) towards the address
2432specified in <location>. This address may be either relative to the site or
2433absolute. Since this request will be handled by the client's browser, it's
2434mandatory that the returned address be reachable from the outside.
willy tarreaueedaa9f2005-12-17 14:08:03 +01002435
willy tarreau197e8ec2005-12-17 14:10:59 +01002436Example :
willy tarreaueedaa9f2005-12-17 14:08:03 +01002437---------
2438 listen application 0.0.0.0:80
2439 errorloc 400 /badrequest.html
2440 errorloc 403 /forbidden.html
2441 errorloc 408 /toolong.html
willy tarreauc5f73ed2005-12-18 01:26:38 +01002442 errorloc 500 http://haproxy.domain.net/bugreport.html
willy tarreaueedaa9f2005-12-17 14:08:03 +01002443 errorloc 502 http://192.168.114.58/error50x.html
2444 errorloc 503 http://192.168.114.58/error50x.html
2445 errorloc 504 http://192.168.114.58/error50x.html
2446
willy tarreauc1f47532005-12-18 01:08:26 +01002447Note: RFC2616 says that a client must reuse the same method to fetch the
2448Location returned by a 302, which causes problems with the POST method.
2449The return code 303 was designed explicitly to force the client to fetch the
2450Location URL with the GET method, but there are some browsers pre-dating
2451HTTP/1.1 which don't support it. Anyway, most browsers still behave with 302 as
willy tarreauc5f73ed2005-12-18 01:26:38 +01002452if it was a 303. In order to allow the user to chose, versions 1.1.31 and 1.2.5
2453bring two new keywords to replace 'errorloc' : 'errorloc302' and 'errorloc303'.
willy tarreauc1f47532005-12-18 01:08:26 +01002454
2455They are preffered over errorloc (which still does 302). Consider using
2456errorloc303 everytime you know that your clients support HTTP 303 responses..
2457
Willy Tarreau3f49b302007-06-11 00:29:26 +020024584.6.2) Local files
2459------------------
2460Sometimes, it is desirable to change the returned error without resorting to
2461redirections. The second method consists in loading local files during startup
2462and send them as pure HTTP content upon error. This is what the 'errorfile'
2463keyword does.
2464
2465Warning, there are traps to consider :
2466 - The files are loaded while parsing configuration, before doing a chroot().
2467 Thus, they are relative to the real filesystem. For this reason, it is
2468 recommended to pass an absolute path to those files.
2469
2470 - The contents of those files is not HTML, but real HTTP protocol with
2471 possible HTML body. So the first line and headers are mandatory. Ideally,
2472 every line in the HTTP part should end with CR-LF for maximum compatibility.
2473
2474 - The response is limited to the buffer size (BUSIZE), generally 8 or 16 kB.
2475
2476 - The response should not include references to the local server, in order to
2477 avoid infinite loops on the browser in case of local failure.
2478
2479Example :
2480---------
2481 errorfile 400 /etc/haproxy/errorfiles/400badreq.http
2482 errorfile 403 /etc/haproxy/errorfiles/403forbid.http
2483 errorfile 503 /etc/haproxy/errorfiles/503sorry.http
2484
willy tarreauc1f47532005-12-18 01:08:26 +01002485
willy tarreau982249e2005-12-18 00:57:06 +010024864.7) Modifying default values
willy tarreau197e8ec2005-12-17 14:10:59 +01002487-----------------------------
willy tarreau197e8ec2005-12-17 14:10:59 +01002488Version 1.1.22 introduced the notion of default values, which eliminates the
2489pain of often repeating common parameters between many instances, such as
2490logs, timeouts, modes, etc...
willy tarreaueedaa9f2005-12-17 14:08:03 +01002491
willy tarreau197e8ec2005-12-17 14:10:59 +01002492Default values are set in a 'defaults' section. Each of these section clears
2493all previously set default parameters, so there may be as many default
2494parameters as needed. Only the last one before a 'listen' section will be
2495used for this section. The 'defaults' section uses the same syntax as the
2496'listen' section, for the supported parameters. The 'defaults' keyword ignores
2497everything on its command line, so that fake instance names can be specified
2498there for better clarity.
willy tarreaueedaa9f2005-12-17 14:08:03 +01002499
willy tarreau982249e2005-12-18 00:57:06 +01002500In version 1.1.28/1.2.1, only those parameters can be preset in the 'default'
willy tarreau197e8ec2005-12-17 14:10:59 +01002501section :
2502 - log (the first and second one)
willy tarreaueedaa9f2005-12-17 14:08:03 +01002503 - mode { tcp, http, health }
2504 - balance { roundrobin }
willy tarreau197e8ec2005-12-17 14:10:59 +01002505 - disabled (to disable every further instances)
2506 - enabled (to enable every further instances, this is the default)
willy tarreaueedaa9f2005-12-17 14:08:03 +01002507 - contimeout, clitimeout, srvtimeout, grace, retries, maxconn
willy tarreau982249e2005-12-18 00:57:06 +01002508 - option { redispatch, transparent, keepalive, forwardfor, logasap, httpclose,
2509 checkcache, httplog, tcplog, dontlognull, persist, httpchk }
willy tarreaueedaa9f2005-12-17 14:08:03 +01002510 - redispatch, redisp, transparent, source { addr:port }
2511 - cookie, capture
2512 - errorloc
2513
willy tarreau197e8ec2005-12-17 14:10:59 +01002514As of 1.1.24, it is not possible to put certain parameters in a 'defaults'
2515section, mainly regular expressions and server configurations :
willy tarreaueedaa9f2005-12-17 14:08:03 +01002516 - dispatch, server,
willy tarreau197e8ec2005-12-17 14:10:59 +01002517 - req*, rsp*
willy tarreaueedaa9f2005-12-17 14:08:03 +01002518
willy tarreau197e8ec2005-12-17 14:10:59 +01002519Last, there's no way yet to change a boolean option from its assigned default
2520value. So if an 'option' statement is set in a 'defaults' section, the only
2521way to flush it is to redefine a new 'defaults' section without this 'option'.
willy tarreaueedaa9f2005-12-17 14:08:03 +01002522
willy tarreau197e8ec2005-12-17 14:10:59 +01002523Examples :
willy tarreaueedaa9f2005-12-17 14:08:03 +01002524----------
2525 defaults applications TCP
willy tarreauc5f73ed2005-12-18 01:26:38 +01002526 log global
2527 mode tcp
2528 balance roundrobin
2529 clitimeout 180000
2530 srvtimeout 180000
2531 contimeout 4000
2532 retries 3
2533 redispatch
willy tarreaueedaa9f2005-12-17 14:08:03 +01002534
2535 listen app_tcp1 10.0.0.1:6000-6063
willy tarreauc5f73ed2005-12-18 01:26:38 +01002536 server srv1 192.168.1.1 check port 6000 inter 10000
2537 server srv2 192.168.1.2 backup
willy tarreaueedaa9f2005-12-17 14:08:03 +01002538
2539 listen app_tcp2 10.0.0.2:6000-6063
willy tarreauc5f73ed2005-12-18 01:26:38 +01002540 server srv1 192.168.2.1 check port 6000 inter 10000
2541 server srv2 192.168.2.2 backup
willy tarreaueedaa9f2005-12-17 14:08:03 +01002542
2543 defaults applications HTTP
willy tarreauc5f73ed2005-12-18 01:26:38 +01002544 log global
2545 mode http
2546 option httplog
2547 option forwardfor
2548 option dontlognull
2549 balance roundrobin
2550 clitimeout 20000
2551 srvtimeout 20000
2552 contimeout 4000
2553 retries 3
willy tarreaueedaa9f2005-12-17 14:08:03 +01002554
2555 listen app_http1 10.0.0.1:80-81
willy tarreauc5f73ed2005-12-18 01:26:38 +01002556 cookie SERVERID postonly insert indirect
2557 capture cookie userid= len 10
2558 server srv1 192.168.1.1:+8000 cookie srv1 check port 8080 inter 1000
2559 server srv1 192.168.1.2:+8000 cookie srv2 check port 8080 inter 1000
willy tarreaueedaa9f2005-12-17 14:08:03 +01002560
2561 defaults
willy tarreauc5f73ed2005-12-18 01:26:38 +01002562 # this empty section voids all default parameters
willy tarreaueedaa9f2005-12-17 14:08:03 +01002563
willy tarreau481132e2006-05-21 21:43:10 +02002564
25654.8) Status report in HTML page
2566-------------------------------
2567Starting with 1.2.14, it is possible for HAProxy to intercept requests for a
2568particular URI and return a full report of the proxy's activity and servers
2569statistics. This is available through the 'stats' keyword, associated to any
2570such options :
2571
2572 - stats enable
2573 - stats uri <uri prefix>
2574 - stats realm <authentication realm>
2575 - stats auth <user:password>
2576 - stats scope <proxy_id> | '.'
2577
2578By default, the status report is disabled. Specifying any combination above
2579enables it for the proxy instance referencing it. The easiest solution is to
2580use "stats enable" which will enable the report with default parameters :
2581
2582 - default URI : "/haproxy?stats" (CONFIG_STATS_DEFAULT_URI)
2583 - default auth : unspecified (no authentication)
2584 - default realm : "HAProxy Statistics" (CONFIG_STATS_DEFAULT_REALM)
2585 - default scope : unspecified (access to all instances)
2586
2587The "stats uri <uri_prefix>" option allows one to intercept another URI prefix.
2588Note that any URI that BEGINS with this string will match. For instance, one
2589proxy instance might be dedicated to status page only and would reply to any
2590URI.
2591
2592Example :
2593---------
2594 # catches any URI and returns the status page.
2595 listen stats :8080
2596 mode http
2597 stats uri /
2598
2599The "stats auth <user:password>" option enables Basic authentication and adds a
2600valid user:password combination to the list of authorized accounts. The user
2601and password are passed in the configuration file as clear text, and since this
2602is HTTP Basic authentication, you should be aware that it transits as clear
2603text on the network, so you must not use any sensible account. The list is
2604unlimited in order to provide easy accesses to developpers or customers.
2605
2606The "stats realm <realm>" option defines the "realm" name which is displayed
2607in the popup box when the browser asks for a password. It's important to ensure
2608that this one is not used by the application, otherwise the browser will try to
2609use a cached one from the application. Note that any space in the realm name
2610should be escaped with a backslash ('\').
2611
2612The "stats scope <proxy_id>" option limits the scope of the status report. By
2613default, all proxy instances are listed. But under some circumstances, it would
2614be better to limit the listing to some proxies or only to the current one. This
2615is what this option does. The special proxy name "." (a single dot) references
2616the current proxy. The proxy name can be repeated multiple times, even for
2617proxies defined later in the configuration or some which do not exist. The name
2618is the one which appears after the 'listen' keyword.
2619
2620Example :
2621---------
2622 # simple application with authenticated embedded status report
2623 listen app1 192.168.1.100:80
2624 mode http
willy tarreaud4ba08d2006-05-21 21:54:14 +02002625 option httpclose
willy tarreau481132e2006-05-21 21:43:10 +02002626 balance roundrobin
2627 cookie SERVERID postonly insert indirect
2628 server srv1 192.168.1.1:8080 cookie srv1 check inter 1000
2629 server srv1 192.168.1.2:8080 cookie srv2 check inter 1000
2630 stats uri /my_stats
willy tarreaud4ba08d2006-05-21 21:54:14 +02002631 stats realm Statistics\ for\ MyApp1-2
2632 stats auth guest:guest
2633 stats auth admin:AdMiN123
2634 stats scope .
2635 stats scope app2
willy tarreau481132e2006-05-21 21:43:10 +02002636
2637 # simple application with anonymous embedded status report
2638 listen app2 192.168.2.100:80
2639 mode http
willy tarreaud4ba08d2006-05-21 21:54:14 +02002640 option httpclose
willy tarreau481132e2006-05-21 21:43:10 +02002641 balance roundrobin
2642 cookie SERVERID postonly insert indirect
2643 server srv1 192.168.2.1:8080 cookie srv1 check inter 1000
2644 server srv1 192.168.2.2:8080 cookie srv2 check inter 1000
2645 stats uri /my_stats
willy tarreaud4ba08d2006-05-21 21:54:14 +02002646 stats realm Statistics\ for\ MyApp2
2647 stats scope .
willy tarreau481132e2006-05-21 21:43:10 +02002648
2649 listen admin_page :8080
2650 mode http
2651 stats uri /my_stats
willy tarreaud4ba08d2006-05-21 21:54:14 +02002652 stats realm Global\ statistics
2653 stats auth admin:AdMiN123
willy tarreau481132e2006-05-21 21:43:10 +02002654
2655Notes :
2656-------
2657 - The 'stats' options can also be specified in the 'defaults' section, in
2658 which case it will provide the exact same configuration to all further
2659 instances (hence the usefulness of the scope "."). However, if an instance
2660 redefines any 'stats' parameter, defaults will not be used for this
2661 instance.
2662
2663 - HTTP Basic authentication is very basic and unsecure from snooping. No
2664 sensible password should be used, and be aware that there is no way to
2665 remove it from the browser so it will be sent to the whole application
2666 upon further accesses.
2667
willy tarreaud4ba08d2006-05-21 21:54:14 +02002668 - It is very important that the 'option httpclose' is specified, otherwise
2669 the proxy will not be able to detect the URI within keep-alive sessions
2670 maintained between the browser and the servers, so the stats URI will be
2671 forwarded unmodified to the server as if the option was not set.
2672
willy tarreau481132e2006-05-21 21:43:10 +02002673
Willy Tarreau726c2bf2007-05-09 01:31:45 +020026745) Access lists
2675===============
2676
2677With version 1.3.10, a new concept of access lists (acl) was born. As it was
2678not necesary to reinvent the wheel, and because even long thoughts lead to
2679unsatisfying proposals, it was finally decided that something close to what
2680Squid provides would be a good compromise between features and ease of use.
2681
2682The principle is very simple : acls are declared with a name, a test and a list
2683of valid values to check against during the test. Conditions are applied on
2684various actions, and those conditions apply a logical AND between acls. The
2685condition is then only met if all acls are true.
2686
2687It is possible to use the reserved keyword "OR" in conditions, and it is
2688possible for an acl to be specified multiple times, even with various tests, in
2689which case the first one which returns true validates the ACL.
2690
Willy Tarreauae8b7962007-06-09 23:10:04 +02002691As of 1.3.12, only the following tests have been implemented :
Willy Tarreau726c2bf2007-05-09 01:31:45 +02002692
2693 Layer 3/4 :
2694 src <ipv4_address>[/mask] ... : match IPv4 source address
2695 dst <ipv4_address>[/mask] ... : match IPv4 destination address
Willy Tarreauae8b7962007-06-09 23:10:04 +02002696 src_port <range> ... : match source port range
2697 dst_port <range> ... : match destination port range
2698 dst_conn <range> ... : match #connections on frontend
Willy Tarreau726c2bf2007-05-09 01:31:45 +02002699
2700 Layer 7 :
2701 method <HTTP method> ... : match HTTP method
2702 req_ver <1.0|1.1> ... : match HTTP request version
2703 resp_ver <1.0|1.1> ... : match HTTP response version
Willy Tarreauae8b7962007-06-09 23:10:04 +02002704 status <range> ... : match HTTP response status code in range
Willy Tarreau726c2bf2007-05-09 01:31:45 +02002705 url <string> ... : exact string match on URI
2706 url_reg <regex> ... : regex string match on URI
2707 url_beg <string> ... : true if URI begins with <string>
2708 url_end <string> ... : true if URI ends with <string>
2709 url_sub <string> ... : true if URI contains <string>
2710 url_dir <string> ... : true if URI contains <string> between slashes
2711 url_dom <string> ... : true if URI contains <string> between slashes or dots
2712
Willy Tarreauae8b7962007-06-09 23:10:04 +02002713A 'range' is one or two integers which may be prefixed by an operator.
2714The syntax is :
2715
2716 [<op>] <low>[:<high>]
2717
2718Where <op> can be :
2719 'eq' : the tested value must be equal to <low> or within <low>..<high>
2720 'le' : the tested value must be lower than or equal to <low>
2721 'lt' : the tested value must be lower than <low>
2722 'ge' : the tested value must be greater than or equal to <low>
2723 'gt' : the tested value must be greater than <low>
2724
2725When no operator is defined, 'eq' is assumed. Note that when the operator is
2726specified, it applies to all subsequent ranges of values until the end of the
2727line is reached or another operator is specified. Example :
2728
2729 acl status_error status 400:599
2730 acl saturated_frt dst_conn ge 1000
2731 acl invalid_ports src_port lt 512 ge 65535
2732
Willy Tarreau726c2bf2007-05-09 01:31:45 +02002733Other ones are coming (headers, cookies, time, auth), it's just a matter of
2734time. It is also planned to be able to read the patterns from a file, as well
2735as to ignore the case for some of them.
2736
2737The only command supporting a condition right now is the "block" command, which
2738blocks a request and returns a 403 if its condition is true (with the "if"
2739keyword), or if it is false (with the "unless" keyword).
2740
2741Example :
2742---------
2743
2744 acl options_uris url *
2745 acl meth_option method OPTIONS
2746 acl http_1.1 req_ver 1.1
2747 acl allowed_meth method GET HEAD POST OPTIONS CONNECT
2748 acl connect_meth method CONNECT
2749 acl proxy_url url_beg http://
2750
2751 # block if reserved URI "*" used with a method other than "OPTIONS"
2752 block if options_uris !meth_option
2753
2754 # block if the OPTIONS method is used with HTTP 1.0
2755 block if meth_option !http_1.1
2756
2757 # allow non-proxy url with anything but the CONNECT method
2758 block if !connect_meth !proxy_url
2759
2760 # block all unknown methods
2761 block unless allowed_meth
2762
2763Note: this documentation is very light but should permit one to start and above
2764all it should permit to work on the project without being slowed down too much
2765with the doc.
2766
2767
willy tarreau197e8ec2005-12-17 14:10:59 +01002768=========================
2769| System-specific setup |
2770=========================
willy tarreaueedaa9f2005-12-17 14:08:03 +01002771
willy tarreau197e8ec2005-12-17 14:10:59 +01002772Linux 2.4
2773=========
willy tarreaueedaa9f2005-12-17 14:08:03 +01002774
2775-- cut here --
2776#!/bin/sh
2777# set this to about 256/4M (16384 for 256M machine)
2778MAXFILES=16384
2779echo $MAXFILES > /proc/sys/fs/file-max
2780ulimit -n $MAXFILES
2781
2782if [ -e /proc/sys/net/ipv4/ip_conntrack_max ]; then
willy tarreauc5f73ed2005-12-18 01:26:38 +01002783 echo 65536 > /proc/sys/net/ipv4/ip_conntrack_max
willy tarreaueedaa9f2005-12-17 14:08:03 +01002784fi
2785
2786if [ -e /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_fin_wait ]; then
willy tarreauc5f73ed2005-12-18 01:26:38 +01002787 # 30 seconds for fin, 15 for time wait
2788 echo 3000 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_fin_wait
2789 echo 1500 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_time_wait
2790 echo 0 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_log_invalid_scale
2791 echo 0 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_log_out_of_window
willy tarreaueedaa9f2005-12-17 14:08:03 +01002792fi
2793
2794echo 1024 60999 > /proc/sys/net/ipv4/ip_local_port_range
2795echo 30 > /proc/sys/net/ipv4/tcp_fin_timeout
2796echo 4096 > /proc/sys/net/ipv4/tcp_max_syn_backlog
2797echo 262144 > /proc/sys/net/ipv4/tcp_max_tw_buckets
2798echo 262144 > /proc/sys/net/ipv4/tcp_max_orphans
2799echo 300 > /proc/sys/net/ipv4/tcp_keepalive_time
2800echo 1 > /proc/sys/net/ipv4/tcp_tw_recycle
2801echo 0 > /proc/sys/net/ipv4/tcp_timestamps
2802echo 0 > /proc/sys/net/ipv4/tcp_ecn
willy tarreauc5f73ed2005-12-18 01:26:38 +01002803echo 1 > /proc/sys/net/ipv4/tcp_sack
willy tarreaueedaa9f2005-12-17 14:08:03 +01002804echo 0 > /proc/sys/net/ipv4/tcp_dsack
2805
2806# auto-tuned on 2.4
2807#echo 262143 > /proc/sys/net/core/rmem_max
2808#echo 262143 > /proc/sys/net/core/rmem_default
2809
2810echo 16384 65536 524288 > /proc/sys/net/ipv4/tcp_rmem
2811echo 16384 349520 699040 > /proc/sys/net/ipv4/tcp_wmem
2812
2813-- cut here --
2814
willy tarreau197e8ec2005-12-17 14:10:59 +01002815
2816FreeBSD
2817=======
2818
2819A FreeBSD port of HA-Proxy is now available and maintained, thanks to
2820Clement Laforet <sheepkiller@cultdeadsheep.org>.
2821
2822For more information :
2823http://www.freebsd.org/cgi/url.cgi?ports/net/haproxy/pkg-descr
2824http://www.freebsd.org/cgi/cvsweb.cgi/ports/net/haproxy/
2825http://www.freshports.org/net/haproxy
2826
2827
2828-- end --