Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1 | ---------------------- |
| 2 | HAProxy |
| 3 | Configuration Manual |
| 4 | ---------------------- |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 5 | version 1.3.15 |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 6 | willy tarreau |
Willy Tarreau | 7b4c5ae | 2008-04-19 21:06:14 +0200 | [diff] [blame] | 7 | 2008/04/19 |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 8 | |
| 9 | |
| 10 | This document covers the configuration language as implemented in the version |
| 11 | specified above. It does not provide any hint, example or advice. For such |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 12 | documentation, please refer to the Reference Manual or the Architecture Manual. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 13 | |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 14 | Note to documentation contributors : this document is formated with 80 columns |
| 15 | per line, with even number of spaces for indentation and without tabs. Please |
| 16 | follow these rules strictly so that it remains easily printable everywhere. If |
| 17 | a line needs to be printed verbatim and does not fit, please end each line with |
| 18 | a backslash ('\') and continue on next line. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 19 | |
| 20 | HAProxy's configuration process involves 3 major sources of parameters : |
| 21 | |
| 22 | - the arguments from the command-line, which always take precedence |
| 23 | - the "global" section, which sets process-wide parameters |
| 24 | - the proxies sections which can take form of "defaults", "listen", |
| 25 | "frontend" and "backend". |
| 26 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 27 | The configuration file syntax consists in lines beginning with a keyword |
| 28 | referenced in this manual, optionally followed by one or several parameters |
| 29 | delimited by spaces. If spaces have to be entered in strings, then they must be |
| 30 | preceeded by a backslash ('\') to be escaped. Backslashes also have to be |
| 31 | escaped by doubling them. |
| 32 | |
| 33 | Some parameters involve values representating time, such as timeouts. These |
| 34 | values are generally expressed in milliseconds (unless explicitly stated |
| 35 | otherwise) but may be expressed in any other unit by suffixing the unit to the |
| 36 | numeric value. It is important to consider this because it will not be repeated |
| 37 | for every keyword. Supported units are : |
| 38 | |
| 39 | - us : microseconds. 1 microsecond = 1/1000000 second |
| 40 | - ms : milliseconds. 1 millisecond = 1/1000 second. This is the default. |
| 41 | - s : seconds. 1s = 1000ms |
| 42 | - m : minutes. 1m = 60s = 60000ms |
| 43 | - h : hours. 1h = 60m = 3600s = 3600000ms |
| 44 | - d : days. 1d = 24h = 1440m = 86400s = 86400000ms |
| 45 | |
| 46 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 47 | 1. Global parameters |
| 48 | -------------------- |
| 49 | |
| 50 | Parameters in the "global" section are process-wide and often OS-specific. They |
| 51 | are generally set once for all and do not need being changed once correct. Some |
| 52 | of them have command-line equivalents. |
| 53 | |
| 54 | The following keywords are supported in the "global" section : |
| 55 | |
| 56 | * Process management and security |
| 57 | - chroot |
| 58 | - daemon |
| 59 | - gid |
| 60 | - group |
| 61 | - log |
| 62 | - nbproc |
| 63 | - pidfile |
| 64 | - uid |
| 65 | - ulimit-n |
| 66 | - user |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 67 | - stats |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 68 | |
| 69 | * Performance tuning |
| 70 | - maxconn |
| 71 | - noepoll |
| 72 | - nokqueue |
| 73 | - nopoll |
| 74 | - nosepoll |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 75 | - spread-checks |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 76 | - tune.maxaccept |
| 77 | - tune.maxpollevents |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 78 | |
| 79 | * Debugging |
| 80 | - debug |
| 81 | - quiet |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 82 | |
| 83 | |
| 84 | 1.1) Process management and security |
| 85 | ------------------------------------ |
| 86 | |
| 87 | chroot <jail dir> |
| 88 | Changes current directory to <jail dir> and performs a chroot() there before |
| 89 | dropping privileges. This increases the security level in case an unknown |
| 90 | vulnerability would be exploited, since it would make it very hard for the |
| 91 | attacker to exploit the system. This only works when the process is started |
| 92 | with superuser privileges. It is important to ensure that <jail_dir> is both |
| 93 | empty and unwritable to anyone. |
| 94 | |
| 95 | daemon |
| 96 | Makes the process fork into background. This is the recommended mode of |
| 97 | operation. It is equivalent to the command line "-D" argument. It can be |
| 98 | disabled by the command line "-db" argument. |
| 99 | |
| 100 | gid <number> |
| 101 | Changes the process' group ID to <number>. It is recommended that the group |
| 102 | ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 103 | be started with a user belonging to this group, or with superuser privileges. |
| 104 | See also "group" and "uid". |
| 105 | |
| 106 | group <group name> |
| 107 | Similar to "gid" but uses the GID of group name <group name> from /etc/group. |
| 108 | See also "gid" and "user". |
| 109 | |
| 110 | log <address> <facility> [max level] |
| 111 | Adds a global syslog server. Up to two global servers can be defined. They |
| 112 | will receive logs for startups and exits, as well as all logs from proxies |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 113 | configured with "log global". |
| 114 | |
| 115 | <address> can be one of: |
| 116 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 117 | - An IPv4 address optionally followed by a colon and a UDP port. If |
Robert Tsai | 81ae195 | 2007-12-05 10:47:29 +0100 | [diff] [blame] | 118 | no port is specified, 514 is used by default (the standard syslog |
| 119 | port). |
| 120 | |
| 121 | - A filesystem path to a UNIX domain socket, keeping in mind |
| 122 | considerations for chroot (be sure the path is accessible inside |
| 123 | the chroot) and uid/gid (be sure the path is appropriately |
| 124 | writeable). |
| 125 | |
| 126 | <facility> must be one of the 24 standard syslog facilities : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 127 | |
| 128 | kern user mail daemon auth syslog lpr news |
| 129 | uucp cron auth2 ftp ntp audit alert cron2 |
| 130 | local0 local1 local2 local3 local4 local5 local6 local7 |
| 131 | |
| 132 | An optional level can be specified to filter outgoing messages. By default, |
| 133 | all messages are sent. If a level is specified, only messages with a severity |
| 134 | at least as important as this level will be sent. 8 levels are known : |
| 135 | |
| 136 | emerg alert crit err warning notice info debug |
| 137 | |
| 138 | nbproc <number> |
| 139 | Creates <number> processes when going daemon. This requires the "daemon" |
| 140 | mode. By default, only one process is created, which is the recommended mode |
| 141 | of operation. For systems limited to small sets of file descriptors per |
| 142 | process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES |
| 143 | IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon". |
| 144 | |
| 145 | pidfile <pidfile> |
| 146 | Writes pids of all daemons into file <pidfile>. This option is equivalent to |
| 147 | the "-p" command line argument. The file must be accessible to the user |
| 148 | starting the process. See also "daemon". |
| 149 | |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 150 | stats socket <path> [{uid | user} <uid>] [{gid | group} <gid>] [mode <mode>] |
| 151 | Creates a UNIX socket in stream mode at location <path>. Any previously |
| 152 | existing socket will be backed up then replaced. Connections to this socket |
| 153 | will get a CSV-formated output of the process statistics in response to the |
Willy Tarreau | a8efd36 | 2008-01-03 10:19:15 +0100 | [diff] [blame] | 154 | "show stat" command followed by a line feed, and more general process |
| 155 | information in response to the "show info" command followed by a line feed. |
| 156 | |
| 157 | On platforms which support it, it is possible to restrict access to this |
| 158 | socket by specifying numerical IDs after "uid" and "gid", or valid user and |
| 159 | group names after the "user" and "group" keywords. It is also possible to |
| 160 | restrict permissions on the socket by passing an octal value after the "mode" |
| 161 | keyword (same syntax as chmod). Depending on the platform, the permissions on |
| 162 | the socket will be inherited from the directory which hosts it, or from the |
| 163 | user the process is started with. |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 164 | |
| 165 | stats timeout <timeout, in milliseconds> |
| 166 | The default timeout on the stats socket is set to 10 seconds. It is possible |
| 167 | to change this value with "stats timeout". The value must be passed in |
Willy Tarreau | befdff1 | 2007-12-02 22:27:38 +0100 | [diff] [blame] | 168 | milliseconds, or be suffixed by a time unit among { us, ms, s, m, h, d }. |
Willy Tarreau | fbee713 | 2007-10-18 13:53:22 +0200 | [diff] [blame] | 169 | |
| 170 | stats maxconn <connections> |
| 171 | By default, the stats socket is limited to 10 concurrent connections. It is |
| 172 | possible to change this value with "stats maxconn". |
| 173 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 174 | uid <number> |
| 175 | Changes the process' user ID to <number>. It is recommended that the user ID |
| 176 | is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 177 | be started with superuser privileges in order to be able to switch to another |
| 178 | one. See also "gid" and "user". |
| 179 | |
| 180 | ulimit-n <number> |
| 181 | Sets the maximum number of per-process file-descriptors to <number>. By |
| 182 | default, it is automatically computed, so it is recommended not to use this |
| 183 | option. |
| 184 | |
| 185 | user <user name> |
| 186 | Similar to "uid" but uses the UID of user name <user name> from /etc/passwd. |
| 187 | See also "uid" and "group". |
| 188 | |
| 189 | |
| 190 | 1.2) Performance tuning |
| 191 | ----------------------- |
| 192 | |
| 193 | maxconn <number> |
| 194 | Sets the maximum per-process number of concurrent connections to <number>. It |
| 195 | is equivalent to the command-line argument "-n". Proxies will stop accepting |
| 196 | connections when this limit is reached. The "ulimit-n" parameter is |
| 197 | automatically adjusted according to this value. See also "ulimit-n". |
| 198 | |
| 199 | noepoll |
| 200 | Disables the use of the "epoll" event polling system on Linux. It is |
| 201 | equivalent to the command-line argument "-de". The next polling system |
| 202 | used will generally be "poll". See also "nosepoll", and "nopoll". |
| 203 | |
| 204 | nokqueue |
| 205 | Disables the use of the "kqueue" event polling system on BSD. It is |
| 206 | equivalent to the command-line argument "-dk". The next polling system |
| 207 | used will generally be "poll". See also "nopoll". |
| 208 | |
| 209 | nopoll |
| 210 | Disables the use of the "poll" event polling system. It is equivalent to the |
| 211 | command-line argument "-dp". The next polling system used will be "select". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 212 | It should never be needed to disable "poll" since it's available on all |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 213 | platforms supported by HAProxy. See also "nosepoll", and "nopoll" and |
| 214 | "nokqueue". |
| 215 | |
| 216 | nosepoll |
| 217 | Disables the use of the "speculative epoll" event polling system on Linux. It |
| 218 | is equivalent to the command-line argument "-ds". The next polling system |
| 219 | used will generally be "epoll". See also "nosepoll", and "nopoll". |
| 220 | |
Willy Tarreau | fe255b7 | 2007-10-14 23:09:26 +0200 | [diff] [blame] | 221 | spread-checks <0..50, in percent> |
| 222 | Sometimes it is desirable to avoid sending health checks to servers at exact |
| 223 | intervals, for instance when many logical servers are located on the same |
| 224 | physical server. With the help of this parameter, it becomes possible to add |
| 225 | some randomness in the check interval between 0 and +/- 50%. A value between |
| 226 | 2 and 5 seems to show good results. The default value remains at 0. |
| 227 | |
Willy Tarreau | a0250ba | 2008-01-06 11:22:57 +0100 | [diff] [blame] | 228 | tune.maxaccept <number> |
| 229 | Sets the maximum number of consecutive accepts that a process may perform on |
| 230 | a single wake up. High values give higher priority to high connection rates, |
| 231 | while lower values give higher priority to already established connections. |
| 232 | This value is unlimited by default in single process mode. However, in |
| 233 | multi-process mode (nbproc > 1), it defaults to 8 so that when one process |
| 234 | wakes up, it does not take all incoming connections for itself and leaves a |
| 235 | part of them to other processes. Setting this value to zero or less disables |
| 236 | the limitation. It should normally not be needed to tweak this value. |
| 237 | |
| 238 | tune.maxpollevents <number> |
| 239 | Sets the maximum amount of events that can be processed at once in a call to |
| 240 | the polling system. The default value is adapted to the operating system. It |
| 241 | has been noticed that reducing it below 200 tends to slightly decrease |
| 242 | latency at the expense of network bandwidth, and increasing it above 200 |
| 243 | tends to trade latency for slightly increased bandwidth. |
| 244 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 245 | |
| 246 | 1.3) Debugging |
| 247 | --------------- |
| 248 | |
| 249 | debug |
| 250 | Enables debug mode which dumps to stdout all exchanges, and disables forking |
| 251 | into background. It is the equivalent of the command-line argument "-d". It |
| 252 | should never be used in a production configuration since it may prevent full |
| 253 | system startup. |
| 254 | |
| 255 | quiet |
| 256 | Do not display any message during startup. It is equivalent to the command- |
| 257 | line argument "-q". |
| 258 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 259 | |
| 260 | 2) Proxies |
| 261 | ---------- |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 262 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 263 | Proxy configuration can be located in a set of sections : |
| 264 | - defaults <name> |
| 265 | - frontend <name> |
| 266 | - backend <name> |
| 267 | - listen <name> |
| 268 | |
| 269 | A "defaults" section sets default parameters for all other sections following |
| 270 | its declaration. Those default parameters are reset by the next "defaults" |
| 271 | section. See below for the list of parameters which can be set in a "defaults" |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 272 | section. The name is optional but its use is encouraged for better readability. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 273 | |
| 274 | A "frontend" section describes a set of listening sockets accepting client |
| 275 | connections. |
| 276 | |
| 277 | A "backend" section describes a set of servers to which the proxy will connect |
| 278 | to forward incoming connections. |
| 279 | |
| 280 | A "listen" section defines a complete proxy with its frontend and backend |
| 281 | parts combined in one section. It is generally useful for TCP-only traffic. |
| 282 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 283 | All proxy names must be formed from upper and lower case letters, digits, |
| 284 | '-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are |
| 285 | case-sensitive, which means that "www" and "WWW" are two different proxies. |
| 286 | |
| 287 | Historically, all proxy names could overlap, it just caused troubles in the |
| 288 | logs. Since the introduction of content switching, it is mandatory that two |
| 289 | proxies with overlapping capabilities (frontend/backend) have different names. |
| 290 | However, it is still permitted that a frontend and a backend share the same |
| 291 | name, as this configuration seems to be commonly encountered. |
| 292 | |
| 293 | Right now, two major proxy modes are supported : "tcp", also known as layer 4, |
| 294 | and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards |
| 295 | bidirectionnal traffic between two sides. In layer 7 mode, HAProxy analyzes the |
| 296 | protocol, and can interact with it by allowing, blocking, switching, adding, |
| 297 | modifying, or removing arbitrary contents in requests or responses, based on |
| 298 | arbitrary criteria. |
| 299 | |
| 300 | |
| 301 | 2.1) Quick reminder about HTTP |
| 302 | ------------------------------ |
| 303 | |
| 304 | When a proxy is running in HTTP mode, both the request and the response are |
| 305 | fully analyzed and indexed, thus it becomes possible to build matching criteria |
| 306 | on almost anything found in the contents. |
| 307 | |
| 308 | However, it is important to understand how HTTP requests and responses are |
| 309 | formed, and how HAProxy decomposes them. It will then become easier to write |
| 310 | correct rules and to debug existing configurations. |
| 311 | |
| 312 | |
| 313 | 2.1.1) The HTTP transaction model |
| 314 | --------------------------------- |
| 315 | |
| 316 | The HTTP protocol is transaction-driven. This means that each request will lead |
| 317 | to one and only one response. Traditionnally, a TCP connection is established |
| 318 | from the client to the server, a request is sent by the client on the |
| 319 | connection, the server responds and the connection is closed. A new request |
| 320 | will involve a new connection : |
| 321 | |
| 322 | [CON1] [REQ1] ... [RESP1] [CLO1] [CON2] [REQ2] ... [RESP2] [CLO2] ... |
| 323 | |
| 324 | In this mode, called the "HTTP close" mode, there are as many connection |
| 325 | establishments as there are HTTP transactions. Since the connection is closed |
| 326 | by the server after the response, the client does not need to know the content |
| 327 | length. |
| 328 | |
| 329 | Due to the transactional nature of the protocol, it was possible to improve it |
| 330 | to avoid closing a connection between two subsequent transactions. In this mode |
| 331 | however, it is mandatory that the server indicates the content length for each |
| 332 | response so that the client does not wait indefinitely. For this, a special |
| 333 | header is used: "Content-length". This mode is called the "keep-alive" mode : |
| 334 | |
| 335 | [CON] [REQ1] ... [RESP1] [REQ2] ... [RESP2] [CLO] ... |
| 336 | |
| 337 | Its advantages are a reduced latency between transactions, and less processing |
| 338 | power required on the server side. It is generally better than the close mode, |
| 339 | but not always because the clients often limit their concurrent connections to |
| 340 | a smaller value. HAProxy currently does not support the HTTP keep-alive mode, |
| 341 | but knows how to transform it to the close mode. |
| 342 | |
| 343 | A last improvement in the communications is the pipelining mode. It still uses |
| 344 | keep-alive, but the client does not wait for the first response to send the |
| 345 | second request. This is useful for fetching large number of images composing a |
| 346 | page : |
| 347 | |
| 348 | [CON] [REQ1] [REQ2] ... [RESP1] [RESP2] [CLO] ... |
| 349 | |
| 350 | This can obviously have a tremendous benefit on performance because the network |
| 351 | latency is eliminated between subsequent requests. Many HTTP agents do not |
| 352 | correctly support pipelining since there is no way to associate a response with |
| 353 | the corresponding request in HTTP. For this reason, it is mandatory for the |
| 354 | server to reply in the exact same order as the requests were received. |
| 355 | |
| 356 | Right now, HAProxy only supports the first mode (HTTP close) if it needs to |
| 357 | process the request. This means that for each request, there will be one TCP |
| 358 | connection. If keep-alive or pipelining are required, HAProxy will still |
| 359 | support them, but will only see the first request and the first response of |
| 360 | each transaction. While this is generally problematic with regards to logs, |
| 361 | content switching or filtering, it most often causes no problem for persistence |
| 362 | with cookie insertion. |
| 363 | |
| 364 | |
| 365 | 2.1.2) HTTP request |
| 366 | ------------------- |
| 367 | |
| 368 | First, let's consider this HTTP request : |
| 369 | |
| 370 | Line Contents |
| 371 | number |
| 372 | 1 GET /serv/login.php?lang=en&profile=2 HTTP/1.1 |
| 373 | 2 Host: www.mydomain.com |
| 374 | 3 User-agent: my small browser |
| 375 | 4 Accept: image/jpeg, image/gif |
| 376 | 5 Accept: image/png |
| 377 | |
| 378 | |
| 379 | 2.1.2.1) The Request line |
| 380 | ------------------------- |
| 381 | |
| 382 | Line 1 is the "request line". It is always composed of 3 fields : |
| 383 | |
| 384 | - a METHOD : GET |
| 385 | - a URI : /serv/login.php?lang=en&profile=2 |
| 386 | - a version tag : HTTP/1.1 |
| 387 | |
| 388 | All of them are delimited by what the standard calls LWS (linear white spaces), |
| 389 | which are commonly spaces, but can also be tabs or line feeds/carriage returns |
| 390 | followed by spaces/tabs. The method itself cannot contain any colon (':') and |
| 391 | is limited to alphabetic letters. All those various combinations make it |
| 392 | desirable that HAProxy performs the splitting itself rather than leaving it to |
| 393 | the user to write a complex or inaccurate regular expression. |
| 394 | |
| 395 | The URI itself can have several forms : |
| 396 | |
| 397 | - A "relative URI" : |
| 398 | |
| 399 | /serv/login.php?lang=en&profile=2 |
| 400 | |
| 401 | It is a complete URL without the host part. This is generally what is |
| 402 | received by servers, reverse proxies and transparent proxies. |
| 403 | |
| 404 | - An "absolute URI", also called a "URL" : |
| 405 | |
| 406 | http://192.168.0.12:8080/serv/login.php?lang=en&profile=2 |
| 407 | |
| 408 | It is composed of a "scheme" (the protocol name followed by '://'), a host |
| 409 | name or address, optionally a colon (':') followed by a port number, then |
| 410 | a relative URI beginning at the first slash ('/') after the address part. |
| 411 | This is generally what proxies receive, but a server supporting HTTP/1.1 |
| 412 | must accept this form too. |
| 413 | |
| 414 | - a star ('*') : this form is only accepted in association with the OPTIONS |
| 415 | method and is not relayable. It is used to inquiry a next hop's |
| 416 | capabilities. |
| 417 | |
| 418 | - an address:port combination : 192.168.0.12:80 |
| 419 | This is used with the CONNECT method, which is used to establish TCP |
| 420 | tunnels through HTTP proxies, generally for HTTPS, but sometimes for |
| 421 | other protocols too. |
| 422 | |
| 423 | In a relative URI, two sub-parts are identified. The part before the question |
| 424 | mark is called the "path". It is typically the relative path to static objects |
| 425 | on the server. The part after the question mark is called the "query string". |
| 426 | It is mostly used with GET requests sent to dynamic scripts and is very |
| 427 | specific to the language, framework or application in use. |
| 428 | |
| 429 | |
| 430 | 2.1.2.2) The request headers |
| 431 | ---------------------------- |
| 432 | |
| 433 | The headers start at the second line. They are composed of a name at the |
| 434 | beginning of the line, immediately followed by a colon (':'). Traditionally, |
| 435 | an LWS is added after the colon but that's not required. Then come the values. |
| 436 | Multiple identical headers may be folded into one single line, delimiting the |
| 437 | values with commas, provided that their order is respected. This is commonly |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 438 | encountered in the "Cookie:" field. A header may span over multiple lines if |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 439 | the subsequent lines begin with an LWS. In the example in 2.1.2, lines 4 and 5 |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 440 | define a total of 3 values for the "Accept:" header. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 441 | |
| 442 | Contrary to a common mis-conception, header names are not case-sensitive, and |
| 443 | their values are not either if they refer to other header names (such as the |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 444 | "Connection:" header). |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 445 | |
| 446 | The end of the headers is indicated by the first empty line. People often say |
| 447 | that it's a double line feed, which is not exact, even if a double line feed |
| 448 | is one valid form of empty line. |
| 449 | |
| 450 | Fortunately, HAProxy takes care of all these complex combinations when indexing |
| 451 | headers, checking values and counting them, so there is no reason to worry |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 452 | about the way they could be written, but it is important not to accuse an |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 453 | application of being buggy if it does unusual, valid things. |
| 454 | |
| 455 | Important note: |
| 456 | As suggested by RFC2616, HAProxy normalizes headers by replacing line breaks |
| 457 | in the middle of headers by LWS in order to join multi-line headers. This |
| 458 | is necessary for proper analysis and helps less capable HTTP parsers to work |
| 459 | correctly and not to be fooled by such complex constructs. |
| 460 | |
| 461 | |
| 462 | 2.1.3) HTTP response |
| 463 | -------------------- |
| 464 | |
| 465 | An HTTP response looks very much like an HTTP request. Both are called HTTP |
| 466 | messages. Let's consider this HTTP response : |
| 467 | |
| 468 | Line Contents |
| 469 | number |
| 470 | 1 HTTP/1.1 200 OK |
| 471 | 2 Content-length: 350 |
| 472 | 3 Content-Type: text/html |
| 473 | |
| 474 | |
| 475 | 2.1.3.1) The Response line |
| 476 | -------------------------- |
| 477 | |
| 478 | Line 1 is the "response line". It is always composed of 3 fields : |
| 479 | |
| 480 | - a version tag : HTTP/1.1 |
| 481 | - a status code : 200 |
| 482 | - a reason : OK |
| 483 | |
| 484 | The status code is always 3-digit. The first digit indicates a general status : |
| 485 | - 2xx = OK, content is following (eg: 200, 206) |
| 486 | - 3xx = OK, no content following (eg: 302, 304) |
| 487 | - 4xx = error caused by the client (eg: 401, 403, 404) |
| 488 | - 5xx = error caused by the server (eg: 500, 502, 503) |
| 489 | |
| 490 | Please refer to RFC2616 for the detailed meaning of all such codes. The |
| 491 | "reason" field is just a hint, but is not parsed by clients. Anything can be |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 492 | found there, but it's a common practice to respect the well-established |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 493 | messages. It can be composed of one or multiple words, such as "OK", "Found", |
| 494 | or "Authentication Required". |
| 495 | |
| 496 | |
| 497 | 2.1.3.2) The response headers |
| 498 | ----------------------------- |
| 499 | |
| 500 | Response headers work exactly like request headers, and as such, HAProxy uses |
| 501 | the same parsing function for both. Please refer to paragraph 2.1.2.2 for more |
| 502 | details. |
| 503 | |
| 504 | |
| 505 | 2.2) Proxy keywords matrix |
| 506 | ---------------------------- |
| 507 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 508 | The following list of keywords is supported. Most of them may only be used in a |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 509 | limited set of section types. Some of them are marked as "deprecated" because |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 510 | they are inherited from an old syntax which may be confusing or functionally |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 511 | limited, and there are new recommended keywords to replace them. Keywords |
| 512 | listed with [no] can be optionally inverted using the "no" prefix, ex. "no |
| 513 | option contstats". This makes sense when the option has been enabled by default |
| 514 | and must be disabled for a specific instance. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 515 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 516 | |
| 517 | keyword defaults frontend listen backend |
| 518 | ----------------------+----------+----------+---------+--------- |
| 519 | acl - X X X |
| 520 | appsession - - X X |
Willy Tarreau | c73ce2b | 2008-01-06 10:55:10 +0100 | [diff] [blame] | 521 | backlog X X X - |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 522 | balance X - X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 523 | bind - X X - |
| 524 | block - X X X |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 525 | capture cookie - X X - |
| 526 | capture request header - X X - |
| 527 | capture response header - X X - |
Willy Tarreau | e219db7 | 2007-12-03 01:30:13 +0100 | [diff] [blame] | 528 | clitimeout X X X - (deprecated) |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 529 | contimeout X - X X (deprecated) |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 530 | cookie X - X X |
| 531 | default_backend - X X - |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 532 | disabled X X X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 533 | dispatch - - X X |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 534 | enabled X X X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 535 | errorfile X X X X |
| 536 | errorloc X X X X |
| 537 | errorloc302 X X X X |
| 538 | errorloc303 X X X X |
| 539 | fullconn X - X X |
| 540 | grace - X X X |
Willy Tarreau | dbc36f6 | 2007-11-30 12:29:11 +0100 | [diff] [blame] | 541 | http-check disable-on-404 X - X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 542 | log X X X X |
| 543 | maxconn X X X - |
| 544 | mode X X X X |
Willy Tarreau | c7246fc | 2007-12-02 17:31:20 +0100 | [diff] [blame] | 545 | monitor fail - X X - |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 546 | monitor-net X X X - |
| 547 | monitor-uri X X X - |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 548 | [no] option abortonclose X - X X |
| 549 | [no] option allbackups X - X X |
| 550 | [no] option checkcache X - X X |
| 551 | [no] option clitcpka X X X - |
| 552 | [no] option contstats X X X - |
| 553 | [no] option dontlognull X X X - |
| 554 | [no] option forceclose X - X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 555 | option forwardfor X X X X |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 556 | [no] option http_proxy X X X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 557 | option httpchk X - X X |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 558 | [no] option httpclose X X X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 559 | option httplog X X X X |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 560 | [no] option logasap X X X - |
| 561 | [no] option nolinger X X X X |
| 562 | [no] option persist X - X X |
| 563 | [no] option redispatch X - X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 564 | option smtpchk X - X X |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 565 | [no] option srvtcpka X - X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 566 | option ssl-hello-chk X - X X |
| 567 | option tcpka X X X X |
| 568 | option tcplog X X X X |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 569 | [no] option tcpsplice X X X X |
| 570 | [no] option transparent X X X - |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 571 | redirect - X X X |
Krzysztof Oledzki | 336d475 | 2007-12-25 02:40:22 +0100 | [diff] [blame] | 572 | redisp X - X X (deprecated) |
| 573 | redispatch X - X X (deprecated) |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 574 | reqadd - X X X |
| 575 | reqallow - X X X |
| 576 | reqdel - X X X |
| 577 | reqdeny - X X X |
| 578 | reqiallow - X X X |
| 579 | reqidel - X X X |
| 580 | reqideny - X X X |
| 581 | reqipass - X X X |
| 582 | reqirep - X X X |
| 583 | reqisetbe - X X X |
| 584 | reqitarpit - X X X |
| 585 | reqpass - X X X |
| 586 | reqrep - X X X |
| 587 | reqsetbe - X X X |
| 588 | reqtarpit - X X X |
| 589 | retries X - X X |
| 590 | rspadd - X X X |
| 591 | rspdel - X X X |
| 592 | rspdeny - X X X |
| 593 | rspidel - X X X |
| 594 | rspideny - X X X |
| 595 | rspirep - X X X |
| 596 | rsprep - X X X |
| 597 | server - - X X |
| 598 | source X - X X |
Willy Tarreau | e219db7 | 2007-12-03 01:30:13 +0100 | [diff] [blame] | 599 | srvtimeout X - X X (deprecated) |
Willy Tarreau | 24e779b | 2007-07-24 23:43:37 +0200 | [diff] [blame] | 600 | stats auth X - X X |
| 601 | stats enable X - X X |
| 602 | stats realm X - X X |
Willy Tarreau | bbd4212 | 2007-07-25 07:26:38 +0200 | [diff] [blame] | 603 | stats refresh X - X X |
Willy Tarreau | 24e779b | 2007-07-24 23:43:37 +0200 | [diff] [blame] | 604 | stats scope X - X X |
| 605 | stats uri X - X X |
Krzysztof Oledzki | d9db927 | 2007-10-15 10:05:11 +0200 | [diff] [blame] | 606 | stats hide-version X - X X |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 607 | timeout check X - X X |
Willy Tarreau | e219db7 | 2007-12-03 01:30:13 +0100 | [diff] [blame] | 608 | timeout client X X X - |
| 609 | timeout clitimeout X X X - (deprecated) |
| 610 | timeout connect X - X X |
| 611 | timeout contimeout X - X X (deprecated) |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 612 | timeout http-request X X X - |
Willy Tarreau | e219db7 | 2007-12-03 01:30:13 +0100 | [diff] [blame] | 613 | timeout queue X - X X |
| 614 | timeout server X - X X |
| 615 | timeout srvtimeout X - X X (deprecated) |
Willy Tarreau | 51c9bde | 2008-01-06 13:40:03 +0100 | [diff] [blame] | 616 | timeout tarpit X X X X |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 617 | transparent X X X - (deprecated) |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 618 | use_backend - X X - |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 619 | ----------------------+----------+----------+---------+--------- |
| 620 | keyword defaults frontend listen backend |
| 621 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 622 | |
| 623 | 2.2.1) Alphabetically sorted keywords reference |
| 624 | ----------------------------------------------- |
| 625 | |
| 626 | This section provides a description of each keyword and its usage. |
| 627 | |
| 628 | |
| 629 | acl <aclname> <criterion> [flags] [operator] <value> ... |
| 630 | Declare or complete an access list. |
| 631 | May be used in sections : defaults | frontend | listen | backend |
| 632 | no | yes | yes | yes |
| 633 | Example: |
| 634 | acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| 635 | acl invalid_src src_port 0:1023 |
| 636 | acl local_dst hdr(host) -i localhost |
| 637 | |
| 638 | See section 2.3 about ACL usage. |
| 639 | |
| 640 | |
| 641 | appsession <cookie> len <length> timeout <holdtime> |
| 642 | Define session stickiness on an existing application cookie. |
| 643 | May be used in sections : defaults | frontend | listen | backend |
| 644 | no | no | yes | yes |
| 645 | Arguments : |
| 646 | <cookie> this is the name of the cookie used by the application and which |
| 647 | HAProxy will have to learn for each new session. |
| 648 | |
| 649 | <length> this is the number of characters that will be memorized and |
| 650 | checked in each cookie value. |
| 651 | |
| 652 | <holdtime> this is the time after which the cookie will be removed from |
| 653 | memory if unused. If no unit is specified, this time is in |
| 654 | milliseconds. |
| 655 | |
| 656 | When an application cookie is defined in a backend, HAProxy will check when |
| 657 | the server sets such a cookie, and will store its value in a table, and |
| 658 | associate it with the server's identifier. Up to <length> characters from |
| 659 | the value will be retained. On each connection, haproxy will look for this |
| 660 | cookie both in the "Cookie:" headers, and as a URL parameter in the query |
| 661 | string. If a known value is found, the client will be directed to the server |
| 662 | associated with this value. Otherwise, the load balancing algorithm is |
| 663 | applied. Cookies are automatically removed from memory when they have been |
| 664 | unused for a duration longer than <holdtime>. |
| 665 | |
| 666 | The definition of an application cookie is limited to one per backend. |
| 667 | |
| 668 | Example : |
| 669 | appsession JSESSIONID len 52 timeout 3h |
| 670 | |
| 671 | See also : "cookie", "capture cookie" and "balance". |
| 672 | |
| 673 | |
Willy Tarreau | c73ce2b | 2008-01-06 10:55:10 +0100 | [diff] [blame] | 674 | backlog <conns> |
| 675 | Give hints to the system about the approximate listen backlog desired size |
| 676 | May be used in sections : defaults | frontend | listen | backend |
| 677 | yes | yes | yes | no |
| 678 | Arguments : |
| 679 | <conns> is the number of pending connections. Depending on the operating |
| 680 | system, it may represent the number of already acknowledged |
| 681 | connections, of non-acknowledged ones, or both. |
| 682 | |
| 683 | In order to protect against SYN flood attacks, one solution is to increase |
| 684 | the system's SYN backlog size. Depending on the system, sometimes it is just |
| 685 | tunable via a system parameter, sometimes it is not adjustable at all, and |
| 686 | sometimes the system relies on hints given by the application at the time of |
| 687 | the listen() syscall. By default, HAProxy passes the frontend's maxconn value |
| 688 | to the listen() syscall. On systems which can make use of this value, it can |
| 689 | sometimes be useful to be able to specify a different value, hence this |
| 690 | backlog parameter. |
| 691 | |
| 692 | On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is |
| 693 | used as a hint and the system accepts up to the smallest greater power of |
| 694 | two, and never more than some limits (usually 32768). |
| 695 | |
| 696 | See also : "maxconn" and the target operating system's tuning guide. |
| 697 | |
| 698 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 699 | balance <algorithm> [ <arguments> ] |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 700 | balance url_param <param> [check_post [<max_wait>]] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 701 | Define the load balancing algorithm to be used in a backend. |
| 702 | May be used in sections : defaults | frontend | listen | backend |
| 703 | yes | no | yes | yes |
| 704 | Arguments : |
| 705 | <algorithm> is the algorithm used to select a server when doing load |
| 706 | balancing. This only applies when no persistence information |
| 707 | is available, or when a connection is redispatched to another |
| 708 | server. <algorithm> may be one of the following : |
| 709 | |
| 710 | roundrobin Each server is used in turns, according to their weights. |
| 711 | This is the smoothest and fairest algorithm when the server's |
| 712 | processing time remains equally distributed. This algorithm |
| 713 | is dynamic, which means that server weights may be adjusted |
| 714 | on the fly for slow starts for instance. |
| 715 | |
Willy Tarreau | 2d2a7f8 | 2008-03-17 12:07:56 +0100 | [diff] [blame] | 716 | leastconn The server with the lowest number of connections receives the |
| 717 | connection. Round-robin is performed within groups of servers |
| 718 | of the same load to ensure that all servers will be used. Use |
| 719 | of this algorithm is recommended where very long sessions are |
| 720 | expected, such as LDAP, SQL, TSE, etc... but is not very well |
| 721 | suited for protocols using short sessions such as HTTP. This |
| 722 | algorithm is dynamic, which means that server weights may be |
| 723 | adjusted on the fly for slow starts for instance. |
| 724 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 725 | source The source IP address is hashed and divided by the total |
| 726 | weight of the running servers to designate which server will |
| 727 | receive the request. This ensures that the same client IP |
| 728 | address will always reach the same server as long as no |
| 729 | server goes down or up. If the hash result changes due to the |
| 730 | number of running servers changing, many clients will be |
| 731 | directed to a different server. This algorithm is generally |
| 732 | used in TCP mode where no cookie may be inserted. It may also |
| 733 | be used on the Internet to provide a best-effort stickyness |
| 734 | to clients which refuse session cookies. This algorithm is |
| 735 | static, which means that changing a server's weight on the |
| 736 | fly will have no effect. |
| 737 | |
| 738 | uri The left part of the URI (before the question mark) is hashed |
| 739 | and divided by the total weight of the running servers. The |
| 740 | result designates which server will receive the request. This |
| 741 | ensures that a same URI will always be directed to the same |
| 742 | server as long as no server goes up or down. This is used |
| 743 | with proxy caches and anti-virus proxies in order to maximize |
| 744 | the cache hit rate. Note that this algorithm may only be used |
| 745 | in an HTTP backend. This algorithm is static, which means |
| 746 | that changing a server's weight on the fly will have no |
| 747 | effect. |
| 748 | |
Marek Majkowski | 9c30fc1 | 2008-04-27 23:25:55 +0200 | [diff] [blame] | 749 | This algorithm support two optional parameters "len" and |
| 750 | "depth", both followed by a positive integer number. These |
| 751 | options may be helpful when it is needed to balance servers |
| 752 | based on the beginning of the URI only. The "len" parameter |
| 753 | indicates that the algorithm should only consider that many |
| 754 | characters at the beginning of the URI to compute the hash. |
| 755 | Note that having "len" set to 1 rarely makes sense since most |
| 756 | URIs start with a leading "/". |
| 757 | |
| 758 | The "depth" parameter indicates the maximum directory depth |
| 759 | to be used to compute the hash. One level is counted for each |
| 760 | slash in the request. If both parameters are specified, the |
| 761 | evaluation stops when either is reached. |
| 762 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 763 | url_param The URL parameter specified in argument will be looked up in |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 764 | the query string of each HTTP GET request. |
| 765 | |
| 766 | If the modifier "check_post" is used, then an HTTP POST |
| 767 | request entity will be searched for the parameter argument, |
| 768 | when the question mark indicating a query string ('?') is not |
| 769 | present in the URL. Optionally, specify a number of octets to |
| 770 | wait for before attempting to search the message body. If the |
| 771 | entity can not be searched, then round robin is used for each |
| 772 | request. For instance, if your clients always send the LB |
| 773 | parameter in the first 128 bytes, then specify that. The |
| 774 | default is 48. The entity data will not be scanned until the |
| 775 | required number of octets have arrived at the gateway, this |
| 776 | is the minimum of: (default/max_wait, Content-Length or first |
| 777 | chunk length). If Content-Length is missing or zero, it does |
| 778 | not need to wait for more data than the client promised to |
| 779 | send. When Content-Length is present and larger than |
| 780 | <max_wait>, then waiting is limited to <max_wait> and it is |
| 781 | assumed that this will be enough data to search for the |
| 782 | presence of the parameter. In the unlikely event that |
| 783 | Transfer-Encoding: chunked is used, only the first chunk is |
| 784 | scanned. Parameter values separated by a chunk boundary, may |
| 785 | be randomly balanced if at all. |
| 786 | |
| 787 | If the parameter is found followed by an equal sign ('=') and |
| 788 | a value, then the value is hashed and divided by the total |
| 789 | weight of the running servers. The result designates which |
| 790 | server will receive the request. |
| 791 | |
| 792 | This is used to track user identifiers in requests and ensure |
| 793 | that a same user ID will always be sent to the same server as |
| 794 | long as no server goes up or down. If no value is found or if |
| 795 | the parameter is not found, then a round robin algorithm is |
| 796 | applied. Note that this algorithm may only be used in an HTTP |
| 797 | backend. This algorithm is static, which means that changing a |
| 798 | server's weight on the fly will have no effect. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 799 | |
| 800 | <arguments> is an optional list of arguments which may be needed by some |
Marek Majkowski | 9c30fc1 | 2008-04-27 23:25:55 +0200 | [diff] [blame] | 801 | algorithms. Right now, only "url_param" and "uri" support an |
| 802 | optional argument. |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 803 | |
Marek Majkowski | 9c30fc1 | 2008-04-27 23:25:55 +0200 | [diff] [blame] | 804 | balance uri [len <len>] [depth <depth>] |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 805 | balance url_param <param> [check_post [<max_wait>]] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 806 | |
| 807 | The definition of the load balancing algorithm is mandatory for a backend |
| 808 | and limited to one per backend. |
| 809 | |
| 810 | Examples : |
| 811 | balance roundrobin |
| 812 | balance url_param userid |
matt.farnsworth@nokia.com | 1c2ab96 | 2008-04-14 20:47:37 +0200 | [diff] [blame] | 813 | balance url_param session_id check_post 64 |
| 814 | |
| 815 | Note: the following caveats and limitations on using the "check_post" |
| 816 | extension with "url_param" must be considered : |
| 817 | |
| 818 | - all POST requests are eligable for consideration, because there is no way |
| 819 | to determine if the parameters will be found in the body or entity which |
| 820 | may contain binary data. Therefore another method may be required to |
| 821 | restrict consideration of POST requests that have no URL parameters in |
| 822 | the body. (see acl reqideny http_end) |
| 823 | |
| 824 | - using a <max_wait> value larger than the request buffer size does not |
| 825 | make sense and is useless. The buffer size is set at build time, and |
| 826 | defaults to 16 kB. |
| 827 | |
| 828 | - Content-Encoding is not supported, the parameter search will probably |
| 829 | fail; and load balancing will fall back to Round Robin. |
| 830 | |
| 831 | - Expect: 100-continue is not supported, load balancing will fall back to |
| 832 | Round Robin. |
| 833 | |
| 834 | - Transfer-Encoding (RFC2616 3.6.1) is only supported in the first chunk. |
| 835 | If the entire parameter value is not present in the first chunk, the |
| 836 | selection of server is undefined (actually, defined by how little |
| 837 | actually appeared in the first chunk). |
| 838 | |
| 839 | - This feature does not support generation of a 100, 411 or 501 response. |
| 840 | |
| 841 | - In some cases, requesting "check_post" MAY attempt to scan the entire |
| 842 | contents of a message body. Scaning normally terminates when linear |
| 843 | white space or control characters are found, indicating the end of what |
| 844 | might be a URL parameter list. This is probably not a concern with SGML |
| 845 | type message bodies. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 846 | |
| 847 | See also : "dispatch", "cookie", "appsession", "transparent" and "http_proxy". |
| 848 | |
| 849 | |
| 850 | bind [<address>]:<port> [, ...] |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 851 | bind [<address>]:<port> [, ...] transparent |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 852 | Define one or several listening addresses and/or ports in a frontend. |
| 853 | May be used in sections : defaults | frontend | listen | backend |
| 854 | no | yes | yes | no |
| 855 | Arguments : |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 856 | <address> is optional and can be a host name, an IPv4 address, an IPv6 |
| 857 | address, or '*'. It designates the address the frontend will |
| 858 | listen on. If unset, all IPv4 addresses of the system will be |
| 859 | listened on. The same will apply for '*' or the system's |
| 860 | special address "0.0.0.0". |
| 861 | |
| 862 | <port> is the TCP port number the proxy will listen on. The port is |
| 863 | mandatory. Note that in the case of an IPv6 address, the port |
| 864 | is always the number after the last colon (':'). |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 865 | |
Willy Tarreau | b1e52e8 | 2008-01-13 14:49:51 +0100 | [diff] [blame] | 866 | transparent is an optional keyword which is supported only on certain |
| 867 | Linux kernels. It indicates that the addresses will be bound |
| 868 | even if they do not belong to the local machine. Any packet |
| 869 | targetting any of these addresses will be caught just as if |
| 870 | the address was locally configured. This normally requires |
| 871 | that IP forwarding is enabled. Caution! do not use this with |
| 872 | the default address '*', as it would redirect any traffic for |
| 873 | the specified port. This keyword is available only when |
| 874 | HAProxy is built with USE_LINUX_TPROXY=1. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 875 | |
| 876 | It is possible to specify a list of address:port combinations delimited by |
| 877 | commas. The frontend will then listen on all of these addresses. There is no |
| 878 | fixed limit to the number of addresses and ports which can be listened on in |
| 879 | a frontend, as well as there is no limit to the number of "bind" statements |
| 880 | in a frontend. |
| 881 | |
| 882 | Example : |
| 883 | listen http_proxy |
| 884 | bind :80,:443 |
| 885 | bind 10.0.0.1:10080,10.0.0.1:10443 |
| 886 | |
| 887 | See also : "source". |
| 888 | |
| 889 | |
| 890 | block { if | unless } <condition> |
| 891 | Block a layer 7 request if/unless a condition is matched |
| 892 | May be used in sections : defaults | frontend | listen | backend |
| 893 | no | yes | yes | yes |
| 894 | |
| 895 | The HTTP request will be blocked very early in the layer 7 processing |
| 896 | if/unless <condition> is matched. A 403 error will be returned if the request |
| 897 | is blocked. The condition has to reference ACLs (see section 2.3). This is |
| 898 | typically used to deny access to certain sensible resources if some |
| 899 | conditions are met or not met. There is no fixed limit to the number of |
| 900 | "block" statements per instance. |
| 901 | |
| 902 | Example: |
| 903 | acl invalid_src src 0.0.0.0/7 224.0.0.0/3 |
| 904 | acl invalid_src src_port 0:1023 |
| 905 | acl local_dst hdr(host) -i localhost |
| 906 | block if invalid_src || local_dst |
| 907 | |
| 908 | See section 2.3 about ACL usage. |
| 909 | |
| 910 | |
| 911 | capture cookie <name> len <length> |
| 912 | Capture and log a cookie in the request and in the response. |
| 913 | May be used in sections : defaults | frontend | listen | backend |
| 914 | no | yes | yes | no |
| 915 | Arguments : |
| 916 | <name> is the beginning of the name of the cookie to capture. In order |
| 917 | to match the exact name, simply suffix the name with an equal |
| 918 | sign ('='). The full name will appear in the logs, which is |
| 919 | useful with application servers which adjust both the cookie name |
| 920 | and value (eg: ASPSESSIONXXXXX). |
| 921 | |
| 922 | <length> is the maximum number of characters to report in the logs, which |
| 923 | include the cookie name, the equal sign and the value, all in the |
| 924 | standard "name=value" form. The string will be truncated on the |
| 925 | right if it exceeds <length>. |
| 926 | |
| 927 | Only the first cookie is captured. Both the "cookie" request headers and the |
| 928 | "set-cookie" response headers are monitored. This is particularly useful to |
| 929 | check for application bugs causing session crossing or stealing between |
| 930 | users, because generally the user's cookies can only change on a login page. |
| 931 | |
| 932 | When the cookie was not presented by the client, the associated log column |
| 933 | will report "-". When a request does not cause a cookie to be assigned by the |
| 934 | server, a "-" is reported in the response column. |
| 935 | |
| 936 | The capture is performed in the frontend only because it is necessary that |
| 937 | the log format does not change for a given frontend depending on the |
| 938 | backends. This may change in the future. Note that there can be only one |
| 939 | "capture cookie" statement in a frontend. The maximum capture length is |
| 940 | configured in the souces by default to 64 characters. It is not possible to |
| 941 | specify a capture in a "defaults" section. |
| 942 | |
| 943 | Example: |
| 944 | capture cookie ASPSESSION len 32 |
| 945 | |
| 946 | See also : "capture request header", "capture response header" as well as |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 947 | section 2.6 about logging. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 948 | |
| 949 | |
| 950 | capture request header <name> len <length> |
| 951 | Capture and log the first occurrence of the specified request header. |
| 952 | May be used in sections : defaults | frontend | listen | backend |
| 953 | no | yes | yes | no |
| 954 | Arguments : |
| 955 | <name> is the name of the header to capture. The header names are not |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 956 | case-sensitive, but it is a common practice to write them as they |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 957 | appear in the requests, with the first letter of each word in |
| 958 | upper case. The header name will not appear in the logs, only the |
| 959 | value is reported, but the position in the logs is respected. |
| 960 | |
| 961 | <length> is the maximum number of characters to extract from the value and |
| 962 | report in the logs. The string will be truncated on the right if |
| 963 | it exceeds <length>. |
| 964 | |
| 965 | Only the first value of the first occurrence of the header is captured. The |
| 966 | value will be added to the logs between braces ('{}'). If multiple headers |
| 967 | are captured, they will be delimited by a vertical bar ('|') and will appear |
| 968 | in the same order they were declared in the configuration. Common uses for |
| 969 | request header captures include the "Host" field in virtual hosting |
| 970 | environments, the "Content-length" when uploads are supported, "User-agent" |
| 971 | to quickly differenciate between real users and robots, and "X-Forwarded-For" |
| 972 | in proxied environments to find where the request came from. |
| 973 | |
| 974 | There is no limit to the number of captured request headers, but each capture |
| 975 | is limited to 64 characters. In order to keep log format consistent for a |
| 976 | same frontend, header captures can only be declared in a frontend. It is not |
| 977 | possible to specify a capture in a "defaults" section. |
| 978 | |
| 979 | Example: |
| 980 | capture request header Host len 15 |
| 981 | capture request header X-Forwarded-For len 15 |
| 982 | capture request header Referrer len 15 |
| 983 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 984 | See also : "capture cookie", "capture response header" as well as section 2.6 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 985 | about logging. |
| 986 | |
| 987 | |
| 988 | capture response header <name> len <length> |
| 989 | Capture and log the first occurrence of the specified response header. |
| 990 | May be used in sections : defaults | frontend | listen | backend |
| 991 | no | yes | yes | no |
| 992 | Arguments : |
| 993 | <name> is the name of the header to capture. The header names are not |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 994 | case-sensitive, but it is a common practice to write them as they |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 995 | appear in the response, with the first letter of each word in |
| 996 | upper case. The header name will not appear in the logs, only the |
| 997 | value is reported, but the position in the logs is respected. |
| 998 | |
| 999 | <length> is the maximum number of characters to extract from the value and |
| 1000 | report in the logs. The string will be truncated on the right if |
| 1001 | it exceeds <length>. |
| 1002 | |
| 1003 | Only the first value of the first occurrence of the header is captured. The |
| 1004 | result will be added to the logs between braces ('{}') after the captured |
| 1005 | request headers. If multiple headers are captured, they will be delimited by |
| 1006 | a vertical bar ('|') and will appear in the same order they were declared in |
| 1007 | the configuration. Common uses for response header captures include the |
| 1008 | "Content-length" header which indicates how many bytes are expected to be |
| 1009 | returned, the "Location" header to track redirections. |
| 1010 | |
| 1011 | There is no limit to the number of captured response headers, but each |
| 1012 | capture is limited to 64 characters. In order to keep log format consistent |
| 1013 | for a same frontend, header captures can only be declared in a frontend. It |
| 1014 | is not possible to specify a capture in a "defaults" section. |
| 1015 | |
| 1016 | Example: |
| 1017 | capture response header Content-length len 9 |
| 1018 | capture response header Location len 15 |
| 1019 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 1020 | See also : "capture cookie", "capture request header" as well as section 2.6 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1021 | about logging. |
| 1022 | |
| 1023 | |
| 1024 | clitimeout <timeout> |
| 1025 | Set the maximum inactivity time on the client side. |
| 1026 | May be used in sections : defaults | frontend | listen | backend |
| 1027 | yes | yes | yes | no |
| 1028 | Arguments : |
| 1029 | <timeout> is the timeout value is specified in milliseconds by default, but |
| 1030 | can be in any other unit if the number is suffixed by the unit, |
| 1031 | as explained at the top of this document. |
| 1032 | |
| 1033 | The inactivity timeout applies when the client is expected to acknowledge or |
| 1034 | send data. In HTTP mode, this timeout is particularly important to consider |
| 1035 | during the first phase, when the client sends the request, and during the |
| 1036 | response while it is reading data sent by the server. The value is specified |
| 1037 | in milliseconds by default, but can be in any other unit if the number is |
| 1038 | suffixed by the unit, as specified at the top of this document. In TCP mode |
| 1039 | (and to a lesser extent, in HTTP mode), it is highly recommended that the |
| 1040 | client timeout remains equal to the server timeout in order to avoid complex |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 1041 | situations to debug. It is a good practice to cover one or several TCP packet |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1042 | losses by specifying timeouts that are slightly above multiples of 3 seconds |
| 1043 | (eg: 4 or 5 seconds). |
| 1044 | |
| 1045 | This parameter is specific to frontends, but can be specified once for all in |
| 1046 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 1047 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 1048 | is not recommended. Such a usage is accepted and works but reports a warning |
| 1049 | during startup because it may results in accumulation of expired sessions in |
| 1050 | the system if the system's timeouts are not configured either. |
| 1051 | |
| 1052 | This parameter is provided for compatibility but is currently deprecated. |
| 1053 | Please use "timeout client" instead. |
| 1054 | |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 1055 | See also : "timeout client", "timeout http-request", "timeout server", and |
| 1056 | "srvtimeout". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1057 | |
| 1058 | |
| 1059 | contimeout <timeout> |
| 1060 | Set the maximum time to wait for a connection attempt to a server to succeed. |
| 1061 | May be used in sections : defaults | frontend | listen | backend |
| 1062 | yes | no | yes | yes |
| 1063 | Arguments : |
| 1064 | <timeout> is the timeout value is specified in milliseconds by default, but |
| 1065 | can be in any other unit if the number is suffixed by the unit, |
| 1066 | as explained at the top of this document. |
| 1067 | |
| 1068 | If the server is located on the same LAN as haproxy, the connection should be |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 1069 | immediate (less than a few milliseconds). Anyway, it is a good practice to |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1070 | cover one or several TCP packet losses by specifying timeouts that are |
| 1071 | slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the |
| 1072 | connect timeout also presets the queue timeout to the same value if this one |
| 1073 | has not been specified. Historically, the contimeout was also used to set the |
| 1074 | tarpit timeout in a listen section, which is not possible in a pure frontend. |
| 1075 | |
| 1076 | This parameter is specific to backends, but can be specified once for all in |
| 1077 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 1078 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 1079 | is not recommended. Such a usage is accepted and works but reports a warning |
| 1080 | during startup because it may results in accumulation of failed sessions in |
| 1081 | the system if the system's timeouts are not configured either. |
| 1082 | |
| 1083 | This parameter is provided for backwards compatibility but is currently |
| 1084 | deprecated. Please use "timeout connect", "timeout queue" or "timeout tarpit" |
| 1085 | instead. |
| 1086 | |
| 1087 | See also : "timeout connect", "timeout queue", "timeout tarpit", |
| 1088 | "timeout server", "contimeout". |
| 1089 | |
| 1090 | |
Krzysztof Piotr Oledzki | efe3b6f | 2008-05-23 23:49:32 +0200 | [diff] [blame] | 1091 | cookie <name> [ rewrite|insert|prefix ] [ indirect ] [ nocache ] [ postonly ] [domain <domain>] |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1092 | Enable cookie-based persistence in a backend. |
| 1093 | May be used in sections : defaults | frontend | listen | backend |
| 1094 | yes | no | yes | yes |
| 1095 | Arguments : |
| 1096 | <name> is the name of the cookie which will be monitored, modified or |
| 1097 | inserted in order to bring persistence. This cookie is sent to |
| 1098 | the client via a "Set-Cookie" header in the response, and is |
| 1099 | brought back by the client in a "Cookie" header in all requests. |
| 1100 | Special care should be taken to choose a name which does not |
| 1101 | conflict with any likely application cookie. Also, if the same |
| 1102 | backends are subject to be used by the same clients (eg: |
| 1103 | HTTP/HTTPS), care should be taken to use different cookie names |
| 1104 | between all backends if persistence between them is not desired. |
| 1105 | |
| 1106 | rewrite This keyword indicates that the cookie will be provided by the |
| 1107 | server and that haproxy will have to modify its value to set the |
| 1108 | server's identifier in it. This mode is handy when the management |
| 1109 | of complex combinations of "Set-cookie" and "Cache-control" |
| 1110 | headers is left to the application. The application can then |
| 1111 | decide whether or not it is appropriate to emit a persistence |
| 1112 | cookie. Since all responses should be monitored, this mode only |
| 1113 | works in HTTP close mode. Unless the application behaviour is |
| 1114 | very complex and/or broken, it is advised not to start with this |
| 1115 | mode for new deployments. This keyword is incompatible with |
| 1116 | "insert" and "prefix". |
| 1117 | |
| 1118 | insert This keyword indicates that the persistence cookie will have to |
| 1119 | be inserted by haproxy in the responses. If the server emits a |
| 1120 | cookie with the same name, it will be replaced anyway. For this |
| 1121 | reason, this mode can be used to upgrade existing configurations |
| 1122 | running in the "rewrite" mode. The cookie will only be a session |
| 1123 | cookie and will not be stored on the client's disk. Due to |
| 1124 | caching effects, it is generally wise to add the "indirect" and |
| 1125 | "nocache" or "postonly" keywords (see below). The "insert" |
| 1126 | keyword is not compatible with "rewrite" and "prefix". |
| 1127 | |
| 1128 | prefix This keyword indicates that instead of relying on a dedicated |
| 1129 | cookie for the persistence, an existing one will be completed. |
| 1130 | This may be needed in some specific environments where the client |
| 1131 | does not support more than one single cookie and the application |
| 1132 | already needs it. In this case, whenever the server sets a cookie |
| 1133 | named <name>, it will be prefixed with the server's identifier |
| 1134 | and a delimiter. The prefix will be removed from all client |
| 1135 | requests so that the server still finds the cookie it emitted. |
| 1136 | Since all requests and responses are subject to being modified, |
| 1137 | this mode requires the HTTP close mode. The "prefix" keyword is |
| 1138 | not compatible with "rewrite" and "insert". |
| 1139 | |
| 1140 | indirect When this option is specified in insert mode, cookies will only |
| 1141 | be added when the server was not reached after a direct access, |
| 1142 | which means that only when a server is elected after applying a |
| 1143 | load-balancing algorithm, or after a redispatch, then the cookie |
| 1144 | will be inserted. If the client has all the required information |
| 1145 | to connect to the same server next time, no further cookie will |
| 1146 | be inserted. In all cases, when the "indirect" option is used in |
| 1147 | insert mode, the cookie is always removed from the requests |
| 1148 | transmitted to the server. The persistence mechanism then becomes |
| 1149 | totally transparent from the application point of view. |
| 1150 | |
| 1151 | nocache This option is recommended in conjunction with the insert mode |
| 1152 | when there is a cache between the client and HAProxy, as it |
| 1153 | ensures that a cacheable response will be tagged non-cacheable if |
| 1154 | a cookie needs to be inserted. This is important because if all |
| 1155 | persistence cookies are added on a cacheable home page for |
| 1156 | instance, then all customers will then fetch the page from an |
| 1157 | outer cache and will all share the same persistence cookie, |
| 1158 | leading to one server receiving much more traffic than others. |
| 1159 | See also the "insert" and "postonly" options. |
| 1160 | |
| 1161 | postonly This option ensures that cookie insertion will only be performed |
| 1162 | on responses to POST requests. It is an alternative to the |
| 1163 | "nocache" option, because POST responses are not cacheable, so |
| 1164 | this ensures that the persistence cookie will never get cached. |
| 1165 | Since most sites do not need any sort of persistence before the |
| 1166 | first POST which generally is a login request, this is a very |
| 1167 | efficient method to optimize caching without risking to find a |
| 1168 | persistence cookie in the cache. |
| 1169 | See also the "insert" and "nocache" options. |
| 1170 | |
Krzysztof Piotr Oledzki | efe3b6f | 2008-05-23 23:49:32 +0200 | [diff] [blame] | 1171 | domain This option allows to specify the domain at which a cookie is |
| 1172 | inserted. It requires exactly one paramater: a valid domain |
| 1173 | name. |
| 1174 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1175 | There can be only one persistence cookie per HTTP backend, and it can be |
| 1176 | declared in a defaults section. The value of the cookie will be the value |
| 1177 | indicated after the "cookie" keyword in a "server" statement. If no cookie |
| 1178 | is declared for a given server, the cookie is not set. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1179 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1180 | Examples : |
| 1181 | cookie JSESSIONID prefix |
| 1182 | cookie SRV insert indirect nocache |
| 1183 | cookie SRV insert postonly indirect |
| 1184 | |
| 1185 | See also : "appsession", "balance source", "capture cookie", "server". |
| 1186 | |
| 1187 | |
| 1188 | default_backend <backend> |
| 1189 | Specify the backend to use when no "use_backend" rule has been matched. |
| 1190 | May be used in sections : defaults | frontend | listen | backend |
| 1191 | yes | yes | yes | no |
| 1192 | Arguments : |
| 1193 | <backend> is the name of the backend to use. |
| 1194 | |
| 1195 | When doing content-switching between frontend and backends using the |
| 1196 | "use_backend" keyword, it is often useful to indicate which backend will be |
| 1197 | used when no rule has matched. It generally is the dynamic backend which |
| 1198 | will catch all undetermined requests. |
| 1199 | |
| 1200 | The "default_backend" keyword is also supported in TCP mode frontends to |
| 1201 | facilitate the ordering of configurations in frontends and backends, |
| 1202 | eventhough it does not make much more sense in case of TCP due to the fact |
| 1203 | that use_backend currently does not work in TCP mode. |
| 1204 | |
| 1205 | Example : |
| 1206 | |
| 1207 | use_backend dynamic if url_dyn |
| 1208 | use_backend static if url_css url_img extension_img |
| 1209 | default_backend dynamic |
| 1210 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1211 | See also : "use_backend", "reqsetbe", "reqisetbe" |
| 1212 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1213 | |
| 1214 | disabled |
| 1215 | Disable a proxy, frontend or backend. |
| 1216 | May be used in sections : defaults | frontend | listen | backend |
| 1217 | yes | yes | yes | yes |
| 1218 | Arguments : none |
| 1219 | |
| 1220 | The "disabled" keyword is used to disable an instance, mainly in order to |
| 1221 | liberate a listening port or to temporarily disable a service. The instance |
| 1222 | will still be created and its configuration will be checked, but it will be |
| 1223 | created in the "stopped" state and will appear as such in the statistics. It |
| 1224 | will not receive any traffic nor will it send any health-checks or logs. It |
| 1225 | is possible to disable many instances at once by adding the "disabled" |
| 1226 | keyword in a "defaults" section. |
| 1227 | |
| 1228 | See also : "enabled" |
| 1229 | |
| 1230 | |
| 1231 | enabled |
| 1232 | Enable a proxy, frontend or backend. |
| 1233 | May be used in sections : defaults | frontend | listen | backend |
| 1234 | yes | yes | yes | yes |
| 1235 | Arguments : none |
| 1236 | |
| 1237 | The "enabled" keyword is used to explicitly enable an instance, when the |
| 1238 | defaults has been set to "disabled". This is very rarely used. |
| 1239 | |
| 1240 | See also : "disabled" |
| 1241 | |
| 1242 | |
| 1243 | errorfile <code> <file> |
| 1244 | Return a file contents instead of errors generated by HAProxy |
| 1245 | May be used in sections : defaults | frontend | listen | backend |
| 1246 | yes | yes | yes | yes |
| 1247 | Arguments : |
| 1248 | <code> is the HTTP status code. Currently, HAProxy is capable of |
| 1249 | generating codes 400, 403, 408, 500, 502, 503, and 504. |
| 1250 | |
| 1251 | <file> designates a file containing the full HTTP response. It is |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 1252 | recommended to follow the common practice of appending ".http" to |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1253 | the filename so that people do not confuse the response with HTML |
| 1254 | error pages. |
| 1255 | |
| 1256 | It is important to understand that this keyword is not meant to rewrite |
| 1257 | errors returned by the server, but errors detected and returned by HAProxy. |
| 1258 | This is why the list of supported errors is limited to a small set. |
| 1259 | |
| 1260 | The files are returned verbatim on the TCP socket. This allows any trick such |
| 1261 | as redirections to another URL or site, as well as tricks to clean cookies, |
| 1262 | force enable or disable caching, etc... The package provides default error |
| 1263 | files returning the same contents as default errors. |
| 1264 | |
| 1265 | The files are read at the same time as the configuration and kept in memory. |
| 1266 | For this reason, the errors continue to be returned even when the process is |
| 1267 | chrooted, and no file change is considered while the process is running. A |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 1268 | simple method for developing those files consists in associating them to the |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1269 | 403 status code and interrogating a blocked URL. |
| 1270 | |
| 1271 | See also : "errorloc", "errorloc302", "errorloc303" |
| 1272 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1273 | |
| 1274 | errorloc <code> <url> |
| 1275 | errorloc302 <code> <url> |
| 1276 | Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| 1277 | May be used in sections : defaults | frontend | listen | backend |
| 1278 | yes | yes | yes | yes |
| 1279 | Arguments : |
| 1280 | <code> is the HTTP status code. Currently, HAProxy is capable of |
| 1281 | generating codes 400, 403, 408, 500, 502, 503, and 504. |
| 1282 | |
| 1283 | <url> it is the exact contents of the "Location" header. It may contain |
| 1284 | either a relative URI to an error page hosted on the same site, |
| 1285 | or an absolute URI designating an error page on another site. |
| 1286 | Special care should be given to relative URIs to avoid redirect |
| 1287 | loops if the URI itself may generate the same error (eg: 500). |
| 1288 | |
| 1289 | It is important to understand that this keyword is not meant to rewrite |
| 1290 | errors returned by the server, but errors detected and returned by HAProxy. |
| 1291 | This is why the list of supported errors is limited to a small set. |
| 1292 | |
| 1293 | Note that both keyword return the HTTP 302 status code, which tells the |
| 1294 | client to fetch the designated URL using the same HTTP method. This can be |
| 1295 | quite problematic in case of non-GET methods such as POST, because the URL |
| 1296 | sent to the client might not be allowed for something other than GET. To |
| 1297 | workaround this problem, please use "errorloc303" which send the HTTP 303 |
| 1298 | status code, indicating to the client that the URL must be fetched with a GET |
| 1299 | request. |
| 1300 | |
| 1301 | See also : "errorfile", "errorloc303" |
| 1302 | |
| 1303 | |
| 1304 | errorloc303 <code> <url> |
| 1305 | Return an HTTP redirection to a URL instead of errors generated by HAProxy |
| 1306 | May be used in sections : defaults | frontend | listen | backend |
| 1307 | yes | yes | yes | yes |
| 1308 | Arguments : |
| 1309 | <code> is the HTTP status code. Currently, HAProxy is capable of |
| 1310 | generating codes 400, 403, 408, 500, 502, 503, and 504. |
| 1311 | |
| 1312 | <url> it is the exact contents of the "Location" header. It may contain |
| 1313 | either a relative URI to an error page hosted on the same site, |
| 1314 | or an absolute URI designating an error page on another site. |
| 1315 | Special care should be given to relative URIs to avoid redirect |
| 1316 | loops if the URI itself may generate the same error (eg: 500). |
| 1317 | |
| 1318 | It is important to understand that this keyword is not meant to rewrite |
| 1319 | errors returned by the server, but errors detected and returned by HAProxy. |
| 1320 | This is why the list of supported errors is limited to a small set. |
| 1321 | |
| 1322 | Note that both keyword return the HTTP 303 status code, which tells the |
| 1323 | client to fetch the designated URL using the same HTTP GET method. This |
| 1324 | solves the usual problems associated with "errorloc" and the 302 code. It is |
| 1325 | possible that some very old browsers designed before HTTP/1.1 do not support |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 1326 | it, but no such problem has been reported till now. |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1327 | |
| 1328 | See also : "errorfile", "errorloc", "errorloc302" |
| 1329 | |
| 1330 | |
| 1331 | fullconn <conns> |
| 1332 | Specify at what backend load the servers will reach their maxconn |
| 1333 | May be used in sections : defaults | frontend | listen | backend |
| 1334 | yes | no | yes | yes |
| 1335 | Arguments : |
| 1336 | <conns> is the number of connections on the backend which will make the |
| 1337 | servers use the maximal number of connections. |
| 1338 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1339 | When a server has a "maxconn" parameter specified, it means that its number |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1340 | of concurrent connections will never go higher. Additionally, if it has a |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1341 | "minconn" parameter, it indicates a dynamic limit following the backend's |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1342 | load. The server will then always accept at least <minconn> connections, |
| 1343 | never more than <maxconn>, and the limit will be on the ramp between both |
| 1344 | values when the backend has less than <conns> concurrent connections. This |
| 1345 | makes it possible to limit the load on the servers during normal loads, but |
| 1346 | push it further for important loads without overloading the servers during |
| 1347 | exceptionnal loads. |
| 1348 | |
| 1349 | Example : |
| 1350 | # The servers will accept between 100 and 1000 concurrent connections each |
| 1351 | # and the maximum of 1000 will be reached when the backend reaches 10000 |
| 1352 | # connections. |
| 1353 | backend dynamic |
| 1354 | fullconn 10000 |
| 1355 | server srv1 dyn1:80 minconn 100 maxconn 1000 |
| 1356 | server srv2 dyn2:80 minconn 100 maxconn 1000 |
| 1357 | |
| 1358 | See also : "maxconn", "server" |
| 1359 | |
| 1360 | |
| 1361 | grace <time> |
| 1362 | Maintain a proxy operational for some time after a soft stop |
| 1363 | May be used in sections : defaults | frontend | listen | backend |
| 1364 | no | yes | yes | yes |
| 1365 | Arguments : |
| 1366 | <time> is the time (by default in milliseconds) for which the instance |
| 1367 | will remain operational with the frontend sockets still listening |
| 1368 | when a soft-stop is received via the SIGUSR1 signal. |
| 1369 | |
| 1370 | This may be used to ensure that the services disappear in a certain order. |
| 1371 | This was designed so that frontends which are dedicated to monitoring by an |
| 1372 | external equipement fail immediately while other ones remain up for the time |
| 1373 | needed by the equipment to detect the failure. |
| 1374 | |
| 1375 | Note that currently, there is very little benefit in using this parameter, |
| 1376 | and it may in fact complicate the soft-reconfiguration process more than |
| 1377 | simplify it. |
| 1378 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1379 | |
| 1380 | http-check disable-on-404 |
| 1381 | Enable a maintenance mode upon HTTP/404 response to health-checks |
| 1382 | May be used in sections : defaults | frontend | listen | backend |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1383 | yes | no | yes | yes |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1384 | Arguments : none |
| 1385 | |
| 1386 | When this option is set, a server which returns an HTTP code 404 will be |
| 1387 | excluded from further load-balancing, but will still receive persistent |
| 1388 | connections. This provides a very convenient method for Web administrators |
| 1389 | to perform a graceful shutdown of their servers. It is also important to note |
| 1390 | that a server which is detected as failed while it was in this mode will not |
| 1391 | generate an alert, just a notice. If the server responds 2xx or 3xx again, it |
| 1392 | will immediately be reinserted into the farm. The status on the stats page |
| 1393 | reports "NOLB" for a server in this mode. It is important to note that this |
| 1394 | option only works in conjunction with the "httpchk" option. |
| 1395 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1396 | See also : "option httpchk" |
| 1397 | |
| 1398 | |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 1399 | id <value> |
| 1400 | Set a persistent value for proxy ID. Must be unique and larger than 1000, as |
| 1401 | smaller values are reserved for auto-assigned ids. |
| 1402 | |
| 1403 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1404 | log global |
| 1405 | log <address> <facility> [<level>] |
| 1406 | Enable per-instance logging of events and traffic. |
| 1407 | May be used in sections : defaults | frontend | listen | backend |
| 1408 | yes | yes | yes | yes |
| 1409 | Arguments : |
| 1410 | global should be used when the instance's logging parameters are the |
| 1411 | same as the global ones. This is the most common usage. "global" |
| 1412 | replaces <address>, <facility> and <level> with those of the log |
| 1413 | entries found in the "global" section. Only one "log global" |
| 1414 | statement may be used per instance, and this form takes no other |
| 1415 | parameter. |
| 1416 | |
| 1417 | <address> indicates where to send the logs. It takes the same format as |
| 1418 | for the "global" section's logs, and can be one of : |
| 1419 | |
| 1420 | - An IPv4 address optionally followed by a colon (':') and a UDP |
| 1421 | port. If no port is specified, 514 is used by default (the |
| 1422 | standard syslog port). |
| 1423 | |
| 1424 | - A filesystem path to a UNIX domain socket, keeping in mind |
| 1425 | considerations for chroot (be sure the path is accessible |
| 1426 | inside the chroot) and uid/gid (be sure the path is |
| 1427 | appropriately writeable). |
| 1428 | |
| 1429 | <facility> must be one of the 24 standard syslog facilities : |
| 1430 | |
| 1431 | kern user mail daemon auth syslog lpr news |
| 1432 | uucp cron auth2 ftp ntp audit alert cron2 |
| 1433 | local0 local1 local2 local3 local4 local5 local6 local7 |
| 1434 | |
| 1435 | <level> is optional and can be specified to filter outgoing messages. By |
| 1436 | default, all messages are sent. If a level is specified, only |
| 1437 | messages with a severity at least as important as this level |
| 1438 | will be sent. 8 levels are known : |
| 1439 | |
| 1440 | emerg alert crit err warning notice info debug |
| 1441 | |
| 1442 | Note that up to two "log" entries may be specified per instance. However, if |
| 1443 | "log global" is used and if the "global" section already contains 2 log |
| 1444 | entries, then additional log entries will be ignored. |
| 1445 | |
| 1446 | Also, it is important to keep in mind that it is the frontend which decides |
| 1447 | what to log, and that in case of content switching, the log entries from the |
| 1448 | backend will be ignored. |
| 1449 | |
| 1450 | Example : |
| 1451 | log global |
| 1452 | log 127.0.0.1:514 local0 notice |
| 1453 | |
| 1454 | |
| 1455 | maxconn <conns> |
| 1456 | Fix the maximum number of concurrent connections on a frontend |
| 1457 | May be used in sections : defaults | frontend | listen | backend |
| 1458 | yes | yes | yes | no |
| 1459 | Arguments : |
| 1460 | <conns> is the maximum number of concurrent connections the frontend will |
| 1461 | accept to serve. Excess connections will be queued by the system |
| 1462 | in the socket's listen queue and will be served once a connection |
| 1463 | closes. |
| 1464 | |
| 1465 | If the system supports it, it can be useful on big sites to raise this limit |
| 1466 | very high so that haproxy manages connection queues, instead of leaving the |
| 1467 | clients with unanswered connection attempts. This value should not exceed the |
| 1468 | global maxconn. Also, keep in mind that a connection contains two buffers |
| 1469 | of 8kB each, as well as some other data resulting in about 17 kB of RAM being |
| 1470 | consumed per established connection. That means that a medium system equipped |
| 1471 | with 1GB of RAM can withstand around 40000-50000 concurrent connections if |
| 1472 | properly tuned. |
| 1473 | |
| 1474 | Also, when <conns> is set to large values, it is possible that the servers |
| 1475 | are not sized to accept such loads, and for this reason it is generally wise |
| 1476 | to assign them some reasonable connection limits. |
| 1477 | |
| 1478 | See also : "server", global section's "maxconn", "fullconn" |
| 1479 | |
| 1480 | |
| 1481 | mode { tcp|http|health } |
| 1482 | Set the running mode or protocol of the instance |
| 1483 | May be used in sections : defaults | frontend | listen | backend |
| 1484 | yes | yes | yes | yes |
| 1485 | Arguments : |
| 1486 | tcp The instance will work in pure TCP mode. A full-duplex connection |
| 1487 | will be established between clients and servers, and no layer 7 |
| 1488 | examination will be performed. This is the default mode. It |
| 1489 | should be used for SSL, SSH, SMTP, ... |
| 1490 | |
| 1491 | http The instance will work in HTTP mode. The client request will be |
| 1492 | analyzed in depth before connecting to any server. Any request |
| 1493 | which is not RFC-compliant will be rejected. Layer 7 filtering, |
| 1494 | processing and switching will be possible. This is the mode which |
| 1495 | brings HAProxy most of its value. |
| 1496 | |
| 1497 | health The instance will work in "health" mode. It will just reply "OK" |
| 1498 | to incoming connections and close the connection. Nothing will be |
| 1499 | logged. This mode is used to reply to external components health |
| 1500 | checks. This mode is deprecated and should not be used anymore as |
| 1501 | it is possible to do the same and even better by combining TCP or |
| 1502 | HTTP modes with the "monitor" keyword. |
| 1503 | |
| 1504 | When doing content switching, it is mandatory that the frontend and the |
| 1505 | backend are in the same mode (generally HTTP), otherwise the configuration |
| 1506 | will be refused. |
| 1507 | |
| 1508 | Example : |
| 1509 | defaults http_instances |
| 1510 | mode http |
| 1511 | |
| 1512 | See also : "monitor", "monitor-net" |
| 1513 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1514 | |
| 1515 | monitor fail [if | unless] <condition> |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1516 | Add a condition to report a failure to a monitor HTTP request. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1517 | May be used in sections : defaults | frontend | listen | backend |
| 1518 | no | yes | yes | no |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1519 | Arguments : |
| 1520 | if <cond> the monitor request will fail if the condition is satisfied, |
| 1521 | and will succeed otherwise. The condition should describe a |
| 1522 | combinated test which must induce a failure if all conditions |
| 1523 | are met, for instance a low number of servers both in a |
| 1524 | backend and its backup. |
| 1525 | |
| 1526 | unless <cond> the monitor request will succeed only if the condition is |
| 1527 | satisfied, and will fail otherwise. Such a condition may be |
| 1528 | based on a test on the presence of a minimum number of active |
| 1529 | servers in a list of backends. |
| 1530 | |
| 1531 | This statement adds a condition which can force the response to a monitor |
| 1532 | request to report a failure. By default, when an external component queries |
| 1533 | the URI dedicated to monitoring, a 200 response is returned. When one of the |
| 1534 | conditions above is met, haproxy will return 503 instead of 200. This is |
| 1535 | very useful to report a site failure to an external component which may base |
| 1536 | routing advertisements between multiple sites on the availability reported by |
| 1537 | haproxy. In this case, one would rely on an ACL involving the "nbsrv" |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1538 | criterion. Note that "monitor fail" only works in HTTP mode. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1539 | |
| 1540 | Example: |
| 1541 | frontend www |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1542 | mode http |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1543 | acl site_dead nbsrv(dynamic) lt 2 |
| 1544 | acl site_dead nbsrv(static) lt 2 |
| 1545 | monitor-uri /site_alive |
| 1546 | monitor fail if site_dead |
| 1547 | |
Willy Tarreau | 2769aa0 | 2007-12-27 18:26:09 +0100 | [diff] [blame] | 1548 | See also : "monitor-net", "monitor-uri" |
| 1549 | |
| 1550 | |
| 1551 | monitor-net <source> |
| 1552 | Declare a source network which is limited to monitor requests |
| 1553 | May be used in sections : defaults | frontend | listen | backend |
| 1554 | yes | yes | yes | no |
| 1555 | Arguments : |
| 1556 | <source> is the source IPv4 address or network which will only be able to |
| 1557 | get monitor responses to any request. It can be either an IPv4 |
| 1558 | address, a host name, or an address followed by a slash ('/') |
| 1559 | followed by a mask. |
| 1560 | |
| 1561 | In TCP mode, any connection coming from a source matching <source> will cause |
| 1562 | the connection to be immediately closed without any log. This allows another |
| 1563 | equipement to probe the port and verify that it is still listening, without |
| 1564 | forwarding the connection to a remote server. |
| 1565 | |
| 1566 | In HTTP mode, a connection coming from a source matching <source> will be |
| 1567 | accepted, the following response will be sent without waiting for a request, |
| 1568 | then the connection will be closed : "HTTP/1.0 200 OK". This is normally |
| 1569 | enough for any front-end HTTP probe to detect that the service is UP and |
| 1570 | running without forwarding the request to a backend server. |
| 1571 | |
| 1572 | Monitor requests are processed very early. It is not possible to block nor |
| 1573 | divert them using ACLs. They cannot be logged either, and it is the intended |
| 1574 | purpose. They are only used to report HAProxy's health to an upper component, |
| 1575 | nothing more. Right now, it is not possible to set failure conditions on |
| 1576 | requests caught by "monitor-net". |
| 1577 | |
| 1578 | Example : |
| 1579 | # addresses .252 and .253 are just probing us. |
| 1580 | frontend www |
| 1581 | monitor-net 192.168.0.252/31 |
| 1582 | |
| 1583 | See also : "monitor fail", "monitor-uri" |
| 1584 | |
| 1585 | |
| 1586 | monitor-uri <uri> |
| 1587 | Intercept a URI used by external components' monitor requests |
| 1588 | May be used in sections : defaults | frontend | listen | backend |
| 1589 | yes | yes | yes | no |
| 1590 | Arguments : |
| 1591 | <uri> is the exact URI which we want to intercept to return HAProxy's |
| 1592 | health status instead of forwarding the request. |
| 1593 | |
| 1594 | When an HTTP request referencing <uri> will be received on a frontend, |
| 1595 | HAProxy will not forward it nor log it, but instead will return either |
| 1596 | "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure |
| 1597 | conditions defined with "monitor fail". This is normally enough for any |
| 1598 | front-end HTTP probe to detect that the service is UP and running without |
| 1599 | forwarding the request to a backend server. Note that the HTTP method, the |
| 1600 | version and all headers are ignored, but the request must at least be valid |
| 1601 | at the HTTP level. This keyword may only be used with an HTTP-mode frontend. |
| 1602 | |
| 1603 | Monitor requests are processed very early. It is not possible to block nor |
| 1604 | divert them using ACLs. They cannot be logged either, and it is the intended |
| 1605 | purpose. They are only used to report HAProxy's health to an upper component, |
| 1606 | nothing more. However, it is possible to add any number of conditions using |
| 1607 | "monitor fail" and ACLs so that the result can be adjusted to whatever check |
| 1608 | can be imagined (most often the number of available servers in a backend). |
| 1609 | |
| 1610 | Example : |
| 1611 | # Use /haproxy_test to report haproxy's status |
| 1612 | frontend www |
| 1613 | mode http |
| 1614 | monitor-uri /haproxy_test |
| 1615 | |
| 1616 | See also : "monitor fail", "monitor-net" |
| 1617 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1618 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1619 | option abortonclose |
| 1620 | no option abortonclose |
| 1621 | Enable or disable early dropping of aborted requests pending in queues. |
| 1622 | May be used in sections : defaults | frontend | listen | backend |
| 1623 | yes | no | yes | yes |
| 1624 | Arguments : none |
| 1625 | |
| 1626 | In presence of very high loads, the servers will take some time to respond. |
| 1627 | The per-instance connection queue will inflate, and the response time will |
| 1628 | increase respective to the size of the queue times the average per-session |
| 1629 | response time. When clients will wait for more than a few seconds, they will |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1630 | often hit the "STOP" button on their browser, leaving a useless request in |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1631 | the queue, and slowing down other users, and the servers as well, because the |
| 1632 | request will eventually be served, then aborted at the first error |
| 1633 | encountered while delivering the response. |
| 1634 | |
| 1635 | As there is no way to distinguish between a full STOP and a simple output |
| 1636 | close on the client side, HTTP agents should be conservative and consider |
| 1637 | that the client might only have closed its output channel while waiting for |
| 1638 | the response. However, this introduces risks of congestion when lots of users |
| 1639 | do the same, and is completely useless nowadays because probably no client at |
| 1640 | all will close the session while waiting for the response. Some HTTP agents |
| 1641 | support this behaviour (Squid, Apache, HAProxy), and others do not (TUX, most |
| 1642 | hardware-based load balancers). So the probability for a closed input channel |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1643 | to represent a user hitting the "STOP" button is close to 100%, and the risk |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1644 | of being the single component to break rare but valid traffic is extremely |
| 1645 | low, which adds to the temptation to be able to abort a session early while |
| 1646 | still not served and not pollute the servers. |
| 1647 | |
| 1648 | In HAProxy, the user can choose the desired behaviour using the option |
| 1649 | "abortonclose". By default (without the option) the behaviour is HTTP |
| 1650 | compliant and aborted requests will be served. But when the option is |
| 1651 | specified, a session with an incoming channel closed will be aborted while |
| 1652 | it is still possible, either pending in the queue for a connection slot, or |
| 1653 | during the connection establishment if the server has not yet acknowledged |
| 1654 | the connection request. This considerably reduces the queue size and the load |
| 1655 | on saturated servers when users are tempted to click on STOP, which in turn |
| 1656 | reduces the response time for other users. |
| 1657 | |
| 1658 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1659 | in a specific instance by prepending the "no" keyword before it. |
| 1660 | |
| 1661 | See also : "timeout queue" and server's "maxconn" and "maxqueue" parameters |
| 1662 | |
| 1663 | |
| 1664 | option allbackups |
| 1665 | no option allbackups |
| 1666 | Use either all backup servers at a time or only the first one |
| 1667 | May be used in sections : defaults | frontend | listen | backend |
| 1668 | yes | no | yes | yes |
| 1669 | Arguments : none |
| 1670 | |
| 1671 | By default, the first operational backup server gets all traffic when normal |
| 1672 | servers are all down. Sometimes, it may be preferred to use multiple backups |
| 1673 | at once, because one will not be enough. When "option allbackups" is enabled, |
| 1674 | the load balancing will be performed among all backup servers when all normal |
| 1675 | ones are unavailable. The same load balancing algorithm will be used and the |
| 1676 | servers' weights will be respected. Thus, there will not be any priority |
| 1677 | order between the backup servers anymore. |
| 1678 | |
| 1679 | This option is mostly used with static server farms dedicated to return a |
| 1680 | "sorry" page when an application is completely offline. |
| 1681 | |
| 1682 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1683 | in a specific instance by prepending the "no" keyword before it. |
| 1684 | |
| 1685 | |
| 1686 | option checkcache |
| 1687 | no option checkcache |
| 1688 | Analyze all server responses and block requests with cachable cookies |
| 1689 | May be used in sections : defaults | frontend | listen | backend |
| 1690 | yes | no | yes | yes |
| 1691 | Arguments : none |
| 1692 | |
| 1693 | Some high-level frameworks set application cookies everywhere and do not |
| 1694 | always let enough control to the developer to manage how the responses should |
| 1695 | be cached. When a session cookie is returned on a cachable object, there is a |
| 1696 | high risk of session crossing or stealing between users traversing the same |
| 1697 | caches. In some situations, it is better to block the response than to let |
| 1698 | some sensible session information go in the wild. |
| 1699 | |
| 1700 | The option "checkcache" enables deep inspection of all server responses for |
| 1701 | strict compliance with HTTP specification in terms of cachability. It |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1702 | carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1703 | response to check if there's a risk of caching a cookie on a client-side |
| 1704 | proxy. When this option is enabled, the only responses which can be delivered |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1705 | to the client are : |
| 1706 | - all those without "Set-Cookie" header ; |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1707 | - all those with a return code other than 200, 203, 206, 300, 301, 410, |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1708 | provided that the server has not set a "Cache-control: public" header ; |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1709 | - all those that come from a POST request, provided that the server has not |
| 1710 | set a 'Cache-Control: public' header ; |
| 1711 | - those with a 'Pragma: no-cache' header |
| 1712 | - those with a 'Cache-control: private' header |
| 1713 | - those with a 'Cache-control: no-store' header |
| 1714 | - those with a 'Cache-control: max-age=0' header |
| 1715 | - those with a 'Cache-control: s-maxage=0' header |
| 1716 | - those with a 'Cache-control: no-cache' header |
| 1717 | - those with a 'Cache-control: no-cache="set-cookie"' header |
| 1718 | - those with a 'Cache-control: no-cache="set-cookie,' header |
| 1719 | (allowing other fields after set-cookie) |
| 1720 | |
| 1721 | If a response doesn't respect these requirements, then it will be blocked |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 1722 | just as if it was from an "rspdeny" filter, with an "HTTP 502 bad gateway". |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1723 | The session state shows "PH--" meaning that the proxy blocked the response |
| 1724 | during headers processing. Additionnaly, an alert will be sent in the logs so |
| 1725 | that admins are informed that there's something to be fixed. |
| 1726 | |
| 1727 | Due to the high impact on the application, the application should be tested |
| 1728 | in depth with the option enabled before going to production. It is also a |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 1729 | good practice to always activate it during tests, even if it is not used in |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1730 | production, as it will report potentially dangerous application behaviours. |
| 1731 | |
| 1732 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1733 | in a specific instance by prepending the "no" keyword before it. |
| 1734 | |
| 1735 | |
| 1736 | option clitcpka |
| 1737 | no option clitcpka |
| 1738 | Enable or disable the sending of TCP keepalive packets on the client side |
| 1739 | May be used in sections : defaults | frontend | listen | backend |
| 1740 | yes | yes | yes | no |
| 1741 | Arguments : none |
| 1742 | |
| 1743 | When there is a firewall or any session-aware component between a client and |
| 1744 | a server, and when the protocol involves very long sessions with long idle |
| 1745 | periods (eg: remote desktops), there is a risk that one of the intermediate |
| 1746 | components decides to expire a session which has remained idle for too long. |
| 1747 | |
| 1748 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 1749 | to the other end of the connection, leaving it active. The delay between |
| 1750 | keep-alive probes is controlled by the system only and depends both on the |
| 1751 | operating system and its tuning parameters. |
| 1752 | |
| 1753 | It is important to understand that keep-alive packets are neither emitted nor |
| 1754 | received at the application level. It is only the network stacks which sees |
| 1755 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 1756 | to maintain its connection alive, those keep-alive packets will not be |
| 1757 | forwarded to the other side of the proxy. |
| 1758 | |
| 1759 | Please note that this has nothing to do with HTTP keep-alive. |
| 1760 | |
| 1761 | Using option "clitcpka" enables the emission of TCP keep-alive probes on the |
| 1762 | client side of a connection, which should help when session expirations are |
| 1763 | noticed between HAProxy and a client. |
| 1764 | |
| 1765 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1766 | in a specific instance by prepending the "no" keyword before it. |
| 1767 | |
| 1768 | See also : "option srvtcpka", "option tcpka" |
| 1769 | |
| 1770 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 1771 | option contstats |
| 1772 | Enable continuous traffic statistics updates |
| 1773 | May be used in sections : defaults | frontend | listen | backend |
| 1774 | yes | yes | yes | no |
| 1775 | Arguments : none |
| 1776 | |
| 1777 | By default, counters used for statistics calculation are incremented |
| 1778 | only when a session finishes. It works quite well when serving small |
| 1779 | objects, but with big ones (for example large images or archives) or |
| 1780 | with A/V streaming, a graph generated from haproxy counters looks like |
| 1781 | a hedgehog. With this option enabled counters get incremented continuously, |
| 1782 | during a whole session. Recounting touches a hotpath directly so |
| 1783 | it is not enabled by default, as it has small performance impact (~0.5%). |
| 1784 | |
| 1785 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1786 | option dontlognull |
| 1787 | no option dontlognull |
| 1788 | Enable or disable logging of null connections |
| 1789 | May be used in sections : defaults | frontend | listen | backend |
| 1790 | yes | yes | yes | no |
| 1791 | Arguments : none |
| 1792 | |
| 1793 | In certain environments, there are components which will regularly connect to |
| 1794 | various systems to ensure that they are still alive. It can be the case from |
| 1795 | another load balancer as well as from monitoring systems. By default, even a |
| 1796 | simple port probe or scan will produce a log. If those connections pollute |
| 1797 | the logs too much, it is possible to enable option "dontlognull" to indicate |
| 1798 | that a connection on which no data has been transferred will not be logged, |
| 1799 | which typically corresponds to those probes. |
| 1800 | |
| 1801 | It is generally recommended not to use this option in uncontrolled |
| 1802 | environments (eg: internet), otherwise scans and other malicious activities |
| 1803 | would not be logged. |
| 1804 | |
| 1805 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1806 | in a specific instance by prepending the "no" keyword before it. |
| 1807 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 1808 | See also : "log", "monitor-net", "monitor-uri" and section 2.6 about logging. |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 1809 | |
| 1810 | |
| 1811 | option forceclose |
| 1812 | no option forceclose |
| 1813 | Enable or disable active connection closing after response is transferred. |
| 1814 | May be used in sections : defaults | frontend | listen | backend |
| 1815 | yes | no | yes | yes |
| 1816 | Arguments : none |
| 1817 | |
| 1818 | Some HTTP servers do not necessarily close the connections when they receive |
| 1819 | the "Connection: close" set by "option httpclose", and if the client does not |
| 1820 | close either, then the connection remains open till the timeout expires. This |
| 1821 | causes high number of simultaneous connections on the servers and shows high |
| 1822 | global session times in the logs. |
| 1823 | |
| 1824 | When this happens, it is possible to use "option forceclose". It will |
| 1825 | actively close the outgoing server channel as soon as the server begins to |
| 1826 | reply and only if the request buffer is empty. Note that this should NOT be |
| 1827 | used if CONNECT requests are expected between the client and the server. This |
| 1828 | option implicitly enables the "httpclose" option. |
| 1829 | |
| 1830 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1831 | in a specific instance by prepending the "no" keyword before it. |
| 1832 | |
| 1833 | See also : "option httpclose" |
| 1834 | |
| 1835 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 1836 | option forwardfor [ except <network> ] |
| 1837 | Enable insertion of the X-Forwarded-For header to requests sent to servers |
| 1838 | May be used in sections : defaults | frontend | listen | backend |
| 1839 | yes | yes | yes | yes |
| 1840 | Arguments : |
| 1841 | <network> is an optional argument used to disable this option for sources |
| 1842 | matching <network> |
| 1843 | |
| 1844 | Since HAProxy works in reverse-proxy mode, the servers see its IP address as |
| 1845 | their client address. This is sometimes annoying when the client's IP address |
| 1846 | is expected in server logs. To solve this problem, the well-known HTTP header |
| 1847 | "X-Forwarded-For" may be added by HAProxy to all requests sent to the server. |
| 1848 | This header contains a value representing the client's IP address. Since this |
| 1849 | header is always appended at the end of the existing header list, the server |
| 1850 | must be configured to always use the last occurrence of this header only. See |
| 1851 | the server's manual to find how to enable use of this standard header. |
| 1852 | |
| 1853 | Sometimes, a same HAProxy instance may be shared between a direct client |
| 1854 | access and a reverse-proxy access (for instance when an SSL reverse-proxy is |
| 1855 | used to decrypt HTTPS traffic). It is possible to disable the addition of the |
| 1856 | header for a known source address or network by adding the "except" keyword |
| 1857 | followed by the network address. In this case, any source IP matching the |
| 1858 | network will not cause an addition of this header. Most common uses are with |
| 1859 | private networks or 127.0.0.1. |
| 1860 | |
| 1861 | This option may be specified either in the frontend or in the backend. If at |
| 1862 | least one of them uses it, the header will be added. |
| 1863 | |
| 1864 | It is important to note that as long as HAProxy does not support keep-alive |
| 1865 | connections, only the first request of a connection will receive the header. |
| 1866 | For this reason, it is important to ensure that "option httpclose" is set |
| 1867 | when using this option. |
| 1868 | |
| 1869 | Example : |
| 1870 | # Public HTTP address also used by stunnel on the same machine |
| 1871 | frontend www |
| 1872 | mode http |
| 1873 | option forwardfor except 127.0.0.1 # stunnel already adds the header |
| 1874 | |
| 1875 | See also : "option httpclose" |
| 1876 | |
| 1877 | |
| 1878 | option http_proxy |
| 1879 | no option http_proxy |
| 1880 | Enable or disable plain HTTP proxy mode |
| 1881 | May be used in sections : defaults | frontend | listen | backend |
| 1882 | yes | yes | yes | yes |
| 1883 | Arguments : none |
| 1884 | |
| 1885 | It sometimes happens that people need a pure HTTP proxy which understands |
| 1886 | basic proxy requests without caching nor any fancy feature. In this case, |
| 1887 | it may be worth setting up an HAProxy instance with the "option http_proxy" |
| 1888 | set. In this mode, no server is declared, and the connection is forwarded to |
| 1889 | the IP address and port found in the URL after the "http://" scheme. |
| 1890 | |
| 1891 | No host address resolution is performed, so this only works when pure IP |
| 1892 | addresses are passed. Since this option's usage perimeter is rather limited, |
| 1893 | it will probably be used only by experts who know they need exactly it. Last, |
| 1894 | if the clients are susceptible of sending keep-alive requests, it will be |
| 1895 | needed to add "option http_close" to ensure that all requests will correctly |
| 1896 | be analyzed. |
| 1897 | |
| 1898 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1899 | in a specific instance by prepending the "no" keyword before it. |
| 1900 | |
| 1901 | Example : |
| 1902 | # this backend understands HTTP proxy requests and forwards them directly. |
| 1903 | backend direct_forward |
| 1904 | option httpclose |
| 1905 | option http_proxy |
| 1906 | |
| 1907 | See also : "option httpclose" |
| 1908 | |
| 1909 | |
| 1910 | option httpchk |
| 1911 | option httpchk <uri> |
| 1912 | option httpchk <method> <uri> |
| 1913 | option httpchk <method> <uri> <version> |
| 1914 | Enable HTTP protocol to check on the servers health |
| 1915 | May be used in sections : defaults | frontend | listen | backend |
| 1916 | yes | no | yes | yes |
| 1917 | Arguments : |
| 1918 | <method> is the optional HTTP method used with the requests. When not set, |
| 1919 | the "OPTIONS" method is used, as it generally requires low server |
| 1920 | processing and is easy to filter out from the logs. Any method |
| 1921 | may be used, though it is not recommended to invent non-standard |
| 1922 | ones. |
| 1923 | |
| 1924 | <uri> is the URI referenced in the HTTP requests. It defaults to " / " |
| 1925 | which is accessible by default on almost any server, but may be |
| 1926 | changed to any other URI. Query strings are permitted. |
| 1927 | |
| 1928 | <version> is the optional HTTP version string. It defaults to "HTTP/1.0" |
| 1929 | but some servers might behave incorrectly in HTTP 1.0, so turning |
| 1930 | it to HTTP/1.1 may sometimes help. Note that the Host field is |
| 1931 | mandatory in HTTP/1.1, and as a trick, it is possible to pass it |
| 1932 | after "\r\n" following the version string. |
| 1933 | |
| 1934 | By default, server health checks only consist in trying to establish a TCP |
| 1935 | connection. When "option httpchk" is specified, a complete HTTP request is |
| 1936 | sent once the TCP connection is established, and responses 2xx and 3xx are |
| 1937 | considered valid, while all other ones indicate a server failure, including |
| 1938 | the lack of any response. |
| 1939 | |
| 1940 | The port and interval are specified in the server configuration. |
| 1941 | |
| 1942 | This option does not necessarily require an HTTP backend, it also works with |
| 1943 | plain TCP backends. This is particularly useful to check simple scripts bound |
| 1944 | to some dedicated ports using the inetd daemon. |
| 1945 | |
| 1946 | Examples : |
| 1947 | # Relay HTTPS traffic to Apache instance and check service availability |
| 1948 | # using HTTP request "OPTIONS * HTTP/1.1" on port 80. |
| 1949 | backend https_relay |
| 1950 | mode tcp |
Willy Tarreau | ebaf21a | 2008-03-21 20:17:14 +0100 | [diff] [blame] | 1951 | option httpchk OPTIONS * HTTP/1.1\r\nHost:\ www |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 1952 | server apache1 192.168.1.1:443 check port 80 |
| 1953 | |
| 1954 | See also : "option ssl-hello-chk", "option smtpchk", "http-check" and the |
| 1955 | "check", "port" and "interval" server options. |
| 1956 | |
| 1957 | |
| 1958 | option httpclose |
| 1959 | no option httpclose |
| 1960 | Enable or disable passive HTTP connection closing |
| 1961 | May be used in sections : defaults | frontend | listen | backend |
| 1962 | yes | yes | yes | yes |
| 1963 | Arguments : none |
| 1964 | |
| 1965 | As stated in section 2.1, HAProxy does not yes support the HTTP keep-alive |
| 1966 | mode. So by default, if a client communicates with a server in this mode, it |
| 1967 | will only analyze, log, and process the first request of each connection. To |
| 1968 | workaround this limitation, it is possible to specify "option httpclose". It |
| 1969 | will check if a "Connection: close" header is already set in each direction, |
| 1970 | and will add one if missing. Each end should react to this by actively |
| 1971 | closing the TCP connection after each transfer, thus resulting in a switch to |
| 1972 | the HTTP close mode. Any "Connection" header different from "close" will also |
| 1973 | be removed. |
| 1974 | |
| 1975 | It seldom happens that some servers incorrectly ignore this header and do not |
| 1976 | close the connection eventough they reply "Connection: close". For this |
| 1977 | reason, they are not compatible with older HTTP 1.0 browsers. If this |
| 1978 | happens it is possible to use the "option forceclose" which actively closes |
| 1979 | the request connection once the server responds. |
| 1980 | |
| 1981 | This option may be set both in a frontend and in a backend. It is enabled if |
| 1982 | at least one of the frontend or backend holding a connection has it enabled. |
| 1983 | If "option forceclose" is specified too, it has precedence over "httpclose". |
| 1984 | |
| 1985 | If this option has been enabled in a "defaults" section, it can be disabled |
| 1986 | in a specific instance by prepending the "no" keyword before it. |
| 1987 | |
| 1988 | See also : "option forceclose" |
| 1989 | |
| 1990 | |
| 1991 | option httplog |
| 1992 | Enable logging of HTTP request, session state and timers |
| 1993 | May be used in sections : defaults | frontend | listen | backend |
| 1994 | yes | yes | yes | yes |
| 1995 | Arguments : none |
| 1996 | |
| 1997 | By default, the log output format is very poor, as it only contains the |
| 1998 | source and destination addresses, and the instance name. By specifying |
| 1999 | "option httplog", each log line turns into a much richer format including, |
| 2000 | but not limited to, the HTTP request, the connection timers, the session |
| 2001 | status, the connections numbers, the captured headers and cookies, the |
| 2002 | frontend, backend and server name, and of course the source address and |
| 2003 | ports. |
| 2004 | |
| 2005 | This option may be set either in the frontend or the backend. |
| 2006 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2007 | See also : section 2.6 about logging. |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 2008 | |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 2009 | |
| 2010 | option logasap |
| 2011 | no option logasap |
| 2012 | Enable or disable early logging of HTTP requests |
| 2013 | May be used in sections : defaults | frontend | listen | backend |
| 2014 | yes | yes | yes | no |
| 2015 | Arguments : none |
| 2016 | |
| 2017 | By default, HTTP requests are logged upon termination so that the total |
| 2018 | transfer time and the number of bytes appear in the logs. When large objects |
| 2019 | are being transferred, it may take a while before the request appears in the |
| 2020 | logs. Using "option logasap", the request gets logged as soon as the server |
| 2021 | sends the complete headers. The only missing information in the logs will be |
| 2022 | the total number of bytes which will indicate everything except the amount |
| 2023 | of data transferred, and the total time which will not take the transfer |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2024 | time into account. In such a situation, it's a good practice to capture the |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 2025 | "Content-Length" response header so that the logs at least indicate how many |
| 2026 | bytes are expected to be transferred. |
| 2027 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2028 | See also : "option httplog", "capture response header", and section 2.6 about |
Willy Tarreau | c27debf | 2008-01-06 08:57:02 +0100 | [diff] [blame] | 2029 | logging. |
| 2030 | |
| 2031 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 2032 | option nolinger |
| 2033 | no option nolinger |
| 2034 | Enable or disable immediate session ressource cleaning after close |
| 2035 | May be used in sections: defaults | frontend | listen | backend |
| 2036 | yes | yes | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2037 | Arguments : none |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 2038 | |
| 2039 | When clients or servers abort connections in a dirty way (eg: they are |
| 2040 | physically disconnected), the session timeouts triggers and the session is |
| 2041 | closed. But it will remain in FIN_WAIT1 state for some time in the system, |
| 2042 | using some resources and possibly limiting the ability to establish newer |
| 2043 | connections. |
| 2044 | |
| 2045 | When this happens, it is possible to activate "option nolinger" which forces |
| 2046 | the system to immediately remove any socket's pending data on close. Thus, |
| 2047 | the session is instantly purged from the system's tables. This usually has |
| 2048 | side effects such as increased number of TCP resets due to old retransmits |
| 2049 | getting immediately rejected. Some firewalls may sometimes complain about |
| 2050 | this too. |
| 2051 | |
| 2052 | For this reason, it is not recommended to use this option when not absolutely |
| 2053 | needed. You know that you need it when you have thousands of FIN_WAIT1 |
| 2054 | sessions on your system (TIME_WAIT ones do not count). |
| 2055 | |
| 2056 | This option may be used both on frontends and backends, depending on the side |
| 2057 | where it is required. Use it on the frontend for clients, and on the backend |
| 2058 | for servers. |
| 2059 | |
| 2060 | If this option has been enabled in a "defaults" section, it can be disabled |
| 2061 | in a specific instance by prepending the "no" keyword before it. |
| 2062 | |
| 2063 | |
| 2064 | option persist |
| 2065 | no option persist |
| 2066 | Enable or disable forced persistence on down servers |
| 2067 | May be used in sections: defaults | frontend | listen | backend |
| 2068 | yes | no | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2069 | Arguments : none |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 2070 | |
| 2071 | When an HTTP request reaches a backend with a cookie which references a dead |
| 2072 | server, by default it is redispatched to another server. It is possible to |
| 2073 | force the request to be sent to the dead server first using "option persist" |
| 2074 | if absolutely needed. A common use case is when servers are under extreme |
| 2075 | load and spend their time flapping. In this case, the users would still be |
| 2076 | directed to the server they opened the session on, in the hope they would be |
| 2077 | correctly served. It is recommended to use "option redispatch" in conjunction |
| 2078 | with this option so that in the event it would not be possible to connect to |
| 2079 | the server at all (server definitely dead), the client would finally be |
| 2080 | redirected to another valid server. |
| 2081 | |
| 2082 | If this option has been enabled in a "defaults" section, it can be disabled |
| 2083 | in a specific instance by prepending the "no" keyword before it. |
| 2084 | |
| 2085 | See also : "option redispatch", "retries" |
| 2086 | |
| 2087 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 2088 | option redispatch |
| 2089 | no option redispatch |
| 2090 | Enable or disable session redistribution in case of connection failure |
| 2091 | May be used in sections: defaults | frontend | listen | backend |
| 2092 | yes | no | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2093 | Arguments : none |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 2094 | |
| 2095 | In HTTP mode, if a server designated by a cookie is down, clients may |
| 2096 | definitely stick to it because they cannot flush the cookie, so they will not |
| 2097 | be able to access the service anymore. |
| 2098 | |
| 2099 | Specifying "option redispatch" will allow the proxy to break their |
| 2100 | persistence and redistribute them to a working server. |
| 2101 | |
| 2102 | It also allows to retry last connection to another server in case of multiple |
| 2103 | connection failures. Of course, it requires having "retries" set to a nonzero |
| 2104 | value. |
| 2105 | |
| 2106 | This form is the preferred form, which replaces both the "redispatch" and |
| 2107 | "redisp" keywords. |
| 2108 | |
| 2109 | If this option has been enabled in a "defaults" section, it can be disabled |
| 2110 | in a specific instance by prepending the "no" keyword before it. |
| 2111 | |
| 2112 | See also : "redispatch", "retries" |
| 2113 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 2114 | |
| 2115 | option smtpchk |
| 2116 | option smtpchk <hello> <domain> |
| 2117 | Use SMTP health checks for server testing |
| 2118 | May be used in sections : defaults | frontend | listen | backend |
| 2119 | yes | no | yes | yes |
| 2120 | Arguments : |
| 2121 | <hello> is an optional argument. It is the "hello" command to use. It can |
| 2122 | be either "HELO" (for SMTP) or "EHLO" (for ESTMP). All other |
| 2123 | values will be turned into the default command ("HELO"). |
| 2124 | |
| 2125 | <domain> is the domain name to present to the server. It may only be |
| 2126 | specified (and is mandatory) if the hello command has been |
| 2127 | specified. By default, "localhost" is used. |
| 2128 | |
| 2129 | When "option smtpchk" is set, the health checks will consist in TCP |
| 2130 | connections followed by an SMTP command. By default, this command is |
| 2131 | "HELO localhost". The server's return code is analyzed and only return codes |
| 2132 | starting with a "2" will be considered as valid. All other responses, |
| 2133 | including a lack of response will constitute an error and will indicate a |
| 2134 | dead server. |
| 2135 | |
| 2136 | This test is meant to be used with SMTP servers or relays. Depending on the |
| 2137 | request, it is possible that some servers do not log each connection attempt, |
| 2138 | so you may want to experiment to improve the behaviour. Using telnet on port |
| 2139 | 25 is often easier than adjusting the configuration. |
| 2140 | |
| 2141 | Most often, an incoming SMTP server needs to see the client's IP address for |
| 2142 | various purposes, including spam filtering, anti-spoofing and logging. When |
| 2143 | possible, it is often wise to masquerade the client's IP address when |
| 2144 | connecting to the server using the "usesrc" argument of the "source" keyword, |
| 2145 | which requires the cttproxy feature to be compiled in. |
| 2146 | |
| 2147 | Example : |
| 2148 | option smtpchk HELO mydomain.org |
| 2149 | |
| 2150 | See also : "option httpchk", "source" |
| 2151 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 2152 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 2153 | option srvtcpka |
| 2154 | no option srvtcpka |
| 2155 | Enable or disable the sending of TCP keepalive packets on the server side |
| 2156 | May be used in sections : defaults | frontend | listen | backend |
| 2157 | yes | no | yes | yes |
| 2158 | Arguments : none |
| 2159 | |
| 2160 | When there is a firewall or any session-aware component between a client and |
| 2161 | a server, and when the protocol involves very long sessions with long idle |
| 2162 | periods (eg: remote desktops), there is a risk that one of the intermediate |
| 2163 | components decides to expire a session which has remained idle for too long. |
| 2164 | |
| 2165 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 2166 | to the other end of the connection, leaving it active. The delay between |
| 2167 | keep-alive probes is controlled by the system only and depends both on the |
| 2168 | operating system and its tuning parameters. |
| 2169 | |
| 2170 | It is important to understand that keep-alive packets are neither emitted nor |
| 2171 | received at the application level. It is only the network stacks which sees |
| 2172 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 2173 | to maintain its connection alive, those keep-alive packets will not be |
| 2174 | forwarded to the other side of the proxy. |
| 2175 | |
| 2176 | Please note that this has nothing to do with HTTP keep-alive. |
| 2177 | |
| 2178 | Using option "srvtcpka" enables the emission of TCP keep-alive probes on the |
| 2179 | server side of a connection, which should help when session expirations are |
| 2180 | noticed between HAProxy and a server. |
| 2181 | |
| 2182 | If this option has been enabled in a "defaults" section, it can be disabled |
| 2183 | in a specific instance by prepending the "no" keyword before it. |
| 2184 | |
| 2185 | See also : "option clitcpka", "option tcpka" |
| 2186 | |
| 2187 | |
Willy Tarreau | a453bdd | 2008-01-08 19:50:52 +0100 | [diff] [blame] | 2188 | option ssl-hello-chk |
| 2189 | Use SSLv3 client hello health checks for server testing |
| 2190 | May be used in sections : defaults | frontend | listen | backend |
| 2191 | yes | no | yes | yes |
| 2192 | Arguments : none |
| 2193 | |
| 2194 | When some SSL-based protocols are relayed in TCP mode through HAProxy, it is |
| 2195 | possible to test that the server correctly talks SSL instead of just testing |
| 2196 | that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure |
| 2197 | SSLv3 client hello messages are sent once the connection is established to |
| 2198 | the server, and the response is analyzed to find an SSL server hello message. |
| 2199 | The server is considered valid only when the response contains this server |
| 2200 | hello message. |
| 2201 | |
| 2202 | All servers tested till there correctly reply to SSLv3 client hello messages, |
| 2203 | and most servers tested do not even log the requests containing only hello |
| 2204 | messages, which is appreciable. |
| 2205 | |
| 2206 | See also: "option httpchk" |
| 2207 | |
| 2208 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 2209 | option tcpka |
| 2210 | Enable or disable the sending of TCP keepalive packets on both sides |
| 2211 | May be used in sections : defaults | frontend | listen | backend |
| 2212 | yes | yes | yes | yes |
| 2213 | Arguments : none |
| 2214 | |
| 2215 | When there is a firewall or any session-aware component between a client and |
| 2216 | a server, and when the protocol involves very long sessions with long idle |
| 2217 | periods (eg: remote desktops), there is a risk that one of the intermediate |
| 2218 | components decides to expire a session which has remained idle for too long. |
| 2219 | |
| 2220 | Enabling socket-level TCP keep-alives makes the system regularly send packets |
| 2221 | to the other end of the connection, leaving it active. The delay between |
| 2222 | keep-alive probes is controlled by the system only and depends both on the |
| 2223 | operating system and its tuning parameters. |
| 2224 | |
| 2225 | It is important to understand that keep-alive packets are neither emitted nor |
| 2226 | received at the application level. It is only the network stacks which sees |
| 2227 | them. For this reason, even if one side of the proxy already uses keep-alives |
| 2228 | to maintain its connection alive, those keep-alive packets will not be |
| 2229 | forwarded to the other side of the proxy. |
| 2230 | |
| 2231 | Please note that this has nothing to do with HTTP keep-alive. |
| 2232 | |
| 2233 | Using option "tcpka" enables the emission of TCP keep-alive probes on both |
| 2234 | the client and server sides of a connection. Note that this is meaningful |
| 2235 | only in "defaults" or "listen" sections. If this option is used in a |
| 2236 | frontend, only the client side will get keep-alives, and if this option is |
| 2237 | used in a backend, only the server side will get keep-alives. For this |
| 2238 | reason, it is strongly recommended to explicitly use "option clitcpka" and |
| 2239 | "option srvtcpka" when the configuration is split between frontends and |
| 2240 | backends. |
| 2241 | |
| 2242 | See also : "option clitcpka", "option srvtcpka" |
| 2243 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 2244 | |
| 2245 | option tcplog |
| 2246 | Enable advanced logging of TCP connections with session state and timers |
| 2247 | May be used in sections : defaults | frontend | listen | backend |
| 2248 | yes | yes | yes | yes |
| 2249 | Arguments : none |
| 2250 | |
| 2251 | By default, the log output format is very poor, as it only contains the |
| 2252 | source and destination addresses, and the instance name. By specifying |
| 2253 | "option tcplog", each log line turns into a much richer format including, but |
| 2254 | not limited to, the connection timers, the session status, the connections |
| 2255 | numbers, the frontend, backend and server name, and of course the source |
| 2256 | address and ports. This option is useful for pure TCP proxies in order to |
| 2257 | find which of the client or server disconnects or times out. For normal HTTP |
| 2258 | proxies, it's better to use "option httplog" which is even more complete. |
| 2259 | |
| 2260 | This option may be set either in the frontend or the backend. |
| 2261 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2262 | See also : "option httplog", and section 2.6 about logging. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 2263 | |
| 2264 | |
| 2265 | option tcpsplice [ experimental ] |
| 2266 | Enable linux kernel-based acceleration of data relaying |
| 2267 | May be used in sections : defaults | frontend | listen | backend |
| 2268 | yes | yes | yes | yes |
| 2269 | Arguments : none |
| 2270 | |
| 2271 | This option is only available when HAProxy has been built for use on Linux |
| 2272 | with USE_TCPSPLICE=1. This option requires a kernel patch which is available |
| 2273 | on http://www.linux-l7sw.org/. |
| 2274 | |
| 2275 | When "option tcpsplice" is set, as soon as the server's response headers have |
| 2276 | been transferred, the session handling is transferred to the kernel which |
| 2277 | will forward all subsequent data from the server to the client untill the |
| 2278 | session closes. This leads to much faster data transfers between client and |
| 2279 | server since the data is not copied twice between kernel and user space, but |
| 2280 | there are some limitations such as the lack of information about the number |
| 2281 | of bytes transferred and the total transfer time. |
| 2282 | |
| 2283 | This is an experimental feature. It happens to reliably work but issues |
| 2284 | caused by corner cases are to be expected. |
| 2285 | |
| 2286 | Note that this option requires that the process permanently runs with |
| 2287 | CAP_NETADMIN privileges, which most often translates into running as root. |
| 2288 | |
| 2289 | |
| 2290 | option transparent |
| 2291 | no option transparent |
| 2292 | Enable client-side transparent proxying |
| 2293 | May be used in sections : defaults | frontend | listen | backend |
| 2294 | yes | yes | yes | no |
| 2295 | Arguments : none |
| 2296 | |
| 2297 | This option was introduced in order to provide layer 7 persistence to layer 3 |
| 2298 | load balancers. The idea is to use the OS's ability to redirect an incoming |
| 2299 | connection for a remote address to a local process (here HAProxy), and let |
| 2300 | this process know what address was initially requested. When this option is |
| 2301 | used, sessions without cookies will be forwarded to the original destination |
| 2302 | IP address of the incoming request (which should match that of another |
| 2303 | equipment), while requests with cookies will still be forwarded to the |
| 2304 | appropriate server. |
| 2305 | |
| 2306 | Note that contrary to a common belief, this option does NOT make HAProxy |
| 2307 | present the client's IP to the server when establishing the connection. |
| 2308 | |
| 2309 | Use of this option is really discouraged, and since no really valid use of it |
| 2310 | has been reported for years, it will probably be removed in future versions. |
| 2311 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2312 | See also: the "usersrc" argument of the "source" keyword, and the |
| 2313 | "transparent" option of the "bind" keyword. |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 2314 | |
Willy Tarreau | bf1f816 | 2007-12-28 17:42:56 +0100 | [diff] [blame] | 2315 | |
Willy Tarreau | b463dfb | 2008-06-07 23:08:56 +0200 | [diff] [blame] | 2316 | redirect {location | prefix} <to> [code <code>] {if | unless} <condition> |
| 2317 | Return an HTTP redirection if/unless a condition is matched |
| 2318 | May be used in sections : defaults | frontend | listen | backend |
| 2319 | no | yes | yes | yes |
| 2320 | |
| 2321 | If/unless the condition is matched, the HTTP request will lead to a redirect |
| 2322 | response. There are currently two types of redirections : "location" and |
| 2323 | "prefix". With "location", the exact value in <to> is placed into the HTTP |
| 2324 | "Location" header. With "prefix", the "Location" header is built from the |
| 2325 | concatenation of <to> and the URI. It is particularly suited for global site |
| 2326 | redirections. |
| 2327 | |
| 2328 | The code is optional. It indicates in <code> which type of HTTP redirection |
| 2329 | is desired. Only codes 301, 302 and 303 are supported. 302 is used if no code |
| 2330 | is specified. |
| 2331 | |
| 2332 | Example: move the login URL only to HTTPS. |
| 2333 | acl clear dst_port 80 |
| 2334 | acl secure dst_port 8080 |
| 2335 | acl login_page url_beg /login |
| 2336 | redirect prefix https://mysite.com if login_page !secure |
| 2337 | redirect location http://mysite.com/ if !login_page secure |
| 2338 | |
| 2339 | See section 2.3 about ACL usage. |
| 2340 | |
| 2341 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 2342 | redisp (deprecated) |
| 2343 | redispatch (deprecated) |
| 2344 | Enable or disable session redistribution in case of connection failure |
| 2345 | May be used in sections: defaults | frontend | listen | backend |
| 2346 | yes | no | yes | yes |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2347 | Arguments : none |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 2348 | |
| 2349 | In HTTP mode, if a server designated by a cookie is down, clients may |
| 2350 | definitely stick to it because they cannot flush the cookie, so they will not |
| 2351 | be able to access the service anymore. |
| 2352 | |
| 2353 | Specifying "redispatch" will allow the proxy to break their persistence and |
| 2354 | redistribute them to a working server. |
| 2355 | |
| 2356 | It also allows to retry last connection to another server in case of multiple |
| 2357 | connection failures. Of course, it requires having "retries" set to a nonzero |
| 2358 | value. |
| 2359 | |
| 2360 | This form is deprecated, do not use it in any new configuration, use the new |
| 2361 | "option redispatch" instead. |
| 2362 | |
| 2363 | See also : "option redispatch" |
| 2364 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2365 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2366 | reqadd <string> |
| 2367 | Add a header at the end of the HTTP request |
| 2368 | May be used in sections : defaults | frontend | listen | backend |
| 2369 | no | yes | yes | yes |
| 2370 | Arguments : |
| 2371 | <string> is the complete line to be added. Any space or known delimiter |
| 2372 | must be escaped using a backslash ('\'). Please refer to section |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2373 | 2.5 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2374 | |
| 2375 | A new line consisting in <string> followed by a line feed will be added after |
| 2376 | the last header of an HTTP request. |
| 2377 | |
| 2378 | Header transformations only apply to traffic which passes through HAProxy, |
| 2379 | and not to traffic generated by HAProxy, such as health-checks or error |
| 2380 | responses. |
| 2381 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2382 | See also: "rspadd" and section 2.5 about HTTP header manipulation |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2383 | |
| 2384 | |
| 2385 | reqallow <search> |
| 2386 | reqiallow <search> (ignore case) |
| 2387 | Definitely allow an HTTP request if a line matches a regular expression |
| 2388 | May be used in sections : defaults | frontend | listen | backend |
| 2389 | no | yes | yes | yes |
| 2390 | Arguments : |
| 2391 | <search> is the regular expression applied to HTTP headers and to the |
| 2392 | request line. This is an extended regular expression. Parenthesis |
| 2393 | grouping is supported and no preliminary backslash is required. |
| 2394 | Any space or known delimiter must be escaped using a backslash |
| 2395 | ('\'). The pattern applies to a full line at a time. The |
| 2396 | "reqallow" keyword strictly matches case while "reqiallow" |
| 2397 | ignores case. |
| 2398 | |
| 2399 | A request containing any line which matches extended regular expression |
| 2400 | <search> will mark the request as allowed, even if any later test would |
| 2401 | result in a deny. The test applies both to the request line and to request |
| 2402 | headers. Keep in mind that URLs in request line are case-sensitive while |
| 2403 | header names are not. |
| 2404 | |
| 2405 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 2406 | Reqdeny, reqallow and reqpass should be avoided in new designs. |
| 2407 | |
| 2408 | Example : |
| 2409 | # allow www.* but refuse *.local |
| 2410 | reqiallow ^Host:\ www\. |
| 2411 | reqideny ^Host:\ .*\.local |
| 2412 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2413 | See also: "reqdeny", "acl", "block" and section 2.5 about HTTP header |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2414 | manipulation |
| 2415 | |
| 2416 | |
| 2417 | reqdel <search> |
| 2418 | reqidel <search> (ignore case) |
| 2419 | Delete all headers matching a regular expression in an HTTP request |
| 2420 | May be used in sections : defaults | frontend | listen | backend |
| 2421 | no | yes | yes | yes |
| 2422 | Arguments : |
| 2423 | <search> is the regular expression applied to HTTP headers and to the |
| 2424 | request line. This is an extended regular expression. Parenthesis |
| 2425 | grouping is supported and no preliminary backslash is required. |
| 2426 | Any space or known delimiter must be escaped using a backslash |
| 2427 | ('\'). The pattern applies to a full line at a time. The "reqdel" |
| 2428 | keyword strictly matches case while "reqidel" ignores case. |
| 2429 | |
| 2430 | Any header line matching extended regular expression <search> in the request |
| 2431 | will be completely deleted. Most common use of this is to remove unwanted |
| 2432 | and/or dangerous headers or cookies from a request before passing it to the |
| 2433 | next servers. |
| 2434 | |
| 2435 | Header transformations only apply to traffic which passes through HAProxy, |
| 2436 | and not to traffic generated by HAProxy, such as health-checks or error |
| 2437 | responses. Keep in mind that header names are not case-sensitive. |
| 2438 | |
| 2439 | Example : |
| 2440 | # remove X-Forwarded-For header and SERVER cookie |
| 2441 | reqidel ^X-Forwarded-For:.* |
| 2442 | reqidel ^Cookie:.*SERVER= |
| 2443 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2444 | See also: "reqadd", "reqrep", "rspdel" and section 2.5 about HTTP header |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2445 | manipulation |
| 2446 | |
| 2447 | |
| 2448 | reqdeny <search> |
| 2449 | reqideny <search> (ignore case) |
| 2450 | Deny an HTTP request if a line matches a regular expression |
| 2451 | May be used in sections : defaults | frontend | listen | backend |
| 2452 | no | yes | yes | yes |
| 2453 | Arguments : |
| 2454 | <search> is the regular expression applied to HTTP headers and to the |
| 2455 | request line. This is an extended regular expression. Parenthesis |
| 2456 | grouping is supported and no preliminary backslash is required. |
| 2457 | Any space or known delimiter must be escaped using a backslash |
| 2458 | ('\'). The pattern applies to a full line at a time. The |
| 2459 | "reqdeny" keyword strictly matches case while "reqideny" ignores |
| 2460 | case. |
| 2461 | |
| 2462 | A request containing any line which matches extended regular expression |
| 2463 | <search> will mark the request as denied, even if any later test would |
| 2464 | result in an allow. The test applies both to the request line and to request |
| 2465 | headers. Keep in mind that URLs in request line are case-sensitive while |
| 2466 | header names are not. |
| 2467 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2468 | A denied request will generate an "HTTP 403 forbidden" response once the |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2469 | complete request has been parsed. This is consistent with what is practiced |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2470 | using ACLs. |
| 2471 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2472 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 2473 | Reqdeny, reqallow and reqpass should be avoided in new designs. |
| 2474 | |
| 2475 | Example : |
| 2476 | # refuse *.local, then allow www.* |
| 2477 | reqideny ^Host:\ .*\.local |
| 2478 | reqiallow ^Host:\ www\. |
| 2479 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2480 | See also: "reqallow", "rspdeny", "acl", "block" and section 2.5 about HTTP |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2481 | header manipulation |
| 2482 | |
| 2483 | |
| 2484 | reqpass <search> |
| 2485 | reqipass <search> (ignore case) |
| 2486 | Ignore any HTTP request line matching a regular expression in next rules |
| 2487 | May be used in sections : defaults | frontend | listen | backend |
| 2488 | no | yes | yes | yes |
| 2489 | Arguments : |
| 2490 | <search> is the regular expression applied to HTTP headers and to the |
| 2491 | request line. This is an extended regular expression. Parenthesis |
| 2492 | grouping is supported and no preliminary backslash is required. |
| 2493 | Any space or known delimiter must be escaped using a backslash |
| 2494 | ('\'). The pattern applies to a full line at a time. The |
| 2495 | "reqpass" keyword strictly matches case while "reqipass" ignores |
| 2496 | case. |
| 2497 | |
| 2498 | A request containing any line which matches extended regular expression |
| 2499 | <search> will skip next rules, without assigning any deny or allow verdict. |
| 2500 | The test applies both to the request line and to request headers. Keep in |
| 2501 | mind that URLs in request line are case-sensitive while header names are not. |
| 2502 | |
| 2503 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 2504 | Reqdeny, reqallow and reqpass should be avoided in new designs. |
| 2505 | |
| 2506 | Example : |
| 2507 | # refuse *.local, then allow www.*, but ignore "www.private.local" |
| 2508 | reqipass ^Host:\ www.private\.local |
| 2509 | reqideny ^Host:\ .*\.local |
| 2510 | reqiallow ^Host:\ www\. |
| 2511 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2512 | See also: "reqallow", "reqdeny", "acl", "block" and section 2.5 about HTTP |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2513 | header manipulation |
| 2514 | |
| 2515 | |
| 2516 | reqrep <search> <string> |
| 2517 | reqirep <search> <string> (ignore case) |
| 2518 | Replace a regular expression with a string in an HTTP request line |
| 2519 | May be used in sections : defaults | frontend | listen | backend |
| 2520 | no | yes | yes | yes |
| 2521 | Arguments : |
| 2522 | <search> is the regular expression applied to HTTP headers and to the |
| 2523 | request line. This is an extended regular expression. Parenthesis |
| 2524 | grouping is supported and no preliminary backslash is required. |
| 2525 | Any space or known delimiter must be escaped using a backslash |
| 2526 | ('\'). The pattern applies to a full line at a time. The "reqrep" |
| 2527 | keyword strictly matches case while "reqirep" ignores case. |
| 2528 | |
| 2529 | <string> is the complete line to be added. Any space or known delimiter |
| 2530 | must be escaped using a backslash ('\'). References to matched |
| 2531 | pattern groups are possible using the common \N form, with N |
| 2532 | being a single digit between 0 and 9. Please refer to section |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2533 | 2.5 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2534 | |
| 2535 | Any line matching extended regular expression <search> in the request (both |
| 2536 | the request line and header lines) will be completely replaced with <string>. |
| 2537 | Most common use of this is to rewrite URLs or domain names in "Host" headers. |
| 2538 | |
| 2539 | Header transformations only apply to traffic which passes through HAProxy, |
| 2540 | and not to traffic generated by HAProxy, such as health-checks or error |
| 2541 | responses. Note that for increased readability, it is suggested to add enough |
| 2542 | spaces between the request and the response. Keep in mind that URLs in |
| 2543 | request line are case-sensitive while header names are not. |
| 2544 | |
| 2545 | Example : |
| 2546 | # replace "/static/" with "/" at the beginning of any request path. |
| 2547 | reqrep ^([^\ ]*)\ /static/(.*) \1\ /\2 |
| 2548 | # replace "www.mydomain.com" with "www" in the host name. |
| 2549 | reqirep ^Host:\ www.mydomain.com Host:\ www |
| 2550 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2551 | See also: "reqadd", "reqdel", "rsprep" and section 2.5 about HTTP header |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2552 | manipulation |
| 2553 | |
| 2554 | |
| 2555 | reqtarpit <search> |
| 2556 | reqitarpit <search> (ignore case) |
| 2557 | Tarpit an HTTP request containing a line matching a regular expression |
| 2558 | May be used in sections : defaults | frontend | listen | backend |
| 2559 | no | yes | yes | yes |
| 2560 | Arguments : |
| 2561 | <search> is the regular expression applied to HTTP headers and to the |
| 2562 | request line. This is an extended regular expression. Parenthesis |
| 2563 | grouping is supported and no preliminary backslash is required. |
| 2564 | Any space or known delimiter must be escaped using a backslash |
| 2565 | ('\'). The pattern applies to a full line at a time. The |
| 2566 | "reqtarpit" keyword strictly matches case while "reqitarpit" |
| 2567 | ignores case. |
| 2568 | |
| 2569 | A request containing any line which matches extended regular expression |
| 2570 | <search> will be tarpitted, which means that it will connect to nowhere, will |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2571 | be kept open for a pre-defined time, then will return an HTTP error 500 so |
| 2572 | that the attacker does not suspect it has been tarpitted. The status 500 will |
| 2573 | be reported in the logs, but the completion flags will indicate "PT". The |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2574 | delay is defined by "timeout tarpit", or "timeout connect" if the former is |
| 2575 | not set. |
| 2576 | |
| 2577 | The goal of the tarpit is to slow down robots attacking servers with |
| 2578 | identifiable requests. Many robots limit their outgoing number of connections |
| 2579 | and stay connected waiting for a reply which can take several minutes to |
| 2580 | come. Depending on the environment and attack, it may be particularly |
| 2581 | efficient at reducing the load on the network and firewalls. |
| 2582 | |
| 2583 | Example : |
| 2584 | # ignore user-agents reporting any flavour of "Mozilla" or "MSIE", but |
| 2585 | # block all others. |
| 2586 | reqipass ^User-Agent:\.*(Mozilla|MSIE) |
| 2587 | reqitarpit ^User-Agent: |
| 2588 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2589 | See also: "reqallow", "reqdeny", "reqpass", and section 2.5 about HTTP header |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2590 | manipulation |
| 2591 | |
| 2592 | |
Willy Tarreau | e5c5ce9 | 2008-06-20 17:27:19 +0200 | [diff] [blame] | 2593 | retries <value> |
| 2594 | Set the number of retries to perform on a server after a connection failure |
| 2595 | May be used in sections: defaults | frontend | listen | backend |
| 2596 | yes | no | yes | yes |
| 2597 | Arguments : |
| 2598 | <value> is the number of times a connection attempt should be retried on |
| 2599 | a server when a connection either is refused or times out. The |
| 2600 | default value is 3. |
| 2601 | |
| 2602 | It is important to understand that this value applies to the number of |
| 2603 | connection attempts, not full requests. When a connection has effectively |
| 2604 | been established to a server, there will be no more retry. |
| 2605 | |
| 2606 | In order to avoid immediate reconnections to a server which is restarting, |
| 2607 | a turn-around timer of 1 second is applied before a retry occurs. |
| 2608 | |
| 2609 | When "option redispatch" is set, the last retry may be performed on another |
| 2610 | server even if a cookie references a different server. |
| 2611 | |
| 2612 | See also : "option redispatch" |
| 2613 | |
| 2614 | |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2615 | rspadd <string> |
| 2616 | Add a header at the end of the HTTP response |
| 2617 | May be used in sections : defaults | frontend | listen | backend |
| 2618 | no | yes | yes | yes |
| 2619 | Arguments : |
| 2620 | <string> is the complete line to be added. Any space or known delimiter |
| 2621 | must be escaped using a backslash ('\'). Please refer to section |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2622 | 2.5 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2623 | |
| 2624 | A new line consisting in <string> followed by a line feed will be added after |
| 2625 | the last header of an HTTP response. |
| 2626 | |
| 2627 | Header transformations only apply to traffic which passes through HAProxy, |
| 2628 | and not to traffic generated by HAProxy, such as health-checks or error |
| 2629 | responses. |
| 2630 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2631 | See also: "reqadd" and section 2.5 about HTTP header manipulation |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2632 | |
| 2633 | |
| 2634 | rspdel <search> |
| 2635 | rspidel <search> (ignore case) |
| 2636 | Delete all headers matching a regular expression in an HTTP response |
| 2637 | May be used in sections : defaults | frontend | listen | backend |
| 2638 | no | yes | yes | yes |
| 2639 | Arguments : |
| 2640 | <search> is the regular expression applied to HTTP headers and to the |
| 2641 | response line. This is an extended regular expression, so |
| 2642 | parenthesis grouping is supported and no preliminary backslash |
| 2643 | is required. Any space or known delimiter must be escaped using |
| 2644 | a backslash ('\'). The pattern applies to a full line at a time. |
| 2645 | The "rspdel" keyword strictly matches case while "rspidel" |
| 2646 | ignores case. |
| 2647 | |
| 2648 | Any header line matching extended regular expression <search> in the response |
| 2649 | will be completely deleted. Most common use of this is to remove unwanted |
| 2650 | and/or sensible headers or cookies from a response before passing it to the |
| 2651 | client. |
| 2652 | |
| 2653 | Header transformations only apply to traffic which passes through HAProxy, |
| 2654 | and not to traffic generated by HAProxy, such as health-checks or error |
| 2655 | responses. Keep in mind that header names are not case-sensitive. |
| 2656 | |
| 2657 | Example : |
| 2658 | # remove the Server header from responses |
| 2659 | reqidel ^Server:.* |
| 2660 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2661 | See also: "rspadd", "rsprep", "reqdel" and section 2.5 about HTTP header |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2662 | manipulation |
| 2663 | |
| 2664 | |
| 2665 | rspdeny <search> |
| 2666 | rspideny <search> (ignore case) |
| 2667 | Block an HTTP response if a line matches a regular expression |
| 2668 | May be used in sections : defaults | frontend | listen | backend |
| 2669 | no | yes | yes | yes |
| 2670 | Arguments : |
| 2671 | <search> is the regular expression applied to HTTP headers and to the |
| 2672 | response line. This is an extended regular expression, so |
| 2673 | parenthesis grouping is supported and no preliminary backslash |
| 2674 | is required. Any space or known delimiter must be escaped using |
| 2675 | a backslash ('\'). The pattern applies to a full line at a time. |
| 2676 | The "rspdeny" keyword strictly matches case while "rspideny" |
| 2677 | ignores case. |
| 2678 | |
| 2679 | A response containing any line which matches extended regular expression |
| 2680 | <search> will mark the request as denied. The test applies both to the |
| 2681 | response line and to response headers. Keep in mind that header names are not |
| 2682 | case-sensitive. |
| 2683 | |
| 2684 | Main use of this keyword is to prevent sensitive information leak and to |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2685 | block the response before it reaches the client. If a response is denied, it |
| 2686 | will be replaced with an HTTP 502 error so that the client never retrieves |
| 2687 | any sensitive data. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2688 | |
| 2689 | It is easier, faster and more powerful to use ACLs to write access policies. |
| 2690 | Rspdeny should be avoided in new designs. |
| 2691 | |
| 2692 | Example : |
| 2693 | # Ensure that no content type matching ms-word will leak |
| 2694 | rspideny ^Content-type:\.*/ms-word |
| 2695 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2696 | See also: "reqdeny", "acl", "block" and section 2.5 about HTTP header |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2697 | manipulation |
| 2698 | |
| 2699 | |
| 2700 | rsprep <search> <string> |
| 2701 | rspirep <search> <string> (ignore case) |
| 2702 | Replace a regular expression with a string in an HTTP response line |
| 2703 | May be used in sections : defaults | frontend | listen | backend |
| 2704 | no | yes | yes | yes |
| 2705 | Arguments : |
| 2706 | <search> is the regular expression applied to HTTP headers and to the |
| 2707 | response line. This is an extended regular expression, so |
| 2708 | parenthesis grouping is supported and no preliminary backslash |
| 2709 | is required. Any space or known delimiter must be escaped using |
| 2710 | a backslash ('\'). The pattern applies to a full line at a time. |
| 2711 | The "rsprep" keyword strictly matches case while "rspirep" |
| 2712 | ignores case. |
| 2713 | |
| 2714 | <string> is the complete line to be added. Any space or known delimiter |
| 2715 | must be escaped using a backslash ('\'). References to matched |
| 2716 | pattern groups are possible using the common \N form, with N |
| 2717 | being a single digit between 0 and 9. Please refer to section |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2718 | 2.5 about HTTP header manipulation for more information. |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2719 | |
| 2720 | Any line matching extended regular expression <search> in the response (both |
| 2721 | the response line and header lines) will be completely replaced with |
| 2722 | <string>. Most common use of this is to rewrite Location headers. |
| 2723 | |
| 2724 | Header transformations only apply to traffic which passes through HAProxy, |
| 2725 | and not to traffic generated by HAProxy, such as health-checks or error |
| 2726 | responses. Note that for increased readability, it is suggested to add enough |
| 2727 | spaces between the request and the response. Keep in mind that header names |
| 2728 | are not case-sensitive. |
| 2729 | |
| 2730 | Example : |
| 2731 | # replace "Location: 127.0.0.1:8080" with "Location: www.mydomain.com" |
| 2732 | rspirep ^Location:\ 127.0.0.1:8080 Location:\ www.mydomain.com |
| 2733 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 2734 | See also: "rspadd", "rspdel", "reqrep" and section 2.5 about HTTP header |
Willy Tarreau | 303c035 | 2008-01-17 19:01:39 +0100 | [diff] [blame] | 2735 | manipulation |
| 2736 | |
| 2737 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2738 | server <name> <address>[:port] [param*] |
| 2739 | Declare a server in a backend |
| 2740 | May be used in sections : defaults | frontend | listen | backend |
| 2741 | no | no | yes | yes |
| 2742 | Arguments : |
| 2743 | <name> is the internal name assigned to this server. This name will |
| 2744 | appear in logs and alerts. |
| 2745 | |
| 2746 | <address> is the IPv4 address of the server. Alternatively, a resolvable |
| 2747 | hostname is supported, but this name will be resolved during |
| 2748 | start-up. |
| 2749 | |
| 2750 | <ports> is an optional port specification. If set, all connections will |
| 2751 | be sent to this port. If unset, the same port the client |
| 2752 | connected to will be used. The port may also be prefixed by a "+" |
| 2753 | or a "-". In this case, the server's port will be determined by |
| 2754 | adding this value to the client's port. |
| 2755 | |
| 2756 | <param*> is a list of parameters for this server. The "server" keywords |
| 2757 | accepts an important number of options and has a complete section |
| 2758 | dedicated to it. Please refer to section 2.4 for more details. |
| 2759 | |
| 2760 | Examples : |
| 2761 | server first 10.1.1.1:1080 cookie first check inter 1000 |
| 2762 | server second 10.1.1.2:1080 cookie second check inter 1000 |
| 2763 | |
| 2764 | See also : section 2.4 about server options |
| 2765 | |
| 2766 | |
| 2767 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
| 2768 | Set the source address for outgoing connections |
| 2769 | May be used in sections : defaults | frontend | listen | backend |
| 2770 | yes | no | yes | yes |
| 2771 | Arguments : |
| 2772 | <addr> is the IPv4 address HAProxy will bind to before connecting to a |
| 2773 | server. This address is also used as a source for health checks. |
| 2774 | The default value of 0.0.0.0 means that the system will select |
| 2775 | the most appropriate address to reach its destination. |
| 2776 | |
| 2777 | <port> is an optional port. It is normally not needed but may be useful |
| 2778 | in some very specific contexts. The default value of zero means |
| 2779 | the system will select a free port. |
| 2780 | |
| 2781 | <addr2> is the IP address to present to the server when connections are |
| 2782 | forwarded in full transparent proxy mode. This is currently only |
| 2783 | supported on some patched Linux kernels. When this address is |
| 2784 | specified, clients connecting to the server will be presented |
| 2785 | with this address, while health checks will still use the address |
| 2786 | <addr>. |
| 2787 | |
| 2788 | <port2> is the optional port to present to the server when connections |
| 2789 | are forwarded in full transparent proxy mode (see <addr2> above). |
| 2790 | The default value of zero means the system will select a free |
| 2791 | port. |
| 2792 | |
| 2793 | The "source" keyword is useful in complex environments where a specific |
| 2794 | address only is allowed to connect to the servers. It may be needed when a |
| 2795 | private address must be used through a public gateway for instance, and it is |
| 2796 | known that the system cannot determine the adequate source address by itself. |
| 2797 | |
| 2798 | An extension which is available on certain patched Linux kernels may be used |
| 2799 | through the "usesrc" optional keyword. It makes it possible to connect to the |
| 2800 | servers with an IP address which does not belong to the system itself. This |
| 2801 | is called "full transparent proxy mode". For this to work, the destination |
| 2802 | servers have to route their traffic back to this address through the machine |
| 2803 | running HAProxy, and IP forwarding must generally be enabled on this machine. |
| 2804 | |
| 2805 | In this "full transparent proxy" mode, it is possible to force a specific IP |
| 2806 | address to be presented to the servers. This is not much used in fact. A more |
| 2807 | common use is to tell HAProxy to present the client's IP address. For this, |
| 2808 | there are two methods : |
| 2809 | |
| 2810 | - present the client's IP and port addresses. This is the most transparent |
| 2811 | mode, but it can cause problems when IP connection tracking is enabled on |
| 2812 | the machine, because a same connection may be seen twice with different |
| 2813 | states. However, this solution presents the huge advantage of not |
| 2814 | limiting the system to the 64k outgoing address+port couples, because all |
| 2815 | of the client ranges may be used. |
| 2816 | |
| 2817 | - present only the client's IP address and select a spare port. This |
| 2818 | solution is still quite elegant but slightly less transparent (downstream |
| 2819 | firewalls logs will not match upstream's). It also presents the downside |
| 2820 | of limiting the number of concurrent connections to the usual 64k ports. |
| 2821 | However, since the upstream and downstream ports are different, local IP |
| 2822 | connection tracking on the machine will not be upset by the reuse of the |
| 2823 | same session. |
| 2824 | |
| 2825 | Note that depending on the transparent proxy technology used, it may be |
| 2826 | required to force the source address. In fact, cttproxy version 2 requires an |
| 2827 | IP address in <addr> above, and does not support setting of "0.0.0.0" as the |
| 2828 | IP address because it creates NAT entries which much match the exact outgoing |
| 2829 | address. Tproxy version 4 and some other kernel patches which work in pure |
| 2830 | forwarding mode generally will not have this limitation. |
| 2831 | |
| 2832 | This option sets the default source for all servers in the backend. It may |
| 2833 | also be specified in a "defaults" section. Finer source address specification |
| 2834 | is possible at the server level using the "source" server option. Refer to |
| 2835 | section 2.4 for more information. |
| 2836 | |
| 2837 | Examples : |
| 2838 | backend private |
| 2839 | # Connect to the servers using our 192.168.1.200 source address |
| 2840 | source 192.168.1.200 |
| 2841 | |
| 2842 | backend transparent_ssl1 |
| 2843 | # Connect to the SSL farm from the client's source address |
| 2844 | source 192.168.1.200 usesrc clientip |
| 2845 | |
| 2846 | backend transparent_ssl2 |
| 2847 | # Connect to the SSL farm from the client's source address and port |
| 2848 | # not recommended if IP conntrack is present on the local machine. |
| 2849 | source 192.168.1.200 usesrc client |
| 2850 | |
| 2851 | backend transparent_ssl3 |
| 2852 | # Connect to the SSL farm from the client's source address. It |
| 2853 | # is more conntrack-friendly. |
| 2854 | source 192.168.1.200 usesrc clientip |
| 2855 | |
| 2856 | backend transparent_smtp |
| 2857 | # Connect to the SMTP farm from the client's source address/port |
| 2858 | # with Tproxy version 4. |
| 2859 | source 0.0.0.0 usesrc clientip |
| 2860 | |
| 2861 | See also : the "source" server option in section 2.4, the Tproxy patches for |
| 2862 | the Linux kernel on www.balabit.com, the "bind" keyword. |
| 2863 | |
Krzysztof Piotr Oledzki | 25b501a | 2008-01-06 16:36:16 +0100 | [diff] [blame] | 2864 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 2865 | srvtimeout <timeout> (deprecated) |
| 2866 | Set the maximum inactivity time on the server side. |
| 2867 | May be used in sections : defaults | frontend | listen | backend |
| 2868 | yes | no | yes | yes |
| 2869 | Arguments : |
| 2870 | <timeout> is the timeout value specified in milliseconds by default, but |
| 2871 | can be in any other unit if the number is suffixed by the unit, |
| 2872 | as explained at the top of this document. |
| 2873 | |
| 2874 | The inactivity timeout applies when the server is expected to acknowledge or |
| 2875 | send data. In HTTP mode, this timeout is particularly important to consider |
| 2876 | during the first phase of the server's response, when it has to send the |
| 2877 | headers, as it directly represents the server's processing time for the |
| 2878 | request. To find out what value to put there, it's often good to start with |
| 2879 | what would be considered as unacceptable response times, then check the logs |
| 2880 | to observe the response time distribution, and adjust the value accordingly. |
| 2881 | |
| 2882 | The value is specified in milliseconds by default, but can be in any other |
| 2883 | unit if the number is suffixed by the unit, as specified at the top of this |
| 2884 | document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly |
| 2885 | recommended that the client timeout remains equal to the server timeout in |
| 2886 | order to avoid complex situations to debug. Whatever the expected server |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 2887 | response times, it is a good practice to cover at least one or several TCP |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 2888 | packet losses by specifying timeouts that are slightly above multiples of 3 |
| 2889 | seconds (eg: 4 or 5 seconds minimum). |
| 2890 | |
| 2891 | This parameter is specific to backends, but can be specified once for all in |
| 2892 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 2893 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 2894 | is not recommended. Such a usage is accepted and works but reports a warning |
| 2895 | during startup because it may results in accumulation of expired sessions in |
| 2896 | the system if the system's timeouts are not configured either. |
| 2897 | |
| 2898 | This parameter is provided for compatibility but is currently deprecated. |
| 2899 | Please use "timeout server" instead. |
| 2900 | |
| 2901 | See also : "timeout server", "timeout client" and "clitimeout". |
| 2902 | |
| 2903 | |
Willy Tarreau | eabeafa | 2008-01-16 16:17:06 +0100 | [diff] [blame] | 2904 | stats auth <user>:<passwd> |
| 2905 | Enable statistics with authentication and grant access to an account |
| 2906 | May be used in sections : defaults | frontend | listen | backend |
| 2907 | yes | no | yes | yes |
| 2908 | Arguments : |
| 2909 | <user> is a user name to grant access to |
| 2910 | |
| 2911 | <passwd> is the cleartext password associated to this user |
| 2912 | |
| 2913 | This statement enables statistics with default settings, and restricts access |
| 2914 | to declared users only. It may be repeated as many times as necessary to |
| 2915 | allow as many users as desired. When a user tries to access the statistics |
| 2916 | without a valid account, a "401 Forbidden" response will be returned so that |
| 2917 | the browser asks the user to provide a valid user and password. The real |
| 2918 | which will be returned to the browser is configurable using "stats realm". |
| 2919 | |
| 2920 | Since the authentication method is HTTP Basic Authentication, the passwords |
| 2921 | circulate in cleartext on the network. Thus, it was decided that the |
| 2922 | configuration file would also use cleartext passwords to remind the users |
| 2923 | that those ones should not be sensible and not shared with any other account. |
| 2924 | |
| 2925 | It is also possible to reduce the scope of the proxies which appear in the |
| 2926 | report using "stats scope". |
| 2927 | |
| 2928 | Though this statement alone is enough to enable statistics reporting, it is |
| 2929 | recommended to set all other settings in order to avoid relying on default |
| 2930 | unobvious parameters. |
| 2931 | |
| 2932 | Example : |
| 2933 | # public access (limited to this backend only) |
| 2934 | backend public_www |
| 2935 | server srv1 192.168.0.1:80 |
| 2936 | stats enable |
| 2937 | stats hide-version |
| 2938 | stats scope . |
| 2939 | stats uri /admin?stats |
| 2940 | stats realm Haproxy\ Statistics |
| 2941 | stats auth admin1:AdMiN123 |
| 2942 | stats auth admin2:AdMiN321 |
| 2943 | |
| 2944 | # internal monitoring access (unlimited) |
| 2945 | backend private_monitoring |
| 2946 | stats enable |
| 2947 | stats uri /admin?stats |
| 2948 | stats refresh 5s |
| 2949 | |
| 2950 | See also : "stats enable", "stats realm", "stats scope", "stats uri" |
| 2951 | |
| 2952 | |
| 2953 | stats enable |
| 2954 | Enable statistics reporting with default settings |
| 2955 | May be used in sections : defaults | frontend | listen | backend |
| 2956 | yes | no | yes | yes |
| 2957 | Arguments : none |
| 2958 | |
| 2959 | This statement enables statistics reporting with default settings defined |
| 2960 | at build time. Unless stated otherwise, these settings are used : |
| 2961 | - stats uri : /haproxy?stats |
| 2962 | - stats realm : "HAProxy Statistics" |
| 2963 | - stats auth : no authentication |
| 2964 | - stats scope : no restriction |
| 2965 | |
| 2966 | Though this statement alone is enough to enable statistics reporting, it is |
| 2967 | recommended to set all other settings in order to avoid relying on default |
| 2968 | unobvious parameters. |
| 2969 | |
| 2970 | Example : |
| 2971 | # public access (limited to this backend only) |
| 2972 | backend public_www |
| 2973 | server srv1 192.168.0.1:80 |
| 2974 | stats enable |
| 2975 | stats hide-version |
| 2976 | stats scope . |
| 2977 | stats uri /admin?stats |
| 2978 | stats realm Haproxy\ Statistics |
| 2979 | stats auth admin1:AdMiN123 |
| 2980 | stats auth admin2:AdMiN321 |
| 2981 | |
| 2982 | # internal monitoring access (unlimited) |
| 2983 | backend private_monitoring |
| 2984 | stats enable |
| 2985 | stats uri /admin?stats |
| 2986 | stats refresh 5s |
| 2987 | |
| 2988 | See also : "stats auth", "stats realm", "stats uri" |
| 2989 | |
| 2990 | |
| 2991 | stats realm <realm> |
| 2992 | Enable statistics and set authentication realm |
| 2993 | May be used in sections : defaults | frontend | listen | backend |
| 2994 | yes | no | yes | yes |
| 2995 | Arguments : |
| 2996 | <realm> is the name of the HTTP Basic Authentication realm reported to |
| 2997 | the browser. The browser uses it to display it in the pop-up |
| 2998 | inviting the user to enter a valid username and password. |
| 2999 | |
| 3000 | The realm is read as a single word, so any spaces in it should be escaped |
| 3001 | using a backslash ('\'). |
| 3002 | |
| 3003 | This statement is useful only in conjunction with "stats auth" since it is |
| 3004 | only related to authentication. |
| 3005 | |
| 3006 | Though this statement alone is enough to enable statistics reporting, it is |
| 3007 | recommended to set all other settings in order to avoid relying on default |
| 3008 | unobvious parameters. |
| 3009 | |
| 3010 | Example : |
| 3011 | # public access (limited to this backend only) |
| 3012 | backend public_www |
| 3013 | server srv1 192.168.0.1:80 |
| 3014 | stats enable |
| 3015 | stats hide-version |
| 3016 | stats scope . |
| 3017 | stats uri /admin?stats |
| 3018 | stats realm Haproxy\ Statistics |
| 3019 | stats auth admin1:AdMiN123 |
| 3020 | stats auth admin2:AdMiN321 |
| 3021 | |
| 3022 | # internal monitoring access (unlimited) |
| 3023 | backend private_monitoring |
| 3024 | stats enable |
| 3025 | stats uri /admin?stats |
| 3026 | stats refresh 5s |
| 3027 | |
| 3028 | See also : "stats auth", "stats enable", "stats uri" |
| 3029 | |
| 3030 | |
| 3031 | stats refresh <delay> |
| 3032 | Enable statistics with automatic refresh |
| 3033 | May be used in sections : defaults | frontend | listen | backend |
| 3034 | yes | no | yes | yes |
| 3035 | Arguments : |
| 3036 | <delay> is the suggested refresh delay, specified in seconds, which will |
| 3037 | be returned to the browser consulting the report page. While the |
| 3038 | browser is free to apply any delay, it will generally respect it |
| 3039 | and refresh the page this every seconds. The refresh interval may |
| 3040 | be specified in any other non-default time unit, by suffixing the |
| 3041 | unit after the value, as explained at the top of this document. |
| 3042 | |
| 3043 | This statement is useful on monitoring displays with a permanent page |
| 3044 | reporting the load balancer's activity. When set, the HTML report page will |
| 3045 | include a link "refresh"/"stop refresh" so that the user can select whether |
| 3046 | he wants automatic refresh of the page or not. |
| 3047 | |
| 3048 | Though this statement alone is enough to enable statistics reporting, it is |
| 3049 | recommended to set all other settings in order to avoid relying on default |
| 3050 | unobvious parameters. |
| 3051 | |
| 3052 | Example : |
| 3053 | # public access (limited to this backend only) |
| 3054 | backend public_www |
| 3055 | server srv1 192.168.0.1:80 |
| 3056 | stats enable |
| 3057 | stats hide-version |
| 3058 | stats scope . |
| 3059 | stats uri /admin?stats |
| 3060 | stats realm Haproxy\ Statistics |
| 3061 | stats auth admin1:AdMiN123 |
| 3062 | stats auth admin2:AdMiN321 |
| 3063 | |
| 3064 | # internal monitoring access (unlimited) |
| 3065 | backend private_monitoring |
| 3066 | stats enable |
| 3067 | stats uri /admin?stats |
| 3068 | stats refresh 5s |
| 3069 | |
| 3070 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| 3071 | |
| 3072 | |
| 3073 | stats scope { <name> | "." } |
| 3074 | Enable statistics and limit access scope |
| 3075 | May be used in sections : defaults | frontend | listen | backend |
| 3076 | yes | no | yes | yes |
| 3077 | Arguments : |
| 3078 | <name> is the name of a listen, frontend or backend section to be |
| 3079 | reported. The special name "." (a single dot) designates the |
| 3080 | section in which the statement appears. |
| 3081 | |
| 3082 | When this statement is specified, only the sections enumerated with this |
| 3083 | statement will appear in the report. All other ones will be hidden. This |
| 3084 | statement may appear as many times as needed if multiple sections need to be |
| 3085 | reported. Please note that the name checking is performed as simple string |
| 3086 | comparisons, and that it is never checked that a give section name really |
| 3087 | exists. |
| 3088 | |
| 3089 | Though this statement alone is enough to enable statistics reporting, it is |
| 3090 | recommended to set all other settings in order to avoid relying on default |
| 3091 | unobvious parameters. |
| 3092 | |
| 3093 | Example : |
| 3094 | # public access (limited to this backend only) |
| 3095 | backend public_www |
| 3096 | server srv1 192.168.0.1:80 |
| 3097 | stats enable |
| 3098 | stats hide-version |
| 3099 | stats scope . |
| 3100 | stats uri /admin?stats |
| 3101 | stats realm Haproxy\ Statistics |
| 3102 | stats auth admin1:AdMiN123 |
| 3103 | stats auth admin2:AdMiN321 |
| 3104 | |
| 3105 | # internal monitoring access (unlimited) |
| 3106 | backend private_monitoring |
| 3107 | stats enable |
| 3108 | stats uri /admin?stats |
| 3109 | stats refresh 5s |
| 3110 | |
| 3111 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| 3112 | |
| 3113 | |
| 3114 | stats uri <prefix> |
| 3115 | Enable statistics and define the URI prefix to access them |
| 3116 | May be used in sections : defaults | frontend | listen | backend |
| 3117 | yes | no | yes | yes |
| 3118 | Arguments : |
| 3119 | <prefix> is the prefix of any URI which will be redirected to stats. This |
| 3120 | prefix may contain a question mark ('?') to indicate part of a |
| 3121 | query string. |
| 3122 | |
| 3123 | The statistics URI is intercepted on the relayed traffic, so it appears as a |
| 3124 | page within the normal application. It is strongly advised to ensure that the |
| 3125 | selected URI will never appear in the application, otherwise it will never be |
| 3126 | possible to reach it in the application. |
| 3127 | |
| 3128 | The default URI compiled in haproxy is "/haproxy?stats", but this may be |
| 3129 | changed at build time, so it's better to always explictly specify it here. |
| 3130 | It is generally a good idea to include a question mark in the URI so that |
| 3131 | intermediate proxies refrain from caching the results. Also, since any string |
| 3132 | beginning with the prefix will be accepted as a stats request, the question |
| 3133 | mark helps ensuring that no valid URI will begin with the same words. |
| 3134 | |
| 3135 | It is sometimes very convenient to use "/" as the URI prefix, and put that |
| 3136 | statement in a "listen" instance of its own. That makes it easy to dedicate |
| 3137 | an address or a port to statistics only. |
| 3138 | |
| 3139 | Though this statement alone is enough to enable statistics reporting, it is |
| 3140 | recommended to set all other settings in order to avoid relying on default |
| 3141 | unobvious parameters. |
| 3142 | |
| 3143 | Example : |
| 3144 | # public access (limited to this backend only) |
| 3145 | backend public_www |
| 3146 | server srv1 192.168.0.1:80 |
| 3147 | stats enable |
| 3148 | stats hide-version |
| 3149 | stats scope . |
| 3150 | stats uri /admin?stats |
| 3151 | stats realm Haproxy\ Statistics |
| 3152 | stats auth admin1:AdMiN123 |
| 3153 | stats auth admin2:AdMiN321 |
| 3154 | |
| 3155 | # internal monitoring access (unlimited) |
| 3156 | backend private_monitoring |
| 3157 | stats enable |
| 3158 | stats uri /admin?stats |
| 3159 | stats refresh 5s |
| 3160 | |
| 3161 | See also : "stats auth", "stats enable", "stats realm" |
| 3162 | |
| 3163 | |
| 3164 | stats hide-version |
| 3165 | Enable statistics and hide HAProxy version reporting |
| 3166 | May be used in sections : defaults | frontend | listen | backend |
| 3167 | yes | no | yes | yes |
| 3168 | Arguments : none |
| 3169 | |
| 3170 | By default, the stats page reports some useful status information along with |
| 3171 | the statistics. Among them is HAProxy's version. However, it is generally |
| 3172 | considered dangerous to report precise version to anyone, as it can help them |
| 3173 | target known weaknesses with specific attacks. The "stats hide-version" |
| 3174 | statement removes the version from the statistics report. This is recommended |
| 3175 | for public sites or any site with a weak login/password. |
| 3176 | |
| 3177 | Though this statement alone is enough to enable statistics reporting, it is |
| 3178 | recommended to set all other settings in order to avoid relying on default |
| 3179 | unobvious parameters. |
| 3180 | |
| 3181 | Example : |
| 3182 | # public access (limited to this backend only) |
| 3183 | backend public_www |
| 3184 | server srv1 192.168.0.1:80 |
| 3185 | stats enable |
| 3186 | stats hide-version |
| 3187 | stats scope . |
| 3188 | stats uri /admin?stats |
| 3189 | stats realm Haproxy\ Statistics |
| 3190 | stats auth admin1:AdMiN123 |
| 3191 | stats auth admin2:AdMiN321 |
| 3192 | |
| 3193 | # internal monitoring access (unlimited) |
| 3194 | backend private_monitoring |
| 3195 | stats enable |
| 3196 | stats uri /admin?stats |
| 3197 | stats refresh 5s |
| 3198 | |
| 3199 | See also : "stats auth", "stats enable", "stats realm", "stats uri" |
| 3200 | |
| 3201 | |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 3202 | timeout check <timeout> |
| 3203 | Set additional check timeout, but only after a connection has been already |
| 3204 | established. |
| 3205 | |
| 3206 | May be used in sections: defaults | frontend | listen | backend |
| 3207 | yes | no | yes | yes |
| 3208 | Arguments: |
| 3209 | <timeout> is the timeout value specified in milliseconds by default, but |
| 3210 | can be in any other unit if the number is suffixed by the unit, |
| 3211 | as explained at the top of this document. |
| 3212 | |
| 3213 | If set, haproxy uses min("timeout connect", "inter") as a connect timeout |
| 3214 | for check and "timeout check" as an additional read timeout. The "min" is |
| 3215 | used so that people running with *very* long "timeout connect" (eg. those |
| 3216 | who needed this due to the queue or tarpit) do not slow down their checks. |
| 3217 | Of course it is better to use "check queue" and "check tarpit" instead of |
| 3218 | long "timeout connect". |
| 3219 | |
| 3220 | If "timeout check" is not set haproxy uses "inter" for complete check |
| 3221 | timeout (connect + read) exactly like all <1.3.15 version. |
| 3222 | |
| 3223 | In most cases check request is much simpler and faster to handle than normal |
| 3224 | requests and people may want to kick out laggy servers so this timeout should |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 3225 | be smaller than "timeout server". |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 3226 | |
| 3227 | This parameter is specific to backends, but can be specified once for all in |
| 3228 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 3229 | forget about it. |
| 3230 | |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 3231 | See also: "timeout connect", "timeout queue", "timeout server", |
| 3232 | "timeout tarpit". |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 3233 | |
| 3234 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3235 | timeout client <timeout> |
| 3236 | timeout clitimeout <timeout> (deprecated) |
| 3237 | Set the maximum inactivity time on the client side. |
| 3238 | May be used in sections : defaults | frontend | listen | backend |
| 3239 | yes | yes | yes | no |
| 3240 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 3241 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3242 | can be in any other unit if the number is suffixed by the unit, |
| 3243 | as explained at the top of this document. |
| 3244 | |
| 3245 | The inactivity timeout applies when the client is expected to acknowledge or |
| 3246 | send data. In HTTP mode, this timeout is particularly important to consider |
| 3247 | during the first phase, when the client sends the request, and during the |
| 3248 | response while it is reading data sent by the server. The value is specified |
| 3249 | in milliseconds by default, but can be in any other unit if the number is |
| 3250 | suffixed by the unit, as specified at the top of this document. In TCP mode |
| 3251 | (and to a lesser extent, in HTTP mode), it is highly recommended that the |
| 3252 | client timeout remains equal to the server timeout in order to avoid complex |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 3253 | situations to debug. It is a good practice to cover one or several TCP packet |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3254 | losses by specifying timeouts that are slightly above multiples of 3 seconds |
| 3255 | (eg: 4 or 5 seconds). |
| 3256 | |
| 3257 | This parameter is specific to frontends, but can be specified once for all in |
| 3258 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 3259 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 3260 | is not recommended. Such a usage is accepted and works but reports a warning |
| 3261 | during startup because it may results in accumulation of expired sessions in |
| 3262 | the system if the system's timeouts are not configured either. |
| 3263 | |
| 3264 | This parameter replaces the old, deprecated "clitimeout". It is recommended |
| 3265 | to use it to write new configurations. The form "timeout clitimeout" is |
| 3266 | provided only by backwards compatibility but its use is strongly discouraged. |
| 3267 | |
| 3268 | See also : "clitimeout", "timeout server". |
| 3269 | |
| 3270 | |
| 3271 | timeout connect <timeout> |
| 3272 | timeout contimeout <timeout> (deprecated) |
| 3273 | Set the maximum time to wait for a connection attempt to a server to succeed. |
| 3274 | May be used in sections : defaults | frontend | listen | backend |
| 3275 | yes | no | yes | yes |
| 3276 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 3277 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3278 | can be in any other unit if the number is suffixed by the unit, |
| 3279 | as explained at the top of this document. |
| 3280 | |
| 3281 | If the server is located on the same LAN as haproxy, the connection should be |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 3282 | immediate (less than a few milliseconds). Anyway, it is a good practice to |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3283 | cover one or several TCP packet losses by specifying timeouts that are |
| 3284 | slightly above multiples of 3 seconds (eg: 4 or 5 seconds). By default, the |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 3285 | connect timeout also presets both queue and tarpit timeouts to the same value |
| 3286 | if these have not been specified. |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3287 | |
| 3288 | This parameter is specific to backends, but can be specified once for all in |
| 3289 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 3290 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 3291 | is not recommended. Such a usage is accepted and works but reports a warning |
| 3292 | during startup because it may results in accumulation of failed sessions in |
| 3293 | the system if the system's timeouts are not configured either. |
| 3294 | |
| 3295 | This parameter replaces the old, deprecated "contimeout". It is recommended |
| 3296 | to use it to write new configurations. The form "timeout contimeout" is |
| 3297 | provided only by backwards compatibility but its use is strongly discouraged. |
| 3298 | |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 3299 | See also: "timeout check", "timeout queue", "timeout server", "contimeout", |
| 3300 | "timeout tarpit". |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3301 | |
| 3302 | |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 3303 | timeout http-request <timeout> |
| 3304 | Set the maximum allowed time to wait for a complete HTTP request |
| 3305 | May be used in sections : defaults | frontend | listen | backend |
| 3306 | yes | yes | yes | no |
| 3307 | Arguments : |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 3308 | <timeout> is the timeout value specified in milliseconds by default, but |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 3309 | can be in any other unit if the number is suffixed by the unit, |
| 3310 | as explained at the top of this document. |
| 3311 | |
| 3312 | In order to offer DoS protection, it may be required to lower the maximum |
| 3313 | accepted time to receive a complete HTTP request without affecting the client |
| 3314 | timeout. This helps protecting against established connections on which |
| 3315 | nothing is sent. The client timeout cannot offer a good protection against |
| 3316 | this abuse because it is an inactivity timeout, which means that if the |
| 3317 | attacker sends one character every now and then, the timeout will not |
| 3318 | trigger. With the HTTP request timeout, no matter what speed the client |
| 3319 | types, the request will be aborted if it does not complete in time. |
| 3320 | |
| 3321 | Note that this timeout only applies to the header part of the request, and |
| 3322 | not to any data. As soon as the empty line is received, this timeout is not |
| 3323 | used anymore. |
| 3324 | |
| 3325 | Generally it is enough to set it to a few seconds, as most clients send the |
| 3326 | full request immediately upon connection. Add 3 or more seconds to cover TCP |
| 3327 | retransmits but that's all. Setting it to very low values (eg: 50 ms) will |
| 3328 | generally work on local networks as long as there are no packet losses. This |
| 3329 | will prevent people from sending bare HTTP requests using telnet. |
| 3330 | |
| 3331 | If this parameter is not set, the client timeout still applies between each |
| 3332 | chunk of the incoming request. |
| 3333 | |
| 3334 | See also : "timeout client". |
| 3335 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 3336 | |
| 3337 | timeout queue <timeout> |
| 3338 | Set the maximum time to wait in the queue for a connection slot to be free |
| 3339 | May be used in sections : defaults | frontend | listen | backend |
| 3340 | yes | no | yes | yes |
| 3341 | Arguments : |
| 3342 | <timeout> is the timeout value specified in milliseconds by default, but |
| 3343 | can be in any other unit if the number is suffixed by the unit, |
| 3344 | as explained at the top of this document. |
| 3345 | |
| 3346 | When a server's maxconn is reached, connections are left pending in a queue |
| 3347 | which may be server-specific or global to the backend. In order not to wait |
| 3348 | indefinitely, a timeout is applied to requests pending in the queue. If the |
| 3349 | timeout is reached, it is considered that the request will almost never be |
| 3350 | served, so it is dropped and a 503 error is returned to the client. |
| 3351 | |
| 3352 | The "timeout queue" statement allows to fix the maximum time for a request to |
| 3353 | be left pending in a queue. If unspecified, the same value as the backend's |
| 3354 | connection timeout ("timeout connect") is used, for backwards compatibility |
| 3355 | with older versions with no "timeout queue" parameter. |
| 3356 | |
| 3357 | See also : "timeout connect", "contimeout". |
| 3358 | |
| 3359 | |
| 3360 | timeout server <timeout> |
| 3361 | timeout srvtimeout <timeout> (deprecated) |
| 3362 | Set the maximum inactivity time on the server side. |
| 3363 | May be used in sections : defaults | frontend | listen | backend |
| 3364 | yes | no | yes | yes |
| 3365 | Arguments : |
| 3366 | <timeout> is the timeout value specified in milliseconds by default, but |
| 3367 | can be in any other unit if the number is suffixed by the unit, |
| 3368 | as explained at the top of this document. |
| 3369 | |
| 3370 | The inactivity timeout applies when the server is expected to acknowledge or |
| 3371 | send data. In HTTP mode, this timeout is particularly important to consider |
| 3372 | during the first phase of the server's response, when it has to send the |
| 3373 | headers, as it directly represents the server's processing time for the |
| 3374 | request. To find out what value to put there, it's often good to start with |
| 3375 | what would be considered as unacceptable response times, then check the logs |
| 3376 | to observe the response time distribution, and adjust the value accordingly. |
| 3377 | |
| 3378 | The value is specified in milliseconds by default, but can be in any other |
| 3379 | unit if the number is suffixed by the unit, as specified at the top of this |
| 3380 | document. In TCP mode (and to a lesser extent, in HTTP mode), it is highly |
| 3381 | recommended that the client timeout remains equal to the server timeout in |
| 3382 | order to avoid complex situations to debug. Whatever the expected server |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 3383 | response times, it is a good practice to cover at least one or several TCP |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 3384 | packet losses by specifying timeouts that are slightly above multiples of 3 |
| 3385 | seconds (eg: 4 or 5 seconds minimum). |
| 3386 | |
| 3387 | This parameter is specific to backends, but can be specified once for all in |
| 3388 | "defaults" sections. This is in fact one of the easiest solutions not to |
| 3389 | forget about it. An unspecified timeout results in an infinite timeout, which |
| 3390 | is not recommended. Such a usage is accepted and works but reports a warning |
| 3391 | during startup because it may results in accumulation of expired sessions in |
| 3392 | the system if the system's timeouts are not configured either. |
| 3393 | |
| 3394 | This parameter replaces the old, deprecated "srvtimeout". It is recommended |
| 3395 | to use it to write new configurations. The form "timeout srvtimeout" is |
| 3396 | provided only by backwards compatibility but its use is strongly discouraged. |
| 3397 | |
| 3398 | See also : "srvtimeout", "timeout client". |
| 3399 | |
| 3400 | |
| 3401 | timeout tarpit <timeout> |
| 3402 | Set the duration for which tapitted connections will be maintained |
| 3403 | May be used in sections : defaults | frontend | listen | backend |
| 3404 | yes | yes | yes | yes |
| 3405 | Arguments : |
| 3406 | <timeout> is the tarpit duration specified in milliseconds by default, but |
| 3407 | can be in any other unit if the number is suffixed by the unit, |
| 3408 | as explained at the top of this document. |
| 3409 | |
| 3410 | When a connection is tarpitted using "reqtarpit", it is maintained open with |
| 3411 | no activity for a certain amount of time, then closed. "timeout tarpit" |
| 3412 | defines how long it will be maintained open. |
| 3413 | |
| 3414 | The value is specified in milliseconds by default, but can be in any other |
| 3415 | unit if the number is suffixed by the unit, as specified at the top of this |
| 3416 | document. If unspecified, the same value as the backend's connection timeout |
| 3417 | ("timeout connect") is used, for backwards compatibility with older versions |
| 3418 | with no "timeout tapit" parameter. |
| 3419 | |
| 3420 | See also : "timeout connect", "contimeout". |
| 3421 | |
| 3422 | |
| 3423 | transparent (deprecated) |
| 3424 | Enable client-side transparent proxying |
| 3425 | May be used in sections : defaults | frontend | listen | backend |
| 3426 | yes | yes | yes | no |
| 3427 | Arguments : none |
| 3428 | |
| 3429 | This keyword was introduced in order to provide layer 7 persistence to layer |
| 3430 | 3 load balancers. The idea is to use the OS's ability to redirect an incoming |
| 3431 | connection for a remote address to a local process (here HAProxy), and let |
| 3432 | this process know what address was initially requested. When this option is |
| 3433 | used, sessions without cookies will be forwarded to the original destination |
| 3434 | IP address of the incoming request (which should match that of another |
| 3435 | equipment), while requests with cookies will still be forwarded to the |
| 3436 | appropriate server. |
| 3437 | |
| 3438 | The "transparent" keyword is deprecated, use "option transparent" instead. |
| 3439 | |
| 3440 | Note that contrary to a common belief, this option does NOT make HAProxy |
| 3441 | present the client's IP to the server when establishing the connection. |
| 3442 | |
| 3443 | Use of this option is really discouraged, and since no really valid use of it |
| 3444 | has been reported for years, it will probably be removed in future versions. |
| 3445 | |
| 3446 | See also: "option transparent" |
| 3447 | |
| 3448 | |
| 3449 | use_backend <backend> if <condition> |
| 3450 | use_backend <backend> unless <condition> |
| 3451 | Switch to a specific backend if/unless a Layer 7 condition is matched. |
| 3452 | May be used in sections : defaults | frontend | listen | backend |
| 3453 | no | yes | yes | no |
| 3454 | Arguments : |
| 3455 | <backend> is the name of a valid backend or "listen" section. |
| 3456 | |
| 3457 | <condition> is a condition composed of ACLs, as described in section 2.3. |
| 3458 | |
| 3459 | When doing content-switching, connections arrive on a frontend and are then |
| 3460 | dispatched to various backends depending on a number of conditions. The |
| 3461 | relation between the conditions and the backends is described with the |
| 3462 | "use_backend" keyword. This is supported only in HTTP mode. |
| 3463 | |
| 3464 | There may be as many "use_backend" rules as desired. All of these rules are |
| 3465 | evaluated in their declaration order, and the first one which matches will |
| 3466 | assign the backend. |
| 3467 | |
| 3468 | In the first form, the backend will be used if the condition is met. In the |
| 3469 | second form, the backend will be used if the condition is not met. If no |
| 3470 | condition is valid, the backend defined with "default_backend" will be used. |
| 3471 | If no default backend is defined, either the servers in the same section are |
| 3472 | used (in case of a "listen" section) or, in case of a frontend, no server is |
| 3473 | used and a 503 service unavailable response is returned. |
| 3474 | |
| 3475 | See also: "default_backend" and section 2.3 about ACLs. |
| 3476 | |
Willy Tarreau | 036fae0 | 2008-01-06 13:24:40 +0100 | [diff] [blame] | 3477 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3478 | 2.3) Using ACLs |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3479 | --------------- |
| 3480 | |
| 3481 | The use of Access Control Lists (ACL) provides a flexible solution to perform |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3482 | content switching and generally to take decisions based on content extracted |
| 3483 | from the request, the response or any environmental status. The principle is |
| 3484 | simple : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3485 | |
| 3486 | - define test criteria with sets of values |
| 3487 | - perform actions only if a set of tests is valid |
| 3488 | |
| 3489 | The actions generally consist in blocking the request, or selecting a backend. |
| 3490 | |
| 3491 | In order to define a test, the "acl" keyword is used. The syntax is : |
| 3492 | |
| 3493 | acl <aclname> <criterion> [flags] [operator] <value> ... |
| 3494 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3495 | This creates a new ACL <aclname> or completes an existing one with new tests. |
| 3496 | Those tests apply to the portion of request/response specified in <criterion> |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3497 | and may be adjusted with optional flags [flags]. Some criteria also support |
| 3498 | an operator which may be specified before the set of values. The values are |
| 3499 | of the type supported by the criterion, and are separated by spaces. |
| 3500 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3501 | ACL names must be formed from upper and lower case letters, digits, '-' (dash), |
| 3502 | '_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive, |
| 3503 | which means that "my_acl" and "My_Acl" are two different ACLs. |
| 3504 | |
| 3505 | There is no enforced limit to the number of ACLs. The unused ones do not affect |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3506 | performance, they just consume a small amount of memory. |
| 3507 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3508 | The following ACL flags are currently supported : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3509 | |
| 3510 | -i : ignore case during matching. |
| 3511 | -- : force end of flags. Useful when a string looks like one of the flags. |
| 3512 | |
| 3513 | Supported types of values are : |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3514 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3515 | - integers or integer ranges |
| 3516 | - strings |
| 3517 | - regular expressions |
| 3518 | - IP addresses and networks |
| 3519 | |
| 3520 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3521 | 2.3.1) Matching integers |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3522 | ------------------------ |
| 3523 | |
| 3524 | Matching integers is special in that ranges and operators are permitted. Note |
| 3525 | that integer matching only applies to positive values. A range is a value |
| 3526 | expressed with a lower and an upper bound separated with a colon, both of which |
| 3527 | may be omitted. |
| 3528 | |
| 3529 | For instance, "1024:65535" is a valid range to represent a range of |
| 3530 | unprivileged ports, and "1024:" would also work. "0:1023" is a valid |
| 3531 | representation of privileged ports, and ":1023" would also work. |
| 3532 | |
| 3533 | For an easier usage, comparison operators are also supported. Note that using |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3534 | operators with ranges does not make much sense and is strongly discouraged. |
| 3535 | Similarly, it does not make much sense to perform order comparisons with a set |
| 3536 | of values. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3537 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3538 | Available operators for integer matching are : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3539 | |
| 3540 | eq : true if the tested value equals at least one value |
| 3541 | ge : true if the tested value is greater than or equal to at least one value |
| 3542 | gt : true if the tested value is greater than at least one value |
| 3543 | le : true if the tested value is less than or equal to at least one value |
| 3544 | lt : true if the tested value is less than at least one value |
| 3545 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3546 | For instance, the following ACL matches any negative Content-Length header : |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3547 | |
| 3548 | acl negative-length hdr_val(content-length) lt 0 |
| 3549 | |
| 3550 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3551 | 2.3.2) Matching strings |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3552 | ----------------------- |
| 3553 | |
| 3554 | String matching applies to verbatim strings as they are passed, with the |
| 3555 | exception of the backslash ("\") which makes it possible to escape some |
| 3556 | characters such as the space. If the "-i" flag is passed before the first |
| 3557 | string, then the matching will be performed ignoring the case. In order |
| 3558 | to match the string "-i", either set it second, or pass the "--" flag |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3559 | before the first string. Same applies of course to match the string "--". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3560 | |
| 3561 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3562 | 2.3.3) Matching regular expressions (regexes) |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3563 | --------------------------------------------- |
| 3564 | |
| 3565 | Just like with string matching, regex matching applies to verbatim strings as |
| 3566 | they are passed, with the exception of the backslash ("\") which makes it |
| 3567 | possible to escape some characters such as the space. If the "-i" flag is |
| 3568 | passed before the first regex, then the matching will be performed ignoring |
| 3569 | the case. In order to match the string "-i", either set it second, or pass |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3570 | the "--" flag before the first string. Same principle applies of course to |
| 3571 | match the string "--". |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3572 | |
| 3573 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3574 | 2.3.4) Matching IPv4 addresses |
| 3575 | ------------------------------ |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3576 | |
| 3577 | IPv4 addresses values can be specified either as plain addresses or with a |
| 3578 | netmask appended, in which case the IPv4 address matches whenever it is |
| 3579 | within the network. Plain addresses may also be replaced with a resolvable |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 3580 | host name, but this practice is generally discouraged as it makes it more |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3581 | difficult to read and debug configurations. If hostnames are used, you should |
| 3582 | at least ensure that they are present in /etc/hosts so that the configuration |
| 3583 | does not depend on any random DNS match at the moment the configuration is |
| 3584 | parsed. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3585 | |
| 3586 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3587 | 2.3.5) Available matching criteria |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3588 | ---------------------------------- |
| 3589 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3590 | 2.3.5.1) Matching at Layer 4 and below |
| 3591 | -------------------------------------- |
| 3592 | |
| 3593 | A first set of criteria applies to information which does not require any |
| 3594 | analysis of the request or response contents. Those generally include TCP/IP |
| 3595 | addresses and ports, as well as internal values independant on the stream. |
| 3596 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3597 | always_false |
| 3598 | This one never matches. All values and flags are ignored. It may be used as |
| 3599 | a temporary replacement for another one when adjusting configurations. |
| 3600 | |
| 3601 | always_true |
| 3602 | This one always matches. All values and flags are ignored. It may be used as |
| 3603 | a temporary replacement for another one when adjusting configurations. |
| 3604 | |
| 3605 | src <ip_address> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3606 | Applies to the client's IPv4 address. It is usually used to limit access to |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3607 | certain resources such as statistics. Note that it is the TCP-level source |
| 3608 | address which is used, and not the address of a client behind a proxy. |
| 3609 | |
| 3610 | src_port <integer> |
| 3611 | Applies to the client's TCP source port. This has a very limited usage. |
| 3612 | |
| 3613 | dst <ip_address> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3614 | Applies to the local IPv4 address the client connected to. It can be used to |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3615 | switch to a different backend for some alternative addresses. |
| 3616 | |
| 3617 | dst_port <integer> |
| 3618 | Applies to the local port the client connected to. It can be used to switch |
| 3619 | to a different backend for some alternative ports. |
| 3620 | |
| 3621 | dst_conn <integer> |
| 3622 | Applies to the number of currently established connections on the frontend, |
| 3623 | including the one being evaluated. It can be used to either return a sorry |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3624 | page before hard-blocking, or to use a specific backend to drain new requests |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3625 | when the farm is considered saturated. |
| 3626 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3627 | nbsrv <integer> |
| 3628 | nbsrv(backend) <integer> |
| 3629 | Returns true when the number of usable servers of either the current backend |
| 3630 | or the named backend matches the values or ranges specified. This is used to |
| 3631 | switch to an alternate backend when the number of servers is too low to |
| 3632 | to handle some load. It is useful to report a failure when combined with |
| 3633 | "monitor fail". |
| 3634 | |
| 3635 | |
| 3636 | 2.3.5.2) Matching at Layer 7 |
| 3637 | ---------------------------- |
| 3638 | |
| 3639 | A second set of criteria applies to information which can be found at the |
| 3640 | application layer (layer 7). Those require that a full HTTP request has been |
| 3641 | read, and are only evaluated then. They may require slightly more CPU resources |
| 3642 | than the layer 4 ones, but not much since the request and response are indexed. |
| 3643 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3644 | method <string> |
| 3645 | Applies to the method in the HTTP request, eg: "GET". Some predefined ACL |
| 3646 | already check for most common methods. |
| 3647 | |
| 3648 | req_ver <string> |
| 3649 | Applies to the version string in the HTTP request, eg: "1.0". Some predefined |
| 3650 | ACL already check for versions 1.0 and 1.1. |
| 3651 | |
| 3652 | path <string> |
| 3653 | Returns true when the path part of the request, which starts at the first |
| 3654 | slash and ends before the question mark, equals one of the strings. It may be |
| 3655 | used to match known files, such as /favicon.ico. |
| 3656 | |
| 3657 | path_beg <string> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3658 | Returns true when the path begins with one of the strings. This can be used |
| 3659 | to send certain directory names to alternative backends. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3660 | |
| 3661 | path_end <string> |
| 3662 | Returns true when the path ends with one of the strings. This may be used to |
| 3663 | control file name extension. |
| 3664 | |
| 3665 | path_sub <string> |
| 3666 | Returns true when the path contains one of the strings. It can be used to |
| 3667 | detect particular patterns in paths, such as "../" for example. See also |
| 3668 | "path_dir". |
| 3669 | |
| 3670 | path_dir <string> |
| 3671 | Returns true when one of the strings is found isolated or delimited with |
| 3672 | slashes in the path. This is used to perform filename or directory name |
| 3673 | matching without the risk of wrong match due to colliding prefixes. See also |
| 3674 | "url_dir" and "path_sub". |
| 3675 | |
| 3676 | path_dom <string> |
| 3677 | Returns true when one of the strings is found isolated or delimited with dots |
| 3678 | in the path. This may be used to perform domain name matching in proxy |
| 3679 | requests. See also "path_sub" and "url_dom". |
| 3680 | |
| 3681 | path_reg <regex> |
| 3682 | Returns true when the path matches one of the regular expressions. It can be |
| 3683 | used any time, but it is important to remember that regex matching is slower |
| 3684 | than other methods. See also "url_reg" and all "path_" criteria. |
| 3685 | |
| 3686 | url <string> |
| 3687 | Applies to the whole URL passed in the request. The only real use is to match |
| 3688 | "*", for which there already is a predefined ACL. |
| 3689 | |
| 3690 | url_beg <string> |
| 3691 | Returns true when the URL begins with one of the strings. This can be used to |
| 3692 | check whether a URL begins with a slash or with a protocol scheme. |
| 3693 | |
| 3694 | url_end <string> |
| 3695 | Returns true when the URL ends with one of the strings. It has very limited |
| 3696 | use. "path_end" should be used instead for filename matching. |
| 3697 | |
| 3698 | url_sub <string> |
| 3699 | Returns true when the URL contains one of the strings. It can be used to |
| 3700 | detect particular patterns in query strings for example. See also "path_sub". |
| 3701 | |
| 3702 | url_dir <string> |
| 3703 | Returns true when one of the strings is found isolated or delimited with |
| 3704 | slashes in the URL. This is used to perform filename or directory name |
| 3705 | matching without the risk of wrong match due to colliding prefixes. See also |
| 3706 | "path_dir" and "url_sub". |
| 3707 | |
| 3708 | url_dom <string> |
| 3709 | Returns true when one of the strings is found isolated or delimited with dots |
| 3710 | in the URL. This is used to perform domain name matching without the risk of |
| 3711 | wrong match due to colliding prefixes. See also "url_sub". |
| 3712 | |
| 3713 | url_reg <regex> |
| 3714 | Returns true when the URL matches one of the regular expressions. It can be |
| 3715 | used any time, but it is important to remember that regex matching is slower |
| 3716 | than other methods. See also "path_reg" and all "url_" criteria. |
| 3717 | |
Alexandre Cassen | 5eb1a90 | 2007-11-29 15:43:32 +0100 | [diff] [blame] | 3718 | url_ip <ip_address> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3719 | Applies to the IP address specified in the absolute URI in an HTTP request. |
| 3720 | It can be used to prevent access to certain resources such as local network. |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3721 | It is useful with option "http_proxy". |
Alexandre Cassen | 5eb1a90 | 2007-11-29 15:43:32 +0100 | [diff] [blame] | 3722 | |
| 3723 | url_port <integer> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3724 | Applies to the port specified in the absolute URI in an HTTP request. It can |
| 3725 | be used to prevent access to certain resources. It is useful with option |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3726 | "http_proxy". Note that if the port is not specified in the request, port 80 |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3727 | is assumed. |
Alexandre Cassen | 5eb1a90 | 2007-11-29 15:43:32 +0100 | [diff] [blame] | 3728 | |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3729 | hdr <string> |
| 3730 | hdr(header) <string> |
| 3731 | Note: all the "hdr*" matching criteria either apply to all headers, or to a |
| 3732 | particular header whose name is passed between parenthesis and without any |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3733 | space. The header name is not case-sensitive. The header matching complies |
| 3734 | with RFC2616, and treats as separate headers all values delimited by commas. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3735 | |
| 3736 | The "hdr" criteria returns true if any of the headers matching the criteria |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3737 | match any of the strings. This can be used to check exact for values. For |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3738 | instance, checking that "connection: close" is set : |
| 3739 | |
| 3740 | hdr(Connection) -i close |
| 3741 | |
| 3742 | hdr_beg <string> |
| 3743 | hdr_beg(header) <string> |
| 3744 | Returns true when one of the headers begins with one of the strings. See |
| 3745 | "hdr" for more information on header matching. |
| 3746 | |
| 3747 | hdr_end <string> |
| 3748 | hdr_end(header) <string> |
| 3749 | Returns true when one of the headers ends with one of the strings. See "hdr" |
| 3750 | for more information on header matching. |
| 3751 | |
| 3752 | hdr_sub <string> |
| 3753 | hdr_sub(header) <string> |
| 3754 | Returns true when one of the headers contains one of the strings. See "hdr" |
| 3755 | for more information on header matching. |
| 3756 | |
| 3757 | hdr_dir <string> |
| 3758 | hdr_dir(header) <string> |
| 3759 | Returns true when one of the headers contains one of the strings either |
| 3760 | isolated or delimited by slashes. This is used to perform filename or |
| 3761 | directory name matching, and may be used with Referer. See "hdr" for more |
| 3762 | information on header matching. |
| 3763 | |
| 3764 | hdr_dom <string> |
| 3765 | hdr_dom(header) <string> |
| 3766 | Returns true when one of the headers contains one of the strings either |
| 3767 | isolated or delimited by dots. This is used to perform domain name matching, |
| 3768 | and may be used with the Host header. See "hdr" for more information on |
| 3769 | header matching. |
| 3770 | |
| 3771 | hdr_reg <regex> |
| 3772 | hdr_reg(header) <regex> |
| 3773 | Returns true when one of the headers matches of the regular expressions. It |
| 3774 | can be used at any time, but it is important to remember that regex matching |
| 3775 | is slower than other methods. See also other "hdr_" criteria, as well as |
| 3776 | "hdr" for more information on header matching. |
| 3777 | |
| 3778 | hdr_val <integer> |
| 3779 | hdr_val(header) <integer> |
| 3780 | Returns true when one of the headers starts with a number which matches the |
| 3781 | values or ranges specified. This may be used to limit content-length to |
| 3782 | acceptable values for example. See "hdr" for more information on header |
| 3783 | matching. |
| 3784 | |
| 3785 | hdr_cnt <integer> |
| 3786 | hdr_cnt(header) <integer> |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3787 | Returns true when the number of occurrence of the specified header matches |
| 3788 | the values or ranges specified. It is important to remember that one header |
| 3789 | line may count as several headers if it has several values. This is used to |
| 3790 | detect presence, absence or abuse of a specific header, as well as to block |
| 3791 | request smugling attacks by rejecting requests which contain more than one |
| 3792 | of certain headers. See "hdr" for more information on header matching. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3793 | |
| 3794 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3795 | 2.3.6) Pre-defined ACLs |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3796 | ----------------------- |
| 3797 | |
| 3798 | Some predefined ACLs are hard-coded so that they do not have to be declared in |
| 3799 | every frontend which needs them. They all have their names in upper case in |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3800 | order to avoid confusion. Their equivalence is provided below. Please note that |
| 3801 | only the first three ones are not layer 7 based. |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3802 | |
| 3803 | ACL name Equivalent to Usage |
| 3804 | ---------------+-----------------------------+--------------------------------- |
| 3805 | TRUE always_true 1 always match |
| 3806 | FALSE always_false 0 never match |
| 3807 | LOCALHOST src 127.0.0.1/8 match connection from local host |
| 3808 | HTTP_1.0 req_ver 1.0 match HTTP version 1.0 |
| 3809 | HTTP_1.1 req_ver 1.1 match HTTP version 1.1 |
| 3810 | METH_CONNECT method CONNECT match HTTP CONNECT method |
| 3811 | METH_GET method GET HEAD match HTTP GET or HEAD method |
| 3812 | METH_HEAD method HEAD match HTTP HEAD method |
| 3813 | METH_OPTIONS method OPTIONS match HTTP OPTIONS method |
| 3814 | METH_POST method POST match HTTP POST method |
| 3815 | METH_TRACE method TRACE match HTTP TRACE method |
| 3816 | HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme |
| 3817 | HTTP_URL_SLASH url_beg / match URL begining with "/" |
| 3818 | HTTP_URL_STAR url * match URL equal to "*" |
| 3819 | HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length |
| 3820 | ---------------+-----------------------------+--------------------------------- |
| 3821 | |
| 3822 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3823 | 2.3.7) Using ACLs to form conditions |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3824 | ------------------------------------ |
| 3825 | |
| 3826 | Some actions are only performed upon a valid condition. A condition is a |
| 3827 | combination of ACLs with operators. 3 operators are supported : |
| 3828 | |
| 3829 | - AND (implicit) |
| 3830 | - OR (explicit with the "or" keyword or the "||" operator) |
| 3831 | - Negation with the exclamation mark ("!") |
| 3832 | |
| 3833 | A condition is formed as a disjonctive form : |
| 3834 | |
| 3835 | [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ... |
| 3836 | |
| 3837 | Such conditions are generally used after an "if" or "unless" statement, |
| 3838 | indicating when the condition will trigger the action. |
| 3839 | |
| 3840 | For instance, to block HTTP requests to the "*" URL with methods other than |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 3841 | "OPTIONS", as well as POST requests without content-length, and GET or HEAD |
| 3842 | requests with a content-length greater than 0, and finally every request which |
| 3843 | is not either GET/HEAD/POST/OPTIONS ! |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 3844 | |
| 3845 | acl missing_cl hdr_cnt(Content-length) eq 0 |
| 3846 | block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl |
| 3847 | block if METH_GET HTTP_CONTENT |
| 3848 | block unless METH_GET or METH_POST or METH_OPTIONS |
| 3849 | |
| 3850 | To select a different backend for requests to static contents on the "www" site |
| 3851 | and to every request on the "img", "video", "download" and "ftp" hosts : |
| 3852 | |
| 3853 | acl url_static path_beg /static /images /img /css |
| 3854 | acl url_static path_end .gif .png .jpg .css .js |
| 3855 | acl host_www hdr_beg(host) -i www |
| 3856 | acl host_static hdr_beg(host) -i img. video. download. ftp. |
| 3857 | |
| 3858 | # now use backend "static" for all static-only hosts, and for static urls |
| 3859 | # of host "www". Use backend "www" for the rest. |
| 3860 | use_backend static if host_static or host_www url_static |
| 3861 | use_backend www if host_www |
| 3862 | |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 3863 | See section 2.2 for detailed help on the "block" and "use_backend" keywords. |
Willy Tarreau | dbc36f6 | 2007-11-30 12:29:11 +0100 | [diff] [blame] | 3864 | |
| 3865 | |
Willy Tarreau | c7246fc | 2007-12-02 17:31:20 +0100 | [diff] [blame] | 3866 | 2.4) Server options |
Willy Tarreau | 5764b38 | 2007-11-30 17:46:49 +0100 | [diff] [blame] | 3867 | ------------------- |
| 3868 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3869 | The "server" keyword supports a certain number of settings which are all passed |
| 3870 | as arguments on the server line. The order in which those arguments appear does |
| 3871 | not count, and they are all optional. Some of those settings are single words |
| 3872 | (booleans) while others expect one or several values after them. In this case, |
| 3873 | the values must immediately follow the setting name. All those settings must be |
| 3874 | specified after the server's address if they are used : |
| 3875 | |
| 3876 | server <name> <address>[:port] [settings ...] |
| 3877 | |
| 3878 | The currently supported settings are the following ones. |
| 3879 | |
| 3880 | addr <ipv4> |
| 3881 | Using the "addr" parameter, it becomes possible to use a different IP address |
| 3882 | to send health-checks. On some servers, it may be desirable to dedicate an IP |
| 3883 | address to specific component able to perform complex tests which are more |
| 3884 | suitable to health-checks than the application. This parameter is ignored if |
| 3885 | the "check" parameter is not set. See also the "port" parameter. |
| 3886 | |
| 3887 | backup |
| 3888 | When "backup" is present on a server line, the server is only used in load |
| 3889 | balancing when all other non-backup servers are unavailable. Requests coming |
| 3890 | with a persistence cookie referencing the server will always be served |
| 3891 | though. By default, only the first operational backup server is used, unless |
Willy Tarreau | af85d94 | 2008-01-30 10:47:10 +0100 | [diff] [blame] | 3892 | the "allbackups" option is set in the backend. See also the "allbackups" |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3893 | option. |
| 3894 | |
| 3895 | check |
| 3896 | This option enables health checks on the server. By default, a server is |
| 3897 | always considered available. If "check" is set, the server will receive |
| 3898 | periodic health checks to ensure that it is really able to serve requests. |
| 3899 | The default address and port to send the tests to are those of the server, |
| 3900 | and the default source is the same as the one defined in the backend. It is |
| 3901 | possible to change the address using the "addr" parameter, the port using the |
| 3902 | "port" parameter, the source address using the "source" address, and the |
| 3903 | interval and timers using the "inter", "rise" and "fall" parameters. The |
| 3904 | request method is define in the backend using the "httpchk", "smtpchk", |
| 3905 | and "ssl-hello-chk" options. Please refer to those options and parameters for |
| 3906 | more information. |
| 3907 | |
| 3908 | cookie <value> |
| 3909 | The "cookie" parameter sets the cookie value assigned to the server to |
| 3910 | <value>. This value will be checked in incoming requests, and the first |
| 3911 | operational server possessing the same value will be selected. In return, in |
| 3912 | cookie insertion or rewrite modes, this value will be assigned to the cookie |
| 3913 | sent to the client. There is nothing wrong in having several servers sharing |
| 3914 | the same cookie value, and it is in fact somewhat common between normal and |
| 3915 | backup servers. See also the "cookie" keyword in backend section. |
| 3916 | |
| 3917 | fall <count> |
| 3918 | The "fall" parameter states that a server will be considered as dead after |
| 3919 | <count> consecutive unsuccessful health checks. This value defaults to 3 if |
| 3920 | unspecified. See also the "check", "inter" and "rise" parameters. |
| 3921 | |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 3922 | id <value> |
| 3923 | Set a persistent value for server ID. Must be unique and larger than 1000, as |
| 3924 | smaller values are reserved for auto-assigned ids. |
| 3925 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3926 | inter <delay> |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 3927 | fastinter <delay> |
| 3928 | downinter <delay> |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3929 | The "inter" parameter sets the interval between two consecutive health checks |
| 3930 | to <delay> milliseconds. If left unspecified, the delay defaults to 2000 ms. |
Krzysztof Piotr Oledzki | 5259dfe | 2008-01-21 01:54:06 +0100 | [diff] [blame] | 3931 | It is also possible to use "fastinter" and "downinter" to optimize delays |
Willy Tarreau | 41a340d | 2008-01-22 12:25:31 +0100 | [diff] [blame] | 3932 | between checks depending on the server state : |
| 3933 | |
| 3934 | Server state | Interval used |
| 3935 | ---------------------------------+----------------------------------------- |
| 3936 | UP 100% (non-transitional) | "inter" |
| 3937 | ---------------------------------+----------------------------------------- |
| 3938 | Transitionally UP (going down), | |
| 3939 | Transitionally DOWN (going up), | "fastinter" if set, "inter" otherwise. |
| 3940 | or yet unchecked. | |
| 3941 | ---------------------------------+----------------------------------------- |
| 3942 | DOWN 100% (non-transitional) | "downinter" if set, "inter" otherwise. |
| 3943 | ---------------------------------+----------------------------------------- |
| 3944 | |
| 3945 | Just as with every other time-based parameter, they can be entered in any |
| 3946 | other explicit unit among { us, ms, s, m, h, d }. The "inter" parameter also |
| 3947 | serves as a timeout for health checks sent to servers if "timeout check" is |
| 3948 | not set. In order to reduce "resonance" effects when multiple servers are |
| 3949 | hosted on the same hardware, the health-checks of all servers are started |
| 3950 | with a small time offset between them. It is also possible to add some random |
| 3951 | noise in the health checks interval using the global "spread-checks" |
| 3952 | keyword. This makes sense for instance when a lot of backends use the same |
| 3953 | servers. |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 3954 | |
| 3955 | maxconn <maxconn> |
| 3956 | The "maxconn" parameter specifies the maximal number of concurrent |
| 3957 | connections that will be sent to this server. If the number of incoming |
| 3958 | concurrent requests goes higher than this value, they will be queued, waiting |
| 3959 | for a connection to be released. This parameter is very important as it can |
| 3960 | save fragile servers from going down under extreme loads. If a "minconn" |
| 3961 | parameter is specified, the limit becomes dynamic. The default value is "0" |
| 3962 | which means unlimited. See also the "minconn" and "maxqueue" parameters, and |
| 3963 | the backend's "fullconn" keyword. |
| 3964 | |
| 3965 | maxqueue <maxqueue> |
| 3966 | The "maxqueue" parameter specifies the maximal number of connections which |
| 3967 | will wait in the queue for this server. If this limit is reached, next |
| 3968 | requests will be redispatched to other servers instead of indefinitely |
| 3969 | waiting to be served. This will break persistence but may allow people to |
| 3970 | quickly re-log in when the server they try to connect to is dying. The |
| 3971 | default value is "0" which means the queue is unlimited. See also the |
| 3972 | "maxconn" and "minconn" parameters. |
| 3973 | |
| 3974 | minconn <minconn> |
| 3975 | When the "minconn" parameter is set, the maxconn limit becomes a dynamic |
| 3976 | limit following the backend's load. The server will always accept at least |
| 3977 | <minconn> connections, never more than <maxconn>, and the limit will be on |
| 3978 | the ramp between both values when the backend has less than <fullconn> |
| 3979 | concurrent connections. This makes it possible to limit the load on the |
| 3980 | server during normal loads, but push it further for important loads without |
| 3981 | overloading the server during exceptionnal loads. See also the "maxconn" |
| 3982 | and "maxqueue" parameters, as well as the "fullconn" backend keyword. |
| 3983 | |
| 3984 | port <port> |
| 3985 | Using the "port" parameter, it becomes possible to use a different port to |
| 3986 | send health-checks. On some servers, it may be desirable to dedicate a port |
| 3987 | to a specific component able to perform complex tests which are more suitable |
| 3988 | to health-checks than the application. It is common to run a simple script in |
| 3989 | inetd for instance. This parameter is ignored if the "check" parameter is not |
| 3990 | set. See also the "addr" parameter. |
| 3991 | |
Willy Tarreau | 21d2af3 | 2008-02-14 20:25:24 +0100 | [diff] [blame] | 3992 | redir <prefix> |
| 3993 | The "redir" parameter enables the redirection mode for all GET and HEAD |
| 3994 | requests addressing this server. This means that instead of having HAProxy |
| 3995 | forward the request to the server, it will send an "HTTP 302" response with |
| 3996 | the "Location" header composed of this prefix immediately followed by the |
| 3997 | requested URI beginning at the leading '/' of the path component. That means |
| 3998 | that no trailing slash should be used after <prefix>. All invalid requests |
| 3999 | will be rejected, and all non-GET or HEAD requests will be normally served by |
| 4000 | the server. Note that since the response is completely forged, no header |
| 4001 | mangling nor cookie insertion is possible in the respose. However, cookies in |
| 4002 | requests are still analysed, making this solution completely usable to direct |
| 4003 | users to a remote location in case of local disaster. Main use consists in |
| 4004 | increasing bandwidth for static servers by having the clients directly |
| 4005 | connect to them. Note: never use a relative location here, it would cause a |
| 4006 | loop between the client and HAProxy! |
| 4007 | |
| 4008 | Example : server srv1 192.168.1.1:80 redir http://image1.mydomain.com check |
| 4009 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 4010 | rise <count> |
| 4011 | The "rise" parameter states that a server will be considered as operational |
| 4012 | after <count> consecutive successful health checks. This value defaults to 2 |
| 4013 | if unspecified. See also the "check", "inter" and "fall" parameters. |
| 4014 | |
Willy Tarreau | 5764b38 | 2007-11-30 17:46:49 +0100 | [diff] [blame] | 4015 | slowstart <start_time_in_ms> |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 4016 | The "slowstart" parameter for a server accepts a value in milliseconds which |
Willy Tarreau | 5764b38 | 2007-11-30 17:46:49 +0100 | [diff] [blame] | 4017 | indicates after how long a server which has just come back up will run at |
Willy Tarreau | befdff1 | 2007-12-02 22:27:38 +0100 | [diff] [blame] | 4018 | full speed. Just as with every other time-based parameter, it can be entered |
| 4019 | in any other explicit unit among { us, ms, s, m, h, d }. The speed grows |
| 4020 | linearly from 0 to 100% during this time. The limitation applies to two |
| 4021 | parameters : |
Willy Tarreau | 5764b38 | 2007-11-30 17:46:49 +0100 | [diff] [blame] | 4022 | |
| 4023 | - maxconn: the number of connections accepted by the server will grow from 1 |
| 4024 | to 100% of the usual dynamic limit defined by (minconn,maxconn,fullconn). |
| 4025 | |
| 4026 | - weight: when the backend uses a dynamic weighted algorithm, the weight |
| 4027 | grows linearly from 1 to 100%. In this case, the weight is updated at every |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 4028 | health-check. For this reason, it is important that the "inter" parameter |
| 4029 | is smaller than the "slowstart", in order to maximize the number of steps. |
Willy Tarreau | 5764b38 | 2007-11-30 17:46:49 +0100 | [diff] [blame] | 4030 | |
| 4031 | The slowstart never applies when haproxy starts, otherwise it would cause |
| 4032 | trouble to running servers. It only applies when a server has been previously |
| 4033 | seen as failed. |
| 4034 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 4035 | source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ] |
| 4036 | The "source" parameter sets the source address which will be used when |
| 4037 | connecting to the server. It follows the exact same parameters and principle |
| 4038 | as the backend "source" keyword, except that it only applies to the server |
| 4039 | referencing it. Please consult the "source" keyword for details. |
| 4040 | |
Krzysztof Piotr Oledzki | c8b16fc | 2008-02-18 01:26:35 +0100 | [diff] [blame] | 4041 | track [<proxy>/]<server> |
| 4042 | This option enables ability to set the current state of the server by |
| 4043 | tracking another one. Only a server with checks enabled can be tracked |
| 4044 | so it is not possible for example to track a server that tracks another |
| 4045 | one. If <proxy> is omitted the current one is used. If disable-on-404 is |
| 4046 | used, it has to be enabled on both proxies. |
| 4047 | |
Willy Tarreau | 198a744 | 2008-01-17 12:05:32 +0100 | [diff] [blame] | 4048 | weight <weight> |
| 4049 | The "weight" parameter is used to adjust the server's weight relative to |
| 4050 | other servers. All servers will receive a load proportional to their weight |
| 4051 | relative to the sum of all weights, so the higher the weight, the higher the |
| 4052 | load. The default weight is 1, and the maximal value is 255. If this |
| 4053 | parameter is used to distribute the load according to server's capacity, it |
| 4054 | is recommended to start with values which can both grow and shrink, for |
| 4055 | instance between 10 and 100 to leave enough room above and below for later |
| 4056 | adjustments. |
| 4057 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 4058 | |
| 4059 | 2.5) HTTP header manipulation |
| 4060 | ----------------------------- |
| 4061 | |
| 4062 | In HTTP mode, it is possible to rewrite, add or delete some of the request and |
| 4063 | response headers based on regular expressions. It is also possible to block a |
| 4064 | request or a response if a particular header matches a regular expression, |
| 4065 | which is enough to stop most elementary protocol attacks, and to protect |
| 4066 | against information leak from the internal network. But there is a limitation |
| 4067 | to this : since HAProxy's HTTP engine does not support keep-alive, only headers |
| 4068 | passed during the first request of a TCP session will be seen. All subsequent |
| 4069 | headers will be considered data only and not analyzed. Furthermore, HAProxy |
| 4070 | never touches data contents, it stops analysis at the end of headers. |
| 4071 | |
| 4072 | This section covers common usage of the following keywords, described in detail |
| 4073 | in section 2.2.1 : |
| 4074 | |
| 4075 | - reqadd <string> |
| 4076 | - reqallow <search> |
| 4077 | - reqiallow <search> |
| 4078 | - reqdel <search> |
| 4079 | - reqidel <search> |
| 4080 | - reqdeny <search> |
| 4081 | - reqideny <search> |
| 4082 | - reqpass <search> |
| 4083 | - reqipass <search> |
| 4084 | - reqrep <search> <replace> |
| 4085 | - reqirep <search> <replace> |
| 4086 | - reqtarpit <search> |
| 4087 | - reqitarpit <search> |
| 4088 | - rspadd <string> |
| 4089 | - rspdel <search> |
| 4090 | - rspidel <search> |
| 4091 | - rspdeny <search> |
| 4092 | - rspideny <search> |
| 4093 | - rsprep <search> <replace> |
| 4094 | - rspirep <search> <replace> |
| 4095 | |
| 4096 | With all these keywords, the same conventions are used. The <search> parameter |
| 4097 | is a POSIX extended regular expression (regex) which supports grouping through |
| 4098 | parenthesis (without the backslash). Spaces and other delimiters must be |
| 4099 | prefixed with a backslash ('\') to avoid confusion with a field delimiter. |
| 4100 | Other characters may be prefixed with a backslash to change their meaning : |
| 4101 | |
| 4102 | \t for a tab |
| 4103 | \r for a carriage return (CR) |
| 4104 | \n for a new line (LF) |
| 4105 | \ to mark a space and differentiate it from a delimiter |
| 4106 | \# to mark a sharp and differentiate it from a comment |
| 4107 | \\ to use a backslash in a regex |
| 4108 | \\\\ to use a backslash in the text (*2 for regex, *2 for haproxy) |
| 4109 | \xXX to write the ASCII hex code XX as in the C language |
| 4110 | |
| 4111 | The <replace> parameter contains the string to be used to replace the largest |
| 4112 | portion of text matching the regex. It can make use of the special characters |
| 4113 | above, and can reference a substring which is delimited by parenthesis in the |
| 4114 | regex, by writing a backslash ('\') immediately followed by one digit from 0 to |
Willy Tarreau | d2a4aa2 | 2008-01-31 15:28:22 +0100 | [diff] [blame] | 4115 | 9 indicating the group position (0 designating the entire line). This practice |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 4116 | is very common to users of the "sed" program. |
| 4117 | |
| 4118 | The <string> parameter represents the string which will systematically be added |
| 4119 | after the last header line. It can also use special character sequences above. |
| 4120 | |
| 4121 | Notes related to these keywords : |
| 4122 | --------------------------------- |
| 4123 | - these keywords are not always convenient to allow/deny based on header |
| 4124 | contents. It is strongly recommended to use ACLs with the "block" keyword |
| 4125 | instead, resulting in far more flexible and manageable rules. |
| 4126 | |
| 4127 | - lines are always considered as a whole. It is not possible to reference |
| 4128 | a header name only or a value only. This is important because of the way |
| 4129 | headers are written (notably the number of spaces after the colon). |
| 4130 | |
| 4131 | - the first line is always considered as a header, which makes it possible to |
| 4132 | rewrite or filter HTTP requests URIs or response codes, but in turn makes |
| 4133 | it harder to distinguish between headers and request line. The regex prefix |
| 4134 | ^[^\ \t]*[\ \t] matches any HTTP method followed by a space, and the prefix |
| 4135 | ^[^ \t:]*: matches any header name followed by a colon. |
| 4136 | |
| 4137 | - for performances reasons, the number of characters added to a request or to |
| 4138 | a response is limited at build time to values between 1 and 4 kB. This |
| 4139 | should normally be far more than enough for most usages. If it is too short |
| 4140 | on occasional usages, it is possible to gain some space by removing some |
| 4141 | useless headers before adding new ones. |
| 4142 | |
| 4143 | - keywords beginning with "reqi" and "rspi" are the same as their couterpart |
| 4144 | without the 'i' letter except that they ignore case when matching patterns. |
| 4145 | |
| 4146 | - when a request passes through a frontend then a backend, all req* rules |
| 4147 | from the frontend will be evaluated, then all req* rules from the backend |
| 4148 | will be evaluated. The reverse path is applied to responses. |
| 4149 | |
| 4150 | - req* statements are applied after "block" statements, so that "block" is |
| 4151 | always the first one, but before "use_backend" in order to permit rewriting |
| 4152 | before switching. |
| 4153 | |
Willy Tarreau | 5764b38 | 2007-11-30 17:46:49 +0100 | [diff] [blame] | 4154 | |
Willy Tarreau | ced2701 | 2008-01-17 20:35:34 +0100 | [diff] [blame] | 4155 | 2.6) Logging |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 4156 | ------------ |
| 4157 | |
| 4158 | [to do] |
| 4159 | |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 4160 | 2.7) CSV format |
| 4161 | |
| 4162 | 0. pxname: proxy name |
| 4163 | 1. svname: service name (FRONTEND for frontend, BACKEND for backend, any name |
| 4164 | for server) |
| 4165 | 2. qcur: current queued requests |
| 4166 | 3. qmax: max queued requests |
| 4167 | 4. scur: current sessions |
| 4168 | 5. smax: max sessions |
| 4169 | 6. slim: sessions limit |
| 4170 | 7. stot: total sessions |
| 4171 | 8. bin: bytes in |
| 4172 | 9. bout: bytes out |
| 4173 | 10. dreq: denied requests |
Krzysztof Piotr Oledzki | 2c6962c | 2008-03-02 02:42:14 +0100 | [diff] [blame] | 4174 | 11. dresp: denied responses |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 4175 | 12. ereq: request errors |
| 4176 | 13. econ: connection errors |
Krzysztof Piotr Oledzki | 2c6962c | 2008-03-02 02:42:14 +0100 | [diff] [blame] | 4177 | 14. eresp: response errors |
Krzysztof Piotr Oledzki | f58a962 | 2008-02-23 01:19:10 +0100 | [diff] [blame] | 4178 | 15. wretr: retries (warning) |
| 4179 | 16. wredis: redispatches (warning) |
| 4180 | 17. status: status (UP/DOWN/...) |
| 4181 | 18. weight: server weight (server), total weight (backend) |
| 4182 | 19. act: server is active (server), number of active servers (backend) |
| 4183 | 20. bck: server is backup (server), number of backup servers (backend) |
| 4184 | 21. chkfail: number of failed checks |
| 4185 | 22. chkdown: number of UP->DOWN transitions |
| 4186 | 23. lastchg: last status change (in seconds) |
| 4187 | 24. downtime: total downtime (in seconds) |
| 4188 | 25. qlimit: queue limit |
| 4189 | 26. pid: process id (0 for first instance, 1 for second, ...) |
| 4190 | 27. iid: unique proxy id |
| 4191 | 28. sid: service id (unique inside a proxy) |
| 4192 | 29. throttle: warm up status |
| 4193 | 30. lbtot: total number of times a server was selected |
| 4194 | 31. tracked: id of proxy/server if tracking is enabled |
| 4195 | 32. type (0=frontend, 1=backend, 2=server) |
Willy Tarreau | 844e3c5 | 2008-01-11 16:28:18 +0100 | [diff] [blame] | 4196 | |
Krzysztof Piotr Oledzki | 2c6962c | 2008-03-02 02:42:14 +0100 | [diff] [blame] | 4197 | 2.8) Unix Socket commands |
| 4198 | |
| 4199 | - "show stat [<iid> <type> <sid>]": dump statistics in the cvs format. By |
| 4200 | passing id, type and sid it is possible to dump only selected items: |
| 4201 | - iid is a proxy id, -1 to dump everything |
| 4202 | - type selects type of dumpable objects: 1 for frontend, 2 for backend, 4 for |
| 4203 | server, -1 for everything. Values can be ORed, for example: |
| 4204 | 1+2=3 -> frontend+backend. |
| 4205 | 1+2+4=7 -> frontend+backend+server. |
| 4206 | - sid is a service id, -1 to dump everything from the selected proxy. |
| 4207 | |
| 4208 | - "show info": dump info about current haproxy status. |
| 4209 | |
Willy Tarreau | 0ba2750 | 2007-12-24 16:55:16 +0100 | [diff] [blame] | 4210 | /* |
| 4211 | * Local variables: |
| 4212 | * fill-column: 79 |
| 4213 | * End: |
| 4214 | */ |