Release notes

Version 17.5 Jump to heading #

Key changes in the HAProxy ALOHA 17.5 release include:

Support for larger firmware

• The HAProxy ALOHA system now supports larger firmware. The partitioning of sda4 has been reworked and 2GB will be reserved for larger firmware. Starting with version 17.5, the system requires at least 8GB of device size.

GSLB module

• The GSLB module now supports an HTTPS proxy mode for sending health checks over HTTPS.

Prometheus

• This version adds new Prometheus metrics:

  • haproxy_frontend_current_session_rate
  • haproxy_frontend_ssl_ocsp_staple
  • haproxy_frontend_ssl_failed_ocsp_staple
  • haproxy_backend_current_session_rate
  • haproxy_backend_ssl_ocsp_staple
  • haproxy_backend_ssl_failed_ocsp_staple
  • haproxy_server_current_session_rate
  • haproxy_server_http_requests_total
  • haproxy_server_ssl_ocsp_staple
  • haproxy_server_ssl_failed_ocsp_staple

Traffic policing

• You can now delay the processing of a request with the pause response policy, giving you another option for slowing down clients that exceed your rate limit.

Health checks

• To send health checks to backend servers over existing, idle connections, use the check-reuse-pool argument on a server directive.

DNS resolver

• Use the global directive dns-accept-family to indicate whether to request and accept IPv4 and/or IPv6 records from nameservers.

Compression

• You can now set a minimum file size to control which files to compress.

HTTP/3 over QUIC

• When you set the QUIC congestion control algorithm with the quic-cc-algo directive, it now automatically enables pacing on top of the chosen algorithm. It had been an opt-in, experimental feature before. Pacing smooths the emission of data to reduce network losses and has shown performance increases of approximately 10-20 fold over lossy networks or when communicating with slow clients at the expense of a higher CPU usage in HAProxy. On a related note, you can set the Bottleneck Bandwidth and Round-trip Propagation Time algorithm, which relies on pacing, without enabling experimental features. Set the quic-cc-algo directive’s bbr argument. Or if you don’t want pacing, disable it completely with tune.quic.disable-tx-pacing.

• This version improves QUIC upload performance. Previous versions only supported the equivalent of a single buffer in flight, which would limit the upload bandwidth to about 1.4 Mbps per stream, which was slow for users attempting to upload large images or videos. Starting with 3.2r1, uploading streams can use up to 90% (by default) of the memory allocated to the connection, allowing them to use the full bandwidth even with a single stream. You can adjust this ratio by using the global directive tune.quic.frontend.stream-data-ratio, allowing you to prioritize fairness (small values) or throughput (higher values). The default setting should suit common, web scenarios by striking a balance.

• A new, global setting, tune.quic.frontend.max-tx-mem, caps the total memory that the QUIC tx buffers can consume, helping to moderate the congestion window so that the sum of the connections don’t allocate more than that. By default, there’s no limitation.

HTTP protocol

• The accept-unsafe-violations-in-http-request and accept-unsafe-violations-in-http-response backend directives introduced in in the previous version allow HTTP messages to violate some rules of the protocol. In version 3.2r1, they allow HAProxy ALOHA to accept WebSocket requests that are missing the Sec-WebSocket-Key HTTP header and responses missing the Sec-WebSocket-Accept HTTP header.

• You can now set the HTTP response header Content-Length to 0, which some non-compliant applications need with HTTP 101 and 204 responses.

• HAProxy ALOHA has become stricter about not permitting some characters in the Authority and Host HTTP headers.

• Two new directives let you drop trailers from HTTP requests or responses, which is useful for removing sensitive information that shouldn’t be exposed to clients:

  • option http-drop-request-trailers
  • option http-drop-response-trailers

• To more efficiently close idle HTTP/2 connections, set the idle-ping argument on a bind or server directive.

Syslog load balancing

• New options in the log-forward section let you control how the load balancer parses and validates Syslog messages.

SSL/TLS

• Use the new ssl-f-use directive to specify the certificates to load in a frontend. This directive simplifies setting TLS-related properties such as ALPN fields, ciphers, signature algorithms, and CAs for client certificate authentication.

Consistent hashing

• When using the balance hash algorithm for consistent-hash load balancing, you can now set the directive hash-preserve-affinity to indicate what to do when servers become maxed out or have full queues. Consistent hashing configures the load balancer to maintain server affinity, but when a server is overwhelmed, blindly preserving that affinity can lead to issues. With hash-preserve-affinity, you can now reroute traffic to available servers while still maintaining affinity.

Overload protection

• When setting maxconn on a server line, you can set strict-maxconn to apply the limit to TCP connections instead of HTTP requests.

Layer 7 retries

• The retry-on directive, which was introduced in version 2.0r1, allows you to set which errors should trigger the retry of a failed request. It now supports the HTTP response status 421 Misdirected Request as a reason.

Fetch methods

• This version introduces the following fetch methods:

  Name	Description
  bc_reused	Returns true if the transfer was performed via a reused backend connection.
  req.ssl_cipherlist	Returns the binary form of the list of symmetric cipher options supported by the client as reported in the TLS ClientHello.
  req.ssl_keyshare_groups	Returns the binary format of the list of cryptographic parameters for key exchange supported by the client as reported in the TLS ClientHello.
  req.ssl_sigalgs	Returns the binary form of the list of signature algorithms supported by the client as reported in the TLS ClientHello.
  req.ssl_supported_groups	Returns the binary form of the list of groups supported by the client as reported in the TLS ClientHello and used for key exchange, which can include both elliptic and non-elliptic key exchange.
  sc_key(<ctr>)	Returns the key used to match the currently tracked counter.
  table_clr_gpc(<idx>[,<table>])	Clears the General Purpose Counter at index of the array and returns its previous value.
  table_inc_gpc(<idx>[,<table>])	Increments the General Purpose Counter at index of the array and returns its new value.
  term_events	Returns a series of comma-separated values that indicate the states of a request as its flowed through the load balancer. Clone the HAProxy GitHub repository, compile the term_events program, then run it to decode the values.

• The accept_date and request_date fetch methods now fall back to using the session’s date if not otherwise set, which can happen when logging SSL handshake errors that occur prior to creating a stream.

Converters

• It was discovered that a risk of buffer overflow can occur when using the regsub converter to replace patterns multiple times at once (multi-reference) with longer patterns. Although the risk is low, it has been fixed. CVE-2025-32464 was filed. The vulnerability affects all versions, so the fix will be backported.

Lua

• The new patref class gives you a way to modify ACL and Map files from your Lua code and is an improvement over the older core.add_acl function. It makes it easier to dynamically change Map and ACL files from your Lua code, such as to build modules that cache responses only for URLs that have a certain URL parameter attached to them. The patref class offers other features too:

  • Manipulate both ACL and Map files.
  • For Map files, replace the values of matching keys.
  • Add new patterns via bulk entry with the patref.add_bulk function.
  • Use prepare() and commit() functions to replace the entire ACL file at once with a new set of data.
  • Subscribe to events related to manipulating pattern files with callback functions.

• A new global directive, tune.lua.bool-sample-conversion, allows you to opt in to proper handling of booleans returned by fetch methods. The default behavior has been that when the Lua code calls a fetch method that returns a boolean, that return value is converted to an integer 0 or 1. Setting the new global directive to normal enables the correct behavior of treating booleans as booleans.

• The AppletTCP class’s receive function now accepts a timeout parameter to limit how long it will wait for data from the client. This makes it easier to design services that take in varying lengths of data, such as interactive utilities that read user input, as opposed to expecting fixed-length data.

• This version introduces new Lua functions:

  Name	Description
  AppletTCP.try_receive	Reads available data from the TCP stream and returns immediately.
  core.wait	Waits for an event to wake the task. It takes an optional delay after which it will awake even if no event fired.
  HTTPMessage.set_body_len	Changes the expected payload length of the HTTP message.

Other performance updates

• By fixing the fairness of the lock that the scheduler uses for shared tasks, heavily loaded machines (64 cores NUMA) will see less latency, typically 8x lower, and 300x fewer occurrences of latencies 32ms or above.

• HAProxy ALOHA will now interrupt the processing of TCP and HTTP rules in the configuration at every 50 rules, a number that’s configurable, to perform other concurrent tasks. This will help keep latencies low for configurations that have hundreds of rules.

• HAProxy ALOHA servers with many CPU cores will see significantly better performance of queues in regards to CPU usage. Queues were refined to be thread group aware, favoring pending requests in the same group when a stream finishes, which reduces data sharing between CPU cores.

• QUIC now supports a larger Rx window to significantly speed up uploads (POST requests).

• On a server with a 128-thread EPYC microprocessor, watchdog warnings were emitted occasionally under extreme contention on the mt_lists, indicating that some CPUs were blocked for at least 100ms. To solve this issue, we shortened the exponential back-off, which seemed too high for these CPUs.

• Memory pools have been optimized. Previously, HAProxy ALOHA merged similar pools that were the same size. Now, pools with less than 16 bytes of difference or 1% of their size will be merged. During a test of 1-million requests, this reduced pools from 48 to 36 and saved 3MB or RAM. The HAProxy Runtime API command show pools detailed will now show which pools have been merged.

