blob: 335cff8420c46b3e0fe7364b3a81de0fdb7a8d7d [file] [log] [blame]
willy tarreau0174f312005-12-18 01:02:42 +01001 -------------------
2 H A - P r o x y
3 Reference Manual
4 -------------------
Willy TARREAU3481c462006-03-01 22:37:57 +01005 version 1.2.9
willy tarreauc5f73ed2005-12-18 01:26:38 +01006 willy tarreau
Willy TARREAU3481c462006-03-01 22:37:57 +01007 2006/03/01
willy tarreaueedaa9f2005-12-17 14:08:03 +01008
9============
10| Abstract |
11============
12
13HA-Proxy is a TCP/HTTP reverse proxy which is particularly suited for high
14availability environments. Indeed, it can :
15 - route HTTP requests depending on statically assigned cookies ;
16 - spread the load among several servers while assuring server persistence
17 through the use of HTTP cookies ;
18 - switch to backup servers in the event a main one fails ;
19 - accept connections to special ports dedicated to service monitoring ;
20 - stop accepting connections without breaking existing ones ;
21 - add/modify/delete HTTP headers both ways ;
22 - block requests matching a particular pattern ;
23
24It needs very little resource. Its event-driven architecture allows it to easily
25handle thousands of simultaneous connections on hundreds of instances without
26risking the system's stability.
27
28====================
29| Start parameters |
30====================
31
32There are only a few command line options :
33
34 -f <configuration file>
35 -n <high limit for the total number of simultaneous connections>
36 -N <high limit for the per-proxy number of simultaneous connections>
37 -d starts in foregreound with debugging mode enabled
38 -D starts in daemon mode
willy tarreau982249e2005-12-18 00:57:06 +010039 -q disable messages on output
40 -V displays messages on output even when -q or 'quiet' are specified.
41 -c only checks config file and exits with code 0 if no error was found, or
42 exits with code 1 if a syntax error was found.
willy tarreaufe2c5c12005-12-17 14:14:34 +010043 -p <pidfile> asks the process to write down each of its children's
44 pids to this file in daemon mode.
willy tarreaueedaa9f2005-12-17 14:08:03 +010045 -s shows statistics (only if compiled in)
46 -l shows even more statistics (implies '-s')
willy tarreau64a3cc32005-12-18 01:13:11 +010047 -de disables use of epoll()
48 -dp disables use of poll()
willy tarreaueedaa9f2005-12-17 14:08:03 +010049
50
51The maximal number of connections per proxy is used as the default parameter for
52each instance for which the 'maxconn' paramter is not set in the 'listen' section.
53
54The maximal number of total connections limits the number of connections used by
55the whole process if the 'maxconn' parameter is not set in the 'global' section.
56
57The debugging mode has the same effect as the 'debug' option in the 'global'
58section. When the proxy runs in this mode, it dumps every connections,
59disconnections, timestamps, and HTTP headers to stdout. This should NEVER
60be used in an init script since it will prevent the system from starting up.
61
62Statistics are only available if compiled in with the 'STATTIME' option. It's
63only used during code optimization phases.
64
65======================
66| Configuration file |
67======================
68
69Structure
70=========
71
72The configuration file parser ignores empty lines, spaces, tabs. Anything
73between a sharp ('#') not following a backslash ('\'), and the end of a line
74constitutes a comment and is ignored too.
75
76The configuration file is segmented in sections. A section begins whenever
77one of these 3 keywords are encountered :
78
79 - 'global'
80 - 'listen'
81 - 'defaults'
82
83Every parameter refer to the section beginning at the last one of these 3
84keywords.
85
86
871) Global parameters
88====================
89
90Global parameters affect the whole process behaviour. They are all set in the
91'global' section. There may be several 'global' sections if needed, but their
92parameters will only be merged. Allowed parameters in 'global' section include
93the following ones :
94
95 - log <address> <facility> [max_level]
96 - maxconn <number>
97 - uid <user id>
98 - gid <group id>
99 - chroot <directory>
100 - nbproc <number>
101 - daemon
102 - debug
willy tarreau64a3cc32005-12-18 01:13:11 +0100103 - noepoll
104 - nopoll
willy tarreaueedaa9f2005-12-17 14:08:03 +0100105 - quiet
willy tarreaufe2c5c12005-12-17 14:14:34 +0100106 - pidfile <file>
willy tarreauc5f73ed2005-12-18 01:26:38 +0100107 - ulimit-n <number>
willy tarreau598da412005-12-18 01:07:29 +0100108 - stats
willy tarreaueedaa9f2005-12-17 14:08:03 +0100109
willy tarreauc5f73ed2005-12-18 01:26:38 +0100110
willy tarreaueedaa9f2005-12-17 14:08:03 +01001111.1) Event logging
112------------------
113Most events are logged : start, stop, servers going up and down, connections and
114errors. Each event generates a syslog message which can be sent to up to 2
115servers. The syntax is :
116
117 log <ip_address> <facility> [max_level]
118
119Connections are logged at level "info". Services initialization and servers
120going up are logged at level "notice", termination signals are logged at
121"warning", and definitive service termination, as well as loss of servers are
122logged at level "alert". The optional parameter <max_level> specifies above
123what level messages should be sent. Level can take one of these 8 values :
124
125 emerg, alert, crit, err, warning, notice, info, debug
126
127For backwards compatibility with versions 1.1.16 and earlier, the default level
128value is "debug" if not specified.
129
130Permitted facilities are :
131 kern, user, mail, daemon, auth, syslog, lpr, news,
132 uucp, cron, auth2, ftp, ntp, audit, alert, cron2,
133 local0, local1, local2, local3, local4, local5, local6, local7
134
135According to RFC3164, messages are truncated to 1024 bytes before being emitted.
136
137Example :
138---------
139 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100140 log 192.168.2.200 local3
141 log 127.0.0.1 local4 notice
142
willy tarreaueedaa9f2005-12-17 14:08:03 +0100143
1441.2) limiting the number of connections
145---------------------------------------
146It is possible and recommended to limit the global number of per-process
willy tarreauc5f73ed2005-12-18 01:26:38 +0100147connections using the 'maxconn' global keyword. Since one connection includes
148both a client and a server, it means that the max number of TCP sessions will
149be about the double of this number. It's important to understand this when
150trying to find best values for 'ulimit -n' before starting the proxy. To
151anticipate the number of sockets needed, all these parameters must be counted :
willy tarreaueedaa9f2005-12-17 14:08:03 +0100152
153 - 1 socket per incoming connection
154 - 1 socket per outgoing connection
155 - 1 socket per address/port/proxy tuple.
156 - 1 socket per server being health-checked
157 - 1 socket for all logs
158
159In simple configurations where each proxy only listens one one address/port,
willy tarreauc5f73ed2005-12-18 01:26:38 +0100160set the limit of file descriptors (ulimit -n) to
161(2 * maxconn + nbproxies + nbservers + 1). Starting with versions 1.1.32/1.2.6,
162it is now possible to set the limit in the configuration using the 'ulimit-n'
163global keyword, provided the proxy is started as root. This puts an end to the
164recurrent problem of ensuring that the system limits are adapted to the proxy
165values. Note that these limits are per-process.
166
167Example :
168---------
169 global
170 maxconn 32000
171 ulimit-n 65536
172
willy tarreaueedaa9f2005-12-17 14:08:03 +0100173
1741.3) Drop of priviledges
175------------------------
176In order to reduce the risk and consequences of attacks, in the event where a
177yet non-identified vulnerability would be successfully exploited, it's possible
178to lower the process priviledges and even isolate it in a riskless directory.
179
180In the 'global' section, the 'uid' parameter sets a numerical user identifier
181which the process will switch to after binding its listening sockets. The value
182'0', which normally represents the super-user, here indicates that the UID must
183not change during startup. It's the default behaviour. The 'gid' parameter does
184the same for the group identifier. It's particularly advised against use of
185generic accounts such as 'nobody' because it has the same consequences as using
186'root' if other services use them.
187
188The 'chroot' parameter makes the process isolate itself in an empty directory
189just before switching its UID. This type of isolation (chroot) can sometimes
190be worked around on certain OS (Linux, Solaris), provided that the attacker
191has gained 'root' priviledges and has the ability to use or create a directory.
192For this reason, it's capital to use a dedicated directory and not to share one
193between several services of different nature. To make isolation more resistant,
194it's recommended to use an empty directory without any right, and to change the
195UID of the process so that it cannot do anything there.
196
197Note: in the event where such a vulnerability would be exploited, it's most
198likely that first attempts would kill the process due to 'Segmentation Fault',
199'Bus Error' or 'Illegal Instruction' signals. Eventhough it's true that
200isolating the server reduces the risks of intrusion, it's sometimes useful to
201find why a process dies, via the analysis of a 'core' file, although very rare
202(the last bug of this sort was fixed in 1.1.9). For security reasons, most
203systems disable the generation of core file when a process changes its UID. So
204the two workarounds are either to start the process from a restricted user
205account, which will not be able to chroot itself, or start it as root and not
206change the UID. In both cases the core will be either in the start or the chroot
207directories. Do not forget to allow core dumps prior to start the process :
208
209# ulimit -c unlimited
210
211Example :
212---------
213
214 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100215 uid 30000
216 gid 30000
217 chroot /var/chroot/haproxy
218
willy tarreaueedaa9f2005-12-17 14:08:03 +0100219
2201.4) Startup modes
221------------------
222The service can start in several different :
223 - foreground / background
224 - quiet / normal / debug
225
226The default mode is normal, foreground, which means that the program doesn't
227return once started. NEVER EVER use this mode in a system startup script, or
228the system won't boot. It needs to be started in background, so that it
229returns immediately after forking. That's accomplished by the 'daemon' option
230in the 'global' section, which is the equivalent of the '-D' command line
231argument.
232
233Moreover, certain alert messages are still sent to the standard output even
234in 'daemon' mode. To make them disappear, simply add the 'quiet' option in the
235'global' section. This option has no command-line equivalent.
236
237Last, the 'debug' mode, enabled with the 'debug' option in the 'global' section,
238and which is equivalent of the '-d' option, allows deep TCP/HTTP analysis, with
239timestamped display of each connection, disconnection, and HTTP headers for both
240ways. This mode is incompatible with 'daemon' and 'quiet' modes for obvious
241reasons.
242
willy tarreauc5f73ed2005-12-18 01:26:38 +0100243
willy tarreaueedaa9f2005-12-17 14:08:03 +01002441.5) Increasing the overall processing power
245--------------------------------------------
246On multi-processor systems, it may seem to be a shame to use only one processor,
willy tarreau982249e2005-12-18 00:57:06 +0100247eventhough the load needed to saturate a recent processor is far above common
willy tarreaueedaa9f2005-12-17 14:08:03 +0100248usage. Anyway, for very specific needs, the proxy can start several processes
249between which the operating system will spread the incoming connections. The
250number of processes is controlled by the 'nbproc' parameter in the 'global'
willy tarreau4302f492005-12-18 01:00:37 +0100251section. It defaults to 1, and obviously works only in 'daemon' mode. One
252typical usage of this parameter has been to workaround the default per-process
253file-descriptor limit that Solaris imposes to user processes.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100254
255Example :
256---------
257
258 global
willy tarreauc5f73ed2005-12-18 01:26:38 +0100259 daemon
260 quiet
261 nbproc 2
willy tarreaueedaa9f2005-12-17 14:08:03 +0100262
263
willy tarreaufe2c5c12005-12-17 14:14:34 +01002641.6) Helping process management
265-------------------------------
266Haproxy now supports the notion of pidfile. If the '-p' command line argument,
267or the 'pidfile' global option is followed with a file name, this file will be
268removed, then filled with all children's pids, one per line (only in daemon
269mode). This file is NOT within the chroot, which allows to work with a readonly
270 chroot. It will be owned by the user starting the process, and will have
271permissions 0644.
272
273Example :
274---------
275
276 global
277 daemon
278 quiet
willy tarreauc5f73ed2005-12-18 01:26:38 +0100279 nbproc 2
willy tarreaufe2c5c12005-12-17 14:14:34 +0100280 pidfile /var/run/haproxy-private.pid
281
282 # to stop only those processes among others :
283 # kill $(</var/run/haproxy-private.pid)
284
285
willy tarreau64a3cc32005-12-18 01:13:11 +01002861.7) Polling mechanisms
287-----------------------
288Starting from version 1.2.5, haproxy supports the poll() and epoll() polling
289mechanisms. On systems where select() is limited by FD_SETSIZE (like Solaris),
290poll() can be an interesting alternative. Performance tests show that Solaris'
291poll() performance does not decay as fast as the numbers of sockets increase,
292making it a safe solution for high loads. However, Solaris already uses poll()
293to emulate select(), so as long as the number of sockets has no reason to go
294higher than FD_SETSIZE, poll() should not provide any better performance. On
295Linux systems with the epoll() patch (or any 2.6 version), haproxy will use
296epoll() which is extremely fast and non dependant on the number of sockets.
297Tests have shown constant performance from 1 to 20000 simultaneous sessions.
298
299Haproxy will use epoll() when available, and will fall back to poll(), then to
300select(). However, if for any reason you need to disable epoll() or poll() (eg.
301because of a bug or just to compare performance), two new global options have
302been created for this matter : 'noepoll' and 'nopoll'.
303
304Example :
305---------
306
307 global
308 # use only select()
309 noepoll
310 nopoll
311
312Note :
313------
314For the sake of configuration file portability, these options are accepted but
315ignored if the poll() or epoll() mechanisms have not been enabled at compile
316time.
317
318To make debugging easier, the '-de' runtime argument disables epoll support and
319the '-dp' argument disables poll support. They are respectively equivalent to
320'noepoll' and 'nopoll'.
321
322
willy tarreaueedaa9f2005-12-17 14:08:03 +01003232) Declaration of a listening service
324=====================================
325
326Service sections start with the 'listen' keyword :
327
328 listen <instance_name> [ <IP_address>:<port_range>[,...] ]
329
330- <instance_name> is the name of the instance. This name will be reported in
331 logs, so it is good to have it reflect the proxied service. No unicity test
332 is done on this name, and it's not mandatory for it to be unique, but highly
333 recommended.
334
335- <IP_address> is the IP address the proxy binds to. Empty address, '*' and
336 '0.0.0.0' all mean that the proxy listens to all valid addresses on the
337 system.
338
339- <port_range> is either a unique port, or a port range for which the proxy will
340 accept connections for the IP address specified above. This range can be :
341 - a numerical port (ex: '80')
342 - a dash-delimited ports range explicitly stating the lower and upper bounds
343 (ex: '2000-2100') which are included in the range.
344
345 Particular care must be taken against port ranges, because every <addr:port>
346 couple consumes one socket (=a file descriptor), so it's easy to eat lots of
347 descriptors with a simple range. The <addr:port> couple must be used only once
348 among all instances running on a same system. Please note that attaching to
349 ports lower than 1024 need particular priviledges to start the program, which
350 are independant of the 'uid' parameter.
351
352- the <IP_address>:<port_range> couple may be repeated indefinitely to require
353 the proxy to listen to other addresses and/or ports. To achieve this, simply
354 separate them with a coma.
355
356Examples :
357---------
358 listen http_proxy :80
359 listen x11_proxy 127.0.0.1:6000-6009
360 listen smtp_proxy 127.0.0.1:25,127.0.0.1:587
361 listen ldap_proxy :389,:663
362
363In the event that all addresses do not fit line width, it's preferable to
364detach secondary addresses on other lines with the 'bind' keyword. If this
365keyword is used, it's not even necessary to specify the first address on the
366'listen' line, which sometimes makes multiple configuration handling easier :
367
368 bind [ <IP_address>:<port_range>[,...] ]
369
370Examples :
371----------
372 listen http_proxy
373 bind :80,:443
willy tarreauc5f73ed2005-12-18 01:26:38 +0100374 bind 10.0.0.1:10080,10.0.0.1:10443
375
willy tarreaueedaa9f2005-12-17 14:08:03 +0100376
3772.1) Inhibiting a service
378-------------------------
379A service may be disabled for maintenance reasons, without needing to comment
380out the whole section, simply by specifying the 'disabled' keyword in the
381section to be disabled :
382
383 listen smtp_proxy 0.0.0.0:25
willy tarreauc5f73ed2005-12-18 01:26:38 +0100384 disabled
willy tarreaueedaa9f2005-12-17 14:08:03 +0100385
386Note: the 'enabled' keyword allows to enable a service which has been disabled
387 previously by a default configuration.
388
willy tarreauc5f73ed2005-12-18 01:26:38 +0100389
willy tarreaueedaa9f2005-12-17 14:08:03 +01003902.2) Modes of operation
391-----------------------
392A service can work in 3 different distinct modes :
393 - TCP
394 - HTTP
395 - monitoring
396
397TCP mode
398--------
399In this mode, the service relays TCP connections as soon as they're established,
400towards one or several servers. No processing is done on the stream. It's only
401an association of source(addr:port) -> destination(addr:port). To use this mode,
402you must specify 'mode tcp' in the 'listen' section. This is the default mode.
403
404Example :
405---------
406 listen smtp_proxy 0.0.0.0:25
willy tarreauc5f73ed2005-12-18 01:26:38 +0100407 mode tcp
willy tarreaueedaa9f2005-12-17 14:08:03 +0100408
409HTTP mode
410---------
411In this mode, the service relays TCP connections towards one or several servers,
412when it has enough informations to decide, which normally means that all HTTP
413headers have been read. Some of them may be scanned for a cookie or a pattern
414matching a regex. To use this mode, specify 'mode http' in the 'listen' section.
415
416Example :
417---------
418 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100419 mode http
willy tarreaueedaa9f2005-12-17 14:08:03 +0100420
421Health-checking mode
422--------------------
423This mode provides a way for external components to check the proxy's health.
424It is meant to be used with intelligent load-balancers which can use send/expect
425scripts to check for all of their servers' availability. This one simply accepts
willy tarreau197e8ec2005-12-17 14:10:59 +0100426the connection, returns the word 'OK' and closes it. If the 'option httpchk' is
427set, then the reply will be 'HTTP/1.0 200 OK' with no data, so that it can be
428tested from a tool which supports HTTP health-checks. To enable it, simply
willy tarreaueedaa9f2005-12-17 14:08:03 +0100429specify 'health' as the working mode :
430
431Example :
432---------
willy tarreau197e8ec2005-12-17 14:10:59 +0100433 # simple response : 'OK'
willy tarreaueedaa9f2005-12-17 14:08:03 +0100434 listen health_check 0.0.0.0:60000
willy tarreauc5f73ed2005-12-18 01:26:38 +0100435 mode health
willy tarreaueedaa9f2005-12-17 14:08:03 +0100436
willy tarreau197e8ec2005-12-17 14:10:59 +0100437 # HTTP response : 'HTTP/1.0 200 OK'
438 listen http_health_check 0.0.0.0:60001
willy tarreauc5f73ed2005-12-18 01:26:38 +0100439 mode health
440 option httpchk
441
442Monitoring
443----------
444Versions 1.1.32 and 1.2.6 provide a new solution to check the proxy's
445availability without perturbating the service. The 'monitor-net' keyword was
446created to specify a network of equipments which CANNOT use the service for
447anything but health-checks. This is particularly suited to TCP proxies, because
448it prevents the proxy from relaying the monitor's connection to the remote
449server.
450
451When used with TCP, the connection is accepted then closed and nothing is
452logged. This is enough for a front-end load-balancer to detect the service as
453available.
willy tarreau197e8ec2005-12-17 14:10:59 +0100454
willy tarreauc5f73ed2005-12-18 01:26:38 +0100455When used with HTTP, the connection is accepted, nothing is logged, the
456following response is sent, then the session is closed : "HTTP/1.0 200 OK".
457This is normally enough for any front-end HTTP load-balancer to detect the
458service as available too, both with TCP and HTTP checks.
459
460Proxies using the "monitor-net" keyword can remove the "option dontlognull", as
461it will make them log empty connections from hosts outside the monitoring
462network.
463
464Example :
465---------
466
467 listen tse-proxy
468 bind :3389,:1494,:5900 # TSE, ICA and VNC at once.
469 mode tcp
470 balance roundrobin
471 server tse-farm 192.168.1.10
472 monitor-net 192.168.1.252/31 # L4 load-balancers on .252 and .253
473
willy tarreaueedaa9f2005-12-17 14:08:03 +0100474
4752.3) Limiting the number of simultaneous connections
476----------------------------------------------------
477The 'maxconn' parameter allows a proxy to refuse connections above a certain
478amount of simultaneous ones. When the limit is reached, it simply stops
479listening, but the system may still be accepting them because of the back log
willy tarreau982249e2005-12-18 00:57:06 +0100480queue. These connections will be processed later when other ones have freed
willy tarreaueedaa9f2005-12-17 14:08:03 +0100481some slots. This provides a serialization effect which helps very fragile
482servers resist to high loads. Se further for system limitations.
483
484Example :
485---------
486 listen tiny_server 0.0.0.0:80
487 maxconn 10
488
489
4902.4) Soft stop
491--------------
492It is possible to stop services without breaking existing connections by the
willy tarreau22739ef2006-01-20 20:43:32 +0100493sending of the SIGUSR1 signal to the process. All services are then put into
willy tarreaueedaa9f2005-12-17 14:08:03 +0100494soft-stop state, which means that they will refuse to accept new connections,
495except for those which have a non-zero value in the 'grace' parameter, in which
496case they will still accept connections for the specified amount of time, in
willy tarreau22739ef2006-01-20 20:43:32 +0100497milliseconds. This makes it possible to tell a load-balancer that the service
498is failing, while still doing the job during the time it needs to detect it.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100499
500Note: active connections are never killed. In the worst case, the user will have
501to wait for all of them to close or to time-out, or simply kill the process
willy tarreau22739ef2006-01-20 20:43:32 +0100502normally (SIGTERM). The default 'grace' value is '0'.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100503
504Example :
505---------
506 # enter soft stop after 'killall -USR1 haproxy'
507 # the service will still run 10 seconds after the signal
508 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100509 mode http
510 grace 10000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100511
512 # this port is dedicated to a load-balancer, and must fail immediately
513 listen health_check 0.0.0.0:60000
willy tarreauc5f73ed2005-12-18 01:26:38 +0100514 mode health
515 grace 0
willy tarreaueedaa9f2005-12-17 14:08:03 +0100516
517
willy tarreau39df2dc2006-01-29 21:56:05 +0100518As of version 1.2.8, a new soft-reconfiguration mechanism has been introduced.
willy tarreau22739ef2006-01-20 20:43:32 +0100519It is now possible to "pause" all the proxies by sending a SIGTTOU signal to
520the processes. This will disable the listening socket without breaking existing
521connections. After that, sending a SIGTTIN signal to those processes enables
522the listening sockets again. This is very useful to try to load a new
523configuration or even a new version of haproxy without breaking existing
524connections. If the load succeeds, then simply send a SIGUSR1 which will make
525the previous proxies exit immediately once their sessions are closed ; and if
526the load fails, then simply send a SIGTTIN to restore the service immediately.
527Please note that the 'grace' parameter is ignored for SIGTTOU, as well as for
528SIGUSR1 when the process was in the pause mode. Please also note that it would
529be useful to save the pidfile before starting a new instance.
530
531
willy tarreaueedaa9f2005-12-17 14:08:03 +01005322.5) Connections expiration time
533--------------------------------
534It is possible (and recommended) to configure several time-outs on TCP
535connections. Three independant timers are adjustable with values specified
536in milliseconds. A session will be terminated if either one of these timers
537expire.
538
539 - the time we accept to wait for data from the client, or for the client to
540 accept data : 'clitimeout' :
541
willy tarreauc5f73ed2005-12-18 01:26:38 +0100542 # client time-out set to 2mn30.
543 clitimeout 150000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100544
545 - the time we accept to wait for data from the server, or for the server to
546 accept data : 'srvtimeout' :
547
willy tarreauc5f73ed2005-12-18 01:26:38 +0100548 # server time-out set to 30s.
549 srvtimeout 30000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100550
551 - the time we accept to wait for a connection to establish on a server :
552 'contimeout' :
553
554 # we give up if the connection does not complete within 4 seconds
willy tarreauc5f73ed2005-12-18 01:26:38 +0100555 contimeout 4000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100556
557Notes :
558-------
559 - 'contimeout' and 'srvtimeout' have no sense on 'health' mode servers ;
560 - under high loads, or with a saturated or defective network, it's possible
561 that some packets get lost. Since the first TCP retransmit only happens
562 after 3 seconds, a time-out equal to, or lower than 3 seconds cannot
563 compensate for a packet loss. A 4 seconds time-out seems a reasonable
564 minimum which will considerably reduce connection failures.
565
willy tarreauc5f73ed2005-12-18 01:26:38 +0100566
willy tarreaueedaa9f2005-12-17 14:08:03 +01005672.6) Attempts to reconnect
568--------------------------
569After a connection failure to a server, it is possible to retry, potentially
570on another server. This is useful if health-checks are too rare and you don't
571want the clients to see the failures. The number of attempts to reconnect is
572set by the 'retries' paramter.
573
574Example :
575---------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100576 # we can retry 3 times max after a failure
577 retries 3
willy tarreaueedaa9f2005-12-17 14:08:03 +0100578
579
5802.7) Address of the dispatch server (deprecated)
581------------------------------------------------
582The server which will be sent all new connections is defined by the 'dispatch'
583parameter, in the form <address>:<port>. It generally is dedicated to unknown
584connections and will assign them a cookie, in case of HTTP persistence mode,
585or simply is a single server in case of generic TCP proxy. This old mode is only
586provided for backwards compatibility, but doesn't allow to check remote servers
587state, and has a rather limited usage. All new setups should switch to 'balance'
588mode. The principle of the dispatcher is to be able to perform the load
589balancing itself, but work only on new clients so that the server doesn't need
590to be a big machine.
591
592Example :
593---------
willy tarreauc5f73ed2005-12-18 01:26:38 +0100594 # all new connections go there
595 dispatch 192.168.1.2:80
willy tarreaueedaa9f2005-12-17 14:08:03 +0100596
597Note :
598------
599This parameter has no sense for 'health' servers, and is incompatible with
600'balance' mode.
601
602
6032.8) Outgoing source address
604----------------------------
605It is often necessary to bind to a particular address when connecting to some
606remote hosts. This is done via the 'source' parameter which is a per-proxy
607parameter. A newer version may allow to fix different sources to reach different
608servers. The syntax is 'source <address>[:<port>]', where <address> is a valid
609local address (or '0.0.0.0' or '*' or empty to let the system choose), and
610<port> is an optional parameter allowing the user to force the source port for
611very specific needs. If the port is not specified or is '0', the system will
612choose a free port. Note that as of version 1.1.18, the servers health checks
613are also performed from the same source.
614
615Examples :
616----------
617 listen http_proxy *:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100618 # all connections take 192.168.1.200 as source address
619 source 192.168.1.200:0
willy tarreaueedaa9f2005-12-17 14:08:03 +0100620
621 listen rlogin_proxy *:513
willy tarreauc5f73ed2005-12-18 01:26:38 +0100622 # use address 192.168.1.200 and the reserved port 900 (needs to be root)
623 source 192.168.1.200:900
willy tarreaueedaa9f2005-12-17 14:08:03 +0100624
625
6262.9) Setting the cookie name
627----------------------------
628In HTTP mode, it is possible to look for a particular cookie which will contain
629a server identifier which should handle the connection. The cookie name is set
630via the 'cookie' parameter.
631
632Example :
633---------
634 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100635 mode http
636 cookie SERVERID
willy tarreaueedaa9f2005-12-17 14:08:03 +0100637
638It is possible to change the cookie behaviour to get a smarter persistence,
639depending on applications. It is notably possible to delete or modify a cookie
640emitted by a server, insert a cookie identifying the server in an HTTP response
641and even add a header to tell upstream caches not to cache this response.
642
643Examples :
644----------
645
646To remove the cookie for direct accesses (ie when the server matches the one
647which was specified in the client cookie) :
648
willy tarreauc5f73ed2005-12-18 01:26:38 +0100649 cookie SERVERID indirect
willy tarreaueedaa9f2005-12-17 14:08:03 +0100650
651To replace the cookie value with the one assigned to the server if any (no
652cookie will be created if the server does not provide one, nor if the
653configuration does not provide one). This lets the application put the cookie
654exactly on certain pages (eg: successful authentication) :
655
willy tarreauc5f73ed2005-12-18 01:26:38 +0100656 cookie SERVERID rewrite
willy tarreaueedaa9f2005-12-17 14:08:03 +0100657
658To create a new cookie and assign the server identifier to it (in this case, all
659servers should be associated with a valid cookie, since no cookie will simply
660delete the cookie from the client's browser) :
661
willy tarreauc5f73ed2005-12-18 01:26:38 +0100662 cookie SERVERID insert
willy tarreaueedaa9f2005-12-17 14:08:03 +0100663
willy tarreau0174f312005-12-18 01:02:42 +0100664To reuse an existing application cookie and prefix it with the server's
665identifier, and remove it in the request, use the 'prefix' option. This allows
666to insert a haproxy in front of an application without risking to break clients
667which does not support more than one cookie :
668
willy tarreauc5f73ed2005-12-18 01:26:38 +0100669 cookie JSESSIONID prefix
willy tarreau0174f312005-12-18 01:02:42 +0100670
willy tarreaueedaa9f2005-12-17 14:08:03 +0100671To insert a cookie and ensure that no upstream cache will store it, add the
672'nocache' option :
673
willy tarreauc5f73ed2005-12-18 01:26:38 +0100674 cookie SERVERID insert nocache
willy tarreaueedaa9f2005-12-17 14:08:03 +0100675
676To insert a cookie only after a POST request, add 'postonly' after 'insert'.
677This has the advantage that there's no risk of caching, and that all pages
678seen before the POST one can still be cached :
679
willy tarreauc5f73ed2005-12-18 01:26:38 +0100680 cookie SERVERID insert postonly
willy tarreaueedaa9f2005-12-17 14:08:03 +0100681
682Notes :
683-----------
684- it is possible to combine 'insert' with 'indirect' or 'rewrite' to adapt to
685 applications which already generate the cookie with an invalid content.
686
687- in the case where 'insert' and 'indirect' are both specified, the cookie is
willy tarreau0174f312005-12-18 01:02:42 +0100688 never transmitted to the server, since it wouldn't understand it. This is the
689 most application-transparent mode.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100690
691- it is particularly recommended to use 'nocache' in 'insert' mode if any
692 upstream HTTP/1.0 cache is susceptible to cache the result, because this may
693 lead to many clients going to the same server, or even worse, some clients
694 having their server changed while retrieving a page from the cache.
695
willy tarreau0174f312005-12-18 01:02:42 +0100696- the 'prefix' mode normally does not need 'indirect', 'nocache', nor
697 'postonly', because just as in the 'rewrite' mode, it relies on the
698 application to know when a cookie can be emitted. However, since it has to
699 fix the cookie name in every subsequent requests, you must ensure that the
700 proxy will be used without any "HTTP keep-alive". Use option "httpclose" if
701 unsure.
702
willy tarreaueedaa9f2005-12-17 14:08:03 +0100703- when the application is well known and controlled, the best method is to
704 only add the persistence cookie on a POST form because it's up to the
willy tarreau0174f312005-12-18 01:02:42 +0100705 application to select which page it wants the upstream servers to cache. In
706 this case, you would use 'insert postonly indirect'.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100707
willy tarreauc5f73ed2005-12-18 01:26:38 +0100708
willy tarreaueedaa9f2005-12-17 14:08:03 +01007092.10) Associating a cookie value with a server
710----------------------------------------------
711In HTTP mode, it's possible to associate a cookie value to each server. This
712was initially used in combination with 'dispatch' mode to handle direct accesses
713but it is now the standard way of doing the load balancing. The syntax is :
714
715 server <identifier> <address>:<port> cookie <value>
716
717- <identifier> is any name which can be used to identify the server in the logs.
718- <address>:<port> specifies where the server is bound.
719- <value> is the value to put in or to read from the cookie.
720
721Example : the 'SERVERID' cookie can be either 'server01' or 'server02'
722---------
723 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100724 mode http
725 cookie SERVERID
726 dispatch 192.168.1.100:80
727 server web1 192.168.1.1:80 cookie server01
728 server web2 192.168.1.2:80 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100729
730Warning : the syntax has changed since version 1.0 !
731---------
732
willy tarreauc5f73ed2005-12-18 01:26:38 +0100733
willy tarreau598da412005-12-18 01:07:29 +01007342.11) Application Cookies
735-------------------------
736Since 1.2.4 it is possible to catch the cookie that comes from an
737application server in order to apply "application session stickyness".
738The server's response is searched for 'appsession' cookie, the first
739'len' bytes are used for matching and it is stored for a period of
740'timeout'.
741The syntax is:
742
743 appsession <SESSIONCOOKIE> len <MATCHLENGTH> timeout <HOLDTIME>
744
745- <SESSIONCOOKIE> is the cookie, the server uses for it's session-handling
746- <MATCHLENGTH> how many bytes/characters should be used for matching equal
747 sessions
748- <HOLDTIME> after this inactivaty time, in ms, the cookie will be deleted
749 from the sessionstore
750
751The appsession is only per 'listen' section possible.
752
753Example :
754---------
755 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100756 mode http
willy tarreau598da412005-12-18 01:07:29 +0100757 appsession JSESSIONID len 52 timeout 300000
758 .
759 .
760
willy tarreauc5f73ed2005-12-18 01:26:38 +0100761
willy tarreaueedaa9f2005-12-17 14:08:03 +01007623) Autonomous load balancer
763===========================
764
765The proxy can perform the load-balancing itself, both in TCP and in HTTP modes.
766This is the most interesting mode which obsoletes the old 'dispatch' mode
767described above. It has advantages such as server health monitoring, multiple
768port binding and port mapping. To use this mode, the 'balance' keyword is used,
769followed by the selected algorithm. As of version 1.1.23, only 'roundrobin' is
770available, which is also the default value if unspecified. In this mode, there
771will be no dispatch address, but the proxy needs at least one server.
772
773Example : same as the last one, with internal load balancer
774---------
775
776 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100777 mode http
778 cookie SERVERID
779 balance roundrobin
780 server web1 192.168.1.1:80 cookie server01
781 server web2 192.168.1.2:80 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100782
783
784Since version 1.1.22, it is possible to automatically determine on which port
785the server will get the connection, depending on the port the client connected
786to. Indeed, there now are 4 possible combinations for the server's <port> field:
787
788 - unspecified or '0' :
789 the connection will be sent to the same port as the one on which the proxy
790 received the client connection itself.
791
792 - numerical value (the only one supported in versions earlier than 1.1.22) :
793 the connection will always be sent to the specified port.
794
795 - '+' followed by a numerical value :
796 the connection will be sent to the same port as the one on which the proxy
797 received the connection, plus this value.
798
799 - '-' followed by a numerical value :
800 the connection will be sent to the same port as the one on which the proxy
801 received the connection, minus this value.
802
803Examples :
804----------
805
806# same as previous example
807
808 listen http_proxy :80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100809 mode http
810 cookie SERVERID
811 balance roundrobin
812 server web1 192.168.1.1 cookie server01
813 server web2 192.168.1.2 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100814
815# simultaneous relaying of ports 80, 81 and 8080-8089
816
817 listen http_proxy :80,:81,:8080-8089
willy tarreauc5f73ed2005-12-18 01:26:38 +0100818 mode http
819 cookie SERVERID
820 balance roundrobin
821 server web1 192.168.1.1 cookie server01
822 server web2 192.168.1.2 cookie server02
willy tarreaueedaa9f2005-12-17 14:08:03 +0100823
824# relaying of TCP ports 25, 389 and 663 to ports 1025, 1389 and 1663
825
826 listen http_proxy :25,:389,:663
willy tarreauc5f73ed2005-12-18 01:26:38 +0100827 mode tcp
828 balance roundrobin
829 server srv1 192.168.1.1:+1000
830 server srv2 192.168.1.2:+1000
willy tarreaueedaa9f2005-12-17 14:08:03 +0100831
832
willy tarreau197e8ec2005-12-17 14:10:59 +01008333.1) Server monitoring
834----------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +0100835It is possible to check the servers status by trying to establish TCP
836connections or even sending HTTP requests to them. A server which fails to
837reply to health checks as expected will not be used by the load balancing
838algorithms. To enable monitoring, add the 'check' keyword on a server line.
839It is possible to specify the interval between tests (in milliseconds) with
840the 'inter' parameter, the number of failures supported before declaring that
841the server has fallen down with the 'fall' parameter, and the number of valid
842checks needed for the server to fully get up with the 'rise' parameter. Since
843version 1.1.22, it is also possible to send checks to a different port
844(mandatory when none is specified) with the 'port' parameter. The default
845values are the following ones :
846
847 - inter : 2000
848 - rise : 2
849 - fall : 3
850 - port : default server port
851
852The default mode consists in establishing TCP connections only. But in certain
853types of application failures, it is often that the server continues to accept
854connections because the system does it itself while the application is running
855an endless loop, or is completely stuck. So in version 1.1.16 were introduced
856HTTP health checks which only performed simple lightweight requests and analysed
857the response. Now, as of version 1.1.23, it is possible to change the HTTP
858method, the URI, and the HTTP version string (which even allows to send headers
859with a dirty trick). To enable HTTP health-checks, use 'option httpchk'.
860
861By default, requests use the 'OPTIONS' method because it's very light and easy
862to filter from logs, and does it on '/'. Only HTTP responses 2xx and 3xx are
863considered valid ones, and only if they come before the time to send a new
864request is reached ('inter' parameter). If some servers block this type of
865request, 3 other forms help to forge a request :
866
867 - option httpchk -> OPTIONS / HTTP/1.0
868 - option httpchk URI -> OPTIONS <URI> HTTP/1.0
869 - option httpchk METH URI -> <METH> <URI> HTTP/1.0
870 - option httpchk METH URI VER -> <METH> <URI> <VER>
871
872See examples below.
873
874Since version 1.1.17, it is possible to specify backup servers. These servers
875are only sollicited when no other server is available. This may only be useful
876to serve a maintenance page, or define one active and one backup server (seldom
877used in TCP mode). To make a server a backup one, simply add the 'backup' option
878on its line. These servers also support cookies, so if a cookie is specified for
879a backup server, clients assigned to this server will stick to it even when the
880other ones come back. Conversely, if no cookie is assigned to such a server,
881the clients will get their cookies removed (empty cookie = removal), and will
882be balanced against other servers once they come back. Please note that there
Willy TARREAU3481c462006-03-01 22:37:57 +0100883is no load-balancing among backup servers by default. If there are several
884backup servers, the second one will only be used when the first one dies, and
885so on. To force load-balancing between backup servers, specify the 'allbackups'
886option.
willy tarreaueedaa9f2005-12-17 14:08:03 +0100887
888Since version 1.1.17, it is also possible to visually check the status of all
889servers at once. For this, you just have to send a SIGHUP signal to the proxy.
890The servers status will be dumped into the logs at the 'notice' level, as well
891as on <stderr> if not closed. For this reason, it's always a good idea to have
892one local log server at the 'notice' level.
893
willy tarreau982249e2005-12-18 00:57:06 +0100894Since version 1.1.28 and 1.2.1, if an instance loses all its servers, an
willy tarreau0174f312005-12-18 01:02:42 +0100895emergency message will be sent in the logs to inform the administator that an
willy tarreau982249e2005-12-18 00:57:06 +0100896immediate action must be taken.
897
willy tarreau0174f312005-12-18 01:02:42 +0100898Since version 1.1.30 and 1.2.3, several servers can share the same cookie
899value. This is particularly useful in backup mode, to select alternate paths
900for a given server for example, to provide soft-stop, or to direct the clients
901to a temporary page during an application restart. The principle is that when
902a server is dead, the proxy will first look for another server which shares the
903same cookie value for every client which presents the cookie. If there is no
904standard server for this cookie, it will then look for a backup server which
905shares the same name. Please consult the architecture guide for more information.
willy tarreau982249e2005-12-18 00:57:06 +0100906
willy tarreaueedaa9f2005-12-17 14:08:03 +0100907Examples :
908----------
909# same setup as in paragraph 3) with TCP monitoring
910 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100911 mode http
912 cookie SERVERID
913 balance roundrobin
914 server web1 192.168.1.1:80 cookie server01 check
915 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +0100916
917# same with HTTP monitoring via 'OPTIONS / HTTP/1.0'
918 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100919 mode http
920 cookie SERVERID
921 balance roundrobin
922 option httpchk
923 server web1 192.168.1.1:80 cookie server01 check
924 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +0100925
926# same with HTTP monitoring via 'OPTIONS /index.html HTTP/1.0'
927 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100928 mode http
929 cookie SERVERID
930 balance roundrobin
931 option httpchk /index.html
932 server web1 192.168.1.1:80 cookie server01 check
933 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +0100934
935# same with HTTP monitoring via 'HEAD /index.jsp? HTTP/1.1\r\nHost: www'
936 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100937 mode http
938 cookie SERVERID
939 balance roundrobin
940 option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
941 server web1 192.168.1.1:80 cookie server01 check
942 server web2 192.168.1.2:80 cookie server02 check inter 500 rise 1 fall 2
willy tarreaueedaa9f2005-12-17 14:08:03 +0100943
willy tarreau0174f312005-12-18 01:02:42 +0100944# Load-balancing with 'prefixed cookie' persistence, and soft-stop using an
945# alternate port 81 on the server for health-checks.
946 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100947 mode http
948 cookie JSESSIONID prefix
949 balance roundrobin
950 option httpchk HEAD /index.jsp? HTTP/1.1\r\nHost:\ www
951 server web1-norm 192.168.1.1:80 cookie s1 check port 81
952 server web2-norm 192.168.1.2:80 cookie s2 check port 81
953 server web1-stop 192.168.1.1:80 cookie s1 check port 80 backup
954 server web2-stop 192.168.1.2:80 cookie s2 check port 80 backup
willy tarreau0174f312005-12-18 01:02:42 +0100955
willy tarreaueedaa9f2005-12-17 14:08:03 +0100956# automatic insertion of a cookie in the server's response, and automatic
957# deletion of the cookie in the client request, while asking upstream caches
958# not to cache replies.
959 listen web_appl 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100960 mode http
961 cookie SERVERID insert nocache indirect
962 balance roundrobin
963 server web1 192.168.1.1:80 cookie server01 check
964 server web2 192.168.1.2:80 cookie server02 check
willy tarreaueedaa9f2005-12-17 14:08:03 +0100965
966# same with off-site application backup and local error pages server
967 listen web_appl 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +0100968 mode http
969 cookie SERVERID insert nocache indirect
970 balance roundrobin
971 server web1 192.168.1.1:80 cookie server01 check
972 server web2 192.168.1.2:80 cookie server02 check
973 server web-backup 192.168.2.1:80 cookie server03 check backup
974 server web-excuse 192.168.3.1:80 check backup
willy tarreaueedaa9f2005-12-17 14:08:03 +0100975
willy tarreauc5f73ed2005-12-18 01:26:38 +0100976# SMTP+TLS relaying with health-checks and backup servers
willy tarreaueedaa9f2005-12-17 14:08:03 +0100977
978 listen http_proxy :25,:587
willy tarreauc5f73ed2005-12-18 01:26:38 +0100979 mode tcp
980 balance roundrobin
981 server srv1 192.168.1.1 check port 25 inter 30000 rise 1 fall 2
982 server srv2 192.168.1.2 backup
willy tarreaueedaa9f2005-12-17 14:08:03 +0100983
Willy TARREAU3481c462006-03-01 22:37:57 +0100984# Load-balancing using a backup pool (requires haproxy 1.2.9)
985 listen http_proxy 0.0.0.0:80
986 mode http
987 balance roundrobin
988 option httpchk
989 server inst1 192.168.1.1:80 cookie s1 check
990 server inst2 192.168.1.2:80 cookie s2 check
991 server inst3 192.168.1.3:80 cookie s3 check
992 server back1 192.168.1.10:80 check backup
993 server back2 192.168.1.11:80 check backup
994 option allbackups # all backups will be used
995
willy tarreaueedaa9f2005-12-17 14:08:03 +0100996
9973.2) Redistribute connections in case of failure
998------------------------------------------------
999In HTTP mode, if a server designated by a cookie does not respond, the clients
1000may definitely stick to it because they cannot flush the cookie, so they will
1001not be able to access the service anymore. Specifying 'redispatch' will allow
1002the proxy to break their persistence and redistribute them to working servers.
1003
1004Example :
1005---------
1006 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001007 mode http
1008 cookie SERVERID
1009 dispatch 192.168.1.100:80
1010 server web1 192.168.1.1:80 cookie server01
1011 server web2 192.168.1.2:80 cookie server02
1012 redispatch # send back to dispatch in case of connection failure
willy tarreaueedaa9f2005-12-17 14:08:03 +01001013
1014Up to, and including version 1.1.16, this parameter only applied to connection
1015failures. Since version 1.1.17, it also applies to servers which have been
1016detected as failed by the health check mechanism. Indeed, a server may be broken
1017but still accepting connections, which would not solve every case. But it is
1018possible to conserve the old behaviour, that is, make a client insist on trying
1019to connect to a server even if it is said to be down, by setting the 'persist'
1020option :
1021
1022 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001023 mode http
1024 option persist
1025 cookie SERVERID
1026 dispatch 192.168.1.100:80
1027 server web1 192.168.1.1:80 cookie server01
1028 server web2 192.168.1.2:80 cookie server02
1029 redispatch # send back to dispatch in case of connection failure
willy tarreaueedaa9f2005-12-17 14:08:03 +01001030
1031
10324) Additionnal features
1033=======================
1034
1035Other features are available. They are transparent mode, event logging and
1036header rewriting/filtering.
1037
willy tarreauc5f73ed2005-12-18 01:26:38 +01001038
willy tarreau0174f312005-12-18 01:02:42 +010010394.1) Network features
willy tarreaueedaa9f2005-12-17 14:08:03 +01001040---------------------
willy tarreau0174f312005-12-18 01:02:42 +010010414.1.1) Transparent mode
1042-----------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +01001043In HTTP mode, the 'transparent' keyword allows to intercept sessions which are
1044routed through the system hosting the proxy. This mode was implemented as a
1045replacement for the 'dispatch' mode, since connections without cookie will be
1046sent to the original address while known cookies will be sent to the servers.
1047This mode implies that the system can redirect sessions to a local port.
1048
1049Example :
1050---------
1051 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001052 mode http
1053 transparent
1054 cookie SERVERID
1055 server server01 192.168.1.1:80
1056 server server02 192.168.1.2:80
willy tarreaueedaa9f2005-12-17 14:08:03 +01001057
1058 # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
1059 --dport 80 -j REDIRECT --to-ports 65000
1060
1061Note :
1062------
1063If the port is left unspecified on the server, the port the client connected to
1064will be used. This allows to relay a full port range without using transparent
1065mode nor thousands of file descriptors, provided that the system can redirect
1066sessions to local ports.
1067
1068Example :
1069---------
1070 # redirect all ports to local port 65000, then forward to the server on the
1071 # original port.
1072 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001073 mode tcp
1074 server server01 192.168.1.1 check port 60000
1075 server server02 192.168.1.2 check port 60000
willy tarreaueedaa9f2005-12-17 14:08:03 +01001076
1077 # iptables -t nat -A PREROUTING -i eth0 -p tcp -d 192.168.1.100 \
1078 -j REDIRECT --to-ports 65000
1079
willy tarreau0174f312005-12-18 01:02:42 +010010804.1.2) Per-server source address binding
1081----------------------------------------
1082As of versions 1.1.30 and 1.2.3, it is possible to specify a particular source
1083to reach each server. This is useful when reaching backup servers from a
1084different LAN, or to use an alternate path to reach the same server. It is also
1085usable to provide source load-balancing for outgoing connections. Obviously,
1086the same source address is used to send health-checks.
1087
1088Example :
1089---------
1090 # use a particular source to reach both servers
1091 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001092 mode http
1093 balance roundrobin
1094 server server01 192.168.1.1:80 source 192.168.2.13
1095 server server02 192.168.1.2:80 source 192.168.2.13
willy tarreau0174f312005-12-18 01:02:42 +01001096
1097Example :
1098---------
1099 # use a particular source to reach each servers
1100 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001101 mode http
1102 balance roundrobin
1103 server server01 192.168.1.1:80 source 192.168.1.1
1104 server server02 192.168.2.1:80 source 192.168.2.1
willy tarreau0174f312005-12-18 01:02:42 +01001105
1106Example :
1107---------
1108 # provide source load-balancing to reach the same proxy through 2 WAN links
1109 listen http_proxy 0.0.0.0:65000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001110 mode http
1111 balance roundrobin
1112 server remote-proxy-way1 192.168.1.1:3128 source 192.168.2.1
1113 server remote-proxy-way2 192.168.1.1:3128 source 192.168.3.1
willy tarreau0174f312005-12-18 01:02:42 +01001114
1115Example :
1116---------
1117 # force a TCP connection to bind to a specific port
1118 listen http_proxy 0.0.0.0:2000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001119 mode tcp
1120 balance roundrobin
1121 server srv1 192.168.1.1:80 source 192.168.2.1:20
1122 server srv2 192.168.1.2:80 source 192.168.2.1:20
willy tarreau0174f312005-12-18 01:02:42 +01001123
willy tarreaub952e1d2005-12-18 01:31:20 +010011244.1.3) TCP keep-alive
1125---------------------
1126With version 1.2.7, it becomes possible to enable TCP keep-alives on both the
1127client and server sides. This makes it possible to prevent long sessions from
1128expiring on external layer 4 components such as firewalls and load-balancers.
1129It also allows the system to terminate dead sessions when no timeout has been
1130set (not recommanded). The proxy cannot set the keep-alive probes intervals nor
1131maximal count, consult your operating system manual for this. There are 3
1132options to enable TCP keep-alive :
1133
1134 option tcpka # enables keep-alive both on client and server side
1135 option clitcpka # enables keep-alive only on client side
1136 option srvtcpka # enables keep-alive only on server side
1137
willy tarreaueedaa9f2005-12-17 14:08:03 +01001138
11394.2) Event logging
1140------------------
willy tarreauc5f73ed2005-12-18 01:26:38 +01001141
1142HAProxy's strength certainly lies in its precise logs. It probably provides the
1143finest level of information available for such a product, which is very
1144important for troubleshooting complex environments. Standard log information
1145include client ports, TCP/HTTP state timers, precise session state at
1146termination and precise termination cause, information about decisions to
1147direct trafic to a server, and of course the ability to capture arbitrary
1148headers.
1149
1150In order to improve administrators reactivity, it offers a great transparency
1151about encountered problems, both internal and external, and it is possible to
1152send logs to different sources at the same time with different level filters :
1153
1154 - global process-level logs (system errors, start/stop, etc..)
1155 - per-listener system and internal errors (lack of resource, bugs, ...)
1156 - per-listener external troubles (servers up/down, max connections)
1157 - per-listener activity (client connections), either at the establishment or
1158 at the termination.
1159
1160The ability to distribute different levels of logs to different log servers
1161allow several production teams to interact and to fix their problems as soon
1162as possible. For example, the system team might monitor system-wide errors,
1163while the application team might be monitoring the up/down for their servers in
1164real time, and the security team might analyze the activity logs with one hour
1165delay.
1166
willy tarreauc1cae632005-12-17 14:12:23 +010011674.2.1) Log levels
1168-----------------
willy tarreau197e8ec2005-12-17 14:10:59 +01001169TCP and HTTP connections can be logged with informations such as date, time,
1170source IP address, destination address, connection duration, response times,
1171HTTP request, the HTTP return code, number of bytes transmitted, the conditions
1172in which the session ended, and even exchanged cookies values, to track a
1173particular user's problems for example. All messages are sent to up to two
1174syslog servers. Consult section 1.1 for more info about log facilities. The
1175syntax follows :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001176
willy tarreau197e8ec2005-12-17 14:10:59 +01001177 log <address_1> <facility_1> [max_level_1]
1178 log <address_2> <facility_2> [max_level_2]
1179or
willy tarreaueedaa9f2005-12-17 14:08:03 +01001180 log global
1181
willy tarreau197e8ec2005-12-17 14:10:59 +01001182Note :
1183------
1184The particular syntax 'log global' means that the same log configuration as the
1185'global' section will be used.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001186
willy tarreau197e8ec2005-12-17 14:10:59 +01001187Example :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001188---------
1189 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001190 mode http
1191 log 192.168.2.200 local3
1192 log 192.168.2.201 local4
willy tarreaueedaa9f2005-12-17 14:08:03 +01001193
willy tarreauc1cae632005-12-17 14:12:23 +010011944.2.2) Log format
1195-----------------
1196By default, connections are logged at the TCP level, as soon as the session
1197establishes between the client and the proxy. By enabling the 'tcplog' option,
1198the proxy will wait until the session ends to generate an enhanced log
1199containing more information such as session duration and its state during the
1200disconnection.
1201
willy tarreauc5f73ed2005-12-18 01:26:38 +01001202Example of TCP logging :
1203------------------------
willy tarreau982249e2005-12-18 00:57:06 +01001204 listen relais-tcp 0.0.0.0:8000
willy tarreauc5f73ed2005-12-18 01:26:38 +01001205 mode tcp
1206 option tcplog
1207 log 192.168.2.200 local3
willy tarreau982249e2005-12-18 00:57:06 +01001208
willy tarreauc5f73ed2005-12-18 01:26:38 +01001209>>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28] relais-tcp Srv1 0/5007 0 -- 1/1
1210
1211 Field Format Example
1212
1213 1 process_name '[' pid ']:' haproxy[18989]:
1214 2 client_ip ':' client_port 127.0.0.1:34550
1215 3 '[' date ']' [15/Oct/2003:15:24:28]
1216 4 listener_name relais-tcp
1217 5 server_name Srv1
1218 6 connect_time '/' total_time 0/5007
1219 7 bytes_read 0
1220 8 termination_state --
1221 9 listener_conns '/' process_conns 1/1
1222
willy tarreau982249e2005-12-18 00:57:06 +01001223
willy tarreauc1cae632005-12-17 14:12:23 +01001224Another option, 'httplog', provides more detailed information about HTTP
1225contents, such as the request and some cookies. In the event where an external
1226component would establish frequent connections to check the service, logs may be
1227full of useless lines. So it is possible not to log any session which didn't
1228transfer any data, by the setting of the 'dontlognull' option. This only has
1229effect on sessions which are established then closed.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001230
willy tarreauc5f73ed2005-12-18 01:26:38 +01001231Example of HTTP logging :
1232-------------------------
willy tarreaueedaa9f2005-12-17 14:08:03 +01001233 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001234 mode http
1235 option httplog
1236 option dontlognull
1237 log 192.168.2.200 local3
1238
1239>>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57] relais-http Srv1 9/7/147/723 200 243 - - ---- 3/3 "HEAD / HTTP/1.0"
willy tarreaueedaa9f2005-12-17 14:08:03 +01001240
willy tarreauc5f73ed2005-12-18 01:26:38 +01001241More complete example
1242 haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31] relais-http Srv1 3183/-1/-1/11215 503 0 - - SC-- 202/205 {w.ods.org|Mozilla} {} "HEAD / HTTP/1.0"
1243
1244 Field Format Example
1245
1246 1 process_name '[' pid ']:' haproxy[18989]:
1247 2 client_ip ':' client_port 10.0.0.1:34552
1248 3 '[' date ']' [15/Oct/2003:15:26:31]
1249 4 listener_name relais-http
1250 5 server_name Srv1
1251 6 Tq '/' Tc '/' Tr '/' Tt 3183/-1/-1/11215
1252 7 HTTP_return_code 503
1253 8 bytes_read 0
1254 9 captured_request_cookie -
1255 10 captured_response_cookie -
1256 11 termination_state SC--
1257 12 listener_conns '/' process_conns 202/205
1258 13 '{' captured_request_headers '}' {w.ods.org|Mozilla}
1259 14 '{' captured_response_headers '}' {}
1260 15 '"' HTTP_request '"' "HEAD / HTTP/1.0"
1261
1262Note for log parsers: the URI is ALWAYS the end of the line starting with the
1263 first double quote '"'.
willy tarreau982249e2005-12-18 00:57:06 +01001264
1265The problem when logging at end of connection is that you have no clue about
1266what is happening during very long sessions. To workaround this problem, a
1267new option 'logasap' has been introduced in 1.1.28/1.2.1. When specified, the
1268proxy will log as soon as possible, just before data transfer begins. This means
1269that in case of TCP, it will still log the connection status to the server, and
1270in case of HTTP, it will log just after processing the server headers. In this
1271case, the number of bytes reported is the number of header bytes sent to the
1272client.
1273
1274In order to avoid confusion with normal logs, the total time field and the
1275number of bytes are prefixed with a '+' sign which mean that real numbers are
1276certainly bigger.
1277
1278Example :
1279---------
1280
1281 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001282 mode http
1283 option httplog
1284 option dontlognull
1285 option logasap
1286 log 192.168.2.200 local3
willy tarreau982249e2005-12-18 00:57:06 +01001287
willy tarreauc5f73ed2005-12-18 01:26:38 +01001288>>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/7/14/+30 200 +243 - - ---- 3/3 "GET /image.iso HTTP/1.0"
willy tarreau982249e2005-12-18 00:57:06 +01001289
willy tarreauc1cae632005-12-17 14:12:23 +010012904.2.3) Timing events
1291--------------------
1292Timers provide a great help in trouble shooting network problems. All values
1293are reported in milliseconds (ms). In HTTP mode, four control points are
1294reported under the form 'Tq/Tc/Tr/Tt' :
1295
1296 - Tq: total time to get the client request.
1297 It's the time elapsed between the moment the client connection was accepted
1298 and the moment the proxy received the last HTTP header. The value '-1'
1299 indicates that the end of headers (empty line) has never been seen.
1300
1301 - Tc: total time to establish the TCP connection to the server.
1302 It's the time elapsed between the moment the proxy sent the connection
1303 request, and the moment it was acknowledged, or between the TCP SYN packet
1304 and the matching SYN/ACK in return. The value '-1' means that the
1305 connection never established.
1306
1307 - Tr: server response time. It's the time elapsed between the moment the
1308 TCP connection was established to the server and the moment it send its
1309 complete response header. It purely shows its request processing time,
1310 without the network overhead due to the data transmission. The value '-1'
1311 means that the last the response header (empty line) was never seen.
1312
1313 - Tt: total session duration time, between the moment the proxy accepted it
willy tarreau982249e2005-12-18 00:57:06 +01001314 and the moment both ends were closed. The exception is when the 'logasap'
1315 option is specified. In this case, it only equals (Tq+Tc+Tr), and is
1316 prefixed with a '+' sign. From this field, we can deduce Td, the data
1317 transmission time, by substracting other timers when valid :
willy tarreauc1cae632005-12-17 14:12:23 +01001318
1319 Td = Tt - (Tq + Tc + Tr)
1320
1321 Timers with '-1' values have to be excluded from this equation.
1322
1323In TCP mode ('option tcplog'), only Tc and Tt are reported.
1324
1325These timers provide precious indications on trouble causes. Since the TCP
1326protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure
1327that timers close to multiples of 3s are nearly always related to packets lost
1328due to network problems (wires or negociation). Moreover, if <Tt> is close to
1329a timeout value specified in the configuration, it often means that a session
1330has been aborted on time-out.
1331
1332Most common cases :
1333
1334 - If Tq is close to 3000, a packet has probably been lost between the client
1335 and the proxy.
1336 - If Tc is close to 3000, a packet has probably been lost between the server
1337 and the proxy during the server connection phase. This one should always be
1338 very low (less than a few tens).
1339 - If Tr is nearly always lower than 3000 except some rare values which seem to
1340 be the average majored by 3000, there are probably some packets lost between
1341 the proxy and the server.
1342 - If Tt is often slightly higher than a time-out, it's often because the
1343 client and the server use HTTP keep-alive and the session is maintained
1344 after the response ends. Se further for how to disable HTTP keep-alive.
1345
1346Other cases ('xx' means any value to be ignored) :
1347 -1/xx/xx/Tt : the client was not able to send its complete request in time,
willy tarreauc5f73ed2005-12-18 01:26:38 +01001348 or that it aborted it too early.
willy tarreauc1cae632005-12-17 14:12:23 +01001349 Tq/-1/xx/Tt : the connection could not establish on the server. Either it
willy tarreauc5f73ed2005-12-18 01:26:38 +01001350 refused it or it timed out after Tt-Tq ms.
willy tarreauc1cae632005-12-17 14:12:23 +01001351 Tq/Tc/-1/Tt : the server has accepted the connection but did not return a
willy tarreauc5f73ed2005-12-18 01:26:38 +01001352 complete response in time, or it closed its connexion
1353 unexpectedly, after Tt-(Tq+Tc) ms.
willy tarreauc1cae632005-12-17 14:12:23 +01001354
13554.2.4) Session state at disconnection
1356-------------------------------------
willy tarreauc5f73ed2005-12-18 01:26:38 +01001357TCP and HTTP logs provide a session completion indicator in the
1358<termination_state> field, just before the number of active
1359connections. It is 2-characters long in TCP, and 4-characters long in
1360HTTP, each of which has a special meaning :
1361
willy tarreau197e8ec2005-12-17 14:10:59 +01001362 - On the first character, a code reporting the first event which caused the
1363 session to terminate :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001364
willy tarreauc5f73ed2005-12-18 01:26:38 +01001365 C : the TCP session was unexpectedly aborted by the client.
1366
1367 S : the TCP session was unexpectedly aborted by the server, or the
1368 server explicitly refused it.
1369
1370 P : the session was prematurely aborted by the proxy, because of a
1371 connection limit enforcement, because a DENY filter was matched,
1372 or because of a security check which detected and blocked a
1373 dangerous error in server response which might have caused
1374 information leak (eg: cacheable cookie).
1375
1376 R : a resource on the proxy has been exhausted (memory, sockets, source
1377 ports, ...). Usually, this appears during the connection phase, and
1378 system logs should contain a copy of the precise error.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001379
willy tarreauc5f73ed2005-12-18 01:26:38 +01001380 I : an internal error was identified by the proxy during a self-check.
1381 This should NEVER happen, and you are encouraged to report any log
1382 containing this, because this is a bug.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001383
willy tarreauc5f73ed2005-12-18 01:26:38 +01001384 c : the client-side time-out expired first.
1385
1386 s : the server-side time-out expired first.
1387
1388 - : normal session completion.
1389
1390 - on the second character, the TCP/HTTP session state when it was closed :
1391
1392 R : waiting for complete REQUEST from the client (HTTP only). Nothing
1393 was sent to any server.
1394
1395 C : waiting for CONNECTION to establish on the server. The server might
1396 at most have noticed a connection attempt.
1397
1398 H : waiting for, receiving and processing server HEADERS (HTTP only).
1399
1400 D : the session was in the DATA phase.
1401
1402 L : the proxy was still transmitting LAST data to the client while the
1403 server had already finished.
1404
1405 - : normal session completion after end of data transfer.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001406
willy tarreau197e8ec2005-12-17 14:10:59 +01001407 - the third character tells whether the persistence cookie was provided by
willy tarreauc1cae632005-12-17 14:12:23 +01001408 the client (only in HTTP mode) :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001409
willy tarreauc5f73ed2005-12-18 01:26:38 +01001410 N : the client provided NO cookie. This is usually the case on new
1411 connections.
1412
1413 I : the client provided an INVALID cookie matching no known
1414 server. This might be caused by a recent configuration change,
1415 mixed cookies between HTTP/HTTPS sites, or an attack.
1416
1417 D : the client provided a cookie designating a server which was DOWN,
1418 so either the 'persist' option was used and the client was sent to
1419 this server, or it was not set and the client was redispatched to
1420 another server.
1421
1422 V : the client provided a valid cookie, and was sent to the associated
1423 server.
1424
1425 - : does not apply (no cookie set in configuration).
willy tarreaueedaa9f2005-12-17 14:08:03 +01001426
willy tarreau197e8ec2005-12-17 14:10:59 +01001427 - the last character reports what operations were performed on the persistence
willy tarreauc1cae632005-12-17 14:12:23 +01001428 cookie returned by the server (only in HTTP mode) :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001429
willy tarreauc5f73ed2005-12-18 01:26:38 +01001430 N : NO cookie was provided by the server, and none was inserted either.
1431
1432 I : no cookie was provided by the server, and the proxy INSERTED one.
1433
willy tarreau197e8ec2005-12-17 14:10:59 +01001434 P : a cookie was PROVIDED by the server and transmitted as-is.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001435
willy tarreauc5f73ed2005-12-18 01:26:38 +01001436 R : the cookie provided by the server was REWRITTEN by the proxy.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001437
willy tarreauc5f73ed2005-12-18 01:26:38 +01001438 D : the cookie provided by the server was DELETED by the proxy.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001439
willy tarreauc5f73ed2005-12-18 01:26:38 +01001440 - : does not apply (no cookie set in configuration).
willy tarreaueedaa9f2005-12-17 14:08:03 +01001441
willy tarreauc5f73ed2005-12-18 01:26:38 +01001442The combination of the two first flags give a lot of information about what was
1443happening when the session terminated. It can be helpful to detect server
1444saturation, network troubles, local system resource starvation, attacks, etc...
willy tarreaueedaa9f2005-12-17 14:08:03 +01001445
willy tarreauc5f73ed2005-12-18 01:26:38 +01001446The most common termination flags combinations are indicated here.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001447
willy tarreauc5f73ed2005-12-18 01:26:38 +01001448 Flags Reason
1449 CR The client aborted before sending a full request. Most probably the
1450 request was done by hand using a telnet client, and aborted early.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001451
willy tarreauc5f73ed2005-12-18 01:26:38 +01001452 cR The client timed out before sending a full request. This is sometimes
1453 caused by too large TCP MSS values on the client side for PPPoE
1454 networks which cannot transport full-sized packets, or by clients
1455 sending requests by hand and not typing fast enough.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001456
willy tarreauc5f73ed2005-12-18 01:26:38 +01001457 SC The server explicitly refused the connection (the proxy received a
1458 TCP RST or an ICMP in return). Under some circumstances, it can
1459 also be the network stack telling the proxy that the server is
1460 unreachable (eg: no route, or no ARP response on local network).
willy tarreau982249e2005-12-18 00:57:06 +01001461
willy tarreauc5f73ed2005-12-18 01:26:38 +01001462 sC The connection to the server did not complete during contimeout.
willy tarreau982249e2005-12-18 00:57:06 +01001463
willy tarreauc5f73ed2005-12-18 01:26:38 +01001464 PC The proxy refused to establish a connection to the server because the
1465 maxconn limit has been reached. The listener's maxconn parameter may
1466 be increased in the proxy configuration, as well as the global
1467 maxconn parameter.
willy tarreauc1cae632005-12-17 14:12:23 +01001468
willy tarreauc5f73ed2005-12-18 01:26:38 +01001469 RC A local resource has been exhausted (memory, sockets, source ports)
1470 preventing the connection to the server from establishing. The error
1471 logs will tell precisely what was missing. Anyway, this can only be
1472 solved by system tuning.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001473
willy tarreauc5f73ed2005-12-18 01:26:38 +01001474 cH The client timed out during a POST request. This is sometimes caused
1475 by too large TCP MSS values for PPPoE networks which cannot transport
1476 full-sized packets.
willy tarreauc1cae632005-12-17 14:12:23 +01001477
willy tarreauc5f73ed2005-12-18 01:26:38 +01001478 SH The server aborted before sending its full headers, or it crashed.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001479
willy tarreauc5f73ed2005-12-18 01:26:38 +01001480 sH The server failed to reply during the srvtimeout delay, which
1481 indicates too long transactions, probably caused by back-end
1482 saturation. The only solutions are to fix the problem on the
1483 application or to increase the 'srvtimeout' parameter to support
1484 longer delays (at the risk of the client giving up anyway).
1485
1486 PR The proxy blocked the client's request, either because of an invalid
1487 HTTP syntax, in which case it returned an HTTP 400 error to the
1488 client, or because a deny filter matched, in which case it returned
1489 an HTTP 403 error.
1490
1491 PH The proxy blocked the server's response, because it was invalid,
1492 incomplete, dangerous (cache control), or matched a security filter.
1493 In any case, an HTTP 502 error is sent to the client.
1494
1495 cD The client did not read any data for as long as the clitimeout delay.
1496 This is often caused by network failures on the client side.
1497
1498 CD The client unexpectedly aborted during data transfer. This is either
1499 caused by a browser crash, or by a keep-alive session between the
1500 server and the client terminated first by the client.
1501
1502 sD The server did nothing during the srvtimeout delay. This is often
1503 caused by too short timeouts on L4 equipements before the server
1504 (firewalls, load-balancers, ...).
1505
15064.2.5) Non-printable characters
willy tarreau4302f492005-12-18 01:00:37 +01001507-------------------------------
1508As of version 1.1.29, non-printable characters are not sent as-is into log
1509files, but are converted to their two-digits hexadecimal representation,
1510prefixed by the character '#'. The only characters that can now be logged
1511without being escaped are between 32 and 126 (inclusive). Obviously, the
1512escape character '#' is also encoded to avoid any ambiguity. It is the same for
1513the character '"', as well as '{', '|' and '}' when logging headers.
1514
willy tarreauc5f73ed2005-12-18 01:26:38 +010015154.2.6) Capturing HTTP headers and cookies
1516-----------------------------------------
1517Version 1.1.23 brought cookie capture, and 1.1.29 the header capture. All this
1518is performed using the 'capture' keyword.
1519
1520Cookie capture makes it easy to track a complete user session. The syntax is :
1521
1522 capture cookie <cookie_prefix> len <capture_length>
1523
1524This will enable cookie capture from both requests and responses. This way,
1525it's easy to detect when a user switches to a new session for example, because
1526the server will reassign it a new cookie.
1527
1528The FIRST cookie whose name starts with <cookie_prefix> will be captured, and
1529logged as 'NAME=value', without exceeding <capture_length> characters (64 max).
1530When the cookie name is fixed and known, it's preferable to suffix '=' to it to
1531ensure that no other cookie will be logged.
1532
1533Examples :
1534----------
1535 # capture the first cookie whose name starts with "ASPSESSION"
1536 capture cookie ASPSESSION len 32
1537
1538 # capture the first cookie whose name is exactly "vgnvisitor"
1539 capture cookie vgnvisitor= len 32
1540
1541In the logs, the field preceeding the completion indicator contains the cookie
1542value as sent by the server, preceeded by the cookie value as sent by the
1543client. Each of these field is replaced with '-' when no cookie was seen or
1544when the option is disabled.
1545
1546Header captures have a different goal. They are useful to track unique request
1547identifiers set by a previous proxy, virtual host names, user-agents, POST
1548content-length, referrers, etc. In the response, one can search for information
1549about the response length, how the server asked the cache to behave, or an
1550object location during a redirection. As for cookie captures, it is both
1551possible to include request headers and response headers at the same time. The
1552syntax is :
willy tarreau4302f492005-12-18 01:00:37 +01001553
1554 capture request header <name> len <max length>
1555 capture response header <name> len <max length>
1556
1557Note: Header names are not case-sensitive.
1558
1559Examples:
1560---------
1561 # keep the name of the virtual server
1562 capture request header Host len 20
1563 # keep the amount of data uploaded during a POST
1564 capture request header Content-Length len 10
1565
1566 # note the expected cache behaviour on the response
1567 capture response header Cache-Control len 8
1568 # note the URL location during a redirection
1569 capture response header Location len 20
1570
1571Non-existant headers are logged as empty strings, and if one header appears more
1572than once, only its last occurence will be kept. Request headers are grouped
1573within braces '{' and '}' in the same order as they were declared, and delimited
1574with a vertical bar '|' without any space. Response headers follow the same
1575representation, but are displayed after a space following the request headers
1576block. These blocks are displayed just before the HTTP request in the logs.
willy tarreauc5f73ed2005-12-18 01:26:38 +01001577
willy tarreau4302f492005-12-18 01:00:37 +01001578Example :
1579
willy tarreauc5f73ed2005-12-18 01:26:38 +01001580 Config:
1581
1582 capture request header Host len 20
1583 capture request header Content-Length len 10
1584 capture request header Referer len 20
1585 capture response header Server len 20
1586 capture response header Content-Length len 10
1587 capture response header Cache-Control len 8
1588 capture response header Via len 20
1589 capture response header Location len 20
1590
1591 Log :
1592
1593 Aug 9 20:26:09 localhost haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] relais-http netcache 0/0/162/+162 200 +350 - - ---- {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} "GET http://fr.adserver.yahoo.com/"
1594 Aug 9 20:30:46 localhost haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] relais-http netcache 0/0/182/+182 200 +279 - - ---- {w.ods.org||} {Formilux/0.1.8|3495|||} "GET http://w.ods.org/sytadin.html HTTP/1.1"
1595 Aug 9 20:30:46 localhost haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] relais-http netcache 0/2/126/+128 200 +223 - - ---- {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"
1596
1597
15984.2.7) Examples of logs
1599-----------------------
1600- haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57] relais-http Srv1 6559/7/147/6723 200 243 - - ---- 3/5 "HEAD / HTTP/1.0"
1601 => long request (6.5s) entered by hand through 'telnet'. The server replied
1602 in 147 ms, and the session ended normally ('----')
1603
1604- haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/7/14/+30 200 +243 - - ---- 3/3 "GET /image.iso HTTP/1.0"
1605 => request for a long data transfer. The 'logasap' option was specified, so
1606 the log was produced just before transfering data. The server replied in
1607 14 ms, 243 bytes of headers were sent to the client, and total time from
1608 accept to first data byte is 30 ms.
1609
1610- haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17] relais-http Srv1 9/7/14/30 502 243 - - PH-- 2/3 "GET /cgi-bin/bug.cgi? HTTP/1.0"
1611 => the proxy blocked a server response either because of an 'rspdeny' or
1612 'rspideny' filter, or because it blocked sensible information which risked
1613 being cached. In this case, the response is replaced with a '502 bad
1614 gateway'.
1615
1616- haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55] relais-http <NOSRV> -1/-1/-1/8490 -1 0 - - CR-- 2/2 ""
1617 => the client never completed its request and aborted itself ('C---') after
1618 8.5s, while the proxy was waiting for the request headers ('-R--').
1619 Nothing was sent to the server.
1620
1621- haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06] relais-http <NOSRV> -1/-1/-1/50001 408 0 - - cR-- 2/2 ""
1622 => The client never completed its request, which was aborted by the time-out
1623 ('c---') after 50s, while the proxy was waiting for the request headers ('-R--').
1624 Nothing was sent to the server, but the proxy could send a 408 return code
1625 to the client.
willy tarreau4302f492005-12-18 01:00:37 +01001626
willy tarreauc5f73ed2005-12-18 01:26:38 +01001627- haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28] relais-tcp Srv1 0/5007 0 cD
1628 => This is a 'tcplog' entry. Client-side time-out ('c----') occured after 5s.
willy tarreau4302f492005-12-18 01:00:37 +01001629
willy tarreauc5f73ed2005-12-18 01:26:38 +01001630- haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31] relais-http Srv1 3183/-1/-1/11215 503 0 - - SC-- 202/205 "HEAD / HTTP/1.0"
1631 => The request took 3s to complete (probably a network problem), and the
1632 connection to the server failed ('SC--') after 4 attemps of 2 seconds
1633 (config says 'retries 3'), then a 503 error code was sent to the client.
1634 There were 202 connections on this proxy, and 205 on the global process.
1635 It is possible that the server refused the connection because of too many
1636 already established.
willy tarreau4302f492005-12-18 01:00:37 +01001637
willy tarreau4302f492005-12-18 01:00:37 +01001638
willy tarreau197e8ec2005-12-17 14:10:59 +010016394.3) HTTP header manipulation
1640-----------------------------
1641In HTTP mode, it is possible to rewrite, add or delete some of the request and
1642response headers based on regular expressions. It is also possible to block a
1643request or a response if a particular header matches a regular expression,
1644which is enough to stops most elementary protocol attacks, and to protect
1645against information leak from the internal network. But there is a limitation
1646to this : since haproxy's HTTP engine knows nothing about keep-alive, only
1647headers passed during the first request of a TCP session will be seen. All
1648subsequent headers will be considered data only and not analyzed. Furthermore,
1649haproxy doesn't touch data contents, it stops at the end of headers.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001650
willy tarreau197e8ec2005-12-17 14:10:59 +01001651The syntax is :
1652 reqadd <string> to add a header to the request
1653 reqrep <search> <replace> to modify the request
1654 reqirep <search> <replace> same, but ignoring the case
1655 reqdel <search> to delete a header in the request
1656 reqidel <search> same, but ignoring the case
1657 reqallow <search> definitely allow a request if a header matches <search>
1658 reqiallow <search> same, but ignoring the case
1659 reqdeny <search> denies a request if a header matches <search>
1660 reqideny <search> same, but ignoring the case
1661 reqpass <search> ignore a header matching <search>
1662 reqipass <search> same, but ignoring the case
willy tarreaueedaa9f2005-12-17 14:08:03 +01001663
willy tarreau197e8ec2005-12-17 14:10:59 +01001664 rspadd <string> to add a header to the response
1665 rsprep <search> <replace> to modify the response
1666 rspirep <search> <replace> same, but ignoring the case
1667 rspdel <search> to delete the response
1668 rspidel <search> same, but ignoring the case
willy tarreau982249e2005-12-18 00:57:06 +01001669 rspdeny <search> replaces a response with a HTTP 502 if a header matches <search>
1670 rspideny <search> same, but ignoring the case
willy tarreaueedaa9f2005-12-17 14:08:03 +01001671
1672
willy tarreau197e8ec2005-12-17 14:10:59 +01001673<search> is a POSIX regular expression (regex) which supports grouping through
1674parenthesis (without the backslash). Spaces and other delimiters must be
1675prefixed with a backslash ('\') to avoid confusion with a field delimiter.
1676Other characters may be prefixed with a backslash to change their meaning :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001677
willy tarreau197e8ec2005-12-17 14:10:59 +01001678 \t for a tab
1679 \r for a carriage return (CR)
1680 \n for a new line (LF)
1681 \ to mark a space and differentiate it from a delimiter
1682 \# to mark a sharp and differentiate it from a comment
1683 \\ to use a backslash in a regex
1684 \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy)
1685 \xXX to write the ASCII hex code XX as in the C language
willy tarreaueedaa9f2005-12-17 14:08:03 +01001686
1687
willy tarreau197e8ec2005-12-17 14:10:59 +01001688<replace> containst the string to be used to replace the largest portion of text
1689matching the regex. It can make use of the special characters above, and can
1690reference a substring delimited by parenthesis in the regex, by the group
1691numerical order from 1 to 9. In this case, you would write a backslah ('\')
1692immediately followed by one digit indicating the group position.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001693
willy tarreau197e8ec2005-12-17 14:10:59 +01001694<string> represents the string which will systematically be added after the last
1695header line. It can also use special characters above.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001696
willy tarreau197e8ec2005-12-17 14:10:59 +01001697Notes :
1698-------
1699 - the first line is considered as a header, which makes it possible to rewrite
1700 or filter HTTP requests URIs or response codes.
1701 - 'reqrep' is the equivalent of 'cliexp' in version 1.0, and 'rsprep' is the
1702 equivalent of 'srvexp' in 1.0. Those names are still supported but
1703 deprecated.
1704 - for performances reasons, the number of characters added to a request or to
1705 a response is limited to 4096 since version 1.1.5 (it was 256 before). This
1706 value is easy to modify in the code if needed (#define). If it is too short
1707 on occasional uses, it is possible to gain some space by removing some
1708 useless headers before adding new ones.
willy tarreau982249e2005-12-18 00:57:06 +01001709 - a denied request will generate an "HTTP 403 forbidden" response, while a
1710 denied response will generate an "HTTP 502 Bad gateway" response.
1711
willy tarreaueedaa9f2005-12-17 14:08:03 +01001712
willy tarreau197e8ec2005-12-17 14:10:59 +01001713Examples :
1714----------
willy tarreauc5f73ed2005-12-18 01:26:38 +01001715 ###### a few examples ######
willy tarreau197e8ec2005-12-17 14:10:59 +01001716
willy tarreauc5f73ed2005-12-18 01:26:38 +01001717 # rewrite 'online.fr' instead of 'free.fr' for GET and POST requests
1718 reqrep ^(GET\ .*)(.free.fr)(.*) \1.online.fr\3
1719 reqrep ^(POST\ .*)(.free.fr)(.*) \1.online.fr\3
willy tarreau197e8ec2005-12-17 14:10:59 +01001720
willy tarreauc5f73ed2005-12-18 01:26:38 +01001721 # force proxy connections to close
1722 reqirep ^Proxy-Connection:.* Proxy-Connection:\ close
1723 # rewrite locations
1724 rspirep ^(Location:\ )([^:]*://[^/]*)(.*) \1\3
willy tarreaueedaa9f2005-12-17 14:08:03 +01001725
willy tarreauc5f73ed2005-12-18 01:26:38 +01001726 ###### A full configuration being used on production ######
willy tarreaueedaa9f2005-12-17 14:08:03 +01001727
willy tarreau197e8ec2005-12-17 14:10:59 +01001728 # Every header should end with a colon followed by one space.
willy tarreauc5f73ed2005-12-18 01:26:38 +01001729 reqideny ^[^:\ ]*[\ ]*$
willy tarreaueedaa9f2005-12-17 14:08:03 +01001730
willy tarreau197e8ec2005-12-17 14:10:59 +01001731 # block Apache chunk exploit
willy tarreauc5f73ed2005-12-18 01:26:38 +01001732 reqideny ^Transfer-Encoding:[\ ]*chunked
1733 reqideny ^Host:\ apache-
willy tarreaueedaa9f2005-12-17 14:08:03 +01001734
willy tarreau197e8ec2005-12-17 14:10:59 +01001735 # block annoying worms that fill the logs...
willy tarreauc5f73ed2005-12-18 01:26:38 +01001736 reqideny ^[^:\ ]*\ .*(\.|%2e)(\.|%2e)(%2f|%5c|/|\\\\)
1737 reqideny ^[^:\ ]*\ ([^\ ]*\ [^\ ]*\ |.*%00)
1738 reqideny ^[^:\ ]*\ .*<script
1739 reqideny ^[^:\ ]*\ .*/(root\.exe\?|cmd\.exe\?|default\.ida\?)
willy tarreau197e8ec2005-12-17 14:10:59 +01001740
1741 # allow other syntactically valid requests, and block any other method
willy tarreauc5f73ed2005-12-18 01:26:38 +01001742 reqipass ^(GET|POST|HEAD|OPTIONS)\ /.*\ HTTP/1\.[01]$
1743 reqipass ^OPTIONS\ \\*\ HTTP/1\.[01]$
1744 reqideny ^[^:\ ]*\
willy tarreau197e8ec2005-12-17 14:10:59 +01001745
1746 # force connection:close, thus disabling HTTP keep-alive
willy tarreauc5f73ed2005-12-18 01:26:38 +01001747 option httpclose
willy tarreau197e8ec2005-12-17 14:10:59 +01001748
willy tarreauc5f73ed2005-12-18 01:26:38 +01001749 # change the server name
1750 rspidel ^Server:\
1751 rspadd Server:\ Formilux/0.1.8
willy tarreau197e8ec2005-12-17 14:10:59 +01001752
1753
willy tarreau982249e2005-12-18 00:57:06 +01001754Also, the 'forwardfor' option creates an HTTP 'X-Forwarded-For' header which
willy tarreauc1cae632005-12-17 14:12:23 +01001755contains the client's IP address. This is useful to let the final web server
1756know what the client address was (eg for statistics on domains).
1757
willy tarreau982249e2005-12-18 00:57:06 +01001758Last, the 'httpclose' option removes any 'Connection' header both ways, and
1759adds a 'Connection: close' header in each direction. This makes it easier to
Willy TARREAU767ba712006-03-01 22:40:50 +01001760disable HTTP keep-alive than the previous 4-rules block.
willy tarreau982249e2005-12-18 00:57:06 +01001761
willy tarreauc1cae632005-12-17 14:12:23 +01001762Example :
1763---------
1764 listen http_proxy 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001765 mode http
1766 log global
1767 option httplog
1768 option dontlognull
1769 option forwardfor
1770 option httpclose
1771
Willy TARREAU767ba712006-03-01 22:40:50 +01001772Note that some HTTP servers do not necessarily close the connections when they
1773receive the 'Connection: close', and if the client does not close either, then
1774the connection will be maintained up to the time-out. This translates into high
1775number of simultaneous sessions and high global session times in the logs. To
1776workaround this, a new option 'forceclose' appeared in version 1.2.9 to enforce
1777the closing of the outgoing server channel as soon as the server begins to
1778reply and only if the request buffer is empty. Note that this should NOT be
1779used if CONNECT requests are expected between the client and the server. The
1780'forceclose' option implies the 'httpclose' option.
1781
1782Example :
1783---------
1784 listen http_proxy 0.0.0.0:80
1785 mode http
1786 log global
1787 option httplog
1788 option dontlognull
1789 option forwardfor
1790 option forceclose
1791
willy tarreau197e8ec2005-12-17 14:10:59 +01001792
17934.4) Load balancing with persistence
1794------------------------------------
willy tarreau197e8ec2005-12-17 14:10:59 +01001795Combining cookie insertion with internal load balancing allows to transparently
1796bring persistence to applications. The principle is quite simple :
1797 - assign a cookie value to each server
1798 - enable the load balancing between servers
1799 - insert a cookie into responses resulting from the balancing algorithm
1800 (indirect accesses), end ensure that no upstream proxy will cache it.
1801 - remove the cookie in the request headers so that the application never sees
1802 it.
1803
1804Example :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001805---------
1806 listen application 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001807 mode http
1808 cookie SERVERID insert nocache indirect
1809 balance roundrobin
1810 server srv1 192.168.1.1:80 cookie server01 check
1811 server srv2 192.168.1.2:80 cookie server02 check
willy tarreaueedaa9f2005-12-17 14:08:03 +01001812
willy tarreau0174f312005-12-18 01:02:42 +01001813The other solution brought by versions 1.1.30 and 1.2.3 is to reuse a cookie
1814from the server, and prefix the server's name to it. In this case, don't forget
1815to force "httpclose" mode so that you can be assured that every subsequent
1816request will have its cookie fixed.
1817
1818 listen application 0.0.0.0:80
willy tarreauc5f73ed2005-12-18 01:26:38 +01001819 mode http
1820 cookie JSESSIONID prefix
1821 balance roundrobin
1822 server srv1 192.168.1.1:80 cookie srv1 check
1823 server srv2 192.168.1.2:80 cookie srv2 check
1824 option httpclose
willy tarreau0174f312005-12-18 01:02:42 +01001825
1826
willy tarreau982249e2005-12-18 00:57:06 +010018274.5) Protection against information leak from the servers
1828---------------------------------------------------------
1829In versions 1.1.28/1.2.1, a new option 'checkcache' was created. It carefully
1830checks 'Cache-control', 'Pragma' and 'Set-cookie' headers in server response
1831to check if there's a risk of caching a cookie on a client-side proxy. When this
1832option is enabled, the only responses which can be delivered to the client are :
1833 - all those without 'Set-Cookie' header ;
1834 - all those with a return code other than 200, 203, 206, 300, 301, 410,
1835 provided that the server has not set a 'Cache-control: public' header ;
1836 - all those that come from a POST request, provided that the server has not
1837 set a 'Cache-Control: public' header ;
1838 - those with a 'Pragma: no-cache' header
1839 - those with a 'Cache-control: private' header
1840 - those with a 'Cache-control: no-store' header
1841 - those with a 'Cache-control: max-age=0' header
1842 - those with a 'Cache-control: s-maxage=0' header
1843 - those with a 'Cache-control: no-cache' header
1844 - those with a 'Cache-control: no-cache="set-cookie"' header
1845 - those with a 'Cache-control: no-cache="set-cookie,' header
1846 (allowing other fields after set-cookie)
willy tarreaueedaa9f2005-12-17 14:08:03 +01001847
willy tarreau982249e2005-12-18 00:57:06 +01001848If a response doesn't respect these requirements, then it will be blocked just
1849as if it was from an 'rspdeny' filter, with an "HTTP 502 bad gateway". The
1850session state shows "PH--" meaning that the proxy blocked the response during
1851headers processing. Additionnaly, an alert will be sent in the logs so that
1852admins are told that there's something to be done.
1853
willy tarreauc5f73ed2005-12-18 01:26:38 +01001854
willy tarreau982249e2005-12-18 00:57:06 +010018554.6) Customizing errors
1856-----------------------
willy tarreau197e8ec2005-12-17 14:10:59 +01001857Some situations can make haproxy return an HTTP error code to the client :
1858 - invalid or too long request => HTTP 400
1859 - request not completely sent in time => HTTP 408
1860 - forbidden request (matches a deny filter) => HTTP 403
1861 - internal error in haproxy => HTTP 500
1862 - the server returned an invalid or incomplete response => HTTP 502
1863 - no server was available to handle the request => HTTP 503
1864 - the server failed to reply in time => HTTP 504
willy tarreaueedaa9f2005-12-17 14:08:03 +01001865
willy tarreau197e8ec2005-12-17 14:10:59 +01001866A succint error message taken from the RFC accompanies these return codes.
1867But depending on the clients knowledge, it may be better to return custom, user
1868friendly, error pages. This is made possible through the use of the 'errorloc'
1869command :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001870
willy tarreau197e8ec2005-12-17 14:10:59 +01001871 errorloc <HTTP_code> <location>
willy tarreaueedaa9f2005-12-17 14:08:03 +01001872
willy tarreau197e8ec2005-12-17 14:10:59 +01001873Instead of generating an HTTP error <HTTP_code> among those above, the proxy
1874will return a temporary redirection code (HTTP 302) towards the address
1875specified in <location>. This address may be either relative to the site or
1876absolute. Since this request will be handled by the client's browser, it's
1877mandatory that the returned address be reachable from the outside.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001878
willy tarreau197e8ec2005-12-17 14:10:59 +01001879Example :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001880---------
1881 listen application 0.0.0.0:80
1882 errorloc 400 /badrequest.html
1883 errorloc 403 /forbidden.html
1884 errorloc 408 /toolong.html
willy tarreauc5f73ed2005-12-18 01:26:38 +01001885 errorloc 500 http://haproxy.domain.net/bugreport.html
willy tarreaueedaa9f2005-12-17 14:08:03 +01001886 errorloc 502 http://192.168.114.58/error50x.html
1887 errorloc 503 http://192.168.114.58/error50x.html
1888 errorloc 504 http://192.168.114.58/error50x.html
1889
willy tarreauc1f47532005-12-18 01:08:26 +01001890Note: RFC2616 says that a client must reuse the same method to fetch the
1891Location returned by a 302, which causes problems with the POST method.
1892The return code 303 was designed explicitly to force the client to fetch the
1893Location URL with the GET method, but there are some browsers pre-dating
1894HTTP/1.1 which don't support it. Anyway, most browsers still behave with 302 as
willy tarreauc5f73ed2005-12-18 01:26:38 +01001895if it was a 303. In order to allow the user to chose, versions 1.1.31 and 1.2.5
1896bring two new keywords to replace 'errorloc' : 'errorloc302' and 'errorloc303'.
willy tarreauc1f47532005-12-18 01:08:26 +01001897
1898They are preffered over errorloc (which still does 302). Consider using
1899errorloc303 everytime you know that your clients support HTTP 303 responses..
1900
1901
willy tarreau982249e2005-12-18 00:57:06 +010019024.7) Modifying default values
willy tarreau197e8ec2005-12-17 14:10:59 +01001903-----------------------------
willy tarreau197e8ec2005-12-17 14:10:59 +01001904Version 1.1.22 introduced the notion of default values, which eliminates the
1905pain of often repeating common parameters between many instances, such as
1906logs, timeouts, modes, etc...
willy tarreaueedaa9f2005-12-17 14:08:03 +01001907
willy tarreau197e8ec2005-12-17 14:10:59 +01001908Default values are set in a 'defaults' section. Each of these section clears
1909all previously set default parameters, so there may be as many default
1910parameters as needed. Only the last one before a 'listen' section will be
1911used for this section. The 'defaults' section uses the same syntax as the
1912'listen' section, for the supported parameters. The 'defaults' keyword ignores
1913everything on its command line, so that fake instance names can be specified
1914there for better clarity.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001915
willy tarreau982249e2005-12-18 00:57:06 +01001916In version 1.1.28/1.2.1, only those parameters can be preset in the 'default'
willy tarreau197e8ec2005-12-17 14:10:59 +01001917section :
1918 - log (the first and second one)
willy tarreaueedaa9f2005-12-17 14:08:03 +01001919 - mode { tcp, http, health }
1920 - balance { roundrobin }
willy tarreau197e8ec2005-12-17 14:10:59 +01001921 - disabled (to disable every further instances)
1922 - enabled (to enable every further instances, this is the default)
willy tarreaueedaa9f2005-12-17 14:08:03 +01001923 - contimeout, clitimeout, srvtimeout, grace, retries, maxconn
willy tarreau982249e2005-12-18 00:57:06 +01001924 - option { redispatch, transparent, keepalive, forwardfor, logasap, httpclose,
1925 checkcache, httplog, tcplog, dontlognull, persist, httpchk }
willy tarreaueedaa9f2005-12-17 14:08:03 +01001926 - redispatch, redisp, transparent, source { addr:port }
1927 - cookie, capture
1928 - errorloc
1929
willy tarreau197e8ec2005-12-17 14:10:59 +01001930As of 1.1.24, it is not possible to put certain parameters in a 'defaults'
1931section, mainly regular expressions and server configurations :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001932 - dispatch, server,
willy tarreau197e8ec2005-12-17 14:10:59 +01001933 - req*, rsp*
willy tarreaueedaa9f2005-12-17 14:08:03 +01001934
willy tarreau197e8ec2005-12-17 14:10:59 +01001935Last, there's no way yet to change a boolean option from its assigned default
1936value. So if an 'option' statement is set in a 'defaults' section, the only
1937way to flush it is to redefine a new 'defaults' section without this 'option'.
willy tarreaueedaa9f2005-12-17 14:08:03 +01001938
willy tarreau197e8ec2005-12-17 14:10:59 +01001939Examples :
willy tarreaueedaa9f2005-12-17 14:08:03 +01001940----------
1941 defaults applications TCP
willy tarreauc5f73ed2005-12-18 01:26:38 +01001942 log global
1943 mode tcp
1944 balance roundrobin
1945 clitimeout 180000
1946 srvtimeout 180000
1947 contimeout 4000
1948 retries 3
1949 redispatch
willy tarreaueedaa9f2005-12-17 14:08:03 +01001950
1951 listen app_tcp1 10.0.0.1:6000-6063
willy tarreauc5f73ed2005-12-18 01:26:38 +01001952 server srv1 192.168.1.1 check port 6000 inter 10000
1953 server srv2 192.168.1.2 backup
willy tarreaueedaa9f2005-12-17 14:08:03 +01001954
1955 listen app_tcp2 10.0.0.2:6000-6063
willy tarreauc5f73ed2005-12-18 01:26:38 +01001956 server srv1 192.168.2.1 check port 6000 inter 10000
1957 server srv2 192.168.2.2 backup
willy tarreaueedaa9f2005-12-17 14:08:03 +01001958
1959 defaults applications HTTP
willy tarreauc5f73ed2005-12-18 01:26:38 +01001960 log global
1961 mode http
1962 option httplog
1963 option forwardfor
1964 option dontlognull
1965 balance roundrobin
1966 clitimeout 20000
1967 srvtimeout 20000
1968 contimeout 4000
1969 retries 3
willy tarreaueedaa9f2005-12-17 14:08:03 +01001970
1971 listen app_http1 10.0.0.1:80-81
willy tarreauc5f73ed2005-12-18 01:26:38 +01001972 cookie SERVERID postonly insert indirect
1973 capture cookie userid= len 10
1974 server srv1 192.168.1.1:+8000 cookie srv1 check port 8080 inter 1000
1975 server srv1 192.168.1.2:+8000 cookie srv2 check port 8080 inter 1000
willy tarreaueedaa9f2005-12-17 14:08:03 +01001976
1977 defaults
willy tarreauc5f73ed2005-12-18 01:26:38 +01001978 # this empty section voids all default parameters
willy tarreaueedaa9f2005-12-17 14:08:03 +01001979
willy tarreau197e8ec2005-12-17 14:10:59 +01001980=========================
1981| System-specific setup |
1982=========================
willy tarreaueedaa9f2005-12-17 14:08:03 +01001983
willy tarreau197e8ec2005-12-17 14:10:59 +01001984Linux 2.4
1985=========
willy tarreaueedaa9f2005-12-17 14:08:03 +01001986
1987-- cut here --
1988#!/bin/sh
1989# set this to about 256/4M (16384 for 256M machine)
1990MAXFILES=16384
1991echo $MAXFILES > /proc/sys/fs/file-max
1992ulimit -n $MAXFILES
1993
1994if [ -e /proc/sys/net/ipv4/ip_conntrack_max ]; then
willy tarreauc5f73ed2005-12-18 01:26:38 +01001995 echo 65536 > /proc/sys/net/ipv4/ip_conntrack_max
willy tarreaueedaa9f2005-12-17 14:08:03 +01001996fi
1997
1998if [ -e /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_fin_wait ]; then
willy tarreauc5f73ed2005-12-18 01:26:38 +01001999 # 30 seconds for fin, 15 for time wait
2000 echo 3000 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_fin_wait
2001 echo 1500 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_timeout_time_wait
2002 echo 0 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_log_invalid_scale
2003 echo 0 > /proc/sys/net/ipv4/netfilter/ip_ct_tcp_log_out_of_window
willy tarreaueedaa9f2005-12-17 14:08:03 +01002004fi
2005
2006echo 1024 60999 > /proc/sys/net/ipv4/ip_local_port_range
2007echo 30 > /proc/sys/net/ipv4/tcp_fin_timeout
2008echo 4096 > /proc/sys/net/ipv4/tcp_max_syn_backlog
2009echo 262144 > /proc/sys/net/ipv4/tcp_max_tw_buckets
2010echo 262144 > /proc/sys/net/ipv4/tcp_max_orphans
2011echo 300 > /proc/sys/net/ipv4/tcp_keepalive_time
2012echo 1 > /proc/sys/net/ipv4/tcp_tw_recycle
2013echo 0 > /proc/sys/net/ipv4/tcp_timestamps
2014echo 0 > /proc/sys/net/ipv4/tcp_ecn
willy tarreauc5f73ed2005-12-18 01:26:38 +01002015echo 1 > /proc/sys/net/ipv4/tcp_sack
willy tarreaueedaa9f2005-12-17 14:08:03 +01002016echo 0 > /proc/sys/net/ipv4/tcp_dsack
2017
2018# auto-tuned on 2.4
2019#echo 262143 > /proc/sys/net/core/rmem_max
2020#echo 262143 > /proc/sys/net/core/rmem_default
2021
2022echo 16384 65536 524288 > /proc/sys/net/ipv4/tcp_rmem
2023echo 16384 349520 699040 > /proc/sys/net/ipv4/tcp_wmem
2024
2025-- cut here --
2026
willy tarreau197e8ec2005-12-17 14:10:59 +01002027
2028FreeBSD
2029=======
2030
2031A FreeBSD port of HA-Proxy is now available and maintained, thanks to
2032Clement Laforet <sheepkiller@cultdeadsheep.org>.
2033
2034For more information :
2035http://www.freebsd.org/cgi/url.cgi?ports/net/haproxy/pkg-descr
2036http://www.freebsd.org/cgi/cvsweb.cgi/ports/net/haproxy/
2037http://www.freshports.org/net/haproxy
2038
2039
2040-- end --