Back in the spotlight, HAProxy 3.1 builds on its history of innovation, delivering improvements that ensure it remains the go-to open source load balancer! As usual, all the features announced in this release will be incorporated into the next enterprise release (HAProxy Enterprise 3.1).
HAProxy 3.1 brings improvements to observability, reliability, performance, and flexibility. So everything we love about HAProxy is now even better! Continual refinement of the things that matter most to HAProxy users is what helps HAProxy remain the G2 category leader in API management, container networking, DDoS protection, web application firewall (WAF), and load balancing.
In this blog post, we'll cover the changes in a short and digestible format. For a deeper dive into what’s new in version 3.1, subscribe to our blog to make sure you don’t miss part 2 (coming soon)!
Watch our webinar HAProxy 3.1: Feature Roundup and listen to our experts as we examine new features and updates and participate in the live Q&A.
New to HAProxy?
HAProxy is the world’s fastest and most widely used software load balancer. It provides high availability, load balancing, and best-in-class SSL processing for TCP, QUIC, and HTTP-based applications.
HAProxy is the open source core that powers HAProxy One, the world’s fastest application delivery and security platform. The platform consists of a flexible data plane (HAProxy Enterprise and HAProxy ALOHA) for TCP, UDP, QUIC and HTTP traffic; a scalable control plane (HAProxy Fusion); and a secure edge network (HAProxy Edge).
HAProxy is trusted by leading companies and cloud providers to simplify, scale, and secure modern applications, APIs, and AI services in any environment.
How to get HAProxy 3.1
You can install HAProxy version 3.1 in any of the following ways:
Install the Linux packages for Ubuntu / Debian.
Run it as a Docker container. View the Docker installation instructions.
Compile it from source. View the compilation instructions.
Major changes
First, let's cover the most important changes in HAProxy 3.1. These changes substantially modify how things were done in previous versions or introduce entirely new capabilities.
Log profiles
HAProxy logs have always been known as a treasure trove of information, offering extreme flexibility in customizing the log format. While this approach has served engineers well for years, evolving needs from DevOps and SecOps teams have pushed this feature to the next level. With HAProxy 3.1, you can now use log profile, a new configuration area designed to define the log format used at different stages of a transaction. These stages include key steps like accept, request, connect, response, close, error, or even any.
Each log profile is linked to a specific log destination server, which brings several advantages:
Tailored log formats per destination: No need to rely on post-processing at the syslog server before forwarding log entries again.
Logging at multiple stages: Capturing logs at various steps of the transaction simplifies troubleshooting and provides deeper insight into what’s happening.
Additionally, you can pair log profiles with the new do-log action, which lets you generate even more detailed logs as traffic flows through HAProxy. This gives you even greater control and visibility over your infrastructure.
Traces
Traces provide detailed debug messages about how different subsystems are running. They give you a way to dive deeply into diagnosing problems, offering valuable insights when dealing with complex issues. While traces have been part of HAProxy for a while, they were considered experimental and primarily used by developers. With HAProxy 3.1, traces are now officially supported (GA) and much easier to use—though they remain a tool designed for advanced debugging scenarios.
You can enable traces for various subsystems, including h1, h2, h3, quic, qmux, fcgi, spop, peers, check, and more. Traces now have their own dedicated configuration section and can even be controlled using the HAProxy Runtime API.
We’ll be publishing a dedicated blog post soon to walk you through everything you can do with traces, so stay tuned—it’s a game-changer for troubleshooting!
Rework of SPOE
Stream Processing Offloading Engine (SPOE) enables administrators, DevOps, and SecOps teams to implement custom functions at the proxy layer using any programming language. However, as HAProxy’s codebase has evolved, maintaining the original SPOE implementation became a bit more complex.
With HAProxy 3.1, SPOE has been updated to fully support HAProxy’s modern architecture, allowing greater efficiency in building and managing custom functions. It’s now implemented as a “mux”, which allows for fine-grained management of SPOP (the SPOE Protocol) through a new backend mode called mode spop. This update brings several benefits:
Support for load-balancing algorithms: You can now apply any load-balancing strategy to SPOP backends, optimizing traffic distribution.
Connection sharing between threads: Idle connections can be shared, improving efficiency on the server side and response times on the agent side.
Rest assured, backward compatibility has been a priority. If you’ve built SPOA (Agents) in previous versions of HAProxy, they’ll continue to work just fine with HAProxy 3.1.
HTTP/2 Performance
In the HTTP/2 protocol, each stream has a window size: this is the maximum volume of data that can be transferred before requiring an acknowledgement. By increasing this window size dynamically during a stream’s lifetime, performance can be significantly improved.
With HAProxy 3.1, this process is now automatic. HAProxy adjusts the per-stream window size for optimal efficiency, using dedicated buffers for each stream alongside a shared buffer pool. This enhancement delivers a dramatic boost in performance:
POST uploads are now up to 20x faster.
Head-of-line blocking is reduced when downloading from HTTP/2 servers, improving responsiveness.
For even more control, a couple of new tuning parameters have been introduced: tune.h2.fe.rxbuf for frontends and tune.h2.be.rxbuf for backends, allowing you to further extend the default settings to match your specific needs.
New Master/Worker Model
HAProxy 3.1 introduces significant improvements to the master/worker model, making the separation of roles cleaner and more efficient.
In previous versions, the master process was responsible for parsing the configuration and then undoing it before handing it over to the workers. This approach occasionally led to issues like inconsistencies during reloads or file descriptor leaks.
Now, the master’s role is limited to starting the worker processes. The workers handle configuration parsing and perform their tasks independently, resulting in more consistent operation across reloads.
Noteworthy changes
Beyond the major changes, HAProxy 3.1 includes several changes that simplify the configuration, improve performance, or extend existing functionality.
New
quic-initial: Introduces actions to execute during the QUIC handshake, similar totcp-requestactions for TCP. The currently supported actions arereject,accept,dgram-drop(for a silent drop), andsend-retry(to force a retry when in 0-RTT for example). These actions help prevent abuse or enforce source-based filtering so that the client cannot even engage in a handshake.New
set-retriesaction: Available intcp-requestandhttp-requestrules, this action allows HAProxy to dynamically change the number of desiredretriesat runtime. This is particularly useful for adapting HAProxy’s behavior to specific parts of an application, or for learning the desired number ofretriesfrom client-side information.New
when(condition)converter: Evaluates thecondition, and if true passes the input sample as-is; otherwise it returns nothing. This allows emitting extra debugging information or triggering some actions only when some conditions are met. This prevents filling the logs with unnecessary information and can be combined with thebs.debug_strandfs.debug_strfetches to help developers better understand a problem.New
bs.debug_str/fs.debug_strfetches: Report useful debugging information from HAProxy’s internal layers. Use these for debugging purposes. You can trigger them with thewhen()converter above.New
last_entity/waiting_entity fetches: Indicate what waiting operation was interrupted by a timeout or an error. For example, it may help detect problems with Lua scripts or SPOA subsystems like compression, or even detect when a full body was not received. This can also report the last rule that was evaluated by HAProxy because of anaccept/redirectordenyfor example.QUIC pacing: Smooths packet distribution over time to avoid overflowing buffers on the path to client applications. (e.g. browser). While it incurs higher CPU usage, it can improve performance by 10–20x on lossy networks or with slow clients. This feature is currently experimental.
New
bbrcongestion algorithm for QUIC:bbr(Bottleneck Bandwidth and Round-trip propagation time) uses network measurements, including packet loss, to model the path and determine optimal data transfer speeds. This allows higher throughput and lower queueing than other congestion algorithms on lossy networks or weak clients.bbrrelies on the pacing mechanism and as such is also currently experimental.Option
httpchknow supports a Host header: This is one of the oldest checks in HAProxy and it now officially supports a Host header, eliminating the need for a workaround with fake strings in thehttpchkline.New server’s init-state: allows a server to remain down (not on) at startup or when leaving maintenance until the first health check succeeds.
Deprecated features
Several features are now marked as deprecated and will trigger warnings unless you set the expose-deprecated-directives global option. Unless noted otherwise, these features will be removed from version 3.3. Most of the deprecated features have a replacement.
The
programsection is marked as deprecated in this release and will be removed in HAProxy 3.3.The
opentracingfilter will be marked as deprecated in HAProxy 3.3 and will be removed in HAProxy 3.5.Another noticeable change is to block duplicate names between various families of proxies (
frontend/listen/backend/defaults/log-forwardetc) and between servers. Duplicates are now properly detected and will report a deprecation warning in 3.1, indicating a breakage in 3.3.The legacy C-based mailers are also deprecated in 3.1 and will be removed in 3.3. The customizable Lua mailers introduced in HAProxy 2.8 will then be the only way to set up mailers.
Breaking changes
HAProxy 3.1 did not introduce any breaking changes. However, to improve communication about future changes, the R&D team created a Wiki page. This page provides a summary of upcoming breaking changes and the releases in which they are planned, helping you stay informed and prepared: https://github.com/haproxy/wiki/wiki/Breaking-changes.
Conclusion
As always, none of this would be possible without the amazing HAProxy community. Your feedback, suggestions, code commits, testing, and documentation benefits millions of users worldwide as they use HAProxy to master their application traffic. To everyone who contributes – thank you.
Subscribe to our blog below and stay tuned for further deep dives on the latest updates from HAProxy 3.1. And in case you missed it, catch up with the new features we announced earlier this month in HAProxy Enterprise 3.0.
Ready to upgrade to HAProxy 3.1? Here’s how to get started.
Last but not least, we're thrilled to kick off HAProxyConf 2025 next summer in San Francisco.HAProxyConf celebrates the thriving community that's helped make HAProxy One the world's fastest application delivery and security platform. Over 2+ days, expert speakers will share best practices and real-world use cases that highlight HAProxy's next-gen approach to high-performance application delivery and security. Check out the HAProxyConf official website to learn more, stay updated, and answer our call for papers!
Subscribe to our blog. Get the latest release updates, tutorials, and deep-dives from HAProxy experts.