• The leastconn load balancing algorithm, which is more sensitive to thread contention because it must use locking when moving the server’s position after getting and releasing connections, shows a lower peak CPU usage in this version. By moving the server less often, we observed a performance improvement of 60% on x86 machines with 48 threads. On an Arm server with 64 threads, we saw a 260% improvement. While faster, the algorithm also became more fair than previous versions, which had to sacrifice fairness to maintain a decent level of performance. There’s now much less difference between the most and least loaded servers.

• The roundrobin load balancing algorithm now scales better on systems with many threads. Testing on a 64-core EPYC server with cpu-policy performance showed a 150% performance increase thanks to no longer accessing variables and locks from distant cores.

• The deadlock watchdog and thread dump signal handlers were reworked to address some of the remaining deadlock cases that users reported in version 3.1 and 3.2. The new approach minimizes inter-thread synchronization, resulting in much less CPU overhead when displaying a warning.

• Performance for stick tables that sync updates from peers got a boost by changing the code to use a single, dedicated thread to update the tree, which reduces thread locking. On a server with 128 threads, speed increased from 500k-1M updates/second to 5-8M updates/second.

• The default limit on the number of threads was raised from 256 to 1024.

• The default limit on the number of thread groups was raised from 16 to 32.

• New global directives, tune.notsent-lowat.client and tune.notsent-lowat.server, allow you to limit the amount of kernel-side socket buffers to the strict minimum required and for the non-acknowledged bytes, lowering memory consumption.

• A new global directive tune.glitches.kill.cpu-usage takes a number between 0 and 100 to indicate the minimum CPU usage at which HAProxy ALOHA should begin to kill connections showing too many protocol glitches. In other words, kill connections that have reached the glitches-threshold limit, once the server gets too busy. The default is 0, where a connection reaching the threshold will be killed automatically, regardless of CPU usage. Consider setting this directive to twice the normally observed CPU usage, or the normal usage plus half the idle one. This setting requires that you also set tune.h2.fe.glitches-threshold or tune.quic.frontend.glitches-threshold.

Version 17.0 Jump to heading #

Key changes in the HAProxy ALOHA 17.0 release include:

UDP module

• The new UDP module, configurable on the LB Layer7 tab enables UDP load balancing in a fast, reliable, and secure way. Although HAProxy ALOHA already supported UDP load balancing via its LB Layer4 tab, the new UDP module has better session tracking, logging, and statistics.

Network management

• The HAProxy Data Plane API can now manage network interfaces on HAProxy ALOHA servers. Through API calls, you can set IP addresses, list devices, and configure high availability, VLANs, and link aggregation.
• The Network Management CLI, netctl, now returns exit status codes to facilitate checking for errors when calling its functions. It also has expanded contextual help. It’ll display available options when you type tab twice after a command.

Logging

• Configuring Layer 7 logging is more flexible with the introduction of log profiles, which let you assign names to your log formats. By defining log formats with names, you can choose the one best suited for each log server and even emit logs to multiple servers at the same time, each with its own format. Log profiles also allow you to write log messages when different events occur, such as when accepting a connection, receiving a request, connecting to a backend server, and receiving a response.
• With the new do-log action, you can emit custom log messages throughout the processing of a request or response, allowing you to add debug statements that help you troubleshoot issues. Add the do-log action at various points of your configuration.
• The option tcplog directive now allows an optional argument: clf. When enabled, CLF (Common Log Format) sends the same information as the non-CLF option, but in a standardized format that CLF log servers can parse.

set-retries action

• The tcp-request content and http-request directives have a new action named set-retries that dynamically changes the number of times HAProxy ALOHA will try to connect to a backend server if it fails to connect initially.

quic-initial directive

• The new quic-initial directive, which you can add to frontend, listen, and named defaults sections, gives you a way to deny QUIC (Quick UDP Internet Connections) packets early in the pipeline to waste no resources on unwanted traffic.

SPOE

• In your configuration file, set mode to spop in the backend that contains the SPOE agents. This mode is now mandatory and automatically set for backends referenced by SPOEs. Configuring your backend in this way means that you are no longer required to use a separate configuration file for SPOE. This new spop backend mode adds flexibility to SPOE, optimizes traffic distribution among servers, improves performance, and will ultimately make the entire system more reliable, as future changes to the SPOE engine will only affect pieces specific to SPOE.

• You can now pass variables from the main stream that’s processing a request to the child stream of a Stream Processing Offload Agent (SPOA). When reading a variable in an spop backend, prefix the variable scope with the letter p for parent stream. For example, instead of req, use preq. This works for these scopes: psess, ptxn, preq, and pres.

• The following SPOE parameters were removed in this version and are silently ignored when present in the SPOE configuration:

  • maxconnrate
  • maxerrrate
  • max-waiting-frames
  • timeout hello
  • timeout idle

Health checks

• When defining health checks, add the new init-state argument to a server directive or server-template directive to control how quickly each server can return to handling traffic after restarting, coming out of maintenance mode, or adding the server through service discovery.
• The option httpchk directive supports a new parameter for passing a host HTTP header with each health check to backend servers. This avoids having to specify carriage return and newline characters to do it, unlike previous versions.

Address families

• When setting an address on a bind line, you can now set these address family prefixes:

  Prefix	Description
  abnsz@	Zero-terminated abstract namespace. This lets you interconnect with software that determines the length of the namespace’s name by the length of the string, terminated by a null byte.
  mptcp@, mptcp4@, mptcp6@	MultiPath Transmission Control Protocol (MPTCP). MPTCP is a TCP extension that improves resource utilization, increases throughput, and responds quicker to failures.

Fetch methods

• This version introduces the following fetch methods:

  Name	Description
  ssl_c_san	Returns a string of comma-separated Subject Alt Name fields contained in the client certificate.
  ssl_fc_sigalgs_bin	Returns the content of the signatures_algorithms (13) TLS extension presented during the Client Hello.
  ssl_fc_supported_versions_bin	Returns the content of the supported_versions (43) TLS extension presented during the Client Hello.
  last_entity	Returns the identity of the last entity that was evaluated during stream analysis.
  waiting_entity	Returns the identity of the entity that was waiting to continue its processing when an error or a timeout was encountered.

Converters

• This version introduces the following converters:

  Name	Description
  date	Converts an HTTP date string to a UNIX timestamp.
  rfc7239_nn	Converts an IPv4 or IPv6 address to a compliant address that you can use in the from field of a Forwarded header. The nn here stands for node name. You can use this converter to build a custom Forwarded header.
  rfc7239_np	Converts an integer into a compliant port that you can use in the from field of a Forwarded header. The np here stands for node port. You can use this converter to build a custom Forwarded header.
  when	Enables you to pass data, such as debugging information, only when a condition is met, such as an error condition.

Troubleshooting

This release includes a number of troubleshooting and debugging improvements:

• Starting in version 3.1, traces get a dedicated configuration section named traces, providing a better user experience compared to previous versions. Traces report more information than before, too.
• The new when converter adds a condition to the end of a fetch method to only fetch the data when the condition is true, such as an error condition.
• As of version 2.5, you can use the sample fetches fc_err_* for frontends and bc_err_* for backends to help determine the cause of an error on the current connection. In this release, these fetches have been enhanced to include connection-level errors that occur during data transfers.
• The system may produce a core dump on a fatal error or when the watchdog fires, which detects deadlocks. While crucial to diagnosing issues, sometimes these files are truncated or can be missing information vital to analysis. This release includes an internal post_mortem structure to be included in core dumps, which contains pointers to the most important internal structures. This structure, present in all core dumps, allows developers to more easily navigate the process’s memory, reducing analysis time, and prevents the user from needing to change their settings to produce different debug output. Additionally, more hints have been added to the crash output to help in decoding the core dump.
• In previous versions, sometimes stderr outputs of the thread backtraces in core dumps would be missing, or only the last one was present due to the reuse of the same output buffer for each thread. Core dumps now include backtraces for all threads, as each thread’s backtrace is now dumped in its own buffer. Also present in core dumps as of this version are the output messages for each thread, which assists developers in determining the causes of issues even when debug symbols are not present.
• This version includes improvements to HAProxy’s watchdog, which detects deadlocks and kills runaway processes. The watchdog will now watch for stuck threads more often, by default every 100ms, and it will emit warnings regarding a stuck thread’s backtrace before killing it. It will stop the thread if, after the first warning, the thread makes no progress for one second. In this way, you should see ten warnings about a stuck thread before the watchdog kills it. Note that you can adjust the time delay after which HAProxy ALOHA will emit a warning for a stuck thread using the global debugging directive warn-blocked-traffic-after. We do not advise that you change this value, but changing it may be necessary during a debugging session.
• This version enhances the accuracy of the memory profiler by improving the tracking of the association between memory allocations and releases and by intercepting more calls such as strdup() as well as non-portable calls such as strndup() and memalign(). This improvement in accuracy applies to the per-DSO (dynamic shared object) summary as well, and should fix some rare occurrences where it incorrectly appeared that there was more memory free than allocated. New to this version, a summary is provided per external dependency, which can help to determine if a particular library is leaking memory and where.

