There are three ways to update the running configuration in HAProxy: by restarting, reloading, or hitless reloading.

  • Restart: The existing HAProxy process is stopped and a new one is started.

  • Reload: A new process is started and the old process is instructed to close its sockets once it is ready. This results in about 100ns where the old process can refuse connections.

  • Hitless reload: The new process reads the sockets from the old process via the socket, so that there are no refused connections.

With reloads or hitless reloads, the old process will keep running until its existing connections are concluded. For keep-alive connections, the next response from it will have a connection; you can close the header to speed that process along. With a restart, existing connections will be interrupted.

The init script currently supports restart and reload, but hitless reloads require the following configuration.

Hitless reloads are available in HAPEE 1.7r1 and later.

Configuring a hitless reload

Before you start, you need to know the locations for the following:

  • HAProxy socket (if using nbproc > 1, you only need a socket for one of the processes)

  • The HAProxy binary (usually /opt/hapee-1.7/sbin/hapee-lb)

If unsure where to find this information:

  • Run ps auxw | grep hapee-lb to display everything (except socket locations).

  • Look for 'stats socket' in the 'global' for socket locations.

Prepare the configuration

  1. In the configuration file's 'global' section at the top, locate the 'stats socket' line similar to the following: (if you do not see it, you must create it)

    stats socket /var/run/1.7/hapee-lb.sock user hapee-lb group hapee mode 660 level admin
  2. Add expose-fd listeners to this line, as follows:

    stats socket /var/run/1.7/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
  3. Edit /etc/default/hapee-1.7-lb to add the following variable:

    HAPROXY_STATS_SOCKET=/var/run/hapee-1.7/hapee-lb.sock
  4. Run a normal reload on HAPEE for a last time, with:

    service hapee-1.7-lb reload

Performing a hitless reload

For versions running systemd

Run service hapee-1.7-lb reload, and the systemd wrapper automatically appends -x with the socket path to the new worker processes it spawns, if the currently running process has expose-fd listeners in it.

When you add expose-fd listeners for the first time, it will perform a normal reload, as the existing process will not send its FD sockets to the new process.

For versions not running systemd

After you (or your scripts) modify the HAProxy configuration, certificates, LUA scripts, or even the HAPEE binary itself, you can perform a hitless reload with the following command:

/opt/hapee-1.7/sbin/hapee-lb -f /etc/hapee-1.7/hapee-lb.cfg -p /run/hapee-1.7-lb.pid -f /etc/hapee-1.7/hapee-lb.dashboard-module.cfg -x /var/run/hapee-1.7/hapee-lb.sock -sf $(cat /run/hapee-1.7-lb.pid | xargs)
  • Any warnings or errors will be printed to stdout/stderr. If everything runs smoothly, this process then forks into the backgroud and the old process stops once its finishes with its existing connections.

  • This command is the same as for a normal reload, but with the addition of:

    -x /var/run/hapee-1.7/hapee-lb.sock
  • Check the return code (for example with echo $?). If it is 1, then this indicates that the new HAProxy process did not complete initialization. Check the output should be checked for the reason. In this case, the existing hapee-lb process continues to run.