HAProxy Enterprise Documentation 2.2r1

Release Notes

New and/or improved features in HAProxy Enterprise 2.2r1 include:

Enterprise addons & native modules

  • A new native module for performing TLS/SSL fingerprinting

  • Support for Single Sign On SAML

  • New validate-crawler daemon to verify the legitimacy of clients claiming to be Googlebot & Bingbot

Core

Dynamic SSL certificate storage

  • SSL certificates can now be added/removed/updated through the Runtime API using the set ssl cert and commit ssl cert commands.

SSL/TLS enhancements

  • TLSv1.2 the new default minimum version TLS version

  • tune.ssl.default-dh-param now defaults to 2048 bits

  • New global directive: ssl-default-bind-curves to specify the list of elliptic curve algorithms that are negotiated during the SSL/TLS handshake when using Elliptic-curve Diffie-Hellman Ephemeral (ECDHE).

  • New global directives: ssl-load-extra-files and issuers-chain-path to load the TLS/SSL private key and intermediate certificates separately.

  • New global directive: ssl-skip-self-issued-ca to avoid sending global CA certificates to clients when using OCSP stapling.

  • New bind parameter ca-verify-file to store the root CA in a separate file to use for validating an intermediate CA.

  • Support for fetching and logging the secrets necessary for decrypting TLS 1.3

Native response generator

  • New actions http-request return and http-response return make it possible to return a custom response from HAProxy, with any status code, based on an error file, a file or a string.

  • In addition, using a log-format string or a log-format file, it is possible to have responses with a dynamic content.

  • Definition of extra headers by passing the hdr argument.

Dynamic error handling

  • A new section http-errors to create global groups of custom HTTP error files.

  • Expanded directives error-files, http-request deny, and http-response deny to support loading http-errors groups.

  • Dynamic error processing to define error file templates with log-format parameters.

Health check overhaul

  • New directives {http|tcp}-check connect to tune health check connection parameters by enabling SNI, connecting over SSL/TLS, performing health checks over SOCKS4, and choosing the protocol, such as HTTP/2 or FastCGI.

  • New directive http-check send to customize fully an HTTP health check, including sending a custom method, URI, headers, and POST body data.

  • New {http|tcp-check} comment directives to define a comment to report in the logs if the http-check rule fails.

  • Ability to query multiple endpoints at once to allow for multistage health checking.

  • New directives {http|tcp}-check set-var and {http|tcp}-check unset-var to set or unset a variable during HTTP and TCP health checks.

  • MySQL based health checks using the option mysql-check directive were rebuilt on top of the new tcp-check rules. They now default to a MySQL 4.1 and above client-compatible check when there is a defined username.

Syslog over TCP

  • New support for sending to syslog over TCP.

  • A new section ring to define custom ring buffers to use for queuing up messages and ensuring message delivery.

Performance improvements

  • Automatic deduplication of ca-file and crl-file directives to improve the overall startup speed.

  • New thread-local pool of recently used pipes to improve cache locality and eliminate unnecessary allocation.

  • ACL unique id value improvements.

  • Significant reduction of the number of syscalls per request for a connection using keep-alive mode.

  • Memory pools now release when there are an abundance of objects created after a traffic surge.

  • The connection layer underwent several performance improvements, essentially resulting in fewer syscalls on average, primarily for epoll.

  • HAProxy Enterprise no longer closes a client connection after it serves an internal response code (such as a 401 or 503), unless requested. Note: Status codes 400 (Bad Request) and 408 (Request Timeout) are excluded from this.

  • A new directive pool-low-conn to optimize server connection pooling. It is also possible to tune it to indicate the number of required idling connections to a server before a thread can reuse a connection.

  • The scheduler is now also latency aware, which means that the Runtime API is usable regardless of HAProxy's load.