Performance improvements

HAProxy ALOHA 17.0 adds these performance improvements:

• The H2 mux is significantly more performant in this version. This was accomplished by optimizing the H2 mux to wake up only when there are requests ready to process, saving CPU cycles, and resulting in using 30% fewer instructions on average when downloading. The POST upload performance has been increased up to 24x with default settings, and it now also avoids head-of-line blocking when downloading from H2 servers. Two new global directives, tune.h2.be.rxbuf and tune.h2.fe.rxbuf, allow for further tuning of this behavior. Specify a buffer size in bytes using tune.h2.fe.rxbuf for incoming connections and tune.h2.be.rxbuf for outgoing connections. For both uploads and for downloads, one buffer is granted to each stream and 7/8 of the unused buffers is shared between streams that are uploading / downloading, which is the mechanism that significantly improves performance.

• New to this version are two new global directives for tuning QUIC performance:

  • tune.quic.cc.cubic.min-losses takes a number that defines a threshold for how many packets must be missed before the Cubic congestion control algorithm determines that a loss has occurred. This setting allows the algorithm to be slightly more tolerant to false losses, though you should exercise caution when changing the value from the default value of 1. A value of 2 may prove to show some performance improvement, though we do not recommend running this way for extended periods of time, only for analysis, and you should avoid providing a value larger than 2.
  • tune.quic.frontend.default-max-window-size defines the default maximum window size for the congestion controller of a single QUIC connection, by specifying an integer value between 10k and 4g, with a suffix of “k”, “m”, or “g”.

• This version sees an efficiency improvement in regards to the QUIC buffer allocator and using this tunable, you are able to vary the size of the memory required per-connection, thus reducing overallocation.

• The transmission path for QUIC has been significantly improved in this version so that it will now adapt to the current send window size and will use Generic Send Offload to let the kernel send multiple packets in a single system call. This offloads processing from HAProxy ALOHA and the kernel and places it onto the hardware. This is especially meaningful when used on virtual machines where system calls have potential to be expensive.

• Small frames for the QUIC buffer handling now use small buffers. This improves both the memory and CPU usage, as the buffers are now more appropriately sized and do not require realignment. QUIC will always send a NEW_TOKEN frame to new clients for reuse in the next connection. This behavior permits clients to reconnect after being validated without going through the address validation process again on the next connection. In other words, the next established connection will improve network performance when a listener is attacked or when dealing with a lossy network.

• To help improve performance in the case of large configurations that consume a lot of CPU on reload, two global configuration directives tune.renice.startup and tune.renice.runtime are new to this version. These global directives take a value between -20 and 19 to apply a scheduling priority to configuration parsing.

• TCP logs saw a 56% performance gain in this version thanks to the implementation of the line-by-line parser into the TCP log forwarder.

• In regards to log servers, the ring sending mechanism sees improvement in this version, as the load is better balanced across available threads, assigning new server connections to threads with the least load. You can now use the max-reuse directive for TCP connections served by rings. When used for this reason, the sink TCP connection processors will not reuse a server connection more times than the indicated maximum. This means that connections to the servers will be forcefully removed and re-created, which helps to better distribute the load across available threads, thus increasing performance. Make sure that when using this directive that the connections are not closed more than a couple of times per second.

• In previous versions, some users may have seen intense CPU usage by the pattern LRU cache when performing lookups with low cardinality. To remedy this, in this version the cache will be skipped for maps or expressions with patterns with low cardinality, that is, less than 5 for regular expressions, less than 20 for others. Depending on your setup, you could see a savings of 5-15% CPU in these cases.

• As of this version, configured servers for backends are now properly indexed, which saves time in detecting duplicate servers. As such, the startup time for a configuration with a large number of servers could see a reduction of up to a factor of 4.

• Variables have been moved from a list to a tree, resulting in a 67% global performance gain for a configuration including 100 variables.

• We saw a performance gain of, on average, 7% regarding arithmetic and string expressions by removing the need for trivial casts for samples and converters of the same types.

• The Lua function core.set_map() has doubled its performance in speed by avoiding duplicate lookups.

• This version includes a performance gain regarding smoother reloads for large systems, that is, systems requiring a large number of file descriptors and a large number of threads. This gain is due to how file descriptors are handled on boot, shortening initialization time from 1.6s to 10ms for a setup with 2M configured file descriptors.

• The master-worker mode was heavily reworked in this version to improve stability and maintainability. Its previous architecture model proved difficult in maintaining forward compatibility for seamless upgrades; the rework aims to remedy this problem. Per the new model, the master process does nothing after starting until it confirms the worker is ready, and it no longer re-executes itself to read the configuration, which greatly reduces the number of potential race conditions. The configuration is now buffered once for both the master and worker and, as a result, will be identical for both. As such, environment variables shared by both will be more consistent, and the worker will be isolated from variables applicable to the master only. This all improves the separation between the processes. An additional improvement is that this rework will reduce file descriptor leaks across the processes as they are now better separated. All of this to say: you should not notice anything as a result of this change except for improved reliability.

Deprecated features and breaking changes

• The program section is deprecated and will no longer be supported starting HAProxy ALOHA 18.0.
• The configuration options accept-invalid-http-request and accept-invalid-http-response are deprecated. Instead, use accept-unsafe-violations-in-http-request and accept-unsafe-violations-in-http-response.
• Duplicate names in various families of proxies, for example, frontend, listen, backend, defaults, and log-forward sections, and between servers, are detected and reported with a deprecation warning, specifying that the duplicate names will not be supported in HAProxy 3.3.

Version 16.5 Jump to heading #

Key changes in the HAProxy ALOHA 16.5 release include:

Bot management module

• Added the Bot Management module to HAProxy ALOHA. It uses reputational signals and scoring based on our own large, real-world datasets and data science to identify traffic accurately. The module will categorize clients as human, suspicious, bot, verified crawler (search engines), or verified bot/tool/app (non-browser). You can then combine this information with other security features, such as rate limiting and WAF, to create customized bot management policies.
• New botmgmt-profile section, scoring algorithms, and sample fetches to tune the module and increase observability.
• Export Prometheus metrics from bot management data.

Web Application Firewall

• Support for base64 decoding when defining custom rules.
• WAF related Prometheus exporter metrics.
• Process request body without Content-Type, even in “raw” mode.
• Validate incoming data to ensure it contains valid UTF-8 characters, filtering out potentially harmful characters that may attempt to exploit vulnerabilities.

Network management

• Network services gained support for new directives:
  • ip rule enables setting policy-based routing.
  • no arp gives you the ability to disable ARP on an interface.
  • no multicast lets you disable receiving of multicasts.
  • dhcptimeout sets a timeout for DHCP.
  • fctl enables or disables sending and processing of flow control frames.
  • sysset sets a parameter in sys.class.net for root or sys.class.net.$if for interfaces.
• Added support for IPv6 addresses, static routes, and IP rules.
• Added the Network Management CLI, a command-line tool for configuring physical and virtual network interfaces on the load balancer.

WireGuard VPN

• Added WireGuard VPN support to encrypt the configuration synchronization traffic that travels between two HAProxy ALOHA servers. You would use this when the servers are in different data centers and the traffic must go over the public internet.

SSL/TLS Enhancements

• The new crt-store configuration section provides a flexible way to store and consume SSL certificates by separating the certificate storage from their use in a frontend. This provides better visibility for certificate information by moving it from external files and placing it into the main configuration. The crt-store section allows you to individually specify the locations of each certificate component; for example certificates files, key files, and OCSP response files. Aliases provide support for human-friendly names for referencing the certificates more easily on bind lines.
• A new global ssl-security-level directive allows you to set a global OpenSSL internal security level. This enforces the appropriate checks and restrictions per the level specified.
• Explicitly set default TLS certificates.
  • You can now set multiple default certificates using the new default-crt argument on your bind line. You can also indicate a default certificate in a crt-list by marking it with an asterisk.
• Decrypt TLS 1.3 packet captures to backend servers.
  • New to this version, you can now use tune.ssl.keylog to enable the logging of TLS secrets for TLS connections between HAProxy ALOHA and backend servers. This allows you to then use those TLS secrets to use Wireshark to decipher your encrypted packet captures.

Prevent HAProxy from accepting traffic on privileged ports

• Two new global settings, harden.reject-privileged-ports.tcp for TCP connections and harden.reject-privileged-ports.quic for QUIC connections, enable HAProxy ALOHA to ignore traffic when the client uses a privileged port (0 - 1023) as their source port. Clients using this range of ports are suspicious and such behavior often indicates spoofing, such as to launch DNS/NTP amplification attacks. The benefit in using these settings is that during DNS/NTP amplification attacks, CPU is reserved as HAProxy ALOHA will drop the packets on these privileged ports instead of parsing them.

HTTP/2 tuning options

