Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 1 | ---------------------- |
| 2 | HAProxy |
| 3 | Configuration Manual |
| 4 | ---------------------- |
Alexandre Cassen | 87ea548 | 2007-10-11 20:48:58 +0200 | [diff] [blame^] | 5 | version 1.3.12.3 |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 6 | willy tarreau |
Alexandre Cassen | 87ea548 | 2007-10-11 20:48:58 +0200 | [diff] [blame^] | 7 | 2007/09/11 |
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 |
| 12 | docuemntation, please refer to the Reference Manual or the Architecture Manual. |
| 13 | |
| 14 | |
| 15 | HAProxy's configuration process involves 3 major sources of parameters : |
| 16 | |
| 17 | - the arguments from the command-line, which always take precedence |
| 18 | - the "global" section, which sets process-wide parameters |
| 19 | - the proxies sections which can take form of "defaults", "listen", |
| 20 | "frontend" and "backend". |
| 21 | |
| 22 | 1. Global parameters |
| 23 | -------------------- |
| 24 | |
| 25 | Parameters in the "global" section are process-wide and often OS-specific. They |
| 26 | are generally set once for all and do not need being changed once correct. Some |
| 27 | of them have command-line equivalents. |
| 28 | |
| 29 | The following keywords are supported in the "global" section : |
| 30 | |
| 31 | * Process management and security |
| 32 | - chroot |
| 33 | - daemon |
| 34 | - gid |
| 35 | - group |
| 36 | - log |
| 37 | - nbproc |
| 38 | - pidfile |
| 39 | - uid |
| 40 | - ulimit-n |
| 41 | - user |
| 42 | |
| 43 | * Performance tuning |
| 44 | - maxconn |
| 45 | - noepoll |
| 46 | - nokqueue |
| 47 | - nopoll |
| 48 | - nosepoll |
| 49 | - tune.maxpollevents |
| 50 | |
| 51 | * Debugging |
| 52 | - debug |
| 53 | - quiet |
| 54 | - stats |
| 55 | |
| 56 | |
| 57 | 1.1) Process management and security |
| 58 | ------------------------------------ |
| 59 | |
| 60 | chroot <jail dir> |
| 61 | Changes current directory to <jail dir> and performs a chroot() there before |
| 62 | dropping privileges. This increases the security level in case an unknown |
| 63 | vulnerability would be exploited, since it would make it very hard for the |
| 64 | attacker to exploit the system. This only works when the process is started |
| 65 | with superuser privileges. It is important to ensure that <jail_dir> is both |
| 66 | empty and unwritable to anyone. |
| 67 | |
| 68 | daemon |
| 69 | Makes the process fork into background. This is the recommended mode of |
| 70 | operation. It is equivalent to the command line "-D" argument. It can be |
| 71 | disabled by the command line "-db" argument. |
| 72 | |
| 73 | gid <number> |
| 74 | Changes the process' group ID to <number>. It is recommended that the group |
| 75 | ID is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 76 | be started with a user belonging to this group, or with superuser privileges. |
| 77 | See also "group" and "uid". |
| 78 | |
| 79 | group <group name> |
| 80 | Similar to "gid" but uses the GID of group name <group name> from /etc/group. |
| 81 | See also "gid" and "user". |
| 82 | |
| 83 | log <address> <facility> [max level] |
| 84 | Adds a global syslog server. Up to two global servers can be defined. They |
| 85 | will receive logs for startups and exits, as well as all logs from proxies |
| 86 | configured with "log global". <address> is an IPv4 address optionally |
| 87 | followed by a colon and an UDP port. If no port is specified, 514 is used |
| 88 | by default (the standard syslog port). <facility> must be one of the 24 |
| 89 | standard syslog facilities : |
| 90 | |
| 91 | kern user mail daemon auth syslog lpr news |
| 92 | uucp cron auth2 ftp ntp audit alert cron2 |
| 93 | local0 local1 local2 local3 local4 local5 local6 local7 |
| 94 | |
| 95 | An optional level can be specified to filter outgoing messages. By default, |
| 96 | all messages are sent. If a level is specified, only messages with a severity |
| 97 | at least as important as this level will be sent. 8 levels are known : |
| 98 | |
| 99 | emerg alert crit err warning notice info debug |
| 100 | |
| 101 | nbproc <number> |
| 102 | Creates <number> processes when going daemon. This requires the "daemon" |
| 103 | mode. By default, only one process is created, which is the recommended mode |
| 104 | of operation. For systems limited to small sets of file descriptors per |
| 105 | process, it may be needed to fork multiple daemons. USING MULTIPLE PROCESSES |
| 106 | IS HARDER TO DEBUG AND IS REALLY DISCOURAGED. See also "daemon". |
| 107 | |
| 108 | pidfile <pidfile> |
| 109 | Writes pids of all daemons into file <pidfile>. This option is equivalent to |
| 110 | the "-p" command line argument. The file must be accessible to the user |
| 111 | starting the process. See also "daemon". |
| 112 | |
| 113 | uid <number> |
| 114 | Changes the process' user ID to <number>. It is recommended that the user ID |
| 115 | is dedicated to HAProxy or to a small set of similar daemons. HAProxy must |
| 116 | be started with superuser privileges in order to be able to switch to another |
| 117 | one. See also "gid" and "user". |
| 118 | |
| 119 | ulimit-n <number> |
| 120 | Sets the maximum number of per-process file-descriptors to <number>. By |
| 121 | default, it is automatically computed, so it is recommended not to use this |
| 122 | option. |
| 123 | |
| 124 | user <user name> |
| 125 | Similar to "uid" but uses the UID of user name <user name> from /etc/passwd. |
| 126 | See also "uid" and "group". |
| 127 | |
| 128 | |
| 129 | 1.2) Performance tuning |
| 130 | ----------------------- |
| 131 | |
| 132 | maxconn <number> |
| 133 | Sets the maximum per-process number of concurrent connections to <number>. It |
| 134 | is equivalent to the command-line argument "-n". Proxies will stop accepting |
| 135 | connections when this limit is reached. The "ulimit-n" parameter is |
| 136 | automatically adjusted according to this value. See also "ulimit-n". |
| 137 | |
| 138 | noepoll |
| 139 | Disables the use of the "epoll" event polling system on Linux. It is |
| 140 | equivalent to the command-line argument "-de". The next polling system |
| 141 | used will generally be "poll". See also "nosepoll", and "nopoll". |
| 142 | |
| 143 | nokqueue |
| 144 | Disables the use of the "kqueue" event polling system on BSD. It is |
| 145 | equivalent to the command-line argument "-dk". The next polling system |
| 146 | used will generally be "poll". See also "nopoll". |
| 147 | |
| 148 | nopoll |
| 149 | Disables the use of the "poll" event polling system. It is equivalent to the |
| 150 | command-line argument "-dp". The next polling system used will be "select". |
| 151 | It should never be needed to didsable "poll" since it's available on all |
| 152 | platforms supported by HAProxy. See also "nosepoll", and "nopoll" and |
| 153 | "nokqueue". |
| 154 | |
| 155 | nosepoll |
| 156 | Disables the use of the "speculative epoll" event polling system on Linux. It |
| 157 | is equivalent to the command-line argument "-ds". The next polling system |
| 158 | used will generally be "epoll". See also "nosepoll", and "nopoll". |
| 159 | |
| 160 | tune.maxpollevents <number> |
| 161 | Sets the maximum amount of events that can be processed at once in a call to |
| 162 | the polling system. The default value is adapted to the operating system. It |
| 163 | has been noticed that reducing it below 200 tends to slightly decrease |
| 164 | latency at the expense of network bandwidth, and increasing it above 200 |
| 165 | tends to trade latency for slightly increased bandwidth. |
| 166 | |
| 167 | |
| 168 | 1.3) Debugging |
| 169 | --------------- |
| 170 | |
| 171 | debug |
| 172 | Enables debug mode which dumps to stdout all exchanges, and disables forking |
| 173 | into background. It is the equivalent of the command-line argument "-d". It |
| 174 | should never be used in a production configuration since it may prevent full |
| 175 | system startup. |
| 176 | |
| 177 | quiet |
| 178 | Do not display any message during startup. It is equivalent to the command- |
| 179 | line argument "-q". |
| 180 | |
| 181 | stats |
| 182 | Dump internal statistics to stdout at regular interval. It is available for |
| 183 | development purposes only and should never be set. |
| 184 | |
| 185 | |
| 186 | 2) Proxies |
| 187 | ---------- |
| 188 | Proxy configuration can be located in a set of sections : |
| 189 | - defaults <name> |
| 190 | - frontend <name> |
| 191 | - backend <name> |
| 192 | - listen <name> |
| 193 | |
| 194 | A "defaults" section sets default parameters for all other sections following |
| 195 | its declaration. Those default parameters are reset by the next "defaults" |
| 196 | section. See below for the list of parameters which can be set in a "defaults" |
| 197 | section. |
| 198 | |
| 199 | A "frontend" section describes a set of listening sockets accepting client |
| 200 | connections. |
| 201 | |
| 202 | A "backend" section describes a set of servers to which the proxy will connect |
| 203 | to forward incoming connections. |
| 204 | |
| 205 | A "listen" section defines a complete proxy with its frontend and backend |
| 206 | parts combined in one section. It is generally useful for TCP-only traffic. |
| 207 | |
| 208 | The following list of keywords is supported. Most of them may only be used in a |
| 209 | limited set of section types. |
| 210 | |
| 211 | keyword defaults frontend listen backend |
| 212 | ----------------------+----------+----------+---------+--------- |
| 213 | acl - X X X |
| 214 | appsession - - X X |
| 215 | balance - - X X |
| 216 | bind - X X - |
| 217 | block - X X X |
| 218 | capture cookie X X X X |
| 219 | capture request header X X X X |
| 220 | capture response header X X X X |
| 221 | clitimeout X X X - |
| 222 | contimeout X X X X |
| 223 | cookie X - X X |
| 224 | default_backend - X X - |
| 225 | disabled - X X X |
| 226 | dispatch - - X X |
| 227 | enabled - X X X |
| 228 | errorfile X X X X |
| 229 | errorloc X X X X |
| 230 | errorloc302 X X X X |
| 231 | errorloc303 X X X X |
| 232 | fullconn X - X X |
| 233 | grace - X X X |
| 234 | log X X X X |
| 235 | maxconn X X X - |
| 236 | mode X X X X |
| 237 | monitor-net X X X - |
| 238 | monitor-uri X X X - |
| 239 | option abortonclose X - X X |
| 240 | option allbackups X - X X |
| 241 | option checkcache X - X X |
| 242 | option clitcpka X X X - |
| 243 | option dontlognull X X X - |
| 244 | option forceclose X - X X |
| 245 | option forwardfor X X X X |
| 246 | option httpchk X - X X |
| 247 | option httpclose X X X X |
| 248 | option httplog X X X X |
| 249 | option logasap X X X - |
Alexandre Cassen | 87ea548 | 2007-10-11 20:48:58 +0200 | [diff] [blame^] | 250 | option nolinger X X X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 251 | option persist X - X X |
| 252 | option redispatch X - X X |
| 253 | option smtpchk X - X X |
| 254 | option srvtcpka X - X X |
| 255 | option ssl-hello-chk X - X X |
| 256 | option tcpka X X X X |
| 257 | option tcplog X X X X |
| 258 | option tcpsplice X X X X |
| 259 | option transparent X X X - |
| 260 | redisp X - X X |
| 261 | redispatch X - X X |
| 262 | reqadd - X X X |
| 263 | reqallow - X X X |
| 264 | reqdel - X X X |
| 265 | reqdeny - X X X |
| 266 | reqiallow - X X X |
| 267 | reqidel - X X X |
| 268 | reqideny - X X X |
| 269 | reqipass - X X X |
| 270 | reqirep - X X X |
| 271 | reqisetbe - X X X |
| 272 | reqitarpit - X X X |
| 273 | reqpass - X X X |
| 274 | reqrep - X X X |
| 275 | reqsetbe - X X X |
| 276 | reqtarpit - X X X |
| 277 | retries X - X X |
| 278 | rspadd - X X X |
| 279 | rspdel - X X X |
| 280 | rspdeny - X X X |
| 281 | rspidel - X X X |
| 282 | rspideny - X X X |
| 283 | rspirep - X X X |
| 284 | rsprep - X X X |
| 285 | server - - X X |
| 286 | source X - X X |
| 287 | srvtimeout X - X X |
Willy Tarreau | 24e779b | 2007-07-24 23:43:37 +0200 | [diff] [blame] | 288 | stats auth X - X X |
| 289 | stats enable X - X X |
| 290 | stats realm X - X X |
Willy Tarreau | bbd4212 | 2007-07-25 07:26:38 +0200 | [diff] [blame] | 291 | stats refresh X - X X |
Willy Tarreau | 24e779b | 2007-07-24 23:43:37 +0200 | [diff] [blame] | 292 | stats scope X - X X |
| 293 | stats uri X - X X |
Willy Tarreau | 6a06a40 | 2007-07-15 20:15:28 +0200 | [diff] [blame] | 294 | transparent X X X - |
| 295 | use_backend - X X - |
| 296 | usesrc X - X X |
| 297 | ----------------------+----------+----------+---------+--------- |
| 298 | keyword defaults frontend listen backend |
| 299 | |
| 300 | |
| 301 | 2.1) using ACLs |
| 302 | --------------- |
| 303 | |
| 304 | The use of Access Control Lists (ACL) provides a flexible solution to perform |
| 305 | content switching. The principle is simple : |
| 306 | |
| 307 | - define test criteria with sets of values |
| 308 | - perform actions only if a set of tests is valid |
| 309 | |
| 310 | The actions generally consist in blocking the request, or selecting a backend. |
| 311 | |
| 312 | In order to define a test, the "acl" keyword is used. The syntax is : |
| 313 | |
| 314 | acl <aclname> <criterion> [flags] [operator] <value> ... |
| 315 | |
| 316 | This creates an ACL <aclname> or completes an existing one with new |
| 317 | tests. Those tests apply to the portion of request specified in <criterion> |
| 318 | and may be adjusted with optional flags [flags]. Some criteria also support |
| 319 | an operator which may be specified before the set of values. The values are |
| 320 | of the type supported by the criterion, and are separated by spaces. |
| 321 | |
| 322 | There is no limit to the number of ACLs. The unused ones do not affect |
| 323 | performance, they just consume a small amount of memory. |
| 324 | |
| 325 | The current flags are currently supported : |
| 326 | |
| 327 | -i : ignore case during matching. |
| 328 | -- : force end of flags. Useful when a string looks like one of the flags. |
| 329 | |
| 330 | Supported types of values are : |
| 331 | - integers or integer ranges |
| 332 | - strings |
| 333 | - regular expressions |
| 334 | - IP addresses and networks |
| 335 | |
| 336 | |
| 337 | 2.1.1) Matching integers |
| 338 | ------------------------ |
| 339 | |
| 340 | Matching integers is special in that ranges and operators are permitted. Note |
| 341 | that integer matching only applies to positive values. A range is a value |
| 342 | expressed with a lower and an upper bound separated with a colon, both of which |
| 343 | may be omitted. |
| 344 | |
| 345 | For instance, "1024:65535" is a valid range to represent a range of |
| 346 | unprivileged ports, and "1024:" would also work. "0:1023" is a valid |
| 347 | representation of privileged ports, and ":1023" would also work. |
| 348 | |
| 349 | For an easier usage, comparison operators are also supported. Note that using |
| 350 | operators with ranges does not make much sense and is discouraged. Also, it |
| 351 | does not make much sense to perform order comparisons with a set of values. |
| 352 | |
| 353 | Available operators are : |
| 354 | |
| 355 | eq : true if the tested value equals at least one value |
| 356 | ge : true if the tested value is greater than or equal to at least one value |
| 357 | gt : true if the tested value is greater than at least one value |
| 358 | le : true if the tested value is less than or equal to at least one value |
| 359 | lt : true if the tested value is less than at least one value |
| 360 | |
| 361 | For instance, the following ACL matches negative Content-Length headers : |
| 362 | |
| 363 | acl negative-length hdr_val(content-length) lt 0 |
| 364 | |
| 365 | |
| 366 | 2.1.2) Matching strings |
| 367 | ----------------------- |
| 368 | |
| 369 | String matching applies to verbatim strings as they are passed, with the |
| 370 | exception of the backslash ("\") which makes it possible to escape some |
| 371 | characters such as the space. If the "-i" flag is passed before the first |
| 372 | string, then the matching will be performed ignoring the case. In order |
| 373 | to match the string "-i", either set it second, or pass the "--" flag |
| 374 | before the first string. |
| 375 | |
| 376 | |
| 377 | 2.1.3) Matching regular expressions (regexes) |
| 378 | --------------------------------------------- |
| 379 | |
| 380 | Just like with string matching, regex matching applies to verbatim strings as |
| 381 | they are passed, with the exception of the backslash ("\") which makes it |
| 382 | possible to escape some characters such as the space. If the "-i" flag is |
| 383 | passed before the first regex, then the matching will be performed ignoring |
| 384 | the case. In order to match the string "-i", either set it second, or pass |
| 385 | the "--" flag before the first string. |
| 386 | |
| 387 | |
| 388 | 2.1.4) Matching IPv4 addresses |
| 389 | ---------------------------- |
| 390 | |
| 391 | IPv4 addresses values can be specified either as plain addresses or with a |
| 392 | netmask appended, in which case the IPv4 address matches whenever it is |
| 393 | within the network. Plain addresses may also be replaced with a resolvable |
| 394 | host name, but this practise is generally discouraged as it makes it more |
| 395 | difficult to read configurations. |
| 396 | |
| 397 | |
| 398 | 2.1.5) Available matching criteria |
| 399 | ---------------------------------- |
| 400 | |
| 401 | always_false |
| 402 | This one never matches. All values and flags are ignored. It may be used as |
| 403 | a temporary replacement for another one when adjusting configurations. |
| 404 | |
| 405 | always_true |
| 406 | This one always matches. All values and flags are ignored. It may be used as |
| 407 | a temporary replacement for another one when adjusting configurations. |
| 408 | |
| 409 | src <ip_address> |
| 410 | Applies to the client's IP address. It is usually used to limit access to |
| 411 | certain resources such as statistics. Note that it is the TCP-level source |
| 412 | address which is used, and not the address of a client behind a proxy. |
| 413 | |
| 414 | src_port <integer> |
| 415 | Applies to the client's TCP source port. This has a very limited usage. |
| 416 | |
| 417 | dst <ip_address> |
| 418 | Applies to the local IP address the client connected to. It can be used to |
| 419 | switch to a different backend for some alternative addresses. |
| 420 | |
| 421 | dst_port <integer> |
| 422 | Applies to the local port the client connected to. It can be used to switch |
| 423 | to a different backend for some alternative ports. |
| 424 | |
| 425 | dst_conn <integer> |
| 426 | Applies to the number of currently established connections on the frontend, |
| 427 | including the one being evaluated. It can be used to either return a sorry |
| 428 | page before hard-blocking, or to use a specific backend to drain the requests |
| 429 | when the farm is considered saturated. |
| 430 | |
| 431 | method <string> |
| 432 | Applies to the method in the HTTP request, eg: "GET". Some predefined ACL |
| 433 | already check for most common methods. |
| 434 | |
| 435 | req_ver <string> |
| 436 | Applies to the version string in the HTTP request, eg: "1.0". Some predefined |
| 437 | ACL already check for versions 1.0 and 1.1. |
| 438 | |
| 439 | path <string> |
| 440 | Returns true when the path part of the request, which starts at the first |
| 441 | slash and ends before the question mark, equals one of the strings. It may be |
| 442 | used to match known files, such as /favicon.ico. |
| 443 | |
| 444 | path_beg <string> |
| 445 | Returns true when the path begins with one of the strings. This can be used to |
| 446 | send certain directory names to alternative backends. |
| 447 | |
| 448 | path_end <string> |
| 449 | Returns true when the path ends with one of the strings. This may be used to |
| 450 | control file name extension. |
| 451 | |
| 452 | path_sub <string> |
| 453 | Returns true when the path contains one of the strings. It can be used to |
| 454 | detect particular patterns in paths, such as "../" for example. See also |
| 455 | "path_dir". |
| 456 | |
| 457 | path_dir <string> |
| 458 | Returns true when one of the strings is found isolated or delimited with |
| 459 | slashes in the path. This is used to perform filename or directory name |
| 460 | matching without the risk of wrong match due to colliding prefixes. See also |
| 461 | "url_dir" and "path_sub". |
| 462 | |
| 463 | path_dom <string> |
| 464 | Returns true when one of the strings is found isolated or delimited with dots |
| 465 | in the path. This may be used to perform domain name matching in proxy |
| 466 | requests. See also "path_sub" and "url_dom". |
| 467 | |
| 468 | path_reg <regex> |
| 469 | Returns true when the path matches one of the regular expressions. It can be |
| 470 | used any time, but it is important to remember that regex matching is slower |
| 471 | than other methods. See also "url_reg" and all "path_" criteria. |
| 472 | |
| 473 | url <string> |
| 474 | Applies to the whole URL passed in the request. The only real use is to match |
| 475 | "*", for which there already is a predefined ACL. |
| 476 | |
| 477 | url_beg <string> |
| 478 | Returns true when the URL begins with one of the strings. This can be used to |
| 479 | check whether a URL begins with a slash or with a protocol scheme. |
| 480 | |
| 481 | url_end <string> |
| 482 | Returns true when the URL ends with one of the strings. It has very limited |
| 483 | use. "path_end" should be used instead for filename matching. |
| 484 | |
| 485 | url_sub <string> |
| 486 | Returns true when the URL contains one of the strings. It can be used to |
| 487 | detect particular patterns in query strings for example. See also "path_sub". |
| 488 | |
| 489 | url_dir <string> |
| 490 | Returns true when one of the strings is found isolated or delimited with |
| 491 | slashes in the URL. This is used to perform filename or directory name |
| 492 | matching without the risk of wrong match due to colliding prefixes. See also |
| 493 | "path_dir" and "url_sub". |
| 494 | |
| 495 | url_dom <string> |
| 496 | Returns true when one of the strings is found isolated or delimited with dots |
| 497 | in the URL. This is used to perform domain name matching without the risk of |
| 498 | wrong match due to colliding prefixes. See also "url_sub". |
| 499 | |
| 500 | url_reg <regex> |
| 501 | Returns true when the URL matches one of the regular expressions. It can be |
| 502 | used any time, but it is important to remember that regex matching is slower |
| 503 | than other methods. See also "path_reg" and all "url_" criteria. |
| 504 | |
| 505 | hdr <string> |
| 506 | hdr(header) <string> |
| 507 | Note: all the "hdr*" matching criteria either apply to all headers, or to a |
| 508 | particular header whose name is passed between parenthesis and without any |
| 509 | space. The header matching complies with RFC2616, and treats as separate |
| 510 | headers all values delimited by comas. |
| 511 | |
| 512 | The "hdr" criteria returns true if any of the headers matching the criteria |
| 513 | match any of the strings. This can be used to check exact values. For |
| 514 | instance, checking that "connection: close" is set : |
| 515 | |
| 516 | hdr(Connection) -i close |
| 517 | |
| 518 | hdr_beg <string> |
| 519 | hdr_beg(header) <string> |
| 520 | Returns true when one of the headers begins with one of the strings. See |
| 521 | "hdr" for more information on header matching. |
| 522 | |
| 523 | hdr_end <string> |
| 524 | hdr_end(header) <string> |
| 525 | Returns true when one of the headers ends with one of the strings. See "hdr" |
| 526 | for more information on header matching. |
| 527 | |
| 528 | hdr_sub <string> |
| 529 | hdr_sub(header) <string> |
| 530 | Returns true when one of the headers contains one of the strings. See "hdr" |
| 531 | for more information on header matching. |
| 532 | |
| 533 | hdr_dir <string> |
| 534 | hdr_dir(header) <string> |
| 535 | Returns true when one of the headers contains one of the strings either |
| 536 | isolated or delimited by slashes. This is used to perform filename or |
| 537 | directory name matching, and may be used with Referer. See "hdr" for more |
| 538 | information on header matching. |
| 539 | |
| 540 | hdr_dom <string> |
| 541 | hdr_dom(header) <string> |
| 542 | Returns true when one of the headers contains one of the strings either |
| 543 | isolated or delimited by dots. This is used to perform domain name matching, |
| 544 | and may be used with the Host header. See "hdr" for more information on |
| 545 | header matching. |
| 546 | |
| 547 | hdr_reg <regex> |
| 548 | hdr_reg(header) <regex> |
| 549 | Returns true when one of the headers matches of the regular expressions. It |
| 550 | can be used at any time, but it is important to remember that regex matching |
| 551 | is slower than other methods. See also other "hdr_" criteria, as well as |
| 552 | "hdr" for more information on header matching. |
| 553 | |
| 554 | hdr_val <integer> |
| 555 | hdr_val(header) <integer> |
| 556 | Returns true when one of the headers starts with a number which matches the |
| 557 | values or ranges specified. This may be used to limit content-length to |
| 558 | acceptable values for example. See "hdr" for more information on header |
| 559 | matching. |
| 560 | |
| 561 | hdr_cnt <integer> |
| 562 | hdr_cnt(header) <integer> |
| 563 | Returns true when the count of the headers which matches the values or ranges |
| 564 | specified. This is used to detect presence or absence of a specific header, |
| 565 | as well as to block request smugling attacks by rejecting requests which |
| 566 | contain more than one of certain headers. See "hdr" for more information on |
| 567 | header matching. |
| 568 | |
| 569 | |
| 570 | 2.1.6) Pre-defined ACLs |
| 571 | ----------------------- |
| 572 | |
| 573 | Some predefined ACLs are hard-coded so that they do not have to be declared in |
| 574 | every frontend which needs them. They all have their names in upper case in |
| 575 | order to avoid confusion. Their equivalence is provided below : |
| 576 | |
| 577 | ACL name Equivalent to Usage |
| 578 | ---------------+-----------------------------+--------------------------------- |
| 579 | TRUE always_true 1 always match |
| 580 | FALSE always_false 0 never match |
| 581 | LOCALHOST src 127.0.0.1/8 match connection from local host |
| 582 | HTTP_1.0 req_ver 1.0 match HTTP version 1.0 |
| 583 | HTTP_1.1 req_ver 1.1 match HTTP version 1.1 |
| 584 | METH_CONNECT method CONNECT match HTTP CONNECT method |
| 585 | METH_GET method GET HEAD match HTTP GET or HEAD method |
| 586 | METH_HEAD method HEAD match HTTP HEAD method |
| 587 | METH_OPTIONS method OPTIONS match HTTP OPTIONS method |
| 588 | METH_POST method POST match HTTP POST method |
| 589 | METH_TRACE method TRACE match HTTP TRACE method |
| 590 | HTTP_URL_ABS url_reg ^[^/:]*:// match absolute URL with scheme |
| 591 | HTTP_URL_SLASH url_beg / match URL begining with "/" |
| 592 | HTTP_URL_STAR url * match URL equal to "*" |
| 593 | HTTP_CONTENT hdr_val(content-length) gt 0 match an existing content-length |
| 594 | ---------------+-----------------------------+--------------------------------- |
| 595 | |
| 596 | |
| 597 | 2.1.7) Using ACLs to form conditions |
| 598 | ------------------------------------ |
| 599 | |
| 600 | Some actions are only performed upon a valid condition. A condition is a |
| 601 | combination of ACLs with operators. 3 operators are supported : |
| 602 | |
| 603 | - AND (implicit) |
| 604 | - OR (explicit with the "or" keyword or the "||" operator) |
| 605 | - Negation with the exclamation mark ("!") |
| 606 | |
| 607 | A condition is formed as a disjonctive form : |
| 608 | |
| 609 | [!]acl1 [!]acl2 ... [!]acln { or [!]acl1 [!]acl2 ... [!]acln } ... |
| 610 | |
| 611 | Such conditions are generally used after an "if" or "unless" statement, |
| 612 | indicating when the condition will trigger the action. |
| 613 | |
| 614 | For instance, to block HTTP requests to the "*" URL with methods other than |
| 615 | "OPTIONS", as well as POST requests without content-length, and GET/HEAD |
| 616 | requests with a content-length greater than 0, and finally every request |
| 617 | which is not either GET/HEAD/POST/OPTIONS ! |
| 618 | |
| 619 | acl missing_cl hdr_cnt(Content-length) eq 0 |
| 620 | block if HTTP_URL_STAR !METH_OPTIONS || METH_POST missing_cl |
| 621 | block if METH_GET HTTP_CONTENT |
| 622 | block unless METH_GET or METH_POST or METH_OPTIONS |
| 623 | |
| 624 | To select a different backend for requests to static contents on the "www" site |
| 625 | and to every request on the "img", "video", "download" and "ftp" hosts : |
| 626 | |
| 627 | acl url_static path_beg /static /images /img /css |
| 628 | acl url_static path_end .gif .png .jpg .css .js |
| 629 | acl host_www hdr_beg(host) -i www |
| 630 | acl host_static hdr_beg(host) -i img. video. download. ftp. |
| 631 | |
| 632 | # now use backend "static" for all static-only hosts, and for static urls |
| 633 | # of host "www". Use backend "www" for the rest. |
| 634 | use_backend static if host_static or host_www url_static |
| 635 | use_backend www if host_www |
| 636 | |
| 637 | See below for the detailed help on the "block" and "use_backend" keywords. |