Observability & debugging

  • A new Runtime API command show servers conn to see the current and idle connection state of the servers within a backend.

  • HAProxy Enterprise Enterprise Stats page now reports connect, queue and response time metrics with more accuracy.

  • A new timing metric, %Tu to return the total estimated time as seen from the client, from the moment the proxy accepts the request to the moment both ends get closed, not including the idle time before the request began.

  • Improved HAProxy Enterprise internal watchdog and expanded support to FreeBSD.

  • The debug converter is now always available and sends the output to a defined event sink. The currently available event sinks are buf0, stdout and stderr.

HTTP actions

  • A new ruleset http-after-response that HAProxy Enterprise evaluates on all responses prior to forwarding.

  • A new http-{request|response|after-response} action called strict-mode to enable or disable a strict rewriting mode on all the rules that follow it.

  • A new http-request action called replace-path is similar to replace-uri, except that it only acts on the path component.

Security hardening

  • HAProxy Enterprise now prevents the creation of new processes at default, effectively disabling the use of external programs for checks completely.

  • A new global directive insecure-fork-wanted to disable the above security capability and allow the use of the external-check command.

  • HAProxy Enterprise now prevents the process from executing setuid binaries by default to prevent it from switching uids after the initial switch to the uid defined within the global section.

  • To re-enable the execution of setuid binaries, you can use the new global directive insecure-setuid-wanted.

Fetches

Name

Description

fc_pp_unique_id

Returns the unique ID TLV from the client in the PROXY protocol header, if any.

res.body

Returns the HTTP response's available body as a block of data.

res.body_len

Returns the length of the HTTP response available body in bytes.

res.body_size

Returns the advertised length of the HTTP response body in bytes. It will represent the advertised Content-Length header, or the size of the available data in case of chunked encoding.

res.hdrs

Returns the current response headers as string including the last empty line separating headers from the response body.

res.hdrs_bin

Returns the current response headers contained in preparsed binary form. This is useful for offloading some processing with SPOE.

so_name

Returns a string containing the current listening socket's name, as defined with name on a bind line.

ssl_fc_client_early_traffic_secret

Returns the CLIENT_EARLY_TRAFFIC_SECRET as a hexadecimal string when the incoming connection was made over TLS 1.3.

ssl_fc_client_handshake_traffic_secret

Returns the CLIENT_HANDSHAKE_TRAFFIC_SECRET as a hexadecimal string when the incoming connection was made over TLS 1.3.

ssl_fc_client_traffic_secret_0

Returns the CLIENT_TRAFFIC_SECRET_0 as a hexadecimal string when the incoming connection was made over TLS 1.3.

ssl_fc_exporter_secret

Returns the EXPORTER_SECRET as a hexadecimal string when the incoming connection was made over TLS 1.3.

ssl_fc_early_exporter_secret

Returns the EARLY_EXPORTER_SECRET as a hexadecimal string when the incoming connection was made over TLS 1.3.

ssl_fc_server_handshake_traffic_secret

Returns the SERVER_HANDSHAKE_TRAFFIC_SECRET as a hexadecimal string when the incoming connection was made over TLS 1.3.

ssl_fc_server_traffic_secret_0

Returns the SERVER_TRAFFIC_SECRET_0 as a hexadecimal string when the incoming connection was made over TLS 1.3.

ssl_s_der

Returns the DER formatted certificate presented by the server when the outgoing connection was made over an SSL/TLS transport layer.

ssl_s_key_alg

Returns the name of the algorithm used to generate the key of the certificate presented by the server when the outgoing connection was made over an SSL/TLS transport layer.

ssl_s_notafter

Returns the end date presented by the server as a formatted string YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS transport layer.

ssl_s_notbefore

Returns the start date presented by the server as a formatted string YYMMDDhhmmss[Z] when the outgoing connection was made over an SSL/TLS transport layer.

ssl_s_i_dn([<entry>[,<occ>[,<format>]]])