• You can limit the number of total streams processed per incoming connection for HTTP/2 using the global directive tune.h2.fe-max-total-streams. Once this limit is reached, HAProxy ALOHA will send a graceful GOAWAY frame informing the client that it will close the connection after all pending streams have been closed. Usually, this prompts clients to reestablish their connections. This is helpful in situations where there is an imbalance in the load balancing due to clients maintaining long-lived connections.
• HAProxy ALOHA now counts protocol “glitches” and allows you to set a limit on them. Protocol glitches are HTTP/2 requests that are valid but have potential to cause issues; for example, sending a single header as a large number of CONTINUATION frames could cause a denial of service. You can also track the glitches in a stick table to identify buggy applications or misbehaving clients.

Consistent hash server mapping

• When load balancing using a hash-based algorithm (balance hash), HAProxy ALOHA must keep track of which server is which. The new hash-key directive allows you to specify how the node keys, that is, the hash for each server, are calculated. This applies to node keys where you have set hash-type to consistent. What this means is that if you have multiple instances of HAProxy ALOHA, each with its own list of servers potentially listed in different orders, routing will be consistent across your load balancers when you use the hash-key directive. There are three options for hash-key:
  • id: the server’s numeric id if set, or its position in the server list
  • addr: the server’s IP address
  • addr-port: the server’s IP address and port

Memory limit

• The memory limiting mechanism now uses RLMIT_DATA instead of RLIMIT_AS, which prevents an issue where the processes were reaching out-of-memory conditions below the configured limit when using -m <limit> to limit the total allocatable memory to a specified number of megabytes across all processes. In master-worker mode, the memory limit is applied separately to the master and its forked worker process, as memory is not shared between processes.

Unix sockets and namespaces

• This version supports the namespace argument for UNIX sockets specified on bind and server lines. If a permissions issue arises, HAProxy ALOHA will log a permissions error instead of “failed to create socket”, since the capability cap_sys_admin is required for using namespaces for sockets.

gRPC

• Prior to this version, cancellations, which are represented as RST_STREAM frames in HTTP/2 or as STOP_SENDING frames in HTTP/3, were not being properly relayed to the server. This has been fixed. Furthermore, this version adds new fetch methods that indicate whether the stream was canceled (aka aborted) and the error code.

Silence warnings on deprecated directives

• If you want to use deprecated directives and silence warnings, you must also use the new expose-deprecated-directives global directive. This directive applies to deprecated directives that don’t have alternative solutions.

Emergency memory allocation

• The mechanism for emergency memory allocation in low memory conditions has been improved for HTTP/1 and applets. Forward progress in processing is guaranteed as tasks are now queued according to their criticality and which missing buffer they require.

Virtual and optional ACL and Map files

• HAProxy ALOHA now supports virtual ACL and virtual map files.
  • A virtual file doesn’t exist on disk and exists only in memory. The load balancer creates it as an in-memory representation during startup. Virtual files will not persist after restarting the load balancer.
  • When you mark a file as optional, the load balancer will check for it on the filesystem, but if it doesn’t find it, it will assume that the file is virtual. Optional files are useful for allowing startup without a file on disk, but saving the file to disk at a later time for long-term persistence.
  • You can use virtual and optional files in cases where you’ll use the Runtime API to dynamically update the values.

Report the key that matched in a map file

• New map_*_key converters return the key that was matched, rather than the associated value, making it easier to view the reason why the load balancer rerouted a request or took some other action.

Track specific HTTP errors

• Two global directives http-err-codes and http-fail-codes let you specify which HTTP status codes to track when using the http_err_cnt, http_err_rate, http_fail_cnt, and http_fail_rate stick table data types.

Stick table pointers

• Prior to this version, you could use the Runtime API to remove or update a record in a stick table based on its key. You can now specify the record’s unique ID (its pointer) instead of its key to update or delete that record. Use the show table command to retrieve the pointer.

Set fwmark on packets to clients and servers

• HAProxy ALOHA now supports setting an fwmark on connections to backend servers as well as to clients connected on the frontend using the set-fc-mark and set-bc-mark actions. These replace the set-mark action, which had applied only to frontends. Setting an fwmark on an IP packet classifies it so that, for example, it can use a specific routing table.

Set traffic priority

• New in this version, HAProxy ALOHA can modify the header of an IP packet to include the Differentiated Services (DS) field on connections to backend servers in addition to frontend connections to clients. Use the set-fc-tos and set-bc-tos actions (referring to the old Type of Service header field, which has been superseded by DS).

Weights in log backends

• In this version, you can set weights on server lines in your mode log backends. mode log is used for load balancing the Syslog protocol.

Support for UUIDv7 identifiers

• Generate universally unique identifiers that use the UUIDv7 format by using the unique-id-format directive with the uuid fetch.

Reverse HTTP

• A new directive named pool-conn-name provides more flexibility when using reverse HTTP, allowing you to set the name to match with an expression of fetch methods and converters, instead of matching via SNI.

Prometheus

• When configuring the Prometheus exporter, you can include a URL parameter named extra-counters that enables additional counters that provide information related to the HTTP protocol, QUIC, and SSL.

Lua

• Single-threaded Lua scripts using lua-load will see a performance improvement from changes to the thread yielding behavior.
  • Use tune.lua.forced-yield to tune the thread yielding behavior. For scripts that use lua-load, the optimal (and default) value was found to be the maximum of either 500 instructions or 10000 instructions divided by the number of threads. As for scripts loaded using lua-load-per-thread, in cases where more responsiveness is required, the value can be lowered from the default of 10000 instructions. In cases where the results of the Lua scripts are mandatory for processing the data, the value can be increased, but with caution, as an increase could cause thread contention.
• By default HAProxy ALOHA prevents thread and process creation after it starts. This is particularly important executing Lua files of uncertain origin. Generally speaking, it’s a best practice to make sure that no unexpected background activity can be triggered by traffic. However, this may prevent external checks from working, and it may break some very specific Lua scripts which actively rely on the ability to fork.
  • In addition, forking from Lua, or anywhere else, is not reliable, as the forked process could embed a lock set by another thread and cause operations to never cease execution. As such, we recommend that you use this option with extreme caution, and that you move any workload requiring such a fork to a safer solution (such as using agents instead of external checks).

QUIC

• The QUIC protocol is supported by default because we’re distributing a QUIC-compatible OpenSSL library with the load balancer package, rather than relying on the library that comes standard with the operating system.
• Two new global settings improve QUIC performance:
  • Use tune.quic.reorder-ratio to change how quickly HAProxy ALOHA detects outgoing packet losses. Lowering the ratio lowers the number of packets that can be missing ACKs before HAProxy ALOHA takes action. The default value is 50%.
  • Use tune.quic.cc-hystart to enable the use of the HyStart++ (RFC9406) algorithm instead of the Cubic algorithm. The HyStart++ algorithm provides an alternative to the TCP slow start phase of the congestion control algorithm and may show better recovery patterns regarding packet loss.

Invalid request targets rejected for non-compliant URIs

• Parsing is now more strict during HTTP/1 processing for request target validation. This means that where previously, for compatibility, non-standard-compliant URIs were forwarded as-is for HTTP/1, now some invalid request targets are rejected with a 400 Bad Request error. The following rules now apply:
  • The asterisk-form is now only allowed for OPTIONS and OTHER methods. There must now be only one asterisk and nothing more.
  • The CONNECT method must have a valid authority-form. All other forms are rejected.
  • The authority-form is now only supported for the CONNECT method. Origin-form is only checked for the CONNECT method.
  • Absolute-form must have a scheme and a valid authority.

Performance upgrades

• Applets, such as the cache, can also take advantage of the fast forwarding mechanism introduced in version 2.9 for TCP, HTTP/1, HTTP/2, and HTTP/3. This enhancement avoids queuing more data when the mux buffer is full resulting in significantly less memory usage. Disable this behavior using tune.applet.zero-copy-forwarding for applets only, or tune.disable.zero-copy-forwarding globally. In regards to QUIC, simplification of the internal send API resulted in removal of one buffer copy. In regards to QUIC, the fast forwarding now considers the flow control, which reduces the number of thread wakeups and optimizes packet filling. The HTTP/1 mutex now also supports zero-copy forwarding for chunks of unknown size. For example, chunks whose size may be larger than the buffer.
• Performance improved for ebtree on non-x86 machines. This results in approximately 3% faster task switching and approximately 2% faster string lookups.
• Configuration parsing time will see an improvement thanks to a change in server name lookups. The lookups now use a tree, which improves lookup time, whereas before the lookup was a linear operation.
• An improvement to traces, made possible by the implementation of near lockless rings, will enable their use on servers with moderate to high levels of traffic without risk of server impact.
• Stick tables have received a performance boost due to a change in the locking mechanism.
• When defining a dynamic server, use of the enabled argument is now rejected with an error, whereas previously it was only silently ignored.

Fetch methods

• New fetch methods introduced in this version expose data that you can use in ACL expressions:

  Name	Description
  bc_be_queue	The number of streams de-queued while waiting for a connection slot on the target backend.
  bc_glitches	The number of protocol glitches counted on the backend connection.
  bc_nb_streams	The number of streams opened on the backend connection.
  bc_srv_queue	The number of streams de-queued while waiting for a connection slot on the target server.
  fc_glitches	The number of protocol glitches counted on the frontend connection.
  bc_settings_streams_limit	The maximum number of streams allowed on the backend connection.
  fc_nb_streams	The number of streams opened on the frontend connection.
  fc_settings_streams_limit	The maximum number of streams allowed on the frontend connection.
  txn.redispatched	True if the connection has experienced redispatch.

