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
|
||||
Configuration Manual
|
||||
----------------------
|
||||
version 1.3.14
|
||||
version 1.3.14.2
|
||||
willy tarreau
|
||||
2007/12/24
|
||||
2007/12/27
|
||||
|
||||
|
||||
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:
|
||||
|
||||
- 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
|
||||
port).
|
||||
|
||||
@ -1064,6 +1064,8 @@ default_backend <backend>
|
||||
use_backend static if url_css url_img extension_img
|
||||
default_backend dynamic
|
||||
|
||||
See also : "use_backend", "reqsetbe", "reqisetbe"
|
||||
|
||||
|
||||
disabled
|
||||
Disable a proxy, frontend or backend.
|
||||
@ -1125,11 +1127,116 @@ errorfile <code> <file>
|
||||
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
|
||||
Enable a maintenance mode upon HTTP/404 response to health-checks
|
||||
May be used in sections : defaults | frontend | listen | backend
|
||||
no | no | yes | yes
|
||||
|
||||
yes | no | yes | yes
|
||||
Arguments : none
|
||||
|
||||
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
|
||||
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>
|
||||
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
|
||||
no | yes | yes | no
|
||||
|
||||
Arguments :
|
||||
if <cond> the monitor request will fail if the condition is satisfied,
|
||||
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
|
||||
routing advertisements between multiple sites on the availability reported by
|
||||
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:
|
||||
frontend www
|
||||
mode http
|
||||
acl site_dead nbsrv(dynamic) lt 2
|
||||
acl site_dead nbsrv(static) lt 2
|
||||
monitor-uri /site_alive
|
||||
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
|
||||
Enable continuous traffic statistics updates
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user