When the outgoing connection was made over an SSL/TLS transport layer, returns the full distinguished name of the issuer of the certificate presented by the server when no <entry> is specified, or the value of the first given entry found from the beginning of the DN.

ssl_s_s_dn

When the outgoing connection was made over an SSL/TLS transport layer, returns the full distinguished name of the subject of the certificate presented by the server when no <entry> is specified, or the value of the first given entry found from the beginning of the DN.

ssl_s_serial

Returns the serial of the certificate presented by the server when the outgoing connection was made over an SSL/TLS transport layer.

ssl_s_sha1

Returns the SHA-1 fingerprint of the certificate presented by the server when the outgoing connection was made over an SSL/TLS transport layer.

ssl_s_sig_alg

Returns the name of the algorithm used to sign the certificate presented by the server when the outgoing connection was made over an SSL/TLS transport layer.

ssl_s_version

Returns the version of the certificate presented by the server when the outgoing connection was made over an SSL/TLS transport layer.

Converters

Name

Description

cut_crlf

Cuts the string representation of the input sample on the first carriage return ('r') or newline ('n') character found.

digest (<algorithm>)

Converts a binary input sample to a message digest.

hmac (<algorithm>, <key>)

Converts a binary input sample to a message authentication code with the given key. The result is a binary sample.

htonl

Converts the input integer value to its 32-bit binary representation in the network byte order.

ltrim (<chars>)

Skips any characters from <chars> from the beginning of the string representation of the input sample.

rtrim (<chars>)

Skips any characters from <chars> from the end of the string representation of the input sample.

secure_memcmp (<var>)

Compares the contents of <var> with the input value. Both values are treated as a binary string. Returns a Boolean indicating whether both binary strings match.

Lua

  • You can now prepend the lookup path for Lua modules using lua-prepend-path.

  • It is now possible to intercept HTTP messages from a Lua action and reply to clients.

  • Lua declared actions can now yield using wake_time (). This function can define a timeout when a Lua action returns act:YIELD. It is a way to force the script to re-execute after a short time (defined in milliseconds).

  • set_var and unset_var now returns a Boolean to indicate success.

  • A new parameter ifexist is added to set_var to allow a Lua developer to set variables to ignore unless the variable name was used elsewhere before.

  • The Server class now has a set_addr function to change a backend server's address and port.

  • A new function is_resp to determine whether a channel is a response channel.

Miscellaneous improvements

  • The parser now supports quotes, braces, and square brackets in arguments.

  • The parser now also shows you the location of where a parsing error occurred.

  • The use-server directive now supports rules using dynamic names.

  • The bits argument for the sha2 converter will now properly be verified.

  • Added the 'sub-second' and 'timezone' fields to the RFC5424 log format.

  • The number of connections reported in the output of a quitting proxy now indicates cumulative connections and not active connections.

  • The Runtime API's show table command now supports filtering stick table output by multiple filters, allowing for filtering on many columns.

  • DNS Service Discovery now reuses information available within the extension parts of an SRV record response.

  • The cookie directive now has an 'attr' field to set attributes on persistence cookies. This is helpful when adding the 'SameSite' attribute, which is required in Chrome 80 and above.

  • You can specify the local peer name with 'localpeer' within the peers section. You can override it with the -L parameter on startup.

  • The Runtime API now allows for escaping spaces.

  • ACLs can no longer be named “or”.

  • Error files that are larger than tune.bufsize now emit a warning message on startup.

  • The http-request deny directive now supports returning status codes '404 Not Found', '410 Gone', and '413 Payload Too Large'.

  • Improved UUID random generation is now thread safe.

  • You can now send and receive a unique-id in the PROXY Protocol for connection tracking purposes.

  • The default maxconn is now automatically set based on the configured ulimit -n.

  • Invalid hex sequences now cause a fatal error.

  • A new option pp2-never-send-local to revert the old bogus behavior on the server side when using proxy-protocol-v2 in health checks.

Next up

Getting Started