4. Proxies

  1. Proxy configuration can be located in a set of sections :
  2.  - defaults [<name>]
  3.  - frontend <name>
  4.  - backend  <name>
  5.  - listen   <name>
  6.  
  7. A "defaults" section sets default parameters for all other sections following
  8. its declaration. Those default parameters are reset by the next "defaults"
  9. section. See below for the list of parameters which can be set in a "defaults"
  10. section. The name is optional but its use is encouraged for better readability.
  11.  
  12. A "frontend" section describes a set of listening sockets accepting client
  13. connections.
  14.  
  15. A "backend" section describes a set of servers to which the proxy will connect
  16. to forward incoming connections.
  17.  
  18. A "listen" section defines a complete proxy with its frontend and backend
  19. parts combined in one section. It is generally useful for TCP-only traffic.
  20.  
  21. All proxy names must be formed from upper and lower case letters, digits,
  22. '-' (dash), '_' (underscore) , '.' (dot) and ':' (colon). ACL names are
  23. case-sensitive, which means that "www" and "WWW" are two different proxies.
  24.  
  25. Historically, all proxy names could overlap, it just caused troubles in the
  26. logs. Since the introduction of content switching, it is mandatory that two
  27. proxies with overlapping capabilities (frontend/backend) have different names.
  28. However, it is still permitted that a frontend and a backend share the same
  29. name, as this configuration seems to be commonly encountered.
  30.  
  31. Right now, two major proxy modes are supported : "tcp", also known as layer 4,
  32. and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards
  33. bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the
  34. protocol, and can interact with it by allowing, blocking, switching, adding,
  35. modifying, or removing arbitrary contents in requests or responses, based on
  36. arbitrary criteria.
  37.  
  38. In HTTP mode, the processing applied to requests and responses flowing over
  39. a connection depends in the combination of the frontend's HTTP options and
  40. the backend's. HAProxy supports 3 connection modes :
  41.  
  42.   - KAL : keep alive ("option http-keep-alive") which is the default mode : all
  43.     requests and responses are processed, and connections remain open but idle
  44.     between responses and new requests.
  45.  
  46.   - TUN: tunnel ("option http-tunnel") : this was the default mode for versions
  47.     1.0 to 1.5-dev21 : only the first request and response are processed, and
  48.     everything else is forwarded with no analysis at all. This mode should not
  49.     be used as it creates lots of trouble with logging and HTTP processing.
  50.     And because it cannot work in HTTP/2, this option is deprecated and it is
  51.     only supported on legacy HTTP frontends. In HTX, it is ignored and a
  52.     warning is emitted during HAProxy startup.
  53.  
  54.   - SCL: server close ("option http-server-close") : the server-facing
  55.     connection is closed after the end of the response is received, but the
  56.     client-facing connection remains open.
  57.  
  58.   - CLO: close ("option httpclose"): the connection is closed after the end of
  59.     the response and "Connection: close" appended in both directions.
  60.  
  61. The effective mode that will be applied to a connection passing through a
  62. frontend and a backend can be determined by both proxy modes according to the
  63. following matrix, but in short, the modes are symmetric, keep-alive is the
  64. weakest option and close is the strongest.
  65.  
  66.                    Backend mode
  67.  
  68.                 | KAL | SCL | CLO
  69.             ----+-----+-----+----
  70.             KAL | KAL | SCL | CLO
  71.             ----+-----+-----+----
  72.             TUN | TUN | SCL | CLO
  73.  Frontend   ----+-----+-----+----
  74.    mode     SCL | SCL | SCL | CLO
  75.             ----+-----+-----+----
  76.             CLO | CLO | CLO | CLO