« back to all changes in this revision
Viewing changes to doc/configuration.txt
- browse files at revision 1.1.7
- compare with another revision
- download diff
- download tarball
- view history from revision 1.1.7
- Committer: Bazaar Package Importer
- Author(s): Arnaud Cornet
- Date: 2009-10-19 22:31:45 UTC
- mfrom: (1.2.5 upstream)
- mto: This revision was merged to the branch mainline in revision 10.
- Revision ID: james.westby@ubuntu.com-20091019223145-rymupk5njs544bvp
Import upstream version 1.3.22
- files added:
- include/proto/port_range.h
- files modified:
- CHANGELOG
added
removed
doc/configuration.txt
2
2
HAProxy
3
3
Configuration Manual
4
4
----------------------
5
version 1.3.18
5
version 1.3.22
6
6
willy tarreau
7
2009/05/10
7
2009/10/14
8
8
9
9
10
10
This document covers the configuration language as implemented in the version
259
259
2 Content-length: 350
260
260
3 Content-Type: text/html
261
261
262
As a special case, HTTP supports so called "Informational responses" as status
263
codes 1xx. These messages are special in that they don't convey any part of the
264
response, they're just used as sort of a signaling message to ask a client to
265
continue to post its request for instance. The requested information will be
266
carried by the next non-1xx response message following the informational one.
267
This implies that multiple responses may be sent to a single request, and that
268
this only works when keep-alive is enabled (1xx messages are HTTP/1.1 only).
269
HAProxy handles these messages and is able to correctly forward and skip them,
270
and only process the next non-1xx response. As such, these messages are neither
271
logged nor transformed, unless explicitly state otherwise.
272
262
273
263
274
1.3.1. The Response line
264
275
------------------------
270
281
- a reason : OK
271
282
272
283
The status code is always 3-digit. The first digit indicates a general status :
284
- 1xx = informational message to be skipped (eg: 100, 101)
273
285
- 2xx = OK, content is following (eg: 200, 206)
274
286
- 3xx = OK, no content following (eg: 302, 304)
275
287
- 4xx = error caused by the client (eg: 401, 403, 404)
371
383
- ulimit-n
372
384
- user
373
385
- stats
386
- node
387
- description
374
388
375
389
* Performance tuning
376
390
- maxconn
500
514
Similar to "uid" but uses the UID of user name <user name> from /etc/passwd.
501
515
See also "uid" and "group".
502
516
517
node <name>
518
Only letters, digits, hyphen and underscore are allowed, like in DNS names.
519
520
This statement is useful in HA configurations where two or more processes or
521
servers share the same IP address. By setting a different node-name on all
522
nodes, it becomes easy to immediately spot what server is handling the
523
traffic.
524
525
description <text>
526
Add a text that describes the instance.
527
528
Please note that it is required to escape certain characters (# for example)
529
and this text is inserted into a html page so you should avoid using
530
"<" and ">" characters.
531
503
532
504
533
3.2. Performance tuning
505
534
-----------------------
658
687
contimeout X - X X (deprecated)
659
688
cookie X - X X
660
689
default_backend - X X -
690
description - X X X
661
691
disabled X X X X
662
692
dispatch - - X X
663
693
enabled X X X X
691
721
[no] option httpclose X X X X
692
722
option httplog X X X X
693
723
[no] option http_proxy X X X X
724
[no] option independant-
725
streams X X X X
694
726
[no] option log-separate-
695
727
errors X X X -
696
728
[no] option logasap X X X -
2370
2402
See also : "option httpclose"
2371
2403
2372
2404
2405
option independant-streams
2406
no option independant-streams
2407
Enable or disable independant timeout processing for both directions
2408
May be used in sections : defaults | frontend | listen | backend
2409
yes | yes | yes | yes
2410
Arguments : none
2411
2412
By default, when data is sent over a socket, both the write timeout and the
2413
read timeout for that socket are refreshed, because we consider that there is
2414
activity on that socket, and we have no other means of guessing if we should
2415
receive data or not.
2416
2417
While this default behaviour is desirable for almost all applications, there
2418
exists a situation where it is desirable to disable it, and only refresh the
2419
read timeout if there are incoming data. This happens on sessions with large
2420
timeouts and low amounts of exchanged data such as telnet session. If the
2421
server suddenly disappears, the output data accumulates in the system's
2422
socket buffers, both timeouts are correctly refreshed, and there is no way
2423
to know the server does not receive them, so we don't timeout. However, when
2424
the underlying protocol always echoes sent data, it would be enough by itself
2425
to detect the issue using the read timeout. Note that this problem does not
2426
happen with more verbose protocols because data won't accumulate long in the
2427
socket buffers.
2428
2429
When this option is set on the frontend, it will disable read timeout updates
2430
on data sent to the client. There probably is little use of this case. When
2431
the option is set on the backend, it will disable read timeout updates on
2432
data sent to the server. Doing so will typically break large HTTP posts from
2433
slow lines, so use it with caution.
2434
2435
See also : "timeout client" and "timeout server"
2436
2437
2373
2438
option log-separate-errors
2374
2439
no option log-separate-errors
2375
2440
Change log level for non-completely successful connections
3397
3462
3398
3463
<port> is an optional port. It is normally not needed but may be useful
3399
3464
in some very specific contexts. The default value of zero means
3400
the system will select a free port.
3465
the system will select a free port. Note that port ranges are not
3466
supported in the backend. If you want to force port ranges, you
3467
have to specify them on each "server" line.
3401
3468
3402
3469
<addr2> is the IP address to present to the server when connections are
3403
3470
forwarded in full transparent proxy mode. This is currently only
3616
3683
See also : "stats auth", "stats realm", "stats uri"
3617
3684
3618
3685
3686
stats show-node [ <name> ]
3687
Enable reporting of a host name on the statistics page.
3688
May be used in sections : defaults | frontend | listen | backend
3689
yes | no | yes | yes
3690
Arguments:
3691
<name> is an optional name to be reported. If unspecified, the
3692
node name from global section is automatically used instead.
3693
3694
This statement is useful for users that offer shared services to their
3695
customers, where node or description might be different on a stats page
3696
provided for each customer.
3697
3698
Though this statement alone is enough to enable statistics reporting, it is
3699
recommended to set all other settings in order to avoid relying on default
3700
unobvious parameters.
3701
3702
Example:
3703
# internal monitoring access (unlimited)
3704
backend private_monitoring
3705
stats enable
3706
stats show-node Europe-1
3707
stats uri /admin?stats
3708
stats refresh 5s
3709
3710
See also: "show-desc", "stats enable", "stats uri", and "node" in global section.
3711
3712
3713
stats show-desc [ <description> ]
3714
Enable reporting of a description on the statistics page.
3715
May be used in sections : defaults | frontend | listen | backend
3716
yes | no | yes | yes
3717
3718
<name> is an optional description to be reported. If unspecified, the
3719
description from global section is automatically used instead.
3720
3721
This statement is useful for users that offer shared services to their
3722
customers, where node or description should be different for each customer.
3723
3724
Though this statement alone is enough to enable statistics reporting, it is
3725
recommended to set all other settings in order to avoid relying on default
3726
unobvious parameters.
3727
3728
Example :
3729
# internal monitoring access (unlimited)
3730
backend private_monitoring
3731
stats enable
3732
stats show-desc Master node for Europe, Asia, Africa
3733
stats uri /admin?stats
3734
stats refresh 5s
3735
3736
See also: "show-node", "stats enable", "stats uri" and "description" in global section.
3737
3738
3619
3739
stats realm <realm>
3620
3740
Enable statistics and set authentication realm
3621
3741
May be used in sections : defaults | frontend | listen | backend
4372
4492
trouble to running servers. It only applies when a server has been previously
4373
4493
seen as failed.
4374
4494
4375
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]
4376
source <addr>[:<port>] [interface <name>] ...
4495
source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ]
4496
source <addr>[:<pl>[-<ph>]] [interface <name>] ...
4377
4497
The "source" parameter sets the source address which will be used when
4378
4498
connecting to the server. It follows the exact same parameters and principle
4379
4499
as the backend "source" keyword, except that it only applies to the server
4380
4500
referencing it. Please consult the "source" keyword for details.
4381
4501
4502
Additionally, the "source" statement on a server line allows one to specify a
4503
source port range by indicating the lower and higher bounds delimited by a
4504
dash ('-'). Some operating systems might require a valid IP address when a
4505
source port range is specified. It is permitted to have the same IP/range for
4506
several servers. Doing so makes it possible to bypass the maximum of 64k
4507
total concurrent connections. The limit will then reach 64k connections per
4508
server.
4509
4382
4510
track [<proxy>/]<server>
4383
4511
This option enables ability to set the current state of the server by
4384
4512
tracking another one. Only a server with checks enabled can be tracked
4390
4518
The "weight" parameter is used to adjust the server's weight relative to
4391
4519
other servers. All servers will receive a load proportional to their weight
4392
4520
relative to the sum of all weights, so the higher the weight, the higher the
4393
load. The default weight is 1, and the maximal value is 255. If this
4394
parameter is used to distribute the load according to server's capacity, it
4395
is recommended to start with values which can both grow and shrink, for
4396
instance between 10 and 100 to leave enough room above and below for later
4397
adjustments.
4521
load. The default weight is 1, and the maximal value is 256. A value of 0
4522
means the server will not participate in load-balancing but will still accept
4523
persistent connections. If this parameter is used to distribute the load
4524
according to server's capacity, it is recommended to start with values which
4525
can both grow and shrink, for instance between 10 and 100 to leave enough
4526
room above and below for later adjustments.
4398
4527
4399
4528
4400
4529
6. HTTP header manipulation
4410
4539
headers will be considered data only and not analyzed. Furthermore, HAProxy
4411
4540
never touches data contents, it stops analysis at the end of headers.
4412
4541
4542
There is an exception though. If HAProxy encounters an "Informational Response"
4543
(status code 1xx), it is able to process all rsp* rules which can allow, deny,
4544
rewrite or delete a header, but it will refuse to add a header to any such
4545
messages as this is not HTTP-compliant. The reason for still processing headers
4546
in such responses is to stop and/or fix any possible information leak which may
4547
happen, for instance because another downstream equipment would inconditionally
4548
add a header, or if a server name appears there. When such messages are seen,
4549
normal processing still occurs on the next non-informational messages.
4550
4413
4551
This section covers common usage of the following keywords, described in detail
4414
4552
in section 4.2 :
4415
4553
4646
4784
to a different backend for some alternative ports.
4647
4785
4648
4786
dst_conn <integer>
4649
Applies to the number of currently established connections on the frontend,
4787
Applies to the number of currently established connections on the same socket
4650
4788
including the one being evaluated. It can be used to either return a sorry
4651
4789
page before hard-blocking, or to use a specific backend to drain new requests
4652
when the farm is considered saturated.
4790
when the socket is considered saturated. This offers the ability to assign
4791
different limits to different listening ports or addresses. See also the
4792
"fe_conn" and "be_conn" criteria.
4793
4794
fe_conn <integer>
4795
fe_conn(frontend) <integer>
4796
Applies to the number of currently established connections on the frontend,
4797
possibly including the connection being evaluated. If no frontend name is
4798
specified, the current one is used. But it is also possible to check another
4799
frontend. It can be used to either return a sorry page before hard-blocking,
4800
or to use a specific backend to drain new requests when the farm is
4801
considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate"
4802
criteria.
4803
4804
be_conn <integer>
4805
be_conn(frontend) <integer>
4806
Applies to the number of currently established connections on the backend,
4807
possibly including the connection being evaluated. If no backend name is
4808
specified, the current one is used. But it is also possible to check another
4809
backend. It can be used to use a specific farm when the nominal one is full.
4810
See also the "fe_conn", "queue" and "be_sess_rate" criteria.
4653
4811
4654
4812
nbsrv <integer>
4655
4813
nbsrv(backend) <integer>
4668
4826
'connslots' = number of available server connection slots, + number of
4669
4827
available server queue slots.
4670
4828
4671
Note that while "dst_conn" may be used, "connslots" comes in especially
4829
Note that while "fe_conn" may be used, "connslots" comes in especially
4672
4830
useful when you have a case of traffic going to one single ip, splitting into
4673
4831
multiple backends (perhaps using acls to do name-based load balancing) and
4674
4832
you want to be able to differentiate between different backends, and their
4675
4833
available "connslots". Also, whereas "nbsrv" only measures servers that are
4676
4834
actually *down*, this acl is more fine-grained and looks into the number of
4677
available connection slots as well.
4835
available connection slots as well. See also "queue" and "avg_queue".
4678
4836
4679
4837
OTHER CAVEATS AND NOTES: at this point in time, the code does not take care
4680
4838
of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0,
4681
4839
then this acl clearly does not make sense, in which case the value returned
4682
4840
will be -1.
4683
4841
4842
queue <integer>
4843
queue(frontend) <integer>
4844
Returns the total number of queued connections of the designated backend,
4845
including all the connections in server queues. If no backend name is
4846
specified, the current one is used, but it is also possible to check another
4847
one. This can be used to take actions when queuing goes above a known level,
4848
generally indicating a surge of traffic or a massive slowdown on the servers.
4849
One possible action could be to reject new users but still accept old ones.
4850
See also the "avg_queue", "be_conn", and "be_sess_rate" criteria.
4851
4852
avg_queue <integer>
4853
avg_queue(frontend) <integer>
4854
Returns the total number of queued connections of the designated backend
4855
divided by the number of active servers. This is very similar to "queue"
4856
except that the size of the farm is considered, in order to give a more
4857
accurate measurement of the time it may take for a new connection to be
4858
processed. The main usage is to return a sorry page to new users when it
4859
becomes certain they will get a degraded service. Note that in the event
4860
there would not be any active server anymore, we would consider twice the
4861
number of queued connections as the measured value. This is a fair estimate,
4862
as we expect one server to get back soon anyway, but we still prefer to send
4863
new traffic to another backend if in better shape. See also the "queue",
4864
"be_conn", and "be_sess_rate" criteria.
4865
4684
4866
fe_sess_rate <integer>
4685
4867
fe_sess_rate(frontend) <integer>
4686
4868
Returns true when the session creation rate on the current or the named
4928
5110
request smugling attacks by rejecting requests which contain more than one
4929
5111
of certain headers. See "hdr" for more information on header matching.
4930
5112
5113
hdr_ip <ip_address>
5114
hdr_ip(header) <ip_address>
5115
Returns true when one of the headers' values contains an IP address matching
5116
<ip_address>. This is mainly used with headers such as X-Forwarded-For or
5117
X-Client-IP. See "hdr" for more information on header matching.
5118
4931
5119
4932
5120
7.6. Pre-defined ACLs
4933
5121
---------------------
6214
6402
30. lbtot: total number of times a server was selected
6215
6403
31. tracked: id of proxy/server if tracking is enabled
6216
6404
32. type (0=frontend, 1=backend, 2=server)
6217
33. rate (number of sessions per second over last elapsed second)
6405
33. rate: number of sessions per second over last elapsed second
6406
34. rate_lim: limit on new sessions per second
6407
35. rate_max: max number of new sessions per second
6218
6408
6219
6409
6220
6410
9.2. Unix Socket commands
Loggerhead is a web-based interface for Breezy
Version: 2.0.1