mirror of
https://git.haproxy.org/git/haproxy.git/
synced 2025-11-28 14:21:00 +01:00
[DOC] large update to the configuration manual
Keywords from "errorloc" to "monitor-uri" inclusive have been added. Some fixes applied too.
This commit is contained in:
Willy Tarreau
parent
336d475d13
commit
2769aa050a
@ -2,9 +2,9 @@
|
|||||||
HAProxy
|
HAProxy
|
||||||
Configuration Manual
|
Configuration Manual
|
||||||
----------------------
|
----------------------
|
||||||
version 1.3.14
|
version 1.3.14.2
|
||||||
willy tarreau
|
willy tarreau
|
||||||
2007/12/24
|
2007/12/27
|
||||||
|
|
||||||
|
|
||||||
This document covers the configuration language as implemented in the version
|
This document covers the configuration language as implemented in the version
|
||||||
@ -108,7 +108,7 @@ log <address> <facility> [max level]
|
|||||||
|
|
||||||
<address> can be one of:
|
<address> can be one of:
|
||||||
|
|
||||||
- An IPv4 address optionally followed by a colon and an UDP port. If
|
- An IPv4 address optionally followed by a colon and a UDP port. If
|
||||||
no port is specified, 514 is used by default (the standard syslog
|
no port is specified, 514 is used by default (the standard syslog
|
||||||
port).
|
port).
|
||||||
|
|
||||||
@ -1064,6 +1064,8 @@ default_backend <backend>
|
|||||||
use_backend static if url_css url_img extension_img
|
use_backend static if url_css url_img extension_img
|
||||||
default_backend dynamic
|
default_backend dynamic
|
||||||
|
|
||||||
|
See also : "use_backend", "reqsetbe", "reqisetbe"
|
||||||
|
|
||||||
|
|
||||||
disabled
|
disabled
|
||||||
Disable a proxy, frontend or backend.
|
Disable a proxy, frontend or backend.
|
||||||
@ -1125,11 +1127,116 @@ errorfile <code> <file>
|
|||||||
See also : "errorloc", "errorloc302", "errorloc303"
|
See also : "errorloc", "errorloc302", "errorloc303"
|
||||||
|
|
||||||
|
|
||||||
|
errorloc <code> <url>
|
||||||
|
errorloc302 <code> <url>
|
||||||
|
Return an HTTP redirection to a URL instead of errors generated by HAProxy
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | yes | yes | yes
|
||||||
|
Arguments :
|
||||||
|
<code> is the HTTP status code. Currently, HAProxy is capable of
|
||||||
|
generating codes 400, 403, 408, 500, 502, 503, and 504.
|
||||||
|
|
||||||
|
<url> it is the exact contents of the "Location" header. It may contain
|
||||||
|
either a relative URI to an error page hosted on the same site,
|
||||||
|
or an absolute URI designating an error page on another site.
|
||||||
|
Special care should be given to relative URIs to avoid redirect
|
||||||
|
loops if the URI itself may generate the same error (eg: 500).
|
||||||
|
|
||||||
|
It is important to understand that this keyword is not meant to rewrite
|
||||||
|
errors returned by the server, but errors detected and returned by HAProxy.
|
||||||
|
This is why the list of supported errors is limited to a small set.
|
||||||
|
|
||||||
|
Note that both keyword return the HTTP 302 status code, which tells the
|
||||||
|
client to fetch the designated URL using the same HTTP method. This can be
|
||||||
|
quite problematic in case of non-GET methods such as POST, because the URL
|
||||||
|
sent to the client might not be allowed for something other than GET. To
|
||||||
|
workaround this problem, please use "errorloc303" which send the HTTP 303
|
||||||
|
status code, indicating to the client that the URL must be fetched with a GET
|
||||||
|
request.
|
||||||
|
|
||||||
|
See also : "errorfile", "errorloc303"
|
||||||
|
|
||||||
|
|
||||||
|
errorloc303 <code> <url>
|
||||||
|
Return an HTTP redirection to a URL instead of errors generated by HAProxy
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | yes | yes | yes
|
||||||
|
Arguments :
|
||||||
|
<code> is the HTTP status code. Currently, HAProxy is capable of
|
||||||
|
generating codes 400, 403, 408, 500, 502, 503, and 504.
|
||||||
|
|
||||||
|
<url> it is the exact contents of the "Location" header. It may contain
|
||||||
|
either a relative URI to an error page hosted on the same site,
|
||||||
|
or an absolute URI designating an error page on another site.
|
||||||
|
Special care should be given to relative URIs to avoid redirect
|
||||||
|
loops if the URI itself may generate the same error (eg: 500).
|
||||||
|
|
||||||
|
It is important to understand that this keyword is not meant to rewrite
|
||||||
|
errors returned by the server, but errors detected and returned by HAProxy.
|
||||||
|
This is why the list of supported errors is limited to a small set.
|
||||||
|
|
||||||
|
Note that both keyword return the HTTP 303 status code, which tells the
|
||||||
|
client to fetch the designated URL using the same HTTP GET method. This
|
||||||
|
solves the usual problems associated with "errorloc" and the 302 code. It is
|
||||||
|
possible that some very old browsers designed before HTTP/1.1 do not support
|
||||||
|
it, but no such problem have been reported till now.
|
||||||
|
|
||||||
|
See also : "errorfile", "errorloc", "errorloc302"
|
||||||
|
|
||||||
|
|
||||||
|
fullconn <conns>
|
||||||
|
Specify at what backend load the servers will reach their maxconn
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | no | yes | yes
|
||||||
|
Arguments :
|
||||||
|
<conns> is the number of connections on the backend which will make the
|
||||||
|
servers use the maximal number of connections.
|
||||||
|
|
||||||
|
When a server has a 'maxconn' parameter specified, it means that its number
|
||||||
|
of concurrent connections will never go higher. Additionally, if it has a
|
||||||
|
'minconn' parameter, it indicates a dynamic limit following the backend's
|
||||||
|
load. The server will then always accept at least <minconn> connections,
|
||||||
|
never more than <maxconn>, and the limit will be on the ramp between both
|
||||||
|
values when the backend has less than <conns> concurrent connections. This
|
||||||
|
makes it possible to limit the load on the servers during normal loads, but
|
||||||
|
push it further for important loads without overloading the servers during
|
||||||
|
exceptionnal loads.
|
||||||
|
|
||||||
|
Example :
|
||||||
|
# The servers will accept between 100 and 1000 concurrent connections each
|
||||||
|
# and the maximum of 1000 will be reached when the backend reaches 10000
|
||||||
|
# connections.
|
||||||
|
backend dynamic
|
||||||
|
fullconn 10000
|
||||||
|
server srv1 dyn1:80 minconn 100 maxconn 1000
|
||||||
|
server srv2 dyn2:80 minconn 100 maxconn 1000
|
||||||
|
|
||||||
|
See also : "maxconn", "server"
|
||||||
|
|
||||||
|
|
||||||
|
grace <time>
|
||||||
|
Maintain a proxy operational for some time after a soft stop
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
no | yes | yes | yes
|
||||||
|
Arguments :
|
||||||
|
<time> is the time (by default in milliseconds) for which the instance
|
||||||
|
will remain operational with the frontend sockets still listening
|
||||||
|
when a soft-stop is received via the SIGUSR1 signal.
|
||||||
|
|
||||||
|
This may be used to ensure that the services disappear in a certain order.
|
||||||
|
This was designed so that frontends which are dedicated to monitoring by an
|
||||||
|
external equipement fail immediately while other ones remain up for the time
|
||||||
|
needed by the equipment to detect the failure.
|
||||||
|
|
||||||
|
Note that currently, there is very little benefit in using this parameter,
|
||||||
|
and it may in fact complicate the soft-reconfiguration process more than
|
||||||
|
simplify it.
|
||||||
|
|
||||||
|
|
||||||
http-check disable-on-404
|
http-check disable-on-404
|
||||||
Enable a maintenance mode upon HTTP/404 response to health-checks
|
Enable a maintenance mode upon HTTP/404 response to health-checks
|
||||||
May be used in sections : defaults | frontend | listen | backend
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
no | no | yes | yes
|
yes | no | yes | yes
|
||||||
|
|
||||||
Arguments : none
|
Arguments : none
|
||||||
|
|
||||||
When this option is set, a server which returns an HTTP code 404 will be
|
When this option is set, a server which returns an HTTP code 404 will be
|
||||||
@ -1142,12 +1249,124 @@ http-check disable-on-404
|
|||||||
reports "NOLB" for a server in this mode. It is important to note that this
|
reports "NOLB" for a server in this mode. It is important to note that this
|
||||||
option only works in conjunction with the "httpchk" option.
|
option only works in conjunction with the "httpchk" option.
|
||||||
|
|
||||||
|
See also : "option httpchk"
|
||||||
|
|
||||||
|
|
||||||
|
log global
|
||||||
|
log <address> <facility> [<level>]
|
||||||
|
Enable per-instance logging of events and traffic.
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | yes | yes | yes
|
||||||
|
Arguments :
|
||||||
|
global should be used when the instance's logging parameters are the
|
||||||
|
same as the global ones. This is the most common usage. "global"
|
||||||
|
replaces <address>, <facility> and <level> with those of the log
|
||||||
|
entries found in the "global" section. Only one "log global"
|
||||||
|
statement may be used per instance, and this form takes no other
|
||||||
|
parameter.
|
||||||
|
|
||||||
|
<address> indicates where to send the logs. It takes the same format as
|
||||||
|
for the "global" section's logs, and can be one of :
|
||||||
|
|
||||||
|
- An IPv4 address optionally followed by a colon (':') and a UDP
|
||||||
|
port. If no port is specified, 514 is used by default (the
|
||||||
|
standard syslog port).
|
||||||
|
|
||||||
|
- A filesystem path to a UNIX domain socket, keeping in mind
|
||||||
|
considerations for chroot (be sure the path is accessible
|
||||||
|
inside the chroot) and uid/gid (be sure the path is
|
||||||
|
appropriately writeable).
|
||||||
|
|
||||||
|
<facility> must be one of the 24 standard syslog facilities :
|
||||||
|
|
||||||
|
kern user mail daemon auth syslog lpr news
|
||||||
|
uucp cron auth2 ftp ntp audit alert cron2
|
||||||
|
local0 local1 local2 local3 local4 local5 local6 local7
|
||||||
|
|
||||||
|
<level> is optional and can be specified to filter outgoing messages. By
|
||||||
|
default, all messages are sent. If a level is specified, only
|
||||||
|
messages with a severity at least as important as this level
|
||||||
|
will be sent. 8 levels are known :
|
||||||
|
|
||||||
|
emerg alert crit err warning notice info debug
|
||||||
|
|
||||||
|
Note that up to two "log" entries may be specified per instance. However, if
|
||||||
|
"log global" is used and if the "global" section already contains 2 log
|
||||||
|
entries, then additional log entries will be ignored.
|
||||||
|
|
||||||
|
Also, it is important to keep in mind that it is the frontend which decides
|
||||||
|
what to log, and that in case of content switching, the log entries from the
|
||||||
|
backend will be ignored.
|
||||||
|
|
||||||
|
Example :
|
||||||
|
log global
|
||||||
|
log 127.0.0.1:514 local0 notice
|
||||||
|
|
||||||
|
|
||||||
|
maxconn <conns>
|
||||||
|
Fix the maximum number of concurrent connections on a frontend
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | yes | yes | no
|
||||||
|
Arguments :
|
||||||
|
<conns> is the maximum number of concurrent connections the frontend will
|
||||||
|
accept to serve. Excess connections will be queued by the system
|
||||||
|
in the socket's listen queue and will be served once a connection
|
||||||
|
closes.
|
||||||
|
|
||||||
|
If the system supports it, it can be useful on big sites to raise this limit
|
||||||
|
very high so that haproxy manages connection queues, instead of leaving the
|
||||||
|
clients with unanswered connection attempts. This value should not exceed the
|
||||||
|
global maxconn. Also, keep in mind that a connection contains two buffers
|
||||||
|
of 8kB each, as well as some other data resulting in about 17 kB of RAM being
|
||||||
|
consumed per established connection. That means that a medium system equipped
|
||||||
|
with 1GB of RAM can withstand around 40000-50000 concurrent connections if
|
||||||
|
properly tuned.
|
||||||
|
|
||||||
|
Also, when <conns> is set to large values, it is possible that the servers
|
||||||
|
are not sized to accept such loads, and for this reason it is generally wise
|
||||||
|
to assign them some reasonable connection limits.
|
||||||
|
|
||||||
|
See also : "server", global section's "maxconn", "fullconn"
|
||||||
|
|
||||||
|
|
||||||
|
mode { tcp|http|health }
|
||||||
|
Set the running mode or protocol of the instance
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | yes | yes | yes
|
||||||
|
Arguments :
|
||||||
|
tcp The instance will work in pure TCP mode. A full-duplex connection
|
||||||
|
will be established between clients and servers, and no layer 7
|
||||||
|
examination will be performed. This is the default mode. It
|
||||||
|
should be used for SSL, SSH, SMTP, ...
|
||||||
|
|
||||||
|
http The instance will work in HTTP mode. The client request will be
|
||||||
|
analyzed in depth before connecting to any server. Any request
|
||||||
|
which is not RFC-compliant will be rejected. Layer 7 filtering,
|
||||||
|
processing and switching will be possible. This is the mode which
|
||||||
|
brings HAProxy most of its value.
|
||||||
|
|
||||||
|
health The instance will work in "health" mode. It will just reply "OK"
|
||||||
|
to incoming connections and close the connection. Nothing will be
|
||||||
|
logged. This mode is used to reply to external components health
|
||||||
|
checks. This mode is deprecated and should not be used anymore as
|
||||||
|
it is possible to do the same and even better by combining TCP or
|
||||||
|
HTTP modes with the "monitor" keyword.
|
||||||
|
|
||||||
|
When doing content switching, it is mandatory that the frontend and the
|
||||||
|
backend are in the same mode (generally HTTP), otherwise the configuration
|
||||||
|
will be refused.
|
||||||
|
|
||||||
|
Example :
|
||||||
|
defaults http_instances
|
||||||
|
mode http
|
||||||
|
|
||||||
|
See also : "monitor", "monitor-net"
|
||||||
|
|
||||||
|
|
||||||
monitor fail [if | unless] <condition>
|
monitor fail [if | unless] <condition>
|
||||||
Add a condition to report a failure to a monitor request.
|
Add a condition to report a failure to a monitor HTTP request.
|
||||||
May be used in sections : defaults | frontend | listen | backend
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
no | yes | yes | no
|
no | yes | yes | no
|
||||||
|
|
||||||
Arguments :
|
Arguments :
|
||||||
if <cond> the monitor request will fail if the condition is satisfied,
|
if <cond> the monitor request will fail if the condition is satisfied,
|
||||||
and will succeed otherwise. The condition should describe a
|
and will succeed otherwise. The condition should describe a
|
||||||
@ -1167,15 +1386,86 @@ monitor fail [if | unless] <condition>
|
|||||||
very useful to report a site failure to an external component which may base
|
very useful to report a site failure to an external component which may base
|
||||||
routing advertisements between multiple sites on the availability reported by
|
routing advertisements between multiple sites on the availability reported by
|
||||||
haproxy. In this case, one would rely on an ACL involving the "nbsrv"
|
haproxy. In this case, one would rely on an ACL involving the "nbsrv"
|
||||||
criterion.
|
criterion. Note that "monitor fail" only works in HTTP mode.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
frontend www
|
frontend www
|
||||||
|
mode http
|
||||||
acl site_dead nbsrv(dynamic) lt 2
|
acl site_dead nbsrv(dynamic) lt 2
|
||||||
acl site_dead nbsrv(static) lt 2
|
acl site_dead nbsrv(static) lt 2
|
||||||
monitor-uri /site_alive
|
monitor-uri /site_alive
|
||||||
monitor fail if site_dead
|
monitor fail if site_dead
|
||||||
|
|
||||||
|
See also : "monitor-net", "monitor-uri"
|
||||||
|
|
||||||
|
|
||||||
|
monitor-net <source>
|
||||||
|
Declare a source network which is limited to monitor requests
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | yes | yes | no
|
||||||
|
Arguments :
|
||||||
|
<source> is the source IPv4 address or network which will only be able to
|
||||||
|
get monitor responses to any request. It can be either an IPv4
|
||||||
|
address, a host name, or an address followed by a slash ('/')
|
||||||
|
followed by a mask.
|
||||||
|
|
||||||
|
In TCP mode, any connection coming from a source matching <source> will cause
|
||||||
|
the connection to be immediately closed without any log. This allows another
|
||||||
|
equipement to probe the port and verify that it is still listening, without
|
||||||
|
forwarding the connection to a remote server.
|
||||||
|
|
||||||
|
In HTTP mode, a connection coming from a source matching <source> will be
|
||||||
|
accepted, the following response will be sent without waiting for a request,
|
||||||
|
then the connection will be closed : "HTTP/1.0 200 OK". This is normally
|
||||||
|
enough for any front-end HTTP probe to detect that the service is UP and
|
||||||
|
running without forwarding the request to a backend server.
|
||||||
|
|
||||||
|
Monitor requests are processed very early. It is not possible to block nor
|
||||||
|
divert them using ACLs. They cannot be logged either, and it is the intended
|
||||||
|
purpose. They are only used to report HAProxy's health to an upper component,
|
||||||
|
nothing more. Right now, it is not possible to set failure conditions on
|
||||||
|
requests caught by "monitor-net".
|
||||||
|
|
||||||
|
Example :
|
||||||
|
# addresses .252 and .253 are just probing us.
|
||||||
|
frontend www
|
||||||
|
monitor-net 192.168.0.252/31
|
||||||
|
|
||||||
|
See also : "monitor fail", "monitor-uri"
|
||||||
|
|
||||||
|
|
||||||
|
monitor-uri <uri>
|
||||||
|
Intercept a URI used by external components' monitor requests
|
||||||
|
May be used in sections : defaults | frontend | listen | backend
|
||||||
|
yes | yes | yes | no
|
||||||
|
Arguments :
|
||||||
|
<uri> is the exact URI which we want to intercept to return HAProxy's
|
||||||
|
health status instead of forwarding the request.
|
||||||
|
|
||||||
|
When an HTTP request referencing <uri> will be received on a frontend,
|
||||||
|
HAProxy will not forward it nor log it, but instead will return either
|
||||||
|
"HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure
|
||||||
|
conditions defined with "monitor fail". This is normally enough for any
|
||||||
|
front-end HTTP probe to detect that the service is UP and running without
|
||||||
|
forwarding the request to a backend server. Note that the HTTP method, the
|
||||||
|
version and all headers are ignored, but the request must at least be valid
|
||||||
|
at the HTTP level. This keyword may only be used with an HTTP-mode frontend.
|
||||||
|
|
||||||
|
Monitor requests are processed very early. It is not possible to block nor
|
||||||
|
divert them using ACLs. They cannot be logged either, and it is the intended
|
||||||
|
purpose. They are only used to report HAProxy's health to an upper component,
|
||||||
|
nothing more. However, it is possible to add any number of conditions using
|
||||||
|
"monitor fail" and ACLs so that the result can be adjusted to whatever check
|
||||||
|
can be imagined (most often the number of available servers in a backend).
|
||||||
|
|
||||||
|
Example :
|
||||||
|
# Use /haproxy_test to report haproxy's status
|
||||||
|
frontend www
|
||||||
|
mode http
|
||||||
|
monitor-uri /haproxy_test
|
||||||
|
|
||||||
|
See also : "monitor fail", "monitor-net"
|
||||||
|
|
||||||
|
|
||||||
option contstats
|
option contstats
|
||||||
Enable continuous traffic statistics updates
|
Enable continuous traffic statistics updates
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user