Preserve Stick Table Data When Reloading HAProxy

With HAProxy situated in front of their servers, many people leverage it as a frontline component for enabling extra security and observability for their networks. HAProxy provides a way to monitor the number of TCP connections, the rate of HTTP requests, the number of application errors, and the like, which you can use to detect anomalous behavior, enforce rate limits, and catch application-related problems early.

Behind the scenes, an in-memory storage called stick tables keeps track of this data. Stick tables associate a key, which is typically the client’s IP address, with counters. These counters represent any of the abovementioned signals, around which you can build custom policies in order to take action when a counter exceeds a threshold. For example, you might send a Too Many Requests error when a user’s request rate goes too high.

There’s just one potential problem. If you make changes to your HAProxy configuration file, you then need to reload HAProxy so that the changes take effect. However, a reload clears away all of your stick table data! The good news is that there is a simple way to preserve this data during a reload, which we’ll cover in this blog post.

Preserve Stick Table Data With Peers

Preserving stick table data comes down to defining peers in your configuration.

What are peers? When you operate two or more HAProxy instances for redundancy, you often need to synchronize stick table data between them. For example, in an active-standby setup, where one load balancer actively receives traffic while the other is on standby, you would want to synchronize them so that if the standby instance needs to take over, it has a copy of the data. Each load balancer instance that shares stick table data is called a peer.

You configure peers by adding a peers section to your HAProxy configuration.


HAProxy Enterprise supports active-active scenarios too, where both load balancers receive traffic simultaneously and aggregate their data. Conversely, a peers section alone overwrites data from one peer to the other and is suitable for active-standby scenarios only.

As it happens, using a peers section doubles as a way to preserve stick table data during a reload, and it works even if you operate only one load balancer.

First, add a peers section to your configuration. For illustration purposes, let’s assume you have only one load balancer. You would list it like this:

peers mypeers
peer garfield

Inside the peers section, each peer line indicates a server participating in data synchronization. In this case, there’s only one, the current server. The first argument is the server’s hostname, which is garfield here. Then, the server’s IP address, which can be either a local host address like or the address at which other peers can access the server, such as The load balancer listens at the designated port for incoming data, which is 10000 here.

It’s important that the first argument matches the server’s hostname. If that would be difficult to do, you can instead set the localpeer directive in the global section of your configuration to use a different name, as shown below.

localpeer odie
peers mypeers
peer odie

Next, add a peers argument to your stick table declaration.

frontend mysite
# the stick table declaration
stick-table type ip size 1m expire 1h store http_req_rate(10s) peers mypeers

Your stick table will now be preserved during a reload. By reload, I mean this command:

# Data is kept
$ sudo systemctl reload haproxy

Note that this will not work if you do a hard restart of HAProxy, such as:

# Does not work
$ sudo systemctl restart haproxy

To see data currently stored in a stick table, use the Runtime API’s show table command.

$ echo "show table mysite" | sudo socat stdio /var/run/haproxy/api.sock


In this blog post, you learned how defining a peers section in your configuration enables HAProxy to retain stick table data during a reload. This ensures that the policies you define for rate limiting and the like will continue to operate normally.

Interested to know when we publish content like this? Subscribe to our blog! You can also follow us on Twitter and join the conversation on Slack.

To learn more about stick tables, sign up for the on-demand webinar, Introduction to HAProxy Stick Tables.

Subscribe to our blog. Get the latest release updates, tutorials, and deep-dives from HAProxy experts.