HAProxy Enterprise Documentation 2.3r1

Release Notes

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

Core

Connection improvements for upcoming QUIC and HTTP/3 support

Connection layer

The connection layer was optimized to reduce the number of syscalls.

Debugging entries

Several debugging entries were added to help better spot anomalies.

Listeners

Listeners have been reworked and related structures have been reorganized to better suit the new design. File descriptors are no longer manipulated by the listener layer.

TCP keepalive

TCP keepalive lets the Linux kernel know when a peer on the other end of a connection has stopped responding and that it's safe to close the idle connection. It discovers this by sending probes. If the peer doesn't reply, the socket is closed automatically.

You can change the number of probes to send, the interval at which to send them, or how long to wait before starting to send probes on both the client and server side through the following parameters:

Parameter

Description

clitcpka-cnt

Sets the maximum number of keepalive probes TCP should send before dropping the connection on the client side.

clitcpka-idle

Sets the time the connection needs to remain idle before TCP starts sending keepalive probes on the client side, if enabled.

clitcpka-intvl

Sets the time between individual keepalive probes on the client side.

srvtcpka-cnt

Sets the maximum number of keepalive probes TCP should send before dropping the connection on the server side.

srvtcpka-idle

Sets the time the connection needs to remain idle before TCP starts sending keepalive probes on the server side, if enabled.

srvtcpka-intvl

Sets the time between individual keepalive probes on the server side.

Syslog Protocol (UDP/TCP)

New log-forward section

A new section called log-forward can bind on TCP using the bind keyword and on UDP using dgram-bind for both IPv4 and IPv6.

You can thus create a syslog listener over UDP or TCP that can forward, prioritize, and translate syslog messages to a pool of UDP or TCP syslog servers.

When combined with the log sampling feature added in HAProxy Enterprise 2.0, you get granular control over how your syslog messages are forwarded.

You can also translate syslog messages from one format to another.

Runtime API

The Runtime API show info command also exposes a new counter called CumRecvLogs, which provides a global count of received syslog messages.

Load Balancing

New path-only option for balance uri

The new balance uri directive's path-only option indicates that the hash should be calculated using only the path, normalizing HTTP/1 and HTTP/2 messages. This avoids inconsistencies between requests received over HTTP/1 and the same ones received over HTTP/2.

balance random algorithm

If the balance random algorithm returns a server whose maxconn value has been reached, meaning that connections are now queuing up for that server, it will add the request to the backend's queue and not the server's queue. The request can be redispatched to another available server, and typically the fastest.

Load balancing algorithms optimization

For some load balancing algorithms (roundrobin, static-rr, leastconn, first), requests were queued in the backend due to a previous attempt at finding a suitable server after trying all of them. Now, the next request skips the part where each server is tried and goes directly to the backend's queue.

leastconn algorithm

The leastconn algorithm has been improved to take the queue length into account when dispatching requests. This means that if a server has a lot of queued requests we won't hammer it with extra connections.

Cache

Expires header directive

This directive instructs HAProxy Enterprise how long it should cache the response.

New cache headers

The cache now supports the ETag, If-None-Match, and If-Modified-Since.

HTTP status code

The cache can return an HTTP status code 304 instead of the full object.

Duplicate cache section names management

HAProxy Enterprise will now also reject any configuration that has a duplicate cache section name.

New fetch methods

added-res.cache_hit and res.cache_name tell you whether a response came from the cache and, if so, the name of the cache used.

SSL/TLS Enhancements

ssl-load-extra-del-ext global directive

If you load SSL/TLS certificates separately from the certificate key through the ssl-load-extra-files global directive, the key no longer needs to be named the exact same as the certificate with .key appended to it.

The new global directive ssl-load-extra-del-ext instructs HAProxy Enterprise to remove the certificate file's extension before adding a new one.

For example, the key can be named mycert.key instead of mycert.crt.key.

Subject Alternative Name

The generate-certificates directive adds a Subject Alternative Name (SAN) to all generated certificates, which is a requirement in modern browsers. It now also supports chaining CAs and attaching a trust chain in addition to the generated certificate. The chain is loaded from the one provided in the ca-sign-file PEM file.

Reusing connections that hardcode the SNI to the backend server

If the SNI is hardcoded on the server line using, as an example, sni str(example.local) there's no risk in reusing the connection. This release allows reusing connections that hardcode the SNI to the backend server. It will mark connections as private only if you've configured a variable expression for the SNI.

Invalid certificates management

If a crt-list does not end with a new line, a warning indicates that the file might have been truncated.

Observability

Statistics context switch

The new show stat Runtime API command's option domain, allows you to change the context of the statistics. The proxy default value displays the core proxy statistics that were available before. The dns value displays statistics related to DNS resolution that HAProxy Enterprise performs.

Additional HTTP/2 statistics

The stats show-modules directive enables extra statistics related to HTTP/2 on the HAProxy Enterprise Stats.

New field under the Wght column in the Stats page

The Stats page displays a new field under the Wght column, which previously only showed the live or effective weight. The Wght column now contains the effective weight separated with a "/" followed by the configured weight.

Filter on servers that are up or not in maintenance mode

The show stat Runtime API command now allows you to use show stat up to filter on servers that are up or show stat no-maint to show those that are not in maintenance mode.

Prometheus exporter

The Prometheus exporter received some new process and per-server metrics, as outlined here:

Metric

Description

haproxy_process_failed_resolutions

Total number of failed DNS resolutions.

haproxy_process_bytes_out_total

Total number of bytes emitted.

