| ---------------------- |
| HAProxy |
| Configuration Manual |
| ---------------------- |
| version 1.5 |
| willy tarreau |
| 2012/09/10 |
| |
| |
| This document covers the configuration language as implemented in the version |
| specified above. It does not provide any hint, example or advice. For such |
| documentation, please refer to the Reference Manual or the Architecture Manual. |
| The summary below is meant to help you search sections by name and navigate |
| through the document. |
| |
| Note to documentation contributors : |
| This document is formatted with 80 columns per line, with even number of |
| spaces for indentation and without tabs. Please follow these rules strictly |
| so that it remains easily printable everywhere. If a line needs to be |
| printed verbatim and does not fit, please end each line with a backslash |
| ('\') and continue on next line, indented by two characters. It is also |
| sometimes useful to prefix all output lines (logs, console outs) with 3 |
| closing angle brackets ('>>>') in order to help get the difference between |
| inputs and outputs when it can become ambiguous. If you add sections, |
| please update the summary below for easier searching. |
| |
| |
| Summary |
| ------- |
| |
| 1. Quick reminder about HTTP |
| 1.1. The HTTP transaction model |
| 1.2. HTTP request |
| 1.2.1. The Request line |
| 1.2.2. The request headers |
| 1.3. HTTP response |
| 1.3.1. The Response line |
| 1.3.2. The response headers |
| |
| 2. Configuring HAProxy |
| 2.1. Configuration file format |
| 2.2. Time format |
| 2.3. Examples |
| |
| 3. Global parameters |
| 3.1. Process management and security |
| 3.2. Performance tuning |
| 3.3. Debugging |
| 3.4. Userlists |
| 3.5. Peers |
| |
| 4. Proxies |
| 4.1. Proxy keywords matrix |
| 4.2. Alphabetically sorted keywords reference |
| |
| 5. Bind and Server options |
| 5.1. Bind options |
| 5.2. Server and default-server options |
| |
| 6. HTTP header manipulation |
| |
| 7. Using ACLs and pattern extraction |
| 7.1. Matching integers |
| 7.2. Matching strings |
| 7.3. Matching regular expressions (regexes) |
| 7.4. Matching IPv4 and IPv6 addresses |
| 7.5. Available matching criteria |
| 7.5.1. Matching at Layer 4 and below |
| 7.5.2. Matching contents at Layer 4 |
| 7.5.3. Matching at Layer 7 |
| 7.6. Pre-defined ACLs |
| 7.7. Using ACLs to form conditions |
| 7.8. Pattern extraction |
| |
| 8. Logging |
| 8.1. Log levels |
| 8.2. Log formats |
| 8.2.1. Default log format |
| 8.2.2. TCP log format |
| 8.2.3. HTTP log format |
| 8.2.4. Custom log format |
| 8.3. Advanced logging options |
| 8.3.1. Disabling logging of external tests |
| 8.3.2. Logging before waiting for the session to terminate |
| 8.3.3. Raising log level upon errors |
| 8.3.4. Disabling logging of successful connections |
| 8.4. Timing events |
| 8.5. Session state at disconnection |
| 8.6. Non-printable characters |
| 8.7. Capturing HTTP cookies |
| 8.8. Capturing HTTP headers |
| 8.9. Examples of logs |
| |
| 9. Statistics and monitoring |
| 9.1. CSV format |
| 9.2. Unix Socket commands |
| |
| |
| 1. Quick reminder about HTTP |
| ---------------------------- |
| |
| When haproxy is running in HTTP mode, both the request and the response are |
| fully analyzed and indexed, thus it becomes possible to build matching criteria |
| on almost anything found in the contents. |
| |
| However, it is important to understand how HTTP requests and responses are |
| formed, and how HAProxy decomposes them. It will then become easier to write |
| correct rules and to debug existing configurations. |
| |
| |
| 1.1. The HTTP transaction model |
| ------------------------------- |
| |
| The HTTP protocol is transaction-driven. This means that each request will lead |
| to one and only one response. Traditionally, a TCP connection is established |
| from the client to the server, a request is sent by the client on the |
| connection, the server responds and the connection is closed. A new request |
| will involve a new connection : |
| |
| [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ... |
| |
| In this mode, called the "HTTP close" mode, there are as many connection |
| establishments as there are HTTP transactions. Since the connection is closed |
| by the server after the response, the client does not need to know the content |
| length. |
| |
| Due to the transactional nature of the protocol, it was possible to improve it |
| to avoid closing a connection between two subsequent transactions. In this mode |
| however, it is mandatory that the server indicates the content length for each |
| response so that the client does not wait indefinitely. For this, a special |
| header is used: "Content-length". This mode is called the "keep-alive" mode : |
| |
| [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ... |
| |
| Its advantages are a reduced latency between transactions, and less processing |
| power required on the server side. It is generally better than the close mode, |
| but not always because the clients often limit their concurrent connections to |
| a smaller value. |
| |
| A last improvement in the communications is the pipelining mode. It still uses |
| keep-alive, but the client does not wait for the first response to send the |
| second request. This is useful for fetching large number of images composing a |
| page : |
| |
| [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ... |
| |
| This can obviously have a tremendous benefit on performance because the network |
| latency is eliminated between subsequent requests. Many HTTP agents do not |
| correctly support pipelining since there is no way to associate a response with |
| the corresponding request in HTTP. For this reason, it is mandatory for the |
| server to reply in the exact same order as the requests were received. |
| |
| By default HAProxy operates in a tunnel-like mode with regards to persistent |
| connections: for each connection it processes the first request and forwards |
| everything else (including additional requests) to selected server. Once |
| established, the connection is persisted both on the client and server |
| sides. Use "option http-server-close" to preserve client persistent connections |
| while handling every incoming request individually, dispatching them one after |
| another to servers, in HTTP close mode. Use "option httpclose" to switch both |
| sides to HTTP close mode. "option forceclose" and "option |
| http-pretend-keepalive" help working around servers misbehaving in HTTP close |
| mode. |
| |
| |
| 1.2. HTTP request |
| ----------------- |
| |
| First, let's consider this HTTP request : |
| |
| Line Contents |
| number |
| 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1 |
| 2 Host: www.mydomain.com |
| 3 User-agent: my small browser |
| 4 Accept: image/jpeg, image/gif |
| 5 Accept: image/png |
| |
| |
| 1.2.1. The Request line |
| ----------------------- |
| |
| Line 1 is the "request line". It is always composed of 3 fields : |
| |
| - a METHOD : GET |
| - a URI : /serv/login.php?lang=en&profile=2 |
| - a version tag : HTTP/1.1 |
| |
| All of them are delimited by what the standard calls LWS (linear white spaces), |
| which are commonly spaces, but can also be tabs or line feeds/carriage returns |
| followed by spaces/tabs. The method itself cannot contain any colon (':') and |
| is limited to alphabetic letters. All those various combinations make it |
| desirable that HAProxy performs the splitting itself rather than leaving it to |
| the user to write a complex or inaccurate regular expression. |
| |
| The URI itself can have several forms : |
| |
| - A "relative URI" : |
| |
| /serv/login.php?lang=en&profile=2 |
| |
| It is a complete URL without the host part. This is generally what is |
| received by servers, reverse proxies and transparent proxies. |
| |
| - An "absolute URI", also called a "URL" : |
| |
| http://192.168.0.12:8080/serv/login.php?lang=en&profile=2 |
| |
| It is composed of a "scheme" (the protocol name followed by '://'), a host |
| name or address, optionally a colon (':') followed by a port number, then |
| a relative URI beginning at the first slash ('/') after the address part. |
| This is generally what proxies receive, but a server supporting HTTP/1.1 |
| must accept this form too. |
| |
| - a star ('*') : this form is only accepted in association with the OPTIONS |
| method and is not relayable. It is used to inquiry a next hop's |
| capabilities. |
| |
| - an address:port combination : 192.168.0.12:80 |
| This is used with the CONNECT method, which is used to establish TCP |
| tunnels through HTTP proxies, generally for HTTPS, but sometimes for |
| other protocols too. |
| |
| In a relative URI, two sub-parts are identified. The part before the question |
| mark is called the "path". It is typically the relative path to static objects |
| on the server. The part after the question mark is called the "query string". |
| It is mostly used with GET requests sent to dynamic scripts and is very |
| specific to the language, framework or application in use. |
| |
| |
| 1.2.2. The request headers |
| -------------------------- |
| |
| The headers start at the second line. They are composed of a name at the |
| beginning of the line, immediately followed by a colon (':'). Traditionally, |
| an LWS is added after the colon but that's not required. Then come the values. |
| Multiple identical headers may be folded into one single line, delimiting the |
| values with commas, provided that their order is respected. This is commonly |
| encountered in the "Cookie:" field. A header may span over multiple lines if |
| the subsequent lines begin with an LWS. In the example in 1.2, lines 4 and 5 |
| define a total of 3 values for the "Accept:" header. |
| |
| Contrary to a common mis-conception, header names are not case-sensitive, and |
| their values are not either if they refer to other header names (such as the |
| "Connection:" header). |
| |
| The end of the headers is indicated by the first empty line. People often say |
| that it's a double line feed, which is not exact, even if a double line feed |
| is one valid form of empty line. |
| |
| Fortunately, HAProxy takes care of all these complex combinations when indexing |
| headers, checking values and counting them, so there is no reason to worry |
| about the way they could be written, but it is important not to accuse an |
| application of being buggy if it does unusual, valid things. |
| |
| Important note: |
| As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks |
| in the middle of headers by LWS in order to join multi-line headers. This |
| is necessary for proper analysis and helps less capable HTTP parsers to work |
| correctly and not to be fooled by such complex constructs. |
| |
| |
| 1.3. HTTP response |
| ------------------ |
| |
| An HTTP response looks very much like an HTTP request. Both are called HTTP |
| messages. Let's consider this HTTP response : |
| |
| Line Contents |
| number |
| 1 HTTP/1.1 200 OK |
| 2 Content-length: 350 |
| 3 Content-Type: text/html |
| |
| As a special case, HTTP supports so called "Informational responses" as status |
| codes 1xx. These messages are special in that they don't convey any part of the |
| response, they're just used as sort of a signaling message to ask a client to |
| continue to post its request for instance. In the case of a status 100 response |
| the requested information will be carried by the next non-100 response message |
| following the informational one. This implies that multiple responses may be |
| sent to a single request, and that this only works when keep-alive is enabled |
| (1xx messages are HTTP/1.1 only). HAProxy handles these messages and is able to |
| correctly forward and skip them, and only process the next non-100 response. As |
| such, these messages are neither logged nor transformed, unless explicitly |
| state otherwise. Status 101 messages indicate that the protocol is changing |
| over the same connection and that haproxy must switch to tunnel mode, just as |
| if a CONNECT had occurred. Then the Upgrade header would contain additional |
| information about the type of protocol the connection is switching to. |
| |
| |
| 1.3.1. The Response line |
| ------------------------ |
| |
| Line 1 is the "response line". It is always composed of 3 fields : |
| |
| - a version tag : HTTP/1.1 |
| - a status code : 200 |
| - a reason : OK |
| |
| The status code is always 3-digit. The first digit indicates a general status : |
| - 1xx = informational message to be skipped (eg: 100, 101) |
| - 2xx = OK, content is following (eg: 200, 206) |
| - 3xx = OK, no content following (eg: 302, 304) |
| - 4xx = error caused by the client (eg: 401, 403, 404) |
| - 5xx = error caused by the server (eg: 500, 502, 503) |
| |
| Please refer to RFC2616 for the detailed meaning of all such codes. The |
| "reason" field is just a hint, but is not parsed by clients. Anything can be |
| found there, but it's a common practice to respect the well-established |
| messages. It can be composed of one or multiple words, such as "OK", "Found", |
| or "Authentication Required". |
| |
| Haproxy may emit the following status codes by itself : |
| |
| Code When / reason |
| 200 access to stats page, and when replying to monitoring requests |
| 301 when performing a redirection, depending on the configured code |
| 302 when performing a redirection, depending on the configured code |
| 303 when performing a redirection, depending on the configured code |
| 400 for an invalid or too large request |
| 401 when an authentication is required to perform the action (when |
| accessing the stats page) |
| 403 when a request is forbidden by a "block" ACL or "reqdeny" filter |
| 408 when the request timeout strikes before the request is complete |
| 500 when haproxy encounters an unrecoverable internal error, such as a |
| memory allocation failure, which should never happen |
| 502 when the server returns an empty, invalid or incomplete response, or |
| when an "rspdeny" filter blocks the response. |
| 503 when no server was available to handle the request, or in response to |
| monitoring requests which match the "monitor fail" condition |
| 504 when the response timeout strikes before the server responds |
| |
| The error 4xx and 5xx codes above may be customized (see "errorloc" in section |
| 4.2). |
| |
| |
| 1.3.2. The response headers |
| --------------------------- |
| |
| Response headers work exactly like request headers, and as such, HAProxy uses |
| the same parsing function for both. Please refer to paragraph 1.2.2 for more |
| details. |
| |
| |
| 2. Configuring HAProxy |
| ---------------------- |
| |
| 2.1. Configuration file format |
| ------------------------------ |
| |
| HAProxy's configuration process involves 3 major sources of parameters : |
| |
| - the arguments from the command-line, which always take precedence |
| - the "global" section, which sets process-wide parameters |
| - the proxies sections which can take form of "defaults", "listen", |
| "frontend" and "backend". |
| |
| The configuration file syntax consists in lines beginning with a keyword |
| referenced in this manual, optionally followed by one or several parameters |
| delimited by spaces. If spaces have to be entered in strings, then they must be |
| preceded by a backslash ('\') to be escaped. Backslashes also have to be |
| escaped by doubling them. |
| |
| |
| 2.2. Time format |
| ---------------- |
| |
| Some parameters involve values representing time, such as timeouts. These |
| values are generally expressed in milliseconds (unless explicitly stated |
| otherwise) but may be expressed in any other unit by suffixing the unit to the |
| numeric value. It is important to consider this because it will not be repeated |
| for every keyword. Supported units are : |
| |
| - us : microseconds. 1 microsecond = 1/1000000 second |
| - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default. |
| - s : seconds. 1s = 1000ms |
| - m : minutes. 1m = 60s = 60000ms |
| - h : hours. 1h = 60m = 3600s = 3600000ms |
| - d : days. 1d = 24h = 1440m = 86400s = 86400000ms |
| |
| |
| 2.3. Examples |
| ------------- |
| |
| # Simple configuration for an HTTP proxy listening on port 80 on all |
| # interfaces and forwarding requests to a single backend "servers" with a |
| # single server "server1" listening on 127.0.0.1:8000 |
| global |
| daemon |
| maxconn 256 |
| |
| defaults |
| mode http |
| timeout connect 5000ms |
| timeout client 50000ms |
| timeout server 50000ms |
| |
| frontend http-in |
| bind *:80 |
| default_backend servers |
| |
| backend servers |
| server server1 127.0.0.1:8000 maxconn 32 |
| |
| |
| # The same configuration defined with a single listen block. Shorter but |
| # less expressive, especially in HTTP mode. |
| global |
| daemon |
| maxconn 256 |
| |
| defaults |
| mode http |
| timeout connect 5000ms |
| timeout client 50000ms |
| timeout server 50000ms |
| |
| listen http-in |
| bind *:80 |
| server server1 127.0.0.1:8000 maxconn 32 |
| |
| |
| Assuming haproxy is in $PATH, test these configurations in a shell with: |
| |
| $ sudo haproxy -f configuration.conf -c |
| |
| |
| 3. Global parameters |
| -------------------- |
| |
| Parameters in the "global" section are process-wide and often OS-specific. They |
| are generally set once for all and do not need being changed once correct. Some |
| of them have command-line equivalents. |
| |
| The following keywords are supported in the "global" section : |
| |
| * Process management and security |
| - ca-base |
| - chroot |
| - crt-base |
| - daemon |
| - gid |
| - group |
| - log |
| - log-send-hostname |
| - nbproc |
| - pidfile |
| - uid |
| - ulimit-n |
| - user |
| - stats |
| - node |
| - description |
| - unix-bind |
| |
| * Performance tuning |
| - maxconn |
| - maxconnrate |
| - maxcomprate |
| - maxpipes |
| - maxsslconn |
| - noepoll |
| - nokqueue |
| - nopoll |
| - nosplice |
| - spread-checks |
| - tune.bufsize |
| - tune.chksize |
| - tune.comp.maxlevel |
| - tune.http.maxhdr |
| - tune.maxaccept |
| - tune.maxpollevents |
| - tune.maxrewrite |
| - tune.pipesize |
| - tune.rcvbuf.client |
| - tune.rcvbuf.server |
| - tune.sndbuf.client |
| - tune.sndbuf.server |
| - tune.ssl.cachesize |
| - tune.zlib.memlevel |
| - tune.zlib.windowsize |
| |
| * Debugging |
| - debug |
| - quiet |
| |
| |
| 3.1. Process management and security |
| ------------------------------------ |
| |
| ca-base <dir> |
| Assigns a default directory to fetch SSL CA certificates and CRLs from when a |
| relative path is used with "ca-file" or "crl-file" directives. Absolute |
| locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base". |
| |
| chroot <jail dir> |
| Changes current directory to <jail dir> and performs a chroot() there before |
| dropping privileges. This increases the security level in case an unknown |
| vulnerability would be exploited, since it would make it very hard for the |
| attacker to exploit the system. This only works when the process is started |
| with superuser privileges. It is important to ensure that <jail_dir> is both |
| empty and unwritable to anyone. |
| |
| cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>... |
| On Linux 2.6 and above, it is possible to bind a process to a specific CPU |
| set. This means that the process will never run on other CPUs. The "cpu-map" |
| directive specifies CPU sets for process sets. The first argument is the |
| process number to bind. This process must have a number between 1 and 32, |
| and any process IDs above nbproc are ignored. It is possible to specify all |
| processes at once using "all", only odd numbers using "odd" or even numbers |
| using "even", just like with the "bind-process" directive. The second and |
| forthcoming arguments are CPU sets. Each CPU set is either a unique number |
| between 0 and 31 or a range with two such numbers delimited by a dash ('-'). |
| Multiple CPU numbers or ranges may be specified, and the processes will be |
| allowed to bind to all of them. Obviously, multiple "cpu-map" directives may |
| be specified. Each "cpu-map" directive will replace the previous ones when |
| they overlap. |
| |
| crt-base <dir> |
| Assigns a default directory to fetch SSL certificates from when a relative |
| path is used with "crtfile" directives. Absolute locations specified after |
| "crtfile" prevail and ignore "crt-base". |
| |
| daemon |
| Makes the process fork into background. This is the recommended mode of |
| operation. It is equivalent to the command line "-D" argument. It can be |
| disabled by the command line "-db" argument. |
| |
| gid <number> |
| Changes the process' group ID to <number>. It is recommended that the group |
| ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| be started with a user belonging to this group, or with superuser privileges. |
| See also "group" and "uid". |
| |
| group <group name> |
| Similar to "gid" but uses the GID of group name <group name> from /etc/group. |
| See also "gid" and "user". |
| |
| log <address> <facility> [max level [min level]] |
| Adds a global syslog server. Up to two global servers can be defined. They |
| will receive logs for startups and exits, as well as all logs from proxies |
| configured with "log global". |
| |
| <address> 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). |
| |
| - An IPv6 address followed by a colon and optionally 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 |
| |
| An optional level can be specified to filter outgoing messages. By default, |
| all messages are sent. If a maximum level is specified, only messages with a |
| severity at least as important as this level will be sent. An optional minimum |
| level can be specified. If it is set, logs emitted with a more severe level |
| than this one will be capped to this level. This is used to avoid sending |
| "emerg" messages on all terminals on some default syslog configurations. |
| Eight levels are known : |
| |
| emerg alert crit err warning notice info debug |
| |
| log-send-hostname [<string>] |
| Sets the hostname field in the syslog header. If optional "string" parameter |
| is set the header is set to the string contents, otherwise uses the hostname |
| of the system. Generally used if one is not relaying logs through an |
| intermediate syslog server or for simply customizing the hostname printed in |
| the logs. |
| |
| log-tag <string> |
| Sets the tag field in the syslog header to this string. It defaults to the |
| program name as launched from the command line, which usually is "haproxy". |
| Sometimes it can be useful to differentiate between multiple processes |
| running on the same host. |
| |
| nbproc <number> |
| Creates <number> processes when going daemon. This requires the "daemon" |
| mode. By default, only one process is created, which is the recommended mode |
| of operation. For systems limited to small sets of file descriptors per |
| process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES |
| IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon". |
| |
| pidfile <pidfile> |
| Writes pids of all daemons into file <pidfile>. This option is equivalent to |
| the "-p" command line argument. The file must be accessible to the user |
| starting the process. See also "daemon". |
| |
| stats bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ... |
| Limits the stats socket to a certain set of processes numbers. By default the |
| stats socket is bound to all processes, causing a warning to be emitted when |
| nbproc is greater than 1 because there is no way to select the target process |
| when connecting. However, by using this setting, it becomes possible to pin |
| the stats socket to a specific set of processes, typically the first one. The |
| warning will automatically be disabled when this setting is used, whatever |
| the number of processes used. |
| |
| stats socket [<address:port>|<path>] [param*] |
| Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>. |
| Connections to this socket will return various statistics outputs and even |
| allow some commands to be issued to change some runtime settings. Please |
| consult section 9.2 "Unix Socket commands" for more details. |
| |
| All parameters supported by "bind" lines are supported, for instance to |
| restrict access to some users or their access rights. Please consult |
| section 5.1 for more information. |
| |
| stats timeout <timeout, in milliseconds> |
| The default timeout on the stats socket is set to 10 seconds. It is possible |
| to change this value with "stats timeout". The value must be passed in |
| milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }. |
| |
| stats maxconn <connections> |
| By default, the stats socket is limited to 10 concurrent connections. It is |
| possible to change this value with "stats maxconn". |
| |
| uid <number> |
| Changes the process' user ID to <number>. It is recommended that the user ID |
| is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| be started with superuser privileges in order to be able to switch to another |
| one. See also "gid" and "user". |
| |
| ulimit-n <number> |
| Sets the maximum number of per-process file-descriptors to <number>. By |
| default, it is automatically computed, so it is recommended not to use this |
| option. |
| |
| unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] |
| [ group <group> ] [ gid <gid> ] |
| |
| Fixes common settings to UNIX listening sockets declared in "bind" statements. |
| This is mainly used to simplify declaration of those UNIX sockets and reduce |
| the risk of errors, since those settings are most commonly required but are |
| also process-specific. The <prefix> setting can be used to force all socket |
| path to be relative to that directory. This might be needed to access another |
| component's chroot. Note that those paths are resolved before haproxy chroots |
| itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid> |
| all have the same meaning as their homonyms used by the "bind" statement. If |
| both are specified, the "bind" statement has priority, meaning that the |
| "unix-bind" settings may be seen as process-wide default settings. |
| |
| user <user name> |
| Similar to "uid" but uses the UID of user name <user name> from /etc/passwd. |
| See also "uid" and "group". |
| |
| node <name> |
| Only letters, digits, hyphen and underscore are allowed, like in DNS names. |
| |
| This statement is useful in HA configurations where two or more processes or |
| servers share the same IP address. By setting a different node-name on all |
| nodes, it becomes easy to immediately spot what server is handling the |
| traffic. |
| |
| description <text> |
| Add a text that describes the instance. |
| |
| Please note that it is required to escape certain characters (# for example) |
| and this text is inserted into a html page so you should avoid using |
| "<" and ">" characters. |
| |
| |
| 3.2. Performance tuning |
| ----------------------- |
| |
| maxconn <number> |
| Sets the maximum per-process number of concurrent connections to <number>. It |
| is equivalent to the command-line argument "-n". Proxies will stop accepting |
| connections when this limit is reached. The "ulimit-n" parameter is |
| automatically adjusted according to this value. See also "ulimit-n". |
| |
| maxconnrate <number> |
| Sets the maximum per-process number of connections per second to <number>. |
| Proxies will stop accepting connections when this limit is reached. It can be |
| used to limit the global capacity regardless of each frontend capacity. It is |
| important to note that this can only be used as a service protection measure, |
| as there will not necessarily be a fair share between frontends when the |
| limit is reached, so it's a good idea to also limit each frontend to some |
| value close to its expected share. Also, lowering tune.maxaccept can improve |
| fairness. |
| |
| maxcomprate <number> |
| Sets the maximum per-process input compression rate to <number> kilobytes |
| pers second. For each session, if the maximum is reached, the compression |
| level will be decreased during the session. If the maximum is reached at the |
| beginning of a session, the session will not compress at all. If the maximum |
| is not reached, the compression level will be increased up to |
| tune.comp.maxlevel. A value of zero means there is no limit, this is the |
| default value. |
| |
| maxpipes <number> |
| Sets the maximum per-process number of pipes to <number>. Currently, pipes |
| are only used by kernel-based tcp splicing. Since a pipe contains two file |
| descriptors, the "ulimit-n" value will be increased accordingly. The default |
| value is maxconn/4, which seems to be more than enough for most heavy usages. |
| The splice code dynamically allocates and releases pipes, and can fall back |
| to standard copy, so setting this value too low may only impact performance. |
| |
| maxsslconn <number> |
| Sets the maximum per-process number of concurrent SSL connections to |
| <number>. By default there is no SSL-specific limit, which means that the |
| global maxconn setting will apply to all connections. Setting this limit |
| avoids having openssl use too much memory and crash when malloc returns NULL |
| (since it unfortunately does not reliably check for such conditions). Note |
| that the limit applies both to incoming and outgoing connections, so one |
| connection which is deciphered then ciphered accounts for 2 SSL connections. |
| |
| maxzlibmem <number> |
| Sets the maximum amount of RAM in megabytes per process usable by the zlib. |
| When the maximum amount is reached, future sessions will not compress as long |
| as RAM is unavailable. When sets to 0, there is no limit. |
| The default value is 0. |
| |
| noepoll |
| Disables the use of the "epoll" event polling system on Linux. It is |
| equivalent to the command-line argument "-de". The next polling system |
| used will generally be "poll". See also "nopoll". |
| |
| nokqueue |
| Disables the use of the "kqueue" event polling system on BSD. It is |
| equivalent to the command-line argument "-dk". The next polling system |
| used will generally be "poll". See also "nopoll". |
| |
| nopoll |
| Disables the use of the "poll" event polling system. It is equivalent to the |
| command-line argument "-dp". The next polling system used will be "select". |
| It should never be needed to disable "poll" since it's available on all |
| platforms supported by HAProxy. See also "nokqueue" and "noepoll". |
| |
| nosplice |
| Disables the use of kernel tcp splicing between sockets on Linux. It is |
| equivalent to the command line argument "-dS". Data will then be copied |
| using conventional and more portable recv/send calls. Kernel tcp splicing is |
| limited to some very recent instances of kernel 2.6. Most versions between |
| 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not |
| be used. This option makes it easier to globally disable kernel splicing in |
| case of doubt. See also "option splice-auto", "option splice-request" and |
| "option splice-response". |
| |
| spread-checks <0..50, in percent> |
| Sometimes it is desirable to avoid sending health checks to servers at exact |
| intervals, for instance when many logical servers are located on the same |
| physical server. With the help of this parameter, it becomes possible to add |
| some randomness in the check interval between 0 and +/- 50%. A value between |
| 2 and 5 seems to show good results. The default value remains at 0. |
| |
| tune.bufsize <number> |
| Sets the buffer size to this size (in bytes). Lower values allow more |
| sessions to coexist in the same amount of RAM, and higher values allow some |
| applications with very large cookies to work. The default value is 16384 and |
| can be changed at build time. It is strongly recommended not to change this |
| from the default value, as very low values will break some services such as |
| statistics, and values larger than default size will increase memory usage, |
| possibly causing the system to run out of memory. At least the global maxconn |
| parameter should be decreased by the same factor as this one is increased. |
| If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will |
| return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger |
| than this size, haproxy will return HTTP 502 (Bad Gateway). |
| |
| tune.chksize <number> |
| Sets the check buffer size to this size (in bytes). Higher values may help |
| find string or regex patterns in very large pages, though doing so may imply |
| more memory and CPU usage. The default value is 16384 and can be changed at |
| build time. It is not recommended to change this value, but to use better |
| checks whenever possible. |
| |
| tune.comp.maxlevel <number> |
| Sets the maximum compression level. The compression level affects CPU |
| usage during compression. This value affects CPU usage during compression. |
| Each session using compression initializes the compression algorithm with |
| this value. The default value is 1. |
| |
| tune.http.maxhdr <number> |
| Sets the maximum number of headers in a request. When a request comes with a |
| number of headers greater than this value (including the first line), it is |
| rejected with a "400 Bad Request" status code. Similarly, too large responses |
| are blocked with "502 Bad Gateway". The default value is 101, which is enough |
| for all usages, considering that the widely deployed Apache server uses the |
| same limit. It can be useful to push this limit further to temporarily allow |
| a buggy application to work by the time it gets fixed. Keep in mind that each |
| new header consumes 32bits of memory for each session, so don't push this |
| limit too high. |
| |
| tune.maxaccept <number> |
| Sets the maximum number of consecutive accepts that a process may perform on |
| a single wake up. High values give higher priority to high connection rates, |
| while lower values give higher priority to already established connections. |
| This value is limited to 100 by default in single process mode. However, in |
| multi-process mode (nbproc > 1), it defaults to 8 so that when one process |
| wakes up, it does not take all incoming connections for itself and leaves a |
| part of them to other processes. Setting this value to -1 completely disables |
| the limitation. It should normally not be needed to tweak this value. |
| |
| tune.maxpollevents <number> |
| Sets the maximum amount of events that can be processed at once in a call to |
| the polling system. The default value is adapted to the operating system. It |
| has been noticed that reducing it below 200 tends to slightly decrease |
| latency at the expense of network bandwidth, and increasing it above 200 |
| tends to trade latency for slightly increased bandwidth. |
| |
| tune.maxrewrite <number> |
| Sets the reserved buffer space to this size in bytes. The reserved space is |
| used for header rewriting or appending. The first reads on sockets will never |
| fill more than bufsize-maxrewrite. Historically it has defaulted to half of |
| bufsize, though that does not make much sense since there are rarely large |
| numbers of headers to add. Setting it too high prevents processing of large |
| requests or responses. Setting it too low prevents addition of new headers |
| to already large requests or to POST requests. It is generally wise to set it |
| to about 1024. It is automatically readjusted to half of bufsize if it is |
| larger than that. This means you don't have to worry about it when changing |
| bufsize. |
| |
| tune.pipesize <number> |
| Sets the kernel pipe buffer size to this size (in bytes). By default, pipes |
| are the default size for the system. But sometimes when using TCP splicing, |
| it can improve performance to increase pipe sizes, especially if it is |
| suspected that pipes are not filled and that many calls to splice() are |
| performed. This has an impact on the kernel's memory footprint, so this must |
| not be changed if impacts are not understood. |
| |
| tune.rcvbuf.client <number> |
| tune.rcvbuf.server <number> |
| Forces the kernel socket receive buffer size on the client or the server side |
| to the specified value in bytes. This value applies to all TCP/HTTP frontends |
| and backends. It should normally never be set, and the default size (0) lets |
| the kernel autotune this value depending on the amount of available memory. |
| However it can sometimes help to set it to very low values (eg: 4096) in |
| order to save kernel memory by preventing it from buffering too large amounts |
| of received data. Lower values will significantly increase CPU usage though. |
| |
| tune.sndbuf.client <number> |
| tune.sndbuf.server <number> |
| Forces the kernel socket send buffer size on the client or the server side to |
| the specified value in bytes. This value applies to all TCP/HTTP frontends |
| and backends. It should normally never be set, and the default size (0) lets |
| the kernel autotune this value depending on the amount of available memory. |
| However it can sometimes help to set it to very low values (eg: 4096) in |
| order to save kernel memory by preventing it from buffering too large amounts |
| of received data. Lower values will significantly increase CPU usage though. |
| Another use case is to prevent write timeouts with extremely slow clients due |
| to the kernel waiting for a large part of the buffer to be read before |
| notifying haproxy again. |
| |
| tune.ssl.cachesize <number> |
| Sets the size of the global SSL session cache, in number of sessions. Each |
| entry uses approximately 600 bytes of memory. The default value may be forced |
| at build time, otherwise defaults to 20000. When the cache is full, the most |
| idle entries are purged and reassigned. Higher values reduce the occurrence |
| of such a purge, hence the number of CPU-intensive SSL handshakes by ensuring |
| that all users keep their session as long as possible. All entries are pre- |
| allocated upon startup and are shared between all processes if "nbproc" is |
| greater than 1. |
| |
| tune.ssl.lifetime <timeout> |
| Sets how long a cached SSL session may remain valid. This time is expressed |
| in seconds and defaults to 300 (5 mn). It is important to understand that it |
| does not guarantee that sessions will last that long, because if the cache is |
| full, the longest idle sessions will be purged despite their configured |
| lifetime. The real usefulness of this setting is to prevent sessions from |
| being used for too long. |
| |
| tune.zlib.memlevel <number> |
| Sets the memLevel parameter in zlib initialization for each session. It |
| defines how much memory should be allocated for the intenal compression |
| state. A value of 1 uses minimum memory but is slow and reduces compression |
| ratio, a value of 9 uses maximum memory for optimal speed. Can be a value |
| between 1 and 9. The default value is 8. |
| |
| tune.zlib.windowsize <number> |
| Sets the window size (the size of the history buffer) as a parameter of the |
| zlib initialization for each session. Larger values of this parameter result |
| in better compression at the expense of memory usage. Can be a value between |
| 8 and 15. The default value is 15. |
| |
| 3.3. Debugging |
| -------------- |
| |
| debug |
| Enables debug mode which dumps to stdout all exchanges, and disables forking |
| into background. It is the equivalent of the command-line argument "-d". It |
| should never be used in a production configuration since it may prevent full |
| system startup. |
| |
| quiet |
| Do not display any message during startup. It is equivalent to the command- |
| line argument "-q". |
| |
| |
| 3.4. Userlists |
| -------------- |
| It is possible to control access to frontend/backend/listen sections or to |
| http stats by allowing only authenticated and authorized users. To do this, |
| it is required to create at least one userlist and to define users. |
| |
| userlist <listname> |
| Creates new userlist with name <listname>. Many independent userlists can be |
| used to store authentication & authorization data for independent customers. |
| |
| group <groupname> [users <user>,<user>,(...)] |
| Adds group <groupname> to the current userlist. It is also possible to |
| attach users to this group by using a comma separated list of names |
| proceeded by "users" keyword. |
| |
| user <username> [password|insecure-password <password>] |
| [groups <group>,<group>,(...)] |
| Adds user <username> to the current userlist. Both secure (encrypted) and |
| insecure (unencrypted) passwords can be used. Encrypted passwords are |
| evaluated using the crypt(3) function so depending of the system's |
| capabilities, different algorithms are supported. For example modern Glibc |
| based Linux system supports MD5, SHA-256, SHA-512 and of course classic, |
| DES-based method of crypting passwords. |
| |
| |
| Example: |
| userlist L1 |
| group G1 users tiger,scott |
| group G2 users xdb,scott |
| |
| user tiger password $6$k6y3o.eP$JlKBx9za9667qe4(...)xHSwRv6J.C0/D7cV91 |
| user scott insecure-password elgato |
| user xdb insecure-password hello |
| |
| userlist L2 |
| group G1 |
| group G2 |
| |
| user tiger password $6$k6y3o.eP$JlKBx(...)xHSwRv6J.C0/D7cV91 groups G1 |
| user scott insecure-password elgato groups G1,G2 |
| user xdb insecure-password hello groups G2 |
| |
| Please note that both lists are functionally identical. |
| |
| |
| 3.5. Peers |
| ---------- |
| It is possible to synchronize server entries in stick tables between several |
| haproxy instances over TCP connections in a multi-master fashion. Each instance |
| pushes its local updates and insertions to remote peers. Server IDs are used to |
| identify servers remotely, so it is important that configurations look similar |
| or at least that the same IDs are forced on each server on all participants. |
| Interrupted exchanges are automatically detected and recovered from the last |
| known point. In addition, during a soft restart, the old process connects to |
| the new one using such a TCP connection to push all its entries before the new |
| process tries to connect to other peers. That ensures very fast replication |
| during a reload, it typically takes a fraction of a second even for large |
| tables. |
| |
| peers <peersect> |
| Creates a new peer list with name <peersect>. It is an independent section, |
| which is referenced by one or more stick-tables. |
| |
| peer <peername> <ip>:<port> |
| Defines a peer inside a peers section. |
| If <peername> is set to the local peer name (by default hostname, or forced |
| using "-L" command line option), haproxy will listen for incoming remote peer |
| connection on <ip>:<port>. Otherwise, <ip>:<port> defines where to connect to |
| to join the remote peer, and <peername> is used at the protocol level to |
| identify and validate the remote peer on the server side. |
| |
| During a soft restart, local peer <ip>:<port> is used by the old instance to |
| connect the new one and initiate a complete replication (teaching process). |
| |
| It is strongly recommended to have the exact same peers declaration on all |
| peers and to only rely on the "-L" command line argument to change the local |
| peer name. This makes it easier to maintain coherent configuration files |
| across all peers. |
| |
| Example: |
| peers mypeers |
| peer haproxy1 192.168.0.1:1024 |
| peer haproxy2 192.168.0.2:1024 |
| peer haproxy3 10.2.0.1:1024 |
| |
| backend mybackend |
| mode tcp |
| balance roundrobin |
| stick-table type ip size 20k peers mypeers |
| stick on src |
| |
| server srv1 192.168.0.30:80 |
| server srv2 192.168.0.31:80 |
| |
| |
| 4. Proxies |
| ---------- |
| |
| Proxy configuration can be located in a set of sections : |
| - defaults <name> |
| - frontend <name> |
| - backend <name> |
| - listen <name> |
| |
| A "defaults" section sets default parameters for all other sections following |
| its declaration. Those default parameters are reset by the next "defaults" |
| section. See below for the list of parameters which can be set in a "defaults" |
| section. The name is optional but its use is encouraged for better readability. |
| |
| A "frontend" section describes a set of listening sockets accepting client |
| connections. |
| |
| A "backend" section describes a set of servers to which the proxy will connect |
| to forward incoming connections. |
| |
| A "listen" section defines a complete proxy with its frontend and backend |
| parts combined in one section. It is generally useful for TCP-only traffic. |
| |
| All proxy names must be formed from upper and lower case letters, digits, |
| '-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are |
| case-sensitive, which means that "www" and "WWW" are two different proxies. |
| |
| Historically, all proxy names could overlap, it just caused troubles in the |
| logs. Since the introduction of content switching, it is mandatory that two |
| proxies with overlapping capabilities (frontend/backend) have different names. |
| However, it is still permitted that a frontend and a backend share the same |
| name, as this configuration seems to be commonly encountered. |
| |
| Right now, two major proxy modes are supported : "tcp", also known as layer 4, |
| and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards |
| bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the |
| protocol, and can interact with it by allowing, blocking, switching, adding, |
| modifying, or removing arbitrary contents in requests or responses, based on |
| arbitrary criteria. |
| |
| |
| 4.1. Proxy keywords matrix |
| -------------------------- |
| |
| The following list of keywords is supported. Most of them may only be used in a |
| limited set of section types. Some of them are marked as "deprecated" because |
| they are inherited from an old syntax which may be confusing or functionally |
| limited, and there are new recommended keywords to replace them. Keywords |
| marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no |
| option contstats". This makes sense when the option has been enabled by default |
| and must be disabled for a specific instance. Such options may also be prefixed |
| with "default" in order to restore default settings regardless of what has been |
| specified in a previous "defaults" section. |
| |
| |
| keyword defaults frontend listen backend |
| ------------------------------------+----------+----------+---------+--------- |
| acl - X X X |
| appsession - - X X |
| backlog X X X - |
| balance X - X X |
| bind - X X - |
| bind-process X X X X |
| block - X X X |
| capture cookie - X X - |
| capture request header - X X - |
| capture response header - X X - |
| clitimeout (deprecated) X X X - |
| compression X X X X |
| contimeout (deprecated) X - X X |
| cookie X - X X |
| default-server X - X X |
| default_backend X X X - |
| description - X X X |
| disabled X X X X |
| dispatch - - X X |
| enabled X X X X |
| errorfile X X X X |
| errorloc X X X X |
| errorloc302 X X X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| errorloc303 X X X X |
| force-persist - X X X |
| fullconn X - X X |
| grace X X X X |
| hash-type X - X X |
| http-check disable-on-404 X - X X |
| http-check expect - - X X |
| http-check send-state X - X X |
| http-request - X X X |
| id - X X X |
| ignore-persist - X X X |
| log (*) X X X X |
| maxconn X X X - |
| mode X X X X |
| monitor fail - X X - |
| monitor-net X X X - |
| monitor-uri X X X - |
| option abortonclose (*) X - X X |
| option accept-invalid-http-request (*) X X X - |
| option accept-invalid-http-response (*) X - X X |
| option allbackups (*) X - X X |
| option checkcache (*) X - X X |
| option clitcpka (*) X X X - |
| option contstats (*) X X X - |
| option dontlog-normal (*) X X X - |
| option dontlognull (*) X X X - |
| option forceclose (*) X X X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| option forwardfor X X X X |
| option http-no-delay (*) X X X X |
| option http-pretend-keepalive (*) X X X X |
| option http-server-close (*) X X X X |
| option http-use-proxy-header (*) X X X - |
| option httpchk X - X X |
| option httpclose (*) X X X X |
| option httplog X X X X |
| option http_proxy (*) X X X X |
| option independent-streams (*) X X X X |
| option ldap-check X - X X |
| option log-health-checks (*) X - X X |
| option log-separate-errors (*) X X X - |
| option logasap (*) X X X - |
| option mysql-check X - X X |
| option pgsql-check X - X X |
| option nolinger (*) X X X X |
| option originalto X X X X |
| option persist (*) X - X X |
| option redispatch (*) X - X X |
| option redis-check X - X X |
| option smtpchk X - X X |
| option socket-stats (*) X X X - |
| option splice-auto (*) X X X X |
| option splice-request (*) X X X X |
| option splice-response (*) X X X X |
| option srvtcpka (*) X - X X |
| option ssl-hello-chk X - X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| option tcp-smart-accept (*) X X X - |
| option tcp-smart-connect (*) X - X X |
| option tcpka X X X X |
| option tcplog X X X X |
| option transparent (*) X - X X |
| persist rdp-cookie X - X X |
| rate-limit sessions X X X - |
| redirect - X X X |
| redisp (deprecated) X - X X |
| redispatch (deprecated) X - X X |
| reqadd - X X X |
| reqallow - X X X |
| reqdel - X X X |
| reqdeny - X X X |
| reqiallow - X X X |
| reqidel - X X X |
| reqideny - X X X |
| reqipass - X X X |
| reqirep - X X X |
| reqisetbe - X X X |
| reqitarpit - X X X |
| reqpass - X X X |
| reqrep - X X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| reqsetbe - X X X |
| reqtarpit - X X X |
| retries X - X X |
| rspadd - X X X |
| rspdel - X X X |
| rspdeny - X X X |
| rspidel - X X X |
| rspideny - X X X |
| rspirep - X X X |
| rsprep - X X X |
| server - - X X |
| source X - X X |
| srvtimeout (deprecated) X - X X |
| stats admin - - X X |
| stats auth X - X X |
| stats enable X - X X |
| stats hide-version X - X X |
| stats http-request - - X X |
| stats realm X - X X |
| stats refresh X - X X |
| stats scope X - X X |
| stats show-desc X - X X |
| stats show-legends X - X X |
| stats show-node X - X X |
| stats uri X - X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| stick match - - X X |
| stick on - - X X |
| stick store-request - - X X |
| stick store-response - - X X |
| stick-table - - X X |
| tcp-request connection - X X - |
| tcp-request content - X X X |
| tcp-request inspect-delay - X X X |
| tcp-response content - - X X |
| tcp-response inspect-delay - - X X |
| timeout check X - X X |
| timeout client X X X - |
| timeout clitimeout (deprecated) X X X - |
| timeout connect X - X X |
| timeout contimeout (deprecated) X - X X |
| timeout http-keep-alive X X X X |
| timeout http-request X X X X |
| timeout queue X - X X |
| timeout server X - X X |
| timeout srvtimeout (deprecated) X - X X |
| timeout tarpit X X X X |
| timeout tunnel X - X X |
| transparent (deprecated) X - X X |
| unique-id-format X X X - |
| unique-id-header X X X - |
| use_backend - X X - |
| use-server - - X X |
| ------------------------------------+----------+----------+---------+--------- |
| keyword defaults frontend listen backend |
| |
| |
| 4.2. Alphabetically sorted keywords reference |
| --------------------------------------------- |
| |
| This section provides a description of each keyword and its usage. |
| |
| |
| acl <aclname> <criterion> [flags] [operator] <value> ... |
| Declare or complete an access list. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Example: |
| acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| acl invalid_src src_port 0:1023 |
| acl local_dst hdr(host) -i localhost |
| |
| See section 7 about ACL usage. |
| |
| |
| appsession <cookie> len <length> timeout <holdtime> |
| [request-learn] [prefix] [mode <path-parameters|query-string>] |
| Define session stickiness on an existing application cookie. |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| Arguments : |
| <cookie> this is the name of the cookie used by the application and which |
| HAProxy will have to learn for each new session. |
| |
| <length> this is the max number of characters that will be memorized and |
| checked in each cookie value. |
| |
| <holdtime> this is the time after which the cookie will be removed from |
| memory if unused. If no unit is specified, this time is in |
| milliseconds. |
| |
| request-learn |
| If this option is specified, then haproxy will be able to learn |
| the cookie found in the request in case the server does not |
| specify any in response. This is typically what happens with |
| PHPSESSID cookies, or when haproxy's session expires before |
| the application's session and the correct server is selected. |
| It is recommended to specify this option to improve reliability. |
| |
| prefix When this option is specified, haproxy will match on the cookie |
| prefix (or URL parameter prefix). The appsession value is the |
| data following this prefix. |
| |
| Example : |
| appsession ASPSESSIONID len 64 timeout 3h prefix |
| |
| This will match the cookie ASPSESSIONIDXXXX=XXXXX, |
| the appsession value will be XXXX=XXXXX. |
| |
| mode This option allows to change the URL parser mode. |
| 2 modes are currently supported : |
| - path-parameters : |
| The parser looks for the appsession in the path parameters |
| part (each parameter is separated by a semi-colon), which is |
| convenient for JSESSIONID for example. |
| This is the default mode if the option is not set. |
| - query-string : |
| In this mode, the parser will look for the appsession in the |
| query string. |
| |
| When an application cookie is defined in a backend, HAProxy will check when |
| the server sets such a cookie, and will store its value in a table, and |
| associate it with the server's identifier. Up to <length> characters from |
| the value will be retained. On each connection, haproxy will look for this |
| cookie both in the "Cookie:" headers, and as a URL parameter (depending on |
| the mode used). If a known value is found, the client will be directed to the |
| server associated with this value. Otherwise, the load balancing algorithm is |
| applied. Cookies are automatically removed from memory when they have been |
| unused for a duration longer than <holdtime>. |
| |
| The definition of an application cookie is limited to one per backend. |
| |
| Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| unless you know what you do : memory is not shared between the |
| processes, which can result in random behaviours. |
| |
| Example : |
| appsession JSESSIONID len 52 timeout 3h |
| |
| See also : "cookie", "capture cookie", "balance", "stick", "stick-table", |
| "ignore-persist", "nbproc" and "bind-process". |
| |
| |
| backlog <conns> |
| Give hints to the system about the approximate listen backlog desired size |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <conns> is the number of pending connections. Depending on the operating |
| system, it may represent the number of already acknowledged |
| connections, of non-acknowledged ones, or both. |
| |
| In order to protect against SYN flood attacks, one solution is to increase |
| the system's SYN backlog size. Depending on the system, sometimes it is just |
| tunable via a system parameter, sometimes it is not adjustable at all, and |
| sometimes the system relies on hints given by the application at the time of |
| the listen() syscall. By default, HAProxy passes the frontend's maxconn value |
| to the listen() syscall. On systems which can make use of this value, it can |
| sometimes be useful to be able to specify a different value, hence this |
| backlog parameter. |
| |
| On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is |
| used as a hint and the system accepts up to the smallest greater power of |
| two, and never more than some limits (usually 32768). |
| |
| See also : "maxconn" and the target operating system's tuning guide. |
| |
| |
| balance <algorithm> [ <arguments> ] |
| balance url_param <param> [check_post [<max_wait>]] |
| Define the load balancing algorithm to be used in a backend. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <algorithm> is the algorithm used to select a server when doing load |
| balancing. This only applies when no persistence information |
| is available, or when a connection is redispatched to another |
| server. <algorithm> may be one of the following : |
| |
| roundrobin Each server is used in turns, according to their weights. |
| This is the smoothest and fairest algorithm when the server's |
| processing time remains equally distributed. This algorithm |
| is dynamic, which means that server weights may be adjusted |
| on the fly for slow starts for instance. It is limited by |
| design to 4128 active servers per backend. Note that in some |
| large farms, when a server becomes up after having been down |
| for a very short time, it may sometimes take a few hundreds |
| requests for it to be re-integrated into the farm and start |
| receiving traffic. This is normal, though very rare. It is |
| indicated here in case you would have the chance to observe |
| it, so that you don't worry. |
| |
| static-rr Each server is used in turns, according to their weights. |
| This algorithm is as similar to roundrobin except that it is |
| static, which means that changing a server's weight on the |
| fly will have no effect. On the other hand, it has no design |
| limitation on the number of servers, and when a server goes |
| up, it is always immediately reintroduced into the farm, once |
| the full map is recomputed. It also uses slightly less CPU to |
| run (around -1%). |
| |
| leastconn The server with the lowest number of connections receives the |
| connection. Round-robin is performed within groups of servers |
| of the same load to ensure that all servers will be used. Use |
| of this algorithm is recommended where very long sessions are |
| expected, such as LDAP, SQL, TSE, etc... but is not very well |
| suited for protocols using short sessions such as HTTP. This |
| algorithm is dynamic, which means that server weights may be |
| adjusted on the fly for slow starts for instance. |
| |
| first The first server with available connection slots receives the |
| connection. The servers are choosen from the lowest numeric |
| identifier to the highest (see server parameter "id"), which |
| defaults to the server's position in the farm. Once a server |
| reaches its maxconn value, the next server is used. It does |
| not make sense to use this algorithm without setting maxconn. |
| The purpose of this algorithm is to always use the smallest |
| number of servers so that extra servers can be powered off |
| during non-intensive hours. This algorithm ignores the server |
| weight, and brings more benefit to long session such as RDP |
| or IMAP than HTTP, though it can be useful there too. In |
| order to use this algorithm efficiently, it is recommended |
| that a cloud controller regularly checks server usage to turn |
| them off when unused, and regularly checks backend queue to |
| turn new servers on when the queue inflates. Alternatively, |
| using "http-check send-state" may inform servers on the load. |
| |
| source The source IP address is hashed and divided by the total |
| weight of the running servers to designate which server will |
| receive the request. This ensures that the same client IP |
| address will always reach the same server as long as no |
| server goes down or up. If the hash result changes due to the |
| number of running servers changing, many clients will be |
| directed to a different server. This algorithm is generally |
| used in TCP mode where no cookie may be inserted. It may also |
| be used on the Internet to provide a best-effort stickiness |
| to clients which refuse session cookies. This algorithm is |
| static by default, which means that changing a server's |
| weight on the fly will have no effect, but this can be |
| changed using "hash-type". |
| |
| uri This algorithm hashes either the left part of the URI (before |
| the question mark) or the whole URI (if the "whole" parameter |
| is present) and divides the hash value by the total weight of |
| the running servers. The result designates which server will |
| receive the request. This ensures that the same URI will |
| always be directed to the same server as long as no server |
| goes up or down. This is used with proxy caches and |
| anti-virus proxies in order to maximize the cache hit rate. |
| Note that this algorithm may only be used in an HTTP backend. |
| This algorithm is static by default, which means that |
| changing a server's weight on the fly will have no effect, |
| but this can be changed using "hash-type". |
| |
| This algorithm supports two optional parameters "len" and |
| "depth", both followed by a positive integer number. These |
| options may be helpful when it is needed to balance servers |
| based on the beginning of the URI only. The "len" parameter |
| indicates that the algorithm should only consider that many |
| characters at the beginning of the URI to compute the hash. |
| Note that having "len" set to 1 rarely makes sense since most |
| URIs start with a leading "/". |
| |
| The "depth" parameter indicates the maximum directory depth |
| to be used to compute the hash. One level is counted for each |
| slash in the request. If both parameters are specified, the |
| evaluation stops when either is reached. |
| |
| url_param The URL parameter specified in argument will be looked up in |
| the query string of each HTTP GET request. |
| |
| If the modifier "check_post" is used, then an HTTP POST |
| request entity will be searched for the parameter argument, |
| when it is not found in a query string after a question mark |
| ('?') in the URL. Optionally, specify a number of octets to |
| wait for before attempting to search the message body. If the |
| entity can not be searched, then round robin is used for each |
| request. For instance, if your clients always send the LB |
| parameter in the first 128 bytes, then specify that. The |
| default is 48. The entity data will not be scanned until the |
| required number of octets have arrived at the gateway, this |
| is the minimum of: (default/max_wait, Content-Length or first |
| chunk length). If Content-Length is missing or zero, it does |
| not need to wait for more data than the client promised to |
| send. When Content-Length is present and larger than |
| <max_wait>, then waiting is limited to <max_wait> and it is |
| assumed that this will be enough data to search for the |
| presence of the parameter. In the unlikely event that |
| Transfer-Encoding: chunked is used, only the first chunk is |
| scanned. Parameter values separated by a chunk boundary, may |
| be randomly balanced if at all. |
| |
| If the parameter is found followed by an equal sign ('=') and |
| a value, then the value is hashed and divided by the total |
| weight of the running servers. The result designates which |
| server will receive the request. |
| |
| This is used to track user identifiers in requests and ensure |
| that a same user ID will always be sent to the same server as |
| long as no server goes up or down. If no value is found or if |
| the parameter is not found, then a round robin algorithm is |
| applied. Note that this algorithm may only be used in an HTTP |
| backend. This algorithm is static by default, which means |
| that changing a server's weight on the fly will have no |
| effect, but this can be changed using "hash-type". |
| |
| hdr(<name>) The HTTP header <name> will be looked up in each HTTP |
| request. Just as with the equivalent ACL 'hdr()' function, |
| the header name in parenthesis is not case sensitive. If the |
| header is absent or if it does not contain any value, the |
| roundrobin algorithm is applied instead. |
| |
| An optional 'use_domain_only' parameter is available, for |
| reducing the hash algorithm to the main domain part with some |
| specific headers such as 'Host'. For instance, in the Host |
| value "haproxy.1wt.eu", only "1wt" will be considered. |
| |
| This algorithm is static by default, which means that |
| changing a server's weight on the fly will have no effect, |
| but this can be changed using "hash-type". |
| |
| rdp-cookie |
| rdp-cookie(<name>) |
| The RDP cookie <name> (or "mstshash" if omitted) will be |
| looked up and hashed for each incoming TCP request. Just as |
| with the equivalent ACL 'req_rdp_cookie()' function, the name |
| is not case-sensitive. This mechanism is useful as a degraded |
| persistence mode, as it makes it possible to always send the |
| same user (or the same session ID) to the same server. If the |
| cookie is not found, the normal roundrobin algorithm is |
| used instead. |
| |
| Note that for this to work, the frontend must ensure that an |
| RDP cookie is already present in the request buffer. For this |
| you must use 'tcp-request content accept' rule combined with |
| a 'req_rdp_cookie_cnt' ACL. |
| |
| This algorithm is static by default, which means that |
| changing a server's weight on the fly will have no effect, |
| but this can be changed using "hash-type". |
| |
| See also the rdp_cookie pattern fetch function. |
| |
| <arguments> is an optional list of arguments which may be needed by some |
| algorithms. Right now, only "url_param" and "uri" support an |
| optional argument. |
| |
| balance uri [len <len>] [depth <depth>] |
| balance url_param <param> [check_post [<max_wait>]] |
| |
| The load balancing algorithm of a backend is set to roundrobin when no other |
| algorithm, mode nor option have been set. The algorithm may only be set once |
| for each backend. |
| |
| Examples : |
| balance roundrobin |
| balance url_param userid |
| balance url_param session_id check_post 64 |
| balance hdr(User-Agent) |
| balance hdr(host) |
| balance hdr(Host) use_domain_only |
| |
| Note: the following caveats and limitations on using the "check_post" |
| extension with "url_param" must be considered : |
| |
| - all POST requests are eligible for consideration, because there is no way |
| to determine if the parameters will be found in the body or entity which |
| may contain binary data. Therefore another method may be required to |
| restrict consideration of POST requests that have no URL parameters in |
| the body. (see acl reqideny http_end) |
| |
| - using a <max_wait> value larger than the request buffer size does not |
| make sense and is useless. The buffer size is set at build time, and |
| defaults to 16 kB. |
| |
| - Content-Encoding is not supported, the parameter search will probably |
| fail; and load balancing will fall back to Round Robin. |
| |
| - Expect: 100-continue is not supported, load balancing will fall back to |
| Round Robin. |
| |
| - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk. |
| If the entire parameter value is not present in the first chunk, the |
| selection of server is undefined (actually, defined by how little |
| actually appeared in the first chunk). |
| |
| - This feature does not support generation of a 100, 411 or 501 response. |
| |
| - In some cases, requesting "check_post" MAY attempt to scan the entire |
| contents of a message body. Scanning normally terminates when linear |
| white space or control characters are found, indicating the end of what |
| might be a URL parameter list. This is probably not a concern with SGML |
| type message bodies. |
| |
| See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and |
| "http_proxy". |
| |
| |
| bind [<address>]:<port_range> [, ...] [param*] |
| bind /<path> [, ...] [param*] |
| Define one or several listening addresses and/or ports in a frontend. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <address> is optional and can be a host name, an IPv4 address, an IPv6 |
| address, or '*'. It designates the address the frontend will |
| listen on. If unset, all IPv4 addresses of the system will be |
| listened on. The same will apply for '*' or the system's |
| special address "0.0.0.0". The IPv6 equivalent is '::'. |
| |
| <port_range> is either a unique TCP port, or a port range for which the |
| proxy will accept connections for the IP address specified |
| above. The port is mandatory for TCP listeners. Note that in |
| the case of an IPv6 address, the port is always the number |
| after the last colon (':'). A range can either be : |
| - a numerical port (ex: '80') |
| - a dash-delimited ports range explicitly stating the lower |
| and upper bounds (ex: '2000-2100') which are included in |
| the range. |
| |
| Particular care must be taken against port ranges, because |
| every <address:port> couple consumes one socket (= a file |
| descriptor), so it's easy to consume lots of descriptors |
| with a simple range, and to run out of sockets. Also, each |
| <address:port> couple must be used only once among all |
| instances running on a same system. Please note that binding |
| to ports lower than 1024 generally require particular |
| privileges to start the program, which are independent of |
| the 'uid' parameter. |
| |
| <path> is a UNIX socket path beginning with a slash ('/'). This is |
| alternative to the TCP listening port. Haproxy will then |
| receive UNIX connections on the socket located at this place. |
| The path must begin with a slash and by default is absolute. |
| It can be relative to the prefix defined by "unix-bind" in |
| the global section. Note that the total length of the prefix |
| followed by the socket path cannot exceed some system limits |
| for UNIX sockets, which commonly are set to 107 characters. |
| |
| <param*> is a list of parameters common to all sockets declared on the |
| same line. These numerous parameters depend on OS and build |
| options and have a complete section dedicated to them. Please |
| refer to section 5 to for more details. |
| |
| It is possible to specify a list of address:port combinations delimited by |
| commas. The frontend will then listen on all of these addresses. There is no |
| fixed limit to the number of addresses and ports which can be listened on in |
| a frontend, as well as there is no limit to the number of "bind" statements |
| in a frontend. |
| |
| Example : |
| listen http_proxy |
| bind :80,:443 |
| bind 10.0.0.1:10080,10.0.0.1:10443 |
| bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy |
| |
| listen http_https_proxy |
| bind :80 |
| bind :443 ssl crt /etc/haproxy/site.pem |
| |
| See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol |
| documentation, and section 5 about bind options. |
| |
| |
| bind-process [ all | odd | even | <number 1-32>[-<number 1-32>] ] ... |
| Limit visibility of an instance to a certain set of processes numbers. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| all All process will see this instance. This is the default. It |
| may be used to override a default value. |
| |
| odd This instance will be enabled on processes 1,3,5,...31. This |
| option may be combined with other numbers. |
| |
| even This instance will be enabled on processes 2,4,6,...32. This |
| option may be combined with other numbers. Do not use it |
| with less than 2 processes otherwise some instances might be |
| missing from all processes. |
| |
| number The instance will be enabled on this process number or range, |
| whose values must all be between 1 and 32. You must be |
| careful not to reference a process number greater than the |
| configured global.nbproc, otherwise some instances might be |
| missing from all processes. |
| |
| This keyword limits binding of certain instances to certain processes. This |
| is useful in order not to have too many processes listening to the same |
| ports. For instance, on a dual-core machine, it might make sense to set |
| 'nbproc 2' in the global section, then distributes the listeners among 'odd' |
| and 'even' instances. |
| |
| At the moment, it is not possible to reference more than 32 processes using |
| this keyword, but this should be more than enough for most setups. Please |
| note that 'all' really means all processes and is not limited to the first |
| 32. |
| |
| If some backends are referenced by frontends bound to other processes, the |
| backend automatically inherits the frontend's processes. |
| |
| Example : |
| listen app_ip1 |
| bind 10.0.0.1:80 |
| bind-process odd |
| |
| listen app_ip2 |
| bind 10.0.0.2:80 |
| bind-process even |
| |
| listen management |
| bind 10.0.0.3:80 |
| bind-process 1 2 3 4 |
| |
| listen management |
| bind 10.0.0.4:80 |
| bind-process 1-4 |
| |
| See also : "nbproc" in global section. |
| |
| |
| block { if | unless } <condition> |
| Block a layer 7 request if/unless a condition is matched |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| The HTTP request will be blocked very early in the layer 7 processing |
| if/unless <condition> is matched. A 403 error will be returned if the request |
| is blocked. The condition has to reference ACLs (see section 7). This is |
| typically used to deny access to certain sensitive resources if some |
| conditions are met or not met. There is no fixed limit to the number of |
| "block" statements per instance. |
| |
| Example: |
| acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| acl invalid_src src_port 0:1023 |
| acl local_dst hdr(host) -i localhost |
| block if invalid_src || local_dst |
| |
| See section 7 about ACL usage. |
| |
| |
| capture cookie <name> len <length> |
| Capture and log a cookie in the request and in the response. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <name> is the beginning of the name of the cookie to capture. In order |
| to match the exact name, simply suffix the name with an equal |
| sign ('='). The full name will appear in the logs, which is |
| useful with application servers which adjust both the cookie name |
| and value (eg: ASPSESSIONXXXXX). |
| |
| <length> is the maximum number of characters to report in the logs, which |
| include the cookie name, the equal sign and the value, all in the |
| standard "name=value" form. The string will be truncated on the |
| right if it exceeds <length>. |
| |
| Only the first cookie is captured. Both the "cookie" request headers and the |
| "set-cookie" response headers are monitored. This is particularly useful to |
| check for application bugs causing session crossing or stealing between |
| users, because generally the user's cookies can only change on a login page. |
| |
| When the cookie was not presented by the client, the associated log column |
| will report "-". When a request does not cause a cookie to be assigned by the |
| server, a "-" is reported in the response column. |
| |
| The capture is performed in the frontend only because it is necessary that |
| the log format does not change for a given frontend depending on the |
| backends. This may change in the future. Note that there can be only one |
| "capture cookie" statement in a frontend. The maximum capture length is |
| configured in the sources by default to 64 characters. It is not possible to |
| specify a capture in a "defaults" section. |
| |
| Example: |
| capture cookie ASPSESSION len 32 |
| |
| See also : "capture request header", "capture response header" as well as |
| section 8 about logging. |
| |
| |
| capture request header <name> len <length> |
| Capture and log the first occurrence of the specified request header. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <name> is the name of the header to capture. The header names are not |
| case-sensitive, but it is a common practice to write them as they |
| appear in the requests, with the first letter of each word in |
| upper case. The header name will not appear in the logs, only the |
| value is reported, but the position in the logs is respected. |
| |
| <length> is the maximum number of characters to extract from the value and |
| report in the logs. The string will be truncated on the right if |
| it exceeds <length>. |
| |
| Only the first value of the last occurrence of the header is captured. The |
| value will be added to the logs between braces ('{}'). If multiple headers |
| are captured, they will be delimited by a vertical bar ('|') and will appear |
| in the same order they were declared in the configuration. Non-existent |
| headers will be logged just as an empty string. Common uses for request |
| header captures include the "Host" field in virtual hosting environments, the |
| "Content-length" when uploads are supported, "User-agent" to quickly |
| differentiate between real users and robots, and "X-Forwarded-For" in proxied |
| environments to find where the request came from. |
| |
| Note that when capturing headers such as "User-agent", some spaces may be |
| logged, making the log analysis more difficult. Thus be careful about what |
| you log if you know your log parser is not smart enough to rely on the |
| braces. |
| |
| There is no limit to the number of captured request headers, but each capture |
| is limited to 64 characters. In order to keep log format consistent for a |
| same frontend, header captures can only be declared in a frontend. It is not |
| possible to specify a capture in a "defaults" section. |
| |
| Example: |
| capture request header Host len 15 |
| capture request header X-Forwarded-For len 15 |
| capture request header Referrer len 15 |
| |
| See also : "capture cookie", "capture response header" as well as section 8 |
| about logging. |
| |
| |
| capture response header <name> len <length> |
| Capture and log the first occurrence of the specified response header. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <name> is the name of the header to capture. The header names are not |
| case-sensitive, but it is a common practice to write them as they |
| appear in the response, with the first letter of each word in |
| upper case. The header name will not appear in the logs, only the |
| value is reported, but the position in the logs is respected. |
| |
| <length> is the maximum number of characters to extract from the value and |
| report in the logs. The string will be truncated on the right if |
| it exceeds <length>. |
| |
| Only the first value of the last occurrence of the header is captured. The |
| result will be added to the logs between braces ('{}') after the captured |
| request headers. If multiple headers are captured, they will be delimited by |
| a vertical bar ('|') and will appear in the same order they were declared in |
| the configuration. Non-existent headers will be logged just as an empty |
| string. Common uses for response header captures include the "Content-length" |
| header which indicates how many bytes are expected to be returned, the |
| "Location" header to track redirections. |
| |
| There is no limit to the number of captured response headers, but each |
| capture is limited to 64 characters. In order to keep log format consistent |
| for a same frontend, header captures can only be declared in a frontend. It |
| is not possible to specify a capture in a "defaults" section. |
| |
| Example: |
| capture response header Content-length len 9 |
| capture response header Location len 15 |
| |
| See also : "capture cookie", "capture request header" as well as section 8 |
| about logging. |
| |
| |
| clitimeout <timeout> (deprecated) |
| Set the maximum inactivity time on the client side. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <timeout> is the timeout value is specified in milliseconds by default, but |
| can be in any other unit if the number is suffixed by the unit, |
| as explained at the top of this document. |
| |
| The inactivity timeout applies when the client is expected to acknowledge or |
| send data. In HTTP mode, this timeout is particularly important to consider |
| during the first phase, when the client sends the request, and during the |
| response while it is reading data sent by the server. The value is specified |
| in milliseconds by default, but can be in any other unit if the number is |
| suffixed by the unit, as specified at the top of this document. In TCP mode |
| (and to a lesser extent, in HTTP mode), it is highly recommended that the |
| client timeout remains equal to the server timeout in order to avoid complex |
| situations to debug. It is a good practice to cover one or several TCP packet |
| losses by specifying timeouts that are slightly above multiples of 3 seconds |
| (eg: 4 or 5 seconds). |
| |
| This parameter is specific to frontends, but can be specified once for all in |
| "defaults" sections. This is in fact one of the easiest solutions not to |
| forget about it. An unspecified timeout results in an infinite timeout, which |
| is not recommended. Such a usage is accepted and works but reports a warning |
| during startup because it may results in accumulation of expired sessions in |
| the system if the system's timeouts are not configured either. |
| |
| This parameter is provided for compatibility but is currently deprecated. |
| Please use "timeout client" instead. |
| |
| See also : "timeout client", "timeout http-request", "timeout server", and |
| "srvtimeout". |
| |
| compression algo <algorithm> ... |
| compression type <mime type> ... |
| compression offload |
| Enable HTTP compression. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| algo is followed by the list of supported compression algorithms. |
| type is followed by the list of MIME types that will be compressed. |
| offload makes haproxy work as a compression offloader only (see notes). |
| |
| The currently supported algorithms are : |
| identity this is mostly for debugging, and it was useful for developping |
| the compression feature. Identity does not apply any change on |
| data. |
| |
| gzip applies gzip compression. This setting is only available when |
| support for zlib was built in. |
| |
| deflate same as gzip, but with deflate algorithm and zlib format. |
| Note that this algorithm has ambiguous support on many browsers |
| and no support at all from recent ones. It is strongly |
| recommended not to use it for anything else than experimentation. |
| This setting is only available when support for zlib was built |
| in. |
| |
| Compression will be activated depending of the Accept-Encoding request |
| header. With identity, it does not take care of that header. |
| |
| The "offload" setting makes haproxy remove the Accept-Encoding header to |
| prevent backend servers from compressing responses. It is strongly |
| recommended not to do this because this means that all the compression work |
| will be done on the single point where haproxy is located. However in some |
| deployment scenarios, haproxy may be installed in front of a buggy gateway |
| and need to prevent it from emitting invalid payloads. In this case, simply |
| removing the header in the configuration does not work because it applies |
| before the header is parsed, so that prevents haproxy from compressing. The |
| "offload" setting should then be used for such scenarios. |
| |
| Examples : |
| compression algo gzip |
| compression type text/html text/plain |
| |
| contimeout <timeout> (deprecated) |
| Set the maximum time to wait for a connection attempt to a server to succeed. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <timeout> is the timeout value is specified in milliseconds by default, but |
| can be in any other unit if the number is suffixed by the unit, |
| as explained at the top of this document. |
| |
| If the server is located on the same LAN as haproxy, the connection should be |
| immediate (less than a few milliseconds). Anyway, it is a good practice to |
| cover one or several TCP packet losses by specifying timeouts that are |
| slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the |
| connect timeout also presets the queue timeout to the same value if this one |
| has not been specified. Historically, the contimeout was also used to set the |
| tarpit timeout in a listen section, which is not possible in a pure frontend. |
| |
| This parameter is specific to backends, but can be specified once for all in |
| "defaults" sections. This is in fact one of the easiest solutions not to |
| forget about it. An unspecified timeout results in an infinite timeout, which |
| is not recommended. Such a usage is accepted and works but reports a warning |
| during startup because it may results in accumulation of failed sessions in |
| the system if the system's timeouts are not configured either. |
| |
| This parameter is provided for backwards compatibility but is currently |
| deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit" |
| instead. |
| |
| See also : "timeout connect", "timeout queue", "timeout tarpit", |
| "timeout server", "contimeout". |
| |
| |
| cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ] |
| [ postonly ] [ preserve ] [ httponly ] [ secure ] |
| [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ] |
| Enable cookie-based persistence in a backend. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <name> is the name of the cookie which will be monitored, modified or |
| inserted in order to bring persistence. This cookie is sent to |
| the client via a "Set-Cookie" header in the response, and is |
| brought back by the client in a "Cookie" header in all requests. |
| Special care should be taken to choose a name which does not |
| conflict with any likely application cookie. Also, if the same |
| backends are subject to be used by the same clients (eg: |
| HTTP/HTTPS), care should be taken to use different cookie names |
| between all backends if persistence between them is not desired. |
| |
| rewrite This keyword indicates that the cookie will be provided by the |
| server and that haproxy will have to modify its value to set the |
| server's identifier in it. This mode is handy when the management |
| of complex combinations of "Set-cookie" and "Cache-control" |
| headers is left to the application. The application can then |
| decide whether or not it is appropriate to emit a persistence |
| cookie. Since all responses should be monitored, this mode only |
| works in HTTP close mode. Unless the application behaviour is |
| very complex and/or broken, it is advised not to start with this |
| mode for new deployments. This keyword is incompatible with |
| "insert" and "prefix". |
| |
| insert This keyword indicates that the persistence cookie will have to |
| be inserted by haproxy in server responses if the client did not |
| |
| already have a cookie that would have permitted it to access this |
| server. When used without the "preserve" option, if the server |
| emits a cookie with the same name, it will be remove before |
| processing. For this reason, this mode can be used to upgrade |
| existing configurations running in the "rewrite" mode. The cookie |
| will only be a session cookie and will not be stored on the |
| client's disk. By default, unless the "indirect" option is added, |
| the server will see the cookies emitted by the client. Due to |
| caching effects, it is generally wise to add the "nocache" or |
| "postonly" keywords (see below). The "insert" keyword is not |
| compatible with "rewrite" and "prefix". |
| |
| prefix This keyword indicates that instead of relying on a dedicated |
| cookie for the persistence, an existing one will be completed. |
| This may be needed in some specific environments where the client |
| does not support more than one single cookie and the application |
| already needs it. In this case, whenever the server sets a cookie |
| named <name>, it will be prefixed with the server's identifier |
| and a delimiter. The prefix will be removed from all client |
| requests so that the server still finds the cookie it emitted. |
| Since all requests and responses are subject to being modified, |
| this mode requires the HTTP close mode. The "prefix" keyword is |
| not compatible with "rewrite" and "insert". Note: it is highly |
| recommended not to use "indirect" with "prefix", otherwise server |
| cookie updates would not be sent to clients. |
| |
| indirect When this option is specified, no cookie will be emitted to a |
| client which already has a valid one for the server which has |
| processed the request. If the server sets such a cookie itself, |
| it will be removed, unless the "preserve" option is also set. In |
| "insert" mode, this will additionally remove cookies from the |
| requests transmitted to the server, making the persistence |
| mechanism totally transparent from an application point of view. |
| Note: it is highly recommended not to use "indirect" with |
| "prefix", otherwise server cookie updates would not be sent to |
| clients. |
| |
| nocache This option is recommended in conjunction with the insert mode |
| when there is a cache between the client and HAProxy, as it |
| ensures that a cacheable response will be tagged non-cacheable if |
| a cookie needs to be inserted. This is important because if all |
| persistence cookies are added on a cacheable home page for |
| instance, then all customers will then fetch the page from an |
| outer cache and will all share the same persistence cookie, |
| leading to one server receiving much more traffic than others. |
| See also the "insert" and "postonly" options. |
| |
| postonly This option ensures that cookie insertion will only be performed |
| on responses to POST requests. It is an alternative to the |
| "nocache" option, because POST responses are not cacheable, so |
| this ensures that the persistence cookie will never get cached. |
| Since most sites do not need any sort of persistence before the |
| first POST which generally is a login request, this is a very |
| efficient method to optimize caching without risking to find a |
| persistence cookie in the cache. |
| See also the "insert" and "nocache" options. |
| |
| preserve This option may only be used with "insert" and/or "indirect". It |
| allows the server to emit the persistence cookie itself. In this |
| case, if a cookie is found in the response, haproxy will leave it |
| untouched. This is useful in order to end persistence after a |
| logout request for instance. For this, the server just has to |
| emit a cookie with an invalid value (eg: empty) or with a date in |
| the past. By combining this mechanism with the "disable-on-404" |
| check option, it is possible to perform a completely graceful |
| shutdown because users will definitely leave the server after |
| they logout. |
| |
| httponly This option tells haproxy to add an "HttpOnly" cookie attribute |
| when a cookie is inserted. This attribute is used so that a |
| user agent doesn't share the cookie with non-HTTP components. |
| Please check RFC6265 for more information on this attribute. |
| |
| secure This option tells haproxy to add a "Secure" cookie attribute when |
| a cookie is inserted. This attribute is used so that a user agent |
| never emits this cookie over non-secure channels, which means |
| that a cookie learned with this flag will be presented only over |
| SSL/TLS connections. Please check RFC6265 for more information on |
| this attribute. |
| |
| domain This option allows to specify the domain at which a cookie is |
| inserted. It requires exactly one parameter: a valid domain |
| name. If the domain begins with a dot, the browser is allowed to |
| use it for any host ending with that name. It is also possible to |
| specify several domain names by invoking this option multiple |
| times. Some browsers might have small limits on the number of |
| domains, so be careful when doing that. For the record, sending |
| 10 domains to MSIE 6 or Firefox 2 works as expected. |
| |
| maxidle This option allows inserted cookies to be ignored after some idle |
| time. It only works with insert-mode cookies. When a cookie is |
| sent to the client, the date this cookie was emitted is sent too. |
| Upon further presentations of this cookie, if the date is older |
| than the delay indicated by the parameter (in seconds), it will |
| be ignored. Otherwise, it will be refreshed if needed when the |
| response is sent to the client. This is particularly useful to |
| prevent users who never close their browsers from remaining for |
| too long on the same server (eg: after a farm size change). When |
| this option is set and a cookie has no date, it is always |
| accepted, but gets refreshed in the response. This maintains the |
| ability for admins to access their sites. Cookies that have a |
| date in the future further than 24 hours are ignored. Doing so |
| lets admins fix timezone issues without risking kicking users off |
| the site. |
| |
| maxlife This option allows inserted cookies to be ignored after some life |
| time, whether they're in use or not. It only works with insert |
| mode cookies. When a cookie is first sent to the client, the date |
| this cookie was emitted is sent too. Upon further presentations |
| of this cookie, if the date is older than the delay indicated by |
| the parameter (in seconds), it will be ignored. If the cookie in |
| the request has no date, it is accepted and a date will be set. |
| Cookies that have a date in the future further than 24 hours are |
| ignored. Doing so lets admins fix timezone issues without risking |
| kicking users off the site. Contrary to maxidle, this value is |
| not refreshed, only the first visit date counts. Both maxidle and |
| maxlife may be used at the time. This is particularly useful to |
| prevent users who never close their browsers from remaining for |
| too long on the same server (eg: after a farm size change). This |
| is stronger than the maxidle method in that it forces a |
| redispatch after some absolute delay. |
| |
| There can be only one persistence cookie per HTTP backend, and it can be |
| declared in a defaults section. The value of the cookie will be the value |
| indicated after the "cookie" keyword in a "server" statement. If no cookie |
| is declared for a given server, the cookie is not set. |
| |
| Examples : |
| cookie JSESSIONID prefix |
| cookie SRV insert indirect nocache |
| cookie SRV insert postonly indirect |
| cookie SRV insert indirect nocache maxidle 30m maxlife 8h |
| |
| See also : "appsession", "balance source", "capture cookie", "server" |
| and "ignore-persist". |
| |
| |
| default-server [param*] |
| Change default options for a server in a backend |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments: |
| <param*> is a list of parameters for this server. The "default-server" |
| keyword accepts an important number of options and has a complete |
| section dedicated to it. Please refer to section 5 for more |
| details. |
| |
| Example : |
| default-server inter 1000 weight 13 |
| |
| See also: "server" and section 5 about server options |
| |
| |
| default_backend <backend> |
| Specify the backend to use when no "use_backend" rule has been matched. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <backend> is the name of the backend to use. |
| |
| When doing content-switching between frontend and backends using the |
| "use_backend" keyword, it is often useful to indicate which backend will be |
| used when no rule has matched. It generally is the dynamic backend which |
| will catch all undetermined requests. |
| |
| Example : |
| |
| use_backend dynamic if url_dyn |
| 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. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| The "disabled" keyword is used to disable an instance, mainly in order to |
| liberate a listening port or to temporarily disable a service. The instance |
| will still be created and its configuration will be checked, but it will be |
| created in the "stopped" state and will appear as such in the statistics. It |
| will not receive any traffic nor will it send any health-checks or logs. It |
| is possible to disable many instances at once by adding the "disabled" |
| keyword in a "defaults" section. |
| |
| See also : "enabled" |
| |
| |
| dispatch <address>:<port> |
| Set a default server address |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| Arguments : |
| |
| <address> is the IPv4 address of the default server. Alternatively, a |
| resolvable hostname is supported, but this name will be resolved |
| during start-up. |
| |
| <ports> is a mandatory port specification. All connections will be sent |
| to this port, and it is not permitted to use port offsets as is |
| possible with normal servers. |
| |
| The "dispatch" keyword designates a default server for use when no other |
| server can take the connection. In the past it was used to forward non |
| persistent connections to an auxiliary load balancer. Due to its simple |
| syntax, it has also been used for simple TCP relays. It is recommended not to |
| use it for more clarity, and to use the "server" directive instead. |
| |
| See also : "server" |
| |
| |
| enabled |
| Enable a proxy, frontend or backend. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| The "enabled" keyword is used to explicitly enable an instance, when the |
| defaults has been set to "disabled". This is very rarely used. |
| |
| See also : "disabled" |
| |
| |
| errorfile <code> <file> |
| Return a file contents 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 200, 400, 403, 408, 500, 502, 503, and 504. |
| |
| <file> designates a file containing the full HTTP response. It is |
| recommended to follow the common practice of appending ".http" to |
| the filename so that people do not confuse the response with HTML |
| error pages, and to use absolute paths, since files are read |
| before any chroot is performed. |
| |
| 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. |
| |
| Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| |
| The files are returned verbatim on the TCP socket. This allows any trick such |
| as redirections to another URL or site, as well as tricks to clean cookies, |
| force enable or disable caching, etc... The package provides default error |
| files returning the same contents as default errors. |
| |
| The files should not exceed the configured buffer size (BUFSIZE), which |
| generally is 8 or 16 kB, otherwise they will be truncated. It is also wise |
| not to put any reference to local contents (eg: images) in order to avoid |
| loops between the client and HAProxy when all servers are down, causing an |
| error to be returned instead of an image. For better HTTP compliance, it is |
| recommended that all header lines end with CR-LF and not LF alone. |
| |
| The files are read at the same time as the configuration and kept in memory. |
| For this reason, the errors continue to be returned even when the process is |
| chrooted, and no file change is considered while the process is running. A |
| simple method for developing those files consists in associating them to the |
| 403 status code and interrogating a blocked URL. |
| |
| See also : "errorloc", "errorloc302", "errorloc303" |
| |
| Example : |
| errorfile 400 /etc/haproxy/errorfiles/400badreq.http |
| errorfile 403 /etc/haproxy/errorfiles/403forbid.http |
| errorfile 503 /etc/haproxy/errorfiles/503sorry.http |
| |
| |
| 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 200, 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. |
| |
| Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| |
| 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. |
| |
| Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| |
| 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 has been reported till now. |
| |
| See also : "errorfile", "errorloc", "errorloc302" |
| |
| |
| force-persist { if | unless } <condition> |
| Declare a condition to force persistence on down servers |
| May be used in sections: defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| By default, requests are not dispatched to down servers. It is possible to |
| force this using "option persist", but it is unconditional and redispatches |
| to a valid server if "option redispatch" is set. That leaves with very little |
| possibilities to force some requests to reach a server which is artificially |
| marked down for maintenance operations. |
| |
| The "force-persist" statement allows one to declare various ACL-based |
| conditions which, when met, will cause a request to ignore the down status of |
| a server and still try to connect to it. That makes it possible to start a |
| server, still replying an error to the health checks, and run a specially |
| configured browser to test the service. Among the handy methods, one could |
| use a specific source IP address, or a specific cookie. The cookie also has |
| the advantage that it can easily be added/removed on the browser from a test |
| page. Once the service is validated, it is then possible to open the service |
| to the world by returning a valid response to health checks. |
| |
| The forced persistence is enabled when an "if" condition is met, or unless an |
| "unless" condition is met. The final redispatch is always disabled when this |
| is used. |
| |
| See also : "option redispatch", "ignore-persist", "persist", |
| and section 7 about ACL usage. |
| |
| |
| 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 |
| exceptional loads. |
| |
| Since it's hard to get this value right, haproxy automatically sets it to |
| 10% of the sum of the maxconns of all frontends that may branch to this |
| backend. That way it's safe to leave it unset. |
| |
| 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 |
| yes | 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 equipment 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. |
| |
| |
| hash-type <method> |
| Specify a method to use for mapping hashes to servers |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| map-based the hash table is a static array containing all alive servers. |
| The hashes will be very smooth, will consider weights, but will |
| be static in that weight changes while a server is up will be |
| ignored. This means that there will be no slow start. Also, |
| since a server is selected by its position in the array, most |
| mappings are changed when the server count changes. This means |
| that when a server goes up or down, or when a server is added |
| to a farm, most connections will be redistributed to different |
| servers. This can be inconvenient with caches for instance. |
| |
| avalanche this mechanism uses the default map-based hashing described |
| above but applies a full avalanche hash before performing the |
| mapping. The result is a slightly less smooth hash for most |
| situations, but the hash becomes better than pure map-based |
| hashes when the number of servers is a multiple of the size of |
| the input set. When using URI hash with a number of servers |
| multiple of 64, it's desirable to change the hash type to |
| this value. |
| |
| consistent the hash table is a tree filled with many occurrences of each |
| server. The hash key is looked up in the tree and the closest |
| server is chosen. This hash is dynamic, it supports changing |
| weights while the servers are up, so it is compatible with the |
| slow start feature. It has the advantage that when a server |
| goes up or down, only its associations are moved. When a server |
| is added to the farm, only a few part of the mappings are |
| redistributed, making it an ideal algorithm for caches. |
| However, due to its principle, the algorithm will never be very |
| smooth and it may sometimes be necessary to adjust a server's |
| weight or its ID to get a more balanced distribution. In order |
| to get the same distribution on multiple load balancers, it is |
| important that all servers have the same IDs. |
| |
| The default hash type is "map-based" and is recommended for most usages. |
| |
| See also : "balance", "server" |
| |
| |
| 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 |
| yes | no | yes | yes |
| Arguments : none |
| |
| When this option is set, a server which returns an HTTP code 404 will be |
| excluded from further load-balancing, but will still receive persistent |
| connections. This provides a very convenient method for Web administrators |
| to perform a graceful shutdown of their servers. It is also important to note |
| that a server which is detected as failed while it was in this mode will not |
| generate an alert, just a notice. If the server responds 2xx or 3xx again, it |
| will immediately be reinserted into the farm. The status on the stats page |
| reports "NOLB" for a server in this mode. It is important to note that this |
| option only works in conjunction with the "httpchk" option. If this option |
| is used with "http-check expect", then it has precedence over it so that 404 |
| responses will still be considered as soft-stop. |
| |
| See also : "option httpchk", "http-check expect" |
| |
| |
| http-check expect [!] <match> <pattern> |
| Make HTTP health checks consider response contents or specific status codes |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <match> is a keyword indicating how to look for a specific pattern in the |
| response. The keyword may be one of "status", "rstatus", |
| "string", or "rstring". The keyword may be preceded by an |
| exclamation mark ("!") to negate the match. Spaces are allowed |
| between the exclamation mark and the keyword. See below for more |
| details on the supported keywords. |
| |
| <pattern> is the pattern to look for. It may be a string or a regular |
| expression. If the pattern contains spaces, they must be escaped |
| with the usual backslash ('\'). |
| |
| By default, "option httpchk" considers that response statuses 2xx and 3xx |
| are valid, and that others are invalid. When "http-check expect" is used, |
| it defines what is considered valid or invalid. Only one "http-check" |
| statement is supported in a backend. If a server fails to respond or times |
| out, the check obviously fails. The available matches are : |
| |
| status <string> : test the exact string match for the HTTP status code. |
| A health check response will be considered valid if the |
| response's status code is exactly this string. If the |
| "status" keyword is prefixed with "!", then the response |
| will be considered invalid if the status code matches. |
| |
| rstatus <regex> : test a regular expression for the HTTP status code. |
| A health check response will be considered valid if the |
| response's status code matches the expression. If the |
| "rstatus" keyword is prefixed with "!", then the response |
| will be considered invalid if the status code matches. |
| This is mostly used to check for multiple codes. |
| |
| string <string> : test the exact string match in the HTTP response body. |
| A health check response will be considered valid if the |
| response's body contains this exact string. If the |
| "string" keyword is prefixed with "!", then the response |
| will be considered invalid if the body contains this |
| string. This can be used to look for a mandatory word at |
| the end of a dynamic page, or to detect a failure when a |
| specific error appears on the check page (eg: a stack |
| trace). |
| |
| rstring <regex> : test a regular expression on the HTTP response body. |
| A health check response will be considered valid if the |
| response's body matches this expression. If the "rstring" |
| keyword is prefixed with "!", then the response will be |
| considered invalid if the body matches the expression. |
| This can be used to look for a mandatory word at the end |
| of a dynamic page, or to detect a failure when a specific |
| error appears on the check page (eg: a stack trace). |
| |
| It is important to note that the responses will be limited to a certain size |
| defined by the global "tune.chksize" option, which defaults to 16384 bytes. |
| Thus, too large responses may not contain the mandatory pattern when using |
| "string" or "rstring". If a large response is absolutely required, it is |
| possible to change the default max size by setting the global variable. |
| However, it is worth keeping in mind that parsing very large responses can |
| waste some CPU cycles, especially when regular expressions are used, and that |
| it is always better to focus the checks on smaller resources. |
| |
| Last, if "http-check expect" is combined with "http-check disable-on-404", |
| then this last one has precedence when the server responds with 404. |
| |
| Examples : |
| # only accept status 200 as valid |
| http-check expect status 200 |
| |
| # consider SQL errors as errors |
| http-check expect ! string SQL\ Error |
| |
| # consider status 5xx only as errors |
| http-check expect ! rstatus ^5 |
| |
| # check that we have a correct hexadecimal tag before /html |
| http-check expect rstring <!--tag:[0-9a-f]*</html> |
| |
| See also : "option httpchk", "http-check disable-on-404" |
| |
| |
| http-check send-state |
| Enable emission of a state header with HTTP health checks |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| When this option is set, haproxy will systematically send a special header |
| "X-Haproxy-Server-State" with a list of parameters indicating to each server |
| how they are seen by haproxy. This can be used for instance when a server is |
| manipulated without access to haproxy and the operator needs to know whether |
| haproxy still sees it up or not, or if the server is the last one in a farm. |
| |
| The header is composed of fields delimited by semi-colons, the first of which |
| is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid |
| checks on the total number before transition, just as appears in the stats |
| interface. Next headers are in the form "<variable>=<value>", indicating in |
| no specific order some values available in the stats interface : |
| - a variable "name", containing the name of the backend followed by a slash |
| ("/") then the name of the server. This can be used when a server is |
| checked in multiple backends. |
| |
| - a variable "node" containing the name of the haproxy node, as set in the |
| global "node" variable, otherwise the system's hostname if unspecified. |
| |
| - a variable "weight" indicating the weight of the server, a slash ("/") |
| and the total weight of the farm (just counting usable servers). This |
| helps to know if other servers are available to handle the load when this |
| one fails. |
| |
| - a variable "scur" indicating the current number of concurrent connections |
| on the server, followed by a slash ("/") then the total number of |
| connections on all servers of the same backend. |
| |
| - a variable "qcur" indicating the current number of requests in the |
| server's queue. |
| |
| Example of a header received by the application server : |
| >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \ |
| scur=13/22; qcur=0 |
| |
| See also : "option httpchk", "http-check disable-on-404" |
| |
| http-request { allow | deny | auth [realm <realm>] } |
| [ { if | unless } <condition> ] |
| Access control for Layer 7 requests |
| |
| May be used in sections: defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| These set of options allow to fine control access to a |
| frontend/listen/backend. Each option may be followed by if/unless and acl. |
| First option with matched condition (or option without condition) is final. |
| For "deny" a 403 error will be returned, for "allow" normal processing is |
| performed, for "auth" a 401/407 error code is returned so the client |
| should be asked to enter a username and password. |
| |
| There is no fixed limit to the number of http-request statements per |
| instance. |
| |
| Example: |
| acl nagios src 192.168.129.3 |
| acl local_net src 192.168.0.0/16 |
| acl auth_ok http_auth(L1) |
| |
| http-request allow if nagios |
| http-request allow if local_net auth_ok |
| http-request auth realm Gimme if local_net auth_ok |
| http-request deny |
| |
| Example: |
| acl auth_ok http_auth_group(L1) G1 |
| |
| http-request auth unless auth_ok |
| |
| See also : "stats http-request", section 3.4 about userlists and section 7 |
| about ACL usage. |
| |
| http-send-name-header [<header>] |
| Add the server name to a request. Use the header string given by <header> |
| |
| May be used in sections: defaults | frontend | listen | backend |
| yes | no | yes | yes |
| |
| Arguments : |
| |
| <header> The header string to use to send the server name |
| |
| The "http-send-name-header" statement causes the name of the target |
| server to be added to the headers of an HTTP request. The name |
| is added with the header string proved. |
| |
| See also : "server" |
| |
| id <value> |
| Set a persistent ID to a proxy. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : none |
| |
| Set a persistent ID for the proxy. This ID must be unique and positive. |
| An unused ID will automatically be assigned if unset. The first assigned |
| value will be 1. This ID is currently only returned in statistics. |
| |
| |
| ignore-persist { if | unless } <condition> |
| Declare a condition to ignore persistence |
| May be used in sections: defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| By default, when cookie persistence is enabled, every requests containing |
| the cookie are unconditionally persistent (assuming the target server is up |
| and running). |
| |
| The "ignore-persist" statement allows one to declare various ACL-based |
| conditions which, when met, will cause a request to ignore persistence. |
| This is sometimes useful to load balance requests for static files, which |
| oftenly don't require persistence. This can also be used to fully disable |
| persistence for a specific User-Agent (for example, some web crawler bots). |
| |
| Combined with "appsession", it can also help reduce HAProxy memory usage, as |
| the appsession table won't grow if persistence is ignored. |
| |
| The persistence is ignored when an "if" condition is met, or unless an |
| "unless" condition is met. |
| |
| See also : "force-persist", "cookie", and section 7 about ACL usage. |
| |
| |
| log global |
| log <address> <facility> [<level> [<minlevel>]] |
| no log |
| Enable per-instance logging of events and traffic. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| |
| Prefix : |
| no should be used when the logger list must be flushed. For example, |
| if you don't want to inherit from the default logger list. This |
| prefix does not allow arguments. |
| |
| 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). |
| |
| - An IPv6 address followed by a colon (':') and optionally 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. An optional minimum level can be specified. If it |
| is set, logs emitted with a more severe level than this one will |
| be capped to this level. This is used to avoid sending "emerg" |
| messages on all terminals on some default syslog configurations. |
| Eight levels are known : |
| |
| emerg alert crit err warning notice info debug |
| |
| It is important to keep in mind that it is the frontend which decides what to |
| log from a connection, and that in case of content switching, the log entries |
| from the backend will be ignored. Connections are logged at level "info". |
| |
| However, backend log declaration define how and where servers status changes |
| will be logged. Level "notice" will be used to indicate a server going up, |
| "warning" will be used for termination signals and definitive service |
| termination, and "alert" will be used for when a server goes down. |
| |
| Note : According to RFC3164, messages are truncated to 1024 bytes before |
| being emitted. |
| |
| Example : |
| log global |
| log 127.0.0.1:514 local0 notice # only send important events |
| log 127.0.0.1:514 local0 notice notice # same but limit output level |
| |
| log-format <string> |
| Allows you to custom a log line. |
| |
| See also : Custom Log Format (8.2.4) |
| |
| |
| 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. |
| |
| By default, this value is set to 2000. |
| |
| 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. Alternatively, |
| If the "httpchk" option is set, "HTTP/1.0 200 OK" will be sent |
| instead. Nothing will be logged in either case. 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 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 |
| combined test which must induce a failure if all conditions |
| are met, for instance a low number of servers both in a |
| backend and its backup. |
| |
| unless <cond> the monitor request will succeed only if the condition is |
| satisfied, and will fail otherwise. Such a condition may be |
| based on a test on the presence of a minimum number of active |
| servers in a list of backends. |
| |
| This statement adds a condition which can force the response to a monitor |
| request to report a failure. By default, when an external component queries |
| the URI dedicated to monitoring, a 200 response is returned. When one of the |
| conditions above is met, haproxy will return 503 instead of 200. This is |
| 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. Note that "monitor fail" only works in HTTP mode. Both status |
| messages may be tweaked using "errorfile" or "errorloc" if needed. |
| |
| 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", "errorfile", "errorloc" |
| |
| |
| 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 |
| equipment 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. Note that this |
| response is sent in raw format, without any transformation. This is important |
| as it means that it will not be SSL-encrypted on SSL listeners. |
| |
| Monitor requests are processed very early, just after tcp-request connection |
| ACLs which are the only ones able to block them. These connections are short |
| lived and never wait for any data from the client. They cannot be logged, and |
| it is the intended purpose. They are only used to report HAProxy's health to |
| an upper component, nothing more. Please note that "monitor fail" rules do |
| not apply to connections intercepted by "monitor-net". |
| |
| Last, please note that only one "monitor-net" statement can be specified in |
| a frontend. If more than one is found, only the last one will be considered. |
| |
| 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 abortonclose |
| no option abortonclose |
| Enable or disable early dropping of aborted requests pending in queues. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| In presence of very high loads, the servers will take some time to respond. |
| The per-instance connection queue will inflate, and the response time will |
| increase respective to the size of the queue times the average per-session |
| response time. When clients will wait for more than a few seconds, they will |
| often hit the "STOP" button on their browser, leaving a useless request in |
| the queue, and slowing down other users, and the servers as well, because the |
| request will eventually be served, then aborted at the first error |
| encountered while delivering the response. |
| |
| As there is no way to distinguish between a full STOP and a simple output |
| close on the client side, HTTP agents should be conservative and consider |
| that the client might only have closed its output channel while waiting for |
| the response. However, this introduces risks of congestion when lots of users |
| do the same, and is completely useless nowadays because probably no client at |
| all will close the session while waiting for the response. Some HTTP agents |
| support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most |
| hardware-based load balancers). So the probability for a closed input channel |
| to represent a user hitting the "STOP" button is close to 100%, and the risk |
| of being the single component to break rare but valid traffic is extremely |
| low, which adds to the temptation to be able to abort a session early while |
| still not served and not pollute the servers. |
| |
| In HAProxy, the user can choose the desired behaviour using the option |
| "abortonclose". By default (without the option) the behaviour is HTTP |
| compliant and aborted requests will be served. But when the option is |
| specified, a session with an incoming channel closed will be aborted while |
| it is still possible, either pending in the queue for a connection slot, or |
| during the connection establishment if the server has not yet acknowledged |
| the connection request. This considerably reduces the queue size and the load |
| on saturated servers when users are tempted to click on STOP, which in turn |
| reduces the response time for other users. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters |
| |
| |
| option accept-invalid-http-request |
| no option accept-invalid-http-request |
| Enable or disable relaxing of HTTP request parsing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| By default, HAProxy complies with RFC2616 in terms of message parsing. This |
| means that invalid characters in header names are not permitted and cause an |
| error to be returned to the client. This is the desired behaviour as such |
| forbidden characters are essentially used to build attacks exploiting server |
| weaknesses, and bypass security filtering. Sometimes, a buggy browser or |
| server will emit invalid header names for whatever reason (configuration, |
| implementation) and the issue will not be immediately fixed. In such a case, |
| it is possible to relax HAProxy's header name parser to accept any character |
| even if that does not make sense, by specifying this option. Similarly, the |
| list of characters allowed to appear in a URI is well defined by RFC3986, and |
| chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96 |
| ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are |
| not allowed at all. Haproxy always blocks a number of them (0..32, 127). The |
| remaining ones are blocked by default unless this option is enabled. |
| |
| This option should never be enabled by default as it hides application bugs |
| and open security breaches. It should only be deployed after a problem has |
| been confirmed. |
| |
| When this option is enabled, erroneous header names will still be accepted in |
| requests, but the complete request will be captured in order to permit later |
| analysis using the "show errors" request on the UNIX stats socket. Similarly, |
| requests containing invalid chars in the URI part will be logged. Doing this |
| also helps confirming that the issue has been solved. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option accept-invalid-http-response" and "show errors" on the |
| stats socket. |
| |
| |
| option accept-invalid-http-response |
| no option accept-invalid-http-response |
| Enable or disable relaxing of HTTP response parsing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| By default, HAProxy complies with RFC2616 in terms of message parsing. This |
| means that invalid characters in header names are not permitted and cause an |
| error to be returned to the client. This is the desired behaviour as such |
| forbidden characters are essentially used to build attacks exploiting server |
| weaknesses, and bypass security filtering. Sometimes, a buggy browser or |
| server will emit invalid header names for whatever reason (configuration, |
| implementation) and the issue will not be immediately fixed. In such a case, |
| it is possible to relax HAProxy's header name parser to accept any character |
| even if that does not make sense, by specifying this option. |
| |
| This option should never be enabled by default as it hides application bugs |
| and open security breaches. It should only be deployed after a problem has |
| been confirmed. |
| |
| When this option is enabled, erroneous header names will still be accepted in |
| responses, but the complete response will be captured in order to permit |
| later analysis using the "show errors" request on the UNIX stats socket. |
| Doing this also helps confirming that the issue has been solved. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option accept-invalid-http-request" and "show errors" on the |
| stats socket. |
| |
| |
| option allbackups |
| no option allbackups |
| Use either all backup servers at a time or only the first one |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| By default, the first operational backup server gets all traffic when normal |
| servers are all down. Sometimes, it may be preferred to use multiple backups |
| at once, because one will not be enough. When "option allbackups" is enabled, |
| the load balancing will be performed among all backup servers when all normal |
| ones are unavailable. The same load balancing algorithm will be used and the |
| servers' weights will be respected. Thus, there will not be any priority |
| order between the backup servers anymore. |
| |
| This option is mostly used with static server farms dedicated to return a |
| "sorry" page when an application is completely offline. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| |
| option checkcache |
| no option checkcache |
| Analyze all server responses and block requests with cacheable cookies |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| Some high-level frameworks set application cookies everywhere and do not |
| always let enough control to the developer to manage how the responses should |
| be cached. When a session cookie is returned on a cacheable object, there is a |
| high risk of session crossing or stealing between users traversing the same |
| caches. In some situations, it is better to block the response than to let |
| some sensitive session information go in the wild. |
| |
| The option "checkcache" enables deep inspection of all server responses for |
| strict compliance with HTTP specification in terms of cacheability. It |
| carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server |
| response to check if there's a risk of caching a cookie on a client-side |
| proxy. When this option is enabled, the only responses which can be delivered |
| to the client are : |
| - all those without "Set-Cookie" header ; |
| - all those with a return code other than 200, 203, 206, 300, 301, 410, |
| provided that the server has not set a "Cache-control: public" header ; |
| - all those that come from a POST request, provided that the server has not |
| set a 'Cache-Control: public' header ; |
| - those with a 'Pragma: no-cache' header |
| - those with a 'Cache-control: private' header |
| - those with a 'Cache-control: no-store' header |
| - those with a 'Cache-control: max-age=0' header |
| - those with a 'Cache-control: s-maxage=0' header |
| - those with a 'Cache-control: no-cache' header |
| - those with a 'Cache-control: no-cache="set-cookie"' header |
| - those with a 'Cache-control: no-cache="set-cookie,' header |
| (allowing other fields after set-cookie) |
| |
| If a response doesn't respect these requirements, then it will be blocked |
| just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway". |
| The session state shows "PH--" meaning that the proxy blocked the response |
| during headers processing. Additionally, an alert will be sent in the logs so |
| that admins are informed that there's something to be fixed. |
| |
| Due to the high impact on the application, the application should be tested |
| in depth with the option enabled before going to production. It is also a |
| good practice to always activate it during tests, even if it is not used in |
| production, as it will report potentially dangerous application behaviours. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| |
| option clitcpka |
| no option clitcpka |
| Enable or disable the sending of TCP keepalive packets on the client side |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| When there is a firewall or any session-aware component between a client and |
| a server, and when the protocol involves very long sessions with long idle |
| periods (eg: remote desktops), there is a risk that one of the intermediate |
| components decides to expire a session which has remained idle for too long. |
| |
| Enabling socket-level TCP keep-alives makes the system regularly send packets |
| to the other end of the connection, leaving it active. The delay between |
| keep-alive probes is controlled by the system only and depends both on the |
| operating system and its tuning parameters. |
| |
| It is important to understand that keep-alive packets are neither emitted nor |
| received at the application level. It is only the network stacks which sees |
| them. For this reason, even if one side of the proxy already uses keep-alives |
| to maintain its connection alive, those keep-alive packets will not be |
| forwarded to the other side of the proxy. |
| |
| Please note that this has nothing to do with HTTP keep-alive. |
| |
| Using option "clitcpka" enables the emission of TCP keep-alive probes on the |
| client side of a connection, which should help when session expirations are |
| noticed between HAProxy and a client. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option srvtcpka", "option tcpka" |
| |
| |
| option contstats |
| Enable continuous traffic statistics updates |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| By default, counters used for statistics calculation are incremented |
| only when a session finishes. It works quite well when serving small |
| objects, but with big ones (for example large images or archives) or |
| with A/V streaming, a graph generated from haproxy counters looks like |
| a hedgehog. With this option enabled counters get incremented continuously, |
| during a whole session. Recounting touches a hotpath directly so |
| it is not enabled by default, as it has small performance impact (~0.5%). |
| |
| |
| option dontlog-normal |
| no option dontlog-normal |
| Enable or disable logging of normal, successful connections |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| There are large sites dealing with several thousand connections per second |
| and for which logging is a major pain. Some of them are even forced to turn |
| logs off and cannot debug production issues. Setting this option ensures that |
| normal connections, those which experience no error, no timeout, no retry nor |
| redispatch, will not be logged. This leaves disk space for anomalies. In HTTP |
| mode, the response status code is checked and return codes 5xx will still be |
| logged. |
| |
| It is strongly discouraged to use this option as most of the time, the key to |
| complex issues is in the normal logs which will not be logged here. If you |
| need to separate logs, see the "log-separate-errors" option instead. |
| |
| See also : "log", "dontlognull", "log-separate-errors" and section 8 about |
| logging. |
| |
| |
| option dontlognull |
| no option dontlognull |
| Enable or disable logging of null connections |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| In certain environments, there are components which will regularly connect to |
| various systems to ensure that they are still alive. It can be the case from |
| another load balancer as well as from monitoring systems. By default, even a |
| simple port probe or scan will produce a log. If those connections pollute |
| the logs too much, it is possible to enable option "dontlognull" to indicate |
| that a connection on which no data has been transferred will not be logged, |
| which typically corresponds to those probes. |
| |
| It is generally recommended not to use this option in uncontrolled |
| environments (eg: internet), otherwise scans and other malicious activities |
| would not be logged. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "log", "monitor-net", "monitor-uri" and section 8 about logging. |
| |
| |
| option forceclose |
| no option forceclose |
| Enable or disable active connection closing after response is transferred. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| Some HTTP servers do not necessarily close the connections when they receive |
| the "Connection: close" set by "option httpclose", and if the client does not |
| close either, then the connection remains open till the timeout expires. This |
| causes high number of simultaneous connections on the servers and shows high |
| global session times in the logs. |
| |
| When this happens, it is possible to use "option forceclose". It will |
| actively close the outgoing server channel as soon as the server has finished |
| to respond. This option implicitly enables the "httpclose" option. Note that |
| this option also enables the parsing of the full request and response, which |
| means we can close the connection to the server very quickly, releasing some |
| resources earlier than with httpclose. |
| |
| This option may also be combined with "option http-pretend-keepalive", which |
| will disable sending of the "Connection: close" header, but will still cause |
| the connection to be closed once the whole response is received. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option httpclose" and "option http-pretend-keepalive" |
| |
| |
| option forwardfor [ except <network> ] [ header <name> ] [ if-none ] |
| Enable insertion of the X-Forwarded-For header to requests sent to servers |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <network> is an optional argument used to disable this option for sources |
| matching <network> |
| <name> an optional argument to specify a different "X-Forwarded-For" |
| header name. |
| |
| Since HAProxy works in reverse-proxy mode, the servers see its IP address as |
| their client address. This is sometimes annoying when the client's IP address |
| is expected in server logs. To solve this problem, the well-known HTTP header |
| "X-Forwarded-For" may be added by HAProxy to all requests sent to the server. |
| This header contains a value representing the client's IP address. Since this |
| header is always appended at the end of the existing header list, the server |
| must be configured to always use the last occurrence of this header only. See |
| the server's manual to find how to enable use of this standard header. Note |
| that only the last occurrence of the header must be used, since it is really |
| possible that the client has already brought one. |
| |
| The keyword "header" may be used to supply a different header name to replace |
| the default "X-Forwarded-For". This can be useful where you might already |
| have a "X-Forwarded-For" header from a different application (eg: stunnel), |
| and you need preserve it. Also if your backend server doesn't use the |
| "X-Forwarded-For" header and requires different one (eg: Zeus Web Servers |
| require "X-Cluster-Client-IP"). |
| |
| Sometimes, a same HAProxy instance may be shared between a direct client |
| access and a reverse-proxy access (for instance when an SSL reverse-proxy is |
| used to decrypt HTTPS traffic). It is possible to disable the addition of the |
| header for a known source address or network by adding the "except" keyword |
| followed by the network address. In this case, any source IP matching the |
| network will not cause an addition of this header. Most common uses are with |
| private networks or 127.0.0.1. |
| |
| Alternatively, the keyword "if-none" states that the header will only be |
| added if it is not present. This should only be used in perfectly trusted |
| environment, as this might cause a security issue if headers reaching haproxy |
| are under the control of the end-user. |
| |
| This option may be specified either in the frontend or in the backend. If at |
| least one of them uses it, the header will be added. Note that the backend's |
| setting of the header subargument takes precedence over the frontend's if |
| both are defined. In the case of the "if-none" argument, if at least one of |
| the frontend or the backend does not specify it, it wants the addition to be |
| mandatory, so it wins. |
| |
| It is important to note that by default, HAProxy works in tunnel mode and |
| only inspects the first request of a connection, meaning that only the first |
| request will have the header appended, which is certainly not what you want. |
| In order to fix this, ensure that any of the "httpclose", "forceclose" or |
| "http-server-close" options is set when using this option. |
| |
| Examples : |
| # Public HTTP address also used by stunnel on the same machine |
| frontend www |
| mode http |
| option forwardfor except 127.0.0.1 # stunnel already adds the header |
| |
| # Those servers want the IP Address in X-Client |
| backend www |
| mode http |
| option forwardfor header X-Client |
| |
| See also : "option httpclose", "option http-server-close", |
| "option forceclose" |
| |
| |
| option http-no-delay |
| no option http-no-delay |
| Instruct the system to favor low interactive delays over performance in HTTP |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| In HTTP, each payload is unidirectional and has no notion of interactivity. |
| Any agent is expected to queue data somewhat for a reasonably low delay. |
| There are some very rare server-to-server applications that abuse the HTTP |
| protocol and expect the payload phase to be highly interactive, with many |
| interleaved data chunks in both directions within a single request. This is |
| absolutely not supported by the HTTP specification and will not work across |
| most proxies or servers. When such applications attempt to do this through |
| haproxy, it works but they will experience high delays due to the network |
| optimizations which favor performance by instructing the system to wait for |
| enough data to be available in order to only send full packets. Typical |
| delays are around 200 ms per round trip. Note that this only happens with |
| abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not |
| affected. |
| |
| When "option http-no-delay" is present in either the frontend or the backend |
| used by a connection, all such optimizations will be disabled in order to |
| make the exchanges as fast as possible. Of course this offers no guarantee on |
| the functionality, as it may break at any other place. But if it works via |
| HAProxy, it will work as fast as possible. This option should never be used |
| by default, and should never be used at all unless such a buggy application |
| is discovered. The impact of using this option is an increase of bandwidth |
| usage and CPU usage, which may significantly lower performance in high |
| latency environments. |
| |
| |
| option http-pretend-keepalive |
| no option http-pretend-keepalive |
| Define whether haproxy will announce keepalive to the server or not |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| When running with "option http-server-close" or "option forceclose", haproxy |
| adds a "Connection: close" header to the request forwarded to the server. |
| Unfortunately, when some servers see this header, they automatically refrain |
| from using the chunked encoding for responses of unknown length, while this |
| is totally unrelated. The immediate effect is that this prevents haproxy from |
| maintaining the client connection alive. A second effect is that a client or |
| a cache could receive an incomplete response without being aware of it, and |
| consider the response complete. |
| |
| By setting "option http-pretend-keepalive", haproxy will make the server |
| believe it will keep the connection alive. The server will then not fall back |
| to the abnormal undesired above. When haproxy gets the whole response, it |
| will close the connection with the server just as it would do with the |
| "forceclose" option. That way the client gets a normal response and the |
| connection is correctly closed on the server side. |
| |
| It is recommended not to enable this option by default, because most servers |
| will more efficiently close the connection themselves after the last packet, |
| and release its buffers slightly earlier. Also, the added packet on the |
| network could slightly reduce the overall peak performance. However it is |
| worth noting that when this option is enabled, haproxy will have slightly |
| less work to do. So if haproxy is the bottleneck on the whole architecture, |
| enabling this option might save a few CPU cycles. |
| |
| This option may be set both in a frontend and in a backend. It is enabled if |
| at least one of the frontend or backend holding a connection has it enabled. |
| This option may be combined with "option httpclose", which will cause |
| keepalive to be announced to the server and close to be announced to the |
| client. This practice is discouraged though. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option forceclose" and "option http-server-close" |
| |
| |
| option http-server-close |
| no option http-server-close |
| Enable or disable HTTP connection closing on the server side |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| By default, when a client communicates with a server, HAProxy will only |
| analyze, log, and process the first request of each connection. Setting |
| "option http-server-close" enables HTTP connection-close mode on the server |
| side while keeping the ability to support HTTP keep-alive and pipelining on |
| the client side. This provides the lowest latency on the client side (slow |
| network) and the fastest session reuse on the server side to save server |
| resources, similarly to "option forceclose". It also permits non-keepalive |
| capable servers to be served in keep-alive mode to the clients if they |
| conform to the requirements of RFC2616. Please note that some servers do not |
| always conform to those requirements when they see "Connection: close" in the |
| request. The effect will be that keep-alive will never be used. A workaround |
| consists in enabling "option http-pretend-keepalive". |
| |
| At the moment, logs will not indicate whether requests came from the same |
| session or not. The accept date reported in the logs corresponds to the end |
| of the previous request, and the request time corresponds to the time spent |
| waiting for a new request. The keep-alive request time is still bound to the |
| timeout defined by "timeout http-keep-alive" or "timeout http-request" if |
| not set. |
| |
| This option may be set both in a frontend and in a backend. It is enabled if |
| at least one of the frontend or backend holding a connection has it enabled. |
| It is worth noting that "option forceclose" has precedence over "option |
| http-server-close" and that combining "http-server-close" with "httpclose" |
| basically achieve the same result as "forceclose". |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option forceclose", "option http-pretend-keepalive", |
| "option httpclose" and "1.1. The HTTP transaction model". |
| |
| |
| option http-use-proxy-header |
| no option http-use-proxy-header |
| Make use of non-standard Proxy-Connection header instead of Connection |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| While RFC2616 explicitly states that HTTP/1.1 agents must use the |
| Connection header to indicate their wish of persistent or non-persistent |
| connections, both browsers and proxies ignore this header for proxied |
| connections and make use of the undocumented, non-standard Proxy-Connection |
| header instead. The issue begins when trying to put a load balancer between |
| browsers and such proxies, because there will be a difference between what |
| haproxy understands and what the client and the proxy agree on. |
| |
| By setting this option in a frontend, haproxy can automatically switch to use |
| that non-standard header if it sees proxied requests. A proxied request is |
| defined here as one where the URI begins with neither a '/' nor a '*'. The |
| choice of header only affects requests passing through proxies making use of |
| one of the "httpclose", "forceclose" and "http-server-close" options. Note |
| that this option can only be specified in a frontend and will affect the |
| request along its whole life. |
| |
| Also, when this option is set, a request which requires authentication will |
| automatically switch to use proxy authentication headers if it is itself a |
| proxied request. That makes it possible to check or enforce authentication in |
| front of an existing proxy. |
| |
| This option should normally never be used, except in front of a proxy. |
| |
| See also : "option httpclose", "option forceclose" and "option |
| http-server-close". |
| |
| |
| option httpchk |
| option httpchk <uri> |
| option httpchk <method> <uri> |
| option httpchk <method> <uri> <version> |
| Enable HTTP protocol to check on the servers health |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <method> is the optional HTTP method used with the requests. When not set, |
| the "OPTIONS" method is used, as it generally requires low server |
| processing and is easy to filter out from the logs. Any method |
| may be used, though it is not recommended to invent non-standard |
| ones. |
| |
| <uri> is the URI referenced in the HTTP requests. It defaults to " / " |
| which is accessible by default on almost any server, but may be |
| changed to any other URI. Query strings are permitted. |
| |
| <version> is the optional HTTP version string. It defaults to "HTTP/1.0" |
| but some servers might behave incorrectly in HTTP 1.0, so turning |
| it to HTTP/1.1 may sometimes help. Note that the Host field is |
| mandatory in HTTP/1.1, and as a trick, it is possible to pass it |
| after "\r\n" following the version string. |
| |
| By default, server health checks only consist in trying to establish a TCP |
| connection. When "option httpchk" is specified, a complete HTTP request is |
| sent once the TCP connection is established, and responses 2xx and 3xx are |
| considered valid, while all other ones indicate a server failure, including |
| the lack of any response. |
| |
| The port and interval are specified in the server configuration. |
| |
| This option does not necessarily require an HTTP backend, it also works with |
| plain TCP backends. This is particularly useful to check simple scripts bound |
| to some dedicated ports using the inetd daemon. |
| |
| Examples : |
| # Relay HTTPS traffic to Apache instance and check service availability |
| # using HTTP request "OPTIONS * HTTP/1.1" on port 80. |
| backend https_relay |
| mode tcp |
| option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www |
| server apache1 192.168.1.1:443 check port 80 |
| |
| See also : "option ssl-hello-chk", "option smtpchk", "option mysql-check", |
| "option pgsql-check", "http-check" and the "check", "port" and |
| "inter" server options. |
| |
| |
| option httpclose |
| no option httpclose |
| Enable or disable passive HTTP connection closing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| By default, when a client communicates with a server, HAProxy will only |
| analyze, log, and process the first request of each connection. If "option |
| httpclose" is set, it will check if a "Connection: close" header is already |
| set in each direction, and will add one if missing. Each end should react to |
| this by actively closing the TCP connection after each transfer, thus |
| resulting in a switch to the HTTP close mode. Any "Connection" header |
| different from "close" will also be removed. |
| |
| It seldom happens that some servers incorrectly ignore this header and do not |
| close the connection even though they reply "Connection: close". For this |
| reason, they are not compatible with older HTTP 1.0 browsers. If this happens |
| it is possible to use the "option forceclose" which actively closes the |
| request connection once the server responds. Option "forceclose" also |
| releases the server connection earlier because it does not have to wait for |
| the client to acknowledge it. |
| |
| This option may be set both in a frontend and in a backend. It is enabled if |
| at least one of the frontend or backend holding a connection has it enabled. |
| If "option forceclose" is specified too, it has precedence over "httpclose". |
| If "option http-server-close" is enabled at the same time as "httpclose", it |
| basically achieves the same result as "option forceclose". |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option forceclose", "option http-server-close" and |
| "1.1. The HTTP transaction model". |
| |
| |
| option httplog [ clf ] |
| Enable logging of HTTP request, session state and timers |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| clf if the "clf" argument is added, then the output format will be |
| the CLF format instead of HAProxy's default HTTP format. You can |
| use this when you need to feed HAProxy's logs through a specific |
| log analyser which only support the CLF format and which is not |
| extensible. |
| |
| By default, the log output format is very poor, as it only contains the |
| source and destination addresses, and the instance name. By specifying |
| "option httplog", each log line turns into a much richer format including, |
| but not limited to, the HTTP request, the connection timers, the session |
| status, the connections numbers, the captured headers and cookies, the |
| frontend, backend and server name, and of course the source address and |
| ports. |
| |
| This option may be set either in the frontend or the backend. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. Specifying |
| only "option httplog" will automatically clear the 'clf' mode if it was set |
| by default. |
| |
| See also : section 8 about logging. |
| |
| |
| option http_proxy |
| no option http_proxy |
| Enable or disable plain HTTP proxy mode |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| It sometimes happens that people need a pure HTTP proxy which understands |
| basic proxy requests without caching nor any fancy feature. In this case, |
| it may be worth setting up an HAProxy instance with the "option http_proxy" |
| set. In this mode, no server is declared, and the connection is forwarded to |
| the IP address and port found in the URL after the "http://" scheme. |
| |
| No host address resolution is performed, so this only works when pure IP |
| addresses are passed. Since this option's usage perimeter is rather limited, |
| it will probably be used only by experts who know they need exactly it. Last, |
| if the clients are susceptible of sending keep-alive requests, it will be |
| needed to add "option httpclose" to ensure that all requests will correctly |
| be analyzed. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| Example : |
| # this backend understands HTTP proxy requests and forwards them directly. |
| backend direct_forward |
| option httpclose |
| option http_proxy |
| |
| See also : "option httpclose" |
| |
| |
| option independent-streams |
| no option independent-streams |
| Enable or disable independent timeout processing for both directions |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| By default, when data is sent over a socket, both the write timeout and the |
| read timeout for that socket are refreshed, because we consider that there is |
| activity on that socket, and we have no other means of guessing if we should |
| receive data or not. |
| |
| While this default behaviour is desirable for almost all applications, there |
| exists a situation where it is desirable to disable it, and only refresh the |
| read timeout if there are incoming data. This happens on sessions with large |
| timeouts and low amounts of exchanged data such as telnet session. If the |
| server suddenly disappears, the output data accumulates in the system's |
| socket buffers, both timeouts are correctly refreshed, and there is no way |
| to know the server does not receive them, so we don't timeout. However, when |
| the underlying protocol always echoes sent data, it would be enough by itself |
| to detect the issue using the read timeout. Note that this problem does not |
| happen with more verbose protocols because data won't accumulate long in the |
| socket buffers. |
| |
| When this option is set on the frontend, it will disable read timeout updates |
| on data sent to the client. There probably is little use of this case. When |
| the option is set on the backend, it will disable read timeout updates on |
| data sent to the server. Doing so will typically break large HTTP posts from |
| slow lines, so use it with caution. |
| |
| Note: older versions used to call this setting "option independant-streams" |
| with a spelling mistake. This spelling is still supported but |
| deprecated. |
| |
| See also : "timeout client", "timeout server" and "timeout tunnel" |
| |
| |
| option ldap-check |
| Use LDAPv3 health checks for server testing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| It is possible to test that the server correctly talks LDAPv3 instead of just |
| testing that it accepts the TCP connection. When this option is set, an |
| LDAPv3 anonymous simple bind message is sent to the server, and the response |
| is analyzed to find an LDAPv3 bind response message. |
| |
| The server is considered valid only when the LDAP response contains success |
| resultCode (http://tools.ietf.org/html/rfc4511#section-4.1.9). |
| |
| Logging of bind requests is server dependent see your documentation how to |
| configure it. |
| |
| Example : |
| option ldap-check |
| |
| See also : "option httpchk" |
| |
| |
| option log-health-checks |
| no option log-health-checks |
| Enable or disable logging of health checks |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| Enable health checks logging so it possible to check for example what |
| was happening before a server crash. Failed health check are logged if |
| server is UP and succeeded health checks if server is DOWN, so the amount |
| of additional information is limited. |
| |
| If health check logging is enabled no health check status is printed |
| when servers is set up UP/DOWN/ENABLED/DISABLED. |
| |
| See also: "log" and section 8 about logging. |
| |
| |
| option log-separate-errors |
| no option log-separate-errors |
| Change log level for non-completely successful connections |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| Sometimes looking for errors in logs is not easy. This option makes haproxy |
| raise the level of logs containing potentially interesting information such |
| as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The |
| level changes from "info" to "err". This makes it possible to log them |
| separately to a different file with most syslog daemons. Be careful not to |
| remove them from the original file, otherwise you would lose ordering which |
| provides very important information. |
| |
| Using this option, large sites dealing with several thousand connections per |
| second may log normal traffic to a rotating buffer and only archive smaller |
| error logs. |
| |
| See also : "log", "dontlognull", "dontlog-normal" and section 8 about |
| logging. |
| |
| |
| option logasap |
| no option logasap |
| Enable or disable early logging of HTTP requests |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| By default, HTTP requests are logged upon termination so that the total |
| transfer time and the number of bytes appear in the logs. When large objects |
| are being transferred, it may take a while before the request appears in the |
| logs. Using "option logasap", the request gets logged as soon as the server |
| sends the complete headers. The only missing information in the logs will be |
| the total number of bytes which will indicate everything except the amount |
| of data transferred, and the total time which will not take the transfer |
| time into account. In such a situation, it's a good practice to capture the |
| "Content-Length" response header so that the logs at least indicate how many |
| bytes are expected to be transferred. |
| |
| Examples : |
| listen http_proxy 0.0.0.0:80 |
| mode http |
| option httplog |
| option logasap |
| log 192.168.2.200 local3 |
| |
| >>> Feb 6 12:14:14 localhost \ |
| haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ |
| static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \ |
| "GET /image.iso HTTP/1.0" |
| |
| See also : "option httplog", "capture response header", and section 8 about |
| logging. |
| |
| |
| option mysql-check [ user <username> ] |
| Use MySQL health checks for server testing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <username> This is the username which will be used when connecting to MySQL |
| server. |
| |
| If you specify a username, the check consists of sending two MySQL packet, |
| one Client Authentication packet, and one QUIT packet, to correctly close |
| MySQL session. We then parse the MySQL Handshake Initialisation packet and/or |
| Error packet. It is a basic but useful test which does not produce error nor |
| aborted connect on the server. However, it requires adding an authorization |
| in the MySQL table, like this : |
| |
| USE mysql; |
| INSERT INTO user (Host,User) values ('<ip_of_haproxy>','<username>'); |
| FLUSH PRIVILEGES; |
| |
| If you don't specify a username (it is deprecated and not recommended), the |
| check only consists in parsing the Mysql Handshake Initialisation packet or |
| Error packet, we don't send anything in this mode. It was reported that it |
| can generate lockout if check is too frequent and/or if there is not enough |
| traffic. In fact, you need in this case to check MySQL "max_connect_errors" |
| value as if a connection is established successfully within fewer than MySQL |
| "max_connect_errors" attempts after a previous connection was interrupted, |
| the error count for the host is cleared to zero. If HAProxy's server get |
| blocked, the "FLUSH HOSTS" statement is the only way to unblock it. |
| |
| Remember that this does not check database presence nor database consistency. |
| To do this, you can use an external check with xinetd for example. |
| |
| The check requires MySQL >=3.22, for older version, please use TCP check. |
| |
| Most often, an incoming MySQL server needs to see the client's IP address for |
| various purposes, including IP privilege matching and connection logging. |
| When possible, it is often wise to masquerade the client's IP address when |
| connecting to the server using the "usesrc" argument of the "source" keyword, |
| which requires the cttproxy feature to be compiled in, and the MySQL server |
| to route the client via the machine hosting haproxy. |
| |
| See also: "option httpchk" |
| |
| option pgsql-check [ user <username> ] |
| Use PostgreSQL health checks for server testing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <username> This is the username which will be used when connecting to |
| PostgreSQL server. |
| |
| The check sends a PostgreSQL StartupMessage and waits for either |
| Authentication request or ErrorResponse message. It is a basic but useful |
| test which does not produce error nor aborted connect on the server. |
| This check is identical with the "mysql-check". |
| |
| See also: "option httpchk" |
| |
| option nolinger |
| no option nolinger |
| Enable or disable immediate session resource cleaning after close |
| May be used in sections: defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| When clients or servers abort connections in a dirty way (eg: they are |
| physically disconnected), the session timeouts triggers and the session is |
| closed. But it will remain in FIN_WAIT1 state for some time in the system, |
| using some resources and possibly limiting the ability to establish newer |
| connections. |
| |
| When this happens, it is possible to activate "option nolinger" which forces |
| the system to immediately remove any socket's pending data on close. Thus, |
| the session is instantly purged from the system's tables. This usually has |
| side effects such as increased number of TCP resets due to old retransmits |
| getting immediately rejected. Some firewalls may sometimes complain about |
| this too. |
| |
| For this reason, it is not recommended to use this option when not absolutely |
| needed. You know that you need it when you have thousands of FIN_WAIT1 |
| sessions on your system (TIME_WAIT ones do not count). |
| |
| This option may be used both on frontends and backends, depending on the side |
| where it is required. Use it on the frontend for clients, and on the backend |
| for servers. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| |
| option originalto [ except <network> ] [ header <name> ] |
| Enable insertion of the X-Original-To header to requests sent to servers |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <network> is an optional argument used to disable this option for sources |
| matching <network> |
| <name> an optional argument to specify a different "X-Original-To" |
| header name. |
| |
| Since HAProxy can work in transparent mode, every request from a client can |
| be redirected to the proxy and HAProxy itself can proxy every request to a |
| complex SQUID environment and the destination host from SO_ORIGINAL_DST will |
| be lost. This is annoying when you want access rules based on destination ip |
| addresses. To solve this problem, a new HTTP header "X-Original-To" may be |
| added by HAProxy to all requests sent to the server. This header contains a |
| value representing the original destination IP address. Since this must be |
| configured to always use the last occurrence of this header only. Note that |
| only the last occurrence of the header must be used, since it is really |
| possible that the client has already brought one. |
| |
| The keyword "header" may be used to supply a different header name to replace |
| the default "X-Original-To". This can be useful where you might already |
| have a "X-Original-To" header from a different application, and you need |
| preserve it. Also if your backend server doesn't use the "X-Original-To" |
| header and requires different one. |
| |
| Sometimes, a same HAProxy instance may be shared between a direct client |
| access and a reverse-proxy access (for instance when an SSL reverse-proxy is |
| used to decrypt HTTPS traffic). It is possible to disable the addition of the |
| header for a known source address or network by adding the "except" keyword |
| followed by the network address. In this case, any source IP matching the |
| network will not cause an addition of this header. Most common uses are with |
| private networks or 127.0.0.1. |
| |
| This option may be specified either in the frontend or in the backend. If at |
| least one of them uses it, the header will be added. Note that the backend's |
| setting of the header subargument takes precedence over the frontend's if |
| both are defined. |
| |
| It is important to note that by default, HAProxy works in tunnel mode and |
| only inspects the first request of a connection, meaning that only the first |
| request will have the header appended, which is certainly not what you want. |
| In order to fix this, ensure that any of the "httpclose", "forceclose" or |
| "http-server-close" options is set when using this option. |
| |
| Examples : |
| # Original Destination address |
| frontend www |
| mode http |
| option originalto except 127.0.0.1 |
| |
| # Those servers want the IP Address in X-Client-Dst |
| backend www |
| mode http |
| option originalto header X-Client-Dst |
| |
| See also : "option httpclose", "option http-server-close", |
| "option forceclose" |
| |
| |
| option persist |
| no option persist |
| Enable or disable forced persistence on down servers |
| May be used in sections: defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| When an HTTP request reaches a backend with a cookie which references a dead |
| server, by default it is redispatched to another server. It is possible to |
| force the request to be sent to the dead server first using "option persist" |
| if absolutely needed. A common use case is when servers are under extreme |
| load and spend their time flapping. In this case, the users would still be |
| directed to the server they opened the session on, in the hope they would be |
| correctly served. It is recommended to use "option redispatch" in conjunction |
| with this option so that in the event it would not be possible to connect to |
| the server at all (server definitely dead), the client would finally be |
| redirected to another valid server. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option redispatch", "retries", "force-persist" |
| |
| |
| option redispatch |
| no option redispatch |
| Enable or disable session redistribution in case of connection failure |
| May be used in sections: defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| In HTTP mode, if a server designated by a cookie is down, clients may |
| definitely stick to it because they cannot flush the cookie, so they will not |
| be able to access the service anymore. |
| |
| Specifying "option redispatch" will allow the proxy to break their |
| persistence and redistribute them to a working server. |
| |
| It also allows to retry last connection to another server in case of multiple |
| connection failures. Of course, it requires having "retries" set to a nonzero |
| value. |
| |
| This form is the preferred form, which replaces both the "redispatch" and |
| "redisp" keywords. |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "redispatch", "retries", "force-persist" |
| |
| |
| option redis-check |
| Use redis health checks for server testing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| It is possible to test that the server correctly talks REDIS protocol instead |
| of just testing that it accepts the TCP connection. When this option is set, |
| a PING redis command is sent to the server, and the response is analyzed to |
| find the "+PONG" response message. |
| |
| Example : |
| option redis-check |
| |
| See also : "option httpchk" |
| |
| |
| option smtpchk |
| option smtpchk <hello> <domain> |
| Use SMTP health checks for server testing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <hello> is an optional argument. It is the "hello" command to use. It can |
| be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other |
| values will be turned into the default command ("HELO"). |
| |
| <domain> is the domain name to present to the server. It may only be |
| specified (and is mandatory) if the hello command has been |
| specified. By default, "localhost" is used. |
| |
| When "option smtpchk" is set, the health checks will consist in TCP |
| connections followed by an SMTP command. By default, this command is |
| "HELO localhost". The server's return code is analyzed and only return codes |
| starting with a "2" will be considered as valid. All other responses, |
| including a lack of response will constitute an error and will indicate a |
| dead server. |
| |
| This test is meant to be used with SMTP servers or relays. Depending on the |
| request, it is possible that some servers do not log each connection attempt, |
| so you may want to experiment to improve the behaviour. Using telnet on port |
| 25 is often easier than adjusting the configuration. |
| |
| Most often, an incoming SMTP server needs to see the client's IP address for |
| various purposes, including spam filtering, anti-spoofing and logging. When |
| possible, it is often wise to masquerade the client's IP address when |
| connecting to the server using the "usesrc" argument of the "source" keyword, |
| which requires the cttproxy feature to be compiled in. |
| |
| Example : |
| option smtpchk HELO mydomain.org |
| |
| See also : "option httpchk", "source" |
| |
| |
| option socket-stats |
| no option socket-stats |
| |
| Enable or disable collecting & providing separate statistics for each socket. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| |
| Arguments : none |
| |
| |
| option splice-auto |
| no option splice-auto |
| Enable or disable automatic kernel acceleration on sockets in both directions |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| When this option is enabled either on a frontend or on a backend, haproxy |
| will automatically evaluate the opportunity to use kernel tcp splicing to |
| forward data between the client and the server, in either direction. Haproxy |
| uses heuristics to estimate if kernel splicing might improve performance or |
| not. Both directions are handled independently. Note that the heuristics used |
| are not much aggressive in order to limit excessive use of splicing. This |
| option requires splicing to be enabled at compile time, and may be globally |
| disabled with the global option "nosplice". Since splice uses pipes, using it |
| requires that there are enough spare pipes. |
| |
| Important note: kernel-based TCP splicing is a Linux-specific feature which |
| first appeared in kernel 2.6.25. It offers kernel-based acceleration to |
| transfer data between sockets without copying these data to user-space, thus |
| providing noticeable performance gains and CPU cycles savings. Since many |
| early implementations are buggy, corrupt data and/or are inefficient, this |
| feature is not enabled by default, and it should be used with extreme care. |
| While it is not possible to detect the correctness of an implementation, |
| 2.6.29 is the first version offering a properly working implementation. In |
| case of doubt, splicing may be globally disabled using the global "nosplice" |
| keyword. |
| |
| Example : |
| option splice-auto |
| |
| If this option has been enabled in a "defaults" section, it can be disabled |
| in a specific instance by prepending the "no" keyword before it. |
| |
| See also : "option splice-request", "option splice-response", and global |
| options "nosplice" and "maxpipes" |
| |
| |
| option splice-request |
| no option splice-request |
| Enable or disable automatic kernel acceleration on sockets for requests |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
|