Should You Reload or Restart HAProxy?

Managing your load balancer instances is important while using HAProxy. You might encounter errors, need to apply configurations, or periodically upgrade HAProxy to a newer version (to name a few examples). As a result, reloading or restarting HAProxy is often the secret ingredient to restoring intended functionality.

Whether you’re relatively inexperienced with HAProxy or you’re a grizzled veteran, understanding which method is best in a given situation is crucial. Our recommended best practices within the HAProxy Configuration Manual are quite helpful, but there’s some added nuance to the reload versus restart discussion. 

In this guide, we’ll cover when to reload or restart HAProxy. We’ll also assess each option from a technical standpoint, note any potential consequences, and share some handy tips.

How to Choose Between Reloading or Restarting HAProxy

At first glance, it seems like HAProxy users should reload and restart almost equally often. However, this isn’t the case. You’ll encounter situations that require reloads far more commonly than those requiring restarts. In the vast majority of cases, we recommend reloading since it’s far less disruptive to active connections. To better understand why, let’s explore what each process entails.

What Does Reloading HAProxy Do?

Reloading starts a new HAProxy instance (or “process”) which handles new requests, while the old instance maintains connections until they naturally close or the hard-stop-after directive takes effect. This avoids severing any active connections and prevents any notable service disruption. 

Interruptions are usually negligible in these cases since reloads can happen in milliseconds. However, it’s important to note that configuration file sizes can impact these reload times, as can DNS resolutions on the backend. HAProxy rereads the configuration file on each reload and a larger file takes longer to parse. We see both happen often with enterprise customers and users with very complex infrastructure setups. Thankfully, there are two main ways to reduce loading times:

1. Adding init-addr <address> on your configuration’s server lines, which lets HAProxy circumvent hostname resolution on reload

2. Altering your systemd unit file to skip the automated configuration check that happens when HAProxy reloads

The systemd method requires two quick steps.

First, HAProxy users who’ve compiled HAProxy from source need to install a compatible service file before running certain HAProxy commands. Open your terminal and enter the following sets of commands to install the service file (unless your package already includes it):

Second, run the systemctl edit --full hapee-2.6-lb.service terminal command. Third, remove the ExecReload=/opt/hapee-2.6/sbin/hapee-lb -Ws -f $CONFIG -c line from your file. HAProxy will now bypass the check.

Hitless Reloads & Hard Stops With HAProxy

HAProxy Enterprise 1.8r1 first enabled hitless reloads in HAProxy. This feature keeps existing connections alive by transferring listening sockets from your old HAProxy instance to your new instance. Hitless reloads happen seamlessly to prevent dropped connections during high utilization periods—where thousands of new connections per second accompany numerous HAProxy process reloads. 

How do we support this? First, the expose-fd listeners function (now the default behavior in HAProxy 2.6 or later) enables retrieval of listening sockets from the old process for utilization, instead of binding new ones. Second, the master-worker mode launches a master process that oversees all worker processes and enforces direct reloads by accepting the SIGUSR2 signal. As a result, any reloads will automatically parse your HAProxy configuration file for changes, apply them, and fork new workers.

HAProxy reloads don’t happen suddenly—they’re instead considered graceful "soft stops." Reloads occur gradually to give old connections time to resolve and leave as needed. That said, reloads also aren’t perfect. We need to be mindful of two scenarios where rare connection drops (1 in 10,000) are possible within a couple of three-millisecond windows:

1. If an old process prevents a new process from binding, HAProxy will have to resolve this using the SIGTTOU+SIGTTIN sequence or SO_REUSEPORT socket option.

2. When old processes close their listening ports, the kernel might occasionally fail to redistribute any pending connections.

Finally, subsequent reloads can cause worker processes to accumulate when you have long-running connections. The hard-stop-after condition lets your HAProxy instance remain alive for a specified maximum amount of time after a reload is initiated. It’s useful for cleaning up pesky, running worker processes—which we recommend killing manually after a few days.

When Should You Reload HAProxy?

We’ve mentioned some key reload scenarios in our earlier diagram, but let’s recap. You’ll want to reload HAProxy under the following conditions: 

• You want to apply HAProxy configuration changes without terminating connections and causing downtime in production

• You want to resolve errors stemming from an active HAProxy instance or config

• You want to reclaim memory for newer processes

• You want to perform a graceful HAProxy shutdown with an extra grace period to manage connection closure over a gradual period (using close-spread-time)

• You need graceful reloads with zero packet loss (traffic control queuing example)

• You want to upgrade HAProxy

Now that we know when to reload HAProxy let's quickly cover the reload procedure next.

How to Reload HAProxy

You can reload HAProxy in a snap. HAProxy users (with the earlier service file installed) should use the systemctl reload haproxy command. Meanwhile, HAProxy Enterprise users should use systemctl reload hapee-2.X-lb.

What Does Restarting HAProxy Do?

Restarting spins up a new HAProxy instance that handles new requests, while the old instance closes immediately even though existing connections remain attached. This drops HTTP requests and TCP connections instead of seamlessly transferring them. Consequently, restarts are more disruptive than reloads and can cause downtime or packet loss.

Read More:

• Load Balance an Infinite Number of Servers & Never Reload HAProxy

• Testing Your HAProxy Configuration

• Essential Sections of an HAProxy Configuration

• Preserve Stick Table Data When Reloading HAProxy

When Should You Restart HAProxy?

Restarts have their downsides and are decidedly less “elegant” than reloads. However, they’re essential from time to time. Expanding on our diagram, you should restart HAProxy for the following reasons: 

• You want to immediately kill a HAProxy instance that’s consuming too many resources, sometimes caused by worker processes that fail to exit. You’ll want to kill troublesome processes manually in production to reduce negative ramifications. 

• You want to apply changes located within /etc/default/haproxy. HAProxy reads this init config file on starts and restarts. 

• Impactful bugs are preventing HAProxy from working properly

• HAProxy isn’t applying configuration changes as it should

The last bullet comes with some caveats. Before restarting HAProxy, check for error messages in the log by using either either the journalctl -xeu haproxy (for HAProxy) or journalctl -xeu hapee-x.y-lb (for HAProxy Enterprise) commands. The systemd component may fail to report failures caused by incorrect configurations, so we want to check things out before taking larger troubleshooting steps. 

You can validate your HAProxy configuration with the following command:

Alternatively, run the following command for HAProxy Enterprise:

If your HAProxy configuration is faulty, you can fix your file and trigger a reload to safely apply those changes.

How to Restart HAProxy

Restarting HAProxy is easy with the sudo systemctl restart haproxy.service command. And though it applies to both reloads and restarts, the hard-stop-after directive emulates a restart since it takes effect instantaneously.

Reload Whenever Possible & Use Restarts Cautiously

If there’s one thing to take away from this guide, it’s this: reloads are almost always preferable to restarts. You should only restart HAProxy for very specific reasons. In most common scenarios, you can achieve your goal by reloading HAProxy and maintaining active connections. 

Both processes are powerful, and following best practices will help maximize uptime—which your end users will definitely appreciate!

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