haproxy_process_spliced_bytes_out_total

Total number of bytes emitted through a kernel pipe.

haproxy_process_bytes_out_rate

Number of bytes emitted over the last elapsed second.

haproxy_server_unsafe_idle_connections_current

Current number of unsafe idle connections.

haproxy_server_safe_idle_connections_current

Current number of safe idle connections.

haproxy_server_used_connections_current

Current number of connections in use.

haproxy_server_need_connections_current

Estimated needed number of connections.

Typo

A typo has been fixed for the haproxy_process_frontend_ssl_reuse metric.

New delimiter for dynamic fields

The Runtime API's show stat output has been extended and adds a new delimiter, a dash ("-"), after which additional dynamic fields can be added. Those fields won't be shown unless the relevant component is in use.

OpenTracing (SPOE)

OpenTracing SPOA

An OpenTracing SPOA allows HAProxy Enterprise to send data directly to distributed tracing systems via the OpenTracing API.

HTTP Request Actions

Modified query string in path replacement

The new HTTP request action http-request replace-pathq, does the same as http-request replace-path, except that the replacement value may contain a modified query string.

Rewrite HTTP request query string

The new HTTP request action http-request set-pathq works similarly to http-request set-path, except that the query string is also rewritten. Unlike http-request replace-pathq, it does not take a regular expression and replacement value, but a formatted string to use as the new path. It can also be used to remove the query string, including the question mark.

New sample fetches

Name

Description

pathq

This extracts the request's URL path with the query-string, which starts at the first slash.

res.cache_hit

Returns the boolean "true" value if the response has been built out of an HTTP cache entry, otherwise returns boolean "false".

res.cache_name

Returns a string containing the name of the HTTP cache that was used to build the HTTP response if res.cache_hit is true, otherwise returns an empty string.

srv_iweight([<backend>/]<server>)

Returns an integer corresponding to the server's initial weight. If <backend> is omitted, then the server is looked up in the current backend.

srv_uweight([<backend>/]<server>)

Returns an integer corresponding to the current (or effective) server's weight. If <backend> is omitted, then the server is looked up in the current backend.

srv_weight([<backend>/]<server>)

Returns an integer corresponding to the current (or effective) server's weight. If <backend> is omitted, then the server is looked up in the current backend.

ssl_c_der_chain

Returns the DER formatted chain certificate presented by the client when the incoming connection was made over an SSL/TLS transport layer. When used for an ACL, the value(s) to match against can be passed in hexadecimal form.

ssl_s_chain_der

Returns the DER formatted chain certificate presented by the server when the outgoing connection was made over an SSL/TLS transport layer. When used for an ACL, the value(s) to match against can be passed in hexadecimal form.

New converters

Name

Description

iif

Returns the <true> string if the input value is true. Returns the <false> string otherwise.

Lua

  • Support for Lua 5.4, which was initially released in June 2020.

  • This release exports the sample fetches http_auth() and http_auth_group().

  • You can now use regular expressions in fetches and converter arguments.

  • Sample fetches and converters that require arguments are now supported as well.

Build

The following build changes were added:

  • DragonFly BSD was added as a build target.

  • Support for accept4() and getaddrinfo() was added to NetBSD.

  • Support for accept4(), closefrom(), and getaddrinfo() was added for FreeBSD and the supported version was bumped to FreeBSD 10 and above.

  • Support for threads, accept4(), closefrom(), and getaddrinfo() was added for OpenBSD and the supported version was bumped to OpenBSD 6.3 and above.

  • Support for getaddrinfo() was added to OS X.

  • Support for closefrom() in Solaris was added and the supported version was bumped to Solaris 10 and above.

  • Support for the TCC compiler has been added.

  • A solution using SSL_READ_EARLY_DATA_SUCCESS was added for

    checking for OpenSSL early data to address cases where BoringSSL was impersonating OpenSSL 1.1.1 but does not feature OpenSSL specific early data support.

Testing

  • Seven new Varnish regression tests.

Deprecated and Removed Directives

  • The obsolete keyword monitor-net was removed. It supported only a single IPv4 network, was incompatible with SSL, and required HTTP/1.x. It is now recommended to use http-request return status 200 if { src 10.1.1.3 } instead.

  • The obsolete keyword mode health was removed. It was incompatible with SSL and worked with only HTTP/1. It is now recommended to use http-request return status 200 instead.

  • The global keyword debug has been removed. It had, on occasion, trapped users by disrupting their system's ability to boot. You can continue to use -d on the command line.

  • The nbproc directive is now deprecated and is set for removal in 2.5. It used too much memory, led to high network overhead (poor reuse, multiple health checks), lacked peers syncing and stats, caused problems with seamless reloads, and would not support QUIC at all. If nbproc is found with more than one process while nbthread is not set, a warning will be emitted encouraging you to remove it or migrate to nbthread.

  • The grace directive has been marked as deprecated and is scheduled tentatively for removal in 2.4 with a hard deadline of 2.5. It was meant to postpone stopping of a process during a soft-stop, but is incompatible with soft reloading.

Miscellaneous

  • The strict-limits directive defaults to on. You'll now get a startup error if you configure too large a maxconn for your system's limits.

  • The process no longer reports proxy <proxy name> has started.

  • An optimization for PCRE2 was made, which uses the JIT match when a JIT optimization has occurred. This should shorten the code path to call the match function.

  • Several deinit() fixes were made to improve the results from Valgrind.

  • Support for upgradable locks was added. These cut the scheduler overhead in half and reduce the locking time during map and ACL updates.


Next up

Getting Started