| ---------------------- |
| HAProxy |
| Configuration Manual |
| ---------------------- |
| version 1.5 |
| willy tarreau |
| 2010/11/11 |
| |
| |
| 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 formated 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 |
| |
| 4. Proxies |
| 4.1. Proxy keywords matrix |
| 4.2. Alphabetically sorted keywords reference |
| |
| 5. 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 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.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 |
| - chroot |
| - daemon |
| - gid |
| - group |
| - log |
| - log-send-hostname |
| - nbproc |
| - pidfile |
| - uid |
| - ulimit-n |
| - user |
| - stats |
| - node |
| - description |
| - unix-bind |
| |
| * Performance tuning |
| - maxconn |
| - maxpipes |
| - noepoll |
| - nokqueue |
| - nopoll |
| - nosepoll |
| - nosplice |
| - spread-checks |
| - tune.bufsize |
| - tune.chksize |
| - tune.maxaccept |
| - tune.maxpollevents |
| - tune.maxrewrite |
| - tune.rcvbuf.client |
| - tune.rcvbuf.server |
| - tune.sndbuf.client |
| - tune.sndbuf.server |
| |
| * Debugging |
| - debug |
| - quiet |
| |
| |
| 3.1. Process management and security |
| ------------------------------------ |
| |
| 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. |
| |
| 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). |
| |
| - 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 socket <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>] |
| [level <level>] |
| |
| Creates a UNIX socket in stream mode at location <path>. Any previously |
| existing socket will be backed up then replaced. Connections to this socket |
| will return various statistics outputs and even allow some commands to be |
| issued. Please consult section 9.2 "Unix Socket commands" for more details. |
| |
| An optional "level" parameter can be specified to restrict the nature of |
| the commands that can be issued on the socket : |
| - "user" is the least privileged level ; only non-sensitive stats can be |
| read, and no change is allowed. It would make sense on systems where it |
| is not easy to restrict access to the socket. |
| |
| - "operator" is the default level and fits most common uses. All data can |
| be read, and only non-sensible changes are permitted (eg: clear max |
| counters). |
| |
| - "admin" should be used with care, as everything is permitted (eg: clear |
| all counters). |
| |
| On platforms which support it, it is possible to restrict access to this |
| socket by specifying numerical IDs after "uid" and "gid", or valid user and |
| group names after the "user" and "group" keywords. It is also possible to |
| restrict permissions on the socket by passing an octal value after the "mode" |
| keyword (same syntax as chmod). Depending on the platform, the permissions on |
| the socket will be inherited from the directory which hosts it, or from the |
| user the process is started with. |
| |
| 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". |
| |
| 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. |
| |
| 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 "nosepoll", and "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 "nosepoll", and "nopoll" and |
| "nokqueue". |
| |
| nosepoll |
| Disables the use of the "speculative epoll" event polling system on Linux. It |
| is equivalent to the command-line argument "-ds". The next polling system |
| used will generally be "epoll". See also "nosepoll", and "nopoll". |
| |
| 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. |
| |
| 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.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.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. |
| |
| |
| 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 independant 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 - |
| 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-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 independant-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 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-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 |
| transparent (deprecated) X - X X |
| use_backend - 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. |
| |
| 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 The left part of the URI (before the question mark) is hashed |
| and divided by the total weight of the running servers. The |
| result designates which server will receive the request. This |
| ensures that a 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 support 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 the question mark indicating a query string ('?') is not |
| present 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". |
| |
| <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> [, ...] |
| bind [<address>]:<port_range> [, ...] interface <interface> |
| bind [<address>]:<port_range> [, ...] mss <maxseg> |
| bind [<address>]:<port_range> [, ...] transparent |
| bind [<address>]:<port_range> [, ...] id <id> |
| bind [<address>]:<port_range> [, ...] name <name> |
| bind [<address>]:<port_range> [, ...] defer-accept |
| bind [<address>]:<port_range> [, ...] accept-proxy |
| bind /<path> [, ...] |
| bind /<path> [, ...] mode <mode> |
| bind /<path> [, ...] [ user <user> | uid <uid> ] |
| bind /<path> [, ...] [ group <user> | gid <gid> ] |
| 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". |
| |
| <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 independant 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. |
| |
| <interface> is an optional physical interface name. This is currently |
| only supported on Linux. The interface must be a physical |
| interface, not an aliased interface. When specified, all |
| addresses on the same line will only be accepted if the |
| incoming packet physically come through the designated |
| interface. It is also possible to bind multiple frontends to |
| the same address if they are bound to different interfaces. |
| Note that binding to a physical interface requires root |
| privileges. This parameter is only compatible with TCP |
| sockets. |
| |
| <maxseg> is an optional TCP Maximum Segment Size (MSS) value to be |
| advertised on incoming connections. This can be used to force |
| a lower MSS for certain specific ports, for instance for |
| connections passing through a VPN. Note that this relies on a |
| kernel feature which is theorically supported under Linux but |
| was buggy in all versions prior to 2.6.28. It may or may not |
| work on other operating systems. It may also not change the |
| advertised value but change the effective size of outgoing |
| segments. The commonly advertised value on Ethernet networks |
| is 1460 = 1500(MTU) - 40(IP+TCP). If this value is positive, |
| it will be used as the advertised MSS. If it is negative, it |
| will indicate by how much to reduce the incoming connection's |
| advertised MSS for outgoing segments. This parameter is only |
| compatible with TCP sockets. |
| |
| <id> is a persistent value for socket ID. Must be positive and |
| unique in the proxy. An unused value will automatically be |
| assigned if unset. Can only be used when defining only a |
| single socket. |
| |
| <name> is an optional name provided for stats |
| |
| <mode> is the octal mode used to define access permissions on the |
| UNIX socket. It can also be set by default in the global |
| section's "unix-bind" statement. Note that some platforms |
| simply ignore this. |
| |
| <user> is the name of user that will be marked owner of the UNIX |
| socket. It can also be set by default in the global |
| section's "unix-bind" statement. Note that some platforms |
| simply ignore this. |
| |
| <group> is the name of a group that will be used to create the UNIX |
| socket. It can also be set by default in the global section's |
| "unix-bind" statement. Note that some platforms simply ignore |
| this. |
| |
| <uid> is the uid of user that will be marked owner of the UNIX |
| socket. It can also be set by default in the global section's |
| "unix-bind" statement. Note that some platforms simply ignore |
| this. |
| |
| <gid> is the gid of a group that will be used to create the UNIX |
| socket. It can also be set by default in the global section's |
| "unix-bind" statement. Note that some platforms simply ignore |
| this. |
| |
| transparent is an optional keyword which is supported only on certain |
| Linux kernels. It indicates that the addresses will be bound |
| even if they do not belong to the local machine. Any packet |
| targeting any of these addresses will be caught just as if |
| the address was locally configured. This normally requires |
| that IP forwarding is enabled. Caution! do not use this with |
| the default address '*', as it would redirect any traffic for |
| the specified port. This keyword is available only when |
| HAProxy is built with USE_LINUX_TPROXY=1. This parameter is |
| only compatible with TCP sockets. |
| |
| defer-accept is an optional keyword which is supported only on certain |
| Linux kernels. It states that a connection will only be |
| accepted once some data arrive on it, or at worst after the |
| first retransmit. This should be used only on protocols for |
| which the client talks first (eg: HTTP). It can slightly |
| improve performance by ensuring that most of the request is |
| already available when the connection is accepted. On the |
| other hand, it will not be able to detect connections which |
| don't talk. It is important to note that this option is |
| broken in all kernels up to 2.6.31, as the connection is |
| never accepted until the client talks. This can cause issues |
| with front firewalls which would see an established |
| connection while the proxy will only see it in SYN_RECV. |
| |
| accept-proxy is an optional keyword which enforces use of the PROXY |
| protocol over any connection accepted by this listener. The |
| PROXY protocol dictates the layer 3/4 addresses of the |
| incoming connection to be used everywhere an address is used, |
| with the only exception of "tcp-request connection" rules |
| which will only see the real connection address. Logs will |
| reflect the addresses indicated in the protocol, unless it is |
| violated, in which case the real address will still be used. |
| This keyword combined with support from external components |
| can be used as an efficient and reliable alternative to the |
| X-Forwarded-For mechanism which is not always reliable and |
| not even always usable. |
| |
| 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 |
| |
| See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol |
| documentation. |
| |
| |
| bind-process [ all | odd | even | <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, 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 |
| |
| 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 sensible 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". |
| |
| |
| 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 ] [ 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". |
| |
| 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. |
| |
| 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. |
| |
| 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 : none |
| |
| <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 "disabled" 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 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. |
| |
| 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 400, 403, 408, 500, 502, 503, and 504. |
| |
| <url> it is the exact contents of the "Location" header. It may contain |
| either a relative URI to an error page hosted on the same site, |
| or an absolute URI designating an error page on another site. |
| Special care should be given to relative URIs to avoid redirect |
| loops if the URI itself may generate the same error (eg: 500). |
| |
| It is important to understand that this keyword is not meant to rewrite |
| errors returned by the server, but errors detected and returned by HAProxy. |
| This is why the list of supported errors is limited to a small set. |
| |
| Note that both keyword return the HTTP 302 status code, which tells the |
| client to fetch the designated URL using the same HTTP method. This can be |
| quite problematic in case of non-GET methods such as POST, because the URL |
| sent to the client might not be allowed for something other than GET. To |
| workaround this problem, please use "errorloc303" which send the HTTP 303 |
| status code, indicating to the client that the URL must be fetched with a GET |
| request. |
| |
| See also : "errorfile", "errorloc303" |
| |
| |
| errorloc303 <code> <url> |
| Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <code> is the HTTP status code. Currently, HAProxy is capable of |
| generating codes 400, 403, 408, 500, 502, 503, and 504. |
| |
| <url> it is the exact contents of the "Location" header. It may contain |
| either a relative URI to an error page hosted on the same site, |
| or an absolute URI designating an error page on another site. |
| Special care should be given to relative URIs to avoid redirect |
| loops if the URI itself may generate the same error (eg: 500). |
| |
| It is important to understand that this keyword is not meant to rewrite |
| errors returned by the server, but errors detected and returned by HAProxy. |
| This is why the list of supported errors is limited to a small set. |
| |
| Note that both keyword return the HTTP 303 status code, which tells the |
| client to fetch the designated URL using the same HTTP GET method. This |
| solves the usual problems associated with "errorloc" and the 302 code. It is |
| possible that some very old browsers designed before HTTP/1.1 do not support |
| it, but no such problem 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. |
| |
| 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 reponse contents or specific status codes |
| May be used in sections : defaults | frontend | listen | backend |
| no | 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 preceeded 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 respose 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 respose 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 respose 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 respose 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-request expect status 200 |
| |
| # consider SQL errors as errors |
| http-request expect ! string SQL\ Error |
| |
| # consider status 5xx only as errors |
| http-request expect ! rstatus ^5 |
| |
| # check that we have a correct hexadecimal tag before /html |
| http-request 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. |
| |
| 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>]] |
| Enable per-instance logging of events and traffic. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| global should be used when the instance's logging parameters are the |
| same as the global ones. This is the most common usage. "global" |
| replaces <address>, <facility> and <level> with those of the log |
| entries found in the "global" section. Only one "log global" |
| statement may be used per instance, and this form takes no other |
| parameter. |
| |
| <address> indicates where to send the logs. It takes the same format as |
| for the "global" section's logs, and can be one of : |
| |
| - An IPv4 address optionally followed by a colon (':') and a UDP |
| port. If no port is specified, 514 is used by default (the |
| standard syslog port). |
| |
| - A filesystem path to a UNIX domain socket, keeping in mind |
| considerations for chroot (be sure the path is accessible |
| inside the chroot) and uid/gid (be sure the path is |
| appropriately writeable). |
| |
| <facility> must be one of the 24 standard syslog facilities : |
| |
| kern user mail daemon auth syslog lpr news |
| uucp cron auth2 ftp ntp audit alert cron2 |
| local0 local1 local2 local3 local4 local5 local6 local7 |
| |
| <level> is optional and can be specified to filter outgoing messages. By |
| default, all messages are sent. If a level is specified, only |
| messages with a severity at least as important as this level |
| will be sent. 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 |
| |
| Note that up to two "log" entries may be specified per instance. However, if |
| "log global" is used and if the "global" section already contains 2 log |
| entries, then additional log entries will be ignored. |
| |
| Also, it is important to keep in mind that it is the frontend which decides |
| what to log 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 |
| |
| |
| maxconn <conns> |
| Fix the maximum number of concurrent connections on a frontend |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <conns> is the maximum number of concurrent connections the frontend will |
| accept to serve. Excess connections will be queued by the system |
| in the socket's listen queue and will be served once a connection |
| closes. |
| |
| If the system supports it, it can be useful on big sites to raise this limit |
| very high so that haproxy manages connection queues, instead of leaving the |
| clients with unanswered connection attempts. This value should not exceed the |
| global maxconn. Also, keep in mind that a connection contains two buffers |
| of 8kB each, as well as some other data resulting in about 17 kB of RAM being |
| consumed per established connection. That means that a medium system equipped |
| with 1GB of RAM can withstand around 40000-50000 concurrent connections if |
| properly tuned. |
| |
| Also, when <conns> is set to large values, it is possible that the servers |
| are not sized to accept such loads, and for this reason it is generally wise |
| to assign them some reasonable connection limits. |
| |
| See also : "server", global section's "maxconn", "fullconn" |
| |
| |
| mode { tcp|http|health } |
| Set the running mode or protocol of the instance |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| tcp The instance will work in pure TCP mode. A full-duplex connection |
| will be established between clients and servers, and no layer 7 |
| examination will be performed. This is the default mode. It |
| should be used for SSL, SSH, SMTP, ... |
| |
| http The instance will work in HTTP mode. The client request will be |
| analyzed in depth before connecting to any server. Any request |
| which is not RFC-compliant will be rejected. Layer 7 filtering, |
| processing and switching will be possible. This is the mode which |
| brings HAProxy most of its value. |
| |
| health The instance will work in "health" mode. It will just reply "OK" |
| to incoming connections and close the connection. Nothing will be |
| logged. This mode is used to reply to external components health |
| checks. This mode is deprecated and should not be used anymore as |
| it is possible to do the same and even better by combining TCP or |
| HTTP modes with the "monitor" keyword. |
| |
| When doing content switching, it is mandatory that the frontend and the |
| backend are in the same mode (generally HTTP), otherwise the configuration |
| will be refused. |
| |
| Example : |
| defaults http_instances |
| mode http |
| |
| See also : "monitor", "monitor-net" |
| |
| |
| monitor fail { if | unless } <condition> |
| Add a condition to report a failure to a monitor 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. |
| |
| Example: |
| frontend www |
| mode http |
| acl site_dead nbsrv(dynamic) lt 2 |
| acl site_dead nbsrv(static) lt 2 |
| monitor-uri /site_alive |
| monitor fail if site_dead |
| |
| See also : "monitor-net", "monitor-uri" |
| |
| |
| monitor-net <source> |
| Declare a source network which is limited to monitor requests |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <source> is the source IPv4 address or network which will only be able to |
| get monitor responses to any request. It can be either an IPv4 |
| address, a host name, or an address followed by a slash ('/') |
| followed by a mask. |
| |
| In TCP mode, any connection coming from a source matching <source> will cause |
| the connection to be immediately closed without any log. This allows another |
| 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. |
| |
| Monitor requests are processed very early. It is not possible to block nor |
| divert them using ACLs. They cannot be logged either, and it is the intended |
| purpose. They are only used to report HAProxy's health to an upper component, |
| nothing more. Right now, it is not possible to set failure conditions on |
| requests caught by "monitor-net". |
| |
| 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. |
| |
| 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. 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 sensible 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> ] |
| 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. |
| |
| 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 as long as HAProxy does not support keep-alive |
| connections, only the first request of a connection will receive the header. |
| For this reason, it is important to ensure that "option httpclose" 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-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 compbined 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 eventhough 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 independant-streams |
| no option independant-streams |
| Enable or disable independant 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. |
| |
| See also : "timeout client" and "timeout server" |
| |
| |
| 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 : |
| user <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 >=4.0, 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 : |
| user <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 as long as HAProxy does not support keep-alive |
| connections, only the first request of a connection will receive the header. |
| For this reason, it is important to ensure that "option httpclose" 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 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 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 |
| Arguments : none |
| |
| When this option is enabled either on a frontend or on a backend, haproxy |
| will user kernel tcp splicing whenever possible to forward data going from |
| the client to the server. It might still use the recv/send scheme if there |
| are no spare pipes left. 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: see "option splice-auto" for usage limitations. |
| |
| Example : |
| option splice-request |
| |
| 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-auto", "option splice-response", and global options |
| "nosplice" and "maxpipes" |
| |
| |
| option splice-response |
| no option splice-response |
| Enable or disable automatic kernel acceleration on sockets for responses |
| 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 user kernel tcp splicing whenever possible to forward data going from |
| the server to the client. It might still use the recv/send scheme if there |
| are no spare pipes left. 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: see "option splice-auto" for usage limitations. |
| |
| Example : |
| option splice-response |
| |
| 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-auto", "option splice-request", and global options |
| "nosplice" and "maxpipes" |
| |
| |
| option srvtcpka |
| no option srvtcpka |
| Enable or disable the sending of TCP keepalive packets on the server side |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| 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 "srvtcpka" enables the emission of TCP keep-alive probes on the |
| server side of a connection, which should help when session expirations are |
| noticed between HAProxy and a 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 clitcpka", "option tcpka" |
| |
| |
| option ssl-hello-chk |
| Use SSLv3 client hello health checks for server testing |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| When some SSL-based protocols are relayed in TCP mode through HAProxy, it is |
| possible to test that the server correctly talks SSL instead of just testing |
| that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure |
| SSLv3 client hello messages are sent once the connection is established to |
| the server, and the response is analyzed to find an SSL server hello message. |
| The server is considered valid only when the response contains this server |
| hello message. |
| |
| All servers tested till there correctly reply to SSLv3 client hello messages, |
| and most servers tested do not even log the requests containing only hello |
| messages, which is appreciable. |
| |
| See also: "option httpchk" |
| |
| |
| option tcp-smart-accept |
| no option tcp-smart-accept |
| Enable or disable the saving of one ACK packet during the accept sequence |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : none |
| |
| When an HTTP connection request comes in, the system acknowledges it on |
| behalf of HAProxy, then the client immediately sends its request, and the |
| system acknowledges it too while it is notifying HAProxy about the new |
| connection. HAProxy then reads the request and responds. This means that we |
| have one TCP ACK sent by the system for nothing, because the request could |
| very well be acknowledged by HAProxy when it sends its response. |
| |
| For this reason, in HTTP mode, HAProxy automatically asks the system to avoid |
| sending this useless ACK on platforms which support it (currently at least |
| Linux). It must not cause any problem, because the system will send it anyway |
| after 40 ms if the response takes more time than expected to come. |
| |
| During complex network debugging sessions, it may be desirable to disable |
| this optimization because delayed ACKs can make troubleshooting more complex |
| when trying to identify where packets are delayed. It is then possible to |
| fall back to normal behaviour by specifying "no option tcp-smart-accept". |
| |
| It is also possible to force it for non-HTTP proxies by simply specifying |
| "option tcp-smart-accept". For instance, it can make sense with some services |
| such as SMTP where the server speaks first. |
| |
| It is recommended to avoid forcing this option in a defaults section. In case |
| of doubt, consider setting it back to automatic values by prepending the |
| "default" keyword before it, or disabling it using the "no" keyword. |
| |
| See also : "option tcp-smart-connect" |
| |
| |
| option tcp-smart-connect |
| no option tcp-smart-connect |
| Enable or disable the saving of one ACK packet during the connect sequence |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| On certain systems (at least Linux), HAProxy can ask the kernel not to |
| immediately send an empty ACK upon a connection request, but to directly |
| send the buffer request instead. This saves one packet on the network and |
| thus boosts performance. It can also be useful for some servers, because they |
| immediately get the request along with the incoming connection. |
| |
| This feature is enabled when "option tcp-smart-connect" is set in a backend. |
| It is not enabled by default because it makes network troubleshooting more |
| complex. |
| |
| It only makes sense to enable it with protocols where the client speaks first |
| such as HTTP. In other situations, if there is no data to send in place of |
| the ACK, a normal ACK is sent. |
| |
| 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 tcp-smart-accept" |
| |
| |
| option tcpka |
| Enable or disable the sending of TCP keepalive packets on both sides |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| 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 "tcpka" enables the emission of TCP keep-alive probes on both |
| the client and server sides of a connection. Note that this is meaningful |
| only in "defaults" or "listen" sections. If this option is used in a |
| frontend, only the client side will get keep-alives, and if this option is |
| used in a backend, only the server side will get keep-alives. For this |
| reason, it is strongly recommended to explicitly use "option clitcpka" and |
| "option srvtcpka" when the configuration is split between frontends and |
| backends. |
| |
| See also : "option clitcpka", "option srvtcpka" |
| |
| |
| option tcplog |
| Enable advanced logging of TCP connections with session state and timers |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| 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 tcplog", each log line turns into a much richer format including, but |
| not limited to, the connection timers, the session status, the connections |
| numbers, the frontend, backend and server name, and of course the source |
| address and ports. This option is useful for pure TCP proxies in order to |
| find which of the client or server disconnects or times out. For normal HTTP |
| proxies, it's better to use "option httplog" which is even more complete. |
| |
| This option may be set either in the frontend or the backend. |
| |
| See also : "option httplog", and section 8 about logging. |
| |
| |
| option transparent |
| no option transparent |
| Enable client-side transparent proxying |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| This option was introduced in order to provide layer 7 persistence to layer 3 |
| load balancers. The idea is to use the OS's ability to redirect an incoming |
| connection for a remote address to a local process (here HAProxy), and let |
| this process know what address was initially requested. When this option is |
| used, sessions without cookies will be forwarded to the original destination |
| IP address of the incoming request (which should match that of another |
| equipment), while requests with cookies will still be forwarded to the |
| appropriate server. |
| |
| Note that contrary to a common belief, this option does NOT make HAProxy |
| present the client's IP to the server when establishing the connection. |
| |
| See also: the "usersrc" argument of the "source" keyword, and the |
| "transparent" option of the "bind" keyword. |
| |
| |
| persist rdp-cookie |
| persist rdp-cookie(name) |
| Enable RDP cookie-based persistence |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <name> is the optional name of the RDP cookie to check. If omitted, the |
| default cookie name "msts" will be used. There currently is no |
| valid reason to change this name. |
| |
| This statement enables persistence based on an RDP cookie. The RDP cookie |
| contains all information required to find the server in the list of known |
| servers. So when this option is set in the backend, the request is analysed |
| and if an RDP cookie is found, it is decoded. If it matches a known server |
| which is still UP (or if "option persist" is set), then the connection is |
| forwarded to this server. |
| |
| Note that this only makes sense in a TCP backend, but for this to work, the |
| frontend must have waited long enough to ensure that an RDP cookie is present |
| in the request buffer. This is the same requirement as with the "rdp-cookie" |
| load-balancing method. Thus it is highly recommended to put all statements in |
| a single "listen" section. |
| |
| Also, it is important to understand that the terminal server will emit this |
| RDP cookie only if it is configured for "token redirection mode", which means |
| that the "IP address redirection" option is disabled. |
| |
| Example : |
| listen tse-farm |
| bind :3389 |
| # wait up to 5s for an RDP cookie in the request |
| tcp-request inspect-delay 5s |
| tcp-request content accept if RDP_COOKIE |
| # apply RDP cookie persistence |
| persist rdp-cookie |
| # if server is unknown, let's balance on the same cookie. |
| # alternatively, "balance leastconn" may be useful too. |
| balance rdp-cookie |
| server srv1 1.1.1.1:3389 |
| server srv2 1.1.1.2:3389 |
| |
| See also : "balance rdp-cookie", "tcp-request" and the "req_rdp_cookie" ACL. |
| |
| |
| rate-limit sessions <rate> |
| Set a limit on the number of new sessions accepted per second on a frontend |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <rate> The <rate> parameter is an integer designating the maximum number |
| of new sessions per second to accept on the frontend. |
| |
| When the frontend reaches the specified number of new sessions per second, it |
| stops accepting new connections until the rate drops below the limit again. |
| During this time, the pending sessions will be kept in the socket's backlog |
| (in system buffers) and haproxy will not even be aware that sessions are |
| pending. When applying very low limit on a highly loaded service, it may make |
| sense to increase the socket's backlog using the "backlog" keyword. |
| |
| This feature is particularly efficient at blocking connection-based attacks |
| or service abuse on fragile servers. Since the session rate is measured every |
| millisecond, it is extremely accurate. Also, the limit applies immediately, |
| no delay is needed at all to detect the threshold. |
| |
| Example : limit the connection rate on SMTP to 10 per second max |
| listen smtp |
| mode tcp |
| bind :25 |
| rate-limit sessions 10 |
| server 127.0.0.1:1025 |
| |
| Note : when the maximum rate is reached, the frontend's status appears as |
| "FULL" in the statistics, exactly as when it is saturated. |
| |
| See also : the "backlog" keyword and the "fe_sess_rate" ACL criterion. |
| |
| |
| redirect location <to> [code <code>] <option> [{if | unless} <condition>] |
| redirect prefix <to> [code <code>] <option> [{if | unless} <condition>] |
| Return an HTTP redirection if/unless a condition is matched |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| If/unless the condition is matched, the HTTP request will lead to a redirect |
| response. If no condition is specified, the redirect applies unconditionally. |
| |
| Arguments : |
| <to> With "redirect location", the exact value in <to> is placed into |
| the HTTP "Location" header. In case of "redirect prefix", the |
| "Location" header is built from the concatenation of <to> and the |
| complete URI, including the query string, unless the "drop-query" |
| option is specified (see below). As a special case, if <to> |
| equals exactly "/" in prefix mode, then nothing is inserted |
| before the original URI. It allows one to redirect to the same |
| URL. |
| |
| <code> The code is optional. It indicates which type of HTTP redirection |
| is desired. Only codes 301, 302 and 303 are supported, and 302 is |
| used if no code is specified. 301 means "Moved permanently", and |
| a browser may cache the Location. 302 means "Moved permanently" |
| and means that the browser should not cache the redirection. 303 |
| is equivalent to 302 except that the browser will fetch the |
| location with a GET method. |
| |
| <option> There are several options which can be specified to adjust the |
| expected behaviour of a redirection : |
| |
| - "drop-query" |
| When this keyword is used in a prefix-based redirection, then the |
| location will be set without any possible query-string, which is useful |
| for directing users to a non-secure page for instance. It has no effect |
| with a location-type redirect. |
| |
| - "append-slash" |
| This keyword may be used in conjunction with "drop-query" to redirect |
| users who use a URL not ending with a '/' to the same one with the '/'. |
| It can be useful to ensure that search engines will only see one URL. |
| For this, a return code 301 is preferred. |
| |
| - "set-cookie NAME[=value]" |
| A "Set-Cookie" header will be added with NAME (and optionally "=value") |
| to the response. This is sometimes used to indicate that a user has |
| been seen, for instance to protect against some types of DoS. No other |
| cookie option is added, so the cookie will be a session cookie. Note |
| that for a browser, a sole cookie name without an equal sign is |
| different from a cookie with an equal sign. |
| |
| - "clear-cookie NAME[=]" |
| A "Set-Cookie" header will be added with NAME (and optionally "="), but |
| with the "Max-Age" attribute set to zero. This will tell the browser to |
| delete this cookie. It is useful for instance on logout pages. It is |
| important to note that clearing the cookie "NAME" will not remove a |
| cookie set with "NAME=value". You have to clear the cookie "NAME=" for |
| that, because the browser makes the difference. |
| |
| Example: move the login URL only to HTTPS. |
| acl clear dst_port 80 |
| acl secure dst_port 8080 |
| acl login_page url_beg /login |
| acl logout url_beg /logout |
| acl uid_given url_reg /login?userid=[^&]+ |
| acl cookie_set hdr_sub(cookie) SEEN=1 |
| |
| redirect prefix https://mysite.com set-cookie SEEN=1 if !cookie_set |
| redirect prefix https://mysite.com if login_page !secure |
| redirect prefix http://mysite.com drop-query if login_page !uid_given |
| redirect location http://mysite.com/ if !login_page secure |
| redirect location / clear-cookie USERID= if logout |
| |
| Example: send redirects for request for articles without a '/'. |
| acl missing_slash path_reg ^/article/[^/]*$ |
| redirect code 301 prefix / drop-query append-slash if missing_slash |
| |
| See section 7 about ACL usage. |
| |
| |
| redisp (deprecated) |
| redispatch (deprecated) |
| 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 "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 deprecated, do not use it in any new configuration, use the new |
| "option redispatch" instead. |
| |
| See also : "option redispatch" |
| |
| |
| reqadd <string> [{if | unless} <cond>] |
| Add a header at the end of the HTTP request |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <string> is the complete line to be added. Any space or known delimiter |
| must be escaped using a backslash ('\'). Please refer to section |
| 6 about HTTP header manipulation for more information. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| A new line consisting in <string> followed by a line feed will be added after |
| the last header of an HTTP request. |
| |
| Header transformations only apply to traffic which passes through HAProxy, |
| and not to traffic generated by HAProxy, such as health-checks or error |
| responses. |
| |
| Example : add "X-Proto: SSL" to requests coming via port 81 |
| acl is-ssl dst_port 81 |
| reqadd X-Proto:\ SSL if is-ssl |
| |
| See also: "rspadd", section 6 about HTTP header manipulation, and section 7 |
| about ACLs. |
| |
| |
| reqallow <search> [{if | unless} <cond>] |
| reqiallow <search> [{if | unless} <cond>] (ignore case) |
| Definitely allow an HTTP request if a line matches a regular expression |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| request line. This is an extended regular expression. Parenthesis |
| grouping is supported and no preliminary backslash is required. |
| Any space or known delimiter must be escaped using a backslash |
| ('\'). The pattern applies to a full line at a time. The |
| "reqallow" keyword strictly matches case while "reqiallow" |
| ignores case. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| A request containing any line which matches extended regular expression |
| <search> will mark the request as allowed, even if any later test would |
| result in a deny. The test applies both to the request line and to request |
| headers. Keep in mind that URLs in request line are case-sensitive while |
| header names are not. |
| |
| It is easier, faster and more powerful to use ACLs to write access policies. |
| Reqdeny, reqallow and reqpass should be avoided in new designs. |
| |
| Example : |
| # allow www.* but refuse *.local |
| reqiallow ^Host:\ www\. |
| reqideny ^Host:\ .*\.local |
| |
| See also: "reqdeny", "block", section 6 about HTTP header manipulation, and |
| section 7 about ACLs. |
| |
| |
| reqdel <search> [{if | unless} <cond>] |
| reqidel <search> [{if | unless} <cond>] (ignore case) |
| Delete all headers matching a regular expression in an HTTP request |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| request line. This is an extended regular expression. Parenthesis |
| grouping is supported and no preliminary backslash is required. |
| Any space or known delimiter must be escaped using a backslash |
| ('\'). The pattern applies to a full line at a time. The "reqdel" |
| keyword strictly matches case while "reqidel" ignores case. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| Any header line matching extended regular expression <search> in the request |
| will be completely deleted. Most common use of this is to remove unwanted |
| and/or dangerous headers or cookies from a request before passing it to the |
| next servers. |
| |
| Header transformations only apply to traffic which passes through HAProxy, |
| and not to traffic generated by HAProxy, such as health-checks or error |
| responses. Keep in mind that header names are not case-sensitive. |
| |
| Example : |
| # remove X-Forwarded-For header and SERVER cookie |
| reqidel ^X-Forwarded-For:.* |
| reqidel ^Cookie:.*SERVER= |
| |
| See also: "reqadd", "reqrep", "rspdel", section 6 about HTTP header |
| manipulation, and section 7 about ACLs. |
| |
| |
| reqdeny <search> [{if | unless} <cond>] |
| reqideny <search> [{if | unless} <cond>] (ignore case) |
| Deny an HTTP request if a line matches a regular expression |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| request line. This is an extended regular expression. Parenthesis |
| grouping is supported and no preliminary backslash is required. |
| Any space or known delimiter must be escaped using a backslash |
| ('\'). The pattern applies to a full line at a time. The |
| "reqdeny" keyword strictly matches case while "reqideny" ignores |
| case. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| A request containing any line which matches extended regular expression |
| <search> will mark the request as denied, even if any later test would |
| result in an allow. The test applies both to the request line and to request |
| headers. Keep in mind that URLs in request line are case-sensitive while |
| header names are not. |
| |
| A denied request will generate an "HTTP 403 forbidden" response once the |
| complete request has been parsed. This is consistent with what is practiced |
| using ACLs. |
| |
| It is easier, faster and more powerful to use ACLs to write access policies. |
| Reqdeny, reqallow and reqpass should be avoided in new designs. |
| |
| Example : |
| # refuse *.local, then allow www.* |
| reqideny ^Host:\ .*\.local |
| reqiallow ^Host:\ www\. |
| |
| See also: "reqallow", "rspdeny", "block", section 6 about HTTP header |
| manipulation, and section 7 about ACLs. |
| |
| |
| reqpass <search> [{if | unless} <cond>] |
| reqipass <search> [{if | unless} <cond>] (ignore case) |
| Ignore any HTTP request line matching a regular expression in next rules |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| request line. This is an extended regular expression. Parenthesis |
| grouping is supported and no preliminary backslash is required. |
| Any space or known delimiter must be escaped using a backslash |
| ('\'). The pattern applies to a full line at a time. The |
| "reqpass" keyword strictly matches case while "reqipass" ignores |
| case. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| A request containing any line which matches extended regular expression |
| <search> will skip next rules, without assigning any deny or allow verdict. |
| The test applies both to the request line and to request headers. Keep in |
| mind that URLs in request line are case-sensitive while header names are not. |
| |
| It is easier, faster and more powerful to use ACLs to write access policies. |
| Reqdeny, reqallow and reqpass should be avoided in new designs. |
| |
| Example : |
| # refuse *.local, then allow www.*, but ignore "www.private.local" |
| reqipass ^Host:\ www.private\.local |
| reqideny ^Host:\ .*\.local |
| reqiallow ^Host:\ www\. |
| |
| See also: "reqallow", "reqdeny", "block", section 6 about HTTP header |
| manipulation, and section 7 about ACLs. |
| |
| |
| reqrep <search> <string> [{if | unless} <cond>] |
| reqirep <search> <string> [{if | unless} <cond>] (ignore case) |
| Replace a regular expression with a string in an HTTP request line |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| request line. This is an extended regular expression. Parenthesis |
| grouping is supported and no preliminary backslash is required. |
| Any space or known delimiter must be escaped using a backslash |
| ('\'). The pattern applies to a full line at a time. The "reqrep" |
| keyword strictly matches case while "reqirep" ignores case. |
| |
| <string> is the complete line to be added. Any space or known delimiter |
| must be escaped using a backslash ('\'). References to matched |
| pattern groups are possible using the common \N form, with N |
| being a single digit between 0 and 9. Please refer to section |
| 6 about HTTP header manipulation for more information. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| Any line matching extended regular expression <search> in the request (both |
| the request line and header lines) will be completely replaced with <string>. |
| Most common use of this is to rewrite URLs or domain names in "Host" headers. |
| |
| Header transformations only apply to traffic which passes through HAProxy, |
| and not to traffic generated by HAProxy, such as health-checks or error |
| responses. Note that for increased readability, it is suggested to add enough |
| spaces between the request and the response. Keep in mind that URLs in |
| request line are case-sensitive while header names are not. |
| |
| Example : |
| # replace "/static/" with "/" at the beginning of any request path. |
| reqrep ^([^\ ]*)\ /static/(.*) \1\ /\2 |
| # replace "www.mydomain.com" with "www" in the host name. |
| reqirep ^Host:\ www.mydomain.com Host:\ www |
| |
| See also: "reqadd", "reqdel", "rsprep", section 6 about HTTP header |
| manipulation, and section 7 about ACLs. |
| |
| |
| reqtarpit <search> [{if | unless} <cond>] |
| reqitarpit <search> [{if | unless} <cond>] (ignore case) |
| Tarpit an HTTP request containing a line matching a regular expression |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| request line. This is an extended regular expression. Parenthesis |
| grouping is supported and no preliminary backslash is required. |
| Any space or known delimiter must be escaped using a backslash |
| ('\'). The pattern applies to a full line at a time. The |
| "reqtarpit" keyword strictly matches case while "reqitarpit" |
| ignores case. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| A request containing any line which matches extended regular expression |
| <search> will be tarpitted, which means that it will connect to nowhere, will |
| be kept open for a pre-defined time, then will return an HTTP error 500 so |
| that the attacker does not suspect it has been tarpitted. The status 500 will |
| be reported in the logs, but the completion flags will indicate "PT". The |
| delay is defined by "timeout tarpit", or "timeout connect" if the former is |
| not set. |
| |
| The goal of the tarpit is to slow down robots attacking servers with |
| identifiable requests. Many robots limit their outgoing number of connections |
| and stay connected waiting for a reply which can take several minutes to |
| come. Depending on the environment and attack, it may be particularly |
| efficient at reducing the load on the network and firewalls. |
| |
| Examples : |
| # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but |
| # block all others. |
| reqipass ^User-Agent:\.*(Mozilla|MSIE) |
| reqitarpit ^User-Agent: |
| |
| # block bad guys |
| acl badguys src 10.1.0.3 172.16.13.20/28 |
| reqitarpit . if badguys |
| |
| See also: "reqallow", "reqdeny", "reqpass", section 6 about HTTP header |
| manipulation, and section 7 about ACLs. |
| |
| |
| retries <value> |
| Set the number of retries to perform on a server after a connection failure |
| May be used in sections: defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <value> is the number of times a connection attempt should be retried on |
| a server when a connection either is refused or times out. The |
| default value is 3. |
| |
| It is important to understand that this value applies to the number of |
| connection attempts, not full requests. When a connection has effectively |
| been established to a server, there will be no more retry. |
| |
| In order to avoid immediate reconnections to a server which is restarting, |
| a turn-around timer of 1 second is applied before a retry occurs. |
| |
| When "option redispatch" is set, the last retry may be performed on another |
| server even if a cookie references a different server. |
| |
| See also : "option redispatch" |
| |
| |
| rspadd <string> [{if | unless} <cond>] |
| Add a header at the end of the HTTP response |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <string> is the complete line to be added. Any space or known delimiter |
| must be escaped using a backslash ('\'). Please refer to section |
| 6 about HTTP header manipulation for more information. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| A new line consisting in <string> followed by a line feed will be added after |
| the last header of an HTTP response. |
| |
| Header transformations only apply to traffic which passes through HAProxy, |
| and not to traffic generated by HAProxy, such as health-checks or error |
| responses. |
| |
| See also: "reqadd", section 6 about HTTP header manipulation, and section 7 |
| about ACLs. |
| |
| |
| rspdel <search> [{if | unless} <cond>] |
| rspidel <search> [{if | unless} <cond>] (ignore case) |
| Delete all headers matching a regular expression in an HTTP response |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| response line. This is an extended regular expression, so |
| parenthesis grouping is supported and no preliminary backslash |
| is required. Any space or known delimiter must be escaped using |
| a backslash ('\'). The pattern applies to a full line at a time. |
| The "rspdel" keyword strictly matches case while "rspidel" |
| ignores case. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| Any header line matching extended regular expression <search> in the response |
| will be completely deleted. Most common use of this is to remove unwanted |
| and/or sensible headers or cookies from a response before passing it to the |
| client. |
| |
| Header transformations only apply to traffic which passes through HAProxy, |
| and not to traffic generated by HAProxy, such as health-checks or error |
| responses. Keep in mind that header names are not case-sensitive. |
| |
| Example : |
| # remove the Server header from responses |
| reqidel ^Server:.* |
| |
| See also: "rspadd", "rsprep", "reqdel", section 6 about HTTP header |
| manipulation, and section 7 about ACLs. |
| |
| |
| rspdeny <search> [{if | unless} <cond>] |
| rspideny <search> [{if | unless} <cond>] (ignore case) |
| Block an HTTP response if a line matches a regular expression |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| response line. This is an extended regular expression, so |
| parenthesis grouping is supported and no preliminary backslash |
| is required. Any space or known delimiter must be escaped using |
| a backslash ('\'). The pattern applies to a full line at a time. |
| The "rspdeny" keyword strictly matches case while "rspideny" |
| ignores case. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| A response containing any line which matches extended regular expression |
| <search> will mark the request as denied. The test applies both to the |
| response line and to response headers. Keep in mind that header names are not |
| case-sensitive. |
| |
| Main use of this keyword is to prevent sensitive information leak and to |
| block the response before it reaches the client. If a response is denied, it |
| will be replaced with an HTTP 502 error so that the client never retrieves |
| any sensitive data. |
| |
| It is easier, faster and more powerful to use ACLs to write access policies. |
| Rspdeny should be avoided in new designs. |
| |
| Example : |
| # Ensure that no content type matching ms-word will leak |
| rspideny ^Content-type:\.*/ms-word |
| |
| See also: "reqdeny", "acl", "block", section 6 about HTTP header manipulation |
| and section 7 about ACLs. |
| |
| |
| rsprep <search> <string> [{if | unless} <cond>] |
| rspirep <search> <string> [{if | unless} <cond>] (ignore case) |
| Replace a regular expression with a string in an HTTP response line |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <search> is the regular expression applied to HTTP headers and to the |
| response line. This is an extended regular expression, so |
| parenthesis grouping is supported and no preliminary backslash |
| is required. Any space or known delimiter must be escaped using |
| a backslash ('\'). The pattern applies to a full line at a time. |
| The "rsprep" keyword strictly matches case while "rspirep" |
| ignores case. |
| |
| <string> is the complete line to be added. Any space or known delimiter |
| must be escaped using a backslash ('\'). References to matched |
| pattern groups are possible using the common \N form, with N |
| being a single digit between 0 and 9. Please refer to section |
| 6 about HTTP header manipulation for more information. |
| |
| <cond> is an optional matching condition built from ACLs. It makes it |
| possible to ignore this rule when other conditions are not met. |
| |
| Any line matching extended regular expression <search> in the response (both |
| the response line and header lines) will be completely replaced with |
| <string>. Most common use of this is to rewrite Location headers. |
| |
| Header transformations only apply to traffic which passes through HAProxy, |
| and not to traffic generated by HAProxy, such as health-checks or error |
| responses. Note that for increased readability, it is suggested to add enough |
| spaces between the request and the response. Keep in mind that header names |
| are not case-sensitive. |
| |
| Example : |
| # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com" |
| rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com |
| |
| See also: "rspadd", "rspdel", "reqrep", section 6 about HTTP header |
| manipulation, and section 7 about ACLs. |
| |
| |
| server <name> <address>[:port] [param*] |
| Declare a server in a backend |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| Arguments : |
| <name> is the internal name assigned to this server. This name will |
| appear in logs and alerts. |
| |
| <address> is the IPv4 address of the server. Alternatively, a resolvable |
| hostname is supported, but this name will be resolved during |
| start-up. Address "0.0.0.0" or "*" has a special meaning. It |
| indicates that the connection will be forwarded to the same IP |
| address as the one from the client connection. This is useful in |
| transparent proxy architectures where the client's connection is |
| intercepted and haproxy must forward to the original destination |
| address. This is more or less what the "transparent" keyword does |
| except that with a server it's possible to limit concurrency and |
| to report statistics. |
| |
| <ports> is an optional port specification. If set, all connections will |
| be sent to this port. If unset, the same port the client |
| connected to will be used. The port may also be prefixed by a "+" |
| or a "-". In this case, the server's port will be determined by |
| adding this value to the client's port. |
| |
| <param*> is a list of parameters for this server. The "server" keywords |
| accepts an important number of options and has a complete section |
| dedicated to it. Please refer to section 5 for more details. |
| |
| Examples : |
| server first 10.1.1.1:1080 cookie first check inter 1000 |
| server second 10.1.1.2:1080 cookie second check inter 1000 |
| |
| See also: "default-server" and section 5 about server options |
| |
| |
| source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
| source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ] |
| source <addr>[:<port>] [interface <name>] |
| Set the source address for outgoing connections |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <addr> is the IPv4 address HAProxy will bind to before connecting to a |
| server. This address is also used as a source for health checks. |
| The default value of 0.0.0.0 means that the system will select |
| the most appropriate address to reach its destination. |
| |
| <port> is an optional port. It is normally not needed but may be useful |
| in some very specific contexts. The default value of zero means |
| the system will select a free port. Note that port ranges are not |
| supported in the backend. If you want to force port ranges, you |
| have to specify them on each "server" line. |
| |
| <addr2> is the IP address to present to the server when connections are |
| forwarded in full transparent proxy mode. This is currently only |
| supported on some patched Linux kernels. When this address is |
| specified, clients connecting to the server will be presented |
| with this address, while health checks will still use the address |
| <addr>. |
| |
| <port2> is the optional port to present to the server when connections |
| are forwarded in full transparent proxy mode (see <addr2> above). |
| The default value of zero means the system will select a free |
| port. |
| |
| <hdr> is the name of a HTTP header in which to fetch the IP to bind to. |
| This is the name of a comma-separated header list which can |
| contain multiple IP addresses. By default, the last occurrence is |
| used. This is designed to work with the X-Forwarded-For header |
| and to automatically bind to the the client's IP address as seen |
| by previous proxy, typically Stunnel. In order to use another |
| occurrence from the last one, please see the <occ> parameter |
| below. When the header (or occurrence) is not found, no binding |
| is performed so that the proxy's default IP address is used. Also |
| keep in mind that the header name is case insensitive, as for any |
| HTTP header. |
| |
| <occ> is the occurrence number of a value to be used in a multi-value |
| header. This is to be used in conjunction with "hdr_ip(<hdr>)", |
| in order to specificy which occurrence to use for the source IP |
| address. Positive values indicate a position from the first |
| occurrence, 1 being the first one. Negative values indicate |
| positions relative to the last one, -1 being the last one. This |
| is helpful for situations where an X-Forwarded-For header is set |
| at the entry point of an infrastructure and must be used several |
| proxy layers away. When this value is not specified, -1 is |
| assumed. Passing a zero here disables the feature. |
| |
| <name> is an optional interface name to which to bind to for outgoing |
| traffic. On systems supporting this features (currently, only |
| Linux), this allows one to bind all traffic to the server to |
| this interface even if it is not the one the system would select |
| based on routing tables. This should be used with extreme care. |
| Note that using this option requires root privileges. |
| |
| The "source" keyword is useful in complex environments where a specific |
| address only is allowed to connect to the servers. It may be needed when a |
| private address must be used through a public gateway for instance, and it is |
| known that the system cannot determine the adequate source address by itself. |
| |
| An extension which is available on certain patched Linux kernels may be used |
| through the "usesrc" optional keyword. It makes it possible to connect to the |
| servers with an IP address which does not belong to the system itself. This |
| is called "full transparent proxy mode". For this to work, the destination |
| servers have to route their traffic back to this address through the machine |
| running HAProxy, and IP forwarding must generally be enabled on this machine. |
| |
| In this "full transparent proxy" mode, it is possible to force a specific IP |
| address to be presented to the servers. This is not much used in fact. A more |
| common use is to tell HAProxy to present the client's IP address. For this, |
| there are two methods : |
| |
| - present the client's IP and port addresses. This is the most transparent |
| mode, but it can cause problems when IP connection tracking is enabled on |
| the machine, because a same connection may be seen twice with different |
| states. However, this solution presents the huge advantage of not |
| limiting the system to the 64k outgoing address+port couples, because all |
| of the client ranges may be used. |
| |
| - present only the client's IP address and select a spare port. This |
| solution is still quite elegant but slightly less transparent (downstream |
| firewalls logs will not match upstream's). It also presents the downside |
| of limiting the number of concurrent connections to the usual 64k ports. |
| However, since the upstream and downstream ports are different, local IP |
| connection tracking on the machine will not be upset by the reuse of the |
| same session. |
| |
| Note that depending on the transparent proxy technology used, it may be |
| required to force the source address. In fact, cttproxy version 2 requires an |
| IP address in <addr> above, and does not support setting of "0.0.0.0" as the |
| IP address because it creates NAT entries which much match the exact outgoing |
| address. Tproxy version 4 and some other kernel patches which work in pure |
| forwarding mode generally will not have this limitation. |
| |
| This option sets the default source for all servers in the backend. It may |
| also be specified in a "defaults" section. Finer source address specification |
| is possible at the server level using the "source" server option. Refer to |
| section 5 for more information. |
| |
| Examples : |
| backend private |
| # Connect to the servers using our 192.168.1.200 source address |
| source 192.168.1.200 |
| |
| backend transparent_ssl1 |
| # Connect to the SSL farm from the client's source address |
| source 192.168.1.200 usesrc clientip |
| |
| backend transparent_ssl2 |
| # Connect to the SSL farm from the client's source address and port |
| # not recommended if IP conntrack is present on the local machine. |
| source 192.168.1.200 usesrc client |
| |
| backend transparent_ssl3 |
| # Connect to the SSL farm from the client's source address. It |
| # is more conntrack-friendly. |
| source 192.168.1.200 usesrc clientip |
| |
| backend transparent_smtp |
| # Connect to the SMTP farm from the client's source address/port |
| # with Tproxy version 4. |
| source 0.0.0.0 usesrc clientip |
| |
| backend transparent_http |
| # Connect to the servers using the client's IP as seen by previous |
| # proxy. |
| source 0.0.0.0 usesrc hdr_ip(x-forwarded-for,-1) |
| |
| See also : the "source" server option in section 5, the Tproxy patches for |
| the Linux kernel on www.balabit.com, the "bind" keyword. |
| |
| |
| srvtimeout <timeout> (deprecated) |
| Set the maximum inactivity time on the server side. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <timeout> is the timeout value 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 server is expected to acknowledge or |
| send data. In HTTP mode, this timeout is particularly important to consider |
| during the first phase of the server's response, when it has to send the |
| headers, as it directly represents the server's processing time for the |
| request. To find out what value to put there, it's often good to start with |
| what would be considered as unacceptable response times, then check the logs |
| to observe the response time distribution, and adjust the value accordingly. |
| |
| 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. Whatever the expected server |
| response times, it is a good practice to cover at least one or several TCP |
| packet losses by specifying timeouts that are slightly above multiples of 3 |
| seconds (eg: 4 or 5 seconds minimum). |
| |
| 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 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 server" instead. |
| |
| See also : "timeout server", "timeout client" and "clitimeout". |
| |
| |
| stats admin { if | unless } <cond> |
| Enable statistics admin level if/unless a condition is matched |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| |
| This statement enables the statistics admin level if/unless a condition is |
| matched. |
| |
| The admin level allows to enable/disable servers from the web interface. By |
| default, statistics page is read-only for security reasons. |
| |
| 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. |
| |
| Currently, there are 2 known limitations : |
| |
| - The POST data are limited to one packet, which means that if the list of |
| servers is too long, the request won't be processed. It is recommended |
| to alter few servers at a time. |
| |
| - Expect: 100-continue is not supported. |
| |
| Example : |
| # statistics admin level only for localhost |
| backend stats_localhost |
| stats enable |
| stats admin if LOCALHOST |
| |
| Example : |
| # statistics admin level always enabled because of the authentication |
| backend stats_auth |
| stats enable |
| stats auth admin:AdMiN123 |
| stats admin if TRUE |
| |
| Example : |
| # statistics admin level depends on the authenticated user |
| userlist stats-auth |
| group admin users admin |
| user admin insecure-password AdMiN123 |
| group readonly users haproxy |
| user haproxy insecure-password haproxy |
| |
| backend stats_auth |
| stats enable |
| acl AUTH http_auth(stats-auth) |
| acl AUTH_ADMIN http_auth_group(stats-auth) admin |
| stats http-request auth unless AUTH |
| stats admin if AUTH_ADMIN |
| |
| See also : "stats enable", "stats auth", "stats http-request", "nbproc", |
| "bind-process", section 3.4 about userlists and section 7 about |
| ACL usage. |
| |
| |
| stats auth <user>:<passwd> |
| Enable statistics with authentication and grant access to an account |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <user> is a user name to grant access to |
| |
| <passwd> is the cleartext password associated to this user |
| |
| This statement enables statistics with default settings, and restricts access |
| to declared users only. It may be repeated as many times as necessary to |
| allow as many users as desired. When a user tries to access the statistics |
| without a valid account, a "401 Forbidden" response will be returned so that |
| the browser asks the user to provide a valid user and password. The real |
| which will be returned to the browser is configurable using "stats realm". |
| |
| Since the authentication method is HTTP Basic Authentication, the passwords |
| circulate in cleartext on the network. Thus, it was decided that the |
| configuration file would also use cleartext passwords to remind the users |
| that those ones should not be sensible and not shared with any other account. |
| |
| It is also possible to reduce the scope of the proxies which appear in the |
| report using "stats scope". |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # public access (limited to this backend only) |
| backend public_www |
| server srv1 192.168.0.1:80 |
| stats enable |
| stats hide-version |
| stats scope . |
| stats uri /admin?stats |
| stats realm Haproxy\ Statistics |
| stats auth admin1:AdMiN123 |
| stats auth admin2:AdMiN321 |
| |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also : "stats enable", "stats realm", "stats scope", "stats uri" |
| |
| |
| stats enable |
| Enable statistics reporting with default settings |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| This statement enables statistics reporting with default settings defined |
| at build time. Unless stated otherwise, these settings are used : |
| - stats uri : /haproxy?stats |
| - stats realm : "HAProxy Statistics" |
| - stats auth : no authentication |
| - stats scope : no restriction |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # public access (limited to this backend only) |
| backend public_www |
| server srv1 192.168.0.1:80 |
| stats enable |
| stats hide-version |
| stats scope . |
| stats uri /admin?stats |
| stats realm Haproxy\ Statistics |
| stats auth admin1:AdMiN123 |
| stats auth admin2:AdMiN321 |
| |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also : "stats auth", "stats realm", "stats uri" |
| |
| |
| stats hide-version |
| Enable statistics and hide HAProxy version reporting |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| By default, the stats page reports some useful status information along with |
| the statistics. Among them is HAProxy's version. However, it is generally |
| considered dangerous to report precise version to anyone, as it can help them |
| target known weaknesses with specific attacks. The "stats hide-version" |
| statement removes the version from the statistics report. This is recommended |
| for public sites or any site with a weak login/password. |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # public access (limited to this backend only) |
| backend public_www |
| server srv1 192.168.0.1:80 |
| stats enable |
| stats hide-version |
| stats scope . |
| stats uri /admin?stats |
| stats realm Haproxy\ Statistics |
| stats auth admin1:AdMiN123 |
| stats auth admin2:AdMiN321 |
| |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| |
| |
| stats http-request { allow | deny | auth [realm <realm>] } |
| [ { if | unless } <condition> ] |
| Access control for statistics |
| |
| May be used in sections: defaults | frontend | listen | backend |
| no | no | yes | yes |
| |
| As "http-request", these set of options allow to fine control access to |
| statistics. 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. |
| |
| See also : "http-request", section 3.4 about userlists and section 7 |
| about ACL usage. |
| |
| |
| stats realm <realm> |
| Enable statistics and set authentication realm |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <realm> is the name of the HTTP Basic Authentication realm reported to |
| the browser. The browser uses it to display it in the pop-up |
| inviting the user to enter a valid username and password. |
| |
| The realm is read as a single word, so any spaces in it should be escaped |
| using a backslash ('\'). |
| |
| This statement is useful only in conjunction with "stats auth" since it is |
| only related to authentication. |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # public access (limited to this backend only) |
| backend public_www |
| server srv1 192.168.0.1:80 |
| stats enable |
| stats hide-version |
| stats scope . |
| stats uri /admin?stats |
| stats realm Haproxy\ Statistics |
| stats auth admin1:AdMiN123 |
| stats auth admin2:AdMiN321 |
| |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also : "stats auth", "stats enable", "stats uri" |
| |
| |
| stats refresh <delay> |
| Enable statistics with automatic refresh |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <delay> is the suggested refresh delay, specified in seconds, which will |
| be returned to the browser consulting the report page. While the |
| browser is free to apply any delay, it will generally respect it |
| and refresh the page this every seconds. The refresh interval may |
| be specified in any other non-default time unit, by suffixing the |
| unit after the value, as explained at the top of this document. |
| |
| This statement is useful on monitoring displays with a permanent page |
| reporting the load balancer's activity. When set, the HTML report page will |
| include a link "refresh"/"stop refresh" so that the user can select whether |
| he wants automatic refresh of the page or not. |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # public access (limited to this backend only) |
| backend public_www |
| server srv1 192.168.0.1:80 |
| stats enable |
| stats hide-version |
| stats scope . |
| stats uri /admin?stats |
| stats realm Haproxy\ Statistics |
| stats auth admin1:AdMiN123 |
| stats auth admin2:AdMiN321 |
| |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| |
| |
| stats scope { <name> | "." } |
| Enable statistics and limit access scope |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <name> is the name of a listen, frontend or backend section to be |
| reported. The special name "." (a single dot) designates the |
| section in which the statement appears. |
| |
| When this statement is specified, only the sections enumerated with this |
| statement will appear in the report. All other ones will be hidden. This |
| statement may appear as many times as needed if multiple sections need to be |
| reported. Please note that the name checking is performed as simple string |
| comparisons, and that it is never checked that a give section name really |
| exists. |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # public access (limited to this backend only) |
| backend public_www |
| server srv1 192.168.0.1:80 |
| stats enable |
| stats hide-version |
| stats scope . |
| stats uri /admin?stats |
| stats realm Haproxy\ Statistics |
| stats auth admin1:AdMiN123 |
| stats auth admin2:AdMiN321 |
| |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| |
| |
| stats show-desc [ <desc> ] |
| Enable reporting of a description on the statistics page. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| |
| <desc> is an optional description to be reported. If unspecified, the |
| description from global section is automatically used instead. |
| |
| This statement is useful for users that offer shared services to their |
| customers, where node or description should be different for each customer. |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats show-desc Master node for Europe, Asia, Africa |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also: "show-node", "stats enable", "stats uri" and "description" in |
| global section. |
| |
| |
| stats show-legends |
| Enable reporting additional informations on the statistics page : |
| - cap: capabilities (proxy) |
| - mode: one of tcp, http or health (proxy) |
| - id: SNMP ID (proxy, socket, server) |
| - IP (socket, server) |
| - cookie (backend, server) |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| See also: "stats enable", "stats uri". |
| |
| |
| stats show-node [ <name> ] |
| Enable reporting of a host name on the statistics page. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments: |
| <name> is an optional name to be reported. If unspecified, the |
| node name from global section is automatically used instead. |
| |
| This statement is useful for users that offer shared services to their |
| customers, where node or description might be different on a stats page |
| provided for each customer. |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example: |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats show-node Europe-1 |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also: "show-desc", "stats enable", "stats uri", and "node" in global |
| section. |
| |
| |
| stats uri <prefix> |
| Enable statistics and define the URI prefix to access them |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <prefix> is the prefix of any URI which will be redirected to stats. This |
| prefix may contain a question mark ('?') to indicate part of a |
| query string. |
| |
| The statistics URI is intercepted on the relayed traffic, so it appears as a |
| page within the normal application. It is strongly advised to ensure that the |
| selected URI will never appear in the application, otherwise it will never be |
| possible to reach it in the application. |
| |
| The default URI compiled in haproxy is "/haproxy?stats", but this may be |
| changed at build time, so it's better to always explicitly specify it here. |
| It is generally a good idea to include a question mark in the URI so that |
| intermediate proxies refrain from caching the results. Also, since any string |
| beginning with the prefix will be accepted as a stats request, the question |
| mark helps ensuring that no valid URI will begin with the same words. |
| |
| It is sometimes very convenient to use "/" as the URI prefix, and put that |
| statement in a "listen" instance of its own. That makes it easy to dedicate |
| an address or a port to statistics only. |
| |
| Though this statement alone is enough to enable statistics reporting, it is |
| recommended to set all other settings in order to avoid relying on default |
| unobvious parameters. |
| |
| Example : |
| # public access (limited to this backend only) |
| backend public_www |
| server srv1 192.168.0.1:80 |
| stats enable |
| stats hide-version |
| stats scope . |
| stats uri /admin?stats |
| stats realm Haproxy\ Statistics |
| stats auth admin1:AdMiN123 |
| stats auth admin2:AdMiN321 |
| |
| # internal monitoring access (unlimited) |
| backend private_monitoring |
| stats enable |
| stats uri /admin?stats |
| stats refresh 5s |
| |
| See also : "stats auth", "stats enable", "stats realm" |
| |
| |
| stick match <pattern> [table <table>] [{if | unless} <cond>] |
| Define a request pattern matching condition to stick a user to a server |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| |
| Arguments : |
| <pattern> is a pattern extraction rule as described in section 7.8. It |
| describes what elements of the incoming request or connection |
| will be analysed in the hope to find a matching entry in a |
| stickiness table. This rule is mandatory. |
| |
| <table> is an optional stickiness table name. If unspecified, the same |
| backend's table is used. A stickiness table is declared using |
| the "stick-table" statement. |
| |
| <cond> is an optional matching condition. It makes it possible to match |
| on a certain criterion only when other conditions are met (or |
| not met). For instance, it could be used to match on a source IP |
| address except when a request passes through a known proxy, in |
| which case we'd match on a header containing that IP address. |
| |
| Some protocols or applications require complex stickiness rules and cannot |
| always simply rely on cookies nor hashing. The "stick match" statement |
| describes a rule to extract the stickiness criterion from an incoming request |
| or connection. See section 7 for a complete list of possible patterns and |
| transformation rules. |
| |
| The table has to be declared using the "stick-table" statement. It must be of |
| a type compatible with the pattern. By default it is the one which is present |
| in the same backend. It is possible to share a table with other backends by |
| referencing it using the "table" keyword. If another table is referenced, |
| the server's ID inside the backends are used. By default, all server IDs |
| start at 1 in each backend, so the server ordering is enough. But in case of |
| doubt, it is highly recommended to force server IDs using their "id" setting. |
| |
| It is possible to restrict the conditions where a "stick match" statement |
| will apply, using "if" or "unless" followed by a condition. See section 7 for |
| ACL based conditions. |
| |
| There is no limit on the number of "stick match" statements. The first that |
| applies and matches will cause the request to be directed to the same server |
| as was used for the request which created the entry. That way, multiple |
| matches can be used as fallbacks. |
| |
| The stick rules are checked after the persistence cookies, so they will not |
| affect stickiness if a cookie has already been used to select a server. That |
| way, it becomes very easy to insert cookies and match on IP addresses in |
| order to maintain stickiness between HTTP and HTTPS. |
| |
| 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 : |
| # forward SMTP users to the same server they just used for POP in the |
| # last 30 minutes |
| backend pop |
| mode tcp |
| balance roundrobin |
| stick store-request src |
| stick-table type ip size 200k expire 30m |
| server s1 192.168.1.1:110 |
| server s2 192.168.1.1:110 |
| |
| backend smtp |
| mode tcp |
| balance roundrobin |
| stick match src table pop |
| server s1 192.168.1.1:25 |
| server s2 192.168.1.1:25 |
| |
| See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7 |
| about ACLs and pattern extraction. |
| |
| |
| stick on <pattern> [table <table>] [{if | unless} <condition>] |
| Define a request pattern to associate a user to a server |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| |
| Note : This form is exactly equivalent to "stick match" followed by |
| "stick store-request", all with the same arguments. Please refer |
| to both keywords for details. It is only provided as a convenience |
| for writing more maintainable configurations. |
| |
| 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. |
| |
| Examples : |
| # The following form ... |
| stick on src table pop if !localhost |
| |
| # ...is strictly equivalent to this one : |
| stick match src table pop if !localhost |
| stick store-request src table pop if !localhost |
| |
| |
| # Use cookie persistence for HTTP, and stick on source address for HTTPS as |
| # well as HTTP without cookie. Share the same table between both accesses. |
| backend http |
| mode http |
| balance roundrobin |
| stick on src table https |
| cookie SRV insert indirect nocache |
| server s1 192.168.1.1:80 cookie s1 |
| server s2 192.168.1.1:80 cookie s2 |
| |
| backend https |
| mode tcp |
| balance roundrobin |
| stick-table type ip size 200k expire 30m |
| stick on src |
| server s1 192.168.1.1:443 |
| server s2 192.168.1.1:443 |
| |
| See also : "stick match", "stick store-request", "nbproc" and "bind-process". |
| |
| |
| stick store-request <pattern> [table <table>] [{if | unless} <condition>] |
| Define a request pattern used to create an entry in a stickiness table |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| |
| Arguments : |
| <pattern> is a pattern extraction rule as described in section 7.8. It |
| describes what elements of the incoming request or connection |
| will be analysed, extracted and stored in the table once a |
| server is selected. |
| |
| <table> is an optional stickiness table name. If unspecified, the same |
| backend's table is used. A stickiness table is declared using |
| the "stick-table" statement. |
| |
| <cond> is an optional storage condition. It makes it possible to store |
| certain criteria only when some conditions are met (or not met). |
| For instance, it could be used to store the source IP address |
| except when the request passes through a known proxy, in which |
| case we'd store a converted form of a header containing that IP |
| address. |
| |
| Some protocols or applications require complex stickiness rules and cannot |
| always simply rely on cookies nor hashing. The "stick store-request" statement |
| describes a rule to decide what to extract from the request and when to do |
| it, in order to store it into a stickiness table for further requests to |
| match it using the "stick match" statement. Obviously the extracted part must |
| make sense and have a chance to be matched in a further request. Storing a |
| client's IP address for instance often makes sense. Storing an ID found in a |
| URL parameter also makes sense. Storing a source port will almost never make |
| any sense because it will be randomly matched. See section 7 for a complete |
| list of possible patterns and transformation rules. |
| |
| The table has to be declared using the "stick-table" statement. It must be of |
| a type compatible with the pattern. By default it is the one which is present |
| in the same backend. It is possible to share a table with other backends by |
| referencing it using the "table" keyword. If another table is referenced, |
| the server's ID inside the backends are used. By default, all server IDs |
| start at 1 in each backend, so the server ordering is enough. But in case of |
| doubt, it is highly recommended to force server IDs using their "id" setting. |
| |
| It is possible to restrict the conditions where a "stick store-request" |
| statement will apply, using "if" or "unless" followed by a condition. This |
| condition will be evaluated while parsing the request, so any criteria can be |
| used. See section 7 for ACL based conditions. |
| |
| There is no limit on the number of "stick store-request" statements, but |
| there is a limit of 8 simultaneous stores per request or response. This |
| makes it possible to store up to 8 criteria, all extracted from either the |
| request or the response, regardless of the number of rules. Only the 8 first |
| ones which match will be kept. Using this, it is possible to feed multiple |
| tables at once in the hope to increase the chance to recognize a user on |
| another protocol or access method. |
| |
| The "store-request" rules are evaluated once the server connection has been |
| established, so that the table will contain the real server that processed |
| the request. |
| |
| 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 : |
| # forward SMTP users to the same server they just used for POP in the |
| # last 30 minutes |
| backend pop |
| mode tcp |
| balance roundrobin |
| stick store-request src |
| stick-table type ip size 200k expire 30m |
| server s1 192.168.1.1:110 |
| server s2 192.168.1.1:110 |
| |
| backend smtp |
| mode tcp |
| balance roundrobin |
| stick match src table pop |
| server s1 192.168.1.1:25 |
| server s2 192.168.1.1:25 |
| |
| See also : "stick-table", "stick on", "nbproc", "bind-process" and section 7 |
| about ACLs and pattern extraction. |
| |
| |
| stick-table type {ip | integer | string [len <length>] | binary [len <length>]} |
| size <size> [expire <expire>] [nopurge] [peers <peersect>] |
| [store <data_type>]* |
| Configure the stickiness table for the current backend |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| Arguments : |
| ip a table declared with "type ip" will only store IPv4 addresses. |
| This form is very compact (about 50 bytes per entry) and allows |
| very fast entry lookup and stores with almost no overhead. This |
| is mainly used to store client source IP addresses. |
| |
| integer a table declared with "type integer" will store 32bit integers |
| which can represent a client identifier found in a request for |
| instance. |
| |
| string a table declared with "type string" will store substrings of up |
| to <len> characters. If the string provided by the pattern |
| extractor is larger than <len>, it will be truncated before |
| being stored. During matching, at most <len> characters will be |
| compared between the string in the table and the extracted |
| pattern. When not specified, the string is automatically limited |
| to 32 characters. |
| |
| binary a table declared with "type binary" will store binary blocks |
| of <len> bytes. If the block provided by the pattern |
| extractor is larger than <len>, it will be truncated before |
| being stored. If the block provided by the pattern extractor |
| is shorter than <len>, it will be padded by 0. When not |
| specified, the block is automatically limited to 32 bytes. |
| |
| <length> is the maximum number of characters that will be stored in a |
| "string" type table (See type "string" above). Or the number |
| of bytes of the block in "binary" type table. Be careful when |
| changing this parameter as memory usage will proportionally |
| increase. |
| |
| <size> is the maximum number of entries that can fit in the table. This |
| value directly impacts memory usage. Count approximately |
| 50 bytes per entry, plus the size of a string if any. The size |
| supports suffixes "k", "m", "g" for 2^10, 2^20 and 2^30 factors. |
| |
| [nopurge] indicates that we refuse to purge older entries when the table |
| is full. When not specified and the table is full when haproxy |
| wants to store an entry in it, it will flush a few of the oldest |
| entries in order to release some space for the new ones. This is |
| most often the desired behaviour. In some specific cases, it |
| be desirable to refuse new entries instead of purging the older |
| ones. That may be the case when the amount of data to store is |
| far above the hardware limits and we prefer not to offer access |
| to new clients than to reject the ones already connected. When |
| using this parameter, be sure to properly set the "expire" |
| parameter (see below). |
| |
| <peersect> is the name of the peers section to use for replication. Entries |
| which associate keys to server IDs are kept synchronized with |
| the remote peers declared in this section. All entries are also |
| automatically learned from the local peer (old process) during a |
| soft restart. |
| |
| NOTE : peers can't be used in multi-process mode. |
| |
| <expire> defines the maximum duration of an entry in the table since it |
| was last created, refreshed or matched. The expiration delay is |
| defined using the standard time format, similarly as the various |
| timeouts. The maximum duration is slightly above 24 days. See |
| section 2.2 for more information. If this delay is not specified, |
| the session won't automatically expire, but older entries will |
| be removed once full. Be sure not to use the "nopurge" parameter |
| if not expiration delay is specified. |
| |
| <data_type> is used to store additional information in the stick-table. This |
| may be used by ACLs in order to control various criteria related |
| to the activity of the client matching the stick-table. For each |
| item specified here, the size of each entry will be inflated so |
| that the additional data can fit. Several data types may be |
| stored with an entry. Multiple data types may be specified after |
| the "store" keyword, as a comma-separated list. Alternatively, |
| it is possible to repeat the "store" keyword followed by one or |
| several data types. Except for the "server_id" type which is |
| automatically detected and enabled, all data types must be |
| explicitly declared to be stored. If an ACL references a data |
| type which is not stored, the ACL will simply not match. Some |
| data types require an argument which must be passed just after |
| the type between parenthesis. See below for the supported data |
| types and their arguments. |
| |
| The data types that can be stored with an entry are the following : |
| - server_id : this is an integer which holds the numeric ID of the server a |
| request was assigned to. It is used by the "stick match", "stick store", |
| and "stick on" rules. It is automatically enabled when referenced. |
| |
| - gpc0 : first General Purpose Counter. It is a positive 32-bit integer |
| integer which may be used for anything. Most of the time it will be used |
| to put a special tag on some entries, for instance to note that a |
| specific behaviour was detected and must be known for future matches. |
| |
| - conn_cnt : Connection Count. It is a positive 32-bit integer which counts |
| the absolute number of connections received from clients which matched |
| this entry. It does not mean the connections were accepted, just that |
| they were received. |
| |
| - conn_cur : Current Connections. It is a positive 32-bit integer which |
| stores the concurrent connection counts for the entry. It is incremented |
| once an incoming connection matches the entry, and decremented once the |
| connection leaves. That way it is possible to know at any time the exact |
| number of concurrent connections for an entry. |
| |
| - conn_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| integer parameter <period> which indicates in milliseconds the length |
| of the period over which the average is measured. It reports the average |
| incoming connection rate over that period, in connections per period. The |
| result is an integer which can be matched using ACLs. |
| |
| - sess_cnt : Session Count. It is a positive 32-bit integer which counts |
| the absolute number of sessions received from clients which matched this |
| entry. A session is a connection that was accepted by the layer 4 rules. |
| |
| - sess_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| integer parameter <period> which indicates in milliseconds the length |
| of the period over which the average is measured. It reports the average |
| incoming session rate over that period, in sessions per period. The |
| result is an integer which can be matched using ACLs. |
| |
| - http_req_cnt : HTTP request Count. It is a positive 32-bit integer which |
| counts the absolute number of HTTP requests received from clients which |
| matched this entry. It does not matter whether they are valid requests or |
| not. Note that this is different from sessions when keep-alive is used on |
| the client side. |
| |
| - http_req_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| integer parameter <period> which indicates in milliseconds the length |
| of the period over which the average is measured. It reports the average |
| HTTP request rate over that period, in requests per period. The result is |
| an integer which can be matched using ACLs. It does not matter whether |
| they are valid requests or not. Note that this is different from sessions |
| when keep-alive is used on the client side. |
| |
| - http_err_cnt : HTTP Error Count. It is a positive 32-bit integer which |
| counts the absolute number of HTTP requests errors induced by clients |
| which matched this entry. Errors are counted on invalid and truncated |
| requests, as well as on denied or tarpitted requests, and on failed |
| authentications. If the server responds with 4xx, then the request is |
| also counted as an error since it's an error triggered by the client |
| (eg: vulnerability scan). |
| |
| - http_err_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| integer parameter <period> which indicates in milliseconds the length |
| of the period over which the average is measured. It reports the average |
| HTTP request error rate over that period, in requests per period (see |
| http_err_cnt above for what is accounted as an error). The result is an |
| integer which can be matched using ACLs. |
| |
| - bytes_in_cnt : client to server byte count. It is a positive 64-bit |
| integer which counts the cumulated amount of bytes received from clients |
| which matched this entry. Headers are included in the count. This may be |
| used to limit abuse of upload features on photo or video servers. |
| |
| - bytes_in_rate(<period>) : frequency counter (takes 12 bytes). It takes an |
| integer parameter <period> which indicates in milliseconds the length |
| of the period over which the average is measured. It reports the average |
| incoming bytes rate over that period, in bytes per period. It may be used |
| to detect users which upload too much and too fast. Warning: with large |
| uploads, it is possible that the amount of uploaded data will be counted |
| once upon termination, thus causing spikes in the average transfer speed |
| instead of having a smooth one. This may partially be smoothed with |
| "option contstats" though this is not perfect yet. Use of byte_in_cnt is |
| recommended for better fairness. |
| |
| - bytes_out_cnt : server to client byte count. It is a positive 64-bit |
| integer which counts the cumulated amount of bytes sent to clients which |
| matched this entry. Headers are included in the count. This may be used |
| to limit abuse of bots sucking the whole site. |
| |
| - bytes_out_rate(<period>) : frequency counter (takes 12 bytes). It takes |
| an integer parameter <period> which indicates in milliseconds the length |
| of the period over which the average is measured. It reports the average |
| outgoing bytes rate over that period, in bytes per period. It may be used |
| to detect users which download too much and too fast. Warning: with large |
| transfers, it is possible that the amount of transferred data will be |
| counted once upon termination, thus causing spikes in the average |
| transfer speed instead of having a smooth one. This may partially be |
| smoothed with "option contstats" though this is not perfect yet. Use of |
| byte_out_cnt is recommended for better fairness. |
| |
| There is only one stick-table per proxy. At the moment of writing this doc, |
| it does not seem useful to have multiple tables per proxy. If this happens |
| to be required, simply create a dummy backend with a stick-table in it and |
| reference it. |
| |
| It is important to understand that stickiness based on learning information |
| has some limitations, including the fact that all learned associations are |
| lost upon restart. In general it can be good as a complement but not always |
| as an exclusive stickiness. |
| |
| Last, memory requirements may be important when storing many data types. |
| Indeed, storing all indicators above at once in each entry requires 116 bytes |
| per entry, or 116 MB for a 1-million entries table. This is definitely not |
| something that can be ignored. |
| |
| Example: |
| # Keep track of counters of up to 1 million IP addresses over 5 minutes |
| # and store a general purpose counter and the average connection rate |
| # computed over a sliding window of 30 seconds. |
| stick-table type ip size 1m expire 5m store gpc0,conn_rate(30s) |
| |
| See also : "stick match", "stick on", "stick store-request", section 2.2 |
| about time format and section 7 avoud ACLs. |
| |
| |
| stick store-response <pattern> [table <table>] [{if | unless} <condition>] |
| Define a request pattern used to create an entry in a stickiness table |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| |
| Arguments : |
| <pattern> is a pattern extraction rule as described in section 7.8. It |
| describes what elements of the response or connection will |
| be analysed, extracted and stored in the table once a |
| server is selected. |
| |
| <table> is an optional stickiness table name. If unspecified, the same |
| backend's table is used. A stickiness table is declared using |
| the "stick-table" statement. |
| |
| <cond> is an optional storage condition. It makes it possible to store |
| certain criteria only when some conditions are met (or not met). |
| For instance, it could be used to store the SSL session ID only |
| when the response is a SSL server hello. |
| |
| Some protocols or applications require complex stickiness rules and cannot |
| always simply rely on cookies nor hashing. The "stick store-response" |
| statement describes a rule to decide what to extract from the response and |
| when to do it, in order to store it into a stickiness table for further |
| requests to match it using the "stick match" statement. Obviously the |
| extracted part must make sense and have a chance to be matched in a further |
| request. Storing an ID found in a header of a response makes sense. |
| See section 7 for a complete list of possible patterns and transformation |
| rules. |
| |
| The table has to be declared using the "stick-table" statement. It must be of |
| a type compatible with the pattern. By default it is the one which is present |
| in the same backend. It is possible to share a table with other backends by |
| referencing it using the "table" keyword. If another table is referenced, |
| the server's ID inside the backends are used. By default, all server IDs |
| start at 1 in each backend, so the server ordering is enough. But in case of |
| doubt, it is highly recommended to force server IDs using their "id" setting. |
| |
| It is possible to restrict the conditions where a "stick store-response" |
| statement will apply, using "if" or "unless" followed by a condition. This |
| condition will be evaluated while parsing the response, so any criteria can |
| be used. See section 7 for ACL based conditions. |
| |
| There is no limit on the number of "stick store-response" statements, but |
| there is a limit of 8 simultaneous stores per request or response. This |
| makes it possible to store up to 8 criteria, all extracted from either the |
| request or the response, regardless of the number of rules. Only the 8 first |
| ones which match will be kept. Using this, it is possible to feed multiple |
| tables at once in the hope to increase the chance to recognize a user on |
| another protocol or access method. |
| |
| The table will contain the real server that processed the request. |
| |
| Example : |
| # Learn SSL session ID from both request and response and create affinity. |
| backend https |
| mode tcp |
| balance roundrobin |
| # maximum SSL session ID length is 32 bytes. |
| stick-table type binary len 32 size 30k expire 30m |
| |
| acl clienthello req_ssl_hello_type 1 |
| acl serverhello rep_ssl_hello_type 2 |
| |
| # use tcp content accepts to detects ssl client and server hello. |
| tcp-request inspect-delay 5s |
| tcp-request content accept if clienthello |
| |
| # no timeout on response inspect delay by default. |
| tcp-response content accept if serverhello |
| |
| # SSL session ID (SSLID) may be present on a client or server hello. |
| # Its length is coded on 1 byte at offset 43 and its value starts |
| # at offset 44. |
| |
| # Match and learn on request if client hello. |
| stick on payload_lv(43,1) if clienthello |
| |
| # Learn on response if server hello. |
| stick store-response payload_lv(43,1) if serverhello |
| |
| server s1 192.168.1.1:443 |
| server s2 192.168.1.1:443 |
| |
| See also : "stick-table", "stick on", and section 7 about ACLs and pattern |
| extraction. |
| |
| |
| tcp-request connection <action> [{if | unless} <condition>] |
| Perform an action on an incoming connection depending on a layer 4 condition |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <action> defines the action to perform if the condition applies. Valid |
| actions include : "accept", "reject", "track-sc1", "track-sc2". |
| See below for more details. |
| |
| <condition> is a standard layer4-only ACL-based condition (see section 7). |
| |
| Immediately after acceptance of a new incoming connection, it is possible to |
| evaluate some conditions to decide whether this connection must be accepted |
| or dropped or have its counters tracked. Those conditions cannot make use of |
| any data contents because the connection has not been read from yet, and the |
| buffers are not yet allocated. This is used to selectively and very quickly |
| accept or drop connections from various sources with a very low overhead. If |
| some contents need to be inspected in order to take the decision, the |
| "tcp-request content" statements must be used instead. |
| |
| The "tcp-request connection" rules are evaluated in their exact declaration |
| order. If no rule matches or if there is no rule, the default action is to |
| accept the incoming connection. There is no specific limit to the number of |
| rules which may be inserted. |
| |
| Three types of actions are supported : |
| - accept : |
| accepts the connection if the condition is true (when used with "if") |
| or false (when used with "unless"). The first such rule executed ends |
| the rules evaluation. |
| |
| - reject : |
| rejects the connection if the condition is true (when used with "if") |
| or false (when used with "unless"). The first such rule executed ends |
| the rules evaluation. Rejected connections do not even become a |
| session, which is why they are accounted separately for in the stats, |
| as "denied connections". They are not considered for the session |
| rate-limit and are not logged either. The reason is that these rules |
| should only be used to filter extremely high connection rates such as |
| the ones encountered during a massive DDoS attack. Under these extreme |
| conditions, the simple action of logging each event would make the |
| system collapse and would considerably lower the filtering capacity. If |
| logging is absolutely desired, then "tcp-request content" rules should |
| be used instead. |
| |
| - { track-sc1 | track-sc2 } <key> [table <table>] : |
| enables tracking of sticky counters from current connection. These |
| rules do not stop evaluation and do not change default action. Two sets |
| of counters may be simultaneously tracked by the same connection. The |
| first "track-sc1" rule executed enables tracking of the counters of the |
| specified table as the first set. The first "track-sc2" rule executed |
| enables tracking of the counters of the specified table as the second |
| set. It is a recommended practice to use the first set of counters for |
| the per-frontend counters and the second set for the per-backend ones. |
| |
| These actions take one or two arguments : |
| <key> is mandatory, and defines the criterion the tracking key will |
| be derived from. At the moment, only "src" is supported. With |
| it, the key will be the connection's source IPv4 address. |
| |
| <table> is an optional table to be used instead of the default one, |
| which is the stick-table declared in the current proxy. All |
| the counters for the matches and updates for the key will |
| then be performed in that table until the session ends. |
| |
| Once a "track-sc*" rule is executed, the key is looked up in the table |
| and if it is not found, an entry is allocated for it. Then a pointer to |
| that entry is kept during all the session's life, and this entry's |
| counters are updated as often as possible, every time the session's |
| counters are updated, and also systematically when the session ends. |
| If the entry tracks concurrent connection counters, one connection is |
| counted for as long as the entry is tracked, and the entry will not |
| expire during that time. Tracking counters also provides a performance |
| advantage over just checking the keys, because only one table lookup is |
| performed for all ACL checks that make use of it. |
| |
| Note that the "if/unless" condition is optional. If no condition is set on |
| the action, it is simply performed unconditionally. That can be useful for |
| "track-sc*" actions as well as for changing the default action to a reject. |
| |
| Example: accept all connections from white-listed hosts, reject too fast |
| connection without counting them, and track accepted connections. |
| This results in connection rate being capped from abusive sources. |
| |
| tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst } |
| tcp-request connection reject if { src_conn_rate gt 10 } |
| tcp-request connection track-sc1 src |
| |
| Example: accept all connections from white-listed hosts, count all other |
| connections and reject too fast ones. This results in abusive ones |
| being blocked as long as they don't slow down. |
| |
| tcp-request connection accept if { src -f /etc/haproxy/whitelist.lst } |
| tcp-request connection track-sc1 src |
| tcp-request connection reject if { sc1_conn_rate gt 10 } |
| |
| See section 7 about ACL usage. |
| |
| See also : "tcp-request content", "stick-table" |
| |
| |
| tcp-request content <action> [{if | unless} <condition>] |
| Perform an action on a new session depending on a layer 4-7 condition |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <action> defines the action to perform if the condition applies. Valid |
| actions include : "accept", "reject", "track-sc1", "track-sc2". |
| See "tcp-request connection" above for their signification. |
| |
| <condition> is a standard layer 4-7 ACL-based condition (see section 7). |
| |
| A request's contents can be analysed at an early stage of request processing |
| called "TCP content inspection". During this stage, ACL-based rules are |
| evaluated every time the request contents are updated, until either an |
| "accept" or a "reject" rule matches, or the TCP request inspection delay |
| expires with no matching rule. |
| |
| The first difference between these rules and "tcp-request connection" rules |
| is that "tcp-request content" rules can make use of contents to take a |
| decision. Most often, these decisions will consider a protocol recognition or |
| validity. The second difference is that content-based rules can be used in |
| both frontends and backends. In frontends, they will be evaluated upon new |
| connections. In backends, they will be evaluated once a session is assigned |
| a backend. This means that a single frontend connection may be evaluated |
| several times by one or multiple backends when a session gets reassigned |
| (for instance after a client-side HTTP keep-alive request). |
| |
| Content-based rules are evaluated in their exact declaration order. If no |
| rule matches or if there is no rule, the default action is to accept the |
| contents. There is no specific limit to the number of rules which may be |
| inserted. |
| |
| Three types of actions are supported : |
| - accept : |
| - reject : |
| - { track-sc1 | track-sc2 } <key> [table <table>] |
| |
| They have the same meaning as their counter-parts in "tcp-request connection" |
| so please refer to that section for a complete description. |
| |
| Also, it is worth noting that if sticky counters are tracked from a rule |
| defined in a backend, this tracking will automatically end when the session |
| releases the backend. That allows per-backend counter tracking even in case |
| of HTTP keep-alive requests when the backend changes. While there is nothing |
| mandatory about it, it is recommended to use the track-sc1 pointer to track |
| per-frontend counters and track-sc2 to track per-backend counters. |
| |
| Note that the "if/unless" condition is optional. If no condition is set on |
| the action, it is simply performed unconditionally. That can be useful for |
| "track-sc*" actions as well as for changing the default action to a reject. |
| |
| It is perfectly possible to match layer 7 contents with "tcp-request content" |
| rules, but then it is important to ensure that a full request has been |
| buffered, otherwise no contents will match. In order to achieve this, the |
| best solution involves detecting the HTTP protocol during the inspection |
| period. |
| |
| Example: |
| # Accept HTTP requests containing a Host header saying "example.com" |
| # and reject everything else. |
| acl is_host_com hdr(Host) -i example.com |
| tcp-request inspect-delay 30s |
| tcp-request content accept if HTTP is_host_com |
| tcp-request content reject |
| |
| Example: |
| # reject SMTP connection if client speaks first |
| tcp-request inspect-delay 30s |
| acl content_present req_len gt 0 |
| tcp-request content reject if content_present |
| |
| # Forward HTTPS connection only if client speaks |
| tcp-request inspect-delay 30s |
| acl content_present req_len gt 0 |
| tcp-request content accept if content_present |
| tcp-request content reject |
| |
| Example: track per-frontend and per-backend counters, block abusers at the |
| frontend when the backend detects abuse. |
| |
| frontend http |
| # Use General Purpose Couter 0 in SC1 as a global abuse counter |
| # protecting all our sites |
| stick-table type ip size 1m expire 5m store gpc0 |
| tcp-request connection track-sc1 src |
| tcp-request connection reject if { sc1_get_gpc0 gt 0 } |
| ... |
| use_backend http_dynamic if { path_end .php } |
| |
| backend http_dynamic |
| # if a source makes too fast requests to this dynamic site (tracked |
| # by SC2), block it globally in the frontend. |
| stick-table type ip size 1m expire 5m store http_req_rate(10s) |
| acl click_too_fast sc2_http_req_rate gt 10 |
| acl mark_as_abuser sc1_inc_gpc0 |
| tcp-request content track-sc2 src |
| tcp-request content reject if click_too_fast mark_as_abuser |
| |
| See section 7 about ACL usage. |
| |
| See also : "tcp-request connection", "tcp-request inspect-delay" |
| |
| |
| tcp-request inspect-delay <timeout> |
| Set the maximum allowed time to wait for data during content inspection |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : |
| <timeout> is the timeout value 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. |
| |
| People using haproxy primarily as a TCP relay are often worried about the |
| risk of passing any type of protocol to a server without any analysis. In |
| order to be able to analyze the request contents, we must first withhold |
| the data then analyze them. This statement simply enables withholding of |
| data for at most the specified amount of time. |
| |
| TCP content inspection applies very early when a connection reaches a |
| frontend, then very early when the connection is forwarded to a backend. This |
| means that a connection may experience a first delay in the frontend and a |
| second delay in the backend if both have tcp-request rules. |
| |
| Note that when performing content inspection, haproxy will evaluate the whole |
| rules for every new chunk which gets in, taking into account the fact that |
| those data are partial. If no rule matches before the aforementioned delay, |
| a last check is performed upon expiration, this time considering that the |
| contents are definitive. If no delay is set, haproxy will not wait at all |
| and will immediately apply a verdict based on the available information. |
| Obviously this is unlikely to be very useful and might even be racy, so such |
| setups are not recommended. |
| |
| As soon as a rule matches, the request is released and continues as usual. If |
| the timeout is reached and no rule matches, the default policy will be to let |
| it pass through unaffected. |
| |
| For most protocols, it is enough to set it to a few seconds, as most clients |
| send the full request immediately upon connection. Add 3 or more seconds to |
| cover TCP retransmits but that's all. For some protocols, it may make sense |
| to use large values, for instance to ensure that the client never talks |
| before the server (eg: SMTP), or to wait for a client to talk before passing |
| data to the server (eg: SSL). Note that the client timeout must cover at |
| least the inspection delay, otherwise it will expire first. If the client |
| closes the connection or if the buffer is full, the delay immediately expires |
| since the contents will not be able to change anymore. |
| |
| See also : "tcp-request content accept", "tcp-request content reject", |
| "timeout client". |
| |
| |
| tcp-response content <action> [{if | unless} <condition>] |
| Perform an action on a session response depending on a layer 4-7 condition |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| Arguments : |
| <action> defines the action to perform if the condition applies. Valid |
| actions include : "accept", "reject". |
| See "tcp-request connection" above for their signification. |
| |
| <condition> is a standard layer 4-7 ACL-based condition (see section 7). |
| |
| Response contents can be analysed at an early stage of response processing |
| called "TCP content inspection". During this stage, ACL-based rules are |
| evaluated every time the response contents are updated, until either an |
| "accept" or a "reject" rule matches, or a TCP response inspection delay is |
| set and expires with no matching rule. |
| |
| Most often, these decisions will consider a protocol recognition or validity. |
| |
| Content-based rules are evaluated in their exact declaration order. If no |
| rule matches or if there is no rule, the default action is to accept the |
| contents. There is no specific limit to the number of rules which may be |
| inserted. |
| |
| Two types of actions are supported : |
| - accept : |
| accepts the response if the condition is true (when used with "if") |
| or false (when used with "unless"). The first such rule executed ends |
| the rules evaluation. |
| |
| - reject : |
| rejects the response if the condition is true (when used with "if") |
| or false (when used with "unless"). The first such rule executed ends |
| the rules evaluation. Rejected session are immediatly closed. |
| |
| Note that the "if/unless" condition is optional. If no condition is set on |
| the action, it is simply performed unconditionally. That can be useful for |
| for changing the default action to a reject. |
| |
| It is perfectly possible to match layer 7 contents with "tcp-reponse content" |
| rules, but then it is important to ensure that a full response has been |
| buffered, otherwise no contents will match. In order to achieve this, the |
| best solution involves detecting the HTTP protocol during the inspection |
| period. |
| |
| See section 7 about ACL usage. |
| |
| See also : "tcp-request content", "tcp-response inspect-delay" |
| |
| |
| tcp-response inspect-delay <timeout> |
| Set the maximum allowed time to wait for a response during content inspection |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| Arguments : |
| <timeout> is the timeout value 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. |
| |
| See also : "tcp-response content", "tcp-request inspect-delay". |
| |
| |
| timeout check <timeout> |
| Set additional check timeout, but only after a connection has been already |
| established. |
| |
| May be used in sections: defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments: |
| <timeout> is the timeout value 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 set, haproxy uses min("timeout connect", "inter") as a connect timeout |
| for check and "timeout check" as an additional read timeout. The "min" is |
| used so that people running with *very* long "timeout connect" (eg. those |
| who needed this due to the queue or tarpit) do not slow down their checks. |
| (Please also note that there is no valid reason to have such long connect |
| timeouts, because "timeout queue" and "timeout tarpit" can always be used to |
| avoid that). |
| |
| If "timeout check" is not set haproxy uses "inter" for complete check |
| timeout (connect + read) exactly like all <1.3.15 version. |
| |
| In most cases check request is much simpler and faster to handle than normal |
| requests and people may want to kick out laggy servers so this timeout should |
| be smaller than "timeout server". |
| |
| 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. |
| |
| See also: "timeout connect", "timeout queue", "timeout server", |
| "timeout tarpit". |
| |
| |
| timeout client <timeout> |
| timeout 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 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 replaces the old, deprecated "clitimeout". It is recommended |
| to use it to write new configurations. The form "timeout clitimeout" is |
| provided only by backwards compatibility but its use is strongly discouraged. |
| |
| See also : "clitimeout", "timeout server". |
| |
| |
| timeout connect <timeout> |
| timeout 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 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 both queue and tarpit timeouts to the same value |
| if these have not been specified. |
| |
| 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 replaces the old, deprecated "contimeout". It is recommended |
| to use it to write new configurations. The form "timeout contimeout" is |
| provided only by backwards compatibility but its use is strongly discouraged. |
| |
| See also: "timeout check", "timeout queue", "timeout server", "contimeout", |
| "timeout tarpit". |
| |
| |
| timeout http-keep-alive <timeout> |
| Set the maximum allowed time to wait for a new HTTP request to appear |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <timeout> is the timeout value 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. |
| |
| By default, the time to wait for a new request in case of keep-alive is set |
| by "timeout http-request". However this is not always convenient because some |
| people want very short keep-alive timeouts in order to release connections |
| faster, and others prefer to have larger ones but still have short timeouts |
| once the request has started to present itself. |
| |
| The "http-keep-alive" timeout covers these needs. It will define how long to |
| wait for a new HTTP request to start coming after a response was sent. Once |
| the first byte of request has been seen, the "http-request" timeout is used |
| to wait for the complete request to come. Note that empty lines prior to a |
| new request do not refresh the timeout and are not counted as a new request. |
| |
| There is also another difference between the two timeouts : when a connection |
| expires during timeout http-keep-alive, no error is returned, the connection |
| just closes. If the connection expires in "http-request" while waiting for a |
| connection to complete, a HTTP 408 error is returned. |
| |
| In general it is optimal to set this value to a few tens to hundreds of |
| milliseconds, to allow users to fetch all objects of a page at once but |
| without waiting for further clicks. Also, if set to a very small value (eg: |
| 1 millisecond) it will probably only accept pipelined requests but not the |
| non-pipelined ones. It may be a nice trade-off for very large sites running |
| with tens to hundreds of thousands of clients. |
| |
| If this parameter is not set, the "http-request" timeout applies, and if both |
| are not set, "timeout client" still applies at the lower level. It should be |
| set in the frontend to take effect, unless the frontend is in TCP mode, in |
| which case the HTTP backend's timeout will be used. |
| |
| See also : "timeout http-request", "timeout client". |
| |
| |
| timeout http-request <timeout> |
| Set the maximum allowed time to wait for a complete HTTP request |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <timeout> is the timeout value 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. |
| |
| In order to offer DoS protection, it may be required to lower the maximum |
| accepted time to receive a complete HTTP request without affecting the client |
| timeout. This helps protecting against established connections on which |
| nothing is sent. The client timeout cannot offer a good protection against |
| this abuse because it is an inactivity timeout, which means that if the |
| attacker sends one character every now and then, the timeout will not |
| trigger. With the HTTP request timeout, no matter what speed the client |
| types, the request will be aborted if it does not complete in time. |
| |
| Note that this timeout only applies to the header part of the request, and |
| not to any data. As soon as the empty line is received, this timeout is not |
| used anymore. It is used again on keep-alive connections to wait for a second |
| request if "timeout http-keep-alive" is not set. |
| |
| Generally it is enough to set it to a few seconds, as most clients send the |
| full request immediately upon connection. Add 3 or more seconds to cover TCP |
| retransmits but that's all. Setting it to very low values (eg: 50 ms) will |
| generally work on local networks as long as there are no packet losses. This |
| will prevent people from sending bare HTTP requests using telnet. |
| |
| If this parameter is not set, the client timeout still applies between each |
| chunk of the incoming request. It should be set in the frontend to take |
| effect, unless the frontend is in TCP mode, in which case the HTTP backend's |
| timeout will be used. |
| |
| See also : "timeout http-keep-alive", "timeout client". |
| |
| |
| timeout queue <timeout> |
| Set the maximum time to wait in the queue for a connection slot to be free |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <timeout> is the timeout value 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. |
| |
| When a server's maxconn is reached, connections are left pending in a queue |
| which may be server-specific or global to the backend. In order not to wait |
| indefinitely, a timeout is applied to requests pending in the queue. If the |
| timeout is reached, it is considered that the request will almost never be |
| served, so it is dropped and a 503 error is returned to the client. |
| |
| The "timeout queue" statement allows to fix the maximum time for a request to |
| be left pending in a queue. If unspecified, the same value as the backend's |
| connection timeout ("timeout connect") is used, for backwards compatibility |
| with older versions with no "timeout queue" parameter. |
| |
| See also : "timeout connect", "contimeout". |
| |
| |
| timeout server <timeout> |
| timeout srvtimeout <timeout> (deprecated) |
| Set the maximum inactivity time on the server side. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <timeout> is the timeout value 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 server is expected to acknowledge or |
| send data. In HTTP mode, this timeout is particularly important to consider |
| during the first phase of the server's response, when it has to send the |
| headers, as it directly represents the server's processing time for the |
| request. To find out what value to put there, it's often good to start with |
| what would be considered as unacceptable response times, then check the logs |
| to observe the response time distribution, and adjust the value accordingly. |
| |
| 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. Whatever the expected server |
| response times, it is a good practice to cover at least one or several TCP |
| packet losses by specifying timeouts that are slightly above multiples of 3 |
| seconds (eg: 4 or 5 seconds minimum). |
| |
| 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 expired sessions in |
| the system if the system's timeouts are not configured either. |
| |
| This parameter replaces the old, deprecated "srvtimeout". It is recommended |
| to use it to write new configurations. The form "timeout srvtimeout" is |
| provided only by backwards compatibility but its use is strongly discouraged. |
| |
| See also : "srvtimeout", "timeout client". |
| |
| |
| timeout tarpit <timeout> |
| Set the duration for which tarpitted connections will be maintained |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <timeout> is the tarpit duration 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. |
| |
| When a connection is tarpitted using "reqtarpit", it is maintained open with |
| no activity for a certain amount of time, then closed. "timeout tarpit" |
| defines how long it will be maintained open. |
| |
| 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. If unspecified, the same value as the backend's connection timeout |
| ("timeout connect") is used, for backwards compatibility with older versions |
| with no "timeout tarpit" parameter. |
| |
| See also : "timeout connect", "contimeout". |
| |
| |
| transparent (deprecated) |
| Enable client-side transparent proxying |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| This keyword was introduced in order to provide layer 7 persistence to layer |
| 3 load balancers. The idea is to use the OS's ability to redirect an incoming |
| connection for a remote address to a local process (here HAProxy), and let |
| this process know what address was initially requested. When this option is |
| used, sessions without cookies will be forwarded to the original destination |
| IP address of the incoming request (which should match that of another |
| equipment), while requests with cookies will still be forwarded to the |
| appropriate server. |
| |
| The "transparent" keyword is deprecated, use "option transparent" instead. |
| |
| Note that contrary to a common belief, this option does NOT make HAProxy |
| present the client's IP to the server when establishing the connection. |
| |
| See also: "option transparent" |
| |
| |
| use_backend <backend> if <condition> |
| use_backend <backend> unless <condition> |
| Switch to a specific backend if/unless an ACL-based condition is matched. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <backend> is the name of a valid backend or "listen" section. |
| |
| <condition> is a condition composed of ACLs, as described in section 7. |
| |
| When doing content-switching, connections arrive on a frontend and are then |
| dispatched to various backends depending on a number of conditions. The |
| relation between the conditions and the backends is described with the |
| "use_backend" keyword. While it is normally used with HTTP processing, it can |
| also be used in pure TCP, either without content using stateless ACLs (eg: |
| source address validation) or combined with a "tcp-request" rule to wait for |
| some payload. |
| |
| There may be as many "use_backend" rules as desired. All of these rules are |
| evaluated in their declaration order, and the first one which matches will |
| assign the backend. |
| |
| In the first form, the backend will be used if the condition is met. In the |
| second form, the backend will be used if the condition is not met. If no |
| condition is valid, the backend defined with "default_backend" will be used. |
| If no default backend is defined, either the servers in the same section are |
| used (in case of a "listen" section) or, in case of a frontend, no server is |
| used and a 503 service unavailable response is returned. |
| |
| Note that it is possible to switch from a TCP frontend to an HTTP backend. In |
| this case, either the frontend has already checked that the protocol is HTTP, |
| and backend processing will immediately follow, or the backend will wait for |
| a complete HTTP request to get in. This feature is useful when a frontend |
| must decode several protocols on a unique port, one of them being HTTP. |
| |
| See also: "default_backend", "tcp-request", and section 7 about ACLs. |
| |
| |
| 5. Server and default-server options |
| ------------------------------------ |
| |
| The "server" and "default-server" keywords support a certain number of settings |
| which are all passed as arguments on the server line. The order in which those |
| arguments appear does not count, and they are all optional. Some of those |
| settings are single words (booleans) while others expect one or several values |
| after them. In this case, the values must immediately follow the setting name. |
| Except default-server, all those settings must be specified after the server's |
| address if they are used: |
| |
| server <name> <address>[:port] [settings ...] |
| default-server [settings ...] |
| |
| The currently supported settings are the following ones. |
| |
| addr <ipv4> |
| Using the "addr" parameter, it becomes possible to use a different IP address |
| to send health-checks. On some servers, it may be desirable to dedicate an IP |
| address to specific component able to perform complex tests which are more |
| suitable to health-checks than the application. This parameter is ignored if |
| the "check" parameter is not set. See also the "port" parameter. |
| |
| Supported in default-server: No |
| |
| backup |
| When "backup" is present on a server line, the server is only used in load |
| balancing when all other non-backup servers are unavailable. Requests coming |
| with a persistence cookie referencing the server will always be served |
| though. By default, only the first operational backup server is used, unless |
| the "allbackups" option is set in the backend. See also the "allbackups" |
| option. |
| |
| Supported in default-server: No |
| |
| check |
| This option enables health checks on the server. By default, a server is |
| always considered available. If "check" is set, the server will receive |
| periodic health checks to ensure that it is really able to serve requests. |
| The default address and port to send the tests to are those of the server, |
| and the default source is the same as the one defined in the backend. It is |
| possible to change the address using the "addr" parameter, the port using the |
| "port" parameter, the source address using the "source" address, and the |
| interval and timers using the "inter", "rise" and "fall" parameters. The |
| request method is define in the backend using the "httpchk", "smtpchk", |
| "mysql-check", "pgsql-check" and "ssl-hello-chk" options. Please refer to |
| those options and parameters for more information. |
| |
| Supported in default-server: No |
| |
| cookie <value> |
| The "cookie" parameter sets the cookie value assigned to the server to |
| <value>. This value will be checked in incoming requests, and the first |
| operational server possessing the same value will be selected. In return, in |
| cookie insertion or rewrite modes, this value will be assigned to the cookie |
| sent to the client. There is nothing wrong in having several servers sharing |
| the same cookie value, and it is in fact somewhat common between normal and |
| backup servers. See also the "cookie" keyword in backend section. |
| |
| Supported in default-server: No |
| |
| disabled |
| The "disabled" keyword starts the server in the "disabled" state. That means |
| that it is marked down in maintenance mode, and no connection other than the |
| ones allowed by persist mode will reach it. It is very well suited to setup |
| new servers, because normal traffic will never reach them, while it is still |
| possible to test the service by making use of the force-persist mechanism. |
| |
| Supported in default-server: No |
| |
| error-limit <count> |
| If health observing is enabled, the "error-limit" parameter specifies the |
| number of consecutive errors that triggers event selected by the "on-error" |
| option. By default it is set to 10 consecutive errors. |
| |
| Supported in default-server: Yes |
| |
| See also the "check", "error-limit" and "on-error". |
| |
| fall <count> |
| The "fall" parameter states that a server will be considered as dead after |
| <count> consecutive unsuccessful health checks. This value defaults to 3 if |
| unspecified. See also the "check", "inter" and "rise" parameters. |
| |
| Supported in default-server: Yes |
| |
| id <value> |
| Set a persistent ID for the server. This ID must be positive and unique for |
| the proxy. An unused ID will automatically be assigned if unset. The first |
| assigned value will be 1. This ID is currently only returned in statistics. |
| |
| Supported in default-server: No |
| |
| inter <delay> |
| fastinter <delay> |
| downinter <delay> |
| The "inter" parameter sets the interval between two consecutive health checks |
| to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms. |
| It is also possible to use "fastinter" and "downinter" to optimize delays |
| between checks depending on the server state : |
| |
| Server state | Interval used |
| ---------------------------------+----------------------------------------- |
| UP 100% (non-transitional) | "inter" |
| ---------------------------------+----------------------------------------- |
| Transitionally UP (going down), | |
| Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise. |
| or yet unchecked. | |
| ---------------------------------+----------------------------------------- |
| DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise. |
| ---------------------------------+----------------------------------------- |
| |
| Just as with every other time-based parameter, they can be entered in any |
| other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also |
| serves as a timeout for health checks sent to servers if "timeout check" is |
| not set. In order to reduce "resonance" effects when multiple servers are |
| hosted on the same hardware, the health-checks of all servers are started |
| with a small time offset between them. It is also possible to add some random |
| noise in the health checks interval using the global "spread-checks" |
| keyword. This makes sense for instance when a lot of backends use the same |
| servers. |
| |
| Supported in default-server: Yes |
| |
| maxconn <maxconn> |
| The "maxconn" parameter specifies the maximal number of concurrent |
| connections that will be sent to this server. If the number of incoming |
| concurrent requests goes higher than this value, they will be queued, waiting |
| for a connection to be released. This parameter is very important as it can |
| save fragile servers from going down under extreme loads. If a "minconn" |
| parameter is specified, the limit becomes dynamic. The default value is "0" |
| which means unlimited. See also the "minconn" and "maxqueue" parameters, and |
| the backend's "fullconn" keyword. |
| |
| Supported in default-server: Yes |
| |
| maxqueue <maxqueue> |
| The "maxqueue" parameter specifies the maximal number of connections which |
| will wait in the queue for this server. If this limit is reached, next |
| requests will be redispatched to other servers instead of indefinitely |
| waiting to be served. This will break persistence but may allow people to |
| quickly re-log in when the server they try to connect to is dying. The |
| default value is "0" which means the queue is unlimited. See also the |
| "maxconn" and "minconn" parameters. |
| |
| Supported in default-server: Yes |
| |
| minconn <minconn> |
| When the "minconn" parameter is set, the maxconn limit becomes a dynamic |
| limit following the backend's load. The server will 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 <fullconn> |
| concurrent connections. This makes it possible to limit the load on the |
| server during normal loads, but push it further for important loads without |
| overloading the server during exceptional loads. See also the "maxconn" |
| and "maxqueue" parameters, as well as the "fullconn" backend keyword. |
| |
| Supported in default-server: Yes |
| |
| observe <mode> |
| This option enables health adjusting based on observing communication with |
| the server. By default this functionality is disabled and enabling it also |
| requires to enable health checks. There are two supported modes: "layer4" and |
| "layer7". In layer4 mode, only successful/unsuccessful tcp connections are |
| significant. In layer7, which is only allowed for http proxies, responses |
| received from server are verified, like valid/wrong http code, unparsable |
| headers, a timeout, etc. |
| |
| Supported in default-server: No |
| |
| See also the "check", "on-error" and "error-limit". |
| |
| on-error <mode> |
| Select what should happen when enough consecutive errors are detected. |
| Currently, four modes are available: |
| - fastinter: force fastinter |
| - fail-check: simulate a failed check, also forces fastinter (default) |
| - sudden-death: simulate a pre-fatal failed health check, one more failed |
| check will mark a server down, forces fastinter |
| - mark-down: mark the server immediately down and force fastinter |
| |
| Supported in default-server: Yes |
| |
| See also the "check", "observe" and "error-limit". |
| |
| port <port> |
| Using the "port" parameter, it becomes possible to use a different port to |
| send health-checks. On some servers, it may be desirable to dedicate a port |
| to a specific component able to perform complex tests which are more suitable |
| to health-checks than the application. It is common to run a simple script in |
| inetd for instance. This parameter is ignored if the "check" parameter is not |
| set. See also the "addr" parameter. |
| |
| Supported in default-server: Yes |
| |
| redir <prefix> |
| The "redir" parameter enables the redirection mode for all GET and HEAD |
| requests addressing this server. This means that instead of having HAProxy |
| forward the request to the server, it will send an "HTTP 302" response with |
| the "Location" header composed of this prefix immediately followed by the |
| requested URI beginning at the leading '/' of the path component. That means |
| that no trailing slash should be used after <prefix>. All invalid requests |
| will be rejected, and all non-GET or HEAD requests will be normally served by |
| the server. Note that since the response is completely forged, no header |
| mangling nor cookie insertion is possible in the response. However, cookies in |
| requests are still analysed, making this solution completely usable to direct |
| users to a remote location in case of local disaster. Main use consists in |
| increasing bandwidth for static servers by having the clients directly |
| connect to them. Note: never use a relative location here, it would cause a |
| loop between the client and HAProxy! |
| |
| Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check |
| |
| Supported in default-server: No |
| |
| rise <count> |
| The "rise" parameter states that a server will be considered as operational |
| after <count> consecutive successful health checks. This value defaults to 2 |
| if unspecified. See also the "check", "inter" and "fall" parameters. |
| |
| Supported in default-server: Yes |
| |
| slowstart <start_time_in_ms> |
| The "slowstart" parameter for a server accepts a value in milliseconds which |
| indicates after how long a server which has just come back up will run at |
| full speed. Just as with every other time-based parameter, it can be entered |
| in any other explicit unit among { us, ms, s, m, h, d }. The speed grows |
| linearly from 0 to 100% during this time. The limitation applies to two |
| parameters : |
| |
| - maxconn: the number of connections accepted by the server will grow from 1 |
| to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn). |
| |
| - weight: when the backend uses a dynamic weighted algorithm, the weight |
| grows linearly from 1 to 100%. In this case, the weight is updated at every |
| health-check. For this reason, it is important that the "inter" parameter |
| is smaller than the "slowstart", in order to maximize the number of steps. |
| |
| The slowstart never applies when haproxy starts, otherwise it would cause |
| trouble to running servers. It only applies when a server has been previously |
| seen as failed. |
| |
| Supported in default-server: Yes |
| |
| source <addr>[:<pl>[-<ph>]] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
| source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | hdr_ip(<hdr>[,<occ>]) } ] |
| source <addr>[:<pl>[-<ph>]] [interface <name>] ... |
| The "source" parameter sets the source address which will be used when |
| connecting to the server. It follows the exact same parameters and principle |
| as the backend "source" keyword, except that it only applies to the server |
| referencing it. Please consult the "source" keyword for details. |
| |
| Additionally, the "source" statement on a server line allows one to specify a |
| source port range by indicating the lower and higher bounds delimited by a |
| dash ('-'). Some operating systems might require a valid IP address when a |
| source port range is specified. It is permitted to have the same IP/range for |
| several servers. Doing so makes it possible to bypass the maximum of 64k |
| total concurrent connections. The limit will then reach 64k connections per |
| server. |
| |
| Supported in default-server: No |
| |
| track [<proxy>/]<server> |
| This option enables ability to set the current state of the server by |
| tracking another one. Only a server with checks enabled can be tracked |
| so it is not possible for example to track a server that tracks another |
| one. If <proxy> is omitted the current one is used. If disable-on-404 is |
| used, it has to be enabled on both proxies. |
| |
| Supported in default-server: No |
| |
| weight <weight> |
| The "weight" parameter is used to adjust the server's weight relative to |
| other servers. All servers will receive a load proportional to their weight |
| relative to the sum of all weights, so the higher the weight, the higher the |
| load. The default weight is 1, and the maximal value is 256. A value of 0 |
| means the server will not participate in load-balancing but will still accept |
| persistent connections. If this parameter is used to distribute the load |
| according to server's capacity, it is recommended to start with values which |
| can both grow and shrink, for instance between 10 and 100 to leave enough |
| room above and below for later adjustments. |
| |
| Supported in default-server: Yes |
| |
| |
| 6. HTTP header manipulation |
| --------------------------- |
| |
| In HTTP mode, it is possible to rewrite, add or delete some of the request and |
| response headers based on regular expressions. It is also possible to block a |
| request or a response if a particular header matches a regular expression, |
| which is enough to stop most elementary protocol attacks, and to protect |
| against information leak from the internal network. But there is a limitation |
| to this : since HAProxy's HTTP engine does not support keep-alive, only headers |
| passed during the first request of a TCP session will be seen. All subsequent |
| headers will be considered data only and not analyzed. Furthermore, HAProxy |
| never touches data contents, it stops analysis at the end of headers. |
| |
| There is an exception though. If HAProxy encounters an "Informational Response" |
| (status code 1xx), it is able to process all rsp* rules which can allow, deny, |
| rewrite or delete a header, but it will refuse to add a header to any such |
| messages as this is not HTTP-compliant. The reason for still processing headers |
| in such responses is to stop and/or fix any possible information leak which may |
| happen, for instance because another downstream equipment would unconditionally |
| add a header, or if a server name appears there. When such messages are seen, |
| normal processing still occurs on the next non-informational messages. |
| |
| This section covers common usage of the following keywords, described in detail |
| in section 4.2 : |
| |
| - reqadd <string> |
| - reqallow <search> |
| - reqiallow <search> |
| - reqdel <search> |
| - reqidel <search> |
| - reqdeny <search> |
| - reqideny <search> |
| - reqpass <search> |
| - reqipass <search> |
| - reqrep <search> <replace> |
| - reqirep <search> <replace> |
| - reqtarpit <search> |
| - reqitarpit <search> |
| - rspadd <string> |
| - rspdel <search> |
| - rspidel <search> |
| - rspdeny <search> |
| - rspideny <search> |
| - rsprep <search> <replace> |
| - rspirep <search> <replace> |
| |
| With all these keywords, the same conventions are used. The <search> parameter |
| is a POSIX extended regular expression (regex) which supports grouping through |
| parenthesis (without the backslash). Spaces and other delimiters must be |
| prefixed with a backslash ('\') to avoid confusion with a field delimiter. |
| Other characters may be prefixed with a backslash to change their meaning : |
| |
| \t for a tab |
| \r for a carriage return (CR) |
| \n for a new line (LF) |
| \ to mark a space and differentiate it from a delimiter |
| \# to mark a sharp and differentiate it from a comment |
| \\ to use a backslash in a regex |
| \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy) |
| \xXX to write the ASCII hex code XX as in the C language |
| |
| The <replace> parameter contains the string to be used to replace the largest |
| portion of text matching the regex. It can make use of the special characters |
| above, and can reference a substring which is delimited by parenthesis in the |
| regex, by writing a backslash ('\') immediately followed by one digit from 0 to |
| 9 indicating the group position (0 designating the entire line). This practice |
| is very common to users of the "sed" program. |
| |
| The <string> parameter represents the string which will systematically be added |
| after the last header line. It can also use special character sequences above. |
| |
| Notes related to these keywords : |
| --------------------------------- |
| - these keywords are not always convenient to allow/deny based on header |
| contents. It is strongly recommended to use ACLs with the "block" keyword |
| instead, resulting in far more flexible and manageable rules. |
| |
| - lines are always considered as a whole. It is not possible to reference |
| a header name only or a value only. This is important because of the way |
| headers are written (notably the number of spaces after the colon). |
| |
| - the first line is always considered as a header, which makes it possible to |
| rewrite or filter HTTP requests URIs or response codes, but in turn makes |
| it harder to distinguish between headers and request line. The regex prefix |
| ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix |
| ^[^ \t:]*: matches any header name followed by a colon. |
| |
| - for performances reasons, the number of characters added to a request or to |
| a response is limited at build time to values between 1 and 4 kB. This |
| should normally be far more than enough for most usages. If it is too short |
| on occasional usages, it is possible to gain some space by removing some |
| useless headers before adding new ones. |
| |
| - keywords beginning with "reqi" and "rspi" are the same as their counterpart |
| without the 'i' letter except that they ignore case when matching patterns. |
| |
| - when a request passes through a frontend then a backend, all req* rules |
| from the frontend will be evaluated, then all req* rules from the backend |
| will be evaluated. The reverse path is applied to responses. |
| |
| - req* statements are applied after "block" statements, so that "block" is |
| always the first one, but before "use_backend" in order to permit rewriting |
| before switching. |
| |
| |
| 7. Using ACLs and pattern extraction |
| ------------------------------------ |
| |
| The use of Access Control Lists (ACL) provides a flexible solution to perform |
| content switching and generally to take decisions based on content extracted |
| from the request, the response or any environmental status. The principle is |
| simple : |
| |
| - define test criteria with sets of values |
| - perform actions only if a set of tests is valid |
| |
| The actions generally consist in blocking the request, or selecting a backend. |
| |
| In order to define a test, the "acl" keyword is used. The syntax is : |
| |
| acl <aclname> <criterion> [flags] [operator] <value> ... |
| |
| This creates a new ACL <aclname> or completes an existing one with new tests. |
| Those tests apply to the portion of request/response specified in <criterion> |
| and may be adjusted with optional flags [flags]. Some criteria also support |
| an operator which may be specified before the set of values. The values are |
| of the type supported by the criterion, and are separated by spaces. |
| |
| ACL names must be formed from upper and lower case letters, digits, '-' (dash), |
| '_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive, |
| which means that "my_acl" and "My_Acl" are two different ACLs. |
| |
| There is no enforced limit to the number of ACLs. The unused ones do not affect |
| performance, they just consume a small amount of memory. |
| |
| The following ACL flags are currently supported : |
| |
| -i : ignore case during matching of all subsequent patterns. |
| -f : load patterns from a file. |
| -- : force end of flags. Useful when a string looks like one of the flags. |
| |
| The "-f" flag is special as it loads all of the lines it finds in the file |
| specified in argument and loads all of them before continuing. It is even |
| possible to pass multiple "-f" arguments if the patterns are to be loaded from |
| multiple files. Empty lines as well as lines beginning with a sharp ('#') will |
| be ignored. All leading spaces and tabs will be stripped. If it is absolutely |
| needed to insert a valid pattern beginning with a sharp, just prefix it with a |
| space so that it is not taken for a comment. Depending on the data type and |
| match method, haproxy may load the lines into a binary tree, allowing very fast |
| lookups. This is true for IPv4 and exact string matching. In this case, |
| duplicates will automatically be removed. Also, note that the "-i" flag applies |
| to subsequent entries and not to entries loaded from files preceeding it. For |
| instance : |
| |
| acl valid-ua hdr(user-agent) -f exact-ua.lst -i -f generic-ua.lst test |
| |
| In this example, each line of "exact-ua.lst" will be exactly matched against |
| the "user-agent" header of the request. Then each line of "generic-ua" will be |
| case-insensitively matched. Then the word "test" will be insensitively matched |
| too. |
| |
| Note that right now it is difficult for the ACL parsers to report errors, so if |
| a file is unreadable or unparsable, the most you'll get is a parse error in the |
| ACL. Thus, file-based ACLs should only be produced by reliable processes. |
| |
| Supported types of values are : |
| |
| - integers or integer ranges |
| - strings |
| - regular expressions |
| - IP addresses and networks |
| |
| |
| 7.1. Matching integers |
| ---------------------- |
| |
| Matching integers is special in that ranges and operators are permitted. Note |
| that integer matching only applies to positive values. A range is a value |
| expressed with a lower and an upper bound separated with a colon, both of which |
| may be omitted. |
| |
| For instance, "1024:65535" is a valid range to represent a range of |
| unprivileged ports, and "1024:" would also work. "0:1023" is a valid |
| representation of privileged ports, and ":1023" would also work. |
| |
| As a special case, some ACL functions support decimal numbers which are in fact |
| two integers separated by a dot. This is used with some version checks for |
| instance. All integer properties apply to those decimal numbers, including |
| ranges and operators. |
| |
| For an easier usage, comparison operators are also supported. Note that using |
| operators with ranges does not make much sense and is strongly discouraged. |
| Similarly, it does not make much sense to perform order comparisons with a set |
| of values. |
| |
| Available operators for integer matching are : |
| |
| eq : true if the tested value equals at least one value |
| ge : true if the tested value is greater than or equal to at least one value |
| gt : true if the tested value is greater than at least one value |
| le : true if the tested value is less than or equal to at least one value |
| lt : true if the tested value is less than at least one value |
| |
| For instance, the following ACL matches any negative Content-Length header : |
| |
| acl negative-length hdr_val(content-length) lt 0 |
| |
| This one matches SSL versions between 3.0 and 3.1 (inclusive) : |
| |
| acl sslv3 req_ssl_ver 3:3.1 |
| |
| |
| 7.2. Matching strings |
| --------------------- |
| |
| String matching applies to verbatim strings as they are passed, with the |
| exception of the backslash ("\") which makes it possible to escape some |
| characters such as the space. If the "-i" flag is passed before the first |
| string, then the matching will be performed ignoring the case. In order |
| to match the string "-i", either set it second, or pass the "--" flag |
| before the first string. Same applies of course to match the string "--". |
| |
| |
| 7.3. Matching regular expressions (regexes) |
| ------------------------------------------- |
| |
| Just like with string matching, regex matching applies to verbatim strings as |
| they are passed, with the exception of the backslash ("\") which makes it |
| possible to escape some characters such as the space. If the "-i" flag is |
| passed before the first regex, then the matching will be performed ignoring |
| the case. In order to match the string "-i", either set it second, or pass |
| the "--" flag before the first string. Same principle applies of course to |
| match the string "--". |
| |
| |
| 7.4. Matching IPv4 addresses |
| ---------------------------- |
| |
| IPv4 addresses values can be specified either as plain addresses or with a |
| netmask appended, in which case the IPv4 address matches whenever it is |
| within the network. Plain addresses may also be replaced with a resolvable |
| host name, but this practice is generally discouraged as it makes it more |
| difficult to read and debug configurations. If hostnames are used, you should |
| at least ensure that they are present in /etc/hosts so that the configuration |
| does not depend on any random DNS match at the moment the configuration is |
| parsed. |
| |
| |
| 7.5. Available matching criteria |
| -------------------------------- |
| |
| 7.5.1. Matching at Layer 4 and below |
| ------------------------------------ |
| |
| A first set of criteria applies to information which does not require any |
| analysis of the request or response contents. Those generally include TCP/IP |
| addresses and ports, as well as internal values independant on the stream. |
| |
| always_false |
| This one never matches. All values and flags are ignored. It may be used as |
| a temporary replacement for another one when adjusting configurations. |
| |
| always_true |
| This one always matches. All values and flags are ignored. It may be used as |
| a temporary replacement for another one when adjusting configurations. |
| |
| avg_queue <integer> |
| avg_queue(backend) <integer> |
| Returns the total number of queued connections of the designated backend |
| divided by the number of active servers. This is very similar to "queue" |
| except that the size of the farm is considered, in order to give a more |
| accurate measurement of the time it may take for a new connection to be |
| processed. The main usage is to return a sorry page to new users when it |
| becomes certain they will get a degraded service. Note that in the event |
| there would not be any active server anymore, we would consider twice the |
| number of queued connections as the measured value. This is a fair estimate, |
| as we expect one server to get back soon anyway, but we still prefer to send |
| new traffic to another backend if in better shape. See also the "queue", |
| "be_conn", and "be_sess_rate" criteria. |
| |
| be_conn <integer> |
| be_conn(backend) <integer> |
| Applies to the number of currently established connections on the backend, |
| possibly including the connection being evaluated. If no backend name is |
| specified, the current one is used. But it is also possible to check another |
| backend. It can be used to use a specific farm when the nominal one is full. |
| See also the "fe_conn", "queue" and "be_sess_rate" criteria. |
| |
| be_id <integer> |
| Applies to the backend's id. Can be used in frontends to check from which |
| backend it was called. |
| |
| be_sess_rate <integer> |
| be_sess_rate(backend) <integer> |
| Returns true when the sessions creation rate on the backend matches the |
| specified values or ranges, in number of new sessions per second. This is |
| used to switch to an alternate backend when an expensive or fragile one |
| reaches too high a session rate, or to limit abuse of service (eg. prevent |
| sucking of an online dictionary). |
| |
| Example : |
| # Redirect to an error page if the dictionary is requested too often |
| backend dynamic |
| mode http |
| acl being_scanned be_sess_rate gt 100 |
| redirect location /denied.html if being_scanned |
| |
| connslots <integer> |
| connslots(backend) <integer> |
| The basic idea here is to be able to measure the number of connection "slots" |
| still available (connection + queue), so that anything beyond that (intended |
| usage; see "use_backend" keyword) can be redirected to a different backend. |
| |
| 'connslots' = number of available server connection slots, + number of |
| available server queue slots. |
| |
| Note that while "fe_conn" may be used, "connslots" comes in especially |
| useful when you have a case of traffic going to one single ip, splitting into |
| multiple backends (perhaps using acls to do name-based load balancing) and |
| you want to be able to differentiate between different backends, and their |
| available "connslots". Also, whereas "nbsrv" only measures servers that are |
| actually *down*, this acl is more fine-grained and looks into the number of |
| available connection slots as well. See also "queue" and "avg_queue". |
| |
| OTHER CAVEATS AND NOTES: at this point in time, the code does not take care |
| of dynamic connections. Also, if any of the server maxconn, or maxqueue is 0, |
| then this acl clearly does not make sense, in which case the value returned |
| will be -1. |
| |
| dst <ip_address> |
| Applies to the local IPv4 address the client connected to. It can be used to |
| switch to a different backend for some alternative addresses. |
| |
| dst_conn <integer> |
| Applies to the number of currently established connections on the same socket |
| including the one being evaluated. It can be used to either return a sorry |
| page before hard-blocking, or to use a specific backend to drain new requests |
| when the socket is considered saturated. This offers the ability to assign |
| different limits to different listening ports or addresses. See also the |
| "fe_conn" and "be_conn" criteria. |
| |
| dst_port <integer> |
| Applies to the local port the client connected to. It can be used to switch |
| to a different backend for some alternative ports. |
| |
| fe_conn <integer> |
| fe_conn(frontend) <integer> |
| Applies to the number of currently established connections on the frontend, |
| possibly including the connection being evaluated. If no frontend name is |
| specified, the current one is used. But it is also possible to check another |
| frontend. It can be used to either return a sorry page before hard-blocking, |
| or to use a specific backend to drain new requests when the farm is |
| considered saturated. See also the "dst_conn", "be_conn" and "fe_sess_rate" |
| criteria. |
| |
| fe_id <integer> |
| Applies to the frontend's id. Can be used in backends to check from which |
| frontend it was called. |
| |
| fe_sess_rate <integer> |
| fe_sess_rate(frontend) <integer> |
| Returns true when the session creation rate on the current or the named |
| frontend matches the specified values or ranges, expressed in new sessions |
| per second. This is used to limit the connection rate to acceptable ranges in |
| order to prevent abuse of service at the earliest moment. This can be |
| combined with layer 4 ACLs in order to force the clients to wait a bit for |
| the rate to go down below the limit. |
| |
| Example : |
| # This frontend limits incoming mails to 10/s with a max of 100 |
| # concurrent connections. We accept any connection below 10/s, and |
| # force excess clients to wait for 100 ms. Since clients are limited to |
| # 100 max, there cannot be more than 10 incoming mails per second. |
| frontend mail |
| bind :25 |
| mode tcp |
| maxconn 100 |
| acl too_fast fe_sess_rate ge 10 |
| tcp-request inspect-delay 100ms |
| tcp-request content accept if ! too_fast |
| tcp-request content accept if WAIT_END |
| |
| nbsrv <integer> |
| nbsrv(backend) <integer> |
| Returns true when the number of usable servers of either the current backend |
| or the named backend matches the values or ranges specified. This is used to |
| switch to an alternate backend when the number of servers is too low to |
| to handle some load. It is useful to report a failure when combined with |
| "monitor fail". |
| |
| queue <integer> |
| queue(backend) <integer> |
| Returns the total number of queued connections of the designated backend, |
| including all the connections in server queues. If no backend name is |
| specified, the current one is used, but it is also possible to check another |
| one. This can be used to take actions when queuing goes above a known level, |
| generally indicating a surge of traffic or a massive slowdown on the servers. |
| One possible action could be to reject new users but still accept old ones. |
| See also the "avg_queue", "be_conn", and "be_sess_rate" criteria. |
| |
| sc1_bytes_in_rate |
| sc2_bytes_in_rate |
| Returns the average client-to-server bytes rate from the currently tracked |
| counters, measured in amount of bytes over the period configured in the |
| table. See also src_bytes_in_rate. |
| |
| sc1_bytes_out_rate |
| sc2_bytes_out_rate |
| Returns the average server-to-client bytes rate from the currently tracked |
| counters, measured in amount of bytes over the period configured in the |
| table. See also src_bytes_out_rate. |
| |
| sc1_conn_cnt |
| sc2_conn_cnt |
| Returns the cumulated number of incoming connections from currently tracked |
| counters. See also src_conn_cnt. |
| |
| sc1_conn_cur |
| sc2_conn_cur |
| Returns the current amount of concurrent connections tracking the same |
| tracked counters. This number is automatically incremented when tracking |
| begins and decremented when tracking stops. See also src_conn_cur. |
| |
| sc1_conn_rate |
| sc2_conn_rate |
| Returns the average connection rate from the currently tracked counters, |
| measured in amount of connections over the period configured in the table. |
| See also src_conn_rate. |
| |
| sc1_get_gpc0 |
| sc2_get_gpc0 |
| Returns the value of the first General Purpose Counter associated to the |
| currently tracked counters. See also src_get_gpc0 and sc1/sc2_inc_gpc0. |
| |
| sc1_http_err_cnt |
| sc2_http_err_cnt |
| Returns the cumulated number of HTTP errors from the currently tracked |
| counters. This includes the both request errors and 4xx error responses. |
| See also src_http_err_cnt. |
| |
| sc1_http_err_rate |
| sc2_http_err_rate |
| Returns the average rate of HTTP errors from the currently tracked counters, |
| measured in amount of errors over the period configured in the table. This |
| includes the both request errors and 4xx error responses. See also |
| src_http_err_rate. |
| |
| sc1_http_req_cnt |
| sc2_http_req_cnt |
| Returns the cumulated number of HTTP requests from the currently tracked |
| counters. This includes every started request, valid or not. See also |
| src_http_req_cnt. |
| |
| sc1_http_req_rate |
| sc2_http_req_rate |
| Returns the average rate of HTTP requests from the currently tracked |
| counters, measured in amount of requests over the period configured in |
| the table. This includes every started request, valid or not. See also |
| src_http_req_rate. |
| |
| sc1_inc_gpc0 |
| sc2_inc_gpc0 |
| Increments the first General Purpose Counter associated to the currently |
| tracked counters, and returns its value. Before the first invocation, the |
| stored value is zero, so first invocation will increase it to 1 and will |
| return 1. The test can also be used alone and always returns true. This is |
| typically used as a second ACL in an expression in order to mark a connection |
| when a first ACL was verified : |
| |
| acl abuse sc1_http_req_rate gt 10 |
| acl kill sc1_inc_gpc0 |
| tcp-request connection reject if abuse kill |
| |
| sc1_kbytes_in |
| sc2_kbytes_in |
| Returns the amount of client-to-server data from the currently tracked |
| counters, measured in kilobytes over the period configured in the table. The |
| test is currently performed on 32-bit integers, which limits values to 4 |
| terabytes. See also src_kbytes_in. |
| |
| sc1_kbytes_out |
| sc2_kbytes_out |
| Returns the amount of server-to-client data from the currently tracked |
| counters, measured in kilobytes over the period configured in the table. The |
| test is currently performed on 32-bit integers, which limits values to 4 |
| terabytes. See also src_kbytes_out. |
| |
| sc1_sess_cnt |
| sc2_sess_cnt |
| Returns the cumulated number of incoming connections that were transformed |
| into sessions, which means that they were accepted by a "tcp-request |
| connection" rule, from the currently tracked counters. A backend may count |
| more sessions than connections because each connection could result in many |
| backend sessions if some HTTP keep-alive is performend over the connection |
| with the client. See also src_sess_cnt. |
| |
| sc1_sess_rate |
| sc2_sess_rate |
| Returns the average session rate from the currently tracked counters, |
| measured in amount of sessions over the period configured in the table. A |
| session is a connection that got past the early "tcp-request connection" |
| rules. A backend may count more sessions than connections because each |
| connection could result in many backend sessions if some HTTP keep-alive is |
| performend over the connection with the client. See also src_sess_rate. |
| |
| so_id <integer> |
| Applies to the socket's id. Useful in frontends with many bind keywords. |
| |
| src <ip_address> |
| Applies to the client's IPv4 address. It is usually used to limit access to |
| certain resources such as statistics. Note that it is the TCP-level source |
| address which is used, and not the address of a client behind a proxy. |
| |
| src_bytes_in_rate <integer> |
| src_bytes_in_rate(table) <integer> |
| Returns the average bytes rate from the connection's source IPv4 address in |
| the current proxy's stick-table or in the designated stick-table, measured in |
| amount of bytes over the period configured in the table. If the address is |
| not found, zero is returned. See also sc1/sc2_bytes_in_rate. |
| |
| src_bytes_out_rate <integer> |
| src_bytes_out_rate(table) <integer> |
| Returns the average bytes rate to the connection's source IPv4 address in the |
| current proxy's stick-table or in the designated stick-table, measured in |
| amount of bytes over the period configured in the table. If the address is |
| not found, zero is returned. See also sc1/sc2_bytes_out_rate. |
| |
| src_conn_cnt <integer> |
| src_conn_cnt(table) <integer> |
| Returns the cumulated number of connections initiated from the current |
| connection's source IPv4 address in the current proxy's stick-table or in |
| the designated stick-table. If the address is not found, zero is returned. |
| See also sc1/sc2_conn_cnt. |
| |
| src_conn_cur <integer> |
| src_conn_cur(table) <integer> |
| Returns the current amount of concurrent connections initiated from the |
| current connection's source IPv4 address in the current proxy's stick-table |
| or in the designated stick-table. If the address is not found, zero is |
| returned. See also sc1/sc2_conn_cur. |
| |
| src_conn_rate <integer> |
| src_conn_rate(table) <integer> |
| Returns the average connection rate from the connection's source IPv4 address |
| in the current proxy's stick-table or in the designated stick-table, measured |
| in amount of connections over the period configured in the table. If the |
| address is not found, zero is returned. See also sc1/sc2_conn_rate. |
| |
| src_get_gpc0 <integer> |
| src_get_gpc0(table) <integer> |
| Returns the value of the first General Purpose Counter associated to the |
| connection's source IPv4 address in the current proxy's stick-table or in |
| the designated stick-table. If the address is not found, zero is returned. |
| See also sc1/sc2_get_gpc0 and src_inc_gpc0. |
| |
| src_http_err_cnt <integer> |
| src_http_err_cnt(table) <integer> |
| Returns the cumulated number of HTTP errors from the current connection's |
| source IPv4 address in the current proxy's stick-table or in the designated |
| stick-table. This includes the both request errors and 4xx error responses. |
| If the address is not found, zero is returned. See also sc1/sc2_http_err_cnt. |
| |
| src_http_err_rate <integer> |
| src_http_err_rate(table) <integer> |
| Returns the average rate of HTTP errors from the current connection's source |
| IPv4 address in the current proxy's stick-table or in the designated stick- |
| table, measured in amount of errors over the period configured in the table. |
| This includes the both request errors and 4xx error responses. If the address |
| is not found, zero is returned. See also sc1/sc2_http_err_rate. |
| |
| src_http_req_cnt <integer> |
| src_http_req_cnt(table) <integer> |
| Returns the cumulated number of HTTP requests from the current connection's |
| source IPv4 address in the current proxy's stick-table or in the designated |
| stick-table. This includes every started request, valid or not. If the |
| address is not found, zero is returned. See also sc1/sc2_http_req_cnt. |
| |
| src_http_req_rate <integer> |
| src_http_req_rate(table) <integer> |
| Returns the average rate of HTTP requests from the current connection's |
| source IPv4 address in the current proxy's stick-table or in the designated |
| stick-table, measured in amount of requests over the period configured in the |
| table. This includes every started request, valid or not. If the address is |
| not found, zero is returned. See also sc1/sc2_http_req_rate. |
| |
| src_inc_gpc0 <integer> |
| src_inc_gpc0(table) <integer> |
| Increments the first General Purpose Counter associated to the connection's |
| source IPv4 address in the current proxy's stick-table or in the designated |
| stick-table, and returns its value. If the address is not found, an entry is |
| created and 1 is returned. The test can also be used alone and always returns |
| true. This is typically used as a second ACL in an expression in order to |
| mark a connection when a first ACL was verified : |
| |
| acl abuse src_http_req_rate gt 10 |
| acl kill src_inc_gpc0 |
| tcp-request connection reject if abuse kill |
| |
| src_kbytes_in <integer> |
| src_kbytes_in(table) <integer> |
| Returns the amount of data received from the connection's source IPv4 address |
| in the current proxy's stick-table or in the designated stick-table, measured |
| in kilobytes over the period configured in the table. If the address is not |
| found, zero is returned. The test is currently performed on 32-bit integers, |
| which limits values to 4 terabytes. See also sc1/sc2_kbytes_in. |
| |
| src_kbytes_out <integer> |
| src_kbytes_out(table) <integer> |
| Returns the amount of data sent to the connection's source IPv4 address in |
| the current proxy's stick-table or in the designated stick-table, measured |
| in kilobytes over the period configured in the table. If the address is not |
| found, zero is returned. The test is currently performed on 32-bit integers, |
| which limits values to 4 terabytes. See also sc1/sc2_kbytes_out. |
| |
| src_port <integer> |
| Applies to the client's TCP source port. This has a very limited usage. |
| |
| src_sess_cnt <integer> |
| src_sess_cnt(table) <integer> |
| Returns the cumulated number of connections initiated from the current |
| connection's source IPv4 address in the current proxy's stick-table or in the |
| designated stick-table, that were transformed into sessions, which means that |
| they were accepted by "tcp-request" rules. If the address is not found, zero |
| is returned. See also sc1/sc2_sess_cnt. |
| |
| src_sess_rate <integer> |
| src_sess_rate(table) <integer> |
| Returns the average session rate from the connection's source IPv4 address in |
| the current proxy's stick-table or in the designated stick-table, measured in |
| amount of sessions over the period configured in the table. A session is a |
| connection that got past the early "tcp-request" rules. If the address is not |
| found, zero is returned. See also sc1/sc2_sess_rate. |
| |
| src_updt_conn_cnt <integer> |
| src_updt_conn_cnt(table) <integer> |
| Creates or updates the entry associated to the source IPv4 address in the |
| current proxy's stick-table or in the designated stick-table. This table |
| must be configured to store the "conn_cnt" data type, otherwise the match |
| will be ignored. The current count is incremented by one, and the expiration |
| timer refreshed. The updated count is returned, so this match can't return |
| zero. This is used to reject service abusers based on their source address. |
| Note: it is recommended to use the more complete "track-counters" instead. |
| |
| Example : |
| # This frontend limits incoming SSH connections to 3 per 10 second for |
| # each source address, and rejects excess connections until a 10 second |
| # silence is observed. At most 20 addresses are tracked. |
| listen ssh |
| bind :22 |
| mode tcp |
| maxconn 100 |
| stick-table type ip size 20 expire 10s store conn_cnt |
| tcp-request content reject if { src_update_count gt 3 } |
| server local 127.0.0.1:22 |
| |
| srv_id <integer> |
| Applies to the server's id. Can be used in frontends or backends. |
| |
| srv_is_up(<server>) |
| srv_is_up(<backend>/<server>) |
| Returns true when the designated server is UP, and false when it is either |
| DOWN or in maintenance mode. If <backend> is omitted, then the server is |
| looked up in the current backend. The function takes no arguments since it |
| is used as a boolean. It is mainly used to take action based on an external |
| status reported via a health check (eg: a geographical site's availability). |
| Another possible use which is more of a hack consists in using dummy servers |
| as boolean variables that can be enabled or disabled from the CLI, so that |
| rules depending on those ACLs can be tweaked in realtime. |
| |
| |
| 7.5.2. Matching contents at Layer 4 (also called Layer 6) |
| --------------------------------------------------------- |
| |
| A second set of criteria depends on data found in buffers, but which can change |
| during analysis. This requires that some data has been buffered, for instance |
| through TCP request content inspection. Please see the "tcp-request content" |
| keyword for more detailed information on the subject. |
| |
| req_len <integer> |
| Returns true when the length of the data in the request buffer matches the |
| specified range. It is important to understand that this test does not |
| return false as long as the buffer is changing. This means that a check with |
| equality to zero will almost always immediately match at the beginning of the |
| session, while a test for more data will wait for that data to come in and |
| return false only when haproxy is certain that no more data will come in. |
| This test was designed to be used with TCP request content inspection. |
| |
| req_proto_http |
| Returns true when data in the request buffer look like HTTP and correctly |
| parses as such. It is the same parser as the common HTTP request parser which |
| is used so there should be no surprises. This test can be used for instance |
| to direct HTTP traffic to a given port and HTTPS traffic to another one |
| using TCP request content inspection rules. |
| |
| req_rdp_cookie <string> |
| req_rdp_cookie(name) <string> |
| Returns true when data in the request buffer look like the RDP protocol, and |
| a cookie is present and equal to <string>. By default, any cookie name is |
| checked, but a specific cookie name can be specified in parenthesis. The |
| parser only checks for the first cookie, as illustrated in the RDP protocol |
| specification. The cookie name is case insensitive. This ACL can be useful |
| with the "MSTS" cookie, as it can contain the user name of the client |
| connecting to the server if properly configured on the client. This can be |
| used to restrict access to certain servers to certain users. |
| |
| req_rdp_cookie_cnt <integer> |
| req_rdp_cookie_cnt(name) <integer> |
| Returns true when the data in the request buffer look like the RDP protocol |
| and the number of RDP cookies matches the specified range (typically zero or |
| one). Optionally a specific cookie name can be checked. This is a simple way |
| of detecting the RDP protocol, as clients generally send the MSTS or MSTSHASH |
| cookies. |
| |
| req_ssl_ver <decimal> |
| Returns true when data in the request buffer look like SSL, with a protocol |
| version matching the specified range. Both SSLv2 hello messages and SSLv3 |
| messages are supported. The test tries to be strict enough to avoid being |
| easily fooled. In particular, it waits for as many bytes as announced in the |
| message header if this header looks valid (bound to the buffer size). Note |
| that TLSv1 is announced as SSL version 3.1. This test was designed to be used |
| with TCP request content inspection. |
| |
| req_ssl_hello_type <integer> |
| Returns true when data in the request buffer looks like a complete SSL (v3 |
| or superior) hello message and handshake type is equal to <integer>. |
| This test was designed to be used with TCP request content inspection: an |
| SSL session ID may be fetched. |
| |
| rep_ssl_hello_type <integer> |
| Returns true when data in the response buffer looks like a complete SSL (v3 |
| or superior) hello message and handshake type is equal to <integer>. |
| This test was designed to be used with TCP response content inspection: a |
| SSL session ID may be fetched. |
| |
| wait_end |
| Waits for the end of the analysis period to return true. This may be used in |
| conjunction with content analysis to avoid returning a wrong verdict early. |
| It may also be used to delay some actions, such as a delayed reject for some |
| special addresses. Since it either stops the rules evaluation or immediately |
| returns true, it is recommended to use this acl as the last one in a rule. |
| Please note that the default ACL "WAIT_END" is always usable without prior |
| declaration. This test was designed to be used with TCP request content |
| inspection. |
| |
| Examples : |
| # delay every incoming request by 2 seconds |
| tcp-request inspect-delay 2s |
| tcp-request content accept if WAIT_END |
| |
| # don't immediately tell bad guys they are rejected |
| tcp-request inspect-delay 10s |
| acl goodguys src 10.0.0.0/24 |
| acl badguys src 10.0.1.0/24 |
| tcp-request content accept if goodguys |
| tcp-request content reject if badguys WAIT_END |
| tcp-request content reject |
| |
| |
| 7.5.3. Matching at Layer 7 |
| -------------------------- |
| |
| A third set of criteria applies to information which can be found at the |
| application layer (layer 7). Those require that a full HTTP request has been |
| read, and are only evaluated then. They may require slightly more CPU resources |
| than the layer 4 ones, but not much since the request and response are indexed. |
| |
| hdr <string> |
| hdr(header) <string> |
| Note: all the "hdr*" matching criteria either apply to all headers, or to a |
| particular header whose name is passed between parenthesis and without any |
| space. The header name is not case-sensitive. The header matching complies |
| with RFC2616, and treats as separate headers all values delimited by commas. |
| Use the shdr() variant for response headers sent by the server. |
| |
| The "hdr" criteria returns true if any of the headers matching the criteria |
| match any of the strings. This can be used to check exact for values. For |
| instance, checking that "connection: close" is set : |
| |
| hdr(Connection) -i close |
| |
| hdr_beg <string> |
| hdr_beg(header) <string> |
| Returns true when one of the headers begins with one of the strings. See |
| "hdr" for more information on header matching. Use the shdr_beg() variant for |
| response headers sent by the server. |
| |
| hdr_cnt <integer> |
| hdr_cnt(header) <integer> |
| Returns true when the number of occurrence of the specified header matches |
| the values or ranges specified. It is important to remember that one header |
| line may count as several headers if it has several values. This is used to |
| detect presence, absence or abuse of a specific header, as well as to block |
| request smuggling attacks by rejecting requests which contain more than one |
| of certain headers. See "hdr" for more information on header matching. Use |
| the shdr_cnt() variant for response headers sent by the server. |
| |
| hdr_dir <string> |
| hdr_dir(header) <string> |
| Returns true when one of the headers contains one of the strings either |
| isolated or delimited by slashes. This is used to perform filename or |
| directory name matching, and may be used with Referer. See "hdr" for more |
| information on header matching. Use the shdr_dir() variant for response |
| headers sent by the server. |
| |
| hdr_dom <string> |
| hdr_dom(header) <string> |
| Returns true when one of the headers contains one of the strings either |
| isolated or delimited by dots. This is used to perform domain name matching, |
| and may be used with the Host header. See "hdr" for more information on |
| header matching. Use the shdr_dom() variant for response headers sent by the |
| server. |
| |
| hdr_end <string> |
| hdr_end(header) <string> |
| Returns true when one of the headers ends with one of the strings. See "hdr" |
| for more information on header matching. Use the shdr_end() variant for |
| response headers sent by the server. |
| |
| hdr_ip <ip_address> |
| hdr_ip(header) <ip_address> |
| Returns true when one of the headers' values contains an IP address matching |
| <ip_address>. This is mainly used with headers such as X-Forwarded-For or |
| X-Client-IP. See "hdr" for more information on header matching. Use the |
| shdr_ip() variant for response headers sent by the server. |
| |
| hdr_reg <regex> |
| hdr_reg(header) <regex> |
| Returns true when one of the headers matches of the regular expressions. It |
| can be used at any time, but it is important to remember that regex matching |
| is slower than other methods. See also other "hdr_" criteria, as well as |
| "hdr" for more information on header matching. Use the shdr_reg() variant for |
| response headers sent by the server. |
| |
| hdr_sub <string> |
| hdr_sub(header) <string> |
| Returns true when one of the headers contains one of the strings. See "hdr" |
| for more information on header matching. Use the shdr_sub() variant for |
| response headers sent by the server. |
| |
| hdr_val <integer> |
| hdr_val(header) <integer> |
| Returns true when one of the headers starts with a number which matches the |
| values or ranges specified. This may be used to limit content-length to |
| acceptable values for example. See "hdr" for more information on header |
| matching. Use the shdr_val() variant for response headers sent by the server. |
| |
| http_auth(userlist) |
| http_auth_group(userlist) <group> [<group>]* |
| Returns true when authentication data received from the client matches |
| username & password stored on the userlist. It is also possible to |
| use http_auth_group to check if the user is assigned to at least one |
| of specified groups. |
| |
| Currently only http basic auth is supported. |
| |
| http_req_first |
| Returns true when the request being processed is the first one of the |
| connection. This can be used to add or remove headers that may be missing |
| from some requests when a request is not the first one, or even to perform |
| some specific ACL checks only on the first request. |
| |
| method <string> |
| Applies to the method in the HTTP request, eg: "GET". Some predefined ACL |
| already check for most common methods. |
| |
| path <string> |
| Returns true when the path part of the request, which starts at the first |
| slash and ends before the question mark, equals one of the strings. It may be |
| used to match known files, such as /favicon.ico. |
| |
| path_beg <string> |
| Returns true when the path begins with one of the strings. This can be used |
| to send certain directory names to alternative backends. |
| |
| path_dir <string> |
| Returns true when one of the strings is found isolated or delimited with |
| slashes in the path. This is used to perform filename or directory name |
| matching without the risk of wrong match due to colliding prefixes. See also |
| "url_dir" and "path_sub". |
| |
| path_dom <string> |
| Returns true when one of the strings is found isolated or delimited with dots |
| in the path. This may be used to perform domain name matching in proxy |
| requests. See also "path_sub" and "url_dom". |
| |
| path_end <string> |
| Returns true when the path ends with one of the strings. This may be used to |
| control file name extension. |
| |
| path_reg <regex> |
| Returns true when the path matches one of the regular expressions. It can be |
| used any time, but it is important to remember that regex matching is slower |
| than other methods. See also "url_reg" and all "path_" criteria. |
| |
| path_sub <string> |
| Returns true when the path contains one of the strings. It can be used to |
| detect particular patterns in paths, such as "../" for example. See also |
| "path_dir". |
| |
| req_ver <string> |
| Applies to the version string in the HTTP request, eg: "1.0". Some predefined |
| ACL already check for versions 1.0 and 1.1. |
| |
| status <integer> |
| Applies to the HTTP status code in the HTTP response, eg: "302". It can be |
| used to act on responses depending on status ranges, for instance, remove |
| any Location header if the response is not a 3xx. |
| |
| url <string> |
| Applies to the whole URL passed in the request. The only real use is to match |
| "*", for which there already is a predefined ACL. |
| |
| url_beg <string> |
| Returns true when the URL begins with one of the strings. This can be used to |
| check whether a URL begins with a slash or with a protocol scheme. |
| |
| url_dir <string> |
| Returns true when one of the strings is found isolated or delimited with |
| slashes in the URL. This is used to perform filename or directory name |
| matching without the risk of wrong match due to colliding prefixes. See also |
| "path_dir" and "url_sub". |
| |
| url_dom <string> |
| Returns true when one of the strings is found isolated or delimited with dots |
| in the URL. This is used to perform domain name matching without the risk of |
| wrong match due to colliding prefixes. See also "url_sub". |
| |
| url_end <string> |
| Returns true when the URL ends with one of the strings. It has very limited |
| use. "path_end" should be used instead for filename matching. |
| |
| url_ip <ip_address> |
| Applies to the IP address specified in the absolute URI in an HTTP request. |
| It can be used to prevent access to certain resources such as local network. |
| It is useful with option "http_proxy". |
| |
| url_port <integer> |
| Applies to the port specified in the absolute URI in an HTTP request. It can |
| be used to prevent access to certain resources. It is useful with option |
| "http_proxy". Note that if the port is not specified in the request, port 80 |
| is assumed. |
| |
| url_reg <regex> |
| Returns true when the URL matches one of the regular expressions. It can be |
| used any time, but it is important to remember that regex matching is slower |
| than other methods. See also "path_reg" and all "url_" criteria. |
| |
| url_sub <string> |
| Returns true when the URL contains one of the strings. It can be used to |
| detect particular patterns in query strings for example. See also "path_sub". |
| |
| |
| 7.6. Pre-defined ACLs |
| --------------------- |
| |
| Some predefined ACLs are hard-coded so that they do not have to be declared in |
| every frontend which needs them. They all have their names in upper case in |
| order to avoid confusion. Their equivalence is provided below. |
| |
| ACL name Equivalent to Usage |
| ---------------+-----------------------------+--------------------------------- |
| FALSE always_false never match |
| HTTP req_proto_http match if protocol is valid HTTP |
| HTTP_1.0 req_ver 1.0 match HTTP version 1.0 |
| HTTP_1.1 req_ver 1.1 match HTTP version 1.1 |
| HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length |
| HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme |
| HTTP_URL_SLASH url_beg / match URL beginning with "/" |
| HTTP_URL_STAR url * match URL equal to "*" |
| LOCALHOST src 127.0.0.1/8 match connection from local host |
| METH_CONNECT method CONNECT match HTTP CONNECT method |
| METH_GET method GET HEAD match HTTP GET or HEAD method |
| METH_HEAD method HEAD match HTTP HEAD method |
| METH_OPTIONS method OPTIONS match HTTP OPTIONS method |
| METH_POST method POST match HTTP POST method |
| METH_TRACE method TRACE match HTTP TRACE method |
| RDP_COOKIE req_rdp_cookie_cnt gt 0 match presence of an RDP cookie |
| REQ_CONTENT req_len gt 0 match data in the request buffer |
| TRUE always_true always match |
| WAIT_END wait_end wait for end of content analysis |
| ---------------+-----------------------------+--------------------------------- |
| |
| |
| 7.7. Using ACLs to form conditions |
| ---------------------------------- |
| |
| Some actions are only performed upon a valid condition. A condition is a |
| combination of ACLs with operators. 3 operators are supported : |
| |
| - AND (implicit) |
| - OR (explicit with the "or" keyword or the "||" operator) |
| - Negation with the exclamation mark ("!") |
| |
| A condition is formed as a disjunctive form: |
| |
| [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ... |
| |
| Such conditions are generally used after an "if" or "unless" statement, |
| indicating when the condition will trigger the action. |
| |
| For instance, to block HTTP requests to the "*" URL with methods other than |
| "OPTIONS", as well as POST requests without content-length, and GET or HEAD |
| requests with a content-length greater than 0, and finally every request which |
| is not either GET/HEAD/POST/OPTIONS ! |
| |
| acl missing_cl hdr_cnt(Content-length) eq 0 |
| block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl |
| block if METH_GET HTTP_CONTENT |
| block unless METH_GET or METH_POST or METH_OPTIONS |
| |
| To select a different backend for requests to static contents on the "www" site |
| and to every request on the "img", "video", "download" and "ftp" hosts : |
| |
| acl url_static path_beg /static /images /img /css |
| acl url_static path_end .gif .png .jpg .css .js |
| acl host_www hdr_beg(host) -i www |
| acl host_static hdr_beg(host) -i img. video. download. ftp. |
| |
| # now use backend "static" for all static-only hosts, and for static urls |
| # of host "www". Use backend "www" for the rest. |
| use_backend static if host_static or host_www url_static |
| use_backend www if host_www |
| |
| It is also possible to form rules using "anonymous ACLs". Those are unnamed ACL |
| expressions that are built on the fly without needing to be declared. They must |
| be enclosed between braces, with a space before and after each brace (because |
| the braces must be seen as independant words). Example : |
| |
| The following rule : |
| |
| acl missing_cl hdr_cnt(Content-length) eq 0 |
| block if METH_POST missing_cl |
| |
| Can also be written that way : |
| |
| block if METH_POST { hdr_cnt(Content-length) eq 0 } |
| |
| It is generally not recommended to use this construct because it's a lot easier |
| to leave errors in the configuration when written that way. However, for very |
| simple rules matching only one source IP address for instance, it can make more |
| sense to use them than to declare ACLs with random names. Another example of |
| good use is the following : |
| |
| With named ACLs : |
| |
| acl site_dead nbsrv(dynamic) lt 2 |
| acl site_dead nbsrv(static) lt 2 |
| monitor fail if site_dead |
| |
| With anonymous ACLs : |
| |
| monitor fail if { nbsrv(dynamic) lt 2 } || { nbsrv(static) lt 2 } |
| |
| See section 4.2 for detailed help on the "block" and "use_backend" keywords. |
| |
| |
| 7.8. Pattern extraction |
| ----------------------- |
| |
| The stickiness features relies on pattern extraction in the request and |
| response. Sometimes the data needs to be converted first before being stored, |
| for instance converted from ASCII to IP or upper case to lower case. |
| |
| All these operations of data extraction and conversion are defined as |
| "pattern extraction rules". A pattern rule always has the same format. It |
| begins with a single pattern fetch word, potentially followed by a list of |
| arguments within parenthesis then an optional list of transformations. As |
| much as possible, the pattern fetch functions use the same name as their |
| equivalent used in ACLs. |
| |
| The list of currently supported pattern fetch functions is the following : |
| |
| src This is the source IPv4 address of the client of the session. |
| It is of type IP and only works with such tables. |
| |
| dst This is the destination IPv4 address of the session on the |
| client side, which is the address the client connected to. |
| It can be useful when running in transparent mode. It is of |
| typie IP and only works with such tables. |
| |
| dst_port This is the destination TCP port of the session on the client |
| side, which is the port the client connected to. This might be |
| used when running in transparent mode or when assigning dynamic |
| ports to some clients for a whole application session. It is of |
| type integer and only works with such tables. |
| |
| hdr(name) This extracts the last occurrence of header <name> in an HTTP |
| request and converts it to an IP address. This IP address is |
| then used to match the table. A typical use is with the |
| x-forwarded-for header. |
| |
| payload(offset,length) |
| This extracts a binary block of <length> bytes, and starting |
| at bytes <offset> in the buffer of request or response (request |
| on "stick on" or "stick match" or response in on "stick store |
| response"). |
| |
| payload_lv(offset1,length[,offset2]) |
| This extracts a binary block. In a first step the size of the |
| block is read from response or request buffer at <offset> |
| bytes and considered coded on <length> bytes. In a second step |
| data of the block are read from buffer at <offset2> bytes |
| (by default <lengthoffset> + <lengthsize>). |
| If <offset2> is prefixed by '+' or '-', it is relative to |
| <lengthoffset> + <lengthsize> else it is absolute. |
| Ex: see SSL session id example in "stick table" chapter. |
| |
| url_param(name) |
| This extracts the first occurrence of the parameter <name> in |
| the query string of the request and uses the correponding value |
| to match. A typical use is to get sticky session through url (e.g. |
| http://example.com/foo?JESSIONID=some_id with |
| url_param(JSESSIONID)), for cases where cookies cannot be used. |
| |
| The currently available list of transformations include : |
| |
| lower Convert a string pattern to lower case. This can only be placed |
| after a string pattern fetch function or after a conversion |
| function returning a string type. The result is of type string. |
| |
| upper Convert a string pattern to upper case. This can only be placed |
| after a string pattern fetch function or after a conversion |
| function returning a string type. The result is of type string. |
| |
| ipmask(mask) Apply a mask to an IPv4 address, and use the result for lookups |
| and storage. This can be used to make all hosts within a |
| certain mask to share the same table entries and as such use |
| the same server. The mask can be passed in dotted form (eg: |
| 255.255.255.0) or in CIDR form (eg: 24). |
| |
| |
| 8. Logging |
| ---------- |
| |
| One of HAProxy's strong points certainly lies is its precise logs. It probably |
| provides the finest level of information available for such a product, which is |
| very important for troubleshooting complex environments. Standard information |
| provided in logs include client ports, TCP/HTTP state timers, precise session |
| state at termination and precise termination cause, information about decisions |
| to direct traffic to a server, and of course the ability to capture arbitrary |
| headers. |
| |
| In order to improve administrators reactivity, it offers a great transparency |
| about encountered problems, both internal and external, and it is possible to |
| send logs to different sources at the same time with different level filters : |
| |
| - global process-level logs (system errors, start/stop, etc..) |
| - per-instance system and internal errors (lack of resource, bugs, ...) |
| - per-instance external troubles (servers up/down, max connections) |
| - per-instance activity (client connections), either at the establishment or |
| at the termination. |
| |
| The ability to distribute different levels of logs to different log servers |
| allow several production teams to interact and to fix their problems as soon |
| as possible. For example, the system team might monitor system-wide errors, |
| while the application team might be monitoring the up/down for their servers in |
| real time, and the security team might analyze the activity logs with one hour |
| delay. |
| |
| |
| 8.1. Log levels |
| --------------- |
| |
| TCP and HTTP connections can be logged with informations such as date, time, |
| source IP address, destination address, connection duration, response times, |
| HTTP request, the HTTP return code, number of bytes transmitted, the conditions |
| in which the session ended, and even exchanged cookies values, to track a |
| particular user's problems for example. All messages are sent to up to two |
| syslog servers. Check the "log" keyword in section 4.2 for more info about log |
| facilities. |
| |
| |
| 8.2. Log formats |
| ---------------- |
| |
| HAProxy supports 4 log formats. Several fields are common between these formats |
| and will be detailed in the next sections. A few of them may slightly vary with |
| the configuration, due to indicators specific to certain options. The supported |
| formats are the following ones : |
| |
| - the default format, which is very basic and very rarely used. It only |
| provides very basic information about the incoming connection at the moment |
| it is accepted : source IP:port, destination IP:port, and frontend-name. |
| This mode will eventually disappear so it will not be described to great |
| extents. |
| |
| - the TCP format, which is more advanced. This format is enabled when "option |
| tcplog" is set on the frontend. HAProxy will then usually wait for the |
| connection to terminate before logging. This format provides much richer |
| information, such as timers, connection counts, queue size, etc... This |
| format is recommended for pure TCP proxies. |
| |
| - the HTTP format, which is the most advanced for HTTP proxying. This format |
| is enabled when "option httplog" is set on the frontend. It provides the |
| same information as the TCP format with some HTTP-specific fields such as |
| the request, the status code, and captures of headers and cookies. This |
| format is recommended for HTTP proxies. |
| |
| - the CLF HTTP format, which is equivalent to the HTTP format, but with the |
| fields arranged in the same order as the CLF format. In this mode, all |
| timers, captures, flags, etc... appear one per field after the end of the |
| common fields, in the same order they appear in the standard HTTP format. |
| |
| Next sections will go deeper into details for each of these formats. Format |
| specification will be performed on a "field" basis. Unless stated otherwise, a |
| field is a portion of text delimited by any number of spaces. Since syslog |
| servers are susceptible of inserting fields at the beginning of a line, it is |
| always assumed that the first field is the one containing the process name and |
| identifier. |
| |
| Note : Since log lines may be quite long, the log examples in sections below |
| might be broken into multiple lines. The example log lines will be |
| prefixed with 3 closing angle brackets ('>>>') and each time a log is |
| broken into multiple lines, each non-final line will end with a |
| backslash ('\') and the next line will start indented by two characters. |
| |
| |
| 8.2.1. Default log format |
| ------------------------- |
| |
| This format is used when no specific option is set. The log is emitted as soon |
| as the connection is accepted. One should note that this currently is the only |
| format which logs the request's destination IP and ports. |
| |
| Example : |
| listen www |
| mode http |
| log global |
| server srv1 127.0.0.1:8000 |
| |
| >>> Feb 6 12:12:09 localhost \ |
| haproxy[14385]: Connect from 10.0.1.2:33312 to 10.0.3.31:8012 \ |
| (www/HTTP) |
| |
| Field Format Extract from the example above |
| 1 process_name '[' pid ']:' haproxy[14385]: |
| 2 'Connect from' Connect from |
| 3 source_ip ':' source_port 10.0.1.2:33312 |
| 4 'to' to |
| 5 destination_ip ':' destination_port 10.0.3.31:8012 |
| 6 '(' frontend_name '/' mode ')' (www/HTTP) |
| |
| Detailed fields description : |
| - "source_ip" is the IP address of the client which initiated the connection. |
| - "source_port" is the TCP port of the client which initiated the connection. |
| - "destination_ip" is the IP address the client connected to. |
| - "destination_port" is the TCP port the client connected to. |
| - "frontend_name" is the name of the frontend (or listener) which received |
| and processed the connection. |
| - "mode is the mode the frontend is operating (TCP or HTTP). |
| |
| In case of a UNIX socket, the source and destination addresses are marked as |
| "unix:" and the ports reflect the internal ID of the socket which accepted the |
| connection (the same ID as reported in the stats). |
| |
| It is advised not to use this deprecated format for newer installations as it |
| will eventually disappear. |
| |
| |
| 8.2.2. TCP log format |
| --------------------- |
| |
| The TCP format is used when "option tcplog" is specified in the frontend, and |
| is the recommended format for pure TCP proxies. It provides a lot of precious |
| information for troubleshooting. Since this format includes timers and byte |
| counts, the log is normally emitted at the end of the session. It can be |
| emitted earlier if "option logasap" is specified, which makes sense in most |
| environments with long sessions such as remote terminals. Sessions which match |
| the "monitor" rules are never logged. It is also possible not to emit logs for |
| sessions for which no data were exchanged between the client and the server, by |
| specifying "option dontlognull" in the frontend. Successful connections will |
| not be logged if "option dontlog-normal" is specified in the frontend. A few |
| fields may slightly vary depending on some configuration options, those are |
| marked with a star ('*') after the field name below. |
| |
| Example : |
| frontend fnt |
| mode tcp |
| option tcplog |
| log global |
| default_backend bck |
| |
| backend bck |
| server srv1 127.0.0.1:8000 |
| |
| >>> Feb 6 12:12:56 localhost \ |
| haproxy[14387]: 10.0.1.2:33313 [06/Feb/2009:12:12:51.443] fnt \ |
| bck/srv1 0/0/5007 212 -- 0/0/0/0/3 0/0 |
| |
| Field Format Extract from the example above |
| 1 process_name '[' pid ']:' haproxy[14387]: |
| 2 client_ip ':' client_port 10.0.1.2:33313 |
| 3 '[' accept_date ']' [06/Feb/2009:12:12:51.443] |
| 4 frontend_name fnt |
| 5 backend_name '/' server_name bck/srv1 |
| 6 Tw '/' Tc '/' Tt* 0/0/5007 |
| 7 bytes_read* 212 |
| 8 termination_state -- |
| 9 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 0/0/0/0/3 |
| 10 srv_queue '/' backend_queue 0/0 |
| |
| Detailed fields description : |
| - "client_ip" is the IP address of the client which initiated the TCP |
| connection to haproxy. If the connection was accepted on a UNIX socket |
| instead, the IP address would be replaced with the word "unix". Note that |
| when the connection is accepted on a socket configured with "accept-proxy" |
| and the PROXY protocol is correctly used, then the logs will reflect the |
| forwarded connection's information. |
| |
| - "client_port" is the TCP port of the client which initiated the connection. |
| If the connection was accepted on a UNIX socket instead, the port would be |
| replaced with the ID of the accepting socket, which is also reported in the |
| stats interface. |
| |
| - "accept_date" is the exact date when the connection was received by haproxy |
| (which might be very slightly different from the date observed on the |
| network if there was some queuing in the system's backlog). This is usually |
| the same date which may appear in any upstream firewall's log. |
| |
| - "frontend_name" is the name of the frontend (or listener) which received |
| and processed the connection. |
| |
| - "backend_name" is the name of the backend (or listener) which was selected |
| to manage the connection to the server. This will be the same as the |
| frontend if no switching rule has been applied, which is common for TCP |
| applications. |
| |
| - "server_name" is the name of the last server to which the connection was |
| sent, which might differ from the first one if there were connection errors |
| and a redispatch occurred. Note that this server belongs to the backend |
| which processed the request. If the connection was aborted before reaching |
| a server, "<NOSRV>" is indicated instead of a server name. |
| |
| - "Tw" is the total time in milliseconds spent waiting in the various queues. |
| It can be "-1" if the connection was aborted before reaching the queue. |
| See "Timers" below for more details. |
| |
| - "Tc" is the total time in milliseconds spent waiting for the connection to |
| establish to the final server, including retries. It can be "-1" if the |
| connection was aborted before a connection could be established. See |
| "Timers" below for more details. |
| |
| - "Tt" is the total time in milliseconds elapsed between the accept and the |
| last close. It covers all possible processings. There is one exception, if |
| "option logasap" was specified, then the time counting stops at the moment |
| the log is emitted. In this case, a '+' sign is prepended before the value, |
| indicating that the final one will be larger. See "Timers" below for more |
| details. |
| |
| - "bytes_read" is the total number of bytes transmitted from the server to |
| the client when the log is emitted. If "option logasap" is specified, the |
| this value will be prefixed with a '+' sign indicating that the final one |
| may be larger. Please note that this value is a 64-bit counter, so log |
| analysis tools must be able to handle it without overflowing. |
| |
| - "termination_state" is the condition the session was in when the session |
| ended. This indicates the session state, which side caused the end of |
| session to happen, and for what reason (timeout, error, ...). The normal |
| flags should be "--", indicating the session was closed by either end with |
| no data remaining in buffers. See below "Session state at disconnection" |
| for more details. |
| |
| - "actconn" is the total number of concurrent connections on the process when |
| the session was logged. It it useful to detect when some per-process system |
| limits have been reached. For instance, if actconn is close to 512 when |
| multiple connection errors occur, chances are high that the system limits |
| the process to use a maximum of 1024 file descriptors and that all of them |
| are used. See section 3 "Global parameters" to find how to tune the system. |
| |
| - "feconn" is the total number of concurrent connections on the frontend when |
| the session was logged. It is useful to estimate the amount of resource |
| required to sustain high loads, and to detect when the frontend's "maxconn" |
| has been reached. Most often when this value increases by huge jumps, it is |
| because there is congestion on the backend servers, but sometimes it can be |
| caused by a denial of service attack. |
| |
| - "beconn" is the total number of concurrent connections handled by the |
| backend when the session was logged. It includes the total number of |
| concurrent connections active on servers as well as the number of |
| connections pending in queues. It is useful to estimate the amount of |
| additional servers needed to support high loads for a given application. |
| Most often when this value increases by huge jumps, it is because there is |
| congestion on the backend servers, but sometimes it can be caused by a |
| denial of service attack. |
| |
| - "srv_conn" is the total number of concurrent connections still active on |
| the server when the session was logged. It can never exceed the server's |
| configured "maxconn" parameter. If this value is very often close or equal |
| to the server's "maxconn", it means that traffic regulation is involved a |
| lot, meaning that either the server's maxconn value is too low, or that |
| there aren't enough servers to process the load with an optimal response |
| time. When only one of the server's "srv_conn" is high, it usually means |
| that this server has some trouble causing the connections to take longer to |
| be processed than on other servers. |
| |
| - "retries" is the number of connection retries experienced by this session |
| when trying to connect to the server. It must normally be zero, unless a |
| server is being stopped at the same moment the connection was attempted. |
| Frequent retries generally indicate either a network problem between |
| haproxy and the server, or a misconfigured system backlog on the server |
| preventing new connections from being queued. This field may optionally be |
| prefixed with a '+' sign, indicating that the session has experienced a |
| redispatch after the maximal retry count has been reached on the initial |
| server. In this case, the server name appearing in the log is the one the |
| connection was redispatched to, and not the first one, though both may |
| sometimes be the same in case of hashing for instance. So as a general rule |
| of thumb, when a '+' is present in front of the retry count, this count |
| should not be attributed to the logged server. |
| |
| - "srv_queue" is the total number of requests which were processed before |
| this one in the server queue. It is zero when the request has not gone |
| through the server queue. It makes it possible to estimate the approximate |
| server's response time by dividing the time spent in queue by the number of |
| requests in the queue. It is worth noting that if a session experiences a |
| redispatch and passes through two server queues, their positions will be |
| cumulated. A request should not pass through both the server queue and the |
| backend queue unless a redispatch occurs. |
| |
| - "backend_queue" is the total number of requests which were processed before |
| this one in the backend's global queue. It is zero when the request has not |
| gone through the global queue. It makes it possible to estimate the average |
| queue length, which easily translates into a number of missing servers when |
| divided by a server's "maxconn" parameter. It is worth noting that if a |
| session experiences a redispatch, it may pass twice in the backend's queue, |
| and then both positions will be cumulated. A request should not pass |
| through both the server queue and the backend queue unless a redispatch |
| occurs. |
| |
| |
| 8.2.3. HTTP log format |
| ---------------------- |
| |
| The HTTP format is the most complete and the best suited for HTTP proxies. It |
| is enabled by when "option httplog" is specified in the frontend. It provides |
| the same level of information as the TCP format with additional features which |
| are specific to the HTTP protocol. Just like the TCP format, the log is usually |
| emitted at the end of the session, unless "option logasap" is specified, which |
| generally only makes sense for download sites. A session which matches the |
| "monitor" rules will never logged. It is also possible not to log sessions for |
| which no data were sent by the client by specifying "option dontlognull" in the |
| frontend. Successful connections will not be logged if "option dontlog-normal" |
| is specified in the frontend. |
| |
| Most fields are shared with the TCP log, some being different. A few fields may |
| slightly vary depending on some configuration options. Those ones are marked |
| with a star ('*') after the field name below. |
| |
| Example : |
| frontend http-in |
| mode http |
| option httplog |
| log global |
| default_backend bck |
| |
| backend static |
| server srv1 127.0.0.1:8000 |
| |
| >>> Feb 6 12:14:14 localhost \ |
| haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ |
| static/srv1 10/0/30/69/109 200 2750 - - ---- 1/1/1/1/0 0/0 {1wt.eu} \ |
| {} "GET /index.html HTTP/1.1" |
| |
| Field Format Extract from the example above |
| 1 process_name '[' pid ']:' haproxy[14389]: |
| 2 client_ip ':' client_port 10.0.1.2:33317 |
| 3 '[' accept_date ']' [06/Feb/2009:12:14:14.655] |
| 4 frontend_name http-in |
| 5 backend_name '/' server_name static/srv1 |
| 6 Tq '/' Tw '/' Tc '/' Tr '/' Tt* 10/0/30/69/109 |
| 7 status_code 200 |
| 8 bytes_read* 2750 |
| 9 captured_request_cookie - |
| 10 captured_response_cookie - |
| 11 termination_state ---- |
| 12 actconn '/' feconn '/' beconn '/' srv_conn '/' retries* 1/1/1/1/0 |
| 13 srv_queue '/' backend_queue 0/0 |
| 14 '{' captured_request_headers* '}' {haproxy.1wt.eu} |
| 15 '{' captured_response_headers* '}' {} |
| 16 '"' http_request '"' "GET /index.html HTTP/1.1" |
| |
| |
| Detailed fields description : |
| - "client_ip" is the IP address of the client which initiated the TCP |
| connection to haproxy. If the connection was accepted on a UNIX socket |
| instead, the IP address would be replaced with the word "unix". Note that |
| when the connection is accepted on a socket configured with "accept-proxy" |
| and the PROXY protocol is correctly used, then the logs will reflect the |
| forwarded connection's information. |
| |
| - "client_port" is the TCP port of the client which initiated the connection. |
| If the connection was accepted on a UNIX socket instead, the port would be |
| replaced with the ID of the accepting socket, which is also reported in the |
| stats interface. |
| |
| - "accept_date" is the exact date when the TCP connection was received by |
| haproxy (which might be very slightly different from the date observed on |
| the network if there was some queuing in the system's backlog). This is |
| usually the same date which may appear in any upstream firewall's log. This |
| does not depend on the fact that the client has sent the request or not. |
| |
| - "frontend_name" is the name of the frontend (or listener) which received |
| and processed the connection. |
| |
| - "backend_name" is the name of the backend (or listener) which was selected |
| to manage the connection to the server. This will be the same as the |
| frontend if no switching rule has been applied. |
| |
| - "server_name" is the name of the last server to which the connection was |
| sent, which might differ from the first one if there were connection errors |
| and a redispatch occurred. Note that this server belongs to the backend |
| which processed the request. If the request was aborted before reaching a |
| server, "<NOSRV>" is indicated instead of a server name. If the request was |
| intercepted by the stats subsystem, "<STATS>" is indicated instead. |
| |
| - "Tq" is the total time in milliseconds spent waiting for the client to send |
| a full HTTP request, not counting data. It can be "-1" if the connection |
| was aborted before a complete request could be received. It should always |
| be very small because a request generally fits in one single packet. Large |
| times here generally indicate network trouble between the client and |
| haproxy. See "Timers" below for more details. |
| |
| - "Tw" is the total time in milliseconds spent waiting in the various queues. |
| It can be "-1" if the connection was aborted before reaching the queue. |
| See "Timers" below for more details. |
| |
| - "Tc" is the total time in milliseconds spent waiting for the connection to |
| establish to the final server, including retries. It can be "-1" if the |
| request was aborted before a connection could be established. See "Timers" |
| below for more details. |
| |
| - "Tr" is the total time in milliseconds spent waiting for the server to send |
| a full HTTP response, not counting data. It can be "-1" if the request was |
| aborted before a complete response could be received. It generally matches |
| the server's processing time for the request, though it may be altered by |
| the amount of data sent by the client to the server. Large times here on |
| "GET" requests generally indicate an overloaded server. See "Timers" below |
| for more details. |
| |
| - "Tt" is the total time in milliseconds elapsed between the accept and the |
| last close. It covers all possible processings. There is one exception, if |
| "option logasap" was specified, then the time counting stops at the moment |
| the log is emitted. In this case, a '+' sign is prepended before the value, |
| indicating that the final one will be larger. See "Timers" below for more |
| details. |
| |
| - "status_code" is the HTTP status code returned to the client. This status |
| is generally set by the server, but it might also be set by haproxy when |
| the server cannot be reached or when its response is blocked by haproxy. |
| |
| - "bytes_read" is the total number of bytes transmitted to the client when |
| the log is emitted. This does include HTTP headers. If "option logasap" is |
| specified, the this value will be prefixed with a '+' sign indicating that |
| the final one may be larger. Please note that this value is a 64-bit |
| counter, so log analysis tools must be able to handle it without |
| overflowing. |
| |
| - "captured_request_cookie" is an optional "name=value" entry indicating that |
| the client had this cookie in the request. The cookie name and its maximum |
| length are defined by the "capture cookie" statement in the frontend |
| configuration. The field is a single dash ('-') when the option is not |
| set. Only one cookie may be captured, it is generally used to track session |
| ID exchanges between a client and a server to detect session crossing |
| between clients due to application bugs. For more details, please consult |
| the section "Capturing HTTP headers and cookies" below. |
| |
| - "captured_response_cookie" is an optional "name=value" entry indicating |
| that the server has returned a cookie with its response. The cookie name |
| and its maximum length are defined by the "capture cookie" statement in the |
| frontend configuration. The field is a single dash ('-') when the option is |
| not set. Only one cookie may be captured, it is generally used to track |
| session ID exchanges between a client and a server to detect session |
| crossing between clients due to application bugs. For more details, please |
| consult the section "Capturing HTTP headers and cookies" below. |
| |
| - "termination_state" is the condition the session was in when the session |
| ended. This indicates the session state, which side caused the end of |
| session to happen, for what reason (timeout, error, ...), just like in TCP |
| logs, and information about persistence operations on cookies in the last |
| two characters. The normal flags should begin with "--", indicating the |
| session was closed by either end with no data remaining in buffers. See |
| below "Session state at disconnection" for more details. |
| |
| - "actconn" is the total number of concurrent connections on the process when |
| the session was logged. It it useful to detect when some per-process system |
| limits have been reached. For instance, if actconn is close to 512 or 1024 |
| when multiple connection errors occur, chances are high that the system |
| limits the process to use a maximum of 1024 file descriptors and that all |
| of them are used. See section 3 "Global parameters" to find how to tune the |
| system. |
| |
| - "feconn" is the total number of concurrent connections on the frontend when |
| the session was logged. It is useful to estimate the amount of resource |
| required to sustain high loads, and to detect when the frontend's "maxconn" |
| has been reached. Most often when this value increases by huge jumps, it is |
| because there is congestion on the backend servers, but sometimes it can be |
| caused by a denial of service attack. |
| |
| - "beconn" is the total number of concurrent connections handled by the |
| backend when the session was logged. It includes the total number of |
| concurrent connections active on servers as well as the number of |
| connections pending in queues. It is useful to estimate the amount of |
| additional servers needed to support high loads for a given application. |
| Most often when this value increases by huge jumps, it is because there is |
| congestion on the backend servers, but sometimes it can be caused by a |
| denial of service attack. |
| |
| - "srv_conn" is the total number of concurrent connections still active on |
| the server when the session was logged. It can never exceed the server's |
| configured "maxconn" parameter. If this value is very often close or equal |
| to the server's "maxconn", it means that traffic regulation is involved a |
| lot, meaning that either the server's maxconn value is too low, or that |
| there aren't enough servers to process the load with an optimal response |
| time. When only one of the server's "srv_conn" is high, it usually means |
| that this server has some trouble causing the requests to take longer to be |
| processed than on other servers. |
| |
| - "retries" is the number of connection retries experienced by this session |
| when trying to connect to the server. It must normally be zero, unless a |
| server is being stopped at the same moment the connection was attempted. |
| Frequent retries generally indicate either a network problem between |
| haproxy and the server, or a misconfigured system backlog on the server |
| preventing new connections from being queued. This field may optionally be |
| prefixed with a '+' sign, indicating that the session has experienced a |
| redispatch after the maximal retry count has been reached on the initial |
| server. In this case, the server name appearing in the log is the one the |
| connection was redispatched to, and not the first one, though both may |
| sometimes be the same in case of hashing for instance. So as a general rule |
| of thumb, when a '+' is present in front of the retry count, this count |
| should not be attributed to the logged server. |
| |
| - "srv_queue" is the total number of requests which were processed before |
| this one in the server queue. It is zero when the request has not gone |
| through the server queue. It makes it possible to estimate the approximate |
| server's response time by dividing the time spent in queue by the number of |
| requests in the queue. It is worth noting that if a session experiences a |
| redispatch and passes through two server queues, their positions will be |
| cumulated. A request should not pass through both the server queue and the |
| backend queue unless a redispatch occurs. |
| |
| - "backend_queue" is the total number of requests which were processed before |
| this one in the backend's global queue. It is zero when the request has not |
| gone through the global queue. It makes it possible to estimate the average |
| queue length, which easily translates into a number of missing servers when |
| divided by a server's "maxconn" parameter. It is worth noting that if a |
| session experiences a redispatch, it may pass twice in the backend's queue, |
| and then both positions will be cumulated. A request should not pass |
| through both the server queue and the backend queue unless a redispatch |
| occurs. |
| |
| - "captured_request_headers" is a list of headers captured in the request due |
| to the presence of the "capture request header" statement in the frontend. |
| Multiple headers can be captured, they will be delimited by a vertical bar |
| ('|'). When no capture is enabled, the braces do not appear, causing a |
| shift of remaining fields. It is important to note that this field may |
| contain spaces, and that using it requires a smarter log parser than when |
| it's not used. Please consult the section "Capturing HTTP headers and |
| cookies" below for more details. |
| |
| - "captured_response_headers" is a list of headers captured in the response |
| due to the presence of the "capture response header" statement in the |
| frontend. Multiple headers can be captured, they will be delimited by a |
| vertical bar ('|'). When no capture is enabled, the braces do not appear, |
| causing a shift of remaining fields. It is important to note that this |
| field may contain spaces, and that using it requires a smarter log parser |
| than when it's not used. Please consult the section "Capturing HTTP headers |
| and cookies" below for more details. |
| |
| - "http_request" is the complete HTTP request line, including the method, |
| request and HTTP version string. Non-printable characters are encoded (see |
| below the section "Non-printable characters"). This is always the last |
| field, and it is always delimited by quotes and is the only one which can |
| contain quotes. If new fields are added to the log format, they will be |
| added before this field. This field might be truncated if the request is |
| huge and does not fit in the standard syslog buffer (1024 characters). This |
| is the reason why this field must always remain the last one. |
| |
| |
| 8.3. Advanced logging options |
| ----------------------------- |
| |
| Some advanced logging options are often looked for but are not easy to find out |
| just by looking at the various options. Here is an entry point for the few |
| options which can enable better logging. Please refer to the keywords reference |
| for more information about their usage. |
| |
| |
| 8.3.1. Disabling logging of external tests |
| ------------------------------------------ |
| |
| It is quite common to have some monitoring tools perform health checks on |
| haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any |
| commercial load-balancer, and sometimes it will simply be a more complete |
| monitoring system such as Nagios. When the tests are very frequent, users often |
| ask how to disable logging for those checks. There are three possibilities : |
| |
| - if connections come from everywhere and are just TCP probes, it is often |
| desired to simply disable logging of connections without data exchange, by |
| setting "option dontlognull" in the frontend. It also disables logging of |
| port scans, which may or may not be desired. |
| |
| - if the connection come from a known source network, use "monitor-net" to |
| declare this network as monitoring only. Any host in this network will then |
| only be able to perform health checks, and their requests will not be |
| logged. This is generally appropriate to designate a list of equipments |
| such as other load-balancers. |
| |
| - if the tests are performed on a known URI, use "monitor-uri" to declare |
| this URI as dedicated to monitoring. Any host sending this request will |
| only get the result of a health-check, and the request will not be logged. |
| |
| |
| 8.3.2. Logging before waiting for the session to terminate |
| ---------------------------------------------------------- |
| |
| The problem with logging at end of connection is that you have no clue about |
| what is happening during very long sessions, such as remote terminal sessions |
| or large file downloads. This problem can be worked around by specifying |
| "option logasap" in the frontend. Haproxy will then log as soon as possible, |
| just before data transfer begins. This means that in case of TCP, it will still |
| log the connection status to the server, and in case of HTTP, it will log just |
| after processing the server headers. In this case, the number of bytes reported |
| is the number of header bytes sent to the client. In order to avoid confusion |
| with normal logs, the total time field and the number of bytes are prefixed |
| with a '+' sign which means that real numbers are certainly larger. |
| |
| |
| 8.3.3. Raising log level upon errors |
| ------------------------------------ |
| |
| Sometimes it is more convenient to separate normal traffic from errors logs, |
| for instance in order to ease error monitoring from log files. When the option |
| "log-separate-errors" is used, connections which experience errors, timeouts, |
| retries, redispatches or HTTP status codes 5xx will see their syslog level |
| raised from "info" to "err". This will help a syslog daemon store the log in |
| a separate file. It is very important to keep the errors in the normal traffic |
| file too, so that log ordering is not altered. You should also be careful if |
| you already have configured your syslog daemon to store all logs higher than |
| "notice" in an "admin" file, because the "err" level is higher than "notice". |
| |
| |
| 8.3.4. Disabling logging of successful connections |
| -------------------------------------------------- |
| |
| Although this may sound strange at first, some large sites have to deal with |
| multiple thousands of logs per second and are experiencing difficulties keeping |
| them intact for a long time or detecting errors within them. If the option |
| "dontlog-normal" is set on the frontend, all normal connections will not be |
| logged. In this regard, a normal connection is defined as one without any |
| error, timeout, retry nor redispatch. In HTTP, the status code is checked too, |
| and a response with a status 5xx is not considered normal and will be logged |
| too. Of course, doing is is really discouraged as it will remove most of the |
| useful information from the logs. Do this only if you have no other |
| alternative. |
| |
| |
| 8.4. Timing events |
| ------------------ |
| |
| Timers provide a great help in troubleshooting network problems. All values are |
| reported in milliseconds (ms). These timers should be used in conjunction with |
| the session termination flags. In TCP mode with "option tcplog" set on the |
| frontend, 3 control points are reported under the form "Tw/Tc/Tt", and in HTTP |
| mode, 5 control points are reported under the form "Tq/Tw/Tc/Tr/Tt" : |
| |
| - Tq: total time to get the client request (HTTP mode only). It's the time |
| elapsed between the moment the client connection was accepted and the |
| moment the proxy received the last HTTP header. The value "-1" indicates |
| that the end of headers (empty line) has never been seen. This happens when |
| the client closes prematurely or times out. |
| |
| - Tw: total time spent in the queues waiting for a connection slot. It |
| accounts for backend queue as well as the server queues, and depends on the |
| queue size, and the time needed for the server to complete previous |
| requests. The value "-1" means that the request was killed before reaching |
| the queue, which is generally what happens with invalid or denied requests. |
| |
| - Tc: total time to establish the TCP connection to the server. It's the time |
| elapsed between the moment the proxy sent the connection request, and the |
| moment it was acknowledged by the server, or between the TCP SYN packet and |
| the matching SYN/ACK packet in return. The value "-1" means that the |
| connection never established. |
| |
| - Tr: server response time (HTTP mode only). It's the time elapsed between |
| the moment the TCP connection was established to the server and the moment |
| the server sent its complete response headers. It purely shows its request |
| processing time, without the network overhead due to the data transmission. |
| It is worth noting that when the client has data to send to the server, for |
| instance during a POST request, the time already runs, and this can distort |
| apparent response time. For this reason, it's generally wise not to trust |
| too much this field for POST requests initiated from clients behind an |
| untrusted network. A value of "-1" here means that the last the response |
| header (empty line) was never seen, most likely because the server timeout |
| stroke before the server managed to process the request. |
| |
| - Tt: total session duration time, between the moment the proxy accepted it |
| and the moment both ends were closed. The exception is when the "logasap" |
| option is specified. In this case, it only equals (Tq+Tw+Tc+Tr), and is |
| prefixed with a '+' sign. From this field, we can deduce "Td", the data |
| transmission time, by substracting other timers when valid : |
| |
| Td = Tt - (Tq + Tw + Tc + Tr) |
| |
| Timers with "-1" values have to be excluded from this equation. In TCP |
| mode, "Tq" and "Tr" have to be excluded too. Note that "Tt" can never be |
| negative. |
| |
| These timers provide precious indications on trouble causes. Since the TCP |
| protocol defines retransmit delays of 3, 6, 12... seconds, we know for sure |
| that timers close to multiples of 3s are nearly always related to lost packets |
| due to network problems (wires, negotiation, congestion). Moreover, if "Tt" is |
| close to a timeout value specified in the configuration, it often means that a |
| session has been aborted on timeout. |
| |
| Most common cases : |
| |
| - If "Tq" is close to 3000, a packet has probably been lost between the |
| client and the proxy. This is very rare on local networks but might happen |
| when clients are on far remote networks and send large requests. It may |
| happen that values larger than usual appear here without any network cause. |
| Sometimes, during an attack or just after a resource starvation has ended, |
| haproxy may accept thousands of connections in a few milliseconds. The time |
| spent accepting these connections will inevitably slightly delay processing |
| of other connections, and it can happen that request times in the order of |
| a few tens of milliseconds are measured after a few thousands of new |
| connections have been accepted at once. Setting "option http-server-close" |
| may display larger request times since "Tq" also measures the time spent |
| waiting for additional requests. |
| |
| - If "Tc" is close to 3000, a packet has probably been lost between the |
| server and the proxy during the server connection phase. This value should |
| always be very low, such as 1 ms on local networks and less than a few tens |
| of ms on remote networks. |
| |
| - If "Tr" is nearly always lower than 3000 except some rare values which seem |
| to be the average majored by 3000, there are probably some packets lost |
| between the proxy and the server. |
| |
| - If "Tt" is large even for small byte counts, it generally is because |
| neither the client nor the server decides to close the connection, for |
| instance because both have agreed on a keep-alive connection mode. In order |
| to solve this issue, it will be needed to specify "option httpclose" on |
| either the frontend or the backend. If the problem persists, it means that |
| the server ignores the "close" connection mode and expects the client to |
| close. Then it will be required to use "option forceclose". Having the |
| smallest possible 'Tt' is important when connection regulation is used with |
| the "maxconn" option on the servers, since no new connection will be sent |
| to the server until another one is released. |
| |
| Other noticeable HTTP log cases ('xx' means any value to be ignored) : |
| |
| Tq/Tw/Tc/Tr/+Tt The "option logasap" is present on the frontend and the log |
| was emitted before the data phase. All the timers are valid |
| except "Tt" which is shorter than reality. |
| |
| -1/xx/xx/xx/Tt The client was not able to send a complete request in time |
| or it aborted too early. Check the session termination flags |
| then "timeout http-request" and "timeout client" settings. |
| |
| Tq/-1/xx/xx/Tt It was not possible to process the request, maybe because |
| servers were out of order, because the request was invalid |
| or forbidden by ACL rules. Check the session termination |
| flags. |
| |
| Tq/Tw/-1/xx/Tt The connection could not establish on the server. Either it |
| actively refused it or it timed out after Tt-(Tq+Tw) ms. |
| Check the session termination flags, then check the |
| "timeout connect" setting. Note that the tarpit action might |
| return similar-looking patterns, with "Tw" equal to the time |
| the client connection was maintained open. |
| |
| Tq/Tw/Tc/-1/Tt The server has accepted the connection but did not return |
| a complete response in time, or it closed its connexion |
| unexpectedly after Tt-(Tq+Tw+Tc) ms. Check the session |
| termination flags, then check the "timeout server" setting. |
| |
| |
| 8.5. Session state at disconnection |
| ----------------------------------- |
| |
| TCP and HTTP logs provide a session termination indicator in the |
| "termination_state" field, just before the number of active connections. It is |
| 2-characters long in TCP mode, and is extended to 4 characters in HTTP mode, |
| each of which has a special meaning : |
| |
| - On the first character, a code reporting the first event which caused the |
| session to terminate : |
| |
| C : the TCP session was unexpectedly aborted by the client. |
| |
| S : the TCP session was unexpectedly aborted by the server, or the |
| server explicitly refused it. |
| |
| P : the session was prematurely aborted by the proxy, because of a |
| connection limit enforcement, because a DENY filter was matched, |
| because of a security check which detected and blocked a dangerous |
| error in server response which might have caused information leak |
| (eg: cacheable cookie), or because the response was processed by |
| the proxy (redirect, stats, etc...). |
| |
| R : a resource on the proxy has been exhausted (memory, sockets, source |
| ports, ...). Usually, this appears during the connection phase, and |
| system logs should contain a copy of the precise error. If this |
| happens, it must be considered as a very serious anomaly which |
| should be fixed as soon as possible by any means. |
| |
| I : an internal error was identified by the proxy during a self-check. |
| This should NEVER happen, and you are encouraged to report any log |
| containing this, because this would almost certainly be a bug. It |
| would be wise to preventively restart the process after such an |
| event too, in case it would be caused by memory corruption. |
| |
| c : the client-side timeout expired while waiting for the client to |
| send or receive data. |
| |
| s : the server-side timeout expired while waiting for the server to |
| send or receive data. |
| |
| - : normal session completion, both the client and the server closed |
| with nothing left in the buffers. |
| |
| - on the second character, the TCP or HTTP session state when it was closed : |
| |
| R : the proxy was waiting for a complete, valid REQUEST from the client |
| (HTTP mode only). Nothing was sent to any server. |
| |
| Q : the proxy was waiting in the QUEUE for a connection slot. This can |
| only happen when servers have a 'maxconn' parameter set. It can |
| also happen in the global queue after a redispatch consecutive to |
| a failed attempt to connect to a dying server. If no redispatch is |
| reported, then no connection attempt was made to any server. |
| |
| C : the proxy was waiting for the CONNECTION to establish on the |
| server. The server might at most have noticed a connection attempt. |
| |
| H : the proxy was waiting for complete, valid response HEADERS from the |
| server (HTTP only). |
| |
| D : the session was in the DATA phase. |
| |
| L : the proxy was still transmitting LAST data to the client while the |
| server had already finished. This one is very rare as it can only |
| happen when the client dies while receiving the last packets. |
| |
| T : the request was tarpitted. It has been held open with the client |
| during the whole "timeout tarpit" duration or until the client |
| closed, both of which will be reported in the "Tw" timer. |
| |
| - : normal session completion after end of data transfer. |
| |
| - the third character tells whether the persistence cookie was provided by |
| the client (only in HTTP mode) : |
| |
| N : the client provided NO cookie. This is usually the case for new |
| visitors, so counting the number of occurrences of this flag in the |
| logs generally indicate a valid trend for the site frequentation. |
| |
| I : the client provided an INVALID cookie matching no known server. |
| This might be caused by a recent configuration change, mixed |
| cookies between HTTP/HTTPS sites, persistence conditionally |
| ignored, or an attack. |
| |
| D : the client provided a cookie designating a server which was DOWN, |
| so either "option persist" was used and the client was sent to |
| this server, or it was not set and the client was redispatched to |
| another server. |
| |
| V : the client provided a VALID cookie, and was sent to the associated |
| server. |
| |
| E : the client provided a valid cookie, but with a last date which was |
| older than what is allowed by the "maxidle" cookie parameter, so |
| the cookie is consider EXPIRED and is ignored. The request will be |
| redispatched just as if there was no cookie. |
| |
| O : the client provided a valid cookie, but with a first date which was |
| older than what is allowed by the "maxlife" cookie parameter, so |
| the cookie is consider too OLD and is ignored. The request will be |
| redispatched just as if there was no cookie. |
| |
| - : does not apply (no cookie set in configuration). |
| |
| - the last character reports what operations were performed on the persistence |
| cookie returned by the server (only in HTTP mode) : |
| |
| N : NO cookie was provided by the server, and none was inserted either. |
| |
| I : no cookie was provided by the server, and the proxy INSERTED one. |
| Note that in "cookie insert" mode, if the server provides a cookie, |
| it will still be overwritten and reported as "I" here. |
| |
| U : the proxy UPDATED the last date in the cookie that was presented by |
| the client. This can only happen in insert mode with "maxidle". It |
| happens everytime there is activity at a different date than the |
| date indicated in the cookie. If any other change happens, such as |
| a redispatch, then the cookie will be marked as inserted instead. |
| |
| P : a cookie was PROVIDED by the server and transmitted as-is. |
| |
| R : the cookie provided by the server was REWRITTEN by the proxy, which |
| happens in "cookie rewrite" or "cookie prefix" modes. |
| |
| D : the cookie provided by the server was DELETED by the proxy. |
| |
| - : does not apply (no cookie set in configuration). |
| |
| The combination of the two first flags gives a lot of information about what |
| was happening when the session terminated, and why it did terminate. It can be |
| helpful to detect server saturation, network troubles, local system resource |
| starvation, attacks, etc... |
| |
| The most common termination flags combinations are indicated below. They are |
| alphabetically sorted, with the lowercase set just after the upper case for |
| easier finding and understanding. |
| |
| Flags Reason |
| |
| -- Normal termination. |
| |
| CC The client aborted before the connection could be established to the |
| server. This can happen when haproxy tries to connect to a recently |
| dead (or unchecked) server, and the client aborts while haproxy is |
| waiting for the server to respond or for "timeout connect" to expire. |
| |
| CD The client unexpectedly aborted during data transfer. This can be |
| caused by a browser crash, by an intermediate equipment between the |
| client and haproxy which decided to actively break the connection, |
| by network routing issues between the client and haproxy, or by a |
| keep-alive session between the server and the client terminated first |
| by the client. |
| |
| cD The client did not send nor acknowledge any data for as long as the |
| "timeout client" delay. This is often caused by network failures on |
| the client side, or the client simply leaving the net uncleanly. |
| |
| CH The client aborted while waiting for the server to start responding. |
| It might be the server taking too long to respond or the client |
| clicking the 'Stop' button too fast. |
| |
| cH The "timeout client" stroke while waiting for client data during a |
| POST request. This is sometimes caused by too large TCP MSS values |
| for PPPoE networks which cannot transport full-sized packets. It can |
| also happen when client timeout is smaller than server timeout and |
| the server takes too long to respond. |
| |
| CQ The client aborted while its session was queued, waiting for a server |
| with enough empty slots to accept it. It might be that either all the |
| servers were saturated or that the assigned server was taking too |
| long a time to respond. |
| |
| CR The client aborted before sending a full HTTP request. Most likely |
| the request was typed by hand using a telnet client, and aborted |
| too early. The HTTP status code is likely a 400 here. Sometimes this |
| might also be caused by an IDS killing the connection between haproxy |
| and the client. |
| |
| cR The "timeout http-request" stroke before the client sent a full HTTP |
| request. This is sometimes caused by too large TCP MSS values on the |
| client side for PPPoE networks which cannot transport full-sized |
| packets, or by clients sending requests by hand and not typing fast |
| enough, or forgetting to enter the empty line at the end of the |
| request. The HTTP status code is likely a 408 here. |
| |
| CT The client aborted while its session was tarpitted. It is important to |
| check if this happens on valid requests, in order to be sure that no |
| wrong tarpit rules have been written. If a lot of them happen, it |
| might make sense to lower the "timeout tarpit" value to something |
| closer to the average reported "Tw" timer, in order not to consume |
| resources for just a few attackers. |
| |
| SC The server or an equipment between it and haproxy explicitly refused |
| the TCP connection (the proxy received a TCP RST or an ICMP message |
| in return). Under some circumstances, it can also be the network |
| stack telling the proxy that the server is unreachable (eg: no route, |
| or no ARP response on local network). When this happens in HTTP mode, |
| the status code is likely a 502 or 503 here. |
| |
| sC The "timeout connect" stroke before a connection to the server could |
| complete. When this happens in HTTP mode, the status code is likely a |
| 503 or 504 here. |
| |
| SD The connection to the server died with an error during the data |
| transfer. This usually means that haproxy has received an RST from |
| the server or an ICMP message from an intermediate equipment while |
| exchanging data with the server. This can be caused by a server crash |
| or by a network issue on an intermediate equipment. |
| |
| sD The server did not send nor acknowledge any data for as long as the |
| "timeout server" setting during the data phase. This is often caused |
| by too short timeouts on L4 equipments before the server (firewalls, |
| load-balancers, ...), as well as keep-alive sessions maintained |
| between the client and the server expiring first on haproxy. |
| |
| SH The server aborted before sending its full HTTP response headers, or |
| it crashed while processing the request. Since a server aborting at |
| this moment is very rare, it would be wise to inspect its logs to |
| control whether it crashed and why. The logged request may indicate a |
| small set of faulty requests, demonstrating bugs in the application. |
| Sometimes this might also be caused by an IDS killing the connection |
| between haproxy and the server. |
| |
| sH The "timeout server" stroke before the server could return its |
| response headers. This is the most common anomaly, indicating too |
| long transactions, probably caused by server or database saturation. |
| The immediate workaround consists in increasing the "timeout server" |
| setting, but it is important to keep in mind that the user experience |
| will suffer from these long response times. The only long term |
| solution is to fix the application. |
| |
| sQ The session spent too much time in queue and has been expired. See |
| the "timeout queue" and "timeout connect" settings to find out how to |
| fix this if it happens too often. If it often happens massively in |
| short periods, it may indicate general problems on the affected |
| servers due to I/O or database congestion, or saturation caused by |
| external attacks. |
| |
| PC The proxy refused to establish a connection to the server because the |
| process' socket limit has been reached while attempting to connect. |
| The global "maxconn" parameter may be increased in the configuration |
| so that it does not happen anymore. This status is very rare and |
| might happen when the global "ulimit-n" parameter is forced by hand. |
| |
| PD The proxy blocked an incorrectly formatted chunked encoded message in |
| a request or a response, after the server has emitted its headers. In |
| most cases, this will indicate an invalid message from the server to |
| the client. |
| |
| PH The proxy blocked the server's response, because it was invalid, |
| incomplete, dangerous (cache control), or matched a security filter. |
| In any case, an HTTP 502 error is sent to the client. One possible |
| cause for this error is an invalid syntax in an HTTP header name |
| containing unauthorized characters. It is also possible but quite |
| rare, that the proxy blocked a chunked-encoding request from the |
| client due to an invalid syntax, before the server responded. In this |
| case, an HTTP 400 error is sent to the client and reported in the |
| logs. |
| |
| PR The proxy blocked the client's HTTP request, either because of an |
| invalid HTTP syntax, in which case it returned an HTTP 400 error to |
| the client, or because a deny filter matched, in which case it |
| returned an HTTP 403 error. |
| |
| PT The proxy blocked the client's request and has tarpitted its |
| connection before returning it a 500 server error. Nothing was sent |
| to the server. The connection was maintained open for as long as |
| reported by the "Tw" timer field. |
| |
| RC A local resource has been exhausted (memory, sockets, source ports) |
| preventing the connection to the server from establishing. The error |
| logs will tell precisely what was missing. This is very rare and can |
| only be solved by proper system tuning. |
| |
| The combination of the two last flags gives a lot of information about how |
| persistence was handled by the client, the server and by haproxy. This is very |
| important to troubleshoot disconnections, when users complain they have to |
| re-authenticate. The commonly encountered flags are : |
| |
| -- Persistence cookie is not enabled. |
| |
| NN No cookie was provided by the client, none was inserted in the |
| response. For instance, this can be in insert mode with "postonly" |
| set on a GET request. |
| |
| II A cookie designating an invalid server was provided by the client, |
| a valid one was inserted in the response. This typically happens when |
| a "server" entry is removed from the configuraton, since its cookie |
| value can be presented by a client when no other server knows it. |
| |
| NI No cookie was provided by the client, one was inserted in the |
| response. This typically happens for first requests from every user |
| in "insert" mode, which makes it an easy way to count real users. |
| |
| VN A cookie was provided by the client, none was inserted in the |
| response. This happens for most responses for which the client has |
| already got a cookie. |
| |
| VU A cookie was provided by the client, with a last visit date which is |
| not completely up-to-date, so an updated cookie was provided in |
| response. This can also happen if there was no date at all, or if |
| there was a date but the "maxidle" parameter was not set, so that the |
| cookie can be switched to unlimited time. |
| |
| EI A cookie was provided by the client, with a last visit date which is |
| too old for the "maxidle" parameter, so the cookie was ignored and a |
| new cookie was inserted in the response. |
| |
| OI A cookie was provided by the client, with a first visit date which is |
| too old for the "maxlife" parameter, so the cookie was ignored and a |
| new cookie was inserted in the response. |
| |
| DI The server designated by the cookie was down, a new server was |
| selected and a new cookie was emitted in the response. |
| |
| VI The server designated by the cookie was not marked dead but could not |
| be reached. A redispatch happened and selected another one, which was |
| then advertised in the response. |
| |
| |
| 8.6. Non-printable characters |
| ----------------------------- |
| |
| In order not to cause trouble to log analysis tools or terminals during log |
| consulting, non-printable characters are not sent as-is into log files, but are |
| converted to the two-digits hexadecimal representation of their ASCII code, |
| prefixed by the character '#'. The only characters that can be logged without |
| being escaped are comprised between 32 and 126 (inclusive). Obviously, the |
| escape character '#' itself is also encoded to avoid any ambiguity ("#23"). It |
| is the same for the character '"' which becomes "#22", as well as '{', '|' and |
| '}' when logging headers. |
| |
| Note that the space character (' ') is not encoded in headers, which can cause |
| issues for tools relying on space count to locate fields. A typical header |
| containing spaces is "User-Agent". |
| |
| Last, it has been observed that some syslog daemons such as syslog-ng escape |
| the quote ('"') with a backslash ('\'). The reverse operation can safely be |
| performed since no quote may appear anywhere else in the logs. |
| |
| |
| 8.7. Capturing HTTP cookies |
| --------------------------- |
| |
| Cookie capture simplifies the tracking a complete user session. This can be |
| achieved using the "capture cookie" statement in the frontend. Please refer to |
| section 4.2 for more details. Only one cookie can be captured, and the same |
| cookie will simultaneously be checked in the request ("Cookie:" header) and in |
| the response ("Set-Cookie:" header). The respective values will be reported in |
| the HTTP logs at the "captured_request_cookie" and "captured_response_cookie" |
| locations (see section 8.2.3 about HTTP log format). When either cookie is |
| not seen, a dash ('-') replaces the value. This way, it's easy to detect when a |
| user switches to a new session for example, because the server will reassign it |
| a new cookie. It is also possible to detect if a server unexpectedly sets a |
| wrong cookie to a client, leading to session crossing. |
| |
| Examples : |
| # capture the first cookie whose name starts with "ASPSESSION" |
| capture cookie ASPSESSION len 32 |
| |
| # capture the first cookie whose name is exactly "vgnvisitor" |
| capture cookie vgnvisitor= len 32 |
| |
| |
| 8.8. Capturing HTTP headers |
| --------------------------- |
| |
| Header captures are useful to track unique request identifiers set by an upper |
| proxy, virtual host names, user-agents, POST content-length, referrers, etc. In |
| the response, one can search for information about the response length, how the |
| server asked the cache to behave, or an object location during a redirection. |
| |
| Header captures are performed using the "capture request header" and "capture |
| response header" statements in the frontend. Please consult their definition in |
| section 4.2 for more details. |
| |
| It is possible to include both request headers and response headers at the same |
| time. Non-existent headers are logged as empty strings, and if one header |
| appears more than once, only its last occurrence will be logged. Request headers |
| are grouped within braces '{' and '}' in the same order as they were declared, |
| and delimited with a vertical bar '|' without any space. Response headers |
| follow the same representation, but are displayed after a space following the |
| request headers block. These blocks are displayed just before the HTTP request |
| in the logs. |
| |
| Example : |
| # This instance chains to the outgoing proxy |
| listen proxy-out |
| mode http |
| option httplog |
| option logasap |
| log global |
| server cache1 192.168.1.1:3128 |
| |
| # log the name of the virtual server |
| capture request header Host len 20 |
| |
| # log the amount of data uploaded during a POST |
| capture request header Content-Length len 10 |
| |
| # log the beginning of the referrer |
| capture request header Referer len 20 |
| |
| # server name (useful for outgoing proxies only) |
| capture response header Server len 20 |
| |
| # logging the content-length is useful with "option logasap" |
| capture response header Content-Length len 10 |
| |
| # log the expected cache behaviour on the response |
| capture response header Cache-Control len 8 |
| |
| # the Via header will report the next proxy's name |
| capture response header Via len 20 |
| |
| # log the URL location during a redirection |
| capture response header Location len 20 |
| |
| >>> Aug 9 20:26:09 localhost \ |
| haproxy[2022]: 127.0.0.1:34014 [09/Aug/2004:20:26:09] proxy-out \ |
| proxy-out/cache1 0/0/0/162/+162 200 +350 - - ---- 0/0/0/0/0 0/0 \ |
| {fr.adserver.yahoo.co||http://fr.f416.mail.} {|864|private||} \ |
| "GET http://fr.adserver.yahoo.com/" |
| |
| >>> Aug 9 20:30:46 localhost \ |
| haproxy[2022]: 127.0.0.1:34020 [09/Aug/2004:20:30:46] proxy-out \ |
| proxy-out/cache1 0/0/0/182/+182 200 +279 - - ---- 0/0/0/0/0 0/0 \ |
| {w.ods.org||} {Formilux/0.1.8|3495|||} \ |
| "GET http://trafic.1wt.eu/ HTTP/1.1" |
| |
| >>> Aug 9 20:30:46 localhost \ |
| haproxy[2022]: 127.0.0.1:34028 [09/Aug/2004:20:30:46] proxy-out \ |
| proxy-out/cache1 0/0/2/126/+128 301 +223 - - ---- 0/0/0/0/0 0/0 \ |
| {www.sytadin.equipement.gouv.fr||http://trafic.1wt.eu/} \ |
| {Apache|230|||http://www.sytadin.} \ |
| "GET http://www.sytadin.equipement.gouv.fr/ HTTP/1.1" |
| |
| |
| 8.9. Examples of logs |
| --------------------- |
| |
| These are real-world examples of logs accompanied with an explanation. Some of |
| them have been made up by hand. The syslog part has been removed for better |
| reading. Their sole purpose is to explain how to decipher them. |
| |
| >>> haproxy[674]: 127.0.0.1:33318 [15/Oct/2003:08:31:57.130] px-http \ |
| px-http/srv1 6559/0/7/147/6723 200 243 - - ---- 5/3/3/1/0 0/0 \ |
| "HEAD / HTTP/1.0" |
| |
| => long request (6.5s) entered by hand through 'telnet'. The server replied |
| in 147 ms, and the session ended normally ('----') |
| |
| >>> haproxy[674]: 127.0.0.1:33319 [15/Oct/2003:08:31:57.149] px-http \ |
| px-http/srv1 6559/1230/7/147/6870 200 243 - - ---- 324/239/239/99/0 \ |
| 0/9 "HEAD / HTTP/1.0" |
| |
| => Idem, but the request was queued in the global queue behind 9 other |
| requests, and waited there for 1230 ms. |
| |
| >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.654] px-http \ |
| px-http/srv1 9/0/7/14/+30 200 +243 - - ---- 3/3/3/1/0 0/0 \ |
| "GET /image.iso HTTP/1.0" |
| |
| => request for a long data transfer. The "logasap" option was specified, so |
| the log was produced just before transferring data. The server replied in |
| 14 ms, 243 bytes of headers were sent to the client, and total time from |
| accept to first data byte is 30 ms. |
| |
| >>> haproxy[674]: 127.0.0.1:33320 [15/Oct/2003:08:32:17.925] px-http \ |
| px-http/srv1 9/0/7/14/30 502 243 - - PH-- 3/2/2/0/0 0/0 \ |
| "GET /cgi-bin/bug.cgi? HTTP/1.0" |
| |
| => the proxy blocked a server response either because of an "rspdeny" or |
| "rspideny" filter, or because the response was improperly formatted and |
| not HTTP-compliant, or because it blocked sensible information which |
| risked being cached. In this case, the response is replaced with a "502 |
| bad gateway". The flags ("PH--") tell us that it was haproxy who decided |
| to return the 502 and not the server. |
| |
| >>> haproxy[18113]: 127.0.0.1:34548 [15/Oct/2003:15:18:55.798] px-http \ |
| px-http/<NOSRV> -1/-1/-1/-1/8490 -1 0 - - CR-- 2/2/2/0/0 0/0 "" |
| |
| => the client never completed its request and aborted itself ("C---") after |
| 8.5s, while the proxy was waiting for the request headers ("-R--"). |
| Nothing was sent to any server. |
| |
| >>> haproxy[18113]: 127.0.0.1:34549 [15/Oct/2003:15:19:06.103] px-http \ |
| px-http/<NOSRV> -1/-1/-1/-1/50001 408 0 - - cR-- 2/2/2/0/0 0/0 "" |
| |
| => The client never completed its request, which was aborted by the |
| time-out ("c---") after 50s, while the proxy was waiting for the request |
| headers ("-R--"). Nothing was sent to any server, but the proxy could |
| send a 408 return code to the client. |
| |
| >>> haproxy[18989]: 127.0.0.1:34550 [15/Oct/2003:15:24:28.312] px-tcp \ |
| px-tcp/srv1 0/0/5007 0 cD 0/0/0/0/0 0/0 |
| |
| => This log was produced with "option tcplog". The client timed out after |
| 5 seconds ("c----"). |
| |
| >>> haproxy[18989]: 10.0.0.1:34552 [15/Oct/2003:15:26:31.462] px-http \ |
| px-http/srv1 3183/-1/-1/-1/11215 503 0 - - SC-- 205/202/202/115/3 \ |
| 0/0 "HEAD / HTTP/1.0" |
| |
| => The request took 3s to complete (probably a network problem), and the |
| connection to the server failed ('SC--') after 4 attempts of 2 seconds |
| (config says 'retries 3'), and no redispatch (otherwise we would have |
| seen "/+3"). Status code 503 was returned to the client. There were 115 |
| connections on this server, 202 connections on this proxy, and 205 on |
| the global process. It is possible that the server refused the |
| connection because of too many already established. |
| |
| |
| 9. Statistics and monitoring |
| ---------------------------- |
| |
| It is possible to query HAProxy about its status. The most commonly used |
| mechanism is the HTTP statistics page. This page also exposes an alternative |
| CSV output format for monitoring tools. The same format is provided on the |
| Unix socket. |
| |
| |
| 9.1. CSV format |
| --------------- |
| |
| The statistics may be consulted either from the unix socket or from the HTTP |
| page. Both means provide a CSV format whose fields follow. |
| |
| 0. pxname: proxy name |
| 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name |
| for server) |
| 2. qcur: current queued requests |
| 3. qmax: max queued requests |
| 4. scur: current sessions |
| 5. smax: max sessions |
| 6. slim: sessions limit |
| 7. stot: total sessions |
| 8. bin: bytes in |
| 9. bout: bytes out |
| 10. dreq: denied requests |
| 11. dresp: denied responses |
| 12. ereq: request errors |
| 13. econ: connection errors |
| 14. eresp: response errors (among which srv_abrt) |
| 15. wretr: retries (warning) |
| 16. wredis: redispatches (warning) |
| 17. status: status (UP/DOWN/NOLB/MAINT/MAINT(via)...) |
| 18. weight: server weight (server), total weight (backend) |
| 19. act: server is active (server), number of active servers (backend) |
| 20. bck: server is backup (server), number of backup servers (backend) |
| 21. chkfail: number of failed checks |
| 22. chkdown: number of UP->DOWN transitions |
| 23. lastchg: last status change (in seconds) |
| 24. downtime: total downtime (in seconds) |
| 25. qlimit: queue limit |
| 26. pid: process id (0 for first instance, 1 for second, ...) |
| 27. iid: unique proxy id |
| 28. sid: service id (unique inside a proxy) |
| 29. throttle: warm up status |
| 30. lbtot: total number of times a server was selected |
| 31. tracked: id of proxy/server if tracking is enabled |
| 32. type (0=frontend, 1=backend, 2=server, 3=socket) |
| 33. rate: number of sessions per second over last elapsed second |
| 34. rate_lim: limit on new sessions per second |
| 35. rate_max: max number of new sessions per second |
| 36. check_status: status of last health check, one of: |
| UNK -> unknown |
| INI -> initializing |
| SOCKERR -> socket error |
| L4OK -> check passed on layer 4, no upper layers testing enabled |
| L4TMOUT -> layer 1-4 timeout |
| L4CON -> layer 1-4 connection problem, for example |
| "Connection refused" (tcp rst) or "No route to host" (icmp) |
| L6OK -> check passed on layer 6 |
| L6TOUT -> layer 6 (SSL) timeout |
| L6RSP -> layer 6 invalid response - protocol error |
| L7OK -> check passed on layer 7 |
| L7OKC -> check conditionally passed on layer 7, for example 404 with |
| disable-on-404 |
| L7TOUT -> layer 7 (HTTP/SMTP) timeout |
| L7RSP -> layer 7 invalid response - protocol error |
| L7STS -> layer 7 response error, for example HTTP 5xx |
| 37. check_code: layer5-7 code, if available |
| 38. check_duration: time in ms took to finish last health check |
| 39. hrsp_1xx: http responses with 1xx code |
| 40. hrsp_2xx: http responses with 2xx code |
| 41. hrsp_3xx: http responses with 3xx code |
| 42. hrsp_4xx: http responses with 4xx code |
| 43. hrsp_5xx: http responses with 5xx code |
| 44. hrsp_other: http responses with other codes (protocol error) |
| 45. hanafail: failed health checks details |
| 46. req_rate: HTTP requests per second over last elapsed second |
| 47. req_rate_max: max number of HTTP requests per second observed |
| 48. req_tot: total number of HTTP requests received |
| 49. cli_abrt: number of data transfers aborted by the client |
| 50. srv_abrt: number of data transfers aborted by the server (inc. in eresp) |
| |
| |
| 9.2. Unix Socket commands |
| ------------------------- |
| |
| The following commands are supported on the UNIX stats socket ; all of them |
| must be terminated by a line feed. The socket supports pipelining, so that it |
| is possible to chain multiple commands at once provided they are delimited by |
| a semi-colon or a line feed, although the former is more reliable as it has no |
| risk of being truncated over the network. The responses themselves will each be |
| followed by an empty line, so it will be easy for an external script to match a |
| given response with a given request. By default one command line is processed |
| then the connection closes, but there is an interactive allowing multiple lines |
| to be issued one at a time. |
| |
| It is important to understand that when multiple haproxy processes are started |
| on the same sockets, any process may pick up the request and will output its |
| own stats. |
| |
| clear counters |
| Clear the max values of the statistics counters in each proxy (frontend & |
| backend) and in each server. The cumulated counters are not affected. This |
| can be used to get clean counters after an incident, without having to |
| restart nor to clear traffic counters. This command is restricted and can |
| only be issued on sockets configured for levels "operator" or "admin". |
| |
| clear counters all |
| Clear all statistics counters in each proxy (frontend & backend) and in each |
| server. This has the same effect as restarting. This command is restricted |
| and can only be issued on sockets configured for level "admin". |
| |
| clear table <table> key <key> |
| Remove entry <key> from the stick-table <table>. The key must be of the same |
| type as the table, which currently is limited to IPv4. This is typically used |
| un unblock some users complaining they have been abusively denied access to a |
| service, but this can also be used to clear some stickiness entries matching |
| a server that is going to be replaced (see "show table" below for details). |
| Note that sometimes, removal of a key will be refused because it is currently |
| tracked by a session. Retrying a few seconds later after the session ends is |
| usuall enough. |
| |
| Example : |
| $ echo "show table http_proxy" | socat stdio /tmp/sock1 |
| >>> # table: http_proxy, type: ip, size:204800, used:2 |
| >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \ |
| bytes_out_rate(60000)=187 |
| >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| bytes_out_rate(60000)=191 |
| |
| $ echo "clear table http_proxy key 127.0.0.1" | socat stdio /tmp/sock1 |
| |
| $ echo "show table http_proxy" | socat stdio /tmp/sock1 |
| >>> # table: http_proxy, type: ip, size:204800, used:1 |
| >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| bytes_out_rate(60000)=191 |
| |
| disable server <backend>/<server> |
| Mark the server DOWN for maintenance. In this mode, no more checks will be |
| performed on the server until it leaves maintenance. |
| If the server is tracked by other servers, those servers will be set to DOWN |
| during the maintenance. |
| |
| In the statistics page, a server DOWN for maintenance will appear with a |
| "MAINT" status, its tracking servers with the "MAINT(via)" one. |
| |
| Both the backend and the server may be specified either by their name or by |
| their numeric ID, prefixed with a dash ('#'). |
| |
| This command is restricted and can only be issued on sockets configured for |
| level "admin". |
| |
| enable server <backend>/<server> |
| If the server was previously marked as DOWN for maintenance, this marks the |
| server UP and checks are re-enabled. |
| |
| Both the backend and the server may be specified either by their name or by |
| their numeric ID, prefixed with a dash ('#'). |
| |
| This command is restricted and can only be issued on sockets configured for |
| level "admin". |
| |
| get weight <backend>/<server> |
| Report the current weight and the initial weight of server <server> in |
| backend <backend> or an error if either doesn't exist. The initial weight is |
| the one that appears in the configuration file. Both are normally equal |
| unless the current weight has been changed. Both the backend and the server |
| may be specified either by their name or by their numeric ID, prefixed with a |
| dash ('#'). |
| |
| help |
| Print the list of known keywords and their basic usage. The same help screen |
| is also displayed for unknown commands. |
| |
| prompt |
| Toggle the prompt at the beginning of the line and enter or leave interactive |
| mode. In interactive mode, the connection is not closed after a command |
| completes. Instead, the prompt will appear again, indicating the user that |
| the interpreter is waiting for a new command. The prompt consists in a right |
| angle bracket followed by a space "> ". This mode is particularly convenient |
| when one wants to periodically check information such as stats or errors. |
| It is also a good idea to enter interactive mode before issuing a "help" |
| command. |
| |
| quit |
| Close the connection when in interactive mode. |
| |
| set timeout cli <delay> |
| Change the CLI interface timeout for current connection. This can be useful |
| during long debugging sessions where the user needs to constantly inspect |
| some indicators without being disconnected. The delay is passed in seconds. |
| |
| set weight <backend>/<server> <weight>[%] |
| Change a server's weight to the value passed in argument. If the value ends |
| with the '%' sign, then the new weight will be relative to the initially |
| configured weight. Relative weights are only permitted between 0 and 100%, |
| and absolute weights are permitted between 0 and 256. Servers which are part |
| of a farm running a static load-balancing algorithm have stricter limitations |
| because the weight cannot change once set. Thus for these servers, the only |
| accepted values are 0 and 100% (or 0 and the initial weight). Changes take |
| effect immediately, though certain LB algorithms require a certain amount of |
| requests to consider changes. A typical usage of this command is to disable |
| a server during an update by setting its weight to zero, then to enable it |
| again after the update by setting it back to 100%. This command is restricted |
| and can only be issued on sockets configured for level "admin". Both the |
| backend and the server may be specified either by their name or by their |
| numeric ID, prefixed with a dash ('#'). |
| |
| show errors [<iid>] |
| Dump last known request and response errors collected by frontends and |
| backends. If <iid> is specified, the limit the dump to errors concerning |
| either frontend or backend whose ID is <iid>. This command is restricted |
| and can only be issued on sockets configured for levels "operator" or |
| "admin". |
| |
| The errors which may be collected are the last request and response errors |
| caused by protocol violations, often due to invalid characters in header |
| names. The report precisely indicates what exact character violated the |
| protocol. Other important information such as the exact date the error was |
| detected, frontend and backend names, the server name (when known), the |
| internal session ID and the source address which has initiated the session |
| are reported too. |
| |
| All characters are returned, and non-printable characters are encoded. The |
| most common ones (\t = 9, \n = 10, \r = 13 and \e = 27) are encoded as one |
| letter following a backslash. The backslash itself is encoded as '\\' to |
| avoid confusion. Other non-printable characters are encoded '\xNN' where |
| NN is the two-digits hexadecimal representation of the character's ASCII |
| code. |
| |
| Lines are prefixed with the position of their first character, starting at 0 |
| for the beginning of the buffer. At most one input line is printed per line, |
| and large lines will be broken into multiple consecutive output lines so that |
| the output never goes beyond 79 characters wide. It is easy to detect if a |
| line was broken, because it will not end with '\n' and the next line's offset |
| will be followed by a '+' sign, indicating it is a continuation of previous |
| line. |
| |
| Example : |
| $ echo "show errors" | socat stdio /tmp/sock1 |
| >>> [04/Mar/2009:15:46:56.081] backend http-in (#2) : invalid response |
| src 127.0.0.1, session #54, frontend fe-eth0 (#1), server s2 (#1) |
| response length 213 bytes, error at position 23: |
| |
| 00000 HTTP/1.0 200 OK\r\n |
| 00017 header/bizarre:blah\r\n |
| 00038 Location: blah\r\n |
| 00054 Long-line: this is a very long line which should b |
| 00104+ e broken into multiple lines on the output buffer, |
| 00154+ otherwise it would be too large to print in a ter |
| 00204+ minal\r\n |
| 00211 \r\n |
| |
| In the example above, we see that the backend "http-in" which has internal |
| ID 2 has blocked an invalid response from its server s2 which has internal |
| ID 1. The request was on session 54 initiated by source 127.0.0.1 and |
| received by frontend fe-eth0 whose ID is 1. The total response length was |
| 213 bytes when the error was detected, and the error was at byte 23. This |
| is the slash ('/') in header name "header/bizarre", which is not a valid |
| HTTP character for a header name. |
| |
| show info |
| Dump info about haproxy status on current process. |
| |
| show sess |
| Dump all known sessions. Avoid doing this on slow connections as this can |
| be huge. This command is restricted and can only be issued on sockets |
| configured for levels "operator" or "admin". |
| |
| show sess <id> |
| Display a lot of internal information about the specified session identifier. |
| This identifier is the first field at the beginning of the lines in the dumps |
| of "show sess" (it corresponds to the session pointer). Those information are |
| useless to most users but may be used by haproxy developers to troubleshoot a |
| complex bug. The output format is intentionally not documented so that it can |
| freely evolve depending on demands. |
| |
| show stat [<iid> <type> <sid>] |
| Dump statistics in the CSV format. By passing <id>, <type> and <sid>, it is |
| possible to dump only selected items : |
| - <iid> is a proxy ID, -1 to dump everything |
| - <type> selects the type of dumpable objects : 1 for frontends, 2 for |
| backends, 4 for servers, -1 for everything. These values can be ORed, |
| for example: |
| 1 + 2 = 3 -> frontend + backend. |
| 1 + 2 + 4 = 7 -> frontend + backend + server. |
| - <sid> is a server ID, -1 to dump everything from the selected proxy. |
| |
| Example : |
| $ echo "show info;show stat" | socat stdio unix-connect:/tmp/sock1 |
| >>> Name: HAProxy |
| Version: 1.4-dev2-49 |
| Release_date: 2009/09/23 |
| Nbproc: 1 |
| Process_num: 1 |
| (...) |
| |
| # pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,dreq, (...) |
| stats,FRONTEND,,,0,0,1000,0,0,0,0,0,0,,,,,OPEN,,,,,,,,,1,1,0, (...) |
| stats,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,0,0,0,,0,250,(...) |
| (...) |
| www1,BACKEND,0,0,0,0,1000,0,0,0,0,0,,0,0,0,0,UP,1,1,0,,0,250, (...) |
| |
| $ |
| |
| Here, two commands have been issued at once. That way it's easy to find |
| which process the stats apply to in multi-process mode. Notice the empty |
| line after the information output which marks the end of the first block. |
| A similar empty line appears at the end of the second block (stats) so that |
| the reader knows the output has not been truncated. |
| |
| show table |
| Dump general information on all known stick-tables. Their name is returned |
| (the name of the proxy which holds them), their type (currently zero, always |
| IP), their size in maximum possible number of entries, and the number of |
| entries currently in use. |
| |
| Example : |
| $ echo "show table" | socat stdio /tmp/sock1 |
| >>> # table: front_pub, type: 0, size:204800, used:171454 |
| >>> # table: back_rdp, type: 0, size:204800, used:0 |
| |
| show table <name> [ data.<type> <operator> <value> ] |
| Dump contents of stick-table <name>. In this mode, a first line of generic |
| information about the table is reported as with "show table", then all |
| entries are dumped. Since this can be quite heavy, it is possible to specify |
| a filter in order to specify what entries to display. The filter then applies |
| to the stored data (see "stick-table" in section 4.2). One stored data type |
| has to be specified in <type>, and this data type must be stored in the table |
| otherwise an error is reported. The data is compared according to <operator> |
| with the 64-bit integer <value>. Operators are the same as with the ACLs : |
| - eq : match entries whose data is equal to this value |
| - ne : match entries whose data is not equal to this value |
| - le : match entries whose data is less than or equal to this value |
| - ge : match entries whose data is greater than or equal to this value |
| - lt : match entries whose data is less than this value |
| - gt : match entries whose data is greater than this value |
| |
| Example : |
| $ echo "show table http_proxy" | socat stdio /tmp/sock1 |
| >>> # table: http_proxy, type: 0, size:204800, used:2 |
| >>> 0x80e6a4c: key=127.0.0.1 use=0 exp=3594729 gpc0=0 conn_rate(30000)=1 \ |
| bytes_out_rate(60000)=187 |
| >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| bytes_out_rate(60000)=191 |
| |
| $ echo "show table http_proxy data.gpc0 gt 0" | socat stdio /tmp/sock1 |
| >>> # table: http_proxy, type: 0, size:204800, used:2 |
| >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| bytes_out_rate(60000)=191 |
| |
| $ echo "show table http_proxy data.conn_rate gt 5" | \ |
| socat stdio /tmp/sock1 |
| >>> # table: http_proxy, type: 0, size:204800, used:2 |
| >>> 0x80e6a80: key=127.0.0.2 use=0 exp=3594740 gpc0=1 conn_rate(30000)=10 \ |
| bytes_out_rate(60000)=191 |
| |
| When the data criterion applies to a dynamic value dependent on time such as |
| a bytes rate, the value is dynamically computed during the evaluation of the |
| entry in order to decide whether it has to be dumped or not. This means that |
| such a filter could match for some time then not match anymore because as |
| time goes, the average event rate drops. |
| |
| It is possible to use this to extract lists of IP addresses abusing the |
| service, in order to monitor them or even blacklist them in a firewall. |
| Example : |
| $ echo "show table http_proxy data.gpc0 gt 0" \ |
| | socat stdio /tmp/sock1 \ |
| | fgrep 'key=' | cut -d' ' -f2 | cut -d= -f2 > abusers-ip.txt |
| ( or | awk '/key/{ print a[split($2,a,"=")]; }' ) |
| |
| /* |
| * Local variables: |
| * fill-column: 79 |
| * End: |
| */ |