--- title: "4. Proxies" linkTitle: "4. Proxies" weight: 150 description: "Defaults, frontends, backends, listeners, proxy keywords, and action references" icon: fa-solid fa-right-left module: [HAPROXY] categories: [Reference] aliases: - /haproxy/configuration/proxies/ - /docs/haproxy/configuration/proxies/ - /haproxy/proxies/ upstream_link: "https://docs.haproxy.org/3.4/configuration.html" upstream_name: "HAProxy 3.4 Configuration Manual" upstream_ref: "v3.4.4, chapter 4" --- Proxy configuration can be located in a set of sections: - defaults [``] [ from `` ] - frontend `` [ from `` ] - backend `` [ from `` ] - listen `` [ from `` ] A "frontend" section describes a set of listening sockets accepting client connections. A "backend" section describes a set of servers to which the proxy will connect to forward incoming connections. A "listen" section defines a complete proxy with its frontend and backend parts combined in one section. It is generally useful for TCP-only traffic. A "defaults" section resets all settings to the documented ones and presets new ones for use by subsequent sections. All of "frontend", "backend" and "listen" sections always take their initial settings from a defaults section, by default the latest one that appears before the newly created section. It is possible to explicitly designate a specific "defaults" section to load the initial settings from by indicating its name on the section line after the optional keyword "from". While "defaults" section do not impose a name, this use is encouraged for better readability. It is also the only way to designate a specific section to use instead of the default previous one. Since "defaults" section names are optional, by default a very permissive check is applied on their name and these are even permitted to overlap. However if a "defaults" section is referenced by any other section, its name must comply with the syntax imposed on all proxy names, and this name must be unique among the defaults sections. Please note that regardless of what is currently permitted, it is recommended to avoid duplicate section names in general and to respect the same syntax as for proxy names. This rule might be enforced in a future version. In addition, a warning is emitted if a defaults section is explicitly used by a proxy while it is also implicitly used by another one because it is the last one defined. It is highly encouraged to not mix both usages by always using explicit references or by adding a last common defaults section reserved for all implicit uses. Note that it is even possible for a defaults section to take its initial settings from another one, and as such, inherit settings across multiple levels of defaults sections. This can be convenient to establish certain configuration profiles to carry groups of default settings (e.g. TCP vs HTTP or short vs long timeouts) but can quickly become confusing to follow. By default, named defaults sections are preserved after configuration parsing. This allows to reuse them for dynamic backends creation. This behavior can be changed globally via "tune.defaults.purge" keyword. All proxy names must be formed from upper and lower case letters, digits, '-' (dash), '\_' (underscore) , '.' (dot) and ':' (colon). ACL names are case-sensitive, which means that "www" and "WWW" are two different proxies. Historically, all proxy names could overlap when certain conditions were met (e.g. when not having the same frontend/backend capabilities), but it used to cause too many problems in the logs as well as confusion on CLI operations, stick-tables naming and stats retrieval. It is now mandatory that two proxies have different names, regardless of their respective capabilities. Right now, two major proxy modes are supported: "tcp", also known as layer 4, and "http", also known as layer 7. In layer 4 mode, HAProxy simply forwards bidirectional traffic between two sides. In layer 7 mode, HAProxy analyzes the protocol, and can interact with it by allowing, blocking, switching, adding, modifying, or removing arbitrary contents in requests or responses, based on arbitrary criteria. In HTTP mode, the processing applied to requests and responses flowing over a connection depends in the combination of the frontend's HTTP options and the backend's. HAProxy supports 3 connection modes: - KAL: keep alive ("option http-keep-alive") which is the default mode: all requests and responses are processed, and connections remain open but idle between responses and new requests. - SCL: server close ("option http-server-close"): the server-facing connection is closed after the end of the response is received, but the client-facing connection remains open. - CLO: close ("option httpclose"): the connection is closed after the end of the response and "Connection: close" appended in both directions. The effective mode that will be applied to a connection passing through a frontend and a backend can be determined by both proxy modes according to the following matrix, but in short, the modes are symmetric, keep-alive is the weakest option and close is the strongest. Backend mode ```text | KAL | SCL | CLO ----+-----+-----+---- KAL | KAL | SCL | CLO ----+-----+-----+---- mode SCL | SCL | SCL | CLO ----+-----+-----+---- CLO | CLO | CLO | CLO ``` It is possible to chain a TCP frontend to an HTTP backend. It is pointless if only HTTP traffic is handled. But it may be used to handle several protocols within the same frontend. In this case, the client's connection is first handled as a raw tcp connection before being upgraded to HTTP. Before the upgrade, the content processings are performed on raw data. Once upgraded, data is parsed and stored using an internal representation called HTX and it is no longer possible to rely on raw representation. There is no way to go back. There are two kind of upgrades, in-place upgrades and destructive upgrades. The first ones involves a TCP to HTTP/1 upgrade. In HTTP/1, the request processings are serialized, thus the applicative stream can be preserved. The second one involves a TCP to HTTP/2 upgrade. Because it is a multiplexed protocol, the applicative stream cannot be associated to any HTTP/2 stream and is destroyed. New applicative streams are then created when HAProxy receives new HTTP/2 streams at the lower level, in the H2 multiplexer. It is important to understand this difference because that drastically changes the way to process data. When an HTTP/1 upgrade is performed, the content processings already performed on raw data are neither lost nor reexecuted while for an HTTP/2 upgrade, applicative streams are distinct and all frontend rules are evaluated systematically on each one. And as said, the first stream, the TCP one, is destroyed, but only after the frontend rules were evaluated. There is another important point to understand when HTTP processings are performed from a TCP proxy. While HAProxy is able to parse HTTP/1 in-fly from tcp-request content rules, it is not possible for HTTP/2. Only the HTTP/2 preface can be parsed. This is a huge limitation regarding the HTTP content analysis in TCP. Concretely it is only possible to know if received data are HTTP. For instance, it is not possible to choose a backend based on the Host header value while it is trivial in HTTP/1. Hopefully, there is a solution to mitigate this drawback. There are two ways to perform an HTTP upgrade. The first one, the historical method, is to select an HTTP backend. The upgrade happens when the backend is set. Thus, for in-place upgrades, only the backend configuration is considered in the HTTP data processing. For destructive upgrades, the applicative stream is destroyed, thus its processing is stopped. With this method, possibilities to choose a backend with an HTTP/2 connection are really limited, as mentioned above, and a bit useless because the stream is destroyed. The second method is to upgrade during the tcp-request content rules evaluation, thanks to the "switch-mode http" action. In this case, the upgrade is performed in the frontend context and it is possible to define HTTP directives in this frontend. For in-place upgrades, it offers all the power of the HTTP analysis as soon as possible. It is not that far from an HTTP frontend. For destructive upgrades, it does not change anything except it is useless to choose a backend on limited information. It is of course the recommended method. Thus, testing the request protocol from the tcp-request content rules to perform an HTTP upgrade is enough. All the remaining HTTP manipulation may be moved to the frontend http-request ruleset. But keep in mind that tcp-request content rules remains evaluated on each streams, that can't be changed. ## 4.1. Proxy keywords matrix {#section-4-1} The following list of keywords is supported. Most of them may only be used in a limited set of section types. Some of them are marked as "deprecated" because they are inherited from an old syntax which may be confusing or functionally limited, and there are new recommended keywords to replace them. Keywords marked with "(\*)" can be optionally inverted using the "no" prefix, e.g. "no option contstats". This makes sense when the option has been enabled by default and must be disabled for a specific instance. Such options may also be prefixed with "default" in order to restore default settings regardless of what has been specified in a previous "defaults" section. Keywords supported in defaults sections marked with "(!)" are only supported in named defaults sections, not anonymous ones. Note: Some dangerous and not recommended directives are intentionnaly not listed in the following matrix. It is on purpose. These directives are documentated. But by not listing them below is one more way to discourage anyone to use it. ```text keyword defaults frontend listen backend ------------------------------------+----------+----------+---------+--------- acl X (!) X X X backlog X X X - balance X - X X be-unpublished - - X X bind - X X - capture cookie - X X - capture request header - X X - capture response header - X X - clitcpka-cnt X X X - clitcpka-idle X X X - clitcpka-intvl X X X - compression X X X X cookie X - X X crt - X X - declare capture - X X - default-server X - X X default_backend X X X - description - X X X disabled X X X X dispatch (deprecated) - - X X email-alert from X X X X email-alert level X X X X email-alert mailers X X X X email-alert myhostname X X X X email-alert to X X X X enabled X X X X errorfile X X X X errorfiles X X X X errorloc X X X X errorloc302 X X X X -- keyword -------------------------- defaults - frontend - listen -- backend - errorloc303 X X X X error-log-format X X X - external-check command X - X X external-check path X - X X force-persist - - X X force-be-switch - X X - filter - X X X filter-sequence - X X X fullconn X - X X guid - X X X hash-balance-factor X - X X hash-preserve-affinity X - X X hash-type X - X X http-after-response X (!) X X X http-check comment X - X X http-check connect X - X X http-check disable-on-404 X - X X http-check expect X - X X http-check send X - X X http-check send-state X - X X http-check set-var X - X X http-check unset-var X - X X http-error X X X X http-request X (!) X X X http-response X (!) X X X http-reuse X - X X http-send-name-header X - X X id - X X X ignore-persist - - X X load-server-state-from-file X - X X log (*) X X X X log-format X X X - log-format-sd X X X - log-tag X X X X log-steps X X X - max-keep-alive-queue X - X X max-session-srv-conns X X X - maxconn X X X - mode X X X X monitor fail - X X - monitor-uri X X X - option abortonclose (*) X X X X option allbackups (*) X - X X option checkcache (*) X - X X option clitcpka (*) X X X - option contstats (*) X X X - option disable-h2-upgrade (*) X X X - option dontlog-normal (*) X X X - option dontlognull (*) X X X - -- keyword -------------------------- defaults - frontend - listen -- backend - option external-check X - X X option forwardfor X X X X option forwarded (*) X - X X option h1-case-adjust-bogus-client (*) X X X - option h1-case-adjust-bogus-server (*) X - X X option http-buffer-request (*) X X X X option http-drop-request-trailers (*) X - - X option http-drop-response-trailers (*) X - X - option http-ignore-probes (*) X X X - option http-keep-alive (*) X X X X option http-no-delay (*) X X X X option http-pretend-keepalive (*) X - X X option http-restrict-req-hdr-names X X X X option http-server-close (*) X X X X option http-use-proxy-header (*) X X X - option httpchk X - X X option httpclose (*) X X X X option httplog X X X - option httpslog X X X - option idle-close-on-response (*) X X X - option independent-streams (*) X X X X option ldap-check X - X X option log-health-checks (*) X - X X option log-separate-errors (*) X X X - option logasap (*) X X X - option mysql-check X - X X option nolinger (*) X X X X option originalto X X X X option persist (*) X - X X option pgsql-check X - X X option prefer-last-server (*) X - X X option redispatch (*) X - X X option redis-check X - X X option smtpchk X - X X option socket-stats (*) X X X - option splice-auto (*) X X X X option splice-request (*) X X X X option splice-response (*) X X X X option spop-check X - X X option srvtcpka (*) X - X X option ssl-hello-chk X - X X -- keyword -------------------------- defaults - frontend - listen -- backend - option tcp-check X - X X option tcp-smart-accept (*) X X X - option tcp-smart-connect (*) X - X X option tcpka X X X X option tcplog X X X - option transparent (deprecated) (*) X - X X option use-small-buffers (*) X - X X persist rdp-cookie X - X X quic-initial X (!) X X - rate-limit sessions X X X - redirect - X X X -- keyword -------------------------- defaults - frontend - listen -- backend - retries X - X X retry-on X - X X server - - X X server-state-file-name X - X X server-template - - X X source X - X X srvtcpka-cnt X - X X srvtcpka-idle X - X X srvtcpka-intvl X - X X stats admin - X X X stats auth X X X X stats enable X X X X stats hide-version X X X X stats http-request - X X X stats realm X X X X stats refresh X X X X stats scope X X X X stats show-desc X X X X stats show-legends X X X X stats show-node X X X X stats show-version X X X X stats uri X X X X -- keyword -------------------------- defaults - frontend - listen -- backend - stick match - - X X stick on - - X X stick store-request - - X X stick store-response - - X X stick-table - X X X tcp-check comment X - X X tcp-check connect X - X X tcp-check expect X - X X tcp-check send X - X X tcp-check send-lf X - X X tcp-check send-binary X - X X tcp-check send-binary-lf X - X X tcp-check set-var X - X X tcp-check unset-var X - X X tcp-request connection X (!) X X - tcp-request content X (!) X X X tcp-request inspect-delay X (!) X X X tcp-request session X (!) X X - tcp-response content X (!) - X X tcp-response inspect-delay X (!) - X X timeout check X - X X timeout client X X X - timeout client-fin X X X - timeout client-hs X X X - timeout connect X - X X timeout http-keep-alive X X X X timeout http-request X X X X timeout queue X - X X timeout server X - X X timeout server-fin X - X X timeout tarpit X X X X timeout tunnel X - X X transparent (deprecated) X - X X unique-id-format X X X X unique-id-header X X X - use_backend - X X - use-fcgi-app - - X X use-server - - X X ------------------------------------+----------+----------+---------+--------- keyword defaults frontend listen backend ``` ## 4.2. Alphabetically sorted keywords reference {#section-4-2} This section provides a description of each keyword and its usage. **`acl [flags] [operator] ...`** ```haproxy acl [flags] [operator] ... ``` Declare or complete an access list. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes This directive is only available from named defaults sections, not anonymous ones. ACLs defined in a defaults section are not visible from other sections using it. Example: ```text acl invalid_src src 0.0.0.0/7 224.0.0.0/3 acl invalid_src src_port 0:1023 acl local_dst hdr(host) -i localhost ``` See [section 7](/docs/haproxy/acls-and-samples/) about ACL usage. **`backlog `** ```haproxy backlog ``` Give hints to the system about the approximate listen backlog desired size May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text is the number of pending connections. Depending on the operating system, it may represent the number of already acknowledged connections, of non-acknowledged ones, or both. ``` This option is only meaningful for stream listeners, including QUIC ones. Its behavior however is not identical with QUIC instances. For all listeners but QUIC, in order to protect against SYN flood attacks, one solution is to increase the system's SYN backlog size. Depending on the system, sometimes it is just tunable via a system parameter, sometimes it is not adjustable at all, and sometimes the system relies on hints given by the application at the time of the listen() syscall. By default, HAProxy passes the frontend's maxconn value to the listen() syscall. On systems which can make use of this value, it can sometimes be useful to be able to specify a different value, hence this backlog parameter. On Linux 2.4, the parameter is ignored by the system. On Linux 2.6, it is used as a hint and the system accepts up to the smallest greater power of two, and never more than some limits (usually 32768). For QUIC listeners, backlog sets a shared limits for both the maximum count of active handshakes and connections waiting to be accepted. The handshake phase relies primarily of the network latency with the remote peer, whereas the second phase depends solely on haproxy load. When either one of this limit is reached, haproxy starts to drop reception of INITIAL packets, preventing any new connection allocation, until the connection excess starts to decrease. This situation may cause browsers to silently downgrade the HTTP versions and switching to TCP. See also: "maxconn" and the target operating system's tuning guide. **`balance [ ]`** ```haproxy balance [ ] balance url_param [check_post] ``` Define the load balancing algorithm to be used in a backend. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the algorithm used to select a server when doing load balancing. This only applies when no persistence information is available, or when a connection is redispatched to another server. may be one of the following: roundrobin Each server is used in turns, according to their weights. This is the smoothest and fairest algorithm when the server's processing time remains equally distributed. This algorithm is dynamic, which means that server weights may be adjusted on the fly for slow starts for instance. It is limited by design to 4095 active servers per backend. Note that in some large farms, when a server becomes up after having been down for a very short time, it may sometimes take a few hundreds requests for it to be re-integrated into the farm and start receiving traffic. This is normal, though very rare. It is indicated here in case you would have the chance to observe it, so that you don't worry. Note: weights are ignored for backends in LOG mode. static-rr Each server is used in turns, according to their weights. This algorithm is as similar to roundrobin except that it is static, which means that changing a server's weight on the fly will have no effect. On the other hand, it has no design limitation on the number of servers, and when a server goes up, it is always immediately reintroduced into the farm, once the full map is recomputed. It also uses slightly less CPU to run (around -1%). This algorithm is not usable in LOG mode. leastconn The server with the lowest number of connections receives the connection. Round-robin is performed within groups of servers of the same load to ensure that all servers will be used. Use of this algorithm is recommended where very long sessions are expected, such as LDAP, SQL, TSE, etc... but is not very well suited for protocols using short sessions such as HTTP. This algorithm is dynamic, which means that server weights may be adjusted on the fly for slow starts for instance. It will also consider the number of queued connections in addition to the established ones in order to minimize queuing. This algorithm is not usable in LOG mode. first The first server with available connection slots receives the connection. The servers are chosen from the lowest numeric identifier to the highest (see server parameter "id"), which defaults to the server's position in the farm. Once a server reaches its maxconn value, the next server is used. It does not make sense to use this algorithm without setting maxconn. The purpose of this algorithm is to always use the smallest number of servers so that extra servers can be powered off during non-intensive hours. This algorithm ignores the server weight, and brings more benefit to long session such as RDP or IMAP than HTTP, though it can be useful there too. In order to use this algorithm efficiently, it is recommended that a cloud controller regularly checks server usage to turn them off when unused, and regularly checks backend queue to turn new servers on when the queue inflates. Alternatively, using "http-check send-state" may inform servers on the load. This algorithm is not usable in LOG mode. hash Takes a regular sample expression in argument. The expression is evaluated for each request and hashed according to the configured hash-type. The result of the hash is divided by the total weight of the running servers to designate which server will receive the request. This can be used in place of "source", "uri", "hdr()", "url_param()", "rdp-cookie" to make use of a converter, refine the evaluation, or be used to extract data from local variables for example. When the data is not available, round robin will apply. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". This algorithm is not usable for backends in LOG mode, please use "log-hash" instead. source The source IP address is hashed and divided by the total weight of the running servers to designate which server will receive the request. This ensures that the same client IP address will always reach the same server as long as no server goes down or up. If the hash result changes due to the number of running servers changing, many clients will be directed to a different server. This algorithm is generally used in TCP mode where no cookie may be inserted. It may also be used on the Internet to provide a best-effort stickiness to clients which refuse session cookies. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". See also the "hash" option above. This algorithm is not usable for backends in LOG mode. uri This algorithm hashes either the left part of the URI (before the question mark) or the whole URI (if the "whole" parameter is present) and divides the hash value by the total weight of the running servers. The result designates which server will receive the request. This ensures that the same URI will always be directed to the same server as long as no server goes up or down. This is used with proxy caches and anti-virus proxies in order to maximize the cache hit rate. Note that this algorithm may only be used in an HTTP backend. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". This algorithm supports two optional parameters "len" and "depth", both followed by a positive integer number. These options may be helpful when it is needed to balance servers based on the beginning of the URI only. The "len" parameter indicates that the algorithm should only consider that many characters at the beginning of the URI to compute the hash. Note that having "len" set to 1 rarely makes sense since most URIs start with a leading "/". The "depth" parameter indicates the maximum directory depth to be used to compute the hash. One level is counted for each slash in the request. If both parameters are specified, the evaluation stops when either is reached. A "path-only" parameter indicates that the hashing key starts at the first '/' of the path. This can be used to ignore the authority part of absolute URIs, and to make sure that HTTP/1 and HTTP/2 URIs will provide the same hash. See also the "hash" option above. url_param The URL parameter specified in argument will be looked up in the query string of each HTTP GET request. If the modifier "check_post" is used, then an HTTP POST request entity will be searched for the parameter argument, when it is not found in a query string after a question mark ('?') in the URL. The message body will only start to be analyzed once either the advertised amount of data has been received or the request buffer is full. In the unlikely event that chunked encoding is used, only the first chunk is scanned. Parameter values separated by a chunk boundary, may be randomly balanced if at all. This keyword used to support an optional parameter which is now ignored. If the parameter is found followed by an equal sign ('=') and a value, then the value is hashed and divided by the total weight of the running servers. The result designates which server will receive the request. This is used to track user identifiers in requests and ensure that a same user ID will always be sent to the same server as long as no server goes up or down. If no value is found or if the parameter is not found, then a round robin algorithm is applied. Note that this algorithm may only be used in an HTTP backend. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". See also the "hash" option above. hdr() The HTTP header will be looked up in each HTTP request. Just as with the equivalent ACL 'hdr()' function, the header name in parenthesis is not case sensitive. If the header is absent or if it does not contain any value, the roundrobin algorithm is applied instead. An optional 'use_domain_only' parameter is available, for reducing the hash algorithm to the main domain part with some specific headers such as 'Host'. For instance, in the Host value "haproxy.1wt.eu", only "1wt" will be considered. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". See also the "hash" option above. random random() A random number will be used as the key for the consistent hashing function. This means that the servers' weights are respected, dynamic weight changes immediately take effect, as well as new server additions. Random load balancing can be useful with large farms or when servers are frequently added or removed as it may avoid the hammering effect that could result from roundrobin or leastconn in this situation. The hash-balance-factor directive can be used to further improve fairness of the load balancing, especially in situations where servers show highly variable response times. When an argument is present, it must be an integer value one or greater, indicating the number of draws before selecting the least loaded of these servers. It was indeed demonstrated that picking the least loaded of two servers is enough to significantly improve the fairness of the algorithm, by always avoiding to pick the most loaded server within a farm and getting rid of any bias that could be induced by the unfair distribution of the consistent list. Higher values N will take away N-1 of the highest loaded servers at the expense of performance. With very high values, the algorithm will converge towards the leastconn's result but much slower. In addition, for large server farms with very low loads (or perfect balance), comparing loads will often lead to a tie, so in case of equal loads between all measured servers, their request rate over the last second are compared, which allows to better balance server usage over time in the same spirit as roundrobin does, and smooth consistent hash unfairness. The default value is 2, which generally shows very good distribution and performance. For large farms with low loads (less than a few requests per second per server), it may help to raise it to 3 or even 4. This algorithm is also known as the Power of Two Random Choices and is described here: http://www.eecs.harvard.edu/~michaelm/postscripts/handbook2001.pdf For backends in LOG mode, the number of draws is ignored and a single random is picked since there is no notion of server load. Random log balancing can be useful with large farms or when servers are frequently added or removed from the pool of available servers as it may avoid the hammering effect that could result from roundrobin in this situation. rdp-cookie rdp-cookie() The RDP cookie (or "mstshash" if omitted) will be looked up and hashed for each incoming TCP request. Just as with the equivalent ACL 'req.rdp_cookie()' function, the name is not case-sensitive. This mechanism is useful as a degraded persistence mode, as it makes it possible to always send the same user (or the same session ID) to the same server. If the cookie is not found, the normal roundrobin algorithm is used instead. Note that for this to work, the frontend must ensure that an RDP cookie is already present in the request buffer. For this you must use 'tcp-request content accept' rule combined with a 'req.rdp_cookie_cnt' ACL. This algorithm is static by default, which means that changing a server's weight on the fly will have no effect, but this can be changed using "hash-type". See also the "hash" option above. log-hash Takes a comma-delimited list of converters in argument. These converters are applied in sequence to the input log message, and the result will be cast as a string then hashed according to the configured hash-type. The resulting hash will be used to select the destination server among the ones declared in the log backend. The goal of this algorithm is to be able to extract a key within the final log message using string converters and then be able to stick to the same server thanks to the hash. Only "map-based" hashes are supported for now. This algorithm is only usable for backends in LOG mode, for others, please use "hash" instead. sticky Tries to stick to the same server as much as possible. The first server in the list of available servers receives all the log messages. When the server goes DOWN, the next server in the list takes its place. When a previously DOWN server goes back UP it is added at the end of the list so that the sticky server doesn't change until it becomes DOWN. is an optional list of arguments which may be needed by some algorithms. Right now, only "url_param", "uri" and "log-hash" support an optional argument. ``` The load balancing algorithm of a backend is set to "random" when no other algorithm, mode nor option have been set. The algorithm may only be set once for each backend. With authentication schemes that require the same connection like NTLM, URI based algorithms must not be used, as they would cause subsequent requests to be routed to different backend servers, breaking the invalid assumptions NTLM relies on. TCP/HTTP Examples: ```text balance roundrobin balance url_param userid balance url_param session_id check_post 64 balance hdr(User-Agent) balance hdr(host) balance hdr(Host) use_domain_only balance hash req.cookie(clientid) balance hash var(req.client_id) balance hash req.hdr_ip(x-forwarded-for,-1),ipmask(24) ``` LOG backend examples: ```text global log backend@mylog-rrb local0 # send all logs to mylog-rrb backend log backend@mylog-hash local0 # send all logs to mylog-hash backend backend mylog-rrb mode log balance roundrobin server s1 udp@127.0.0.1:514 # will receive 50% of log messages server s2 udp@127.0.0.1:514 backend mylog-hash mode log # extract "METHOD URL PROTO" at the end of the log message, # and let haproxy hash it so that log messages generated from # similar requests get sent to the same syslog server: balance log-hash 'field(-2,\")' # server list here server s1 127.0.0.1:514 #... ``` Note: the following caveats and limitations on using the "check_post" extension with "url_param" must be considered: - all POST requests are eligible for consideration, because there is no way to determine if the parameters will be found in the body or entity which may contain binary data. Therefore another method may be required to restrict consideration of POST requests that have no URL parameters in the body. (see acl http_end) - using a `` value larger than the request buffer size does not make sense and is useless. The buffer size is set at build time, and defaults to 16 kB. - Content-Encoding is not supported, the parameter search will probably fail; and load balancing will fall back to Round Robin. - Expect: 100-continue is not supported, load balancing will fall back to Round Robin. - Transfer-Encoding (RFC7230 3.3.1) is only supported in the first chunk. If the entire parameter value is not present in the first chunk, the selection of server is undefined (actually, defined by how little actually appeared in the first chunk). - This feature does not support generation of a 100, 411 or 501 response. - In some cases, requesting "check_post" MAY attempt to scan the entire contents of a message body. Scanning normally terminates when linear white space or control characters are found, indicating the end of what might be a URL parameter list. This is probably not a concern with SGML type message bodies. See also: "dispatch", "cookie", "transparent", "hash-type". **`be-unpublished`** ```haproxy be-unpublished ``` Instructs the backend to start in the unpublished state. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend no \| no \| yes \| yes In effect, any use_backend and default_backend rules from another proxy which reference the current proxy are ignored and the next content switching rules are evaluated. This can be bypassed though via a "force-be-switch" rule. This state is similar to the disabled one but with some differences. First, an unpublished backend will still be fully initialized, including the server health checks which remain active. Finally, a backend can be publicly exposed via the command "publish backend" on the CLI. See the management manual. See also: "force-be-switch" **`bind [
]: [, ...] [param*]`** ```haproxy bind [
]: [, ...] [param*] bind / [, ...] [param*] ``` Define one or several listening addresses and/or ports in a frontend. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| no Arguments: ```text
is optional and can be a host name, an IPv4 address, an IPv6 address, or '*'. It designates the address the frontend will listen on. If unset, all IPv4 addresses of the system will be listened on. The same will apply for '*' or the system's special address "0.0.0.0". The IPv6 equivalent is '::'. Note that for UDP, specific OS features are required when binding on multiple addresses to ensure the correct network interface and source address will be used on response. In other way, for QUIC listeners only bind on multiple addresses if running with a modern enough systems. Optionally, an address family prefix may be used before the address to force the family regardless of the address format, which can be useful to specify a path to a unix socket with no slash ('/'). Currently supported prefixes are: - 'ipv4@' -> address is always IPv4 - 'ipv6@' -> address is always IPv6 - 'udp@' -> address is resolved as IPv4 or IPv6 and protocol UDP is used. Currently those listeners are supported only in log-forward sections. - 'udp4@' -> address is always IPv4 and protocol UDP is used. Currently those listeners are supported only in log-forward sections. - 'udp6@' -> address is always IPv6 and protocol UDP is used. Currently those listeners are supported only in log-forward sections. - 'unix@' -> address is a path to a local unix socket - 'abns@' -> address is in abstract namespace (Linux only). - 'abnsz@' -> address is in abstract namespace (Linux only) but it is explicitly zero-terminated. This means no \0 padding is used to complete sun_path. It is useful to interconnect with programs that don't implement the default abns naming logic that haproxy uses. - 'fd@' -> use file descriptor inherited from the parent. The fd must be bound and may or may not already be listening. - 'sockpair@'-> like fd@ but you must use the fd of a connected unix socket or of a socketpair. The bind waits to receive a FD over the unix socket and uses it as if it was the FD of an accept(). Should be used carefully. - 'quic4@' -> address is resolved as IPv4 and protocol UDP is used. Note that to achieve the best performance with a large traffic you should keep "tune.quic.fe.sock-per-conn default-on". Else QUIC connections will be multiplexed over the listener socket. Another alternative would be to duplicate QUIC listener instances over several threads, for example using "shards" keyword to at least reduce thread contention. - 'quic6@' -> address is resolved as IPv6 and protocol UDP is used. The performance note for QUIC over IPv4 applies as well. - 'rhttp@' [ EXPERIMENTAL ] -> used for reverse HTTP. Address must be a server with the format '/'. The server will be used to instantiate connections to a remote address. The listener will try to maintain "nbconn" connections. This is an experimental features which requires "expose-experimental-directives" on a line before this bind. You may want to reference some environment variables in the address parameter, see section 2.3 about environment variables. is either a unique TCP port, or a port range for which the proxy will accept connections for the IP address specified above. The port is mandatory for TCP listeners. Note that in the case of an IPv6 address, the port is always the number after the last colon (':'). A range can either be: - a numerical port (ex: '80') - a dash-delimited ports range explicitly stating the lower and upper bounds (ex: '2000-2100') which are included in the range. Particular care must be taken against port ranges, because every couple consumes one socket (= a file descriptor), so it's easy to consume lots of descriptors with a simple range, and to run out of sockets. Also, each couple must be used only once among all instances running on a same system. Please note that binding to ports lower than 1024 generally require particular privileges to start the program, which are independent of the 'uid' parameter. is a UNIX socket path beginning with a slash ('/'). This is alternative to the TCP listening port. HAProxy will then receive UNIX connections on the socket located at this place. The path must begin with a slash and by default is absolute. It can be relative to the prefix defined by "unix-bind" in the global section. Note that the total length of the prefix followed by the socket path cannot exceed some system limits for UNIX sockets, which commonly are set to 107 characters. is a list of parameters common to all sockets declared on the same line. These numerous parameters depend on OS and build options and have a complete section dedicated to them. Please refer to section 5 to for more details. ``` It is possible to specify a list of address:port combinations delimited by commas. The frontend will then listen on all of these addresses. There is no fixed limit to the number of addresses and ports which can be listened on in a frontend, as well as there is no limit to the number of "bind" statements in a frontend. Example: ```text listen http_proxy bind:80,:443 bind 10.0.0.1:10080,10.0.0.1:10443 bind /var/run/ssl-frontend.sock user root mode 600 accept-proxy listen http_https_proxy bind:80 bind:443 ssl crt /etc/haproxy/site.pem listen http_https_proxy_explicit bind ipv6@:80 bind ipv4@public_ssl:443 ssl crt /etc/haproxy/site.pem bind unix@ssl-frontend.sock user root mode 600 accept-proxy listen external_bind_app1 bind "fd@${FD_APP1}" listen h3_quic_proxy bind quic4@10.0.0.1:8888 ssl crt /etc/mycrt ``` Note: regarding Linux's abstract namespace sockets, "abns" HAProxy sockets uses the whole sun_path length is used for the address length. Some other programs such as socat use the string length only by default. Pass the option ",unix-tightsocklen=0" to any abstract socket definition in socat to make it compatible with HAProxy's, or use the "abnsz" HAProxy socket family instead. See also: "source", "option forwardfor", "unix-bind" and the PROXY protocol documentation, and [section 5](/docs/haproxy/bind-and-server-options/) about bind options. **`capture cookie len `** ```haproxy capture cookie len ``` Capture and log a cookie in the request and in the response. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| no Arguments: ```text is the beginning of the name of the cookie to capture. In order to match the exact name, simply suffix the name with an equal sign ('='). The full name will appear in the logs, which is useful with application servers which adjust both the cookie name and value (e.g. ASPSESSIONXXX). is the maximum number of characters to report in the logs, which include the cookie name, the equal sign and the value, all in the standard "name=value" form. The string will be truncated on the right if it exceeds . ``` Only the first cookie is captured. Both the "cookie" request headers and the "set-cookie" response headers are monitored. This is particularly useful to check for application bugs causing session crossing or stealing between users, because generally the user's cookies can only change on a login page. When the cookie was not presented by the client, the associated log column will report "-". When a request does not cause a cookie to be assigned by the server, a "-" is reported in the response column. The capture is performed in the frontend only because it is necessary that the log format does not change for a given frontend depending on the backends. This may change in the future. Note that there can be only one "capture cookie" statement in a frontend. The maximum capture length is set by the global "tune.http.cookielen" setting and defaults to 63 characters. It is not possible to specify a capture in a "defaults" section. Example: ```text capture cookie ASPSESSION len 32 ``` See also: "capture request header", "capture response header" as well as [section 8](/docs/haproxy/configuration-logging/) about logging. **`capture request header len `** ```haproxy capture request header len ``` Capture and log the last occurrence of the specified request header. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| no Arguments: ```text is the name of the header to capture. The header names are not case-sensitive, but it is a common practice to write them as they appear in the requests, with the first letter of each word in upper case. The header name will not appear in the logs, only the value is reported, but the position in the logs is respected. is the maximum number of characters to extract from the value and report in the logs. The string will be truncated on the right if it exceeds . ``` The complete value of the last occurrence of the header is captured. The value will be added to the logs between braces ('{}'). If multiple headers are captured, they will be delimited by a vertical bar ('\|') and will appear in the same order they were declared in the configuration. Non-existent headers will be logged just as an empty string. Common uses for request header captures include the "Host" field in virtual hosting environments, the "Content-length" when uploads are supported, "User-agent" to quickly differentiate between real users and robots, and "X-Forwarded-For" in proxied environments to find where the request came from. Note that when capturing headers such as "User-agent", some spaces may be logged, making the log analysis more difficult. Thus be careful about what you log if you know your log parser is not smart enough to rely on the braces. There is no limit to the number of captured request headers nor to their length, though it is wise to keep them low to limit memory usage per stream. In order to keep log format consistent for a same frontend, header captures can only be declared in a frontend. It is not possible to specify a capture in a "defaults" section. Example: ```text capture request header Host len 15 capture request header X-Forwarded-For len 15 capture request header Referer len 15 ``` See also: "capture cookie", "capture response header" as well as [section 8](/docs/haproxy/configuration-logging/) about logging. **`capture response header len `** ```haproxy capture response header len ``` Capture and log the last occurrence of the specified response header. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| no Arguments: ```text is the name of the header to capture. The header names are not case-sensitive, but it is a common practice to write them as they appear in the response, with the first letter of each word in upper case. The header name will not appear in the logs, only the value is reported, but the position in the logs is respected. is the maximum number of characters to extract from the value and report in the logs. The string will be truncated on the right if it exceeds . ``` The complete value of the last occurrence of the header is captured. The result will be added to the logs between braces ('{}') after the captured request headers. If multiple headers are captured, they will be delimited by a vertical bar ('\|') and will appear in the same order they were declared in the configuration. Non-existent headers will be logged just as an empty string. Common uses for response header captures include the "Content-length" header which indicates how many bytes are expected to be returned, the "Location" header to track redirections. There is no limit to the number of captured response headers nor to their length, though it is wise to keep them low to limit memory usage per stream. In order to keep log format consistent for a same frontend, header captures can only be declared in a frontend. It is not possible to specify a capture in a "defaults" section. Example: ```text capture response header Content-length len 9 capture response header Location len 15 ``` See also: "capture cookie", "capture request header" as well as [section 8](/docs/haproxy/configuration-logging/) about logging. **`clitcpka-cnt `** ```haproxy clitcpka-cnt ``` Sets the maximum number of keepalive probes TCP should send before dropping the connection on the client side. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text is the maximum number of keepalive probes. ``` This keyword corresponds to the socket option TCP_KEEPCNT. If this keyword is not specified, system-wide TCP parameter (tcp_keepalive_probes) is used. The availability of this setting depends on the operating system. It is known to work on Linux. See also: "option clitcpka", "clitcpka-idle", "clitcpka-intvl". **`clitcpka-idle `** ```haproxy clitcpka-idle ``` Sets the time the connection needs to remain idle before TCP starts sending keepalive probes, if enabled the sending of TCP keepalive packets on the client side. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text is the time the connection needs to remain idle before TCP starts sending keepalive probes. It is specified in seconds by default, but can be in any other unit if the number is suffixed by the unit, as explained at the top of this document. ``` This keyword corresponds to the socket option TCP_KEEPIDLE. If this keyword is not specified, system-wide TCP parameter (tcp_keepalive_time) is used. The availability of this setting depends on the operating system. It is known to work on Linux. See also: "option clitcpka", "clitcpka-cnt", "clitcpka-intvl". **`clitcpka-intvl `** ```haproxy clitcpka-intvl ``` Sets the time between individual keepalive probes on the client side. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text is the time between individual keepalive probes. It is specified in seconds by default, but can be in any other unit if the number is suffixed by the unit, as explained at the top of this document. ``` This keyword corresponds to the socket option TCP_KEEPINTVL. If this keyword is not specified, system-wide TCP parameter (tcp_keepalive_intvl) is used. The availability of this setting depends on the operating system. It is known to work on Linux. See also: "option clitcpka", "clitcpka-cnt", "clitcpka-idle". **`compression algo ...`** ```haproxy compression algo ... compression algo-req compression algo-res compression type ... ``` Enable HTTP compression. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text algo is followed by the list of supported compression algorithms for responses (legacy keyword) algo-req is followed by compression algorithm for request (only one is provided). algo-res is followed by the list of supported compression algorithms for responses. type is followed by the list of MIME types that will be compressed for responses (legacy keyword). type-req is followed by the list of MIME types that will be compressed for requests. type-res is followed by the list of MIME types that will be compressed for responses. ``` The currently supported algorithms are: ```text identity this is mostly for debugging, and it was useful for developing the compression feature. Identity does not apply any change on data. gzip applies gzip compression. This setting is only available when support for zlib or libslz was built in. deflate same as "gzip", but with deflate algorithm and zlib format. Note that this algorithm has ambiguous support on many browsers and no support at all from recent ones. It is strongly recommended not to use it for anything else than experimentation. This setting is only available when support for zlib or libslz was built in. raw-deflate same as "deflate" without the zlib wrapper, and used as an alternative when the browser wants "deflate". All major browsers understand it and despite violating the standards, it is known to work better than "deflate", at least on MSIE and some versions of Safari. Do not use it in conjunction with "deflate", use either one or the other since both react to the same Accept-Encoding token. This setting is only available when support for zlib or libslz was built in. ``` Compression will be activated depending on the Accept-Encoding request header. With identity, it does not take care of that header. If backend servers support HTTP compression, these directives will be no-op: HAProxy will see the compressed response and will not compress again. If backend servers do not support HTTP compression and there is Accept-Encoding header in request, HAProxy will compress the matching response. Compression is disabled when: \* the request does not advertise a supported compression algorithm in the "Accept-Encoding" header \* the response message is not HTTP/1.1 or above \* HTTP status code is not one of 200, 201, 202, or 203 \* response contain neither a "Content-Length" header nor a "Transfer-Encoding" whose last value is "chunked" \* response contains a "Content-Type" header whose first value starts with "multipart" \* the response contains the "no-transform" value in the "Cache-control" header \* User-Agent matches "Mozilla/4" unless it is MSIE 6 with XP SP2, or MSIE 7 and later \* The response contains a "Content-Encoding" header, indicating that the response is already compressed (see compression offload) \* The response contains an invalid "ETag" header or multiple ETag headers \* The payload size is smaller than the minimum size (see compression minsize-res) Note: The compression does not emit the Warning header. Examples: ```text compression algo gzip compression type text/html text/plain ``` See also: "compression offload", "compression direction", "compression minsize-req" and "compression minsize-res" **`compression minsize-req `** ```haproxy compression minsize-req compression minsize-res ``` Sets the minimum payload size in bytes for compression to be applied. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Payloads smaller than this size will not be compressed, avoiding unnecessary CPU overhead for data that would not significantly benefit from compression. "minsize-req" applies on requests and "minsize-res" on responses. The default value is 0. **`compression offload`** ```haproxy compression offload ``` Makes HAProxy work as a compression offloader only. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| yes The "offload" setting makes HAProxy remove the Accept-Encoding header to prevent backend servers from compressing responses. It is strongly recommended not to do this because this means that all the compression work will be done on the single point where HAProxy is located. However in some deployment scenarios, HAProxy may be installed in front of a buggy gateway with broken HTTP compression implementation which can't be turned off. In that case HAProxy can be used to prevent that gateway from emitting invalid payloads. In this case, simply removing the header in the configuration does not work because it applies before the header is parsed, so that prevents HAProxy from compressing. The "offload" setting should then be used for such scenarios. If this setting is used in a defaults section, a warning is emitted and the option is ignored. See also: "compression type", "compression algo", "compression direction" **`compression direction (deprecated)`** ```haproxy compression direction (deprecated) ``` Makes haproxy able to compress both requests and responses. Valid values are "request", to compress only requests, "response", to compress only responses, or "both", when you want to compress both. The default value is "response". This directive is only relevant when legacy "filter compression" was enabled, as with explicit comp-req and comp-res filters compression direction is redundant. May be used in the following contexts: http See also: "compression type", "compression algo", "compression offload" **`cookie [ rewrite | insert | prefix ] [ indirect ] [ nocache ]`** ```haproxy cookie [ rewrite | insert | prefix ] [ indirect ] [ nocache ] [ postonly ] [ preserve ] [ httponly ] [ secure ] [ domain ]* [ maxidle ] [ maxlife ] [ dynamic ] [ attr ]* ``` Enable cookie-based persistence in a backend. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the name of the cookie which will be monitored, modified or inserted in order to bring persistence. This cookie is sent to the client via a "Set-Cookie" header in the response, and is brought back by the client in a "Cookie" header in all requests. Special care should be taken to choose a name which does not conflict with any likely application cookie. Also, if the same backends are subject to be used by the same clients (e.g. HTTP/HTTPS), care should be taken to use different cookie names between all backends if persistence between them is not desired. rewrite This keyword indicates that the cookie will be provided by the server and that HAProxy will have to modify its value to set the server's identifier in it. This mode is handy when the management of complex combinations of "Set-cookie" and "Cache-control" headers is left to the application. The application can then decide whether or not it is appropriate to emit a persistence cookie. Since all responses should be monitored, this mode doesn't work in HTTP tunnel mode. Unless the application behavior is very complex and/or broken, it is advised not to start with this mode for new deployments. This keyword is incompatible with "insert" and "prefix". insert This keyword indicates that the persistence cookie will have to be inserted by HAProxy in server responses if the client did not already have a cookie that would have permitted it to access this server. When used without the "preserve" option, if the server emits a cookie with the same name, it will be removed before processing. For this reason, this mode can be used to upgrade existing configurations running in the "rewrite" mode. The cookie will only be a session cookie and will not be stored on the client's disk. By default, unless the "indirect" option is added, the server will see the cookies emitted by the client. Due to caching effects, it is generally wise to add the "nocache" or "postonly" keywords (see below). The "insert" keyword is not compatible with "rewrite" and "prefix". prefix This keyword indicates that instead of relying on a dedicated cookie for the persistence, an existing one will be completed. This may be needed in some specific environments where the client does not support more than one single cookie and the application already needs it. In this case, whenever the server sets a cookie named , it will be prefixed with the server's identifier and a delimiter. The prefix will be removed from all client requests so that the server still finds the cookie it emitted. Since all requests and responses are subject to being modified, this mode doesn't work with tunnel mode. The "prefix" keyword is not compatible with "rewrite" and "insert". Note: it is highly recommended not to use "indirect" with "prefix", otherwise server cookie updates would not be sent to clients. indirect When this option is specified, no cookie will be emitted to a client which already has a valid one for the server which has processed the request. If the server sets such a cookie itself, it will be removed, unless the "preserve" option is also set. In "insert" mode, this will additionally remove cookies from the requests transmitted to the server, making the persistence mechanism totally transparent from an application point of view. Note: it is highly recommended not to use "indirect" with "prefix", otherwise server cookie updates would not be sent to clients. nocache This option is recommended in conjunction with the insert mode when there is a cache between the client and HAProxy, as it ensures that a cacheable response will be tagged non-cacheable if a cookie needs to be inserted. This is important because if all persistence cookies are added on a cacheable home page for instance, then all customers will then fetch the page from an outer cache and will all share the same persistence cookie, leading to one server receiving much more traffic than others. See also the "insert" and "postonly" options. postonly This option ensures that cookie insertion will only be performed on responses to POST requests. It is an alternative to the "nocache" option, because POST responses are not cacheable, so this ensures that the persistence cookie will never get cached. Since most sites do not need any sort of persistence before the first POST which generally is a login request, this is a very efficient method to optimize caching without risking to find a persistence cookie in the cache. See also the "insert" and "nocache" options. preserve This option may only be used with "insert" and/or "indirect". It allows the server to emit the persistence cookie itself. In this case, if a cookie is found in the response, HAProxy will leave it untouched. This is useful in order to end persistence after a logout request for instance. For this, the server just has to emit a cookie with an invalid value (e.g. empty) or with a date in the past. By combining this mechanism with the "disable-on-404" check option, it is possible to perform a completely graceful shutdown because users will definitely leave the server after they logout. httponly This option tells HAProxy to add an "HttpOnly" cookie attribute when a cookie is inserted. This attribute is used so that a user agent doesn't share the cookie with non-HTTP components. Please check RFC6265 for more information on this attribute. secure This option tells HAProxy to add a "Secure" cookie attribute when a cookie is inserted. This attribute is used so that a user agent never emits this cookie over non-secure channels, which means that a cookie learned with this flag will be presented only over SSL/TLS connections. Please check RFC6265 for more information on this attribute. domain This option allows to specify the domain at which a cookie is inserted. It requires exactly one parameter: a valid domain name. If the domain begins with a dot, the browser is allowed to use it for any host ending with that name. It is also possible to specify several domain names by invoking this option multiple times. Some browsers might have small limits on the number of domains, so be careful when doing that. For the record, sending 10 domains to MSIE 6 or Firefox 2 works as expected. maxidle This option allows inserted cookies to be ignored after some idle time. It only works with insert-mode cookies. When a cookie is sent to the client, the date this cookie was emitted is sent too. Upon further presentations of this cookie, if the date is older than the delay indicated by the parameter (in seconds), it will be ignored. Otherwise, it will be refreshed if needed when the response is sent to the client. This is particularly useful to prevent users who never close their browsers from remaining for too long on the same server (e.g. after a farm size change). When this option is set and a cookie has no date, it is always accepted, but gets refreshed in the response. This maintains the ability for admins to access their sites. Cookies that have a date in the future further than 24 hours are ignored. Doing so lets admins fix timezone issues without risking kicking users off the site. maxlife This option allows inserted cookies to be ignored after some life time, whether they're in use or not. It only works with insert mode cookies. When a cookie is first sent to the client, the date this cookie was emitted is sent too. Upon further presentations of this cookie, if the date is older than the delay indicated by the parameter (in seconds), it will be ignored. If the cookie in the request has no date, it is accepted and a date will be set. Cookies that have a date in the future further than 24 hours are ignored. Doing so lets admins fix timezone issues without risking kicking users off the site. Contrary to maxidle, this value is not refreshed, only the first visit date counts. Both maxidle and maxlife may be used at the time. This is particularly useful to prevent users who never close their browsers from remaining for too long on the same server (e.g. after a farm size change). This is stronger than the maxidle method in that it forces a redispatch after some absolute delay. dynamic Activate dynamic cookies. When used, a session cookie is dynamically created for each server, based on the IP and port of the server, and a secret key, specified in the "dynamic-cookie-key" backend directive. The cookie will be regenerated each time the IP address change, and is only generated for IPv4/IPv6. attr This option tells HAProxy to add an extra attribute when a cookie is inserted. The attribute value can contain any characters except control ones or ";". This option may be repeated. ``` There can be only one persistence cookie per HTTP backend, and it can be declared in a defaults section. The value of the cookie will be the value indicated after the "cookie" keyword in a "server" statement. If no cookie is declared for a given server, the cookie is not set. Examples: ```text cookie JSESSIONID prefix cookie SRV insert indirect nocache cookie SRV insert postonly indirect cookie SRV insert indirect nocache maxidle 30m maxlife 8h ``` See also: "balance source", "capture cookie", "server" and "ignore-persist". **`declare capture [ request | response ] len `** ```haproxy declare capture [ request | response ] len ``` Declares a capture slot. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| no Arguments: ```text is the length allowed for the capture. ``` This declaration is only available in the frontend or listen section, but the reserved slot can be used in the backends. The "request" keyword allocates a capture slot for use in the request, and "response" allocates a capture slot for use in the response. See also: "capture-req", "capture-res" (sample converters), "capture.req.hdr", "capture.res.hdr" (sample fetches), "http-request capture" and "http-response capture". **`default-server [param*]`** ```haproxy default-server [param*] ``` Change default options for a server in a backend May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is a list of parameters for this server. The "default-server" keyword accepts an important number of options and has a complete section dedicated to it. Please refer to section 5 for more details. ``` Example: ```text default-server inter 1000 weight 13 ``` See also: "server" and [section 5](/docs/haproxy/bind-and-server-options/) about server options **`default_backend `** ```haproxy default_backend ``` Specify the backend to use when no "use_backend" rule has been matched. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text is the name of the backend to use. ``` When doing content-switching between frontend and backends using the "use_backend" keyword, it is often useful to indicate which backend will be used when no rule has matched. It generally is the dynamic backend which will catch all undetermined requests. If a backend is disabled or unpublished, default_backend rules targeting it will be ignored and stream processing will remain on the original proxy. Example: ```text use_backend dynamic if url_dyn use_backend static if url_css url_img extension_img default_backend dynamic ``` See also: "use_backend" **`description `** ```haproxy description ``` Describe a listen, frontend or backend. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| yes Arguments: string Allows to add a sentence to describe the related object in the HAProxy HTML stats page. The description will be printed on the right of the object name it describes. No need to backslash spaces in the `` arguments. **`disabled`** ```haproxy disabled ``` Disable a proxy, frontend or backend. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none The "disabled" keyword is used to disable an instance, mainly in order to liberate a listening port or to temporarily disable a service. The instance will still be created and its configuration will be checked, but it will be created in the "stopped" state and will appear as such in the statistics. It will not receive any traffic nor will it send any health-checks or logs. It is possible to disable many instances at once by adding the "disabled" keyword in a "defaults" section. By default, a disabled backend cannot be selected for content-switching. However, a portion of the traffic can ignore this when "force-be-switch" is used. See also: "enabled", "force-be-switch" **`dispatch
: (deprecated)`** ```haproxy dispatch
: (deprecated) ``` Set a default server address May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| no \| yes \| yes Arguments: ```text
is the IPv4 address of the default server. Alternatively, a resolvable hostname is supported, but this name will be resolved during start-up. is a mandatory port specification. All connections will be sent to this port, and it is not permitted to use port offsets as is possible with normal servers. ``` The "dispatch" keyword designates a default server for use when no other server can take the connection. In the past it was used to forward non persistent connections to an auxiliary load balancer. Due to its simple syntax, it has also been used for simple TCP relays. It is recommended not to use it for more clarity, and to use the "server" directive instead. This keyword has been deprecated in 3.3 and will be removed in 3.5 due to some internal limitations (no support for SSL nor idle connections etc). Using it will emit a warning that may be silenced by enabling directive "expose-deprecated-directives" in the global section. The correct way to proceed without this directive is to simply declare a server with the same address and port. If the "dispatch" directive was mixed with other servers, then these servers should be configured with a weight of zero in order never to be elected by the load balancing algorithm. Example: ```text backend deprecated_setup dispatch 192.168.100.100:80 # external load balancer's address server s1 192.168.100.1:80 cookie S1 check server s2 192.168.100.2:80 cookie S2 check backend modern_setup server external_lb 192.168.100.100:80 server s1 192.168.100.1:80 cookie S1 check weight 0 server s2 192.168.100.2:80 cookie S2 check weight 0 ``` See also: "server" **`dynamic-cookie-key `** ```haproxy dynamic-cookie-key ``` Set the dynamic cookie secret key for a backend. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: The secret key to be used. When dynamic cookies are enabled (see the "dynamic" directive for cookie), a dynamic cookie is created for each server (unless one is explicitly specified on the "server" line), using a hash of the IP address of the server, the TCP port, and the secret key. That way, we can ensure session persistence across multiple load-balancers, even if servers are dynamically added or removed. **`enabled`** ```haproxy enabled ``` Enable a proxy, frontend or backend. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none The "enabled" keyword is used to explicitly enable an instance, when the defaults has been set to "disabled". This is very rarely used. See also: "disabled" **`errorfile `** ```haproxy errorfile ``` Return a file contents instead of errors generated by HAProxy May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the HTTP status code. Currently, HAProxy is capable of generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503, and 504. designates a file containing the full HTTP response. It is recommended to follow the common practice of appending ".http" to the filename so that people do not confuse the response with HTML error pages, and to use absolute paths, since files are read before any chroot is performed. ``` It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set. Code 200 is emitted in response to requests matching a "monitor-uri" rule. The files are parsed when HAProxy starts and must be valid according to the HTTP specification. They should not exceed the configured buffer size (BUFSIZE), which generally is 16 kB, otherwise an internal error will be returned. It is also wise not to put any reference to local contents (e.g. images) in order to avoid loops between the client and HAProxy when all servers are down, causing an error to be returned instead of an image. Finally, The response cannot exceed (tune.bufsize - tune.maxrewrite) so that "http-after-response" rules still have room to operate (see "tune.maxrewrite"). The files are read at the same time as the configuration and kept in memory. For this reason, the errors continue to be returned even when the process is chrooted, and no file change is considered while the process is running. A simple method for developing those files consists in associating them to the 403 status code and interrogating a blocked URL. See also: "http-error", "errorloc", "errorloc302", "errorloc303" Example: ```text errorfile 400 /etc/haproxy/errorfiles/400badreq.http errorfile 408 /dev/null # work around Chrome pre-connect bug errorfile 403 /etc/haproxy/errorfiles/403forbid.http errorfile 503 /etc/haproxy/errorfiles/503sorry.http ``` **`errorfiles [ ...]`** ```haproxy errorfiles [ ...] ``` Import, fully or partially, the error files defined in the `` http-errors section. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the name of an existing http-errors section. is a HTTP status code. Several status code may be listed. Currently, HAProxy is capable of generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503, and 504. ``` Errors defined in the http-errors section with the name `` are imported in the current proxy. If no status code is specified, all error files of the http-errors section are imported. Otherwise, only error files associated to the listed status code are imported. Those error files override the already defined custom errors for the proxy. And they may be overridden by following ones. Functionally, it is exactly the same as declaring all error files by hand using "errorfile" directives. See also: "http-error", "errorfile", "errorloc", "errorloc302" , "errorloc303" and [section 12.4](/docs/haproxy/other-sections/#section-12-4) about http-errors. Example: ```text errorfiles generic errorfiles site-1 403 404 ``` **`errorloc `** ```haproxy errorloc errorloc302 ``` Return an HTTP redirection to a URL instead of errors generated by HAProxy May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the HTTP status code. Currently, HAProxy is capable of generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503, and 504. it is the exact contents of the "Location" header. It may contain either a relative URI to an error page hosted on the same site, or an absolute URI designating an error page on another site. Special care should be given to relative URIs to avoid redirect loops if the URI itself may generate the same error (e.g. 500). ``` It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set. Code 200 is emitted in response to requests matching a "monitor-uri" rule. Note that both keyword return the HTTP 302 status code, which tells the client to fetch the designated URL using the same HTTP method. This can be quite problematic in case of non-GET methods such as POST, because the URL sent to the client might not be allowed for something other than GET. To work around this problem, please use "errorloc303" which send the HTTP 303 status code, indicating to the client that the URL must be fetched with a GET request. See also: "http-error", "errorfile", "errorloc303" **`errorloc303 `** ```haproxy errorloc303 ``` Return an HTTP redirection to a URL instead of errors generated by HAProxy May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the HTTP status code. Currently, HAProxy is capable of generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503, and 504. it is the exact contents of the "Location" header. It may contain either a relative URI to an error page hosted on the same site, or an absolute URI designating an error page on another site. Special care should be given to relative URIs to avoid redirect loops if the URI itself may generate the same error (e.g. 500). ``` It is important to understand that this keyword is not meant to rewrite errors returned by the server, but errors detected and returned by HAProxy. This is why the list of supported errors is limited to a small set. Code 200 is emitted in response to requests matching a "monitor-uri" rule. Note that both keyword return the HTTP 303 status code, which tells the client to fetch the designated URL using the same HTTP GET method. This solves the usual problems associated with "errorloc" and the 302 code. It is possible that some very old browsers designed before HTTP/1.1 do not support it, but no such problem has been reported till now. See also: "http-error", "errorfile", "errorloc", "errorloc302" **`email-alert from `** ```haproxy email-alert from ``` Declare the from email address to be used in both the envelope and header of email alerts. This is the address that email alerts are sent from. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the from email address to use when sending email alerts ``` Also requires "email-alert mailers" and "email-alert to" to be set and if so sending email alerts is enabled for the proxy. See also: "email-alert level", "email-alert mailers", "email-alert myhostname", "email-alert to", [section 12.3](/docs/haproxy/other-sections/#section-12-3) about mailers. **`email-alert level `** ```haproxy email-alert level ``` Declare the maximum log level of messages for which email alerts will be sent. This acts as a filter on the sending of email alerts. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text One of the 8 syslog levels: emerg alert crit err warning notice info debug The above syslog levels are ordered from lowest to highest. ``` By default level is alert Also requires "email-alert from", "email-alert mailers" and "email-alert to" to be set and if so sending email alerts is enabled for the proxy. Alerts are sent when: - An un-paused server is marked as down and `` is alert or lower - A paused server is marked as down and `` is notice or lower - A server is marked as up or enters the drain state and `` is notice or lower - "option log-health-checks" is enabled, `` is info or lower, and a health check status update occurs See also: "email-alert from", "email-alert mailers", "email-alert myhostname", "email-alert to", [section 12.3](/docs/haproxy/other-sections/#section-12-3) about mailers. **`email-alert mailers `** ```haproxy email-alert mailers ``` Declare the mailers to be used when sending email alerts May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the name of the mailers section to send email alerts. ``` Also requires "email-alert from" and "email-alert to" to be set and if so sending email alerts is enabled for the proxy. See also: "email-alert from", "email-alert level", "email-alert myhostname", "email-alert to", [section 12.3](/docs/haproxy/other-sections/#section-12-3) about mailers. **`email-alert myhostname `** ```haproxy email-alert myhostname ``` Declare the to hostname address to be used when communicating with mailers. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the hostname to use when communicating with mailers ``` By default the systems hostname is used. Also requires "email-alert from", "email-alert mailers" and "email-alert to" to be set and if so sending email alerts is enabled for the proxy. See also: "email-alert from", "email-alert level", "email-alert mailers", "email-alert to", [section 12.3](/docs/haproxy/other-sections/#section-12-3) about mailers. **`email-alert to `** ```haproxy email-alert to ``` Declare both the recipient address in the envelope and to address in the header of email alerts. This is the address that email alerts are sent to. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is the to email address to use when sending email alerts ``` Also requires "email-alert mailers" and "email-alert to" to be set and if so sending email alerts is enabled for the proxy. See also: "email-alert from", "email-alert level", "email-alert mailers", "email-alert myhostname", [section 12.3](/docs/haproxy/other-sections/#section-12-3) about mailers. **`error-log-format `** ```haproxy error-log-format ``` Specifies the log format string to use in case of connection error on the frontend side. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no This directive specifies the log format string that will be used for logs containing information related to errors, timeouts, retries redispatches or HTTP status code 5xx. This format will in short be used for every log line that would be concerned by the "log-separate-errors" option, including connection errors described in [section 8.2.5](/docs/haproxy/configuration-logging/#section-8-2-5). If the directive is used in a defaults section, all subsequent frontends will use the same log format. Please see [section 8.2.6](/docs/haproxy/configuration-logging/#section-8-2-6) which covers the custom log format string in depth. "error-log-format" directive overrides previous "error-log-format" directives. **`force-persist { if | unless } `** ```haproxy force-persist { if | unless } ``` Declare a condition to force persistence on down servers May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| no \| yes \| yes By default, requests are not dispatched to down servers. It is possible to force this using "option persist", but it is unconditional and redispatches to a valid server if "option redispatch" is set. That leaves with very little possibilities to force some requests to reach a server which is artificially marked down for maintenance operations. The "force-persist" statement allows one to declare various ACL-based conditions which, when met, will cause a request to ignore the down status of a server and still try to connect to it. That makes it possible to start a server, still replying an error to the health checks, and run a specially configured browser to test the service. Among the handy methods, one could use a specific source IP address, or a specific cookie. The cookie also has the advantage that it can easily be added/removed on the browser from a test page. Once the service is validated, it is then possible to open the service to the world by returning a valid response to health checks. The forced persistence is enabled when an "if" condition is met, or unless an "unless" condition is met. The final redispatch is always disabled when this is used. See also: "option redispatch", "ignore-persist", "persist", and [section 7](/docs/haproxy/acls-and-samples/) about ACL usage. **`external-check command `** ```haproxy external-check command ``` Executable to run when performing an external-check May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the external command to run ``` The arguments passed to the command are: `` `` `` `` The `` and `` are derived from the first listener that is either IPv4, IPv6 or a UNIX socket. In the case of a UNIX socket listener the proxy_address will be the path of the socket and the `` will be the string "NOT_USED". In a backend section, it's not possible to determine a listener, and both `` and `` will have the string value "NOT_USED". Some values are also provided through environment variables. Environment variables: ```text HAPROXY_PROXY_ADDR The first bind address if available (or empty if not applicable, for example in a "backend" section). HAPROXY_PROXY_ID The backend id. HAPROXY_PROXY_NAME The backend name. HAPROXY_PROXY_PORT The first bind port if available (or empty if not applicable, for example in a "backend" section or for a UNIX socket). HAPROXY_SERVER_ADDR The server address. HAPROXY_SERVER_CURCONN The current number of connections on the server. HAPROXY_SERVER_ID The server id. HAPROXY_SERVER_MAXCONN The server max connections. HAPROXY_SERVER_NAME The server name. HAPROXY_SERVER_PORT The server port if available (or empty for a UNIX socket). HAPROXY_SERVER_SSL "0" when SSL is not used, "1" when it is used HAPROXY_SERVER_PROTO The protocol used by this server, which can be one of "cli" (the haproxy CLI), "syslog" (syslog TCP server), "peers" (peers TCP server), "h1" (HTTP/1.x server), "h2" (HTTP/2 server), or "tcp" (any other TCP server). PATH The PATH environment variable used when executing the command may be set using "external-check path". ``` If the command executed and exits with a zero status then the check is considered to have passed, otherwise the check is considered to have failed. Example: ```text external-check command /bin/true ``` See also: "external-check", "option external-check", "external-check path" **`external-check path `** ```haproxy external-check path ``` The value of the PATH environment variable used when running an external-check May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the path used when executing external command to run ``` The default path is "". Example: ```text external-check path "/usr/bin:/bin" ``` See also: "external-check", "option external-check", "external-check command" **`force-be-switch { if | unless } `** ```haproxy force-be-switch { if | unless } ``` Allow content switching to select a backend instance even if it is disabled or unpublished. This rule can be used by admins to test traffic to services prior to expose them to the outside world. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| no See also: "be-unpublished", "disabled" **`filter [param*]`** ```haproxy filter [param*] ``` Add the filter `` in the filter list attached to the proxy. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| yes Arguments: ```text is the name of the filter. Officially supported filters are referenced in section 9. is a list of parameters accepted by the filter . The parsing of these parameters are the responsibility of the filter. Please refer to the documentation of the corresponding filter (section 9) for all details on the supported parameters. ``` Multiple occurrences of the filter line can be used for the same proxy. The same filter can be referenced many times if needed. Example: ```text listen bind *:80 filter trace name BEFORE-HTTP-COMP filter compression filter trace name AFTER-HTTP-COMP compression algo gzip compression offload server srv1 192.168.0.1:80 ``` See also: [section 9](/docs/haproxy/filters/)., "filter-sequence" filter-sequence { request \| response } `` Specifies in which order filters declared on the proxy should be executed. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| yes Comma-separated list of filter names (``) to specify in which order filters declared on the proxy should be executed, for request or response path, respectively. When filter-sequence is not specified for a given path (ie: request vs response), the order in which filters are declared on the proxy is used. If filter-sequence omits some filters that were declared on the proxy, they will not be executed. This is an effective way of temporarily disabling a filter without removing it from the configuration. Example: ```text global lua-load my-filter.lua # defines custom "lua.my-filter" frontend myfront filter comp-req filter comp-res filter lua.my-filter filter-sequence request lua.my-filter,comp-req filter-sequence response lua.my-filter,comp-res ``` See also: "filter" **`fullconn `** ```haproxy fullconn ``` Specify at what backend load the servers will reach their maxconn May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the number of connections on the backend which will make the servers use the maximal number of connections. ``` When a server has a "maxconn" parameter specified, it means that its number of concurrent connections will never go higher. Additionally, if it has a "minconn" parameter, it indicates a dynamic limit following the backend's load. The server will then always accept at least `` connections, never more than ``, and the limit will be on the ramp between both values when the backend has less than `` concurrent connections. This makes it possible to limit the load on the servers during normal loads, but push it further for important loads without overloading the servers during exceptional loads. Since it's hard to get this value right, HAProxy automatically sets it to 10% of the sum of the maxconns of all frontends that may branch to this backend (based on "use_backend" and "default_backend" rules). That way it's safe to leave it unset. However, "use_backend" involving dynamic names are not counted since there is no way to know if they could match or not. Example: ```shell # The servers will accept between 100 and 1000 concurrent connections each # and the maximum of 1000 will be reached when the backend reaches 10000 # connections. backend dynamic fullconn 10000 server srv1 dyn1:80 minconn 100 maxconn 1000 server srv2 dyn2:80 minconn 100 maxconn 1000 ``` See also: "maxconn", "server" **`guid `** ```haproxy guid ``` Specify a case-sensitive global unique ID for this proxy. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| yes `` must be unique across all haproxy configuration on every object types. Format is left unspecified to allow the user to select its naming policy. The only restriction is its length which cannot be greater than 127 characters. All alphanumerical values and '.', ':', '-' and '\_' characters are valid. See also "shm-stats-file". **`hash-balance-factor `** ```haproxy hash-balance-factor ``` Specify the balancing factor for bounded-load consistent hashing May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| no \| yes Arguments: ```text is the control for the maximum number of concurrent requests to send to a server, expressed as a percentage of the average number of concurrent requests across all of the active servers. ``` Specifying a "hash-balance-factor" for a server with "hash-type consistent" enables an algorithm that prevents any one server from getting too many requests at once, even if some hash buckets receive many more requests than others. Setting `` to 0 (the default) disables the feature. Otherwise, `` is a percentage greater than 100. For example, if `` is 150, then no server will be allowed to have a load more than 1.5 times the average. If server weights are used, they will be respected. If the first-choice server is disqualified, the algorithm will choose another server based on the request hash, until a server with additional capacity is found. A higher `` allows more imbalance between the servers, while a lower `` means that more servers will be checked on average, affecting performance. Reasonable values are from 125 to 200. This setting is also used by "balance random" which internally relies on the consistent hashing mechanism. See also: "balance" and "hash-type". **`hash-preserve-affinity { always | maxconn | maxqueue }`** ```haproxy hash-preserve-affinity { always | maxconn | maxqueue } ``` Specify a method for assigning streams to servers with hash load balancing when servers are satured or have a full queue. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes The following values can be specified: - "always" : this is the default strategy. A stream is assigned to a server based on hashing irrespective of whether the server is currently saturated. - "maxconn" : when selected, servers that have "maxconn" set and are currently saturated will be skipped. Another server will be picked by following the hashing ring. This has no effect on servers that do not set "maxconn". If all servers are saturated, the request is enqueued to the last server in the hash ring before the initially selected server. - "maxqueue": when selected, servers that have "maxconn" set, "maxqueue" set to a non-zero value (limited queue size) and currently have a full queue will be skipped. Another server will be picked by following the hashing ring. This has no effect on servers that do not set both "maxconn" and "maxqueue". See also: "maxconn", "maxqueue", "hash-balance-factor" **`hash-type `** ```haproxy hash-type ``` Specify a method to use for mapping hashes to servers May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the method used to select a server from the hash computed by the : map-based the hash table is a static array containing all alive servers. The hashes will be very smooth, will consider weights, but will be static in that weight changes while a server is up will be ignored. This means that there will be no slow start. Also, since a server is selected by its position in the array, most mappings are changed when the server count changes. This means that when a server goes up or down, or when a server is added to a farm, most connections will be redistributed to different servers. This can be inconvenient with caches for instance. consistent the hash table is a tree filled with many occurrences of each server. The hash key is looked up in the tree and the closest server is chosen. This hash is dynamic, it supports changing weights while the servers are up, so it is compatible with the slow start feature. It has the advantage that when a server goes up or down, only its associations are moved. When a server is added to the farm, only a few part of the mappings are redistributed, making it an ideal method for caches. However, due to its principle, the distribution will never be very smooth and it may sometimes be necessary to adjust a server's weight or its ID to get a more balanced distribution. In order to get the same distribution on multiple load balancers, it is important that all servers have the exact same IDs. Note: consistent hash uses sdbm and avalanche if no hash function is specified. is the hash function to be used: sdbm this function was created initially for sdbm (a public-domain reimplementation of ndbm) database library. It was found to do well in scrambling bits, causing better distribution of the keys and fewer splits. It also happens to be a good general hashing function with good distribution, unless the total server weight is a multiple of 64, in which case applying the avalanche modifier may help. djb2 this function was first proposed by Dan Bernstein many years ago on comp.lang.c. Studies have shown that for certain workload this function provides a better distribution than sdbm. It generally works well with text-based inputs though it can perform extremely poorly with numeric-only input or when the total server weight is a multiple of 33, unless the avalanche modifier is also used. wt6 this function was designed for HAProxy while testing other functions in the past. It is not as smooth as the other ones, but is much less sensible to the input data set or to the number of servers. It can make sense as an alternative to sdbm+avalanche or djb2+avalanche for consistent hashing or when hashing on numeric data such as a source IP address or a visitor identifier in a URL parameter. crc32 this is the most common CRC32 implementation as used in Ethernet, gzip, PNG, etc. It is slower than the other ones but may provide a better distribution or less predictable results especially when used on strings. none don't hash the key, the key will be used as a hash, this can be useful to manually hash the key using a converter for that purpose and let haproxy use the result directly. The operation will convert the key to a string if it is not already, and parse it as an integer whose value will be used as the key. Some input key types might not be relevant here (e.g. IP addresses). indicates an optional method applied after hashing the key: avalanche This directive indicates that the result from the hash function above should not be used in its raw form but that a 4-byte full avalanche hash must be applied first. The purpose of this step is to mix the resulting bits from the previous hash in order to avoid any undesired effect when the input contains some limited values or when the number of servers is a multiple of one of the hash's components (64 for SDBM, 33 for DJB2). Enabling avalanche tends to make the result less predictable, but it's also not as smooth as when using the original function. Some testing might be needed with some workloads. This hash is one of the many proposed by Bob Jenkins. ``` The default hash type is "map-based" and is recommended for most usages. The default function is "sdbm", the selection of a function should be based on the range of the values being hashed. See also: "balance", "hash-balance-factor", "hash-preserve-affinity", "server" **`http-after-response [ { if | unless } ]`** ```haproxy http-after-response [ { if | unless } ] ``` Access control for all Layer 7 responses (server, applet/service and internal ones). May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes The http-after-response statement defines a set of rules which apply to layer 7 processing. The rules are evaluated in their declaration order when they are met in a frontend, listen or backend section. Since these rules apply on responses, the backend rules are applied first, followed by the frontend's rules. Any rule may optionally be followed by an ACL-based condition, in which case it will only be evaluated if the condition evaluates true. Unlike http-response rules, these ones are applied on all responses, the server ones but also to all responses generated by HAProxy. These rules are evaluated at the end of the responses analysis, before the data forwarding phase. The condition is evaluated just before the action is executed, and the action is performed exactly once. As such, there is no problem if an action changes an element which is checked as part of the condition. This also means that multiple actions may rely on the same condition so that the first action that changes the condition's evaluation is sufficient to implicitly disable the remaining actions. This is used for example when trying to assign a value to a variable from various sources when it's empty. There is no limit to the number of "http-after-response" statements per instance. The first keyword after "http-after-response" in the syntax is the rule's action, optionally followed by a varying number of arguments for the action. The supported actions and their respective syntaxes are enumerated in [section 4.3](/docs/haproxy/proxies/#section-4-3) "Actions" (look for actions which tick "HTTP Aft"). This directive is only available from named defaults sections, not anonymous ones. Rules defined in the defaults section are evaluated before ones in the associated proxy section. To avoid ambiguities, in this case the same defaults section cannot be used by proxies with the frontend capability and by proxies with the backend capability. It means a listen section cannot use a defaults section defining such rules. Note: Errors emitted in early stage of the request parsing are handled by the multiplexer at a lower level, before any http analysis. Thus no http-after-response ruleset is evaluated on these errors. Example: ```text http-after-response set-header Strict-Transport-Security "max-age=31536000" http-after-response set-header Cache-Control "no-store,no-cache,private" http-after-response set-header Pragma "no-cache" ``` **`http-check comment `** ```haproxy http-check comment ``` Defines a comment for the following the http-check rule, reported in logs if it fails. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the comment message to add in logs if the following http-check rule fails. ``` It only works for connect, send and expect rules. It is useful to make user-friendly error reporting. See also: "option httpchk", "http-check connect", "http-check send" and "http-check expect". **`http-check connect [default] [port ] [addr ] [send-proxy]`** ```haproxy http-check connect [default] [port ] [addr ] [send-proxy] [via-socks4] [ssl] [sni ] [alpn ] [linger] [proto ] [comment ] ``` Opens a new connection to perform an HTTP health check May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text comment defines a message to report if the rule evaluation fails. default Use default options of the server line to do the health checks. The server options are used only if not redefined. port if not set, check port or server port is used. It tells HAProxy where to open the connection to. must be a valid TCP port source integer, from 1 to 65535 or an sample-fetch expression. addr defines the IP address to do the health check. send-proxy send a PROXY protocol string via-socks4 enables outgoing health checks using upstream socks4 proxy. ssl opens a ciphered connection sni specifies the SNI to use to do health checks over SSL. alpn defines which protocols to advertise with ALPN. The protocol list consists in a comma-delimited list of protocol names, for instance: "h2,http/1.1". If it is not set, the server ALPN is used. proto forces the multiplexer's protocol to use for this connection. It must be an HTTP mux protocol and it must be usable on the backend side. The list of available protocols is reported in haproxy -vv. linger cleanly close the connection instead of using a single RST. ``` Just like tcp-check health checks, it is possible to configure the connection to use to perform HTTP health check. This directive should also be used to describe a scenario involving several request/response exchanges, possibly on different ports or with different servers. When there are no TCP port configured on the server line neither server port directive, then the first step of the http-check sequence must be to specify the port with a "http-check connect". In an http-check ruleset a 'connect' is required, it is also mandatory to start the ruleset with a 'connect' rule. Purpose is to ensure admin know what they do. When a connect must start the ruleset, if may still be preceded by set-var, unset-var or comment rules. Examples: ```shell # check HTTP and HTTPs services on a server. # first open port 80 thanks to server line port directive, then # tcp-check opens port 443, ciphered and run a request on it: option httpchk http-check connect http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu http-check expect status 200-399 http-check connect port 443 ssl sni haproxy.1wt.eu http-check send meth GET uri / ver HTTP/1.1 hdr host haproxy.1wt.eu http-check expect status 200-399 server www 10.0.0.1 check port 80 ``` See also: "option httpchk", "http-check send", "http-check expect" **`http-check disable-on-404`** ```haproxy http-check disable-on-404 ``` Enable a maintenance mode upon HTTP/404 response to health-checks May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none When this option is set, a server which returns an HTTP code 404 will be excluded from further load-balancing, but will still receive persistent connections. This provides a very convenient method for Web administrators to perform a graceful shutdown of their servers. It is also important to note that a server which is detected as failed while it was in this mode will not generate an alert, just a notice. If the server responds 2xx or 3xx again, it will immediately be reinserted into the farm. The status on the stats page reports "NOLB" for a server in this mode. It is important to note that this option only works in conjunction with the "httpchk" option. If this option is used with "http-check expect", then it has precedence over it so that 404 responses will still be considered as soft-stop. Note also that a stopped server will stay stopped even if it replies 404s. This option is only evaluated for running servers. See also: "option httpchk" and "http-check expect". **`http-check expect [min-recv ] [comment ]`** ```haproxy http-check expect [min-recv ] [comment ] [ok-status ] [error-status ] [tout-status ] [on-success ] [on-error ] [status-code ] [!] ``` Make HTTP health checks consider response contents or specific status codes May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text comment defines a message to report if the rule evaluation fails. min-recv is optional and can define the minimum amount of data required to evaluate the current expect rule. If the number of received bytes is under this limit, the check will wait for more data. This option can be used to resolve some ambiguous matching rules or to avoid executing costly regex matches on content known to be still incomplete. If an exact string is used, the minimum between the string length and this parameter is used. This parameter is ignored if it is set to -1. If the expect rule does not match, the check will wait for more data. If set to 0, the evaluation result is always conclusive. ok-status is optional and can be used to set the check status if the expect rule is successfully evaluated and if it is the last rule in the tcp-check ruleset. "L7OK", "L7OKC", "L6OK" and "L4OK" are supported: - L7OK : check passed on layer 7 - L7OKC: check conditionally passed on layer 7, set server to NOLB state. - L6OK : check passed on layer 6 - L4OK : check passed on layer 4 By default "L7OK" is used. error-status is optional and can be used to set the check status if an error occurred during the expect rule evaluation. "L7OKC", "L7RSP", "L7STS", "L6RSP" and "L4CON" are supported: - L7OKC: check conditionally passed on layer 7, set server to NOLB state. - L7RSP: layer 7 invalid response - protocol error - L7STS: layer 7 response error, for example HTTP 5xx - L6RSP: layer 6 invalid response - protocol error - L4CON: layer 1-4 connection problem By default "L7RSP" is used. tout-status is optional and can be used to set the check status if a timeout occurred during the expect rule evaluation. "L7TOUT", "L6TOUT", and "L4TOUT" are supported: - L7TOUT: layer 7 (HTTP/SMTP) timeout - L6TOUT: layer 6 (SSL) timeout - L4TOUT: layer 1-4 timeout By default "L7TOUT" is used. on-success is optional and can be used to customize the informational message reported in logs if the expect rule is successfully evaluated and if it is the last rule in the tcp-check ruleset. is a Custom log format string (see section 8.2.6). on-error is optional and can be used to customize the informational message reported in logs if an error occurred during the expect rule evaluation. is a Custom log format string (see section 8.2.6). status-code is optional and can be used to set the check status code reported in logs, on success or on error. is a standard HAProxy expression formed by a sample-fetch followed by some converters. is a keyword indicating how to look for a specific pattern in the response. The keyword may be one of "status", "rstatus", "hdr", "fhdr", "string", or "rstring". The keyword may be preceded by an exclamation mark ("!") to negate the match. Spaces are allowed between the exclamation mark and the keyword. See below for more details on the supported keywords. is the pattern to look for. It may be a string, a regular expression or a more complex pattern with several arguments. If the string pattern contains spaces, they must be escaped with the usual backslash ('\'). ``` By default, "option httpchk" considers that response statuses 2xx and 3xx are valid, and that others are invalid. When "http-check expect" is used, it defines what is considered valid or invalid. Only one "http-check" statement is supported in a backend. If a server fails to respond or times out, the check obviously fails. The available matches are: ```text status : test the status codes found parsing string. it must be a comma-separated list of status codes or range codes. A health check response will be considered as valid if the response's status code matches any status code or is inside any range of the list. If the "status" keyword is prefixed with "!", then the response will be considered invalid if the status code matches. rstatus : test a regular expression for the HTTP status code. A health check response will be considered valid if the response's status code matches the expression. If the "rstatus" keyword is prefixed with "!", then the response will be considered invalid if the status code matches. This is mostly used to check for multiple codes. hdr { name | name-lf } [ -m ] [ { value | value-lf } [ -m ] : test the specified header pattern on the HTTP response headers. The name pattern is mandatory but the value pattern is optional. If not specified, only the header presence is verified. is the matching method, applied on the header name or the header value. Supported matching methods are "str" (exact match), "beg" (prefix match), "end" (suffix match), "sub" (substring match) or "reg" (regex match). If not specified, exact matching method is used. If the "name-lf" parameter is used, is evaluated as a Custom log format string (see section 8.2.6). If "value-lf" parameter is used, is evaluated as a log-format string. These parameters cannot be used with the regex matching method. Finally, the header value is considered as comma-separated list. Note that matchings are case insensitive on the header names. fhdr { name | name-lf } [ -m ] [ { value | value-lf } [ -m ] : test the specified full header pattern on the HTTP response headers. It does exactly the same as the "hdr" keyword, except the full header value is tested, commas are not considered as delimiters. string : test the exact string match in the HTTP response body. A health check response will be considered valid if the response's body contains this exact string. If the "string" keyword is prefixed with "!", then the response will be considered invalid if the body contains this string. This can be used to look for a mandatory word at the end of a dynamic page, or to detect a failure when a specific error appears on the check page (e.g. a stack trace). rstring : test a regular expression on the HTTP response body. A health check response will be considered valid if the response's body matches this expression. If the "rstring" keyword is prefixed with "!", then the response will be considered invalid if the body matches the expression. This can be used to look for a mandatory word at the end of a dynamic page, or to detect a failure when a specific error appears on the check page (e.g. a stack trace). string-lf : test a Custom log format string (see section 8.2.6) match in the HTTP response body. A health check response will be considered valid if the response's body contains the string resulting of the evaluation of , which follows the log-format rules. If prefixed with "!", then the response will be considered invalid if the body contains the string. ``` It is important to note that the responses will be limited to a certain size defined by the global "tune.bufsize" option, which defaults to 16384 bytes. Thus, too large responses may not contain the mandatory pattern when using "string" or "rstring". If a large response is absolutely required, it is possible to change the default max size by setting the global variable. However, it is worth keeping in mind that parsing very large responses can waste some CPU cycles, especially when regular expressions are used, and that it is always better to focus the checks on smaller resources. In an http-check ruleset, the last expect rule may be implicit. If no expect rule is specified after the last "http-check send", an implicit expect rule is defined to match on 2xx or 3xx status codes. It means this rule is also defined if there is no "http-check" rule at all, when only "option httpchk" is set. Last, if "http-check expect" is combined with "http-check disable-on-404", then this last one has precedence when the server responds with 404. Examples: ```shell # only accept status 200 as valid http-check expect status 200,201,300-310 # be sure a sessid coookie is set http-check expect hdr name "set-cookie" value -m beg "sessid=" # consider SQL errors as errors http-check expect ! string SQL\ Error # consider status 5xx only as errors http-check expect ! rstatus ^5 # check that we have a correct hexadecimal tag before /html http-check expect rstring ``` See also: "option httpchk", "http-check connect", "http-check disable-on-404" and "http-check send". **`http-check send [meth ] [{ uri | uri-lf }>] [ver ]`** ```haproxy http-check send [meth ] [{ uri | uri-lf }>] [ver ] [hdr ]* [{ body | body-lf }] [comment ] ``` Add a possible list of headers and/or a body to the request sent during HTTP health checks. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text comment defines a message to report if the rule evaluation fails. meth is the optional HTTP method used with the requests. When not set, the "OPTIONS" method is used, as it generally requires low server processing and is easy to filter out from the logs. Any method may be used, though it is not recommended to invent non-standard ones. uri is optional and set the URI referenced in the HTTP requests to the string . It defaults to "/" which is accessible by default on almost any server, but may be changed to any other URI. Query strings are permitted. uri-lf is optional and set the URI referenced in the HTTP requests using the Custom log format (see section 8.2.6). It defaults to "/" which is accessible by default on almost any server, but may be changed to any other URI. Query strings are permitted. ver is the optional HTTP version string. It defaults to "HTTP/1.0" but some servers might behave incorrectly in HTTP 1.0, so turning it to HTTP/1.1 may sometimes help. Note that the Host field is mandatory in HTTP/1.1, use "hdr" argument to add it. hdr adds the HTTP header field whose name is specified in and whose value is defined by , which follows the Custom log format rules described in section 8.2.6. body add the body defined by to the request sent during HTTP health checks. If defined, the "Content-Length" header is thus automatically added to the request. body-lf add the body defined by the Custom log format (see section 8.2.6) to the request sent during HTTP health checks. If defined, the "Content-Length" header is thus automatically added to the request. ``` In addition to the request line defined by the "option httpchk" directive, this one is the valid way to add some headers and optionally a body to the request sent during HTTP health checks. If a body is defined, the associate "Content-Length" header is automatically added. Thus, this header or "Transfer-encoding" header should not be present in the request provided by "http-check send". If so, it will be ignored. The old trick consisting to add headers after the version string on the "option httpchk" line is now deprecated. Also "http-check send" doesn't support HTTP keep-alive. Keep in mind that it will automatically append a "Connection: close" header, unless a Connection header has already already been configured via a hdr entry. Note that the Host header and the request authority, when both defined, are automatically synchronized. It means when the HTTP request is sent, when a Host is inserted in the request, the request authority is accordingly updated. Thus, don't be surprised if the Host header value overwrites the configured request authority. Note also for now, no Host header is automatically added in HTTP/1.1 or above requests. You should add it explicitly. See also: "option httpchk", "http-check send-state" and "http-check expect". **`http-check send-state`** ```haproxy http-check send-state ``` Enable emission of a state header with HTTP health checks May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none When this option is set, HAProxy will systematically send a special header "X-Haproxy-Server-State" with a list of parameters indicating to each server how they are seen by HAProxy. This can be used for instance when a server is manipulated without access to HAProxy and the operator needs to know whether HAProxy still sees it up or not, or if the server is the last one in a farm. The header is composed of fields delimited by semi-colons, the first of which is a word ("UP", "DOWN", "NOLB"), possibly followed by a number of valid checks on the total number before transition, just as appears in the stats interface. Next headers are in the form "``=``", indicating in no specific order some values available in the stats interface: - a variable "address", containing the address of the backend server. This corresponds to the `
` field in the server declaration. For unix domain sockets, it will read "unix". - a variable "port", containing the port of the backend server. This corresponds to the `` field in the server declaration. For unix domain sockets, it will read "unix". - a variable "name", containing the name of the backend followed by a slash ("/") then the name of the server. This can be used when a server is checked in multiple backends. - a variable "node" containing the name of the HAProxy node, as set in the global "node" variable, otherwise the system's hostname if unspecified. - a variable "weight" indicating the weight of the server, a slash ("/") and the total weight of the farm (just counting usable servers). This helps to know if other servers are available to handle the load when this one fails. - a variable "scur" indicating the current number of concurrent connections on the server, followed by a slash ("/") then the total number of connections on all servers of the same backend. - a variable "qcur" indicating the current number of requests in the server's queue. Example of a header received by the application server: ```shell >>> X-Haproxy-Server-State: UP 2/3; name=bck/srv2; node=lb1; weight=1/2; \ scur=13/22; qcur=0 ``` See also: "option httpchk", "http-check disable-on-404" and "http-check send". **`http-check set-var([,...]) `** ```haproxy http-check set-var([,...]) http-check set-var-fmt([,...]) ``` This operation sets the content of a variable. The variable is declared inline. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text The name of the variable. Only "proc", "sess" and "check" scopes can be used. See section 2.8 about variables for details. A set of conditions that must all be true for the variable to actually be set (such as "ifnotempty", "ifgt" ...). See the set-var converter's description for a full list of possible conditions. Is a sample-fetch expression potentially followed by converters. This is the value expressed using Custom log format (see Custom Log Format in section 8.2.6). ``` Examples: ```text http-check set-var(check.port) int(1234) http-check set-var-fmt(check.port) "name=%H" ``` **`http-check unset-var()`** ```haproxy http-check unset-var() ``` Free a reference to a variable within its scope. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text The name of the variable. Only "proc", "sess" and "check" scopes can be used. See section 2.8 about variables for details. ``` Examples: ```text http-check unset-var(check.port) ``` **`http-error status [content-type ]`** ```haproxy http-error status [content-type ] [ { default-errorfiles | errorfile | errorfiles | ``` file `` | lf-file `` | string `` | lf-string `` } ] [ hdr `` `` ]* Defines a custom error message to use instead of errors generated by HAProxy. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text status is the HTTP status code. It must be specified. Currently, HAProxy is capable of generating codes 200, 400, 401, 403, 404, 405, 407, 408, 410, 413, 414, 425, 429, 431, 500, 501, 502, 503, and 504. content-type is the response content type, for instance "text/plain". This parameter is ignored and should be omitted when an errorfile is configured or when the payload is empty. Otherwise, it must be defined. default-errorfiles Reset the previously defined error message for current proxy for the status . If used on a backend, the frontend error message is used, if defined. If used on a frontend, the default error message is used. errorfile designates a file containing the full HTTP response. It is recommended to follow the common practice of appending ".http" to the filename so that people do not confuse the response with HTML error pages, and to use absolute paths, since files are read before any chroot is performed. errorfiles designates the http-errors section to use to import the error message with the status code . If no such message is found, the proxy's error messages are considered. file specifies the file to use as response payload. If the file is not empty, its content-type must be set as argument to "content-type", otherwise, any "content-type" argument is ignored. is considered as a raw string. string specifies the raw string to use as response payload. The content-type must always be set as argument to "content-type". lf-file specifies the file to use as response payload. If the file is not empty, its content-type must be set as argument to "content-type", otherwise, any "content-type" argument is ignored. is evaluated as a Custom log format (see section 8.2.6). lf-string specifies the log-format string to use as response payload. The content-type must always be set as argument to "content-type". hdr adds to the response the HTTP header field whose name is specified in and whose value is defined by , which follows the Custom log format rules (see section 8.2.6). This parameter is ignored if an errorfile is used. ``` This directive may be used instead of "errorfile", to define a custom error message. As "errorfile" directive, it is used for errors detected and returned by HAProxy. If an errorfile is defined, it is parsed when HAProxy starts and must be valid according to the HTTP standards. The generated response must not exceed the configured buffer size (BUFFSIZE), otherwise an internal error will be returned. Finally, if you consider to use some http-after-response rules to rewrite these errors, the reserved buffer space should be available (see "tune.maxrewrite"). The files are read at the same time as the configuration and kept in memory. For this reason, the errors continue to be returned even when the process is chrooted, and no file change is considered while the process is running. Note: 400/408/500 errors emitted in early stage of the request parsing are handled by the multiplexer at a lower level. No custom formatting is supported at this level. Thus only static error messages, defined with "errorfile" directive, are supported. However, this limitation only exists during the request headers parsing or between two transactions. See also: "errorfile", "errorfiles", "errorloc", "errorloc302", "errorloc303" and [section 12.4](/docs/haproxy/other-sections/#section-12-4) about http-errors. **`http-request [options...] [ { if | unless } ]`** ```haproxy http-request [options...] [ { if | unless } ] ``` Access control for Layer 7 requests May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes The http-request statement defines a set of rules which apply to layer 7 processing. The rules are evaluated in their declaration order when they are met in a frontend, listen or backend section. Any rule may optionally be followed by an ACL-based condition, in which case it will only be evaluated if the condition evaluates to true. The condition is evaluated just before the action is executed, and the action is performed exactly once. As such, there is no problem if an action changes an element which is checked as part of the condition. This also means that multiple actions may rely on the same condition so that the first action that changes the condition's evaluation is sufficient to implicitly disable the remaining actions. This is used for example when trying to assign a value to a variable from various sources when it's empty. There is no limit to the number of "http-request" statements per instance. The first keyword after "http-request" in the syntax is the rule's action, optionally followed by a varying number of arguments for the action. The supported actions and their respective syntaxes are enumerated in [section 4.3](/docs/haproxy/proxies/#section-4-3) "Actions" (look for actions which tick "HTTP Req"). This directive is only available from named defaults sections, not anonymous ones. Rules defined in the defaults section are evaluated before ones in the associated proxy section. To avoid ambiguities, in this case the same defaults section cannot be used by proxies with the frontend capability and by proxies with the backend capability. It means a listen section cannot use a defaults section defining such rules. Example: ```text acl nagios src 192.168.129.3 acl local_net src 192.168.0.0/16 acl auth_ok http_auth(L1) http-request allow if nagios http-request allow if local_net auth_ok http-request auth realm Gimme if local_net auth_ok http-request deny ``` Example: ```text acl key req.hdr(X-Add-Acl-Key) -m found acl add path /addacl acl del path /delacl acl myhost hdr(Host) -f myhost.lst http-request add-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key add http-request del-acl(myhost.lst) %[req.hdr(X-Add-Acl-Key)] if key del ``` Example: ```text acl value req.hdr(X-Value) -m found acl setmap path /setmap acl delmap path /delmap use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } http-request set-map(map.lst) %[src] %[req.hdr(X-Value)] if setmap value http-request del-map(map.lst) %[src] if delmap ``` See also: "stats http-request", [section 12.2](/docs/haproxy/other-sections/#section-12-2) about userlists and [section 7](/docs/haproxy/acls-and-samples/) about ACL usage. **`http-response [ { if | unless } ]`** ```haproxy http-response [ { if | unless } ] ``` Access control for Layer 7 responses May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| yes The http-response statement defines a set of rules which apply to layer 7 processing. The rules are evaluated in their declaration order when they are met in a frontend, listen or backend section. Since these rules apply on responses, the backend rules are applied first, followed by the frontend's rules. Any rule may optionally be followed by an ACL-based condition, in which case it will only be evaluated if the condition evaluates to true. The condition is evaluated just before the action is executed, and the action is performed exactly once. As such, there is no problem if an action changes an element which is checked as part of the condition. This also means that multiple actions may rely on the same condition so that the first action that changes the condition's evaluation is sufficient to implicitly disable the remaining actions. This is used for example when trying to assign a value to a variable from various sources when it's empty. There is no limit to the number of "http-response" statements per instance. The first keyword after "http-response" in the syntax is the rule's action, optionally followed by a varying number of arguments for the action. The supported actions and their respective syntaxes are enumerated in [section 4.3](/docs/haproxy/proxies/#section-4-3) "Actions" (look for actions which tick "HTTP Res"). This directive is only available from named defaults sections, not anonymous ones. Rules defined in the defaults section are evaluated before ones in the associated proxy section. To avoid ambiguities, in this case the same defaults section cannot be used by proxies with the frontend capability and by proxies with the backend capability. It means a listen section cannot use a defaults section defining such rules. Example: ```text acl key_acl res.hdr(X-Acl-Key) -m found acl myhost hdr(Host) -f myhost.lst http-response add-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl http-response del-acl(myhost.lst) %[res.hdr(X-Acl-Key)] if key_acl ``` Example: ```text acl value res.hdr(X-Value) -m found use_backend bk_appli if { hdr(Host),map_str(map.lst) -m found } http-response set-map(map.lst) %[src] %[res.hdr(X-Value)] if value http-response del-map(map.lst) %[src] if ! value ``` See also: "http-request", [section 12.2](/docs/haproxy/other-sections/#section-12-2) about userlists and [section 7](/docs/haproxy/acls-and-samples/) about ACL usage. **`http-reuse { never | safe | aggressive | always }`** ```haproxy http-reuse { never | safe | aggressive | always } ``` Declare how idle HTTP connections may be shared between requests May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes In order to avoid the cost of setting up new connections to backend servers for each HTTP request, HAProxy tries to keep such idle connections opened after being used. These connections are specific to a server and are stored in a list called a pool, and are grouped together by a set of common key properties. Subsequent HTTP requests will cause a lookup of a compatible connection sharing identical properties in the associated pool and result in this connection being reused instead of establishing a new one. A limit on the number of idle connections to keep on a server can be specified via the "pool-max-conn" server keyword. Unused connections are periodically purged according to the "pool-purge-delay" interval. The following connection properties are used to determine if an idle connection is eligible for reuse on a given request: - source and destination addresses - proxy protocol - TOS and mark socket options - connection name, determined either by the result of the evaluation of the "pool-conn-name" expression if present, otherwise by the "sni" expression, which defaults to "req.hdr(host),field(1,:)", i.e. uses the incoming request's "Host" header field without the colon nor the port number. In some occasions, connection lookup or reuse is not performed due to extra restrictions. This is determined by the reuse strategy specified via the keyword argument: - "never" : idle connections are never shared between sessions. This mode may be enforced to cancel a different strategy inherited from a defaults section or for troubleshooting. For example, if an old bogus application considers that multiple requests over the same connection come from the same client and it is not possible to fix the application, it may be desirable to disable connection sharing in a single backend. An example of such an application could be an old HAProxy using cookie insertion in tunnel mode and not checking any request past the first one. - "safe" : this is the default and the recommended strategy. The first request of a session is always sent over its own connection, and only subsequent requests may be dispatched over other existing connections. This ensures that in case the server closes the connection when the request is being sent, the browser can decide to silently retry it. Since it is exactly equivalent to regular keep-alive, there should be no side effects. There is also a special handling for the connections using protocols subject to Head-of-line blocking (backend with h2 or fcgi). In this case, when at least one stream is processed, the used connection is reserved to handle streams of the same session. When no more streams are processed, the connection is released and can be reused. - "aggressive": this mode may be useful in webservices environments where all servers are not necessarily known and where it would be appreciable to deliver most first requests over existing connections. In this case, first requests are only delivered over existing connections that have been reused at least once, proving that the server correctly supports connection reuse. It should only be used when it's sure that the client can retry a failed request once in a while and where the benefit of aggressive connection reuse significantly outweighs the downsides of rare connection failures. - "always": this mode is only recommended when the path to the server is known for never breaking existing connections quickly after releasing them. It allows the first request of a session to be sent to an existing connection. This can provide a significant performance increase over the "safe" strategy when the backend is a cache farm, since such components tend to show a consistent behavior and will benefit from the connection sharing. It is recommended that the "http-keep-alive" timeout remains low in this mode so that no dead connections remain usable. In most cases, this will lead to the same performance gains as "aggressive" but with more risks. It should only be used when it improves the situation over "aggressive". Also note that connections with certain bogus authentication schemes (relying on the connection) like NTLM are marked private if possible and never shared. This won't be the case however when using a protocol with multiplexing abilities and using reuse mode level value greater than the default "safe" strategy as in this case nothing prevents the connection from being already shared. The rules to decide to keep an idle connection opened or to close it after processing are also governed by the "tune.pool-low-fd-ratio" (default: 20%) and "tune.pool-high-fd-ratio" (default: 25%). These correspond to the percentage of total file descriptors spent in idle connections above which haproxy will respectively refrain from keeping a connection opened after a response, and actively kill idle connections. Some setups using a very high ratio of idle connections, either because of too low a global "maxconn", or due to a lot of HTTP/2 or HTTP/3 traffic on the frontend (few connections) but HTTP/1 connections on the backend, may observe a lower reuse rate because too few connections are kept open. It may be desirable in this case to adjust such thresholds or simply to increase the global "maxconn" value. In some rare cases, when the host name is used to distinguish outgoing TLS connections (e.g. forward proxy), where most request target different hosts, the reuse rate will be very low, and the automatic eviction of rarely used connections will kick in before connections have a chance to be reused, because the mechanism continuously measures the average number of connections needed to deliver the service without exhausting resources. In such situations, setting "pool-low-conn" to a value close to the average expected number of idle connections may help preserve more connections by encouraging threads to setup their own instead of trying to pick other threads' and shrinking the pool of available connections. If a locally hosted server uses a single certificate (with multiple host names or wildcards) and operates multiple sites, it may be more effective to just use "no-sni-auto" on the "server" line to avoid reserving a connection to a single Host name. This will significantly increase the reuse rate. Some servers might perform excessive checks between Host and SNI though, resulting in rejecting subsequent requests, so this option requires preliminary validation. The default behavior ("sni-auto") is to be safe even with such servers. When thread groups are explicitly enabled, it is important to understand that idle connections are only usable between threads from a same group. As such it may happen that unfair load between groups leads to more idle connections being needed, causing a lower reuse rate. The same solution may then be applied (increase global "maxconn" or increase pool ratios). See also: "option http-keep-alive", "pool-conn-name", "pool-max-conn", "pool-purge-delay", "server maxconn", "sni", "thread-groups", "tune.pool-high-fd-ratio", "tune.pool-low-fd-ratio" **`http-send-name-header [
]`** ```haproxy http-send-name-header [
] ``` Add the server name to a request. Use the header string given by `
` May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text
The header string to use to send the server name ``` The "http-send-name-header" statement causes the header field named `
` to be set to the name of the target server at the moment the request is about to be sent on the wire. Any existing occurrences of this header are removed. Upon retries and redispatches, the header field is updated to always reflect the server being attempted to connect to. Given that this header is modified very late in the connection setup, it may have unexpected effects on already modified headers. For example using it with transport-level header such as connection, content-length, transfer-encoding and so on will likely result in invalid requests being sent to the server. This is why following header names are forbidden: host, content-length, transfer-encoding and connection. See also: "server" **`id `** ```haproxy id ``` Set a persistent ID to a proxy. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| yes Arguments: none Set a persistent ID for the proxy. This ID must be unique and positive. An unused ID will automatically be assigned if unset. Due to an historical behavior, value 1 is not used unless explicitly set. Thus, the lowest value automatically assigned will be 2. This ID is currently only returned in statistics. **`ignore-persist { if | unless } `** ```haproxy ignore-persist { if | unless } ``` Declare a condition to ignore persistence May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend no \| no \| yes \| yes By default, when cookie persistence is enabled, every requests containing the cookie are unconditionally persistent (assuming the target server is up and running). The "ignore-persist" statement allows one to declare various ACL-based conditions which, when met, will cause a request to ignore persistence. This is sometimes useful to load balance requests for static files, which often don't require persistence. This can also be used to fully disable persistence for a specific User-Agent (for example, some web crawler bots). The persistence is ignored when an "if" condition is met, or unless an "unless" condition is met. Example: ```text acl url_static path_beg /static /images /img /css acl url_static path_end .gif .png .jpg .css .js ignore-persist if url_static ``` See also: "force-persist", "cookie", and [section 7](/docs/haproxy/acls-and-samples/) about ACL usage. **`load-server-state-from-file { global | local | none }`** ```haproxy load-server-state-from-file { global | local | none } ``` Allow seamless reload of HAProxy May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes This directive points HAProxy to a file where server state from previous running process has been saved. That way, when starting up, before handling traffic, the new process can apply old states to servers exactly has if no reload occurred. The purpose of the "load-server-state-from-file" directive is to tell HAProxy which file to use. For now, only 2 arguments to either prevent loading state or load states from a file containing all backends and servers. The state file can be generated by running the command "show servers state" over the stats socket and redirect output. The format of the file is versioned and is very specific. To understand it, please read the documentation of the "show servers state" command (chapter 9.3 of Management Guide). Arguments: ```text global load the content of the file pointed by the global directive named "server-state-file". local load the content of the file pointed by the directive "server-state-file-name" if set. If not set, then the backend name is used as a file name. none don't load any stat for this backend ``` Notes: - server's IP address is preserved across reloads by default, but the order can be changed thanks to the server's "init-addr" setting. This means that an IP address change performed on the CLI at run time will be preserved, and that any change to the local resolver (e.g. /etc/hosts) will possibly not have any effect if the state file is in use. - server's weight is applied from previous running process unless it has has changed between previous and new configuration files. Example: Minimal configuration global stats socket /tmp/socket server-state-file /tmp/server_state defaults load-server-state-from-file global backend bk server s1 127.0.0.1:22 check weight 11 server s2 127.0.0.1:22 check weight 12 Then one can run: ```text socat /tmp/socket - <<< "show servers state" > /tmp/server_state ``` Content of the file /tmp/server_state would be like this: ```shell 1 # 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0 ``` Example: Minimal configuration global stats socket /tmp/socket server-state-base /etc/haproxy/states defaults load-server-state-from-file local backend bk server s1 127.0.0.1:22 check weight 11 server s2 127.0.0.1:22 check weight 12 Then one can run: ```text socat /tmp/socket - <<< "show servers state bk" > /etc/haproxy/states/bk ``` Content of the file /etc/haproxy/states/bk would be like this: ```shell 1 # 1 bk 1 s1 127.0.0.1 2 0 11 11 4 6 3 4 6 0 0 1 bk 2 s2 127.0.0.1 2 0 12 12 4 6 3 4 6 0 0 ``` See also: "server-state-file", "server-state-file-name", and "show servers state" **`log global`** ```haproxy log global log [len ] [format ] [sample :] [profile ] [ []] no log ``` Enable per-instance logging of events and traffic. May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Prefix: ```text no should be used when the logger list must be flushed. For example, if you don't want to inherit from the default logger list. This prefix does not allow arguments. ``` Arguments: ```text global should be used when the instance's logging parameters are the same as the global ones. This is the most common usage. "global" replaces all log arguments with those of the log entries found in the "global" section. Only one "log global" statement may be used per instance, and this form takes no other parameter. indicates where to send the logs. It takes the same format as for the "global" section's logs, and can be one of: - An IPv4 address optionally followed by a colon (':') and a UDP port. If no port is specified, 514 is used by default (the standard syslog port). - An IPv6 address followed by a colon (':') and optionally a UDP port. If no port is specified, 514 is used by default (the standard syslog port). - A filesystem path to a UNIX domain socket, keeping in mind considerations for chroot (be sure the path is accessible inside the chroot) and uid/gid (be sure the path is appropriately writable). - A file descriptor number in the form "fd@", which may point to a pipe, terminal, or socket. In this case unbuffered logs are used and one writev() call per log is performed. This is a bit expensive but acceptable for most workloads. Messages sent this way will not be truncated but may be dropped, in which case the DroppedLogs counter will be incremented. The writev() call is atomic even on pipes for messages up to PIPE_BUF size, which POSIX recommends to be at least 512 and which is 4096 bytes on most modern operating systems. Any larger message may be interleaved with messages from other processes. Exceptionally for debugging purposes the file descriptor may also be directed to a file, but doing so will significantly slow HAProxy down as non-blocking calls will be ignored. Also there will be no way to purge nor rotate this file without restarting the process. Note that the configured syslog format is preserved, so the output is suitable for use with a TCP syslog server. See also the "short" and "raw" formats below. - "stdout" / "stderr", which are respectively aliases for "fd@1" and "fd@2", see above. - A ring buffer in the form "ring@", which will correspond to an in-memory ring buffer accessible over the CLI using the "show events" command, which will also list existing rings and their sizes. Such buffers are lost on reload or restart but when used as a complement this can help troubleshooting by having the logs instantly available. See section 12.5 about rings. - A log backend in the form "backend@", which will send log messages to the corresponding log backend responsible for sending the message to the proper server according to the backend's lb settings. A log backend is a backend section with "mode log" set (see "mode" for more information). - An explicit stream address prefix such as "tcp@","tcp6@", "tcp4@" or "uxst@" will allocate an implicit ring buffer with a stream forward server targeting the given address. You may want to reference some environment variables in the address parameter, see section 2.3 about environment variables. is an optional maximum line length. Log lines larger than this value will be truncated before being sent. The reason is that syslog servers act differently on log line length. All servers support the default value of 1024, but some servers simply drop larger lines while others do log them. If a server supports long lines, it may make sense to set this value here in order to avoid truncating long lines. Similarly, if a server drops long lines, it is preferable to truncate them before sending them. Accepted values are 80 to 65535 inclusive. The default value of 1024 is generally fine for all standard usages. Some specific cases of long captures or JSON-formatted logs may require larger values. You may also need to increase "tune.http.logurilen" if your request URIs are truncated. A list of comma-separated ranges to identify the logs to sample. This is used to balance the load of the logs to send to the log server. The limits of the ranges cannot be null. They are numbered from 1. The size or period (in number of logs) of the sample must be set with parameter. The size of the sample in number of logs to consider when balancing their logging loads. It is used to balance the load of the logs to send to the syslog server. This size must be greater or equal to the maximum of the high limits of the ranges. (see also parameter). is the log format used when generating syslog messages. It may be one of the following: local Analog to rfc3164 syslog message format except that hostname field is stripped. This is the default. Note: option "log-send-hostname" switches the default to rfc3164. rfc3164 The RFC3164 syslog message format. (https://tools.ietf.org/html/rfc3164) rfc5424 The RFC5424 syslog message format. (https://tools.ietf.org/html/rfc5424) priority A message containing only a level plus syslog facility between angle brackets such as '<63>', followed by the text. The PID, date, time, process name and system name are omitted. This is designed to be used with a local log server. short A message containing only a level between angle brackets such as '<3>', followed by the text. The PID, date, time, process name and system name are omitted. This is designed to be used with a local log server. This format is compatible with what the systemd logger consumes. timed A message containing only a level between angle brackets such as '<3>', followed by ISO date and by the text. The PID, process name and system name are omitted. This is designed to be used with a local log server. iso A message containing only the ISO date, followed by the text. The PID, process name and system name are omitted. This is designed to be used with a local log server. raw A message containing only the text. The level, PID, date, time, process name and system name are omitted. This is designed to be used in containers or during development, where the severity only depends on the file descriptor used (stdout/stderr). name of the optional "log-profile" section that will be considered during the log building process to override some log options. Check out "8.3.5. Log profiles" for more info. must be one of the 24 standard syslog facilities: kern user mail daemon auth syslog lpr news uucp cron auth2 ftp ntp audit alert cron2 local0 local1 local2 local3 local4 local5 local6 local7 Note that the facility is ignored for the "short" and "raw" formats, but still required as a positional field. It is recommended to use "daemon" in this case to make it clear that it's only supposed to be used locally. is optional and can be specified to filter outgoing messages. By default, all messages are sent. If a level is specified, only messages with a severity at least as important as this level will be sent. An optional minimum level can be specified. If it is set, logs emitted with a more severe level than this one will be capped to this level. This is used to avoid sending "emerg" messages on all terminals on some default syslog configurations. Eight levels are known: emerg alert crit err warning notice info debug ``` It is important to keep in mind that it is the frontend which decides what to log from a connection, and that in case of content switching, the log entries from the backend will be ignored. Connections are logged at level "info". However, backend log declaration define how and where servers status changes will be logged. Level "notice" will be used to indicate a server going up, "warning" will be used for termination signals and definitive service termination, and "alert" will be used for when a server goes down. Note: According to RFC3164, messages are truncated to 1024 bytes before being emitted. Example: ```text log global log stdout format short daemon # send log to systemd log stdout format raw daemon # send everything to stdout log stderr format raw daemon notice # send important events to stderr log 127.0.0.1:514 local0 notice # only send important events log tcp@127.0.0.1:514 local0 notice notice # same but limit output # level and send in tcp log "${LOCAL_SYSLOG}:514" local0 notice # send to local server ``` **`log-format `** ```haproxy log-format ``` Specifies the custom log format string to use for traffic logs May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no This directive specifies the log format string that will be used for all logs resulting from traffic passing through the frontend using this line. If the directive is used in a defaults section, all subsequent frontends will use the same log format. Please see [section 8.2.6](/docs/haproxy/configuration-logging/#section-8-2-6) which covers the custom log format string in depth. A specific log-format used only in case of connection error can also be defined, see the "error-log-format" option. "log-format" directive overrides previous "option tcplog", "log-format", "option httplog" and "option httpslog" directives. **`log-format-sd `** ```haproxy log-format-sd ``` Specifies the Custom log format string used to produce RFC5424 structured-data May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no This directive specifies the RFC5424 structured-data log format string that will be used for all logs resulting from traffic passing through the frontend using this line. If the directive is used in a defaults section, all subsequent frontends will use the same log format. Please see [section 8.2.6](/docs/haproxy/configuration-logging/#section-8-2-6) which covers the log format string in depth. See for more information about the RFC5424 structured-data part. Note: This log format string will be used only for loggers that have set log format to "rfc5424". Example: ```text log-format-sd [exampleSDID@1234\ bytes=\"%B\"\ status=\"%ST\"] ``` **`log-steps `** ```haproxy log-steps ``` Specifies at which steps during transaction processing logs should be generated. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no During tcp/http transaction processing, haproxy may produce logs at different steps during the processing (ie: accept, connect, request, response, close). By default, HAProxy emits a single log per transaction, once all of the items used in the logformat expression could be satisfied, which means that in practice the log is usually emitted at the end of the transaction (after the end of the response for HTTP or end of connection for TCP), unless "option logasap" is used. The "log-steps" directive allows to refine the precise instants where logs will be emitted, and even permits to emit multiple logs for a same transaction. Special value 'all' may be used to enable all available log origins, making it possible to track a transaction from accept to close. Individual log origins may also be specified using their names separated by commas to selectively enable when logs should be produced. Common log origins are: accept, connect, request, response, close. Example: ```text frontend myfront option httplog log-steps accept,close #only log accept and close for the txn ``` Log origins specified as "logging steps" (such as accept, close) can be used as-is in log-profiles (after 'on' directive). Combining "log-steps" with log-profiles is really interesting to have fine-grained control over logs automatically generated by haproxy during transaction processing. This setting is only relevant on frontends, it is ignored on backends. See also: "log-profile" **`log-tag `** ```haproxy log-tag ``` Specifies the log tag to use for all outgoing logs May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Sets the tag field in the syslog header to this string. It defaults to the log-tag set in the global section, otherwise the program name as launched from the command line, which usually is "HAProxy". Sometimes it can be useful to differentiate between multiple processes running on the same host, or to differentiate customer instances running in the same process. In the backend, logs about servers up/down will use this tag. As a hint, it can be convenient to set a log-tag related to a hosted customer in a defaults section then put all the frontends and backends for that customer, then start another customer in a new defaults section. See also the global "log-tag" directive. **`max-keep-alive-queue `** ```haproxy max-keep-alive-queue ``` Set the maximum server queue size for maintaining keep-alive connections May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes HTTP keep-alive tries to reuse the same server connection whenever possible, but sometimes it can be counter-productive, for example if a server has a lot of connections while other ones are idle. This is especially true for static servers. The purpose of this setting is to set a threshold on the number of queued connections at which HAProxy stops trying to reuse the same server and prefers to find another one. The default value, -1, means there is no limit. A value of zero means that keep-alive requests will never be queued. For very close servers which can be reached with a low latency and which are not sensible to breaking keep-alive, a low value is recommended (e.g. local static server can use a value of 10 or less). For remote servers suffering from a high latency, higher values might be needed to cover for the latency and/or the cost of picking a different server. Note that this has no impact on responses which are maintained to the same server consecutively to a 401 response. They will still go to the same server even if they have to be queued. See also: "option http-server-close", "option prefer-last-server", server "maxconn" and cookie persistence. **`max-session-srv-conns `** ```haproxy max-session-srv-conns ``` Set the maximum number of outgoing connections we can keep idling for a given client session. The default is 5 (it precisely equals MAX_SRV_LIST which is defined at build time). May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no **`maxconn `** ```haproxy maxconn ``` Fix the maximum number of concurrent connections on a frontend May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text is the maximum number of concurrent connections the frontend will accept to serve. Excess connections will be queued by the system in the socket's listen queue and will be served once a connection closes. ``` If the system supports it, it can be useful on big sites to raise this limit very high so that HAProxy manages connection queues, instead of leaving the clients with unanswered connection attempts. This value should not exceed the global maxconn. Also, keep in mind that a connection contains two buffers of tune.bufsize (16kB by default) each, as well as some other data resulting in about 33 kB of RAM being consumed per established connection. That means that a medium system equipped with 1GB of RAM can withstand around 20000-25000 concurrent connections if properly tuned. Also, when `` is set to large values, it is possible that the servers are not sized to accept such loads, and for this reason it is generally wise to assign them some reasonable connection limits. When this value is set to zero, which is the default, the global "maxconn" value is used. See also: "server", global section's "maxconn", "fullconn" **`mode { tcp|http|log|spop }`** ```haproxy mode { tcp|http|log|spop } ``` Set the running mode or protocol of the instance May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text tcp The instance will work in pure TCP mode. A full-duplex connection will be established between clients and servers, and no layer 7 examination will be performed. This is the default mode. It should be used for SSL, SSH, SMTP, ... http The instance will work in HTTP mode. The client request will be analyzed in depth before connecting to any server. Any request which is not RFC-compliant will be rejected. Layer 7 filtering, processing and switching will be possible. This is the mode which brings HAProxy most of its value. haterm The frontend will work in haterm HTTP benchmark mode. This is not supported by backends. See doc/haterm.txt for details. log When used in a backend section, it will turn the backend into a log backend. Such backend can be used as a log destination for any "log" directive by using the "backend@" syntax. Log messages will be distributed to the servers from the backend according to the lb settings which can be configured using the "balance" keyword. Log backends support UDP servers by prefixing the server's address with the "udp@" prefix. Common backend and server features are supported, but not TCP or HTTP specific ones. spop When used in a backend section, it will turn the backend into a spop backend. This mode is mandatory if the backend contains SPOA servers, but when mode is tcp, it will automatically be converted to mode spop if such servers are detected. ``` When doing content switching, it is mandatory that the frontend and the backend are in the same mode (generally HTTP), otherwise the configuration will be refused. Example: ```text defaults http_instances mode http ``` **`monitor fail { if | unless } `** ```haproxy monitor fail { if | unless } ``` Add a condition to report a failure to a monitor HTTP request. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend no \| yes \| yes \| no Arguments: ```text if the monitor request will fail if the condition is satisfied, and will succeed otherwise. The condition should describe a combined test which must induce a failure if all conditions are met, for instance a low number of servers both in a backend and its backup. unless the monitor request will succeed only if the condition is satisfied, and will fail otherwise. Such a condition may be based on a test on the presence of a minimum number of active servers in a list of backends. ``` This statement adds a condition which can force the response to a monitor request to report a failure. By default, when an external component queries the URI dedicated to monitoring, a 200 response is returned. When one of the conditions above is met, HAProxy will return 503 instead of 200. This is very useful to report a site failure to an external component which may base routing advertisements between multiple sites on the availability reported by HAProxy. In this case, one would rely on an ACL involving the "nbsrv" criterion. Note that "monitor fail" only works in HTTP mode. Both status messages may be tweaked using "errorfile" or "errorloc" if needed. Example: ```text frontend www mode http acl site_dead nbsrv(dynamic) lt 2 acl site_dead nbsrv(static) lt 2 monitor-uri /site_alive monitor fail if site_dead ``` See also: "monitor-uri", "errorfile", "errorloc" **`monitor-uri `** ```haproxy monitor-uri ``` Intercept a URI used by external components' monitor requests May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text is the exact URI which we want to intercept to return HAProxy's health status instead of forwarding the request. ``` When an HTTP request referencing `` will be received on a frontend, HAProxy will not forward it nor log it, but instead will return either "HTTP/1.0 200 OK" or "HTTP/1.0 503 Service unavailable", depending on failure conditions defined with "monitor fail". This is normally enough for any front-end HTTP probe to detect that the service is UP and running without forwarding the request to a backend server. Note that the HTTP method, the version and all headers are ignored, but the request must at least be valid at the HTTP level. This keyword may only be used with an HTTP-mode frontend. Monitor requests are processed very early, just after the request is parsed and even before any "http-request". The only rulesets applied before are the tcp-request ones. They cannot be logged either, and it is the intended purpose. Only one URI may be configured for monitoring; when multiple "monitor-uri" statements are present, the last one will define the URI to be used. They are only used to report HAProxy's health to an upper component, nothing more. However, it is possible to add any number of conditions using "monitor fail" and ACLs so that the result can be adjusted to whatever check can be imagined (most often the number of available servers in a backend). Note: if `` starts by a slash ('/'), the matching is performed against the request's path instead of the request's uri. It is a workaround to let the HTTP/2 requests match the monitor-uri. Indeed, in HTTP/2, clients are encouraged to send absolute URIs only. Example: ```shell # Use /haproxy_test to report HAProxy's status frontend www mode http monitor-uri /haproxy_test ``` See also: "monitor fail" **`option abortonclose`** ```haproxy option abortonclose no option abortonclose ``` Enable or disable early abortion of not started processing when client closes May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none TCP connections support being closed independently in each direction, and a connection with only one direction closed is often said to be "half-closed". Originally when the HTTP ecosystem was mostly made of the "close mode", with only one request and one response per connection before closing, it was pretty frequent to see scripted clients send their request, close the sending side, wait for the response, receive the close indication and be done with this. But with the arrival of keep-alive and more advanced protocols, this practice has practically disappeared and the only cases where a client closes before receiving its response is essentially when the user wants to abort a transfer, or when a timeout strikes and the connection is closed. These two situations (half-closed vs abort) are undistinguishable from the server side (here the HAProxy listener). This is a problem because leaving the connection alive and continuing to process a request when clients abort can cost a lot of resources, particularly if the closure is the result of a user hitting the "reload" button, as it means new requests are queued without the previous ones being aborted. And conversely, systematically aborting when facing such a half-close situation would break a number of TCP applications and even some HTTP ones on internal networks interacting with legacy agents. The "abortonclose" option permits to choose the desired behavior: - when present in a frontend, it will avoid processing TLS handshakes which are pending on a half-closed connection. This can be the result of a user hitting "reload" during an HTTPS request under high load such as a VRRP fail-over between an active HAProxy node and the backup one: all clients reconnect at the same time to the new node, and all have to perform a costly, full TLS handshake. If it takes more than a few seconds, it's likely that some users will give up, and it's pointless to waste CPU cycles on their handshakes. Given the CPU cost of TLS handshakes, it is recommended to leave this option enabled on internet-facing frontends. This is the default for incoming TLS connections. - when present in a backend, it will cause half-closed connections to try to abort a request that was not yet sent to a server (i.e. when it's pending in the queue or when trying to connect). If the request is already being served by a server, then the connection to the server is in turn switched to half-close to indicate the same condition to the server, which will then decide how to proceed. This is the default for HTTP-mode backends. The recommendation is to enable this option on internet-facing TLS endpoints and HTTP services, and to disable it for pure TCP ones as well as unexposed legacy environments. It is enabled by default in HTTP backends, and may be forcefully disabled by prepending the "no" keyword before it, either in the backend section itself, or in the "defaults" section it inherits from. It is also enabled by default for TLS listeners and may be forcefully disabled as well by specifying "no option abortonclose" in the frontend or in the "defaults" section it inherits from. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "timeout queue" and server's "maxconn" and "maxqueue" parameters **`option accept-invalid-http-request (deprecated)`** ```haproxy option accept-invalid-http-request (deprecated) no option accept-invalid-http-request (deprecated) ``` Enable or disable relaxing of HTTP request parsing The "accept-invalid-http-request" keyword is deprecated, use "option accept-unsafe-violations-in-http-request" instead. **`option accept-invalid-http-response (deprecated)`** ```haproxy option accept-invalid-http-response (deprecated) no option accept-invalid-http-response (deprecated) ``` Enable or disable relaxing of HTTP response parsing The "accept-invalid-http-response" keyword is deprecated, use "option accept-unsafe-violations-in-http-response" instead. **`option accept-unsafe-violations-in-http-request`** ```haproxy option accept-unsafe-violations-in-http-request no option accept-unsafe-violations-in-http-request ``` Enable or disable relaxing of HTTP request parsing May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none By default, HAProxy complies with the different HTTP RFCs in terms of message parsing. This means the message parsing is quite strict and causes an error to be returned to the client for malformed messages. This is the desired behavior as such malformed messages are essentially used to build attacks exploiting server weaknesses, and bypass security filtering. Sometimes, a buggy browser will not respect these RCFs for whatever reason (configuration, implementation...) and the issue will not be immediately fixed. In such case, it is possible to relax HAProxy's parser to accept some invalid requests by specifying this option. Most of rules concern the H1 parsing for historical reason. Newer HTTP versions tends to be cleaner and applications follow more stickly these protocols. When this option is set, the following rules are observed: * In H1 only, invalid characters, including NULL character, in header name will not be rejected; however the header will be dropped. * In H1 only, NULL character in header value will be accepted; * In H1 only, characters above 127 in the URI will be accepted. The list of characters allowed to appear in a URI is well defined by RFC3986, and chars 0-31, 32 (space), 34 ('"'), 60 ('<'), 62 ('>'), 92 ('\'), 94 ('^'), 96 ('`'), 123 ('{'), 124 ('|'), 125 ('}'), 127 (delete) and anything above are normally not allowed. In H1, all character between (0..32) and 127 will always be blocked. All characters above 127 (excluded) will also be blocked, except when this option is enabled. Other characters (33..126) will not be checked at all. * In H1 and H2, URLs containing fragment references ('#' after the path) will be accepted; * In H1 only, no check will be performed on the authority for CONNECT requests; * In H1 only, no check will be performed against the authority and the Host header value. * In H1 only, tests on the HTTP version will be relaxed. It will allow HTTP/0.9 GET requests to pass through (no version specified), as well as different protocol names (e.g. RTSP), and multiple digits for both the major and the minor version. * In H1 only, WebSocket (RFC6455) requests failing to present a valid "Sec-Websocket-Key" header field will be accepted. This option should never be enabled by default as it hides application bugs and open security breaches. It should only be deployed after a problem has been confirmed. When this option is enabled, invalid but accepted H1 requests will be captured in order to permit later analysis using the "show errors" request on the UNIX stats socket.Doing this also helps confirming that the issue has been solved. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option accept-unsafe-violations-in-http-response" and "show errors" on the stats socket. **`option accept-unsafe-violations-in-http-response`** ```haproxy option accept-unsafe-violations-in-http-response no option accept-unsafe-violations-in-http-response ``` Enable or disable relaxing of HTTP response parsing May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none Similarly to "option accept-unsafe-violations-in-http-request", this option may be used to relax parsing rules of HTTP responses. It should only be enabled for trusted legacy servers to accept some invalid responses. Most of rules concern the H1 parsing for historical reason. Newer HTTP versions tends to be cleaner and applications follow more stickly these protocols. When this option is set, the following rules are observed: * In H1 only, status codes longer than 3 digits but whose value fits in 16 bits are not rejected. * In H1 only, invalid characters, including NULL character, in header name will not be rejected; however the header will be dropped. * In H1 only, NULL character in header value will be accepted; * In H1 only, empty values or several "chunked" value occurrences for Transfer-Encoding header will be accepted; * In H1 only, no check will be performed against the authority and the Host header value. * In H1 only, tests on the HTTP version will be relaxed. It will allow different protocol names (e.g. RTSP), and multiple digits for both the major and the minor version. * In H1 only, WebSocket (RFC6455) responses failing to present a valid "Sec-Websocket-Accept" header field will be accepted. This option should never be enabled by default as it hides application bugs and open security breaches. It should only be deployed after a problem has been confirmed. When this option is enabled, erroneous header names will still be accepted in responses, but the complete response will be captured in order to permit later analysis using the "show errors" request on the UNIX stats socket. Doing this also helps confirming that the issue has been solved. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option accept-unsafe-violations-in-http-request" and "show errors" on the stats socket. **`option allbackups`** ```haproxy option allbackups no option allbackups ``` Use either all backup servers at a time or only the first one May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none By default, the first operational backup server gets all traffic when normal servers are all down. Sometimes, it may be preferred to use multiple backups at once, because one will not be enough. When "option allbackups" is enabled, the load balancing will be performed among all backup servers when all normal ones are unavailable. The same load balancing algorithm will be used and the servers' weights will be respected. Thus, there will not be any priority order between the backup servers anymore. This option is mostly used with static server farms dedicated to return a "sorry" page when an application is completely offline. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. **`option checkcache`** ```haproxy option checkcache no option checkcache ``` Analyze all server responses and block responses with cacheable cookies May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none Some high-level frameworks set application cookies everywhere and do not always let enough control to the developer to manage how the responses should be cached. When a session cookie is returned on a cacheable object, there is a high risk of session crossing or stealing between users traversing the same caches. In some situations, it is better to block the response than to let some sensitive session information go in the wild. The option "checkcache" enables deep inspection of all server responses for strict compliance with HTTP specification in terms of cacheability. It carefully checks "Cache-control", "Pragma" and "Set-cookie" headers in server response to check if there's a risk of caching a cookie on a client-side proxy. When this option is enabled, the only responses which can be delivered to the client are: - all those without "Set-Cookie" header; - all those with a return code other than 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, 501, provided that the server has not set a "Cache-control: public" header field; - all those that result from a request using a method other than GET, HEAD, OPTIONS, TRACE, provided that the server has not set a 'Cache-Control: public' header field; - those with a 'Pragma: no-cache' header - those with a 'Cache-control: private' header - those with a 'Cache-control: no-store' header - those with a 'Cache-control: max-age=0' header - those with a 'Cache-control: s-maxage=0' header - those with a 'Cache-control: no-cache' header - those with a 'Cache-control: no-cache="set-cookie"' header - those with a 'Cache-control: no-cache="set-cookie,' header (allowing other fields after set-cookie) If a response doesn't respect these requirements, then it will be blocked just as if it was from an "http-response deny" rule, with an "HTTP 502 bad gateway". The session state shows "PH--" meaning that the proxy blocked the response during headers processing. Additionally, an alert will be sent in the logs so that admins are informed that there's something to be fixed. Due to the high impact on the application, the application should be tested in depth with the option enabled before going to production. It is also a good practice to always activate it during tests, even if it is not used in production, as it will report potentially dangerous application behaviors. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. **`option clitcpka`** ```haproxy option clitcpka no option clitcpka ``` Enable or disable the sending of TCP keepalive packets on the client side May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none When there is a firewall or any session-aware component between a client and a server, and when the protocol involves very long sessions with long idle periods (e.g. remote desktops), there is a risk that one of the intermediate components decides to expire a session which has remained idle for too long. Enabling socket-level TCP keep-alives makes the system regularly send packets to the other end of the connection, leaving it active. The delay between keep-alive probes is controlled by the system only and depends both on the operating system and its tuning parameters. It is important to understand that keep-alive packets are neither emitted nor received at the application level. It is only the network stacks which sees them. For this reason, even if one side of the proxy already uses keep-alives to maintain its connection alive, those keep-alive packets will not be forwarded to the other side of the proxy. Please note that this has nothing to do with HTTP keep-alive. Using option "clitcpka" enables the emission of TCP keep-alive probes on the client side of a connection, which should help when session expirations are noticed between HAProxy and a client. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option srvtcpka", "option tcpka" **`option contstats`** ```haproxy option contstats ``` Enable continuous traffic statistics updates May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none By default, counters used for statistics calculation are incremented only when a stream finishes. It works quite well when serving small objects, but with big ones (for example large images or archives) or with A/V streaming, a graph generated from HAProxy counters looks like a hedgehog. With this option enabled counters get incremented frequently along the stream, typically every 5 seconds, which is often enough to produce clean graphs. Recounting touches a hotpath directly so it is not not enabled by default, as it can cause a lot of wakeups for very large session counts and cause a small performance drop. **`option disable-h2-upgrade`** ```haproxy option disable-h2-upgrade no option disable-h2-upgrade ``` Enable or disable the implicit HTTP/2 upgrade from an HTTP/1.x client connection. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none By default, HAProxy is able to implicitly upgrade an HTTP/1.x client connection to an HTTP/2 connection if the first request it receives from a given HTTP connection matches the HTTP/2 connection preface (i.e. the string "PRI \* HTTP/2.0\r\n\r\nSM\r\n\r\n"). This way, it is possible to support HTTP/1.x and HTTP/2 clients on a non-SSL connections. This option must be used to disable the implicit upgrade. Note this implicit upgrade is only supported for HTTP proxies, thus this option too. Note also it is possible to force the HTTP/2 on clear connections by specifying "proto h2" on the bind line. Finally, this option is applied on all bind lines. To disable implicit HTTP/2 upgrades for a specific bind line, it is possible to use "proto h1". If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. **`option dontlog-normal`** ```haproxy option dontlog-normal no option dontlog-normal ``` Enable or disable logging of normal, successful connections May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none There are large sites dealing with several thousand connections per second and for which logging is a major pain. Some of them are even forced to turn logs off and cannot debug production issues. Setting this option ensures that normal connections, those which experience no error, no timeout, no retry nor redispatch, will not be logged. This leaves disk space for anomalies. In HTTP mode, the response status code is checked and return codes 5xx will still be logged. It is strongly discouraged to use this option as most of the time, the key to complex issues is in the normal logs which will not be logged here. If you need to separate logs, see the "log-separate-errors" option instead. See also: "log", "dontlognull", "log-separate-errors" and [section 8](/docs/haproxy/configuration-logging/) about logging. **`option dontlognull`** ```haproxy option dontlognull no option dontlognull ``` Enable or disable logging of null connections May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none In certain environments, there are components which will regularly connect to various systems to ensure that they are still alive. It can be the case from another load balancer as well as from monitoring systems. By default, even a simple port probe or scan will produce a log. If those connections pollute the logs too much, it is possible to enable option "dontlognull" to indicate that a connection on which no data has been transferred will not be logged, which typically corresponds to those probes. Note that errors will still be returned to the client and accounted for in the stats. If this is not what is desired, option http-ignore-probes can be used instead. It is generally recommended not to use this option in uncontrolled environments (e.g. internet), otherwise scans and other malicious activities would not be logged. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "log", "http-ignore-probes", "monitor-uri", and [section 8](/docs/haproxy/configuration-logging/) about logging. **`option external-check`** ```haproxy option external-check ``` Use external processes for server health checks May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes It is possible to test the health of a server using an external command. This is achieved by running the executable set using "external-check command". Requires the "external-check" global to be set. See also: "external-check", "external-check command", "external-check path" **`option forwarded [ proto ]`** ```haproxy option forwarded [ proto ] [ host | host-expr ] [ by | by-expr ] [ by_port | by_port-expr ] [ for | for-expr ] [ for_port | for_port-expr ] no option forwarded ``` Enable insertion of the rfc 7239 forwarded header in requests sent to servers May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text optional argument to specify a custom sample expression those result will be used as 'host' parameter value optional argument to specify a custom sample expression those result will be used as 'by' parameter nodename value optional argument to specify a custom sample expression those result will be used as 'for' parameter nodename value optional argument to specify a custom sample expression those result will be used as 'by' parameter nodeport value optional argument to specify a custom sample expression those result will be used as 'for' parameter nodeport value ``` Since HAProxy works in reverse-proxy mode, servers are losing some request context (request origin: client ip address, protocol used...) A common way to address this limitation is to use the well known x-forward-for and x-forward-\* friends to expose some of this context to the underlying servers/applications. While this use to work and is widely deployed, it is not officially supported by the IETF and can be the root of some interoperability as well as security issues. To solve this, a new HTTP extension has been described by the IETF: forwarded header (RFC7239). More information here: The use of this single header allow to convey numerous details within the same header, and most importantly, fixes the proxy chaining issue. (the rfc allows for multiple chained proxies to append their own values to an already existing header). This option may be specified in defaults, listen or backend section, but it will be ignored for frontend sections. Setting option forwarded without arguments results in using default implicit behavior. Default behavior enables proto parameter and injects original client ip. The equivalent explicit/manual configuration would be: ```text option forwarded proto for ``` The keyword 'by' is used to enable 'by' parameter ("nodename") in forwarded header. It allows to embed request proxy information. 'by' value will be set to proxy ip (destination address) If not available (ie: UNIX listener), 'by' will be set to "unknown". The keyword 'by-expr' is used to enable 'by' parameter ("nodename") in forwarded header. It allows to embed request proxy information. 'by' value will be set to the result of the sample expression ``, if valid, otherwise it will be set to "unknown". The keyword 'for' is used to enable 'for' parameter ("nodename") in forwarded header. It allows to embed request client information. 'for' value will be set to client ip (source address) If not available (ie: UNIX listener), 'for' will be set to "unknown". The keyword 'for-expr' is used to enable 'for' parameter ("nodename") in forwarded header. It allows to embed request client information. 'for' value will be set to the result of the sample expression ``, if valid, otherwise it will be set to "unknown". The keyword 'by_port' is used to provide "nodeport" info to 'by' parameter. 'by_port' requires 'by' or 'by-expr' to be set or it will be ignored. "nodeport" will be set to proxy (destination) port if available, otherwise it will be ignored. The keyword 'by_port-expr' is used to provide "nodeport" info to 'by' parameter. 'by_port-expr' requires 'by' or 'by-expr' to be set or it will be ignored. "nodeport" will be set to the result of the sample expression ``, if valid, otherwise it will be ignored. The keyword 'for_port' is used to provide "nodeport" info to 'for' parameter. 'for_port' requires 'for' or 'for-expr' to be set or it will be ignored. "nodeport" will be set to client (source) port if available, otherwise it will be ignored. The keyword 'for_port-expr' is used to provide "nodeport" info to 'for' parameter. 'for_port-expr' requires 'for' or 'for-expr' to be set or it will be ignored. "nodeport" will be set to the result of the sample expression ``, if valid, otherwise it will be ignored. Examples: ```shell # Those servers want the ip address and protocol of the client request # Resulting header would look like this: # forwarded: proto=http;for=127.0.0.1 backend www_default mode http option forwarded #equivalent to: option forwarded proto for # Those servers want the requested host and hashed client ip address # as well as client source port (you should use seed for xxh32 if ensuring # ip privacy is a concern) # Resulting header would look like this: # forwarded: host="haproxy.org";for="_000000007F2F367E:60138" backend www_host mode http option forwarded host for-expr src,xxh32,hex for_port # Those servers want custom data in host, for and by parameters # Resulting header would look like this: # forwarded: host="host.com";by=_haproxy;for="[::1]:10" backend www_custom mode http option forwarded host-expr str(host.com) by-expr str(_haproxy) for for_port-expr int(10) # Those servers want random 'for' obfuscated identifiers for request # tracing purposes while protecting sensitive IP information # Resulting header would look like this: # forwarded: for=_000000002B1F4D63 backend www_for_hide mode http option forwarded for-expr rand,hex ``` See also: "option forwardfor", "option originalto" **`option forwardfor [ except ] [ header ] [ if-none ]`** ```haproxy option forwardfor [ except ] [ header ] [ if-none ] ``` Enable insertion of the X-Forwarded-For header to requests sent to servers May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is an optional argument used to disable this option for sources matching an optional argument to specify a different "X-Forwarded-For" header name. ``` Since HAProxy works in reverse-proxy mode, the servers see its IP address as their client address. This is sometimes annoying when the client's IP address is expected in server logs. To solve this problem, the well-known HTTP header "X-Forwarded-For" may be added by HAProxy to all requests sent to the server. This header contains a value representing the client's IP address. Since this header is always appended at the end of the existing header list, the server must be configured to always use the last occurrence of this header only. See the server's manual to find how to enable use of this standard header. Note that only the last occurrence of the header must be used, since it is really possible that the client has already brought one. The keyword "header" may be used to supply a different header name to replace the default "X-Forwarded-For". This can be useful where you might already have a "X-Forwarded-For" header from a different application (e.g. stunnel), and you need preserve it. Also if your backend server doesn't use the "X-Forwarded-For" header and requires different one (e.g. Zeus Web Servers require "X-Cluster-Client-IP"). Sometimes, a same HAProxy instance may be shared between a direct client access and a reverse-proxy access (for instance when an SSL reverse-proxy is used to decrypt HTTPS traffic). It is possible to disable the addition of the header for a known source address or network by adding the "except" keyword followed by the network address. In this case, any source IP matching the network will not cause an addition of this header. Most common uses are with private networks or 127.0.0.1. IPv4 and IPv6 are both supported. Alternatively, the keyword "if-none" states that the header will only be added if it is not present. This should only be used in perfectly trusted environment, as this might cause a security issue if headers reaching HAProxy are under the control of the end-user. This option may be specified either in the frontend or in the backend. If at least one of them uses it, the header will be added. Note that the backend's setting of the header subargument takes precedence over the frontend's if both are defined. In the case of the "if-none" argument, if at least one of the frontend or the backend does not specify it, it wants the addition to be mandatory, so it wins. Example: ```shell # Public HTTP address also used by stunnel on the same machine frontend www mode http option forwardfor except 127.0.0.1 # stunnel already adds the header # Those servers want the IP Address in X-Client backend www mode http option forwardfor header X-Client ``` See also: "option httpclose", "option http-server-close", "option http-keep-alive" **`option h1-case-adjust-bogus-client`** ```haproxy option h1-case-adjust-bogus-client no option h1-case-adjust-bogus-client ``` Enable or disable the case adjustment of HTTP/1 headers sent to bogus clients May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none There is no standard case for header names because, as stated in RFC7230, they are case-insensitive. So applications must handle them in a case-insensitive manner. But some bogus applications violate the standards and erroneously rely on the cases most commonly used by browsers. This problem becomes critical with HTTP/2 because all header names must be exchanged in lower case, and HAProxy follows the same convention. All header names are sent in lower case to clients and servers, regardless of the HTTP version. When HAProxy receives an HTTP/1 response, its header names are converted to lower case and manipulated and sent this way to the clients. If a client is known to violate the HTTP standards and to fail to process a response coming from HAProxy, it is possible to transform the lower case header names to a different format when the response is formatted and sent to the client, by enabling this option and specifying the list of headers to be reformatted using the global directives "h1-case-adjust" or "h1-case-adjust-file". This must only be a temporary workaround for the time it takes the client to be fixed, because clients which require such workarounds might be vulnerable to content smuggling attacks and must absolutely be fixed. Please note that this option will not affect standards-compliant clients. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option h1-case-adjust-bogus-server", "h1-case-adjust", "h1-case-adjust-file". **`option h1-case-adjust-bogus-server`** ```haproxy option h1-case-adjust-bogus-server no option h1-case-adjust-bogus-server ``` Enable or disable the case adjustment of HTTP/1 headers sent to bogus servers May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none There is no standard case for header names because, as stated in RFC7230, they are case-insensitive. So applications must handle them in a case-insensitive manner. But some bogus applications violate the standards and erroneously rely on the cases most commonly used by browsers. This problem becomes critical with HTTP/2 because all header names must be exchanged in lower case, and HAProxy follows the same convention. All header names are sent in lower case to clients and servers, regardless of the HTTP version. When HAProxy receives an HTTP/1 request, its header names are converted to lower case and manipulated and sent this way to the servers. If a server is known to violate the HTTP standards and to fail to process a request coming from HAProxy, it is possible to transform the lower case header names to a different format when the request is formatted and sent to the server, by enabling this option and specifying the list of headers to be reformatted using the global directives "h1-case-adjust" or "h1-case-adjust-file". This must only be a temporary workaround for the time it takes the server to be fixed, because servers which require such workarounds might be vulnerable to content smuggling attacks and must absolutely be fixed. Please note that this option will not affect standards-compliant servers. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option h1-case-adjust-bogus-client", "h1-case-adjust", "h1-case-adjust-file". **`option http-buffer-request`** ```haproxy option http-buffer-request no option http-buffer-request ``` Enable or disable waiting for whole HTTP request body before proceeding May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none It is sometimes desirable to wait for the body of an HTTP request before taking a decision. This is what is being done by "balance url_param" for example. The first use case is to buffer requests from slow clients before connecting to the server. Another use case consists in taking the routing decision based on the request body's contents. This option placed in a frontend or backend forces the HTTP processing to wait until either the whole body is received or the request buffer is full. It can have undesired side effects with some applications abusing HTTP by expecting unbuffered transmissions between the frontend and the backend, so this should definitely not be used by default. See also: "option http-no-delay", "timeout http-request", "http-request wait-for-body" **`option http-drop-request-trailers`** ```haproxy option http-drop-request-trailers no option http-drop-request-trailers ``` Drop the HTTP trailers from the request when sent to the server May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| no \| yes Arguments: none When this option is enabled, any HTTP trailers found in a request will be dropped before sending it to the server. RFC9110#section-6.5.1 stated that trailer fields could be merged into the header fields. It should be done on purpose, but it may be a problem for some applications, especially if malicious clients hide sensitive header fields in the trailers part and some intermediaries merge them with headers with no specific checks. In that case, this option can be enabled on the backend to drop any trailer fields found in requests before sending them to the server. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option http-drop-response-trailers" **`option http-drop-response-trailers`** ```haproxy option http-drop-response-trailers no option http-drop-response-trailers ``` Drop the HTTP trailers from the response when sent to the client May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none This option is similar to "option http-drop-request-trailers" but it must be used to drop trailer fields from responses before sending them to clients. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option http-drop-request-trailers" **`option http-ignore-probes`** ```haproxy option http-ignore-probes no option http-ignore-probes ``` Enable or disable logging of null connections and request timeouts May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none Recently some browsers started to implement a "pre-connect" feature consisting in speculatively connecting to some recently visited web sites just in case the user would like to visit them. This results in many connections being established to web sites, which end up in 408 Request Timeout if the timeout strikes first, or 400 Bad Request when the browser decides to close them first. These ones pollute the log and feed the error counters. There was already "option dontlognull" but it's insufficient in this case. Instead, this option does the following things: - prevent any 400/408 message from being sent to the client if nothing was received over a connection before it was closed; - prevent any log from being emitted in this situation; - prevent any error counter from being incremented That way the empty connection is silently ignored. Note that it is better not to use this unless it is clear that it is needed, because it will hide real problems. The most common reason for not receiving a request and seeing a 408 is due to an MTU inconsistency between the client and an intermediary element such as a VPN, which blocks too large packets. These issues are generally seen with POST requests as well as GET with large cookies. The logs are often the only way to detect them. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "log", "dontlognull", "errorfile", and [section 8](/docs/haproxy/configuration-logging/) about logging. **`option http-keep-alive`** ```haproxy option http-keep-alive no option http-keep-alive ``` Enable or disable HTTP keep-alive from client to server for HTTP/1.x connections May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none By default HAProxy operates in keep-alive mode with regards to persistent HTTP/1.x connections: for each connection it processes each request and response, and leaves the connection idle on both sides. This mode may be changed by several options such as "option http-server-close" or "option httpclose". This option allows to set back the keep-alive mode, which can be useful when another mode was used in a defaults section. Setting "option http-keep-alive" enables HTTP keep-alive mode on the client-and server- sides. This provides the lowest latency on the client side (slow network) and the fastest session reuse on the server side at the expense of maintaining idle connections to the servers. In general, it is possible with this option to achieve approximately twice the request rate that the "http-server-close" option achieves on small objects. There are mainly two situations where this option may be useful: - when the server is non-HTTP compliant and authenticates the connection instead of requests (e.g. NTLM authentication) - when the cost of establishing the connection to the server is significant compared to the cost of retrieving the associated object from the server. This last case can happen when the server is a fast static server of cache. At the moment, logs will not indicate whether requests came from the same session or not. The accept date reported in the logs corresponds to the end of the previous request, and the request time corresponds to the time spent waiting for a new request. The keep-alive request time is still bound to the timeout defined by "timeout http-keep-alive" or "timeout http-request" if not set. This option disables and replaces any previous "option httpclose" or "option http-server-close". See also: "option httpclose",, "option http-server-close", "option prefer-last-server" and "option http-pretend-keepalive". **`option http-no-delay`** ```haproxy option http-no-delay no option http-no-delay ``` Instruct the system to favor low interactive delays over performance in HTTP May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none In HTTP, each payload is unidirectional and has no notion of interactivity. Any agent is expected to queue data somewhat for a reasonably low delay. There are some very rare server-to-server applications that abuse the HTTP protocol and expect the payload phase to be highly interactive, with many interleaved data chunks in both directions within a single request. This is absolutely not supported by the HTTP specification and will not work across most proxies or servers. When such applications attempt to do this through HAProxy, it works but they will experience high delays due to the network optimizations which favor performance by instructing the system to wait for enough data to be available in order to only send full packets. Typical delays are around 200 ms per round trip. Note that this only happens with abnormal uses. Normal uses such as CONNECT requests nor WebSockets are not affected. When "option http-no-delay" is present in either the frontend or the backend used by a connection, all such optimizations will be disabled in order to make the exchanges as fast as possible. Of course this offers no guarantee on the functionality, as it may break at any other place. But if it works via HAProxy, it will work as fast as possible. This option should never be used by default, and should never be used at all unless such a buggy application is discovered. The impact of using this option is an increase of bandwidth usage and CPU usage, which may significantly lower performance in high latency environments. See also: "option http-buffer-request" **`option http-pretend-keepalive`** ```haproxy option http-pretend-keepalive no option http-pretend-keepalive ``` Define whether HAProxy will announce keepalive for HTTP/1.x connection to the server or not May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none When running with "option http-server-close" or "option httpclose", HAProxy adds a "Connection: close" header to the HTTP/1.x request forwarded to the server. Unfortunately, when some servers see this header, they automatically refrain from using the chunked encoding for responses of unknown length, while this is totally unrelated. The effect is that a client or a cache could receive an incomplete response without being aware of it, and consider the response complete. By setting "option http-pretend-keepalive", HAProxy will make the server believe it will keep the connection alive. The server will then not fall back to the abnormal undesired above. When HAProxy gets the whole response, it will close the connection with the server just as it would do with the "option httpclose". That way the client gets a normal response and the connection is correctly closed on the server side. It is recommended not to enable this option by default, because most servers will more efficiently close the connection themselves after the last packet, and release its buffers slightly earlier. Also, the added packet on the network could slightly reduce the overall peak performance. However it is worth noting that when this option is enabled, HAProxy will have slightly less work to do. So if HAProxy is the bottleneck on the whole architecture, enabling this option might save a few CPU cycles. This option may be set in backend and listen sections. Using it in a frontend section will be ignored and a warning will be reported during startup. It is a backend related option, so there is no real reason to set it on a frontend. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option httpclose", "option http-server-close", and "option http-keep-alive" **`option http-restrict-req-hdr-names { preserve | delete | reject }`** ```haproxy option http-restrict-req-hdr-names { preserve | delete | reject } ``` Set HAProxy policy about HTTP request header names containing characters outside the "[a-zA-Z0-9-]" charset May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text preserve disable the filtering. It is the default mode for HTTP proxies with no FastCGI application configured. delete remove request headers with a name containing a character outside the "[a-zA-Z0-9-]" charset. It is the default mode for HTTP backends with a configured FastCGI application. reject reject the request with a 403-Forbidden response if it contains a header name with a character outside the "[a-zA-Z0-9-]" charset. ``` This option may be used to restrict the request header names to alphanumeric and hyphen characters ([A-Za-z0-9-]). This may be mandatory to interoperate with non-HTTP compliant servers that fail to handle some characters in header names. It may also be mandatory for FastCGI applications because all non-alphanumeric characters in header names are replaced by an underscore ('\_'). Thus, it is easily possible to mix up header names and bypass some rules. For instance, "X-Forwarded-For" and "X_Forwarded-For" headers are both converted to "HTTP_X_FORWARDED_FOR" in FastCGI. Note this option is evaluated per proxy and after the http-request rules evaluation. **`option http-server-close`** ```haproxy option http-server-close no option http-server-close ``` Enable or disable HTTP/1.x connection closing on the server side May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none By default HAProxy operates in keep-alive mode with regards to persistent HTTP/1.x connections: for each connection it processes each request and response, and leaves the connection idle on both sides. This mode may be changed by several options such as "option http-server-close" or "option httpclose". Setting "option http-server-close" enables HTTP connection-close mode on the server side while keeping the ability to support HTTP keep-alive and pipelining on the client side. This provides the lowest latency on the client side (slow network) and the fastest session reuse on the server side to save server resources, similarly to "option httpclose". It also permits non-keepalive capable servers to be served in keep-alive mode to the clients if they conform to the requirements of RFC7230. Please note that some servers do not always conform to those requirements when they see "Connection: close" in the request. The effect will be that keep-alive will never be used. A workaround consists in enabling "option http-pretend-keepalive". At the moment, logs will not indicate whether requests came from the same session or not. The accept date reported in the logs corresponds to the end of the previous request, and the request time corresponds to the time spent waiting for a new request. The keep-alive request time is still bound to the timeout defined by "timeout http-keep-alive" or "timeout http-request" if not set. This option may be set both in a frontend and in a backend. It is enabled if at least one of the frontend or backend holding a connection has it enabled. It disables and replaces any previous "option httpclose" or "option http-keep-alive". Please check [section 4](/docs/haproxy/proxies/) ("Proxies") to see how this option combines with others when frontend and backend options differ. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option httpclose", "option http-pretend-keepalive" and "option http-keep-alive". **`option http-use-proxy-header`** ```haproxy option http-use-proxy-header no option http-use-proxy-header ``` Make use of non-standard Proxy-Connection header instead of Connection May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none While RFC7230 explicitly states that HTTP/1.1 agents must use the Connection header to indicate their wish of persistent or non-persistent connections, both browsers and proxies ignore this header for proxied connections and make use of the undocumented, non-standard Proxy-Connection header instead. The issue begins when trying to put a load balancer between browsers and such proxies, because there will be a difference between what HAProxy understands and what the client and the proxy agree on. By setting this option in a frontend, HAProxy can automatically switch to use that non-standard header if it sees proxied requests. A proxied request is defined here as one where the URI begins with neither a '/' nor a '\*'. This is incompatible with the HTTP tunnel mode. Note that this option can only be specified in a frontend and will affect the request along its whole life. Also, when this option is set, a request which requires authentication will automatically switch to use proxy authentication headers if it is itself a proxied request. That makes it possible to check or enforce authentication in front of an existing proxy. This option should normally never be used, except in front of a proxy. See also: "option httpclose", and "option http-server-close". **`option httpchk`** ```haproxy option httpchk option httpchk option httpchk option httpchk option httpchk ``` Enables HTTP protocol to check on the servers health May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the optional HTTP method used with the requests. When not set, the "OPTIONS" method is used, as it generally requires low server processing and is easy to filter out from the logs. Any method may be used, though it is not recommended to invent non-standard ones. is the URI referenced in the HTTP requests. It defaults to " / " which is accessible by default on almost any server, but may be changed to any other URI. Query strings are permitted. is the optional HTTP version string. It defaults to "HTTP/1.0" but some servers might behave incorrectly in HTTP 1.0, so turning it to HTTP/1.1 may sometimes help. Note that the Host field is mandatory in HTTP/1.1. is the optional HTTP Host header value. It is not set by default. It is a log-format string. ``` By default, server health checks only consist in trying to establish a TCP connection. When "option httpchk" is specified, a complete HTTP request is sent once the TCP connection is established, and responses 2xx and 3xx are considered valid, while all other ones indicate a server failure, including the lack of any response. Combined with "http-check" directives, it is possible to customize the request sent during the HTTP health checks or the matching rules on the response. It is also possible to configure a send/expect sequence, just like with the directive "tcp-check" for TCP health checks. The server configuration is used by default to open connections to perform HTTP health checks. By it is also possible to overwrite server parameters using "http-check connect" rules. "httpchk" option does not necessarily require an HTTP backend, it also works with plain TCP backends. This is particularly useful to check simple scripts bound to some dedicated ports using the inetd daemon. However, it will always internally relies on an HTX multiplexer. Thus, it means the request formatting and the response parsing will be strict. Examples: ```shell # Relay HTTPS traffic to Apache instance and check service availability # using HTTP request "OPTIONS * HTTP/1.1" on port 80. backend https_relay mode tcp option httpchk OPTIONS * HTTP/1.1 http-check send hdr Host www server apache1 192.168.1.1:443 check port 80 ``` See also: "option ssl-hello-chk", "option smtpchk", "option mysql-check", "option pgsql-check", "http-check" and the "check", "port" and "inter" server options. **`option httpclose`** ```haproxy option httpclose no option httpclose ``` Enable or disable HTTP/1.x connection closing May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none By default HAProxy operates in keep-alive mode with regards to persistent HTTP/1.x connections: for each connection it processes each request and response, and leaves the connection idle on both sides. This mode may be changed by several options such as "option http-server-close" or "option httpclose". If "option httpclose" is set, HAProxy will close the client or the server connection, depending where the option is set. The frontend is considered for client connections while the backend is considered for server ones. If the option is set on a listener, it is applied both on client and server connections. It will check if a "Connection: close" header is already set in each direction, and will add one if missing. This option may also be combined with "option http-pretend-keepalive", which will disable sending of the "Connection: close" request header, but will still cause the connection to be closed once the whole response is received. It disables and replaces any previous "option http-server-close" or "option http-keep-alive". If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option http-server-close". **`option httplog [ clf ]`** ```haproxy option httplog [ clf ] ``` Enable logging of HTTP request, stream state and timers May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text clf if the "clf" argument is added, then the output format will be the CLF format instead of HAProxy's default HTTP format. You can use this when you need to feed HAProxy's logs through a specific log analyzer which only support the CLF format and which is not extensible. ``` By default, the log output format is very poor, as it only contains the source and destination addresses, and the instance name. By specifying "option httplog", each log line turns into a much richer format including, but not limited to, the HTTP request, the connection timers, the stream status, the connections numbers, the captured headers and cookies, the frontend, backend and server name, and of course the source address and ports. Specifying only "option httplog" will automatically clear the 'clf' mode if it was set by default. "option httplog" overrides any previous "log-format" directive. See also: [section 8](/docs/haproxy/configuration-logging/) about logging. **`option httpslog`** ```haproxy option httpslog ``` Enable logging of HTTPS request, stream state and timers May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no By default, the log output format is very poor, as it only contains the source and destination addresses, and the instance name. By specifying "option httpslog", each log line turns into a much richer format including, but not limited to, the HTTP request, the connection timers, the stream status, the connections numbers, the captured headers and cookies, the frontend, backend and server name, the SSL certificate verification and SSL handshake statuses, and of course the source address and ports. "option httpslog" overrides any previous "log-format" directive. See also: [section 8](/docs/haproxy/configuration-logging/) about logging. **`option idle-close-on-response`** ```haproxy option idle-close-on-response no option idle-close-on-response ``` Avoid closing idle frontend connections if a soft stop is in progress May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none By default, idle connections will be closed during a soft stop. In some environments, a client talking to the proxy may have prepared some idle connections in order to send requests later. If there is no proper retry on write errors, this can result in errors while haproxy is reloading. Even though a proper implementation should retry on connection/write errors, this option was introduced to support backwards compatibility with haproxy prior to version 2.4. Indeed before v2.4, haproxy used to wait for a last request and response to add a "connection: close" header before closing, thus notifying the client that the connection would not be reusable. In a real life example, this behavior was seen in AWS using the ALB in front of a haproxy. The end result was ALB sending 502 during haproxy reloads. Users are warned that using this option may increase the number of old processes if connections remain idle for too long. Adjusting the client timeouts and/or the "hard-stop-after" parameter accordingly might be needed in case of frequent reloads. See also: "timeout client", "timeout client-fin", "timeout http-request", "hard-stop-after" **`option independent-streams`** ```haproxy option independent-streams no option independent-streams ``` Enable or disable independent timeout processing for both directions May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none By default, when data is sent over a socket, both the write timeout and the read timeout for that socket are refreshed, because we consider that there is activity on that socket, and we have no other means of guessing if we should receive data or not. While this default behavior is desirable for almost all applications, there exists a situation where it is desirable to disable it, and only refresh the read timeout if there are incoming data. This happens on streams with large timeouts and low amounts of exchanged data such as telnet session. If the server suddenly disappears, the output data accumulates in the system's socket buffers, both timeouts are correctly refreshed, and there is no way to know the server does not receive them, so we don't timeout. However, when the underlying protocol always echoes sent data, it would be enough by itself to detect the issue using the read timeout. Note that this problem does not happen with more verbose protocols because data won't accumulate long in the socket buffers. When this option is set on the frontend, it will disable read timeout updates on data sent to the client. There probably is little use of this case. When the option is set on the backend, it will disable read timeout updates on data sent to the server. Doing so will typically break large HTTP posts from slow lines, so use it with caution. See also: "timeout client", "timeout server" and "timeout tunnel" **`option ldap-check`** ```haproxy option ldap-check ``` Use LDAPv3 health checks for server testing May be used in the following contexts: tcp May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none It is possible to test that the server correctly talks LDAPv3 instead of just testing that it accepts the TCP connection. When this option is set, an LDAPv3 anonymous simple bind message is sent to the server, and the response is analyzed to find an LDAPv3 bind response message. The server is considered valid only when the LDAP response contains success resultCode (). Logging of bind requests is server dependent see your documentation how to configure it. Example: ```text option ldap-check ``` See also: "option httpchk" **`option log-health-checks`** ```haproxy option log-health-checks no option log-health-checks ``` Enable or disable logging of health checks status updates May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none By default, failed health check are logged if server is UP and successful health checks are logged if server is DOWN, so the amount of additional information is limited. When this option is enabled, any change of the health check status or to the server's health will be logged, so that it becomes possible to know that a server was failing occasional checks before crashing, or exactly when it failed to respond a valid HTTP status, then when the port started to reject connections, then when the server stopped responding at all. Note that status changes not caused by health checks (e.g. enable/disable on the CLI) are intentionally not logged by this option. See also: "option httpchk", "option ldap-check", "option mysql-check", "option pgsql-check", "option redis-check", "option smtpchk", "option tcp-check", "log" and [section 8](/docs/haproxy/configuration-logging/) about logging. **`option log-separate-errors`** ```haproxy option log-separate-errors no option log-separate-errors ``` Change log level for non-completely successful connections May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none Sometimes looking for errors in logs is not easy. This option makes HAProxy raise the level of logs containing potentially interesting information such as errors, timeouts, retries, redispatches, or HTTP status codes 5xx. The level changes from "info" to "err". This makes it possible to log them separately to a different file with most syslog daemons. Be careful not to remove them from the original file, otherwise you would lose ordering which provides very important information. Using this option, large sites dealing with several thousand connections per second may log normal traffic to a rotating buffer and only archive smaller error logs. See also: "log", "dontlognull", "dontlog-normal" and [section 8](/docs/haproxy/configuration-logging/) about logging. **`option logasap`** ```haproxy option logasap no option logasap ``` Enable or disable early logging. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none By default, logs are emitted when all the log format aliases and sample fetches used in the definition of the log-format string return a value, or when the stream is terminated. This allows the built in log-format strings to account for the transfer time, or the number of bytes in log messages. When handling long lived connections such as large file transfers or RDP, it may take a while for the request or connection to appear in the logs. Using "option logasap", the log message is created as soon as the server connection is established in mode tcp, or as soon as the server sends the complete headers in mode http. Missing information in the logs will be the total number of bytes which will only indicate the amount of data transferred before the message was created and the total time which will not take the remainder of the connection life or transfer time into account. For the case of HTTP, it is good practice to capture the Content-Length response header so that the logs at least indicate how many bytes are expected to be transferred. Examples: ```text listen http_proxy 0.0.0.0:80 mode http option httplog option logasap log 192.168.2.200 local3 ``` ```text >>> Feb 6 12:14:14 localhost \ haproxy[14389]: 10.0.1.2:33317 [06/Feb/2009:12:14:14.655] http-in \ static/srv1 9/10/7/14/+30 200 +243 - - ---- 3/1/1/1/0 1/0 \ "GET /image.iso HTTP/1.0" ``` See also: "option httplog", "capture response header", and [section 8](/docs/haproxy/configuration-logging/) about logging. **`option mysql-check [ user [ { post-41 | pre-41 | post-80 } ] ]`** ```haproxy option mysql-check [ user [ { post-41 | pre-41 | post-80 } ] ] ``` Use MySQL health checks for server testing May be used in the following contexts: tcp May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text This is the username which will be used when connecting to MySQL server. post-41 Send post v4.1 client compatible checks (the default) pre-41 Send pre v4.1 client compatible checks post-80 Send post v8.0 client compatible checks with CLIENT_PLUGIN_AUTH capability set and mysql_native_password as the authentication plugin. Use this option when connecting to MySQL 8.0+ servers where the health check user is created with mysql_native_password authentication. Example: CREATE USER 'haproxy'@'%' IDENTIFIED WITH mysql_native_password BY ''; ``` If you specify a username, the check consists of sending two MySQL packet, one Client Authentication packet, and one QUIT packet, to correctly close MySQL session. We then parse the MySQL Handshake Initialization packet and/or Error packet. It is a basic but useful test which does not produce error nor aborted connect on the server. However, it requires an unlocked authorised user without a password. To create a basic limited user in MySQL with optional resource limits: ```text CREATE USER ''@'' /*!50701 WITH MAX_QUERIES_PER_HOUR 1 MAX_UPDATES_PER_HOUR 0 */ /*M!100201 MAX_STATEMENT_TIME 0.0001 */; ``` If you don't specify a username (it is deprecated and not recommended), the check only consists in parsing the Mysql Handshake Initialization packet or Error packet, we don't send anything in this mode. It was reported that it can generate lockout if check is too frequent and/or if there is not enough traffic. In fact, you need in this case to check MySQL "max_connect_errors" value as if a connection is established successfully within fewer than MySQL "max_connect_errors" attempts after a previous connection was interrupted, the error count for the host is cleared to zero. If HAProxy's server get blocked, the "FLUSH HOSTS" statement is the only way to unblock it. Remember that this does not check database presence nor database consistency. To do this, you can use an external check with xinetd for example. The check requires MySQL \>=3.22, for older version, please use TCP check. Most often, an incoming MySQL server needs to see the client's IP address for various purposes, including IP privilege matching and connection logging. When possible, it is often wise to masquerade the client's IP address when connecting to the server using the "usesrc" argument of the "source" keyword, which requires the transparent proxy feature to be compiled in, and the MySQL server to route the client via the machine hosting HAProxy. See also: "option httpchk" **`option nolinger`** ```haproxy option nolinger no option nolinger ``` Enable or disable immediate session resource cleaning after close May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none When clients or servers abort connections in a dirty way (e.g. they are physically disconnected), the session timeouts triggers and the session is closed. But it will remain in FIN_WAIT1 state for some time in the system, using some resources and possibly limiting the ability to establish newer connections. When this happens, it is possible to activate "option nolinger" which forces the system to immediately remove any socket's pending data on close. Thus, a TCP RST is emitted, any pending data are truncated, and the session is instantly purged from the system's tables. The generally visible effect for a client is that responses are truncated if the close happens with a last block of data (e.g. on a redirect or error response). On the server side, it may help release the source ports immediately when forwarding a client aborts in tunnels. In both cases, TCP resets are emitted and given that the session is instantly destroyed, there will be no retransmit. On a lossy network this can increase problems, especially when there is a firewall on the lossy side, because the firewall might see and process the reset (hence purge its session) and block any further traffic for this session,, including retransmits from the other side. So if the other side doesn't receive it, it will never receive any RST again, and the firewall might log many blocked packets. For all these reasons, it is strongly recommended NOT to use this option, unless absolutely needed as a last resort. In most situations, using the "client-fin" or "server-fin" timeouts achieves similar results with a more reliable behavior. On Linux it's also possible to use the "tcp-ut" bind or server setting. This option may be used both on frontends and backends, depending on the side where it is required. Use it on the frontend for clients, and on the backend for servers. While this option is technically supported in "defaults" sections, it must really not be used there as it risks to accidentally propagate to sections that must no use it and to cause problems there. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "timeout client-fin", "timeout server-fin", "tcp-ut" bind or server keywords. **`option originalto [ except ] [ header ]`** ```haproxy option originalto [ except ] [ header ] ``` Enable insertion of the X-Original-To header to requests sent to servers May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: ```text is an optional argument used to disable this option for sources matching an optional argument to specify a different "X-Original-To" header name. ``` Since HAProxy can work in transparent mode, every request from a client can be redirected to the proxy and HAProxy itself can proxy every request to a complex SQUID environment and the destination host from SO_ORIGINAL_DST will be lost. This is annoying when you want access rules based on destination ip addresses. To solve this problem, a new HTTP header "X-Original-To" may be added by HAProxy to all requests sent to the server. This header contains a value representing the original destination IP address. Since this must be configured to always use the last occurrence of this header only. Note that only the last occurrence of the header must be used, since it is really possible that the client has already brought one. The keyword "header" may be used to supply a different header name to replace the default "X-Original-To". This can be useful where you might already have a "X-Original-To" header from a different application, and you need preserve it. Also if your backend server doesn't use the "X-Original-To" header and requires different one. Sometimes, a same HAProxy instance may be shared between a direct client access and a reverse-proxy access (for instance when an SSL reverse-proxy is used to decrypt HTTPS traffic). It is possible to disable the addition of the header for a known destination address or network by adding the "except" keyword followed by the network address. In this case, any destination IP matching the network will not cause an addition of this header. Most common uses are with private networks or 127.0.0.1. IPv4 and IPv6 are both supported. This option may be specified either in the frontend or in the backend. If at least one of them uses it, the header will be added. Note that the backend's setting of the header subargument takes precedence over the frontend's if both are defined. Examples: ```shell # Original Destination address frontend www mode http option originalto except 127.0.0.1 # Those servers want the IP Address in X-Client-Dst backend www mode http option originalto header X-Client-Dst ``` See also: "option httpclose", "option http-server-close". **`option persist`** ```haproxy option persist no option persist ``` Enable or disable forced persistence on down servers May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none When an HTTP request reaches a backend with a cookie which references a dead server, by default it is redispatched to another server. It is possible to force the request to be sent to the dead server first using "option persist" if absolutely needed. A common use case is when servers are under extreme load and spend their time flapping. In this case, the users would still be directed to the server they opened the session on, in the hope they would be correctly served. It is recommended to use "option redispatch" in conjunction with this option so that in the event it would not be possible to connect to the server at all (server definitely dead), the client would finally be redirected to another valid server. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option redispatch", "retries", "force-persist" **`option pgsql-check user `** ```haproxy option pgsql-check user ``` Use PostgreSQL health checks for server testing May be used in the following contexts: tcp May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text This is the username which will be used when connecting to PostgreSQL server. ``` The check sends a PostgreSQL StartupMessage and waits for either Authentication request or ErrorResponse message. It is a basic but useful test which does not produce error nor aborted connect on the server. This check is identical with the "mysql-check". See also: "option httpchk" **`option prefer-last-server`** ```haproxy option prefer-last-server no option prefer-last-server ``` Allow multiple load balanced requests to remain on the same server May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none When the load balancing algorithm in use is not deterministic, and a previous request was sent to a server to which HAProxy still holds a connection, it is sometimes desirable that subsequent requests on a same session go to the same server as much as possible. Note that this is different from persistence, as we only indicate a preference which HAProxy tries to apply without any form of warranty. The real use is for keep-alive connections sent to servers. When this option is used, HAProxy will try to reuse the same connection that is attached to the server instead of rebalancing to another server, causing a close of the connection. This can make sense for static file servers. It does not make much sense to use this in combination with hashing algorithms. Note, HAProxy already automatically tries to stick to a server which sends a 401 or to a proxy which sends a 407 (authentication required), when the load balancing algorithm is not deterministic. This is mandatory for use with the broken NTLM authentication challenge, and significantly helps in troubleshooting some faulty applications. Option prefer-last-server might be desirable in these environments as well, to avoid redistributing the traffic after every other response. It may be useful to precise here, which load balancing algorithms are considered deterministic. Deterministic algorithms will always select the same server for a given client data, assuming the set of available servers has not changed. In general, deterministic algorithms involve hashing or lookups on the incoming requests to choose the target server. However, this is not always the case; "static-rr", for example, can be also considered as deterministic because the server choice is based on the server's static weight, making the selection predictable. "sticky" algorithm provides deterministic routing for the returning clients. As for non-deterministic algorithms, these algorithms select a server based on dynamic server state or simple rotation, so two consecutive requests are not guaranteed to land on the same server. option prefer-last-server is designed specifically for these. roundrobin, leastconn are examples of such algorithms. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option http-keep-alive" **`option redispatch`** ```haproxy option redispatch option redispatch no option redispatch ``` Enable or disable session redistribution in case of connection failure May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text The optional integer value that controls how often redispatches occur when retrying connections. Positive value P indicates a redispatch is desired on every Pth retry, and negative value N indicate a redispatch is desired on the Nth retry prior to the last retry. For example, the default of -1 preserves the historical behavior of redispatching on the last retry, a positive value of 1 would indicate a redispatch on every retry, and a positive value of 3 would indicate a redispatch on every third retry. You can disable redispatches with a value of 0. ``` In HTTP mode, if a server designated by a cookie is down, clients may definitely stick to it, for example when using "option persist" or "force-persist", because they cannot flush the cookie, so they will not be able to access the service anymore. Specifying "option redispatch" will allow the proxy to break cookie or consistent hash based persistence and redistribute them to a working server. Active servers are selected from a subset of the list of available servers. Active servers that are not down or in maintenance (i.e., whose health is not checked or that have been checked as "up"), are selected in the following order: ```text 1. Any active, non-backup server, if any, or, 2. If the "allbackups" option is not set, the first backup server in the list, or 3. If the "allbackups" option is set, any backup server. ``` When a retry occurs, HAProxy tries to select another server than the last one. The new server is selected from the current list of servers. Sometimes, if the list is updated between retries (e.g., if numerous retries occur and last longer than the time needed to check that a server is down, remove it from the list and fall back on the list of backup servers), connections may be redirected to a backup server, though. It also allows to retry connections to another server in case of multiple connection failures. Of course, it requires having "retries" set to a nonzero value. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option persist", "force-persist", "retries" **`option redis-check`** ```haproxy option redis-check ``` Use redis health checks for server testing May be used in the following contexts: tcp May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none It is possible to test that the server correctly talks REDIS protocol instead of just testing that it accepts the TCP connection. When this option is set, a PING redis command is sent to the server, and the response is analyzed to find the "+PONG" response message. Example: ```text option redis-check ``` See also: "option httpchk", "option tcp-check", "tcp-check expect" **`option smtpchk`** ```haproxy option smtpchk option smtpchk ``` Use SMTP health checks for server testing May be used in the following contexts: tcp May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is an optional argument. It is the "hello" command to use. It can be either "HELO" (for SMTP) or "EHLO" (for ESMTP). All other values will be turned into the default command ("HELO"). is the domain name to present to the server. It may only be specified (and is mandatory) if the hello command has been specified. By default, "localhost" is used. ``` When "option smtpchk" is set, the health checks will consist in TCP connections followed by an SMTP command. By default, this command is "HELO localhost". The server's return code is analyzed and only return codes starting with a "2" will be considered as valid. All other responses, including a lack of response will constitute an error and will indicate a dead server. This test is meant to be used with SMTP servers or relays. Depending on the request, it is possible that some servers do not log each connection attempt, so you may want to experiment to improve the behavior. Using telnet on port 25 is often easier than adjusting the configuration. Most often, an incoming SMTP server needs to see the client's IP address for various purposes, including spam filtering, anti-spoofing and logging. When possible, it is often wise to masquerade the client's IP address when connecting to the server using the "usesrc" argument of the "source" keyword, which requires the transparent proxy feature to be compiled in. Example: ```text option smtpchk HELO mydomain.org ``` See also: "option httpchk", "source" option socket-stats no option socket-stats Enable or disable collecting & providing separate statistics for each socket. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none **`option splice-auto`** ```haproxy option splice-auto no option splice-auto ``` Enable or disable automatic kernel acceleration on sockets in both directions May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none When this option is enabled either on a frontend or on a backend, HAProxy will automatically evaluate the opportunity to use kernel tcp splicing to forward data between the client and the server, in either direction. HAProxy uses heuristics to estimate if kernel splicing might improve performance or not. Both directions are handled independently. Note that the heuristics used are not much aggressive in order to limit excessive use of splicing. This option requires splicing to be enabled at compile time, and may be globally disabled with the global option "nosplice". Since splice uses pipes, using it requires that there are enough spare pipes. Important note: kernel-based TCP splicing is a Linux-specific feature which first appeared in kernel 2.6.25. It offers kernel-based acceleration to transfer data between sockets without copying these data to user-space, thus providing noticeable performance gains and CPU cycles savings. Since many early implementations are buggy, corrupt data and/or are inefficient, this feature is not enabled by default, and it should be used with extreme care. While it is not possible to detect the correctness of an implementation, 2.6.29 is the first version offering a properly working implementation. In case of doubt, splicing may be globally disabled using the global "nosplice" keyword. Example: ```text option splice-auto ``` If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option splice-request", "option splice-response", and global options "nosplice" and "maxpipes" **`option splice-request`** ```haproxy option splice-request no option splice-request ``` Enable or disable automatic kernel acceleration on sockets for requests May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none When this option is enabled either on a frontend or on a backend, HAProxy will use kernel tcp splicing whenever possible to forward data going from the client to the server. It might still use the recv/send scheme if there are no spare pipes left. This option requires splicing to be enabled at compile time, and may be globally disabled with the global option "nosplice". Since splice uses pipes, using it requires that there are enough spare pipes. Important note: see "option splice-auto" for usage limitations. Example: ```text option splice-request ``` If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option splice-auto", "option splice-response", and global options "nosplice" and "maxpipes" **`option splice-response`** ```haproxy option splice-response no option splice-response ``` Enable or disable automatic kernel acceleration on sockets for responses May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none When this option is enabled either on a frontend or on a backend, HAProxy will use kernel tcp splicing whenever possible to forward data going from the server to the client. It might still use the recv/send scheme if there are no spare pipes left. This option requires splicing to be enabled at compile time, and may be globally disabled with the global option "nosplice". Since splice uses pipes, using it requires that there are enough spare pipes. Important note: see "option splice-auto" for usage limitations. Example: ```text option splice-response ``` If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option splice-auto", "option splice-request", and global options "nosplice" and "maxpipes" **`option spop-check`** ```haproxy option spop-check ``` Use SPOP health checks for server testing May be used in the following contexts: tcp May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none It is possible to test that the server correctly talks SPOP protocol instead of just testing that it accepts the TCP connection. When this option is set, a HELLO handshake is performed between HAProxy and the server, and the response is analyzed to check no error is reported. Example: ```text option spop-check ``` See also: "option httpchk" **`option srvtcpka`** ```haproxy option srvtcpka no option srvtcpka ``` Enable or disable the sending of TCP keepalive packets on the server side May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none When there is a firewall or any session-aware component between a client and a server, and when the protocol involves very long sessions with long idle periods (e.g. remote desktops), there is a risk that one of the intermediate components decides to expire a session which has remained idle for too long. Enabling socket-level TCP keep-alives makes the system regularly send packets to the other end of the connection, leaving it active. The delay between keep-alive probes is controlled by the system only and depends both on the operating system and its tuning parameters. It is important to understand that keep-alive packets are neither emitted nor received at the application level. It is only the network stacks which sees them. For this reason, even if one side of the proxy already uses keep-alives to maintain its connection alive, those keep-alive packets will not be forwarded to the other side of the proxy. Please note that this has nothing to do with HTTP keep-alive. Using option "srvtcpka" enables the emission of TCP keep-alive probes on the server side of a connection, which should help when session expirations are noticed between HAProxy and a server. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option clitcpka", "option tcpka" **`option ssl-hello-chk`** ```haproxy option ssl-hello-chk ``` Use SSLv3 client hello health checks for server testing May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none When some SSL-based protocols are relayed in TCP mode through HAProxy, it is possible to test that the server correctly talks SSL instead of just testing that it accepts the TCP connection. When "option ssl-hello-chk" is set, pure SSLv3 client hello messages are sent once the connection is established to the server, and the response is analyzed to find an SSL server hello message. The server is considered valid only when the response contains this server hello message. All servers tested till there correctly reply to SSLv3 client hello messages, and most servers tested do not even log the requests containing only hello messages, which is appreciable. Note that this check works even when SSL support was not built into HAProxy because it forges the SSL message. When SSL support is available, it is best to use native SSL health checks instead of this one. See also: "option httpchk", "check-ssl" **`option tcp-check`** ```haproxy option tcp-check ``` Perform health checks using tcp-check send/expect sequences May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes This health check method is intended to be combined with "tcp-check" command lists in order to support send/expect types of health check sequences. TCP checks currently support 4 modes of operations: - no "tcp-check" directive: the health check only consists in a connection attempt, which remains the default mode. - "tcp-check send" or "tcp-check send-binary" only is mentioned: this is used to send a string along with a connection opening. With some protocols, it helps sending a "QUIT" message for example that prevents the server from logging a connection error for each health check. The check result will still be based on the ability to open the connection only. - "tcp-check expect" only is mentioned: this is used to test a banner. The connection is opened and HAProxy waits for the server to present some contents which must validate some rules. The check result will be based on the matching between the contents and the rules. This is suited for POP, IMAP, SMTP, FTP, SSH, TELNET. - both "tcp-check send" and "tcp-check expect" are mentioned: this is used to test a hello-type protocol. HAProxy sends a message, the server responds and its response is analyzed. the check result will be based on the matching between the response contents and the rules. This is often suited for protocols which require a binding or a request/response model. LDAP, MySQL, Redis and SSL are example of such protocols, though they already all have their dedicated checks with a deeper understanding of the respective protocols. In this mode, many questions may be sent and many answers may be analyzed. A fifth mode can be used to insert comments in different steps of the script. For each tcp-check rule you create, you can add a "comment" directive, followed by a string. This string will be reported in the log and stderr in debug mode. It is useful to make user-friendly error reporting. The "comment" is of course optional. During the execution of a health check, a variable scope is made available to store data samples, using the "tcp-check set-var" operation. Freeing those variable is possible using "tcp-check unset-var". Examples: ```shell # perform a POP check (analyze only server's banner) option tcp-check tcp-check expect string +OK\ POP3\ ready comment POP\ protocol # perform an IMAP check (analyze only server's banner) option tcp-check tcp-check expect string *\ OK\ IMAP4\ ready comment IMAP\ protocol # look for the redis master server after ensuring it speaks well # redis protocol, then it exits properly. # (send a command then analyze the response 3 times) option tcp-check tcp-check comment PING\ phase tcp-check send PING\r\n tcp-check expect string +PONG tcp-check comment role\ check tcp-check send info\ replication\r\n tcp-check expect string role:master tcp-check comment QUIT\ phase tcp-check send QUIT\r\n tcp-check expect string +OK forge a HTTP request, then analyze the response (send many headers before analyzing) option tcp-check tcp-check comment forge\ and\ send\ HTTP\ request tcp-check send HEAD\ /\ HTTP/1.1\r\n tcp-check send Host:\ www.mydomain.com\r\n tcp-check send User-Agent:\ HAProxy\ tcpcheck\r\n tcp-check send \r\n tcp-check expect rstring HTTP/1\..\ (2..|3..) comment check\ HTTP\ response ``` See also: "tcp-check connect", "tcp-check expect" and "tcp-check send". **`option tcp-smart-accept`** ```haproxy option tcp-smart-accept no option tcp-smart-accept ``` Enable or disable the saving of one ACK packet during the accept sequence May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: none When an HTTP connection request comes in, the system acknowledges it on behalf of HAProxy, then the client immediately sends its request, and the system acknowledges it too while it is notifying HAProxy about the new connection. HAProxy then reads the request and responds. This means that we have one TCP ACK sent by the system for nothing, because the request could very well be acknowledged by HAProxy when it sends its response. For this reason, in HTTP mode, HAProxy automatically asks the system to avoid sending this useless ACK on platforms which support it (currently at least Linux). It must not cause any problem, because the system will send it anyway after 40 ms if the response takes more time than expected to come. During complex network debugging sessions, it may be desirable to disable this optimization because delayed ACKs can make troubleshooting more complex when trying to identify where packets are delayed. It is then possible to fall back to normal behavior by specifying "no option tcp-smart-accept". It is also possible to force it for non-HTTP proxies by simply specifying "option tcp-smart-accept". For instance, it can make sense with some services such as SMTP where the server speaks first. It is recommended to avoid forcing this option in a defaults section. In case of doubt, consider setting it back to automatic values by prepending the "default" keyword before it, or disabling it using the "no" keyword. See also: "option tcp-smart-connect" **`option tcp-smart-connect`** ```haproxy option tcp-smart-connect no option tcp-smart-connect ``` Enable or disable the saving of one ACK packet during the connect sequence May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none On certain systems (at least Linux), HAProxy can ask the kernel not to immediately send an empty ACK upon a connection request, but to directly send the buffer request instead. This saves one packet on the network and thus boosts performance. It can also be useful for some servers, because they immediately get the request along with the incoming connection. This feature is enabled when "option tcp-smart-connect" is set in a backend. It is not enabled by default because it makes network troubleshooting more complex. It only makes sense to enable it with protocols where the client speaks first such as HTTP. In other situations, if there is no data to send in place of the ACK, a normal ACK is sent. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: "option tcp-smart-accept" **`option tcpka`** ```haproxy option tcpka ``` Enable or disable the sending of TCP keepalive packets on both sides May be used in the following contexts: tcp, http, log May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| yes Arguments: none When there is a firewall or any session-aware component between a client and a server, and when the protocol involves very long sessions with long idle periods (e.g. remote desktops), there is a risk that one of the intermediate components decides to expire a session which has remained idle for too long. Enabling socket-level TCP keep-alives makes the system regularly send packets to the other end of the connection, leaving it active. The delay between keep-alive probes is controlled by the system only and depends both on the operating system and its tuning parameters. It is important to understand that keep-alive packets are neither emitted nor received at the application level. It is only the network stacks which sees them. For this reason, even if one side of the proxy already uses keep-alives to maintain its connection alive, those keep-alive packets will not be forwarded to the other side of the proxy. Please note that this has nothing to do with HTTP keep-alive. Using option "tcpka" enables the emission of TCP keep-alive probes on both the client and server sides of a connection. Note that this is meaningful only in "defaults" or "listen" sections. If this option is used in a frontend, only the client side will get keep-alives, and if this option is used in a backend, only the server side will get keep-alives. For this reason, it is strongly recommended to explicitly use "option clitcpka" and "option srvtcpka" when the configuration is split between frontends and backends. See also: "option clitcpka", "option srvtcpka" **`option tcplog [clf]`** ```haproxy option tcplog [clf] ``` Enable advanced logging of TCP connections with stream state and timers May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text clf if the "clf" argument is added, then the output format will be the CLF format instead of HAProxy's default TCP format. You can use this when you need to feed HAProxy's logs through a specific log analyzer which only support the CLF format and which is not extensible. Since this expects an HTTP format some of the values have been pre set. The http request will show as TCP and the response code will show as 000. ``` By default, the log output format is very poor, as it only contains the source and destination addresses, and the instance name. By specifying "option tcplog", each log line turns into a much richer format including, but not limited to, the connection timers, the stream status, the connections numbers, the frontend, backend and server name, and of course the source address and ports. This option is useful for pure TCP proxies in order to find which of the client or server disconnects or times out. For normal HTTP proxies, it's better to use "option httplog" which is even more complete. "option tcplog" overrides any previous "log-format" directive. See also: "option httplog", and [section 8](/docs/haproxy/configuration-logging/) about logging. **`option transparent (deprecated)`** ```haproxy option transparent (deprecated) no option transparent (deprecated) ``` Enable client-side transparent proxying May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: none This option was introduced in order to provide layer 7 persistence to layer 3 load balancers. The idea is to use the OS's ability to redirect an incoming connection for a remote address to a local process (here HAProxy), and let this process know what address was initially requested. When this option is used, sessions without cookies will be forwarded to the original destination IP address of the incoming request (which should match that of another equipment), while requests with cookies will still be forwarded to the appropriate server. Note that contrary to a common belief, this option does NOT make HAProxy present the client's IP to the server when establishing the connection. As of 3.3, this option is now deprecated because it used to suffer from a number of internal technical limitations. Using it will emit a warning, which can be avoided if really needed via the "expose-deprecated-directives" global keyword. The correct approach is to declare a server on address 0.0.0.0, which will take care of connecting to the expected destination address. A server will also properly handle idle connections to the target servers. Example: ```shell # option transparent ## before 3.3 server transparent 0.0.0.0 ``` See also: the "usesrc" argument of the "source" keyword, and the "transparent" option of the "bind" keyword. option use-small-buffers [ queue \| l7-retries \| check ]\* Enable support for small buffers for the given categories. May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes This option can be used to enable the small buffers support at different places to save memory. By default, with no parameter, small buffers are used as far as possible at all possible places. Otherwise, it is possible to limit it to following the places: - queue: When set, small buffers will be used to store the requests, if small enough, when the connection is queued. - l7-retries: When set, small buffers will be used to save the requests when L7 retries are enabled. - check: When set, small buffers will be used for the health-checks requests. When enabled, small buffers are used, but only if it is possible. Otherwise, when data are too large, a regular buffer is automatically used. The size of small buffers is configurable via the "tune.bufsize.small" global setting. If this option has been enabled in a "defaults" section, it can be disabled in a specific instance by prepending the "no" keyword before it. See also: tune.bufsize.small **`persist rdp-cookie`** ```haproxy persist rdp-cookie persist rdp-cookie() ``` Enable RDP cookie-based persistence May be used in the following contexts: tcp May be used in sections: defaults \| frontend \| listen \| backend yes \| no \| yes \| yes Arguments: ```text is the optional name of the RDP cookie to check. If omitted, the default cookie name "msts" will be used. There currently is no valid reason to change this name. ``` This statement enables persistence based on an RDP cookie. The RDP cookie contains all information required to find the server in the list of known servers. So when this option is set in the backend, the request is analyzed and if an RDP cookie is found, it is decoded. If it matches a known server which is still UP (or if "option persist" is set), then the connection is forwarded to this server. Note that this only makes sense in a TCP backend, but for this to work, the frontend must have waited long enough to ensure that an RDP cookie is present in the request buffer. This is the same requirement as with the "rdp-cookie" load-balancing method. Thus it is highly recommended to put all statements in a single "listen" section. Also, it is important to understand that the terminal server will emit this RDP cookie only if it is configured for "token redirection mode", which means that the "IP address redirection" option is disabled. Example: ```text listen tse-farm bind:3389 # wait up to 5s for an RDP cookie in the request tcp-request inspect-delay 5s tcp-request content accept if RDP_COOKIE # apply RDP cookie persistence persist rdp-cookie # if server is unknown, let's balance on the same cookie. # alternatively, "balance leastconn" may be useful too. balance rdp-cookie server srv1 1.1.1.1:3389 server srv2 1.1.1.2:3389 ``` See also: "balance rdp-cookie", "tcp-request" and the "req.rdp_cookie" ACL. **`quic-initial [ { if | unless } ]`** ```haproxy quic-initial [ { if | unless } ] ``` Perform an action on an incoming QUIC Initial packet. Contrary to "tcp-request connection", this is executed prior to any connection element instantiation and starting and completion of the SSL handshake, which is more efficient when wanting to reject connections attempts. May be used in the following contexts: http May be used in sections: defaults \| frontend \| listen \| backend yes(!) \| yes \| yes \| no Arguments: ```text defines the action to perform if the condition applies. See below. is a standard layer4-only ACL-based condition (see section 7). However, QUIC initial rules are executed too early even for some layer4 sample fetch methods despite no configuration warning and may result in unspecified runtime behavior, although they will not crash. Consider that only internal samples and layer4 "src*" and "dst*" are considered as supported for now. ``` This action is executed early during QUIC packet parsing. As such, only a minimal list of actions is supported: - accept - dgram-drop - reject - send-retry **`rate-limit sessions `** ```haproxy rate-limit sessions ``` Set a limit on the number of new sessions accepted per second on a frontend May be used in the following contexts: tcp, http May be used in sections: defaults \| frontend \| listen \| backend yes \| yes \| yes \| no Arguments: ```text The parameter is an integer designating the maximum number of new sessions per second to accept on the frontend. ``` When the frontend reaches the specified number of new sessions per second, it stops accepting new connections until the rate drops below the limit again. During this time, the pending sessions will be kept in the socket's backlog (in system buffers) and HAProxy will not even be aware that sessions are pending. When applying very low limit on a highly loaded service, it may make sense to increase the socket's backlog using the "backlog" keyword. This feature is particularly efficient at blocking connection-based attacks or service abuse on fragile servers. Since the session rate is measured every millisecond, it is extremely accurate. Also, the limit applies immediately, no delay is needed at all to detect the threshold. Example: limit the connection rate on SMTP to 10 per second max listen smtp mode tcp bind:25 rate-limit sessions 10 server smtp1 127.0.0.1:1025 Note: when the maximum rate is reached, the frontend's status is not changed but its sockets appear as "WAITING" in the statistics if the "socket-stats" option is enabled. See also: the "backlog" keyword and the "fe_sess_rate" ACL criterion. **`redirect location [code ]