Version 16.0 Jump to heading #

Key changes in the HAProxy ALOHA 16.0 release include:

Web Application Firewall

• This version contains a new and improved web application firewall. Now called the HAProxy Enterprise WAF, it utilizes an improved WAF ruleset and engine (called the Intelligent WAF Engine) that has been trained with machine learning. An optional OWASP Core Rule Set compatibility mode exists for anyone who needs it. However, traffic will pass through the Intelligent WAF Engine first and only traffic marked suspicious will be inspected by the OWASP CRS.

Layer 4 load balancing

• The LB Layer4 (LVS) tab gained new load balancing algorithms:

  • weightedoverflow: The Overflow connection scheduling algorithm implements overflow load balancing according to the number of active connections. It will relay all connections to the server with the highest weight and then overflow to the next server if the number of connections exceeds the server’s weight. Note that this scheduler might not be suitable for UDP because it only uses active connections.
  • weightedfailover: Connections go to the server with the highest weight value, if it is available, and then to the next highest and so forth. This is a good choice for implementing a simple failover solution.
  • maglevhash: Google’s Maglev hashing scheduler. It provides consistent hashing, but with minimal disruption, and each destination receives an almost equal number of connections.
  • twoschoice: This algorithm picks two random servers based on weights and then selects the server with the fewest connections, normalized by weight.

Better isolation of admin services

• To make it easier to segregate administrative services onto a separate subnet, some services now support specifying the network interface on which to run. The new @iface keyword is available for the following services:

  • collectd
  • httpd
  • notify
  • ntpd
  • snmpd
  • sshd
  • syslog

Upgraded kernel

• This version upgrades ALOHA’s Linux kernel to version 6.1.

Performance upgrades

• The latest HTTP implementation in HAProxy ALOHA uses less memory and is 40-60% more CPU-efficient for large data transfers. This is due to faster recycling of buffers, which makes zero-copy forwarding operations more likely. To disable this, set the global directive tune.disable-zero-copy-forwarding.
• The locking code got an upgrade, leading to a performance gain of 2-4% on x86 systems and 14-33% on Arm systems.
• Measures to reduce contention on shared pools improved performance for HTTP/2 and HTTP/3. The HTTP/2 request rate improved from 1.5M to 6.7M requests/second on 80 threads without the shared cache, and from 368k to 4.7M requests/second with the shared cache.
• In the log-forward section, the lock used in the part of the code related to updating the log server’s index during sampling has been replaced with atomic operations to reduce bottlenecks and facilitate ~4x faster log production.
• Improvements to the caching storage mechanism to reduce its lock contention on large systems allow it to scale much more linearly with threads.
• QUIC now uses less memory by releasing resources associated with connections winding down earlier. This improves performance at the termination of a connection when there’s no data left to send.
• The http-request set-map, http-response set-map, and http-after-response set-map directives perform better in this version. The improvement comes from the search reference now being implemented as a tree, making map updates more efficient.
• Thread locking code for stick tables was refined by disentangling lookups from peer updates, and improving some undesired cache line sharing.

Health checks

• Health checks, which in version 15.0 were changed to run on a single thread for better performance, are now more proactive about handing off work to a less busy thread. The new global directive tune.max-checks-per-thread lets you set the number of active checks per thread, above which the thread will try to offload the work. The health check thread will also try to find an existing TLS session to the backend server if it doesn’t have one.
• The external-check directive has a new preserve-env argument that will preserve environment variables.

Syslog load balancing

