| ---------------------- |
| HAProxy |
| Configuration Manual |
| ---------------------- |
| version 1.6 |
| willy tarreau |
| 2015/06/17 |
| |
| |
| This document covers the configuration language as implemented in the version |
| specified above. It does not provide any hint, example or advice. For such |
| documentation, please refer to the Reference Manual or the Architecture Manual. |
| The summary below is meant to help you search sections by name and navigate |
| through the document. |
| |
| Note to documentation contributors : |
| This document is formatted with 80 columns per line, with even number of |
| spaces for indentation and without tabs. Please follow these rules strictly |
| so that it remains easily printable everywhere. If a line needs to be |
| printed verbatim and does not fit, please end each line with a backslash |
| ('\') and continue on next line, indented by two characters. It is also |
| sometimes useful to prefix all output lines (logs, console outs) with 3 |
| closing angle brackets ('>>>') in order to help get the difference between |
| inputs and outputs when it can become ambiguous. If you add sections, |
| please update the summary below for easier searching. |
| |
| |
| Summary |
| ------- |
| |
| 1. Quick reminder about HTTP |
| 1.1. The HTTP transaction model |
| 1.2. HTTP request |
| 1.2.1. The Request line |
| 1.2.2. The request headers |
| 1.3. HTTP response |
| 1.3.1. The Response line |
| 1.3.2. The response headers |
| |
| 2. Configuring HAProxy |
| 2.1. Configuration file format |
| 2.2. Quoting and escaping |
| 2.3. Environment variables |
| 2.4. Time format |
| 2.5. Examples |
| |
| 3. Global parameters |
| 3.1. Process management and security |
| 3.2. Performance tuning |
| 3.3. Debugging |
| 3.4. Userlists |
| 3.5. Peers |
| |
| 4. Proxies |
| 4.1. Proxy keywords matrix |
| 4.2. Alphabetically sorted keywords reference |
| |
| 5. Bind and Server options |
| 5.1. Bind options |
| 5.2. Server and default-server options |
| 5.3. Server DNS resolution |
| 5.3.1. Global overview |
| 5.3.2. The resolvers section |
| |
| 6. HTTP header manipulation |
| |
| 7. Using ACLs and fetching samples |
| 7.1. ACL basics |
| 7.1.1. Matching booleans |
| 7.1.2. Matching integers |
| 7.1.3. Matching strings |
| 7.1.4. Matching regular expressions (regexes) |
| 7.1.5. Matching arbitrary data blocks |
| 7.1.6. Matching IPv4 and IPv6 addresses |
| 7.2. Using ACLs to form conditions |
| 7.3. Fetching samples |
| 7.3.1. Converters |
| 7.3.2. Fetching samples from internal states |
| 7.3.3. Fetching samples at Layer 4 |
| 7.3.4. Fetching samples at Layer 5 |
| 7.3.5. Fetching samples from buffer contents (Layer 6) |
| 7.3.6. Fetching HTTP samples (Layer 7) |
| 7.4. Pre-defined ACLs |
| |
| 8. Logging |
| 8.1. Log levels |
| 8.2. Log formats |
| 8.2.1. Default log format |
| 8.2.2. TCP log format |
| 8.2.3. HTTP log format |
| 8.2.4. Custom log format |
| 8.2.5. Error 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 keep-alive mode with regards to persistent |
| connections: for each connection it processes each request and response, and |
| leaves the connection idle on both sides between the end of a response and the |
| start of a new request. |
| |
| HAProxy supports 5 connection modes : |
| - keep alive : all requests and responses are processed (default) |
| - tunnel : only the first request and response are processed, |
| everything else is forwarded with no analysis. |
| - passive close : tunnel with "Connection: close" added in both directions. |
| - server close : the server-facing connection is closed after the response. |
| - forced close : the connection is actively closed after end of response. |
| |
| |
| 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 |
| 307 when performing a redirection, depending on the configured code |
| 308 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. |
| |
| |
| 2.2. Quoting and escaping |
| ------------------------- |
| |
| HAProxy's configuration introduces a quoting and escaping system similar to |
| many programming languages. The configuration file supports 3 types: escaping |
| with a backslash, weak quoting with double quotes, and strong quoting with |
| single quotes. |
| |
| If spaces have to be entered in strings, then they must be escaped by preceding |
| them by a backslash ('\') or by quoting them. Backslashes also have to be |
| escaped by doubling or strong quoting them. |
| |
| Escaping is achieved by preceding a special character by a backslash ('\'): |
| |
| \ to mark a space and differentiate it from a delimiter |
| \# to mark a hash and differentiate it from a comment |
| \\ to use a backslash |
| \' to use a single quote and differentiate it from strong quoting |
| \" to use a double quote and differentiate it from weak quoting |
| |
| Weak quoting is achieved by using double quotes (""). Weak quoting prevents |
| the interpretation of: |
| |
| space as a parameter separator |
| ' single quote as a strong quoting delimiter |
| # hash as a comment start |
| |
| Weak quoting permits the interpretation of variables, if you want to use a non |
| -interpreted dollar within a double quoted string, you should escape it with a |
| backslash ("\$"), it does not work outside weak quoting. |
| |
| Interpretation of escaping and special characters are not prevented by weak |
| quoting. |
| |
| Strong quoting is achieved by using single quotes (''). Inside single quotes, |
| nothing is interpreted, it's the efficient way to quote regexes. |
| |
| Quoted and escaped strings are replaced in memory by their interpreted |
| equivalent, it allows you to perform concatenation. |
| |
| Example: |
| # those are equivalents: |
| log-format %{+Q}o\ %t\ %s\ %{-Q}r |
| log-format "%{+Q}o %t %s %{-Q}r" |
| log-format '%{+Q}o %t %s %{-Q}r' |
| log-format "%{+Q}o %t"' %s %{-Q}r' |
| log-format "%{+Q}o %t"' %s'\ %{-Q}r |
| |
| # those are equivalents: |
| reqrep "^([^\ :]*)\ /static/(.*)" \1\ /\2 |
| reqrep "^([^ :]*)\ /static/(.*)" '\1 /\2' |
| reqrep "^([^ :]*)\ /static/(.*)" "\1 /\2" |
| reqrep "^([^ :]*)\ /static/(.*)" "\1\ /\2" |
| |
| |
| 2.3. Environment variables |
| -------------------------- |
| |
| HAProxy's configuration supports environment variables. Those variables are |
| interpreted only within double quotes. Variables are expanded during the |
| configuration parsing. Variable names must be preceded by a dollar ("$") and |
| optionally enclosed with braces ("{}") similarly to what is done in Bourne |
| shell. Variable names can contain alphanumerical characters or the character |
| underscore ("_") but should not start with a digit. |
| |
| Example: |
| |
| bind "fd@${FD_APP1}" |
| |
| log "${LOCAL_SYSLOG}:514" local0 notice # send to local server |
| |
| user "$HAPROXY_USER" |
| |
| |
| 2.4. 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.4. Examples |
| ------------- |
| |
| # Simple configuration for an HTTP proxy listening on port 80 on all |
| # interfaces and forwarding requests to a single backend "servers" with a |
| # single server "server1" listening on 127.0.0.1:8000 |
| global |
| daemon |
| maxconn 256 |
| |
| defaults |
| mode http |
| timeout connect 5000ms |
| timeout client 50000ms |
| timeout server 50000ms |
| |
| frontend http-in |
| bind *:80 |
| default_backend servers |
| |
| backend servers |
| server server1 127.0.0.1:8000 maxconn 32 |
| |
| |
| # The same configuration defined with a single listen block. Shorter but |
| # less expressive, especially in HTTP mode. |
| global |
| daemon |
| maxconn 256 |
| |
| defaults |
| mode http |
| timeout connect 5000ms |
| timeout client 50000ms |
| timeout server 50000ms |
| |
| listen http-in |
| bind *:80 |
| server server1 127.0.0.1:8000 maxconn 32 |
| |
| |
| Assuming haproxy is in $PATH, test these configurations in a shell with: |
| |
| $ sudo haproxy -f configuration.conf -c |
| |
| |
| 3. Global parameters |
| -------------------- |
| |
| Parameters in the "global" section are process-wide and often OS-specific. They |
| are generally set once for all and do not need being changed once correct. Some |
| of them have command-line equivalents. |
| |
| The following keywords are supported in the "global" section : |
| |
| * Process management and security |
| - ca-base |
| - chroot |
| - crt-base |
| - daemon |
| - external-check |
| - gid |
| - group |
| - log |
| - log-send-hostname |
| - nbproc |
| - pidfile |
| - uid |
| - ulimit-n |
| - user |
| - stats |
| - ssl-server-verify |
| - node |
| - description |
| - unix-bind |
| - 51degrees-data-file |
| - 51degrees-property-name-list |
| - 51degrees-property-separator |
| - 51degrees-cache-size |
| |
| * Performance tuning |
| - max-spread-checks |
| - maxconn |
| - maxconnrate |
| - maxcomprate |
| - maxcompcpuusage |
| - maxpipes |
| - maxsessrate |
| - maxsslconn |
| - maxsslrate |
| - noepoll |
| - nokqueue |
| - nopoll |
| - nosplice |
| - nogetaddrinfo |
| - spread-checks |
| - tune.bufsize |
| - tune.chksize |
| - tune.comp.maxlevel |
| - tune.http.cookielen |
| - tune.http.maxhdr |
| - tune.idletimer |
| - tune.lua.forced-yield |
| - tune.lua.maxmem |
| - tune.lua.session-timeout |
| - tune.lua.task-timeout |
| - tune.maxaccept |
| - tune.maxpollevents |
| - tune.maxrewrite |
| - tune.pattern.cache-size |
| - tune.pipesize |
| - tune.rcvbuf.client |
| - tune.rcvbuf.server |
| - tune.sndbuf.client |
| - tune.sndbuf.server |
| - tune.ssl.cachesize |
| - tune.ssl.lifetime |
| - tune.ssl.force-private-cache |
| - tune.ssl.maxrecord |
| - tune.ssl.default-dh-param |
| - tune.ssl.ssl-ctx-cache-size |
| - tune.vars.global-max-size |
| - tune.vars.reqres-max-size |
| - tune.vars.sess-max-size |
| - tune.vars.txn-max-size |
| - tune.zlib.memlevel |
| - tune.zlib.windowsize |
| |
| * Debugging |
| - debug |
| - quiet |
| |
| |
| 3.1. Process management and security |
| ------------------------------------ |
| |
| ca-base <dir> |
| Assigns a default directory to fetch SSL CA certificates and CRLs from when a |
| relative path is used with "ca-file" or "crl-file" directives. Absolute |
| locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base". |
| |
| chroot <jail dir> |
| Changes current directory to <jail dir> and performs a chroot() there before |
| dropping privileges. This increases the security level in case an unknown |
| vulnerability would be exploited, since it would make it very hard for the |
| attacker to exploit the system. This only works when the process is started |
| with superuser privileges. It is important to ensure that <jail_dir> is both |
| empty and unwritable to anyone. |
| |
| cpu-map <"all"|"odd"|"even"|process_num> <cpu-set>... |
| On Linux 2.6 and above, it is possible to bind a process to a specific CPU |
| set. This means that the process will never run on other CPUs. The "cpu-map" |
| directive specifies CPU sets for process sets. The first argument is the |
| process number to bind. This process must have a number between 1 and 32 or |
| 64, depending on the machine's word size, and any process IDs above nbproc |
| are ignored. It is possible to specify all processes at once using "all", |
| only odd numbers using "odd" or even numbers using "even", just like with the |
| "bind-process" directive. The second and forthcoming arguments are CPU sets. |
| Each CPU set is either a unique number between 0 and 31 or 63 or a range with |
| two such numbers delimited by a dash ('-'). Multiple CPU numbers or ranges |
| may be specified, and the processes will be allowed to bind to all of them. |
| Obviously, multiple "cpu-map" directives may be specified. Each "cpu-map" |
| directive will replace the previous ones when they overlap. |
| |
| crt-base <dir> |
| Assigns a default directory to fetch SSL certificates from when a relative |
| path is used with "crtfile" directives. Absolute locations specified after |
| "crtfile" prevail and ignore "crt-base". |
| |
| daemon |
| Makes the process fork into background. This is the recommended mode of |
| operation. It is equivalent to the command line "-D" argument. It can be |
| disabled by the command line "-db" argument. |
| |
| deviceatlas-json-file <path> |
| Sets the path of the DeviceAtlas JSON data file to be loaded by the API. |
| The path must be a valid JSON data file and accessible by Haproxy process. |
| |
| deviceatlas-log-level <value> |
| Sets the level of informations returned by the API. This directive is |
| optional and set to 0 by default if not set. |
| |
| deviceatlas-separator <char> |
| Sets the character separator for the API properties results. This directive |
| is optional and set to | by default if not set. |
| |
| external-check |
| Allows the use of an external agent to perform health checks. |
| This is disabled by default as a security precaution. |
| See "option external-check". |
| |
| 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. |
| Note that if haproxy is started from a user having supplementary groups, it |
| will only be able to drop these groups if started 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> [len <length>] <facility> [max level [min level]] |
| Adds a global syslog server. Up to two global servers can be defined. They |
| will receive logs for startups and exits, as well as all logs from proxies |
| configured with "log global". |
| |
| <address> can be one of: |
| |
| - An IPv4 address optionally followed by a colon and a UDP port. If |
| no port is specified, 514 is used by default (the standard syslog |
| port). |
| |
| - An IPv6 address followed by a colon and optionally a UDP port. If |
| no port is specified, 514 is used by default (the standard syslog |
| port). |
| |
| - A filesystem path to a UNIX domain socket, keeping in mind |
| considerations for chroot (be sure the path is accessible inside |
| the chroot) and uid/gid (be sure the path is appropriately |
| writeable). |
| |
| You may want to reference some environment variables in the address |
| parameter, see section 2.3 about environment variables. |
| |
| <length> is an optional maximum line length. Log lines larger than this value |
| will be truncated before being sent. The reason is that syslog |
| servers act differently on log line length. All servers support the |
| default value of 1024, but some servers simply drop larger lines |
| while others do log them. If a server supports long lines, it may |
| make sense to set this value here in order to avoid truncating long |
| lines. Similarly, if a server drops long lines, it is preferable to |
| truncate them before sending them. Accepted values are 80 to 65535 |
| inclusive. The default value of 1024 is generally fine for all |
| standard usages. Some specific cases of long captures or |
| JSON-formated logs may require larger values. |
| |
| <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. See also the per-proxy "log-tag" directive. |
| |
| lua-load <file> |
| This global directive loads and executes a Lua file. This directive can be |
| used multiple times. |
| |
| nbproc <number> |
| Creates <number> processes when going daemon. This requires the "daemon" |
| mode. By default, only one process is created, which is the recommended mode |
| of operation. For systems limited to small sets of file descriptors per |
| process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES |
| IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon". |
| |
| pidfile <pidfile> |
| Writes pids of all daemons into file <pidfile>. This option is equivalent to |
| the "-p" command line argument. The file must be accessible to the user |
| starting the process. See also "daemon". |
| |
| stats bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ... |
| Limits the stats socket to a certain set of processes numbers. By default the |
| stats socket is bound to all processes, causing a warning to be emitted when |
| nbproc is greater than 1 because there is no way to select the target process |
| when connecting. However, by using this setting, it becomes possible to pin |
| the stats socket to a specific set of processes, typically the first one. The |
| warning will automatically be disabled when this setting is used, whatever |
| the number of processes used. The maximum process ID depends on the machine's |
| word size (32 or 64). A better option consists in using the "process" setting |
| of the "stats socket" line to force the process on each line. |
| |
| ssl-default-bind-ciphers <ciphers> |
| This setting is only available when support for OpenSSL was built in. It sets |
| the default string describing the list of cipher algorithms ("cipher suite") |
| that are negotiated during the SSL/TLS handshake for all "bind" lines which |
| do not explicitly define theirs. The format of the string is defined in |
| "man 1 ciphers" from OpenSSL man pages, and can be for instance a string such |
| as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). Please check the |
| "bind" keyword for more information. |
| |
| ssl-default-bind-options [<option>]... |
| This setting is only available when support for OpenSSL was built in. It sets |
| default ssl-options to force on all "bind" lines. Please check the "bind" |
| keyword to see available options. |
| |
| Example: |
| global |
| ssl-default-bind-options no-sslv3 no-tls-tickets |
| |
| ssl-default-server-ciphers <ciphers> |
| This setting is only available when support for OpenSSL was built in. It |
| sets the default string describing the list of cipher algorithms that are |
| negotiated during the SSL/TLS handshake with the server, for all "server" |
| lines which do not explicitly define theirs. The format of the string is |
| defined in "man 1 ciphers". Please check the "server" keyword for more |
| information. |
| |
| ssl-default-server-options [<option>]... |
| This setting is only available when support for OpenSSL was built in. It sets |
| default ssl-options to force on all "server" lines. Please check the "server" |
| keyword to see available options. |
| |
| ssl-dh-param-file <file> |
| This setting is only available when support for OpenSSL was built in. It sets |
| the default DH parameters that are used during the SSL/TLS handshake when |
| ephemeral Diffie-Hellman (DHE) key exchange is used, for all "bind" lines |
| which do not explicitely define theirs. It will be overridden by custom DH |
| parameters found in a bind certificate file if any. If custom DH parameters |
| are not specified either by using ssl-dh-param-file or by setting them directly |
| in the certificate file, pre-generated DH parameters of the size specified |
| by tune.ssl.default-dh-param will be used. Custom parameters are known to be |
| more secure and therefore their use is recommended. |
| Custom DH parameters may be generated by using the OpenSSL command |
| "openssl dhparam <size>", where size should be at least 2048, as 1024-bit DH |
| parameters should not be considered secure anymore. |
| |
| ssl-server-verify [none|required] |
| The default behavior for SSL verify on servers side. If specified to 'none', |
| servers certificates are not verified. The default is 'required' except if |
| forced using cmdline option '-dV'. |
| |
| stats socket [<address:port>|<path>] [param*] |
| Binds a UNIX socket to <path> or a TCPv4/v6 address to <address:port>. |
| Connections to this socket will return various statistics outputs and even |
| allow some commands to be issued to change some runtime settings. Please |
| consult section 9.2 "Unix Socket commands" for more details. |
| |
| All parameters supported by "bind" lines are supported, for instance to |
| restrict access to some users or their access rights. Please consult |
| section 5.1 for more information. |
| |
| stats timeout <timeout, in milliseconds> |
| The default timeout on the stats socket is set to 10 seconds. It is possible |
| to change this value with "stats timeout". The value must be passed in |
| milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }. |
| |
| stats maxconn <connections> |
| By default, the stats socket is limited to 10 concurrent connections. It is |
| possible to change this value with "stats maxconn". |
| |
| uid <number> |
| Changes the process' user ID to <number>. It is recommended that the user ID |
| is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| be started with superuser privileges in order to be able to switch to another |
| one. See also "gid" and "user". |
| |
| ulimit-n <number> |
| Sets the maximum number of per-process file-descriptors to <number>. By |
| default, it is automatically computed, so it is recommended not to use this |
| option. |
| |
| unix-bind [ prefix <prefix> ] [ mode <mode> ] [ user <user> ] [ uid <uid> ] |
| [ group <group> ] [ gid <gid> ] |
| |
| Fixes common settings to UNIX listening sockets declared in "bind" statements. |
| This is mainly used to simplify declaration of those UNIX sockets and reduce |
| the risk of errors, since those settings are most commonly required but are |
| also process-specific. The <prefix> setting can be used to force all socket |
| path to be relative to that directory. This might be needed to access another |
| component's chroot. Note that those paths are resolved before haproxy chroots |
| itself, so they are absolute. The <mode>, <user>, <uid>, <group> and <gid> |
| all have the same meaning as their homonyms used by the "bind" statement. If |
| both are specified, the "bind" statement has priority, meaning that the |
| "unix-bind" settings may be seen as process-wide default settings. |
| |
| user <user name> |
| Similar to "uid" but uses the UID of user name <user name> from /etc/passwd. |
| See also "uid" and "group". |
| |
| node <name> |
| Only letters, digits, hyphen and underscore are allowed, like in DNS names. |
| |
| This statement is useful in HA configurations where two or more processes or |
| servers share the same IP address. By setting a different node-name on all |
| nodes, it becomes easy to immediately spot what server is handling the |
| traffic. |
| |
| description <text> |
| Add a text that describes the instance. |
| |
| Please note that it is required to escape certain characters (# for example) |
| and this text is inserted into a html page so you should avoid using |
| "<" and ">" characters. |
| |
| 51degrees-data-file <file path> |
| The path of the 51Degrees data file to provide device detection services. The |
| file should be unzipped and accessible by HAProxy with relevavnt permissions. |
| |
| Please note that this option is only available when haproxy has been |
| compiled with USE_51DEGREES. |
| |
| 51degrees-property-name-list [<string>] |
| A list of 51Degrees property names to be load from the dataset. A full list |
| of names is available on the 51Degrees website: |
| https://51degrees.com/resources/property-dictionary |
| |
| Please note that this option is only available when haproxy has been |
| compiled with USE_51DEGREES. |
| |
| 51degrees-property-separator <char> |
| A char that will be appended to every property value in a response header |
| containing 51Degrees results. If not set that will be set as ','. |
| |
| Please note that this option is only available when haproxy has been |
| compiled with USE_51DEGREES. |
| |
| 51degrees-cache-size <number> |
| Sets the size of the 51Degrees converter cache to <number> entries. This |
| is an LRU cache which reminds previous device detections and their results. |
| By default, this cache is disabled. |
| |
| Please note that this option is only available when haproxy has been |
| compiled with USE_51DEGREES. |
| |
| |
| 3.2. Performance tuning |
| ----------------------- |
| |
| max-spread-checks <delay in milliseconds> |
| By default, haproxy tries to spread the start of health checks across the |
| smallest health check interval of all the servers in a farm. The principle is |
| to avoid hammering services running on the same server. But when using large |
| check intervals (10 seconds or more), the last servers in the farm take some |
| time before starting to be tested, which can be a problem. This parameter is |
| used to enforce an upper bound on delay between the first and the last check, |
| even if the servers' check intervals are larger. When servers run with |
| shorter intervals, their intervals will be respected though. |
| |
| 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". Note: |
| the "select" poller cannot reliably use more than 1024 file descriptors on |
| some platforms. If your platform only supports select and reports "select |
| FAILED" on startup, you need to reduce maxconn until it works (slightly |
| below 500 in general). If this value is not set, it will default to the value |
| set in DEFAULT_MAXCONN at build time (reported in haproxy -vv) if no memory |
| limit is enforced, or will be computed based on the memory limit, the buffer |
| size, memory allocated to compression, SSL cache size, and use or not of SSL |
| and the associated maxsslconn (which can also be automatic). |
| |
| maxconnrate <number> |
| Sets the maximum per-process number of connections per second to <number>. |
| Proxies will stop accepting connections when this limit is reached. It can be |
| used to limit the global capacity regardless of each frontend capacity. It is |
| important to note that this can only be used as a service protection measure, |
| as there will not necessarily be a fair share between frontends when the |
| limit is reached, so it's a good idea to also limit each frontend to some |
| value close to its expected share. Also, lowering tune.maxaccept can improve |
| fairness. |
| |
| maxcomprate <number> |
| Sets the maximum per-process input compression rate to <number> kilobytes |
| per second. For each session, if the maximum is reached, the compression |
| level will be decreased during the session. If the maximum is reached at the |
| beginning of a session, the session will not compress at all. If the maximum |
| is not reached, the compression level will be increased up to |
| tune.comp.maxlevel. A value of zero means there is no limit, this is the |
| default value. |
| |
| maxcompcpuusage <number> |
| Sets the maximum CPU usage HAProxy can reach before stopping the compression |
| for new requests or decreasing the compression level of current requests. |
| It works like 'maxcomprate' but measures CPU usage instead of incoming data |
| bandwidth. The value is expressed in percent of the CPU used by haproxy. In |
| case of multiple processes (nbproc > 1), each process manages its individual |
| usage. A value of 100 disable the limit. The default value is 100. Setting |
| a lower value will prevent the compression work from slowing the whole |
| process down and from introducing high latencies. |
| |
| 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. |
| |
| maxsessrate <number> |
| Sets the maximum per-process number of sessions per second to <number>. |
| Proxies will stop accepting connections when this limit is reached. It can be |
| used to limit the global capacity regardless of each frontend capacity. It is |
| important to note that this can only be used as a service protection measure, |
| as there will not necessarily be a fair share between frontends when the |
| limit is reached, so it's a good idea to also limit each frontend to some |
| value close to its expected share. Also, lowering tune.maxaccept can improve |
| fairness. |
| |
| maxsslconn <number> |
| Sets the maximum per-process number of concurrent SSL connections to |
| <number>. By default there is no SSL-specific limit, which means that the |
| global maxconn setting will apply to all connections. Setting this limit |
| avoids having openssl use too much memory and crash when malloc returns NULL |
| (since it unfortunately does not reliably check for such conditions). Note |
| that the limit applies both to incoming and outgoing connections, so one |
| connection which is deciphered then ciphered accounts for 2 SSL connections. |
| If this value is not set, but a memory limit is enforced, this value will be |
| automatically computed based on the memory limit, maxconn, the buffer size, |
| memory allocated to compression, SSL cache size, and use of SSL in either |
| frontends, backends or both. If neither maxconn nor maxsslconn are specified |
| when there is a memory limit, haproxy will automatically adjust these values |
| so that 100% of the connections can be made over SSL with no risk, and will |
| consider the sides where it is enabled (frontend, backend, both). |
| |
| maxsslrate <number> |
| Sets the maximum per-process number of SSL sessions per second to <number>. |
| SSL listeners will stop accepting connections when this limit is reached. It |
| can be used to limit the global SSL CPU usage regardless of each frontend |
| capacity. It is important to note that this can only be used as a service |
| protection measure, as there will not necessarily be a fair share between |
| frontends when the limit is reached, so it's a good idea to also limit each |
| frontend to some value close to its expected share. It is also important to |
| note that the sessions are accounted before they enter the SSL stack and not |
| after, which also protects the stack against bad handshakes. Also, lowering |
| tune.maxaccept can improve fairness. |
| |
| maxzlibmem <number> |
| Sets the maximum amount of RAM in megabytes per process usable by the zlib. |
| When the maximum amount is reached, future sessions will not compress as long |
| as RAM is unavailable. When sets to 0, there is no limit. |
| The default value is 0. The value is available in bytes on the UNIX socket |
| with "show info" on the line "MaxZlibMemUsage", the memory used by zlib is |
| "ZlibMemUsage" in bytes. |
| |
| noepoll |
| Disables the use of the "epoll" event polling system on Linux. It is |
| equivalent to the command-line argument "-de". The next polling system |
| used will generally be "poll". See also "nopoll". |
| |
| nokqueue |
| Disables the use of the "kqueue" event polling system on BSD. It is |
| equivalent to the command-line argument "-dk". The next polling system |
| used will generally be "poll". See also "nopoll". |
| |
| nopoll |
| Disables the use of the "poll" event polling system. It is equivalent to the |
| command-line argument "-dp". The next polling system used will be "select". |
| It should never be needed to disable "poll" since it's available on all |
| platforms supported by HAProxy. See also "nokqueue" and "noepoll". |
| |
| nosplice |
| Disables the use of kernel tcp splicing between sockets on Linux. It is |
| equivalent to the command line argument "-dS". Data will then be copied |
| using conventional and more portable recv/send calls. Kernel tcp splicing is |
| limited to some very recent instances of kernel 2.6. Most versions between |
| 2.6.25 and 2.6.28 are buggy and will forward corrupted data, so they must not |
| be used. This option makes it easier to globally disable kernel splicing in |
| case of doubt. See also "option splice-auto", "option splice-request" and |
| "option splice-response". |
| |
| nogetaddrinfo |
| Disables the use of getaddrinfo(3) for name resolving. It is equivalent to |
| the command line argument "-dG". Deprecated gethostbyname(3) will be used. |
| |
| spread-checks <0..50, in percent> |
| Sometimes it is desirable to avoid sending agent and 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.buffers.limit <number> |
| Sets a hard limit on the number of buffers which may be allocated per process. |
| The default value is zero which means unlimited. The minimum non-zero value |
| will always be greater than "tune.buffers.reserve" and should ideally always |
| be about twice as large. Forcing this value can be particularly useful to |
| limit the amount of memory a process may take, while retaining a sane |
| behaviour. When this limit is reached, sessions which need a buffer wait for |
| another one to be released by another session. Since buffers are dynamically |
| allocated and released, the waiting time is very short and not perceptible |
| provided that limits remain reasonable. In fact sometimes reducing the limit |
| may even increase performance by increasing the CPU cache's efficiency. Tests |
| have shown good results on average HTTP traffic with a limit to 1/10 of the |
| expected global maxconn setting, which also significantly reduces memory |
| usage. The memory savings come from the fact that a number of connections |
| will not allocate 2*tune.bufsize. It is best not to touch this value unless |
| advised to do so by an haproxy core developer. |
| |
| tune.buffers.reserve <number> |
| Sets the number of buffers which are pre-allocated and reserved for use only |
| during memory shortage conditions resulting in failed memory allocations. The |
| minimum value is 2 and is also the default. There is no reason a user would |
| want to change this value, it's mostly aimed at haproxy core developers. |
| |
| tune.bufsize <number> |
| Sets the buffer size to this size (in bytes). Lower values allow more |
| sessions to coexist in the same amount of RAM, and higher values allow some |
| applications with very large cookies to work. The default value is 16384 and |
| can be changed at build time. It is strongly recommended not to change this |
| from the default value, as very low values will break some services such as |
| statistics, and values larger than default size will increase memory usage, |
| possibly causing the system to run out of memory. At least the global maxconn |
| parameter should be decreased by the same factor as this one is increased. |
| If HTTP request is larger than (tune.bufsize - tune.maxrewrite), haproxy will |
| return HTTP 400 (Bad Request) error. Similarly if an HTTP response is larger |
| than this size, haproxy will return HTTP 502 (Bad Gateway). |
| |
| tune.chksize <number> |
| Sets the check buffer size to this size (in bytes). Higher values may help |
| find string or regex patterns in very large pages, though doing so may imply |
| more memory and CPU usage. The default value is 16384 and can be changed at |
| build time. It is not recommended to change this value, but to use better |
| checks whenever possible. |
| |
| tune.comp.maxlevel <number> |
| Sets the maximum compression level. The compression level affects CPU |
| usage during compression. This value affects CPU usage during compression. |
| Each session using compression initializes the compression algorithm with |
| this value. The default value is 1. |
| |
| tune.http.cookielen <number> |
| Sets the maximum length of captured cookies. This is the maximum value that |
| the "capture cookie xxx len yyy" will be allowed to take, and any upper value |
| will automatically be truncated to this one. It is important not to set too |
| high a value because all cookie captures still allocate this size whatever |
| their configured value (they share a same pool). This value is per request |
| per response, so the memory allocated is twice this value per connection. |
| When not specified, the limit is set to 63 characters. It is recommended not |
| to change this value. |
| |
| tune.http.maxhdr <number> |
| Sets the maximum number of headers in a request. When a request comes with a |
| number of headers greater than this value (including the first line), it is |
| rejected with a "400 Bad Request" status code. Similarly, too large responses |
| are blocked with "502 Bad Gateway". The default value is 101, which is enough |
| for all usages, considering that the widely deployed Apache server uses the |
| same limit. It can be useful to push this limit further to temporarily allow |
| a buggy application to work by the time it gets fixed. Keep in mind that each |
| new header consumes 32bits of memory for each session, so don't push this |
| limit too high. |
| |
| tune.idletimer <timeout> |
| Sets the duration after which haproxy will consider that an empty buffer is |
| probably associated with an idle stream. This is used to optimally adjust |
| some packet sizes while forwarding large and small data alternatively. The |
| decision to use splice() or to send large buffers in SSL is modulated by this |
| parameter. The value is in milliseconds between 0 and 65535. A value of zero |
| means that haproxy will not try to detect idle streams. The default is 1000, |
| which seems to correctly detect end user pauses (eg: read a page before |
| clicking). There should be not reason for changing this value. Please check |
| tune.ssl.maxrecord below. |
| |
| tune.lua.forced-yield <number> |
| This directive forces the Lua engine to execute a yield each <number> of |
| instructions executed. This permits interruptng a long script and allows the |
| HAProxy scheduler to process other tasks like accepting connections or |
| forwarding traffic. The default value is 10000 instructions. If HAProxy often |
| executes some Lua code but more reactivity is required, this value can be |
| lowered. If the Lua code is quite long and its result is absolutely required |
| to process the data, the <number> can be increased. |
| |
| tune.lua.maxmem |
| Sets the maximum amount of RAM in megabytes per process usable by Lua. By |
| default it is zero which means unlimited. It is important to set a limit to |
| ensure that a bug in a script will not result in the system running out of |
| memory. |
| |
| tune.lua.session-timeout <timeout> |
| This is the execution timeout for the Lua sessions. This is useful for |
| preventing infinite loops or spending too much time in Lua. This timeout has a |
| priority over other timeouts. For example, if this timeout is set to 4s and |
| you run a 5s sleep, the code will be interrupted with an error after waiting |
| 4s. |
| |
| tune.lua.task-timeout <timeout> |
| Purpose is the same as "tune.lua.session-timeout", but this timeout is |
| dedicated to the tasks. By default, this timeout isn't set because a task may |
| remain alive during of the lifetime of HAProxy. For example, a task used to |
| check servers. |
| |
| tune.maxaccept <number> |
| Sets the maximum number of consecutive connections a process may accept in a |
| row before switching to other work. In single process mode, higher numbers |
| give better performance at high connection rates. However in multi-process |
| modes, keeping a bit of fairness between processes generally is better to |
| increase performance. This value applies individually to each listener, so |
| that the number of processes a listener is bound to is taken into account. |
| This value defaults to 64. In multi-process mode, it is divided by twice |
| the number of processes the listener is bound to. 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.pattern.cache-size <number> |
| Sets the size of the pattern lookup cache to <number> entries. This is an LRU |
| cache which reminds previous lookups and their results. It is used by ACLs |
| and maps on slow pattern lookups, namely the ones using the "sub", "reg", |
| "dir", "dom", "end", "bin" match methods as well as the case-insensitive |
| strings. It applies to pattern expressions which means that it will be able |
| to memorize the result of a lookup among all the patterns specified on a |
| configuration line (including all those loaded from files). It automatically |
| invalidates entries which are updated using HTTP actions or on the CLI. The |
| default cache size is set to 10000 entries, which limits its footprint to |
| about 5 MB on 32-bit systems and 8 MB on 64-bit systems. There is a very low |
| risk of collision in this cache, which is in the order of the size of the |
| cache divided by 2^64. Typically, at 10000 requests per second with the |
| default cache size of 10000 entries, there's 1% chance that a brute force |
| attack could cause a single collision after 60 years, or 0.1% after 6 years. |
| This is considered much lower than the risk of a memory corruption caused by |
| aging components. If this is not acceptable, the cache can be disabled by |
| setting this parameter to 0. |
| |
| tune.pipesize <number> |
| Sets the kernel pipe buffer size to this size (in bytes). By default, pipes |
| are the default size for the system. But sometimes when using TCP splicing, |
| it can improve performance to increase pipe sizes, especially if it is |
| suspected that pipes are not filled and that many calls to splice() are |
| performed. This has an impact on the kernel's memory footprint, so this must |
| not be changed if impacts are not understood. |
| |
| tune.rcvbuf.client <number> |
| tune.rcvbuf.server <number> |
| Forces the kernel socket receive buffer size on the client or the server side |
| to the specified value in bytes. This value applies to all TCP/HTTP frontends |
| and backends. It should normally never be set, and the default size (0) lets |
| the kernel autotune this value depending on the amount of available memory. |
| However it can sometimes help to set it to very low values (eg: 4096) in |
| order to save kernel memory by preventing it from buffering too large amounts |
| of received data. Lower values will significantly increase CPU usage though. |
| |
| tune.sndbuf.client <number> |
| tune.sndbuf.server <number> |
| Forces the kernel socket send buffer size on the client or the server side to |
| the specified value in bytes. This value applies to all TCP/HTTP frontends |
| and backends. It should normally never be set, and the default size (0) lets |
| the kernel autotune this value depending on the amount of available memory. |
| However it can sometimes help to set it to very low values (eg: 4096) in |
| order to save kernel memory by preventing it from buffering too large amounts |
| of received data. Lower values will significantly increase CPU usage though. |
| Another use case is to prevent write timeouts with extremely slow clients due |
| to the kernel waiting for a large part of the buffer to be read before |
| notifying haproxy again. |
| |
| tune.ssl.cachesize <number> |
| Sets the size of the global SSL session cache, in a number of blocks. A block |
| is large enough to contain an encoded session without peer certificate. |
| An encoded session with peer certificate is stored in multiple blocks |
| depending on the size of the peer certificate. A block uses approximately |
| 200 bytes of memory. The default value may be forced at build time, otherwise |
| defaults to 20000. When the cache is full, the most idle entries are purged |
| and reassigned. Higher values reduce the occurrence of such a purge, hence |
| the number of CPU-intensive SSL handshakes by ensuring that all users keep |
| their session as long as possible. All entries are pre-allocated upon startup |
| and are shared between all processes if "nbproc" is greater than 1. Setting |
| this value to 0 disables the SSL session cache. |
| |
| tune.ssl.force-private-cache |
| This boolean disables SSL session cache sharing between all processes. It |
| should normally not be used since it will force many renegotiations due to |
| clients hitting a random process. But it may be required on some operating |
| systems where none of the SSL cache synchronization method may be used. In |
| this case, adding a first layer of hash-based load balancing before the SSL |
| layer might limit the impact of the lack of session sharing. |
| |
| tune.ssl.lifetime <timeout> |
| Sets how long a cached SSL session may remain valid. This time is expressed |
| in seconds and defaults to 300 (5 min). It is important to understand that it |
| does not guarantee that sessions will last that long, because if the cache is |
| full, the longest idle sessions will be purged despite their configured |
| lifetime. The real usefulness of this setting is to prevent sessions from |
| being used for too long. |
| |
| tune.ssl.maxrecord <number> |
| Sets the maximum amount of bytes passed to SSL_write() at a time. Default |
| value 0 means there is no limit. Over SSL/TLS, the client can decipher the |
| data only once it has received a full record. With large records, it means |
| that clients might have to download up to 16kB of data before starting to |
| process them. Limiting the value can improve page load times on browsers |
| located over high latency or low bandwidth networks. It is suggested to find |
| optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over |
| Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled), |
| keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and |
| 2859 gave good results during tests. Use "strace -e trace=write" to find the |
| best value. Haproxy will automatically switch to this setting after an idle |
| stream has been detected (see tune.idletimer above). |
| |
| tune.ssl.default-dh-param <number> |
| Sets the maximum size of the Diffie-Hellman parameters used for generating |
| the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The |
| final size will try to match the size of the server's RSA (or DSA) key (e.g, |
| a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed |
| this maximum value. Default value if 1024. Only 1024 or higher values are |
| allowed. Higher values will increase the CPU load, and values greater than |
| 1024 bits are not supported by Java 7 and earlier clients. This value is not |
| used if static Diffie-Hellman parameters are supplied either directly |
| in the certificate file or by using the ssl-dh-param-file parameter. |
| |
| tune.ssl.ssl-ctx-cache-size <number> |
| Sets the size of the cache used to store generated certificates to <number> |
| entries. This is a LRU cache. Because generating a SSL certificate |
| dynamically is expensive, they are cached. The default cache size is set to |
| 1000 entries. |
| |
| tune.vars.global-max-size <size> |
| tune.vars.reqres-max-size <size> |
| tune.vars.sess-max-size <size> |
| tune.vars.txn-max-size <size> |
| These four tunes helps to manage the allowed amount of memory used by the |
| variables system. "global" limits the memory for all the systems. "sess" limit |
| the memory by session, "txn" limits the memory by transaction and "reqres" |
| limits the memory for each request or response processing. during the |
| accounting, "sess" embbed "txn" and "txn" embed "reqres". |
| |
| By example, we considers that "tune.vars.sess-max-size" is fixed to 100, |
| "tune.vars.txn-max-size" is fixed to 100, "tune.vars.reqres-max-size" is |
| also fixed to 100. If we create a variable "txn.var" that contains 100 bytes, |
| we cannot create any more variable in the other contexts. |
| |
| tune.zlib.memlevel <number> |
| Sets the memLevel parameter in zlib initialization for each session. It |
| defines how much memory should be allocated for the internal compression |
| state. A value of 1 uses minimum memory but is slow and reduces compression |
| ratio, a value of 9 uses maximum memory for optimal speed. Can be a value |
| between 1 and 9. The default value is 8. |
| |
| tune.zlib.windowsize <number> |
| Sets the window size (the size of the history buffer) as a parameter of the |
| zlib initialization for each session. Larger values of this parameter result |
| in better compression at the expense of memory usage. Can be a value between |
| 8 and 15. The default value is 15. |
| |
| 3.3. Debugging |
| -------------- |
| |
| debug |
| Enables debug mode which dumps to stdout all exchanges, and disables forking |
| into background. It is the equivalent of the command-line argument "-d". It |
| should never be used in a production configuration since it may prevent full |
| system startup. |
| |
| quiet |
| Do not display any message during startup. It is equivalent to the command- |
| line argument "-q". |
| |
| |
| 3.4. Userlists |
| -------------- |
| It is possible to control access to frontend/backend/listen sections or to |
| http stats by allowing only authenticated and authorized users. To do this, |
| it is required to create at least one userlist and to define users. |
| |
| userlist <listname> |
| Creates new userlist with name <listname>. Many independent userlists can be |
| used to store authentication & authorization data for independent customers. |
| |
| group <groupname> [users <user>,<user>,(...)] |
| Adds group <groupname> to the current userlist. It is also possible to |
| attach users to this group by using a comma separated list of names |
| proceeded by "users" keyword. |
| |
| user <username> [password|insecure-password <password>] |
| [groups <group>,<group>,(...)] |
| Adds user <username> to the current userlist. Both secure (encrypted) and |
| insecure (unencrypted) passwords can be used. Encrypted passwords are |
| evaluated using the crypt(3) function so depending of the system's |
| capabilities, different algorithms are supported. For example modern Glibc |
| based Linux system supports MD5, SHA-256, SHA-512 and of course classic, |
| DES-based method of encrypting 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 propagate entries of any data-types 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. The pushed |
| values overwrite remote ones without aggregation. 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. |
| Note that 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. |
| |
| peers <peersect> |
| Creates a new peer list with name <peersect>. It is an independent section, |
| which is referenced by one or more stick-tables. |
| |
| disabled |
| Disables a peers section. It disables both listening and any synchronization |
| related to this section. This is provided to disable synchronization of stick |
| tables without having to comment out all "peers" references. |
| |
| enable |
| This re-enables a disabled peers section which was previously disabled. |
| |
| 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. |
| |
| You may want to reference some environment variables in the address |
| parameter, see section 2.3 about environment variables. |
| |
| 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 |
| |
| |
| 3.6. Mailers |
| ------------ |
| It is possible to send email alerts when the state of servers changes. |
| If configured email alerts are sent to each mailer that is configured |
| in a mailers section. Email is sent to mailers using SMTP. |
| |
| mailer <mailersect> |
| Creates a new mailer list with the name <mailersect>. It is an |
| independent section which is referenced by one or more proxies. |
| |
| mailer <mailername> <ip>:<port> |
| Defines a mailer inside a mailers section. |
| |
| Example: |
| mailers mymailers |
| mailer smtp1 192.168.0.1:587 |
| mailer smtp2 192.168.0.2:587 |
| |
| backend mybackend |
| mode tcp |
| balance roundrobin |
| |
| email-alert mailers mymailers |
| email-alert from test1@horms.org |
| email-alert to test2@horms.org |
| |
| 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. |
| |
| In HTTP mode, the processing applied to requests and responses flowing over |
| a connection depends in the combination of the frontend's HTTP options and |
| the backend's. HAProxy supports 5 connection modes : |
| |
| - KAL : keep alive ("option http-keep-alive") which is the default mode : all |
| requests and responses are processed, and connections remain open but idle |
| between responses and new requests. |
| |
| - TUN: tunnel ("option http-tunnel") : this was the default mode for versions |
| 1.0 to 1.5-dev21 : only the first request and response are processed, and |
| everything else is forwarded with no analysis at all. This mode should not |
| be used as it creates lots of trouble with logging and HTTP processing. |
| |
| - PCL: passive close ("option httpclose") : exactly the same as tunnel mode, |
| but with "Connection: close" appended in both directions to try to make |
| both ends close after the first request/response exchange. |
| |
| - SCL: server close ("option http-server-close") : the server-facing |
| connection is closed after the end of the response is received, but the |
| client-facing connection remains open. |
| |
| - FCL: forced close ("option forceclose") : the connection is actively closed |
| after the end of the response. |
| |
| The effective mode that will be applied to a connection passing through a |
| frontend and a backend can be determined by both proxy modes according to the |
| following matrix, but in short, the modes are symmetric, keep-alive is the |
| weakest option and force close is the strongest. |
| |
| Backend mode |
| |
| | KAL | TUN | PCL | SCL | FCL |
| ----+-----+-----+-----+-----+---- |
| KAL | KAL | TUN | PCL | SCL | FCL |
| ----+-----+-----+-----+-----+---- |
| TUN | TUN | TUN | PCL | SCL | FCL |
| Frontend ----+-----+-----+-----+-----+---- |
| mode PCL | PCL | PCL | PCL | FCL | FCL |
| ----+-----+-----+-----+-----+---- |
| SCL | SCL | SCL | FCL | SCL | FCL |
| ----+-----+-----+-----+-----+---- |
| FCL | FCL | FCL | FCL | FCL | FCL |
| |
| |
| |
| 4.1. Proxy keywords matrix |
| -------------------------- |
| |
| The following list of keywords is supported. Most of them may only be used in a |
| limited set of section types. Some of them are marked as "deprecated" because |
| they are inherited from an old syntax which may be confusing or functionally |
| limited, and there are new recommended keywords to replace them. Keywords |
| marked with "(*)" can be optionally inverted using the "no" prefix, eg. "no |
| option contstats". This makes sense when the option has been enabled by default |
| and must be disabled for a specific instance. Such options may also be prefixed |
| with "default" in order to restore default settings regardless of what has been |
| specified in a previous "defaults" section. |
| |
| |
| keyword defaults frontend listen backend |
| ------------------------------------+----------+----------+---------+--------- |
| acl - X X X |
| appsession - - X X |
| backlog X X X - |
| balance X - X X |
| bind - X X - |
| bind-process X X X X |
| block - X X X |
| capture cookie - X X - |
| capture request header - X X - |
| capture response header - X X - |
| clitimeout (deprecated) X X X - |
| compression X X X X |
| contimeout (deprecated) X - X X |
| cookie X - X X |
| declare capture - X X - |
| default-server X - X X |
| default_backend X X X - |
| description - X X X |
| disabled X X X X |
| dispatch - - X X |
| email-alert from X X X X |
| email-alert level X X X X |
| email-alert mailers X X X X |
| email-alert myhostname X X X X |
| email-alert to X X 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 |
| http-response - X X X |
| http-send-name-header - - X X |
| id - X X X |
| ignore-persist - X X X |
| log (*) X X X X |
| log-format X X X - |
| log-tag X X X X |
| max-keep-alive-queue 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-buffer-request (*) X X X X |
| option http-ignore-probes (*) X X X - |
| option http-keep-alive (*) X X X X |
| option http-no-delay (*) X X X X |
| option http-pretend-keepalive (*) X X X X |
| option http-server-close (*) X X X X |
| option http-tunnel (*) X X X X |
| option http-use-proxy-header (*) X X X - |
| option httpchk X - X X |
| option httpclose (*) X X X X |
| option httplog X X X X |
| option http_proxy (*) X X X X |
| option independent-streams (*) X X X X |
| option ldap-check X - X X |
| option external-check X - X X |
| option log-health-checks (*) X - X X |
| option log-separate-errors (*) X X X - |
| option logasap (*) X X X - |
| option mysql-check X - X X |
| option pgsql-check X - X X |
| option nolinger (*) X X X X |
| option originalto X X X X |
| option persist (*) X - X X |
| option redispatch (*) X - X X |
| option redis-check X - X X |
| option smtpchk X - X X |
| option socket-stats (*) X X X - |
| option splice-auto (*) X X X X |
| option splice-request (*) X X X X |
| option splice-response (*) X X X X |
| option srvtcpka (*) X - X X |
| option ssl-hello-chk X - X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| option tcp-check X - X X |
| 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 |
| external-check command X - X X |
| external-check path 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 |
| reqitarpit - X X X |
| reqpass - X X X |
| reqrep - X X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| reqtarpit - X X X |
| retries X - X X |
| rspadd - X X X |
| rspdel - X X X |
| rspdeny - X X X |
| rspidel - X X X |
| rspideny - X X X |
| rspirep - X X X |
| rsprep - X X X |
| server - - X X |
| source X - X X |
| srvtimeout (deprecated) X - X X |
| stats admin - - X X |
| stats auth X - X X |
| stats enable X - X X |
| stats hide-version X - X X |
| stats http-request - - X X |
| stats realm X - X X |
| stats refresh X - X X |
| stats scope X - X X |
| stats show-desc X - X X |
| stats show-legends X - X X |
| stats show-node X - X X |
| stats uri X - X X |
| -- keyword -------------------------- defaults - frontend - listen -- backend - |
| stick match - - X X |
| stick on - - X X |
| stick store-request - - X X |
| stick store-response - - X X |
| stick-table - - X X |
| tcp-check connect - - X X |
| tcp-check expect - - X X |
| tcp-check send - - X X |
| tcp-check send-binary - - 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 client-fin 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 server-fin X - X X |
| timeout srvtimeout (deprecated) X - X X |
| timeout tarpit X X X X |
| timeout tunnel X - X X |
| transparent (deprecated) X - X X |
| unique-id-format X X X - |
| unique-id-header X X X - |
| use_backend - X X - |
| use-server - - X X |
| ------------------------------------+----------+----------+---------+--------- |
| keyword defaults frontend listen backend |
| |
| |
| 4.2. Alphabetically sorted keywords reference |
| --------------------------------------------- |
| |
| This section provides a description of each keyword and its usage. |
| |
| |
| acl <aclname> <criterion> [flags] [operator] <value> ... |
| Declare or complete an access list. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Example: |
| acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| acl invalid_src src_port 0:1023 |
| acl local_dst hdr(host) -i localhost |
| |
| See section 7 about ACL usage. |
| |
| |
| appsession <cookie> len <length> timeout <holdtime> |
| [request-learn] [prefix] [mode <path-parameters|query-string>] |
| Define session stickiness on an existing application cookie. |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| Arguments : |
| <cookie> this is the name of the cookie used by the application and which |
| HAProxy will have to learn for each new session. |
| |
| <length> this is the max number of characters that will be memorized and |
| checked in each cookie value. |
| |
| <holdtime> this is the time after which the cookie will be removed from |
| memory if unused. If no unit is specified, this time is in |
| milliseconds. |
| |
| request-learn |
| If this option is specified, then haproxy will be able to learn |
| the cookie found in the request in case the server does not |
| specify any in response. This is typically what happens with |
| PHPSESSID cookies, or when haproxy's session expires before |
| the application's session and the correct server is selected. |
| It is recommended to specify this option to improve reliability. |
| |
| prefix When this option is specified, haproxy will match on the cookie |
| prefix (or URL parameter prefix). The appsession value is the |
| data following this prefix. |
| |
| Example : |
| appsession ASPSESSIONID len 64 timeout 3h prefix |
| |
| This will match the cookie ASPSESSIONIDXXXX=XXXXX, |
| the appsession value will be XXXX=XXXXX. |
| |
| mode This option allows to change the URL parser mode. |
| 2 modes are currently supported : |
| - path-parameters : |
| The parser looks for the appsession in the path parameters |
| part (each parameter is separated by a semi-colon), which is |
| convenient for JSESSIONID for example. |
| This is the default mode if the option is not set. |
| - query-string : |
| In this mode, the parser will look for the appsession in the |
| query string. |
| |
| When an application cookie is defined in a backend, HAProxy will check when |
| the server sets such a cookie, and will store its value in a table, and |
| associate it with the server's identifier. Up to <length> characters from |
| the value will be retained. On each connection, haproxy will look for this |
| cookie both in the "Cookie:" headers, and as a URL parameter (depending on |
| the mode used). If a known value is found, the client will be directed to the |
| server associated with this value. Otherwise, the load balancing algorithm is |
| applied. Cookies are automatically removed from memory when they have been |
| unused for a duration longer than <holdtime>. |
| |
| The definition of an application cookie is limited to one per backend. |
| |
| Note : Consider not using this feature in multi-process mode (nbproc > 1) |
| unless you know what you do : memory is not shared between the |
| processes, which can result in random behaviours. |
| |
| Example : |
| appsession JSESSIONID len 52 timeout 3h |
| |
| See also : "cookie", "capture cookie", "balance", "stick", "stick-table", |
| "ignore-persist", "nbproc" and "bind-process". |
| |
| |
| backlog <conns> |
| Give hints to the system about the approximate listen backlog desired size |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <conns> is the number of pending connections. Depending on the operating |
| system, it may represent the number of already acknowledged |
| connections, of non-acknowledged ones, or both. |
| |
| In order to protect against SYN flood attacks, one solution is to increase |
| the system's SYN backlog size. Depending on the system, sometimes it is just |
| tunable via a system parameter, sometimes it is not adjustable at all, and |
| sometimes the system relies on hints given by the application at the time of |
| the listen() syscall. By default, HAProxy passes the frontend's maxconn value |
| to the listen() syscall. On systems which can make use of this value, it can |
| sometimes be useful to be able to specify a different value, hence this |
| backlog parameter. |
| |
| On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is |
| used as a hint and the system accepts up to the smallest greater power of |
| two, and never more than some limits (usually 32768). |
| |
| See also : "maxconn" and the target operating system's tuning guide. |
| |
| |
| balance <algorithm> [ <arguments> ] |
| balance url_param <param> [check_post] |
| 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 4095 active servers per backend. Note that in some |
| large farms, when a server becomes up after having been down |
| for a very short time, it may sometimes take a few hundreds |
| requests for it to be re-integrated into the farm and start |
| receiving traffic. This is normal, though very rare. It is |
| indicated here in case you would have the chance to observe |
| it, so that you don't worry. |
| |
| static-rr Each server is used in turns, according to their weights. |
| This algorithm is as similar to roundrobin except that it is |
| static, which means that changing a server's weight on the |
| fly will have no effect. On the other hand, it has no design |
| limitation on the number of servers, and when a server goes |
| up, it is always immediately reintroduced into the farm, once |
| the full map is recomputed. It also uses slightly less CPU to |
| run (around -1%). |
| |
| leastconn The server with the lowest number of connections receives the |
| connection. Round-robin is performed within groups of servers |
| of the same load to ensure that all servers will be used. Use |
| of this algorithm is recommended where very long sessions are |
| expected, such as LDAP, SQL, TSE, etc... but is not very well |
| suited for protocols using short sessions such as HTTP. This |
| algorithm is dynamic, which means that server weights may be |
| adjusted on the fly for slow starts for instance. |
| |
| first The first server with available connection slots receives the |
| connection. The servers are chosen from the lowest numeric |
| identifier to the highest (see server parameter "id"), which |
| defaults to the server's position in the farm. Once a server |
| reaches its maxconn value, the next server is used. It does |
| not make sense to use this algorithm without setting maxconn. |
| The purpose of this algorithm is to always use the smallest |
| number of servers so that extra servers can be powered off |
| during non-intensive hours. This algorithm ignores the server |
| weight, and brings more benefit to long session such as RDP |
| or IMAP than HTTP, though it can be useful there too. In |
| order to use this algorithm efficiently, it is recommended |
| that a cloud controller regularly checks server usage to turn |
| them off when unused, and regularly checks backend queue to |
| turn new servers on when the queue inflates. Alternatively, |
| using "http-check send-state" may inform servers on the load. |
| |
| source The source IP address is hashed and divided by the total |
| weight of the running servers to designate which server will |
| receive the request. This ensures that the same client IP |
| address will always reach the same server as long as no |
| server goes down or up. If the hash result changes due to the |
| number of running servers changing, many clients will be |
| directed to a different server. This algorithm is generally |
| used in TCP mode where no cookie may be inserted. It may also |
| be used on the Internet to provide a best-effort stickiness |
| to clients which refuse session cookies. This algorithm is |
| static by default, which means that changing a server's |
| weight on the fly will have no effect, but this can be |
| changed using "hash-type". |
| |
| uri This algorithm hashes either the left part of the URI (before |
| the question mark) or the whole URI (if the "whole" parameter |
| is present) and divides the hash value by the total weight of |
| the running servers. The result designates which server will |
| receive the request. This ensures that the same URI will |
| always be directed to the same server as long as no server |
| goes up or down. This is used with proxy caches and |
| anti-virus proxies in order to maximize the cache hit rate. |
| Note that this algorithm may only be used in an HTTP backend. |
| This algorithm is static by default, which means that |
| changing a server's weight on the fly will have no effect, |
| but this can be changed using "hash-type". |
| |
| This algorithm supports two optional parameters "len" and |
| "depth", both followed by a positive integer number. These |
| options may be helpful when it is needed to balance servers |
| based on the beginning of the URI only. The "len" parameter |
| indicates that the algorithm should only consider that many |
| characters at the beginning of the URI to compute the hash. |
| Note that having "len" set to 1 rarely makes sense since most |
| URIs start with a leading "/". |
| |
| The "depth" parameter indicates the maximum directory depth |
| to be used to compute the hash. One level is counted for each |
| slash in the request. If both parameters are specified, the |
| evaluation stops when either is reached. |
| |
| url_param The URL parameter specified in argument will be looked up in |
| the query string of each HTTP GET request. |
| |
| If the modifier "check_post" is used, then an HTTP POST |
| request entity will be searched for the parameter argument, |
| when it is not found in a query string after a question mark |
| ('?') in the URL. The message body will only start to be |
| analyzed once either the advertised amount of data has been |
| received or the request buffer is full. In the unlikely event |
| that chunked encoding is used, only the first chunk is |
| scanned. Parameter values separated by a chunk boundary, may |
| be randomly balanced if at all. This keyword used to support |
| an optional <max_wait> parameter which is now ignored. |
| |
| If the parameter is found followed by an equal sign ('=') and |
| a value, then the value is hashed and divided by the total |
| weight of the running servers. The result designates which |
| server will receive the request. |
| |
| This is used to track user identifiers in requests and ensure |
| that a same user ID will always be sent to the same server as |
| long as no server goes up or down. If no value is found or if |
| the parameter is not found, then a round robin algorithm is |
| applied. Note that this algorithm may only be used in an HTTP |
| backend. This algorithm is static by default, which means |
| that changing a server's weight on the fly will have no |
| effect, but this can be changed using "hash-type". |
| |
| hdr(<name>) The HTTP header <name> will be looked up in each HTTP |
| request. Just as with the equivalent ACL 'hdr()' function, |
| the header name in parenthesis is not case sensitive. If the |
| header is absent or if it does not contain any value, the |
| roundrobin algorithm is applied instead. |
| |
| An optional 'use_domain_only' parameter is available, for |
| reducing the hash algorithm to the main domain part with some |
| specific headers such as 'Host'. For instance, in the Host |
| value "haproxy.1wt.eu", only "1wt" will be considered. |
| |
| This algorithm is static by default, which means that |
| changing a server's weight on the fly will have no effect, |
| but this can be changed using "hash-type". |
| |
| rdp-cookie |
| rdp-cookie(<name>) |
| The RDP cookie <name> (or "mstshash" if omitted) will be |
| looked up and hashed for each incoming TCP request. Just as |
| with the equivalent ACL 'req_rdp_cookie()' function, the name |
| is not case-sensitive. This mechanism is useful as a degraded |
| persistence mode, as it makes it possible to always send the |
| same user (or the same session ID) to the same server. If the |
| cookie is not found, the normal roundrobin algorithm is |
| used instead. |
| |
| Note that for this to work, the frontend must ensure that an |
| RDP cookie is already present in the request buffer. For this |
| you must use 'tcp-request content accept' rule combined with |
| a 'req_rdp_cookie_cnt' ACL. |
| |
| This algorithm is static by default, which means that |
| changing a server's weight on the fly will have no effect, |
| but this can be changed using "hash-type". |
| |
| See also the rdp_cookie pattern fetch function. |
| |
| <arguments> is an optional list of arguments which may be needed by some |
| algorithms. Right now, only "url_param" and "uri" support an |
| optional argument. |
| |
| The load balancing algorithm of a backend is set to roundrobin when no other |
| algorithm, mode nor option have been set. The algorithm may only be set once |
| for each backend. |
| |
| Examples : |
| balance roundrobin |
| balance url_param userid |
| balance url_param session_id check_post 64 |
| balance hdr(User-Agent) |
| balance hdr(host) |
| balance hdr(Host) use_domain_only |
| |
| Note: the following caveats and limitations on using the "check_post" |
| extension with "url_param" must be considered : |
| |
| - all POST requests are eligible for consideration, because there is no way |
| to determine if the parameters will be found in the body or entity which |
| may contain binary data. Therefore another method may be required to |
| restrict consideration of POST requests that have no URL parameters in |
| the body. (see acl reqideny http_end) |
| |
| - using a <max_wait> value larger than the request buffer size does not |
| make sense and is useless. The buffer size is set at build time, and |
| defaults to 16 kB. |
| |
| - Content-Encoding is not supported, the parameter search will probably |
| fail; and load balancing will fall back to Round Robin. |
| |
| - Expect: 100-continue is not supported, load balancing will fall back to |
| Round Robin. |
| |
| - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk. |
| If the entire parameter value is not present in the first chunk, the |
| selection of server is undefined (actually, defined by how little |
| actually appeared in the first chunk). |
| |
| - This feature does not support generation of a 100, 411 or 501 response. |
| |
| - In some cases, requesting "check_post" MAY attempt to scan the entire |
| contents of a message body. Scanning normally terminates when linear |
| white space or control characters are found, indicating the end of what |
| might be a URL parameter list. This is probably not a concern with SGML |
| type message bodies. |
| |
| See also : "dispatch", "cookie", "appsession", "transparent", "hash-type" and |
| "http_proxy". |
| |
| |
| bind [<address>]:<port_range> [, ...] [param*] |
| bind /<path> [, ...] [param*] |
| Define one or several listening addresses and/or ports in a frontend. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <address> is optional and can be a host name, an IPv4 address, an IPv6 |
| address, or '*'. It designates the address the frontend will |
| listen on. If unset, all IPv4 addresses of the system will be |
| listened on. The same will apply for '*' or the system's |
| special address "0.0.0.0". The IPv6 equivalent is '::'. |
| Optionally, an address family prefix may be used before the |
| address to force the family regardless of the address format, |
| which can be useful to specify a path to a unix socket with |
| no slash ('/'). Currently supported prefixes are : |
| - 'ipv4@' -> address is always IPv4 |
| - 'ipv6@' -> address is always IPv6 |
| - 'unix@' -> address is a path to a local unix socket |
| - 'abns@' -> address is in abstract namespace (Linux only). |
| Note: since abstract sockets are not "rebindable", they |
| do not cope well with multi-process mode during |
| soft-restart, so it is better to avoid them if |
| nbproc is greater than 1. The effect is that if the |
| new process fails to start, only one of the old ones |
| will be able to rebind to the socket. |
| - 'fd@<n>' -> use file descriptor <n> inherited from the |
| parent. The fd must be bound and may or may not already |
| be listening. |
| You may want to reference some environment variables in the |
| address parameter, see section 2.3 about environment |
| variables. |
| |
| <port_range> is either a unique TCP port, or a port range for which the |
| proxy will accept connections for the IP address specified |
| above. The port is mandatory for TCP listeners. Note that in |
| the case of an IPv6 address, the port is always the number |
| after the last colon (':'). A range can either be : |
| - a numerical port (ex: '80') |
| - a dash-delimited ports range explicitly stating the lower |
| and upper bounds (ex: '2000-2100') which are included in |
| the range. |
| |
| Particular care must be taken against port ranges, because |
| every <address:port> couple consumes one socket (= a file |
| descriptor), so it's easy to consume lots of descriptors |
| with a simple range, and to run out of sockets. Also, each |
| <address:port> couple must be used only once among all |
| instances running on a same system. Please note that binding |
| to ports lower than 1024 generally require particular |
| privileges to start the program, which are independent of |
| the 'uid' parameter. |
| |
| <path> is a UNIX socket path beginning with a slash ('/'). This is |
| alternative to the TCP listening port. Haproxy will then |
| receive UNIX connections on the socket located at this place. |
| The path must begin with a slash and by default is absolute. |
| It can be relative to the prefix defined by "unix-bind" in |
| the global section. Note that the total length of the prefix |
| followed by the socket path cannot exceed some system limits |
| for UNIX sockets, which commonly are set to 107 characters. |
| |
| <param*> is a list of parameters common to all sockets declared on the |
| same line. These numerous parameters depend on OS and build |
| options and have a complete section dedicated to them. Please |
| refer to section 5 to for more details. |
| |
| It is possible to specify a list of address:port combinations delimited by |
| commas. The frontend will then listen on all of these addresses. There is no |
| fixed limit to the number of addresses and ports which can be listened on in |
| a frontend, as well as there is no limit to the number of "bind" statements |
| in a frontend. |
| |
| Example : |
| listen http_proxy |
| bind :80,:443 |
| bind 10.0.0.1:10080,10.0.0.1:10443 |
| bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy |
| |
| listen http_https_proxy |
| bind :80 |
| bind :443 ssl crt /etc/haproxy/site.pem |
| |
| listen http_https_proxy_explicit |
| bind ipv6@:80 |
| bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem |
| bind unix@ssl-frontend.sock user root mode 600 accept-proxy |
| |
| listen external_bind_app1 |
| bind "fd@${FD_APP1}" |
| |
| See also : "source", "option forwardfor", "unix-bind" and the PROXY protocol |
| documentation, and section 5 about bind options. |
| |
| |
| bind-process [ all | odd | even | <number 1-64>[-<number 1-64>] ] ... |
| 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,...63. This |
| option may be combined with other numbers. |
| |
| even This instance will be enabled on processes 2,4,6,...64. This |
| option may be combined with other numbers. Do not use it |
| with less than 2 processes otherwise some instances might be |
| missing from all processes. |
| |
| number The instance will be enabled on this process number or range, |
| whose values must all be between 1 and 32 or 64 depending on |
| the machine's word size. If a proxy is bound to process |
| numbers greater than the configured global.nbproc, it will |
| either be forced to process #1 if a single process was |
| specified, or to all processes otherwise. |
| |
| 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 or 64 processes |
| using this keyword, but this should be more than enough for most setups. |
| Please note that 'all' really means all processes regardless of the machine's |
| word size, and is not limited to the first 32 or 64. |
| |
| Each "bind" line may further be limited to a subset of the proxy's processes, |
| please consult the "process" bind keyword in section 5.1. |
| |
| When a frontend has no explicit "bind-process" line, it tries to bind to all |
| the processes referenced by its "bind" lines. That means that frontends can |
| easily adapt to their listeners' processes. |
| |
| If some backends are referenced by frontends bound to other processes, the |
| backend automatically inherits the frontend's processes. |
| |
| Example : |
| listen app_ip1 |
| bind 10.0.0.1:80 |
| bind-process odd |
| |
| listen app_ip2 |
| bind 10.0.0.2:80 |
| bind-process even |
| |
| listen management |
| bind 10.0.0.3:80 |
| bind-process 1 2 3 4 |
| |
| listen management |
| bind 10.0.0.4:80 |
| bind-process 1-4 |
| |
| See also : "nbproc" in global section, and "process" in section 5.1. |
| |
| |
| block { if | unless } <condition> |
| Block a layer 7 request if/unless a condition is matched |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| The HTTP request will be blocked very early in the layer 7 processing |
| if/unless <condition> is matched. A 403 error will be returned if the request |
| is blocked. The condition has to reference ACLs (see section 7). This is |
| typically used to deny access to certain sensitive resources if some |
| conditions are met or not met. There is no fixed limit to the number of |
| "block" statements per instance. |
| |
| Example: |
| acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| acl invalid_src src_port 0:1023 |
| acl local_dst hdr(host) -i localhost |
| block if invalid_src || local_dst |
| |
| See section 7 about ACL usage. |
| |
| |
| capture cookie <name> len <length> |
| Capture and log a cookie in the request and in the response. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments : |
| <name> is the beginning of the name of the cookie to capture. In order |
| to match the exact name, simply suffix the name with an equal |
| sign ('='). The full name will appear in the logs, which is |
| useful with application servers which adjust both the cookie name |
| and value (eg: ASPSESSIONXXXXX). |
| |
| <length> is the maximum number of characters to report in the logs, which |
| include the cookie name, the equal sign and the value, all in the |
| standard "name=value" form. The string will be truncated on the |
| right if it exceeds <length>. |
| |
| Only the first cookie is captured. Both the "cookie" request headers and the |
| "set-cookie" response headers are monitored. This is particularly useful to |
| check for application bugs causing session crossing or stealing between |
| users, because generally the user's cookies can only change on a login page. |
| |
| When the cookie was not presented by the client, the associated log column |
| will report "-". When a request does not cause a cookie to be assigned by the |
| server, a "-" is reported in the response column. |
| |
| The capture is performed in the frontend only because it is necessary that |
| the log format does not change for a given frontend depending on the |
| backends. This may change in the future. Note that there can be only one |
| "capture cookie" statement in a frontend. The maximum capture length is set |
| by the global "tune.http.cookielen" setting and defaults to 63 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 last 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>. |
| |
| The complete 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 nor to their |
| length, though it is wise to keep them low to limit memory usage per session. |
| 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 last 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>. |
| |
| The complete 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 nor to their |
| length, though it is wise to keep them low to limit memory usage per session. |
| In order to keep log format consistent for a same frontend, header captures |
| can only be declared in a frontend. It is not possible to specify a capture |
| in a "defaults" section. |
| |
| Example: |
| capture response header Content-length len 9 |
| capture response header Location len 15 |
| |
| See also : "capture cookie", "capture request header" as well as section 8 |
| about logging. |
| |
| |
| clitimeout <timeout> (deprecated) |
| Set the maximum inactivity time on the client side. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | no |
| Arguments : |
| <timeout> is the timeout value is specified in milliseconds by default, but |
| can be in any other unit if the number is suffixed by the unit, |
| as explained at the top of this document. |
| |
| The inactivity timeout applies when the client is expected to acknowledge or |
| send data. In HTTP mode, this timeout is particularly important to consider |
| during the first phase, when the client sends the request, and during the |
| response while it is reading data sent by the server. The value is specified |
| in milliseconds by default, but can be in any other unit if the number is |
| suffixed by the unit, as specified at the top of this document. In TCP mode |
| (and to a lesser extent, in HTTP mode), it is highly recommended that the |
| client timeout remains equal to the server timeout in order to avoid complex |
| situations to debug. It is a good practice to cover one or several TCP packet |
| losses by specifying timeouts that are slightly above multiples of 3 seconds |
| (eg: 4 or 5 seconds). |
| |
| This parameter is specific to frontends, but can be specified once for all in |
| "defaults" sections. This is in fact one of the easiest solutions not to |
| forget about it. An unspecified timeout results in an infinite timeout, which |
| is not recommended. Such a usage is accepted and works but reports a warning |
| during startup because it may results in accumulation of expired sessions in |
| the system if the system's timeouts are not configured either. |
| |
| This parameter is provided for compatibility but is currently deprecated. |
| Please use "timeout client" instead. |
| |
| See also : "timeout client", "timeout http-request", "timeout server", and |
| "srvtimeout". |
| |
| compression algo <algorithm> ... |
| compression type <mime type> ... |
| compression offload |
| Enable HTTP compression. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| algo is followed by the list of supported compression algorithms. |
| type is followed by the list of MIME types that will be compressed. |
| offload makes haproxy work as a compression offloader only (see notes). |
| |
| The currently supported algorithms are : |
| identity this is mostly for debugging, and it was useful for developing |
| the compression feature. Identity does not apply any change on |
| data. |
| |
| gzip applies gzip compression. This setting is only available when |
| support for zlib was built in. |
| |
| deflate same as "gzip", but with deflate algorithm and zlib format. |
| Note that this algorithm has ambiguous support on many |
| browsers and no support at all from recent ones. It is |
| strongly recommended not to use it for anything else than |
| experimentation. This setting is only available when support |
| for zlib was built in. |
| |
| raw-deflate same as "deflate" without the zlib wrapper, and used as an |
| alternative when the browser wants "deflate". All major |
| browsers understand it and despite violating the standards, |
| it is known to work better than "deflate", at least on MSIE |
| and some versions of Safari. Do not use it in conjunction |
| with "deflate", use either one or the other since both react |
| to the same Accept-Encoding token. This setting is only |
| available when support for zlib was built in. |
| |
| Compression will be activated depending on the Accept-Encoding request |
| header. With identity, it does not take care of that header. |
| If backend servers support HTTP compression, these directives |
| will be no-op: haproxy will see the compressed response and will not |
| compress again. If backend servers do not support HTTP compression and |
| there is Accept-Encoding header in request, haproxy will compress the |
| matching response. |
| |
| The "offload" setting makes haproxy remove the Accept-Encoding header to |
| prevent backend servers from compressing responses. It is strongly |
| recommended not to do this because this means that all the compression work |
| will be done on the single point where haproxy is located. However in some |
| deployment scenarios, haproxy may be installed in front of a buggy gateway |
| with broken HTTP compression implementation which can't be turned off. |
| In that case haproxy can be used to prevent that gateway from emitting |
| invalid payloads. In this case, simply removing the header in the |
| configuration does not work because it applies before the header is parsed, |
| so that prevents haproxy from compressing. The "offload" setting should |
| then be used for such scenarios. Note: for now, the "offload" setting is |
| ignored when set in a defaults section. |
| |
| Compression is disabled when: |
| * the request does not advertise a supported compression algorithm in the |
| "Accept-Encoding" header |
| * the response message is not HTTP/1.1 |
| * HTTP status code is not 200 |
| * response header "Transfer-Encoding" contains "chunked" (Temporary |
| Workaround) |
| * response contain neither a "Content-Length" header nor a |
| "Transfer-Encoding" whose last value is "chunked" |
| * response contains a "Content-Type" header whose first value starts with |
| "multipart" |
| * the response contains the "no-transform" value in the "Cache-control" |
| header |
| * User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7 |
| and later |
| * The response contains a "Content-Encoding" header, indicating that the |
| response is already compressed (see compression offload) |
| |
| Note: The compression does not rewrite Etag headers, and does not emit the |
| Warning header. |
| |
| Examples : |
| compression algo gzip |
| compression type text/html text/plain |
| |
| contimeout <timeout> (deprecated) |
| Set the maximum time to wait for a connection attempt to a server to succeed. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <timeout> is the timeout value is specified in milliseconds by default, but |
| can be in any other unit if the number is suffixed by the unit, |
| as explained at the top of this document. |
| |
| If the server is located on the same LAN as haproxy, the connection should be |
| immediate (less than a few milliseconds). Anyway, it is a good practice to |
| cover one or several TCP packet losses by specifying timeouts that are |
| slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the |
| connect timeout also presets the queue timeout to the same value if this one |
| has not been specified. Historically, the contimeout was also used to set the |
| tarpit timeout in a listen section, which is not possible in a pure frontend. |
| |
| This parameter is specific to backends, but can be specified once for all in |
| "defaults" sections. This is in fact one of the easiest solutions not to |
| forget about it. An unspecified timeout results in an infinite timeout, which |
| is not recommended. Such a usage is accepted and works but reports a warning |
| during startup because it may results in accumulation of failed sessions in |
| the system if the system's timeouts are not configured either. |
| |
| This parameter is provided for backwards compatibility but is currently |
| deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit" |
| instead. |
| |
| See also : "timeout connect", "timeout queue", "timeout tarpit", |
| "timeout server", "contimeout". |
| |
| |
| cookie <name> [ rewrite | insert | prefix ] [ indirect ] [ nocache ] |
| [ postonly ] [ preserve ] [ httponly ] [ secure ] |
| [ domain <domain> ]* [ maxidle <idle> ] [ maxlife <life> ] |
| Enable cookie-based persistence in a backend. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <name> is the name of the cookie which will be monitored, modified or |
| inserted in order to bring persistence. This cookie is sent to |
| the client via a "Set-Cookie" header in the response, and is |
| brought back by the client in a "Cookie" header in all requests. |
| Special care should be taken to choose a name which does not |
| conflict with any likely application cookie. Also, if the same |
| backends are subject to be used by the same clients (eg: |
| HTTP/HTTPS), care should be taken to use different cookie names |
| between all backends if persistence between them is not desired. |
| |
| rewrite This keyword indicates that the cookie will be provided by the |
| server and that haproxy will have to modify its value to set the |
| server's identifier in it. This mode is handy when the management |
| of complex combinations of "Set-cookie" and "Cache-control" |
| headers is left to the application. The application can then |
| decide whether or not it is appropriate to emit a persistence |
| cookie. Since all responses should be monitored, this mode only |
| works in HTTP close mode. Unless the application behaviour is |
| very complex and/or broken, it is advised not to start with this |
| mode for new deployments. This keyword is incompatible with |
| "insert" and "prefix". |
| |
| insert This keyword indicates that the persistence cookie will have to |
| be inserted by haproxy in server responses if the client did not |
| |
| already have a cookie that would have permitted it to access this |
| server. When used without the "preserve" option, if the server |
| emits a cookie with the same name, it will be remove before |
| processing. For this reason, this mode can be used to upgrade |
| existing configurations running in the "rewrite" mode. The cookie |
| will only be a session cookie and will not be stored on the |
| client's disk. By default, unless the "indirect" option is added, |
| the server will see the cookies emitted by the client. Due to |
| caching effects, it is generally wise to add the "nocache" or |
| "postonly" keywords (see below). The "insert" keyword is not |
| compatible with "rewrite" and "prefix". |
| |
| prefix This keyword indicates that instead of relying on a dedicated |
| cookie for the persistence, an existing one will be completed. |
| This may be needed in some specific environments where the client |
| does not support more than one single cookie and the application |
| already needs it. In this case, whenever the server sets a cookie |
| named <name>, it will be prefixed with the server's identifier |
| and a delimiter. The prefix will be removed from all client |
| requests so that the server still finds the cookie it emitted. |
| Since all requests and responses are subject to being modified, |
| this mode requires the HTTP close mode. The "prefix" keyword is |
| not compatible with "rewrite" and "insert". Note: it is highly |
| recommended not to use "indirect" with "prefix", otherwise server |
| cookie updates would not be sent to clients. |
| |
| indirect When this option is specified, no cookie will be emitted to a |
| client which already has a valid one for the server which has |
| processed the request. If the server sets such a cookie itself, |
| it will be removed, unless the "preserve" option is also set. In |
| "insert" mode, this will additionally remove cookies from the |
| requests transmitted to the server, making the persistence |
| mechanism totally transparent from an application point of view. |
| Note: it is highly recommended not to use "indirect" with |
| "prefix", otherwise server cookie updates would not be sent to |
| clients. |
| |
| nocache This option is recommended in conjunction with the insert mode |
| when there is a cache between the client and HAProxy, as it |
| ensures that a cacheable response will be tagged non-cacheable if |
| a cookie needs to be inserted. This is important because if all |
| persistence cookies are added on a cacheable home page for |
| instance, then all customers will then fetch the page from an |
| outer cache and will all share the same persistence cookie, |
| leading to one server receiving much more traffic than others. |
| See also the "insert" and "postonly" options. |
| |
| postonly This option ensures that cookie insertion will only be performed |
| on responses to POST requests. It is an alternative to the |
| "nocache" option, because POST responses are not cacheable, so |
| this ensures that the persistence cookie will never get cached. |
| Since most sites do not need any sort of persistence before the |
| first POST which generally is a login request, this is a very |
| efficient method to optimize caching without risking to find a |
| persistence cookie in the cache. |
| See also the "insert" and "nocache" options. |
| |
| preserve This option may only be used with "insert" and/or "indirect". It |
| allows the server to emit the persistence cookie itself. In this |
| case, if a cookie is found in the response, haproxy will leave it |
| untouched. This is useful in order to end persistence after a |
| logout request for instance. For this, the server just has to |
| emit a cookie with an invalid value (eg: empty) or with a date in |
| the past. By combining this mechanism with the "disable-on-404" |
| check option, it is possible to perform a completely graceful |
| shutdown because users will definitely leave the server after |
| they logout. |
| |
| httponly This option tells haproxy to add an "HttpOnly" cookie attribute |
| when a cookie is inserted. This attribute is used so that a |
| user agent doesn't share the cookie with non-HTTP components. |
| Please check RFC6265 for more information on this attribute. |
| |
| secure This option tells haproxy to add a "Secure" cookie attribute when |
| a cookie is inserted. This attribute is used so that a user agent |
| never emits this cookie over non-secure channels, which means |
| that a cookie learned with this flag will be presented only over |
| SSL/TLS connections. Please check RFC6265 for more information on |
| this attribute. |
| |
| domain This option allows to specify the domain at which a cookie is |
| inserted. It requires exactly one parameter: a valid domain |
| name. If the domain begins with a dot, the browser is allowed to |
| use it for any host ending with that name. It is also possible to |
| specify several domain names by invoking this option multiple |
| times. Some browsers might have small limits on the number of |
| domains, so be careful when doing that. For the record, sending |
| 10 domains to MSIE 6 or Firefox 2 works as expected. |
| |
| maxidle This option allows inserted cookies to be ignored after some idle |
| time. It only works with insert-mode cookies. When a cookie is |
| sent to the client, the date this cookie was emitted is sent too. |
| Upon further presentations of this cookie, if the date is older |
| than the delay indicated by the parameter (in seconds), it will |
| be ignored. Otherwise, it will be refreshed if needed when the |
| response is sent to the client. This is particularly useful to |
| prevent users who never close their browsers from remaining for |
| too long on the same server (eg: after a farm size change). When |
| this option is set and a cookie has no date, it is always |
| accepted, but gets refreshed in the response. This maintains the |
| ability for admins to access their sites. Cookies that have a |
| date in the future further than 24 hours are ignored. Doing so |
| lets admins fix timezone issues without risking kicking users off |
| the site. |
| |
| maxlife This option allows inserted cookies to be ignored after some life |
| time, whether they're in use or not. It only works with insert |
| mode cookies. When a cookie is first sent to the client, the date |
| this cookie was emitted is sent too. Upon further presentations |
| of this cookie, if the date is older than the delay indicated by |
| the parameter (in seconds), it will be ignored. If the cookie in |
| the request has no date, it is accepted and a date will be set. |
| Cookies that have a date in the future further than 24 hours are |
| ignored. Doing so lets admins fix timezone issues without risking |
| kicking users off the site. Contrary to maxidle, this value is |
| not refreshed, only the first visit date counts. Both maxidle and |
| maxlife may be used at the time. This is particularly useful to |
| prevent users who never close their browsers from remaining for |
| too long on the same server (eg: after a farm size change). This |
| is stronger than the maxidle method in that it forces a |
| redispatch after some absolute delay. |
| |
| There can be only one persistence cookie per HTTP backend, and it can be |
| declared in a defaults section. The value of the cookie will be the value |
| indicated after the "cookie" keyword in a "server" statement. If no cookie |
| is declared for a given server, the cookie is not set. |
| |
| Examples : |
| cookie JSESSIONID prefix |
| cookie SRV insert indirect nocache |
| cookie SRV insert postonly indirect |
| cookie SRV insert indirect nocache maxidle 30m maxlife 8h |
| |
| See also : "appsession", "balance source", "capture cookie", "server" |
| and "ignore-persist". |
| |
| |
| declare capture [ request | response ] len <length> |
| Declares a capture slot. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | no |
| Arguments: |
| <length> is the length allowed for the capture. |
| |
| This declaration is only available in the frontend or listen section, but the |
| reserved slot can be used in the backends. The "request" keyword allocates a |
| capture slot for use in the request, and "response" allocates a capture slot |
| for use in the response. |
| |
| See also: "capture-req", "capture-res" (sample converters), |
| "http-request capture" and "http-response capture". |
| |
| |
| 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" |
| |
| |
| description <string> |
| Describe a listen, frontend or backend. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : string |
| |
| Allows to add a sentence to describe the related object in the HAProxy HTML |
| stats page. The description will be printed on the right of the object name |
| it describes. |
| No need to backslash spaces in the <string> arguments. |
| |
| |
| disabled |
| Disable a proxy, frontend or backend. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| The "disabled" keyword is used to disable an instance, mainly in order to |
| liberate a listening port or to temporarily disable a service. The instance |
| will still be created and its configuration will be checked, but it will be |
| created in the "stopped" state and will appear as such in the statistics. It |
| will not receive any traffic nor will it send any health-checks or logs. It |
| is possible to disable many instances at once by adding the "disabled" |
| keyword in a "defaults" section. |
| |
| See also : "enabled" |
| |
| |
| dispatch <address>:<port> |
| Set a default server address |
| May be used in sections : defaults | frontend | listen | backend |
| no | no | yes | yes |
| Arguments : |
| |
| <address> is the IPv4 address of the default server. Alternatively, a |
| resolvable hostname is supported, but this name will be resolved |
| during start-up. |
| |
| <ports> is a mandatory port specification. All connections will be sent |
| to this port, and it is not permitted to use port offsets as is |
| possible with normal servers. |
| |
| The "dispatch" keyword designates a default server for use when no other |
| server can take the connection. In the past it was used to forward non |
| persistent connections to an auxiliary load balancer. Due to its simple |
| syntax, it has also been used for simple TCP relays. It is recommended not to |
| use it for more clarity, and to use the "server" directive instead. |
| |
| See also : "server" |
| |
| |
| enabled |
| Enable a proxy, frontend or backend. |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : none |
| |
| The "enabled" keyword is used to explicitly enable an instance, when the |
| defaults has been set to "disabled". This is very rarely used. |
| |
| See also : "disabled" |
| |
| |
| errorfile <code> <file> |
| Return a file contents instead of errors generated by HAProxy |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <code> is the HTTP status code. Currently, HAProxy is capable of |
| generating codes 200, 400, 403, 405, 408, 429, 500, 502, 503, and |
| 504. |
| |
| <file> designates a file containing the full HTTP response. It is |
| recommended to follow the common practice of appending ".http" to |
| the filename so that people do not confuse the response with HTML |
| error pages, and to use absolute paths, since files are read |
| before any chroot is performed. |
| |
| It is important to understand that this keyword is not meant to rewrite |
| errors returned by the server, but errors detected and returned by HAProxy. |
| This is why the list of supported errors is limited to a small set. |
| |
| Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| |
| The files are returned verbatim on the TCP socket. This allows any trick such |
| as redirections to another URL or site, as well as tricks to clean cookies, |
| force enable or disable caching, etc... The package provides default error |
| files returning the same contents as default errors. |
| |
| The files should not exceed the configured buffer size (BUFSIZE), which |
| generally is 8 or 16 kB, otherwise they will be truncated. It is also wise |
| not to put any reference to local contents (eg: images) in order to avoid |
| loops between the client and HAProxy when all servers are down, causing an |
| error to be returned instead of an image. For better HTTP compliance, it is |
| recommended that all header lines end with CR-LF and not LF alone. |
| |
| The files are read at the same time as the configuration and kept in memory. |
| For this reason, the errors continue to be returned even when the process is |
| chrooted, and no file change is considered while the process is running. A |
| simple method for developing those files consists in associating them to the |
| 403 status code and interrogating a blocked URL. |
| |
| See also : "errorloc", "errorloc302", "errorloc303" |
| |
| Example : |
| errorfile 400 /etc/haproxy/errorfiles/400badreq.http |
| errorfile 408 /dev/null # workaround Chrome pre-connect bug |
| errorfile 403 /etc/haproxy/errorfiles/403forbid.http |
| errorfile 503 /etc/haproxy/errorfiles/503sorry.http |
| |
| |
| errorloc <code> <url> |
| errorloc302 <code> <url> |
| Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <code> is the HTTP status code. Currently, HAProxy is capable of |
| generating codes 200, 400, 403, 408, 500, 502, 503, and 504. |
| |
| <url> it is the exact contents of the "Location" header. It may contain |
| either a relative URI to an error page hosted on the same site, |
| or an absolute URI designating an error page on another site. |
| Special care should be given to relative URIs to avoid redirect |
| loops if the URI itself may generate the same error (eg: 500). |
| |
| It is important to understand that this keyword is not meant to rewrite |
| errors returned by the server, but errors detected and returned by HAProxy. |
| This is why the list of supported errors is limited to a small set. |
| |
| Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| |
| Note that both keyword return the HTTP 302 status code, which tells the |
| client to fetch the designated URL using the same HTTP method. This can be |
| quite problematic in case of non-GET methods such as POST, because the URL |
| sent to the client might not be allowed for something other than GET. To |
| workaround this problem, please use "errorloc303" which send the HTTP 303 |
| status code, indicating to the client that the URL must be fetched with a GET |
| request. |
| |
| See also : "errorfile", "errorloc303" |
| |
| |
| errorloc303 <code> <url> |
| Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| May be used in sections : defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| Arguments : |
| <code> is the HTTP status code. Currently, HAProxy is capable of |
| generating codes 400, 403, 408, 500, 502, 503, and 504. |
| |
| <url> it is the exact contents of the "Location" header. It may contain |
| either a relative URI to an error page hosted on the same site, |
| or an absolute URI designating an error page on another site. |
| Special care should be given to relative URIs to avoid redirect |
| loops if the URI itself may generate the same error (eg: 500). |
| |
| It is important to understand that this keyword is not meant to rewrite |
| errors returned by the server, but errors detected and returned by HAProxy. |
| This is why the list of supported errors is limited to a small set. |
| |
| Code 200 is emitted in response to requests matching a "monitor-uri" rule. |
| |
| Note that both keyword return the HTTP 303 status code, which tells the |
| client to fetch the designated URL using the same HTTP GET method. This |
| solves the usual problems associated with "errorloc" and the 302 code. It is |
| possible that some very old browsers designed before HTTP/1.1 do not support |
| it, but no such problem has been reported till now. |
| |
| See also : "errorfile", "errorloc", "errorloc302" |
| |
| |
| email-alert from <emailaddr> |
| Declare the from email address to be used in both the envelope and header |
| of email alerts. This is the address that email alerts are sent from. |
| May be used in sections: defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| |
| Arguments : |
| |
| <emailaddr> is the from email address to use when sending email alerts |
| |
| Also requires "email-alert mailers" and "email-alert to" to be set |
| and if so sending email alerts is enabled for the proxy. |
| |
| See also : "email-alert level", "email-alert mailers", |
| "email-alert myhostname", "email-alert to", section 3.6 about mailers. |
| |
| |
| email-alert level <level> |
| Declare the maximum log level of messages for which email alerts will be |
| sent. This acts as a filter on the sending of email alerts. |
| May be used in sections: defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| |
| Arguments : |
| |
| <level> One of the 8 syslog levels: |
| emerg alert crit err warning notice info debug |
| The above syslog levels are ordered from lowest to highest. |
| |
| By default level is alert |
| |
| Also requires "email-alert from", "email-alert mailers" and |
| "email-alert to" to be set and if so sending email alerts is enabled |
| for the proxy. |
| |
| Alerts are sent when : |
| |
| * An un-paused server is marked as down and <level> is alert or lower |
| * A paused server is marked as down and <level> is notice or lower |
| * A server is marked as up or enters the drain state and <level> |
| is notice or lower |
| * "option log-health-checks" is enabled, <level> is info or lower, |
| and a health check status update occurs |
| |
| See also : "email-alert from", "email-alert mailers", |
| "email-alert myhostname", "email-alert to", |
| section 3.6 about mailers. |
| |
| |
| email-alert mailers <mailersect> |
| Declare the mailers to be used when sending email alerts |
| May be used in sections: defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| |
| Arguments : |
| |
| <mailersect> is the name of the mailers section to send email alerts. |
| |
| Also requires "email-alert from" and "email-alert to" to be set |
| and if so sending email alerts is enabled for the proxy. |
| |
| See also : "email-alert from", "email-alert level", "email-alert myhostname", |
| "email-alert to", section 3.6 about mailers. |
| |
| |
| email-alert myhostname <hostname> |
| Declare the to hostname address to be used when communicating with |
| mailers. |
| May be used in sections: defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| |
| Arguments : |
| |
| <emailaddr> is the to email address to use when sending email alerts |
| |
| By default the systems hostname is used. |
| |
| Also requires "email-alert from", "email-alert mailers" and |
| "email-alert to" to be set and if so sending email alerts is enabled |
| for the proxy. |
| |
| See also : "email-alert from", "email-alert level", "email-alert mailers", |
| "email-alert to", section 3.6 about mailers. |
| |
| |
| email-alert to <emailaddr> |
| Declare both the recipent address in the envelope and to address in the |
| header of email alerts. This is the address that email alerts are sent to. |
| May be used in sections: defaults | frontend | listen | backend |
| yes | yes | yes | yes |
| |
| Arguments : |
| |
| <emailaddr> is the to email address to use when sending email alerts |
| |
| Also requires "email-alert mailers" and "email-alert to" to be set |
| and if so sending email alerts is enabled for the proxy. |
| |
| See also : "email-alert from", "email-alert level", "email-alert mailers", |
| "email-alert myhostname", section 3.6 about mailers. |
| |
| |
| force-persist { if | unless } <condition> |
| Declare a condition to force persistence on down servers |
| May be used in sections: defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| By default, requests are not dispatched to down servers. It is possible to |
| force this using "option persist", but it is unconditional and redispatches |
| to a valid server if "option redispatch" is set. That leaves with very little |
| possibilities to force some requests to reach a server which is artificially |
| marked down for maintenance operations. |
| |
| The "force-persist" statement allows one to declare various ACL-based |
| conditions which, when met, will cause a request to ignore the down status of |
| a server and still try to connect to it. That makes it possible to start a |
| server, still replying an error to the health checks, and run a specially |
| configured browser to test the service. Among the handy methods, one could |
| use a specific source IP address, or a specific cookie. The cookie also has |
| the advantage that it can easily be added/removed on the browser from a test |
| page. Once the service is validated, it is then possible to open the service |
| to the world by returning a valid response to health checks. |
| |
| The forced persistence is enabled when an "if" condition is met, or unless an |
| "unless" condition is met. The final redispatch is always disabled when this |
| is used. |
| |
| See also : "option redispatch", "ignore-persist", "persist", |
| and section 7 about ACL usage. |
| |
| |
| fullconn <conns> |
| Specify at what backend load the servers will reach their maxconn |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <conns> is the number of connections on the backend which will make the |
| servers use the maximal number of connections. |
| |
| When a server has a "maxconn" parameter specified, it means that its number |
| of concurrent connections will never go higher. Additionally, if it has a |
| "minconn" parameter, it indicates a dynamic limit following the backend's |
| load. The server will then always accept at least <minconn> connections, |
| never more than <maxconn>, and the limit will be on the ramp between both |
| values when the backend has less than <conns> concurrent connections. This |
| makes it possible to limit the load on the servers during normal loads, but |
| push it further for important loads without overloading the servers during |
| exceptional loads. |
| |
| Since it's hard to get this value right, haproxy automatically sets it to |
| 10% of the sum of the maxconns of all frontends that may branch to this |
| backend (based on "use_backend" and "default_backend" rules). That way it's |
| safe to leave it unset. However, "use_backend" involving dynamic names are |
| not counted since there is no way to know if they could match or not. |
| |
| 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> <function> <modifier> |
| Specify a method to use for mapping hashes to servers |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <method> is the method used to select a server from the hash computed by |
| the <function> : |
| |
| 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. |
| |
| 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 method for caches. |
| However, due to its principle, the distribution 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 exact |
| same IDs. Note: consistent hash uses sdbm and avalanche if no |
| hash function is specified. |
| |
| <function> is the hash function to be used : |
| |
| sdbm this function was created initially for sdbm (a public-domain |
| reimplementation of ndbm) database library. It was found to do |
| well in scrambling bits, causing better distribution of the keys |
| and fewer splits. It also happens to be a good general hashing |
| function with good distribution, unless the total server weight |
| is a multiple of 64, in which case applying the avalanche |
| modifier may help. |
| |
| djb2 this function was first proposed by Dan Bernstein many years ago |
| on comp.lang.c. Studies have shown that for certain workload this |
| function provides a better distribution than sdbm. It generally |
| works well with text-based inputs though it can perform extremely |
| poorly with numeric-only input or when the total server weight is |
| a multiple of 33, unless the avalanche modifier is also used. |
| |
| wt6 this function was designed for haproxy while testing other |
| functions in the past. It is not as smooth as the other ones, but |
| is much less sensible to the input data set or to the number of |
| servers. It can make sense as an alternative to sdbm+avalanche or |
| djb2+avalanche for consistent hashing or when hashing on numeric |
| data such as a source IP address or a visitor identifier in a URL |
| parameter. |
| |
| crc32 this is the most common CRC32 implementation as used in Ethernet, |
| gzip, PNG, etc. It is slower than the other ones but may provide |
| a better distribution or less predictable results especially when |
| used on strings. |
| |
| <modifier> indicates an optional method applied after hashing the key : |
| |
| avalanche This directive indicates that the result from the hash |
| function above should not be used in its raw form but that |
| a 4-byte full avalanche hash must be applied first. The |
| purpose of this step is to mix the resulting bits from the |
| previous hash in order to avoid any undesired effect when |
| the input contains some limited values or when the number of |
| servers is a multiple of one of the hash's components (64 |
| for SDBM, 33 for DJB2). Enabling avalanche tends to make the |
| result less predictable, but it's also not as smooth as when |
| using the original function. Some testing might be needed |
| with some workloads. This hash is one of the many proposed |
| by Bob Jenkins. |
| |
| The default hash type is "map-based" and is recommended for most usages. The |
| default function is "sdbm", the selection of a function should be based on |
| the range of the values being hashed. |
| |
| See also : "balance", "server" |
| |
| |
| http-check disable-on-404 |
| Enable a maintenance mode upon HTTP/404 response to health-checks |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| When this option is set, a server which returns an HTTP code 404 will be |
| excluded from further load-balancing, but will still receive persistent |
| connections. This provides a very convenient method for Web administrators |
| to perform a graceful shutdown of their servers. It is also important to note |
| that a server which is detected as failed while it was in this mode will not |
| generate an alert, just a notice. If the server responds 2xx or 3xx again, it |
| will immediately be reinserted into the farm. The status on the stats page |
| reports "NOLB" for a server in this mode. It is important to note that this |
| option only works in conjunction with the "httpchk" option. If this option |
| is used with "http-check expect", then it has precedence over it so that 404 |
| responses will still be considered as soft-stop. |
| |
| See also : "option httpchk", "http-check expect" |
| |
| |
| http-check expect [!] <match> <pattern> |
| Make HTTP health checks consider response contents or specific status codes |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : |
| <match> is a keyword indicating how to look for a specific pattern in the |
| response. The keyword may be one of "status", "rstatus", |
| "string", or "rstring". The keyword may be preceded by an |
| exclamation mark ("!") to negate the match. Spaces are allowed |
| between the exclamation mark and the keyword. See below for more |
| details on the supported keywords. |
| |
| <pattern> is the pattern to look for. It may be a string or a regular |
| expression. If the pattern contains spaces, they must be escaped |
| with the usual backslash ('\'). |
| |
| By default, "option httpchk" considers that response statuses 2xx and 3xx |
| are valid, and that others are invalid. When "http-check expect" is used, |
| it defines what is considered valid or invalid. Only one "http-check" |
| statement is supported in a backend. If a server fails to respond or times |
| out, the check obviously fails. The available matches are : |
| |
| status <string> : test the exact string match for the HTTP status code. |
| A health check response will be considered valid if the |
| response's status code is exactly this string. If the |
| "status" keyword is prefixed with "!", then the response |
| will be considered invalid if the status code matches. |
| |
| rstatus <regex> : test a regular expression for the HTTP status code. |
| A health check response will be considered valid if the |
| response's status code matches the expression. If the |
| "rstatus" keyword is prefixed with "!", then the response |
| will be considered invalid if the status code matches. |
| This is mostly used to check for multiple codes. |
| |
| string <string> : test the exact string match in the HTTP response body. |
| A health check response will be considered valid if the |
| response's body contains this exact string. If the |
| "string" keyword is prefixed with "!", then the response |
| will be considered invalid if the body contains this |
| string. This can be used to look for a mandatory word at |
| the end of a dynamic page, or to detect a failure when a |
| specific error appears on the check page (eg: a stack |
| trace). |
| |
| rstring <regex> : test a regular expression on the HTTP response body. |
| A health check response will be considered valid if the |
| response's body matches this expression. If the "rstring" |
| keyword is prefixed with "!", then the response will be |
| considered invalid if the body matches the expression. |
| This can be used to look for a mandatory word at the end |
| of a dynamic page, or to detect a failure when a specific |
| error appears on the check page (eg: a stack trace). |
| |
| It is important to note that the responses will be limited to a certain size |
| defined by the global "tune.chksize" option, which defaults to 16384 bytes. |
| Thus, too large responses may not contain the mandatory pattern when using |
| "string" or "rstring". If a large response is absolutely required, it is |
| possible to change the default max size by setting the global variable. |
| However, it is worth keeping in mind that parsing very large responses can |
| waste some CPU cycles, especially when regular expressions are used, and that |
| it is always better to focus the checks on smaller resources. |
| |
| Also "http-check expect" doesn't support HTTP keep-alive. Keep in mind that it |
| will automatically append a "Connection: close" header, meaning that this |
| header should not be present in the request provided by "option httpchk". |
| |
| Last, if "http-check expect" is combined with "http-check disable-on-404", |
| then this last one has precedence when the server responds with 404. |
| |
| Examples : |
| # only accept status 200 as valid |
| http-check expect status 200 |
| |
| # consider SQL errors as errors |
| http-check expect ! string SQL\ Error |
| |
| # consider status 5xx only as errors |
| http-check expect ! rstatus ^5 |
| |
| # check that we have a correct hexadecimal tag before /html |
| http-check expect rstring <!--tag:[0-9a-f]*</html> |
| |
| See also : "option httpchk", "http-check disable-on-404" |
| |
| |
| http-check send-state |
| Enable emission of a state header with HTTP health checks |
| May be used in sections : defaults | frontend | listen | backend |
| yes | no | yes | yes |
| Arguments : none |
| |
| When this option is set, haproxy will systematically send a special header |
| "X-Haproxy-Server-State" with a list of parameters indicating to each server |
| how they are seen by haproxy. This can be used for instance when a server is |
| manipulated without access to haproxy and the operator needs to know whether |
| haproxy still sees it up or not, or if the server is the last one in a farm. |
| |
| The header is composed of fields delimited by semi-colons, the first of which |
| is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid |
| checks on the total number before transition, just as appears in the stats |
| interface. Next headers are in the form "<variable>=<value>", indicating in |
| no specific order some values available in the stats interface : |
| - a variable "address", containing the address of the backend server. |
| This corresponds to the <address> field in the server declaration. For |
| unix domain sockets, it will read "unix". |
| |
| - a variable "port", containing the port of the backend server. This |
| corresponds to the <port> field in the server declaration. For unix |
| domain sockets, it will read "unix". |
| |
| - 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 | tarpit | auth [realm <realm>] | redirect <rule> | |
| add-header <name> <fmt> | set-header <name> <fmt> | |
| capture <sample> [ len <length> | id <id> ] | |
| del-header <name> | set-nice <nice> | set-log-level <level> | |
| replace-header <name> <match-regex> <replace-fmt> | |
| replace-value <name> <match-regex> <replace-fmt> | |
| set-method <fmt> | set-path <fmt> | set-query <fmt> | |
| set-uri <fmt> | set-tos <tos> | set-mark <mark> | |
| add-acl(<file name>) <key fmt> | |
| del-acl(<file name>) <key fmt> | |
| del-map(<file name>) <key fmt> | |
| set-map(<file name>) <key fmt> <value fmt> | |
| set-var(<var name>) <expr> | |
| { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] | |
| lua <function name> |
| } |
| [ { if | unless } <condition> ] |
| Access control for Layer 7 requests |
| |
| May be used in sections: defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| The http-request statement defines a set of rules which apply to layer 7 |
| processing. The rules are evaluated in their declaration order when they are |
| met in a frontend, listen or backend section. Any rule may optionally be |
| followed by an ACL-based condition, in which case it will only be evaluated |
| if the condition is true. |
| |
| The first keyword is the rule's action. Currently supported actions include : |
| - "allow" : this stops the evaluation of the rules and lets the request |
| pass the check. No further "http-request" rules are evaluated. |
| |
| - "deny" : this stops the evaluation of the rules and immediately rejects |
| the request and emits an HTTP 403 error. No further "http-request" rules |
| are evaluated. |
| |
| - "tarpit" : this stops the evaluation of the rules and immediately blocks |
| the request without responding for a delay specified by "timeout tarpit" |
| or "timeout connect" if the former is not set. After that delay, if the |
| client is still connected, an HTTP error 500 is returned so that the |
| client does not suspect it has been tarpitted. Logs will report the flags |
| "PT". The goal of the tarpit rule is to slow down robots during an attack |
| when they're limited on the number of concurrent requests. It can be very |
| efficient against very dumb robots, and will significantly reduce the |
| load on firewalls compared to a "deny" rule. But when facing "correctly" |
| developed robots, it can make things worse by forcing haproxy and the |
| front firewall to support insane number of concurrent connections. |
| |
| - "auth" : this stops the evaluation of the rules and immediately responds |
| with an HTTP 401 or 407 error code to invite the user to present a valid |
| user name and password. No further "http-request" rules are evaluated. An |
| optional "realm" parameter is supported, it sets the authentication realm |
| that is returned with the response (typically the application's name). |
| |
| - "redirect" : this performs an HTTP redirection based on a redirect rule. |
| This is exactly the same as the "redirect" statement except that it |
| inserts a redirect rule which can be processed in the middle of other |
| "http-request" rules and that these rules use the "log-format" strings. |
| See the "redirect" keyword for the rule's syntax. |
| |
| - "add-header" appends an HTTP header field whose name is specified in |
| <name> and whose value is defined by <fmt> which follows the log-format |
| rules (see Custom Log Format in section 8.2.4). This is particularly |
| useful to pass connection-specific information to the server (eg: the |
| client's SSL certificate), or to combine several headers into one. This |
| rule is not final, so it is possible to add other similar rules. Note |
| that header addition is performed immediately, so one rule might reuse |
| the resulting header from a previous rule. |
| |
| - "set-header" does the same as "add-header" except that the header name |
| is first removed if it existed. This is useful when passing security |
| information to the server, where the header must not be manipulated by |
| external users. Note that the new value is computed before the removal so |
| it is possible to concatenate a value to an existing header. |
| |
| - "del-header" removes all HTTP header fields whose name is specified in |
| <name>. |
| |
| - "replace-header" matches the regular expression in all occurrences of |
| header field <name> according to <match-regex>, and replaces them with |
| the <replace-fmt> argument. Format characters are allowed in replace-fmt |
| and work like in <fmt> arguments in "add-header". The match is only |
| case-sensitive. It is important to understand that this action only |
| considers whole header lines, regardless of the number of values they |
| may contain. This usage is suited to headers naturally containing commas |
| in their value, such as If-Modified-Since and so on. |
| |
| Example: |
| |
| http-request replace-header Cookie foo=([^;]*);(.*) foo=\1;ip=%bi;\2 |
| |
| applied to: |
| |
| Cookie: foo=foobar; expires=Tue, 14-Jun-2016 01:40:45 GMT; |
| |
| outputs: |
| |
| Cookie: foo=foobar;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT; |
| |
| assuming the backend IP is 192.168.1.20 |
| |
| - "replace-value" works like "replace-header" except that it matches the |
| regex against every comma-delimited value of the header field <name> |
| instead of the entire header. This is suited for all headers which are |
| allowed to carry more than one value. An example could be the Accept |
| header. |
| |
| Example: |
| |
| http-request replace-value X-Forwarded-For ^192\.168\.(.*)$ 172.16.\1 |
| |
| applied to: |
| |
| X-Forwarded-For: 192.168.10.1, 192.168.13.24, 10.0.0.37 |
| |
| outputs: |
| |
| X-Forwarded-For: 172.16.10.1, 172.16.13.24, 10.0.0.37 |
| |
| - "set-method" rewrites the request method with the result of the |
| evaluation of format string <fmt>. There should be very few valid reasons |
| for having to do so as this is more likely to break something than to fix |
| it. |
| |
| - "set-path" rewrites the request path with the result of the evaluation of |
| format string <fmt>. The query string, if any, is left intact. If a |
| scheme and authority is found before the path, they are left intact as |
| well. If the request doesn't have a path ("*"), this one is replaced with |
| the format. This can be used to prepend a directory component in front of |
| a path for example. See also "set-query" and "set-uri". |
| |
| Example : |
| # prepend the host name before the path |
| http-request set-path /%[hdr(host)]%[path] |
| |
| - "set-query" rewrites the request's query string which appears after the |
| first question mark ("?") with the result of the evaluation of format |
| string <fmt>. The part prior to the question mark is left intact. If the |
| request doesn't contain a question mark and the new value is not empty, |
| then one is added at the end of the URI, followed by the new value. If |
| a question mark was present, it will never be removed even if the value |
| is empty. This can be used to add or remove parameters from the query |
| string. See also "set-query" and "set-uri". |
| |
| Example : |
| # replace "%3D" with "=" in the query string |
| http-request set-query %[query,regsub(%3D,=,g)] |
| |
| - "set-uri" rewrites the request URI with the result of the evaluation of |
| format string <fmt>. The scheme, authority, path and query string are all |
| replaced at once. This can be used to rewrite hosts in front of proxies, |
| or to perform complex modifications to the URI such as moving parts |
| between the path and the query string. See also "set-path" and |
| "set-query". |
| |
| - "set-nice" sets the "nice" factor of the current request being processed. |
| It only has effect against the other requests being processed at the same |
| time. The default value is 0, unless altered by the "nice" setting on the |
| "bind" line. The accepted range is -1024..1024. The higher the value, the |
| nicest the request will be. Lower values will make the request more |
| important than other ones. This can be useful to improve the speed of |
| some requests, or lower the priority of non-important requests. Using |
| this setting without prior experimentation can cause some major slowdown. |
| |
| - "set-log-level" is used to change the log level of the current request |
| when a certain condition is met. Valid levels are the 8 syslog levels |
| (see the "log" keyword) plus the special level "silent" which disables |
| logging for this request. This rule is not final so the last matching |
| rule wins. This rule can be useful to disable health checks coming from |
| another equipment. |
| |
| - "set-tos" is used to set the TOS or DSCP field value of packets sent to |
| the client to the value passed in <tos> on platforms which support this. |
| This value represents the whole 8 bits of the IP TOS field, and can be |
| expressed both in decimal or hexadecimal format (prefixed by "0x"). Note |
| that only the 6 higher bits are used in DSCP or TOS, and the two lower |
| bits are always 0. This can be used to adjust some routing behaviour on |
| border routers based on some information from the request. See RFC 2474, |
| 2597, 3260 and 4594 for more information. |
| |
| - "set-mark" is used to set the Netfilter MARK on all packets sent to the |
| client to the value passed in <mark> on platforms which support it. This |
| value is an unsigned 32 bit value which can be matched by netfilter and |
| by the routing table. It can be expressed both in decimal or hexadecimal |
| format (prefixed by "0x"). This can be useful to force certain packets to |
| take a different route (for example a cheaper network path for bulk |
| downloads). This works on Linux kernels 2.6.32 and above and requires |
| admin privileges. |
| |
| - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded |
| from a file (even a dummy empty file). The file name of the ACL to be |
| updated is passed between parentheses. It takes one argument: <key fmt>, |
| which follows log-format rules, to collect content of the new entry. It |
| performs a lookup in the ACL before insertion, to avoid duplicated (or |
| more) values. This lookup is done by a linear search and can be expensive |
| with large lists! It is the equivalent of the "add acl" command from the |
| stats socket, but can be triggered by an HTTP request. |
| |
| - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded |
| from a file (even a dummy empty file). The file name of the ACL to be |
| updated is passed between parentheses. It takes one argument: <key fmt>, |
| which follows log-format rules, to collect content of the entry to delete. |
| It is the equivalent of the "del acl" command from the stats socket, but |
| can be triggered by an HTTP request. |
| |
| - "del-map" is used to delete an entry from a MAP. The MAP must be loaded |
| from a file (even a dummy empty file). The file name of the MAP to be |
| updated is passed between parentheses. It takes one argument: <key fmt>, |
| which follows log-format rules, to collect content of the entry to delete. |
| It takes one argument: "file name" It is the equivalent of the "del map" |
| command from the stats socket, but can be triggered by an HTTP request. |
| |
| - "set-map" is used to add a new entry into a MAP. The MAP must be loaded |
| from a file (even a dummy empty file). The file name of the MAP to be |
| updated is passed between parentheses. It takes 2 arguments: <key fmt>, |
| which follows log-format rules, used to collect MAP key, and <value fmt>, |
| which follows log-format rules, used to collect content for the new entry. |
| It performs a lookup in the MAP before insertion, to avoid duplicated (or |
| more) values. This lookup is done by a linear search and can be expensive |
| with large lists! It is the equivalent of the "set map" command from the |
| stats socket, but can be triggered by an HTTP request. |
| |
| - capture <sample> [ len <length> | id <id> ] : |
| captures sample expression <sample> from the request buffer, and converts |
| it to a string of at most <len> characters. The resulting string is |
| stored into the next request "capture" slot, so it will possibly appear |
| next to some captured HTTP headers. It will then automatically appear in |
| the logs, and it will be possible to extract it using sample fetch rules |
| to feed it into headers or anything. The length should be limited given |
| that this size will be allocated for each capture during the whole |
| session life. Please check section 7.3 (Fetching samples) and "capture |
| request header" for more information. |
| |
| If the keyword "id" is used instead of "len", the action tries to store |
| the captured string in a previously declared capture slot. This is useful |
| to run captures in backends. The slot id can be declared by a previous |
| directive "http-request capture" or with the "declare capture" keyword. |
| |
| - { track-sc0 | track-sc1 | track-sc2 } <key> [table <table>] : |
| enables tracking of sticky counters from current request. These rules |
| do not stop evaluation and do not change default action. Three sets of |
| counters may be simultaneously tracked by the same connection. The first |
| "track-sc0" rule executed enables tracking of the counters of the |
| specified table as the first set. The first "track-sc1" rule executed |
| enables tracking of the counters of the specified table as the second |
| set. The first "track-sc2" rule executed enables tracking of the |
| counters of the specified table as the third 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. But this is just a |
| guideline, all may be used everywhere. |
| |
| These actions take one or two arguments : |
| <key> is mandatory, and is a sample expression rule as described |
| in section 7.3. It describes what elements of the incoming |
| request or connection will be analysed, extracted, combined, |
| and used to select which table entry to update the counters. |
| |
| <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. |
| Counters are only updated for events that happen after the tracking has |
| been started. As an exception, connection counters and request counters |
| are systematically updated so that they reflect useful information. |
| |
| 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. |
| |
| - "lua" is used to run a Lua function if the action is executed. The single |
| parameter is the name of the function to run. The prototype of the |
| function is documented in the API documentation. |
| |
| - set-var(<var-name>) <expr> : |
| Is used to set the contents of a variable. The variable is declared |
| inline. |
| |
| <var-name> The name of the variable starts by an indication about its |
| scope. The allowed scopes are: |
| "sess" : the variable is shared with all the session, |
| "txn" : the variable is shared with all the transaction |
| (request and response) |
| "req" : the variable is shared only during the request |
| processing |
| "res" : the variable is shared only during the response |
| processing. |
| This prefix is followed by a name. The separator is a '.'. |
| The name may only contain characters 'a-z', 'A-Z', '0-9', |
| and '_'. |
| |
| <expr> Is a standard HAProxy expression formed by a sample-fetch |
| followed by some converters. |
| |
| Example: |
| |
| http-request set-var(req.my_var) req.fhdr(user-agent),lower |
| |
| There is no limit to the number of http-request statements per instance. |
| |
| It is important to know that http-request rules are processed very early in |
| the HTTP processing, just after "block" rules and before "reqdel" or "reqrep" |
| rules. That way, headers added by "add-header"/"set-header" are visible by |
| almost all further ACL rules. |
| |
| 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 |
| |
| Example: |
| http-request set-header X-Haproxy-Current-Date %T |
| http-request set-header X-SSL %[ssl_fc] |
| http-request set-header X-SSL-Session_ID %[ssl_fc_session_id] |
| http-request set-header X-SSL-Client-Verify %[ssl_c_verify] |
| http-request set-header X-SSL-Client-DN %{+Q}[ssl_c_s_dn] |
| http-request set-header X-SSL-Client-CN %{+Q}[ssl_c_s_dn(cn)] |
| http-request set-header X-SSL-Issuer %{+Q}[ssl_c_i_dn] |
| http-request set-header X-SSL-Client-NotBefore %{+Q}[ssl_c_notbefore] |
| http-request set-header X-SSL-Client-NotAfter %{+Q}[ssl_c_notafter] |
| |
| Example: |
| acl key req.hdr(X-Add-Acl-Key) -m found |
| acl add path /addacl |
| acl del path /delacl |
| |
| acl myhost hdr(Host) -f myhost.lst |
| |
| http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add |
| http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del |
| |
| Example: |
| acl value req.hdr(X-Value) -m found |
| acl setmap path /setmap |
| acl delmap path /delmap |
| |
| use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } |
| |
| http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value |
| http-request del-map(map.lst) %[src] if delmap |
| |
| See also : "stats http-request", section 3.4 about userlists and section 7 |
| about ACL usage. |
| |
| http-response { allow | deny | add-header <name> <fmt> | set-nice <nice> | |
| capture <sample> id <id> | redirect <rule> | |
| set-header <name> <fmt> | del-header <name> | |
| replace-header <name> <regex-match> <replace-fmt> | |
| replace-value <name> <regex-match> <replace-fmt> | |
| set-log-level <level> | set-mark <mark> | set-tos <tos> | |
| add-acl(<file name>) <key fmt> | |
| del-acl(<file name>) <key fmt> | |
| del-map(<file name>) <key fmt> | |
| set-map(<file name>) <key fmt> <value fmt> | |
| set-var(<var-name>) <expr> | |
| lua <function name> |
| } |
| [ { if | unless } <condition> ] |
| Access control for Layer 7 responses |
| |
| May be used in sections: defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| The http-response statement defines a set of rules which apply to layer 7 |
| processing. The rules are evaluated in their declaration order when they are |
| met in a frontend, listen or backend section. Any rule may optionally be |
| followed by an ACL-based condition, in which case it will only be evaluated |
| if the condition is true. Since these rules apply on responses, the backend |
| rules are applied first, followed by the frontend's rules. |
| |
| The first keyword is the rule's action. Currently supported actions include : |
| - "allow" : this stops the evaluation of the rules and lets the response |
| pass the check. No further "http-response" rules are evaluated for the |
| current section. |
| |
| - "deny" : this stops the evaluation of the rules and immediately rejects |
| the response and emits an HTTP 502 error. No further "http-response" |
| rules are evaluated. |
| |
| - "add-header" appends an HTTP header field whose name is specified in |
| <name> and whose value is defined by <fmt> which follows the log-format |
| rules (see Custom Log Format in section 8.2.4). This may be used to send |
| a cookie to a client for example, or to pass some internal information. |
| This rule is not final, so it is possible to add other similar rules. |
| Note that header addition is performed immediately, so one rule might |
| reuse the resulting header from a previous rule. |
| |
| - "set-header" does the same as "add-header" except that the header name |
| is first removed if it existed. This is useful when passing security |
| information to the server, where the header must not be manipulated by |
| external users. |
| |
| - "del-header" removes all HTTP header fields whose name is specified in |
| <name>. |
| |
| - "replace-header" matches the regular expression in all occurrences of |
| header field <name> according to <match-regex>, and replaces them with |
| the <replace-fmt> argument. Format characters are allowed in replace-fmt |
| and work like in <fmt> arguments in "add-header". The match is only |
| case-sensitive. It is important to understand that this action only |
| considers whole header lines, regardless of the number of values they |
| may contain. This usage is suited to headers naturally containing commas |
| in their value, such as Set-Cookie, Expires and so on. |
| |
| Example: |
| |
| http-response replace-header Set-Cookie (C=[^;]*);(.*) \1;ip=%bi;\2 |
| |
| applied to: |
| |
| Set-Cookie: C=1; expires=Tue, 14-Jun-2016 01:40:45 GMT |
| |
| outputs: |
| |
| Set-Cookie: C=1;ip=192.168.1.20; expires=Tue, 14-Jun-2016 01:40:45 GMT |
| |
| assuming the backend IP is 192.168.1.20. |
| |
| - "replace-value" works like "replace-header" except that it matches the |
| regex against every comma-delimited value of the header field <name> |
| instead of the entire header. This is suited for all headers which are |
| allowed to carry more than one value. An example could be the Accept |
| header. |
| |
| Example: |
| |
| http-response replace-value Cache-control ^public$ private |
| |
| applied to: |
| |
| Cache-Control: max-age=3600, public |
| |
| outputs: |
| |
| Cache-Control: max-age=3600, private |
| |
| - "set-nice" sets the "nice" factor of the current request being processed. |
| It only has effect against the other requests being processed at the same |
| time. The default value is 0, unless altered by the "nice" setting on the |
| "bind" line. The accepted range is -1024..1024. The higher the value, the |
| nicest the request will be. Lower values will make the request more |
| important than other ones. This can be useful to improve the speed of |
| some requests, or lower the priority of non-important requests. Using |
| this setting without prior experimentation can cause some major slowdown. |
| |
| - "set-log-level" is used to change the log level of the current request |
| when a certain condition is met. Valid levels are the 8 syslog levels |
| (see the "log" keyword) plus the special level "silent" which disables |
| logging for this request. This rule is not final so the last matching |
| rule wins. This rule can be useful to disable health checks coming from |
| another equipment. |
| |
| - "set-tos" is used to set the TOS or DSCP field value of packets sent to |
| the client to the value passed in <tos> on platforms which support this. |
| This value represents the whole 8 bits of the IP TOS field, and can be |
| expressed both in decimal or hexadecimal format (prefixed by "0x"). Note |
| that only the 6 higher bits are used in DSCP or TOS, and the two lower |
| bits are always 0. This can be used to adjust some routing behaviour on |
| border routers based on some information from the request. See RFC 2474, |
| 2597, 3260 and 4594 for more information. |
| |
| - "set-mark" is used to set the Netfilter MARK on all packets sent to the |
| client to the value passed in <mark> on platforms which support it. This |
| value is an unsigned 32 bit value which can be matched by netfilter and |
| by the routing table. It can be expressed both in decimal or hexadecimal |
| format (prefixed by "0x"). This can be useful to force certain packets to |
| take a different route (for example a cheaper network path for bulk |
| downloads). This works on Linux kernels 2.6.32 and above and requires |
| admin privileges. |
| |
| - "add-acl" is used to add a new entry into an ACL. The ACL must be loaded |
| from a file (even a dummy empty file). The file name of the ACL to be |
| updated is passed between parentheses. It takes one argument: <key fmt>, |
| which follows log-format rules, to collect content of the new entry. It |
| performs a lookup in the ACL before insertion, to avoid duplicated (or |
| more) values. This lookup is done by a linear search and can be expensive |
| with large lists! It is the equivalent of the "add acl" command from the |
| stats socket, but can be triggered by an HTTP response. |
| |
| - "del-acl" is used to delete an entry from an ACL. The ACL must be loaded |
| from a file (even a dummy empty file). The file name of the ACL to be |
| updated is passed between parentheses. It takes one argument: <key fmt>, |
| which follows log-format rules, to collect content of the entry to delete. |
| It is the equivalent of the "del acl" command from the stats socket, but |
| can be triggered by an HTTP response. |
| |
| - "del-map" is used to delete an entry from a MAP. The MAP must be loaded |
| from a file (even a dummy empty file). The file name of the MAP to be |
| updated is passed between parentheses. It takes one argument: <key fmt>, |
| which follows log-format rules, to collect content of the entry to delete. |
| It takes one argument: "file name" It is the equivalent of the "del map" |
| command from the stats socket, but can be triggered by an HTTP response. |
| |
| - "set-map" is used to add a new entry into a MAP. The MAP must be loaded |
| from a file (even a dummy empty file). The file name of the MAP to be |
| updated is passed between parentheses. It takes 2 arguments: <key fmt>, |
| which follows log-format rules, used to collect MAP key, and <value fmt>, |
| which follows log-format rules, used to collect content for the new entry. |
| It performs a lookup in the MAP before insertion, to avoid duplicated (or |
| more) values. This lookup is done by a linear search and can be expensive |
| with large lists! It is the equivalent of the "set map" command from the |
| stats socket, but can be triggered by an HTTP response. |
| |
| - "lua" is used to run a Lua function if the action is executed. The single |
| parameter is the name of the function to run. The prototype of the |
| function is documented in the API documentation. |
| |
| - capture <sample> id <id> : |
| captures sample expression <sample> from the response buffer, and converts |
| it to a string. The resulting string is stored into the next request |
| "capture" slot, so it will possibly appear next to some captured HTTP |
| headers. It will then automatically appear in the logs, and it will be |
| possible to extract it using sample fetch rules to feed it into headers or |
| anything. Please check section 7.3 (Fetching samples) and "capture |
| response header" for more information. |
| |
| The keyword "id" is the id of the capture slot which is used for storing |
| the string. The capture slot must be defined in an associated frontend. |
| This is useful to run captures in backends. The slot id can be declared by |
| a previous directive "http-response capture" or with the "declare capture" |
| keyword. |
| |
| - "redirect" : this performs an HTTP redirection based on a redirect rule. |
| This supports a format string similarly to "http-request redirect" rules, |
| with the exception that only the "location" type of redirect is possible |
| on the response. See the "redirect" keyword for the rule's syntax. When |
| a redirect rule is applied during a response, connections to the server |
| are closed so that no data can be forwarded from the server to the client. |
| |
| - set-var(<var-name>) expr: |
| Is used to set the contents of a variable. The variable is declared |
| inline. |
| |
| <var-name> The name of the variable starts by an indication about its |
| scope. The allowed scopes are: |
| "sess" : the variable is shared with all the session, |
| "txn" : the variable is shared with all the transaction |
| (request and response) |
| "req" : the variable is shared only during the request |
| processing |
| "res" : the variable is shared only during the response |
| processing. |
| This prefix is followed by a name. The separator is a '.'. |
| The name may only contain characters 'a-z', 'A-Z', '0-9', |
| and '_'. |
| |
| <expr> Is a standard HAProxy expression formed by a sample-fetch |
| followed by some converters. |
| |
| Example: |
| |
| http-response set-var(sess.last_redir) res.hdr(location) |
| |
| There is no limit to the number of http-response statements per instance. |
| |
| It is important to know that http-response rules are processed very early in |
| the HTTP processing, before "reqdel" or "reqrep" rules. That way, headers |
| added by "add-header"/"set-header" are visible by almost all further ACL |
| rules. |
| |
| Example: |
| acl key_acl res.hdr(X-Acl-Key) -m found |
| |
| acl myhost hdr(Host) -f myhost.lst |
| |
| http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl |
| http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl |
| |
| Example: |
| acl value res.hdr(X-Value) -m found |
| |
| use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } |
| |
| http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value |
| http-response del-map(map.lst) %[src] if ! value |
| |
| See also : "http-request", section 3.4 about userlists and section 7 about |
| ACL usage. |
| |
| |
| http-send-name-header [<header>] |
| Add the server name to a request. Use the header string given by <header> |
| |
| May be used in sections: defaults | frontend | listen | backend |
| yes | no | yes | yes |
| |
| Arguments : |
| |
| <header> The header string to use to send the server name |
| |
| The "http-send-name-header" statement causes the name of the target |
| server to be added to the headers of an HTTP request. The name |
| is added with the header string proved. |
| |
| See also : "server" |
| |
| id <value> |
| Set a persistent ID to a proxy. |
| May be used in sections : defaults | frontend | listen | backend |
| no | yes | yes | yes |
| Arguments : none |
| |
| Set a persistent ID for the proxy. This ID must be unique and positive. |
| An unused ID will automatically be assigned if unset. The first assigned |
| value will be 1. This ID is currently only returned in statistics. |
| |
| |
| ignore-persist { if | unless } <condition> |
| Declare a condition to ignore persistence |
| May be used in sections: defaults | frontend | listen | backend |
| no | yes | yes | yes |
| |
| By default, when cookie persistence is enabled, every requests containing |
| the cookie are unconditionally persistent (assuming the target server is up |
| and running). |
| |
| The "ignore-persist" statement allows one to declare various ACL-based |
| conditions which, when met, will cause a request to ignore persistence. |
| This is sometimes useful to load balance requests for static files, which |
| often don't require persistence. This can also be used to fully disable |
| |