• A new load balancing mode called log enables you to load balance syslog servers in a backend. Backends with this mode support syslog over UDP. Consult the [balance] (https://www.haproxy.com/documentation/haproxy-configuration-manual/latest/#balance) directive documentation to see which load balancing algorithms are allowed.

QUIC

• On each bind line, you can now set whether QUIC connections should share a listener socket or allocate their own. Set the quic-socket argument to either connection (dedicated socket per connection) or listener (shared listener socket). Previously, you could only configure this behavior at the global level with tune.quic.socket-owner. The default value is connection, which performs the best, but some systems don’t support it.
• This version adds new performance-tuning directives that change the size of the receive and send buffers: tune.rcvbuf.backend, tune.rcvbuf.frontend, tune.sndbuf.backend, tune.sndbuf.frontend.
• The global directive maxsslconn, which sets the maximum, per-process number of concurrent TLS connections, now applies to QUIC connections.
• QUIC connections are now counted in maxconn at their allocation time. Previously, they had been counted only after handshake completion.

Connection handling

• The backlog directive now limits the number of concurrent handshakes and connections waiting to be accepted.
• The new timeout client-hs directive applies to handshakes on TCP, HTTP/1, and HTTP/2. It prevents handshakes from running too long. It defaults to the value of timeout client.

TLS

• You can now specify sigalgs and client-sigalgs on server lines in a backend. The first argument, sigalgs, determines allowed signature algorithms for a TLS handshake. The second, client-sigalgs, determines allowed signature algorithms for client certificate authentication. You can also set these globally with the directives ssl-default-server-sigalgs and ssl-default-server-client-sigalgs.
• The server directive has a new curves argument for setting elliptic curves to use when sending the ClientHello message to a backend server during a TLS handshake. You can also set this globally for all servers with the ssl-default-server-curves directive.

Reverse HTTP

• A new, experimental feature named Reverse HTTP facilitates a two-tier load balancer architecture, where the first HAProxy ALOHA tier initiates a connection to the second HAProxy ALOHA tier. The second tier load balancer then converts the connection to be bidirectional and allows client traffic to pass over that connection. For example, an edge load balancer can accept connections from data center load balancers and then, once established, begin sending client traffic over those connections to the data centers. This is in contrast to the traditional way of configuring backend servers, which is via a static list of server addresses. Instead, this allows a load balancer to self-register itself as an available server within the backend.

Load balancing

• When you set the balance directive to the hash-based algorithm hash, you can then provide a fetch method to calculate the hash key with the utmost flexibility. This version introduces the ability to set hash-type to none, allowing you to disable the built-in hash function and manually hash the key using a converter.

Proxy Protocol

• This version expands support for the Proxy Protocol’s Type-Length-Value (TLV) fields, which let you attach custom data to the Proxy Protocol header. In this version of HAProxy ALOHA, you can:

  • set new TLVs by adding the set-proxy-v2-tlv-fmt argument on a server line.
  • use the fc_pp_tlv fetch method to extract TLVs from the protocol header.
  • use set-proxy-v2-tlv-fmt to forward TLVs you receive with fc_pp_tlv.

Caching

• The cache can differentiate cached objects if they have the Vary HTTP header. However, until now, you could only vary on the Accept-Encoding and Referer headers. This version adds support for varying on the Origin header to support caching CORS responses correctly.

Lua

• HAProxy ALOHA 16.0 adds these Lua features:

  • A new function named core.get_var(var_name) returns proc scoped variables. The older txn:get_var(var_name) returns txn scoped variables.
  • The httpclient class now supports a retries field, which sets the number of times to retry a failed request.
  • The httpclient class now supports a timeout.connect field for setting the maximum time to wait for establishing a connection, in milliseconds. It defaults to 5 seconds.
  • The core.register_action now supports http-after-res.
  • Setting the new global directive tune.lua.log.loggers to on enables sending log messages from your Lua script to the loggers you’ve configured with log lines. Setting it to off disables the logging. The default value is on.
  • Setting tune.lua.log.stderr to on will send log messages to stderr. When set to auto, logging to stderr occurs when tune.lua.log.loggers is set to off or when there’s no proxy-level logger assigned, such as for Lua tasks that run in the background. The default value is auto.

HTTP protocol

• Two new directives, option accept-invalid-http-request and option accept-invalid-http-response, enable the load balancer to accept some invalid characters in URIs that it normally wouldn’t, such as the hash mark (#).

Converters

• This version adds the following converters:

  Name	Description
  ms_ltime	Same as ltime but takes input in milliseconds.
  ms_utime	Same as utime but takes input in milliseconds.
  us_ltime	Same as ltime but takes input in microseconds.
  us_utime	Same as utime but takes input in microseconds.

• The bytes converter now accept variables for its offset and length arguments, which makes it easier to work with the TLV fields in the Proxy Protocol, since they have variable lengths.

• The json_query converter now supports parsing JSON arrays.

Fetch methods

• This version adds the following fetch methods:

  Name	Description
  acl	Evaluates up to 12 named ACLs separated by commas and returns a boolean result.
  pid	Returns the process ID of the current process, which is usually the worker process.
  act_conn	Returns the total number of active, concurrent connections on the process.
  bytes_in	Returns the number of bytes uploaded from the client to the load balancer.
  bytes_out	Returns the number of bytes transmitted from the load balancer to the client.
  accept_date	Returns the exact date when the connection was received by the load balancer.
  request_date	Returns the value for the exact date when the load balancer received the first byte of the HTTP request.
  fc.timer.handshake	Returns the time spent accepting the TCP connection and executing handshakes and is equivalent to %Th.
  fc.timer.total	Returns the total session duration time and is equivalent to %Tt.
  req.timer.idle	Returns the idle time before the request and is equivalent to %Ti.
  req.timer.hdr	Returns the time spent waiting to get the client’s request and is equivalent to %TR.
  req.timer.tq	Returns the sum of %Th, %Ti and %TR and is equivalent to %Tq.
  req.timer.queue	Returns the time spent queued and is equivalent to %Tw.
  bc.timer.connect	Returns the time spent establishing a connection to the backend server and is equivalent to %Tc.
  res.timer.data	Returns the time spent transferring the response payload to the client and is equivalent to %Td.
  res.timer.hdr	Returns the time spent waiting for the server to send a full response and is equivalent to %Tr.
  txn.timer.user	Returns the estimated time as seen by the client and is equivalent to %Tu.
  txn.timer.total	Returns the active time for the HTTP request and is equivalent to %Ta.
  req.cook_names	Returns the names of all cookies in requests.
  res.cook_names	Returns the names of all cookies in responses.
  ssl_bc_curve	Retrieves the name of the curve used in the key agreement when the outgoing connection was made over an SSL/TLS transport layer.
  ssl_fc_curve	Retrieves the name of the curve used in the key agreement when the incoming connection was made over an SSL/TLS transport layer.
  cur_client_timeout	Retrieves the value in milliseconds for the currently configured client timeout.
  fc_pp_tlv	Returns the TLV value for a given TLV ID. This fetch may be useful in detecting errors related to duplicate TLV IDs.

Version 15.5 Jump to heading #

Key changes in the HAProxy ALOHA 15.5 release include:

PacketShield QUIC support

• PacketShield received an update that allows it to protect HTTP/3 traffic over the QUIC protocol. QUIC is a UDP-based protocol.

Email alerts as a Lua module

• The mailers feature, which lets you send email alerts about the load balancer, has been ported to be a Lua module. The benefit to you is the ability to edit the Lua code to suit your needs, such as to customize the alert messages that the load balancer produces. To enable it, load the mailers Lua module using the lua-load directive in the global section.

Lua updates

• A new event framework allows Lua modules to subscribe to some load balancer events and execute event handler functions. Events you can subscribe to include when servers are added, deleted, or go up or down. Use the function Server.event_sub to subscribe to events.
• A new core.queue function lets you create a first-in first-out data structure in Lua.
• The Server class gained new functions for accessing information about backend servers, including getting the server’s name (get_name), the number of active sessions (get_cur_sess), the number of pending connections (get_pend_conn), and other functions.
• A new global directive named tune.lua.burst-timeout terminates the Lua process if it exceeds the timeout value without ever yielding execution back to the load balancer. A well-behaved Lua module will yield execution on the current thread back to the load balancer during long-running tasks, to be continued later.
• The Lua’s HTTP client that ships with the load balancer is able to resolve DNS hostnames thanks to a default resolvers section invisibly added to the configuration. If you do not use the HTTP client in Lua, then you can disable this by setting the new global directive httpclient.resolvers.disabled to on.

HTTP compression

• The HTTP compression directives have an updated syntax that allows you to compress both responses and requests. For example, you can now compress requests that contain JSON messages before relaying them to backend servers. See the compression direction, compression algo-req, compression algo-res, compression type-req, and compression type-res directives.

TLS signing algorithms and curves

• The new global directives ssl-default-bind-client-sigalgs and ssl-default-bind-sigalgs, as well as the new bind arguments client-sigalgs and sigalgs let you list the TLS signing algorithms the load balancer will use or accept during a TLS handshake and during validating a client certificate.
• The curves argument, which sets a list of elliptic curve algorithms negotiated during the TLS handshake, is now available on the server and default-server lines.

Default ALPN values

• You no longer need to specify alpn h2 on a bind line to enable HTTP/2. This is now the default value and will fall back to HTTP/1.1 if the client does not support HTTP/2. Also, bind lines that use the QUIC protocol will default to having an alpn argument set to h3 for HTTP/3.

HTTP Forwarded header

• The new directive option forwarded will add a Forwarded header to HTTP requests, passing the client’s IP address to backend servers. This is the successor to the non-standard X-Forwarded-For header. New converters let you validate and read the header: rfc7239_is_valid, rfc7239_field, rfc7239_n2nn, and rfc7239_n2np.

Configurable sticky counters

• The new global directive tune.stick-counters lets you increase the number of stick table sticky counters, which had previously been a built-in constant set to 3.

HTTP actions

• The http-after-response directive gained an expanded set of actions, including set-map, sc-add-gpc, set-log-level, and others.
• All action directives now support the sc-add-gpc action.

HTTP/2 tuning options

• New global directives enable tuning the HTTP/2 protocol. They include tune.h2.be.initialize-window-size, tune.h2.be.max-concurrent-streams, tune.h2.fe.initial-window-size, tune.h2.fe.max-concurrent-streams, tune.h2.initial-window-size and tune.h2.max-concurrent-streams.

Listener shards

• The new global directive tune.listener.default-shards simplifies setting shards. Sharding is a feature for servers with a high number of threads that makes it easier to replicate a bind line to create multiple listeners and assign worker threads to the listeners. The goal is to reduce thread contention. You can set the directive to a number of shards, to the value by-thread, or to the value by-group. Setting by-group is especially convenient since you can then group threads and assign them together to a listener, and so this is the default setting.

Other performance tuning options

• The bind line’s cpu-map argument, which associates threads with CPUs, now accepts a list, delimited by commas.
• The bind line’s thread argument can now be set to a comma-delimited list of thread ranges instead of just a single range.
• The new global directive tune.listener.multi-queue controls how work is distributed to threads assigned to a listener. A value of on, which is the default, passes work to the least busy thread. A value of fair passes work in a round-robin rotation.
• The new global directive tune.memory.hot-size allows you to set the amount of memory kept hot in the local cache, but the default value of 512 KB should be sufficient for most.

HTTP request body and URL parameters

• The req.body_param, url_param, and urlp_val fetch methods now accept an additional argument that enables case-insensitive matching of parameters, which makes it easier to configure the load balancer’s behavior to agree with the web server’s behavior. Also, a new converter named param extracts name-value parameters from a string while letting you set the delimiter used between parameters.

Round-trip time

• The new fetch methods bc_rtt and bc_trrvar return the round-trip time between the load balancer and a backend server. You can configure them to return values in milliseconds or microseconds.

Preprocessor directives

• This version introduces two new preprocessor functions. The strstr function returns true if the inspected string contains a given string. The enabled function returns true if the given option is enabled at runtime.

Proxy Protocol

• Proxy Protocol v2 has been updated in this version to allow the load balancer to extract extra information from the Proxy Protocol header when a TCP connection is established on the frontend. The new fetch method fc_pp_tlv supports extracting a TLV (Type-Length-Value) from the protocol header.

Version 15.0 Jump to heading #

Key changes in the HAProxy ALOHA 15.0 release include:

HTTP/3 over QUIC

• This version adds support for the HTTP/3 protocol over QUIC.

TLS

• The bind directive’s ca-ignore-err and crt-ignore-err arguments, which let you list TLS errors to ignore, now accept human-readable names in addition to numeric IDs. Refer to the OpenSSL list of error codes to see which values are available.

Lua

• You can now pass optional arguments to your custom Lua scripts from within your L7 configuration file. The lua-load and lua-load-per-thread directives accept one or more arguments after the first argument, which is always the script’s filepath. Then, in your script use the built-in table.pack(...) function with an ellipsis as its argument to collect arguments into a variable of type table.

Multithreading

• A new global directive named thread-group lets you place a range of threads into a group. Once in a group, you can assign those threads to a listening address by adding the thread argument to a bind line in a frontend or listen section. On servers with many CPU cores and thus many threads, allocating a subset of threads to handle connections like this can improve performance by reducing the number of threads competing for work. You can define up to 64 thread groups, each including up to 64 threads.
• A new global directive named thread-groups lets you set the number of thread groups to create and HAProxy ALOHA will divide the threads available on your server into that number of groups. The maximum number is 64.

Converters

• This version adds the following converters:

  Name	Description
  table_expire(<table>[,<default_value>])	Returns the remaining time before a given key will expire in the stick table, as well as how long ago a given key was last seen.
  table_idle(<table>)	Returns the time the given key has remained idle since the last time it was updated.
  host_only	Converts a string that contains a Host header value and removes its port.
  port_only	Converts a string that contains a Host header value and returns only its integer port.
  x509_v_err_str	Converts a numerical value to its corresponding X509_V_ERR constant name, which is useful for setting ACL expressions based on different client certificate errors (expired certificate, revoked certificate, etc.).

Performance upgrades

• Server health checks, which run at an interval, now fire on the same thread exclusively rather than allowing any available thread to perform the task. This has reduced latency by decreasing competition among threads.
• Stick tables became more efficient by changing the type of lock used to restrict multiple threads from accessing a table simultaneously. By revising internal code to use a read-write lock, which allows multiple threads to read from the table simultaneously, but allows only one thread to write, performance improved.
• The integrated HAProxy reduces latency by more aggressively using idle connections when sending HTTP requests to backend servers. If you leave the defaults, or if you manually set the http-reuse directive in a backend to safe, reusing idle connections is enabled and you are choosing the safest mode. That is, a client’s first HTTP request will be dispatched to a backend server on a new thread guaranteed to not be closed, and only subsequent requests will use idle connections, which have the risk of closing unexpectedly. In this release, as long as you have also set the retry-on directive in that backend to retry the connection in case of failure, HAProxy ALOHA will use an idle connection for a client’s first request too. Set retry-on to include conn-failure, empty-response, and response-timeout.

Deprecated features and breaking changes

The following keywords are deprecated:

• The bind-process directive has been removed.
• The process argument on a bind line has been removed.

Version 14.5 Jump to heading #

Key changes in the HAProxy ALOHA 14.5 release include:

Advanced WAF

• New match zones, $COOKIES_VAR and $COOKIES_VAR_X allow rules to match violations found in specific HTTP cookies, complementing the less specific $HEADERS_VAR and $HEADERS_VAR_X match zones.
• A new variable, txn.<filter>.wlcnt returns the number of disabled rules that would have matched the current request.
• The filter waf line now supports a parameter named log-wl that includes disabled WAF rule violations in extended logs.
• The filter waf line now supports a parameter named log-ext-nonzero that enables extended logs only when the violated rule had a non-zero score or triggered an immediate action, cutting down on noise in the logs.
• The filter waf line now supports a parameter named table-categorized that prefixes entries in the violated rules stick table with the category of the violated rule.
• The filter waf line’s body-limit parameter defaults to the global option waf-body-limit, which now defaults to tune.bufsize rather than the compile-time value of BUFSIZE.

ModSecurity WAF

• To associate WAF logs with load balancer logs, you could already use the unique identifier that ModSecurity creates by referencing the txn.<filter>.unique_id variable, appending it to your load balancer logs. Now, you can define a different unique ID format by setting the use-unique-id-format parameter on the filter modsecurity line and then defining a new format with the unique-id-format directive.
• A new parameter use-vars on the filter modsecurity line disables ModSecurity from denying suspicious requests and delegates that to the load balancer. A variable named txn.<filter>.block returns true when the WAF would have denied the request. You can read this variable and then decide on a response policy to enforce. Other variables that support this include txn.<filter>.error, txn.<filter>.status, and txn.<filter>.url.

Traffic shaping

• New directives, filter bwlim-in and filter bwlim-out, support limiting upload and download speeds for clients. Set bandwidth limits that apply per HTTP stream or to all streams associated with a stick table entry, such as to set a limit per client IP address or per backend application.

Load balancing

• A generic load balancing algorithm named hash was introduced and serves as a replacement for the more specific source, uri, url_param, and rdp-cookie algorithms. It accepts a fetch method as a parameter, which indicates the data used to calculate the hash.

TLS and mTLS

• When you enable client certificate authentication with the verify required parameter on a bind line, you must also specify the ca-file parameter, which indicates the CA certificate used to verify the client’s certificate. Now, ca-file accepts a path to a directory of CA certificates.
• Similarly, in a backend, you can set the ca-file parameter on a server line to verify the backend server’s TLS certificate against a known CA. This ca-file parameter now accepts a path to a directory of certificates or you can set it to @system-ca to load your system’s list of trusted CAs.

Lua

• The Lua programming language integration gained the CertCache class, which lets you update an SSL certificate in the load balancer’s runtime memory.
• The Lua httpclient class, which lets you make non-blocking HTTP calls, now supports a dst parameter and a timeout parameter. The former sets the destination address and the latter sets a timeout server value. New global directives support this: httpclient.ssl.ca-file, httpclient.ssl.verify, httpclient.ssl.resolvers.id, and httpclient.resolvers.prefer <ipv4|ipv6>.

Fetches and converts

• New fetches have been added: last_rule_file, which returns the name of the configuration file (e.g. haproxy.cfg) that contains the last line processed during stream analysis, and last_rule_line, which returns the line number. Use this to locate the http-request deny line that stopped a request, for example.
• A new converter has been added: add_item, which concatenates strings with a delimiter between them, such as a semicolon.

Other keyword changes

• The set-var directives, such as http-request set-var, now accept a second parameter to only set the variable if a condition is true. Conditions include: ifexists, ifnotexists, ifempty, ifnotempty, ifset, ifnotset, ifgt, iflt. For example, to set the variable only if it has not already been set: http-request set-var(txn.myvariable,ifnotset) req.hdr(X-MyValue).

Performance upgrades

• Performance optimizations were made to the task scheduler, connection dequeueing, and connection stream code.

Version 14.0 Jump to heading #

The changes in this release focus on two major features: Global server load balancing (GSLB) and the Advanced Web Application Firewall.

You can now run ALOHA as a DNS server and enable GSLB to load balance traffic across multiple datacenters. DNS records will direct clients to the datacenter closest to them or to the one that is reporting as healthy.

The Advanced WAF is an alternative to the ModSecurity WAF and provides a stricter set of rules, which requires more tuning to allow valid traffic through, but has a better requests-per-second throughput.

• Upgraded to HAProxy Enterprise 2.5r1.
• Added the ability to run ALOHA as a DNS server for global server load balancing.
• Added a new WAF mode called Advanced WAF that you can use instead of ModSecurity.

Version 13.5 Jump to heading #

Key changes in the HAProxy ALOHA 13.5 release include:

• Upgraded to HAProxy Enterprise 2.4r1.
• Added a command-line interface that you can access from the web UI.
• The virtual appliance images now have a bigger disk > 8GB.
• Web UI warnings are now also printed when logging with SSH or the console.

Version 13.0 Jump to heading #

Key changes in the HAProxy ALOHA 13.0 release include:

• Kernel updated to 4.19.189.
• Upgrade to HAProxy Enterprise 2.3r1.
• Additional management components, including the Dataplane API.
• Additional security components, including ModSecurity WAF.
• Graphical file manager in the WUI.
• curl utility on the CLI.
• Update to latest Update module
• Upgrade to latest Antibot module.
• Upgrade to latest Fingerprint module.
• Custom routing table target on the flowmgr flow manager.
• 8k maximum message length to on syslog.
• OpenSSL 1.1.1k.
• Better compliance with container environments (additional signals handled in sysvinit).

Version 12.5 Jump to heading #

Key changes in the HAProxy ALOHA 12.5 release include:

• Kernel updated to 4.19.155.
• Upgrade to HAProxy Enterprise 2.2r1.
• RADIUS authentication is now supported.
• Prometheus exporter now available.
• Licenses are now autosaved on upload.
• Update to latest Update module.
• Upgrade to latest Antibot module
• Obsolete ALOHA image aloha-albevalonly-vmplayer.zip.
• timeout command from coreutils is now available.
• VRRP information has been added to the tech support output.
• Tech support process output improved.

Version 12.0 Jump to heading #

Key changes in the HAProxy ALOHA 12.0 release include:

• Kernel updated to 4.19.123.
• Upgrade to HAProxy Enterprise 2.1r1.
• Support for SSO SAML.
• Support for USB3 (XHCI) on the ALB 5300.
• Inotify kernel support.

Deprecated features and breaking changes

• The lb-sanitize module has been removed.

Version 11.5 Jump to heading #

Key changes in the HAProxy ALOHA 11.5 release include:

• Support of SNMP v3.
• Upgrade to HAProxy Enterprise 2.0r1.
• All fixes and features from ALOHA v11.0.7.
• Support of new hardware for model ALB5300.

Version 11.0 Jump to heading #

Major features in ALOHA 11.0 include an upgrade to HAProxy Enterprise 1.9r1 which comprises the following new and improved functionalities:

• End-to-end HTTP/2 support.
• gRPC support.
• Connection pooling to backends.
• Connection multiplexing to backends.
• Improved threading.
• Automatic threading configuration.
• Cache Improvements (supports objects of 2GB).
• Server Queue Priority Control.
• Random Load Balancing Algorithm, which supports configurable draw which can be used for Power of Two Random Choices Load Balancing.
• Early Hints (HTTP 103) and Misdirected Request (HTTP 421) support.
• Runtime API improvements.
• New fetches.
• New Converters.
• System Components version upgrades.
• Upgrade all components with an OpenSSL dependency to be compliant with v1.1.0b (OpenSSL 1.0.2 was removed).
• Keepalived upgraded to 1.4.5.
• Automatic network configuration using VMWare OVF properties (VA only).

Version 10.5 Jump to heading #

New and/or improved features to ALOHA 10.5 include:

• LDAP support which allows authentication of users against a remote LDAP server on CLI/WUI.

• Configurable access type per user.

• Use of PAM for authentication.

• Upgrade to HAProxy Enterprise 1.8r2.

• Security:

  • Update to OpenSSL 1.1.1a support for Layer7 SSL offloading.
  • Update to OpenSSL 1.0.2q to fix latest CVEs.

• Kernel update to latest 4.9 mainline version.

• PacketShield: Use of hardware acceleration to compute a secure hash for SYN cookies.

• Rework of CPU mapping to support nbproc or nbthread equal to max CPU (setting to half of available CPU still offers the best balanced performances).

Version 10.0 Jump to heading #

HAProxy ALOHA 10.0 brings the following improvements:

Latest version of HAProxy Enterprise

• Upgrade to HAProxy Enterprise 1.8r1.

HTTP/2 Protocol Support

• HAProxy Enterprise now supports HTTP/2 on the client side (i.e. the front-end sections) and can act as a gateway between HTTP/2 clients and your HTTP/1.1 and HTTP/1.0 applications.

Multi-threading Model

• The multi-threading model is a feature that allows HAProxy to start multiple threads within a single process.

Server-template Configuration Directive

• The server-template configuration directive allows you to instantiate a number of placeholder backend servers in a single configuration line, instead of having to add tens or hundreds of configuration lines explicitly.

Dynamic Cookies

• A new keyword dynamic for the directive cookie now exists to enable cookie-based application persistence.

SSL/TLS Mode Async

• The OpenSSL library version 1.1.0 and above supports asynchronous I/O operations. This means that the key computation phase (the heaviest part of the TLS protocol) can be run in a non-blocking way in HAProxy.

New Sample Fetches

• HAProxy Enterprise can extract data from traffic passing through it. We call these functions “sample fetches”. More information about sample fetches can be found under “Fetching Data Samples” in the HAProxy Enterprise documentation.

Version 9.5 Jump to heading #

HAProxy ALOHA 9.5 brings the following improvements:

Major Features

• Upgrade to HAProxy Enterprise 1.7r2.
• Single-Sign-On (SSO) Module.
• DNS for Service Discovery.
• Small Object Caching.

Monitoring

• Support of collectd’s statistics export protocol.

SSL/TLS

• Upgrade to openssl-1.1.1 with tls1.3 pending support.
• Enhanced asymmetric performances using multi-CPU engine.

Version 9.0 Jump to heading #

HAProxy ALOHA 9.0 is now powered by HAProxy Enterprise 1.7r1, and brings the following improvements:

Major Features

• Upgraded to HAProxy Enterprise 1.7r1.
• PCRE JIT support.
• Namespace support.
• DNS improvements.
• Server: init-addr indicates the order to resolve the server’s address upon startup. The method none indicates specifically that the server should start without any valid IP address in a down state.
• New srv_admin flag: SRV_ADMF_RMAINT.
• Listener: accept-netscaler-cip option added to the bind keyword.
• Added tcp-request connection expect-netscaler-cip layer4.
• Log format: error management improvements.

SSL/TLS

• Upgrade to openssl-1.1.0 for LB Layer7 SSL offloading.
• lb-update support for TLS session ticket keys.

Route Health Injection

• Upgraded route injection daemon to support newest features.

VRRP

• Upgraded VRRP daemon.

Miscellaneous

• Upgrade to Linux kernel 4.9.
• Automatic flash’s partitions resizing during upgrade.
• New models support: ALB5200 and ALB3200.

New fetches

• fe_name
• be_name
• fc_rcvd_proxy
• xx-hash converters

Command Line Interface

• show cli sockets lists the CLI sockets.
• show stat now supports a proxy name.
• show errors now supports a proxy name; now also capable of dumping only request or response.
• RMAINT state remains when setting an IP address on the CLI.

LUA Scripting

• CLI handler for LUA.
• Allow argument for actions.
• HAProxy now has variable access to the applets.
• Function that returns true if the channel is full.
• IP addresses and network manipulation.
• Utility to check for a boolean argumentA tokenize function.

Version 8.5 Jump to heading #

HAProxy ALOHA 8.5 brings the following improvements:

New Features

• Powered by HAProxy 1.6r2.
• TCP layer statistics are available in the form of new sample fetches (rtt, rtt variance etc, retransmits, losses, etc.).
• New dst_is_local, src_is_local sample fetches make it easier to handle locally initiated connections in contrast to remote connections.
• The peers protocol was updated to version 2.1 with support for synchronization of expiration dates.
• CLI keyword registration to allow modules to plug-in on the command line and receive actions (example: refresh now).
• Ability to disable SO_REUSEPORT with a new bind directive: noreuseport.
• New possibilities for accessing load balancer internals with LUA.
• Idle time in logs is now ignored by default for time measurements, so that HTTP request time corresponds to the time elapsed between the first character and the full request. The handshake time is also available to measure the time spent in SSL/PROXY handshakes.
• Stick-tables now use native types to guarantee better accuracy of tracked information, especially binary keys.
• Mailers now support a configurable connection timeout.
• Changing server address, port and checkport is now possible from the CLI
• New tcp-request session rule-sets makes it possible to track some L5-only information; for instance, anything negotiated in the handshake such as SSL DN or the client’s IP address as passed by the PROXY protocol. Previously, it was needed to do it in tcp-request content rules, which would count one new connection event per request.
• New stats field for denied connections and denied sessions.
• New hash-balance-factor directive for consis.
• New tent hashing method.
• New http-response rule track-sc.

SSL/TLS

• SNI filters supported in multi-type certificates.
• Support of lb-update for TLS session ticket keys.

PacketShield and DDOS protection

• Half-stateful mode for direct server return.
• ICMP rate limiting.
• Geolocalization filtering support.

API REST/JSON

• Support for tcp-check rules.

Miscellaneous

• Kernel version Linux 4.4.
• Review partition sizes on flash.
• LUA support added to the load balancer.
• Support for the LVS sync daemon in the init script.

Version 8.0 Jump to heading #

HAProxy ALOHA 8.0 brings the following improvements:

New Features

• Powered by HAProxy 1.6r1.

SSL/TLS

• Multi-certificate key type support.

PacketShield and DDOS protection

• IPv6 support.
• Stateful protection for all UDP protocols (SNMP, UPnP, etc.).
• Notification by traps or mail.
• New global counters.
• Ability to manually enable countermeasure.
• Counters available through SNMP.

WUI

• Graphs for PacketShield.

VRRP

• Support of VRRPv3.
• Support of Virtual MAC addresses.

LB Layer7

• New http-reuse to share unused server-side connections for multiple clients.
• export of HAProxy’s show info through SNMP.
• Support of double quotes in the configuration.
• DNS resolution of server name at run time.
• GZIP stateless compression.
• Support of variables at run time.
• Stick tables statistics synchronization.
• New hash-type load-balancing algorithm crc32.
• Redispatch interval.
• Dynamic generation of SSL certificates.
• New map type: map_regm to allow matching zones in the regex.
• Mathematical converters can use a variable generated at runtime.

New http-request rules

• sc-inc-gpc0(<sc-id>)
• sc-set-gpt0(<sc-id>) <int>
• silent-drop
• set-src <expr>

New http-response rules

• set-status
• set-var(<var-name>) <expr>
• sc-inc-gpc0(<sc-id>)
• sc-set-gpt0(<sc-id>) <int>
• silent-drop

New tcp-request connection rules

• sc-inc-gpc0(<sc-id>)
• sc-set-gpt0(<sc-id>) <int>
• silent-drop

New tcp-response content rules

• set-var(<var-name>) <expr>
• sc-inc-gpc0(<sc-id>)
• sc-set-gpt0(<sc-id>) <int>
• silent-drop

New tcp-request content rules

• sc-inc-gpc0(<sc-id>)
• sc-set-gpt0(<sc-id>) <int>
• set-var(<var-name>) <expr>
• silent-drop

New converters

• capture-req(<id>)
• capture-res(<id>)
• set-var(<var name>)
• table_gpt0(<table>)

New fetches for internal states

• bin(<hexa>)
• bool(<bool>)
• int(<integer>)
• ipv4(<ipv4>)
• ipv6(<ipv6>)
• meth(<method>)
• str(<string>)
• var(<var-name>)

Layer 4

• sc_get_gpt0(<ctr>[,<table>])
• sc0_get_gpt0([<table>])
• src_get_gpt0([<table>])

Layer 6

• req.ssl_st_ext
• res.ssl_hello_type

Layer 7

• unique-id

Version 7.5 Jump to heading #

HAProxy ALOHA 7.5 brings the following improvements:

Major features

• Configuration deployment using templates in the GUI.
• PacketShield, our packet flood protection solution, now also available on Hardware appliances 1G interfaces.
• SYNPROXY module, to use in conjunction with PacketShield to enable protection for LVS and traffic routed through the appliance.

HAProxy Enterprise Improvements

• Faster processing of ACLs by using a match result cache.
• Ability to analyze HTTP requests body (frontend option option http-buffer-request).
• Faster HTTP gzip compression.
• Traffic capture.
• Comments in tcp-check rules.
• Server side TLS SNI.
• Server side tcp-ut timeout.

New sample fetches

• ssl_fc_is_resumed
• req.ssl_ec_ext
• req.body_param
• req.body_len
• req.body_size

Additional Diagnostic Tools in GUI tab

• Layer 7 errors
• Layer 7 info
• Tech support

HAProxy Enterprise features through the API

• stick-table, stickreq, stickrsp
• tcp-check
• adv-check-http-version
• http-request log-level
• listener tcp-ut