Upgrade HAProxy Enterprise on Linux

To upgrade to a new, major version of HAProxy Enterprise from an older version, please use the Upgrade procedure. However, if you want to install the latest patches for your current version without upgrading to a new, major version, please use the Update procedure.

Upgrade Jump to heading #

You can upgrade HAProxy Enterprise on the following operating systems:

The upgrade procedure installs a new major version of HAProxy Enterprise.

1. Issues with the HAProxy Enterprise configuration can cause the load balancer to fail after an upgrade. Even if the service is performing as desired before the upgrade, the upgrade could introduce changes that cause a failure afterward.

   Validate the HAProxy Enterprise configuration file before proceeding with the upgrade.

   Use the hapee-lb command with the -c option to validate configuration files.

   Depending on your version, the command’s output indicates that the file is valid in these ways:

   • In version 2.8 and earlier, the command indicates a valid configuration by printing Configuration file is valid in addition to setting the zero return status.
   • In version 2.9 and later, the command sets the zero return status for a valid configuration but doesn’t display a message. To display the message, include the -V option on the command line.

   Multiple configuration files

   If you have multiple configuration files in your application, be sure to check them all in the correct order.

   Validate the configuration file as follows:

   Validate the configuration file

   Validate the configuration file3.3r13.2r13.0r12.8r12.6r1

   nix
   sudo /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V

   Alerts and warnings that appear in the console output explain the errors encountered. An alert is a fatal condition and prohibits the service from starting. A warning indicates a condition that isn’t fatal now but may become fatal in the target release. Address all the errors until you receive the successful output: Configuration file is valid.

2. If the HAProxy Enterprise server is part of a high-availability cluster, take it out of the cluster:

   • If using Active/Active clustering, update your network to stop sending traffic to the load balancer. For example, if using DNS roundrobin, remove the load balancer from DNS.
   • If using Active/Standby clustering, then on the active load balancer edit /etc/hapee-extras/hapee-vrrp.cfg. Lower the priority value to less than the standby load balancer’s priority. This will put the active load balancer into the standby state and simultaneously activate the standby load balancer. Then restart the hapee-extras-vrrp or hapee-extras-vrrp22 service.

3. Install HAProxy Enterprise by running the following command, specifying the desired version with --version, and replacing <HAProxy Enterprise Key> with your HAProxy Enterprise license key.

   Install the software

   Install the software3.3r13.2r13.0r12.8r12.6r1

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 3.3r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 3.3r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 3.2r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 3.2r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 3.0r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 3.0r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 2.8r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 2.8r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 2.6r1 \
     --key <HAProxy Enterprise key>

   nix
   wget https://www.haproxy.com/static/install_haproxy_enterprise.sh
   sudo bash ./install_haproxy_enterprise.sh \
     --version 2.6r1 \
     --key <HAProxy Enterprise key>

4. Copy the configuration files from your existing instance to your new instance. In addition to the configuration files, copy any associated files such as maps, certificates, and so on. The default configuration file is located here.

   Configuration file location

   Configuration file location3.3r13.2r13.0r12.8r12.6r1

   text
   /etc/hapee-3.3/hapee-lb.cfg

   text
   /etc/hapee-3.3/hapee-lb.cfg

   text
   /etc/hapee-3.2/hapee-lb.cfg

   text
   /etc/hapee-3.2/hapee-lb.cfg

   text
   /etc/hapee-3.0/hapee-lb.cfg

   text
   /etc/hapee-3.0/hapee-lb.cfg

   text
   /etc/hapee-2.8/hapee-lb.cfg

   text
   /etc/hapee-2.8/hapee-lb.cfg

   text
   /etc/hapee-2.6/hapee-lb.cfg

   text
   /etc/hapee-2.6/hapee-lb.cfg

5. Validate your HAProxy Enterprise configuration file against the new version of HAProxy Enterprise.

   Use the hapee-lb command with the -c option to validate configuration files.

   Depending on your version, the command’s output indicates that the file is valid in these ways:

   • In version 2.8 and earlier, the command indicates a valid configuration by printing Configuration file is valid in addition to setting the zero return status.
   • In version 2.9 and later, the command sets the zero return status for a valid configuration but doesn’t display a message. To display the message, include the -V option on the command line.

   Multiple configuration files

   If you have multiple configuration files in your application, be sure to check them all in the correct order.

   Validate the configuration file as follows:

   Validate the configuration file

   Validate the configuration file3.3r13.2r13.0r12.8r12.6r1

   nix
   sudo /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.3/sbin/hapee-lb -c -f /etc/hapee-3.3/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.2/sbin/hapee-lb -c -f /etc/hapee-3.2/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-3.0/sbin/hapee-lb -c -f /etc/hapee-3.0/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.8/sbin/hapee-lb -c -f /etc/hapee-2.8/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V

   nix
   sudo /opt/hapee-2.6/sbin/hapee-lb -c -f /etc/hapee-2.6/hapee-lb.cfg -V

   Alerts and warnings that appear in the console output explain the errors encountered. An alert is a fatal condition and prohibits the service from starting. A warning indicates a condition that isn’t fatal now but may become fatal in the target release. Address all the errors until you receive the successful output: Configuration file is valid.

6. Disable the old HAProxy Enterprise service from starting with the system, and enable the new version.

   Disable old service

   Disable old service3.3r13.2r13.0r12.8r12.6r1

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-3.3-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-3.3-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-3.2-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-3.2-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-3.0-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-3.0-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-2.8-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-2.8-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-2.6-lb

   nix
   sudo systemctl disable hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl enable hapee-2.6-lb

7. Stop the old HAProxy Enterprise service, and start the new service.

   Stop old service

   Stop old service3.3r13.2r13.0r12.8r12.6r1

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-3.3-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-3.3-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-3.2-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-3.2-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-3.0-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-3.0-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-2.8-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-2.8-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-2.6-lb

   nix
   sudo systemctl stop hapee-<PREVIOUS_VERSION>-lb
   sudo systemctl start hapee-2.6-lb

8. Run tail -f /var/log/syslog (or distribution equivalent) to check for warnings or errors.

9. Run curl localhost to ensure that HAProxy Enterprise is responding. Adjust address/port as needed, and use a local address that is currently active on the box and not a VRRP IP.

10. Put the upgraded server back into the cluster.

11. Repeat this procedure on secondary load balancers after restoring the current load balancer to active service.

Post-upgrade Jump to heading #

Perform these steps after upgrading HAProxy Enterprise.

Upgrade modules Jump to heading #

In addition to upgrading the HAProxy Enterprise package, the upgrade process upgrades many of the modules available with HAProxy Enterprise. Verify that the modules you use have been upgraded.

1. To see which modules you use, review your HAProxy Enterprise configuration file and look for modules named in the module-load directive, for example:

   hapee-lb.cfg
   haproxy
   global
     module-load hapee-lb-waf.so

   hapee-lb.cfg
   haproxy
   global
     module-load hapee-lb-waf.so

2. List modules installed on your node by running the following command:

   apt yum zypper

   nix
   sudo apt list --installed | grep hapee

   nix
   sudo apt list --installed | grep hapee

   nix
   sudo yum list --installed hapee-*

   nix
   sudo yum list --installed hapee-*

   nix
   sudo zypper search --installed-only hapee

   nix
   sudo zypper search --installed-only hapee

3. Verify that the installed modules are up to date with the new version of HAProxy Enterprise. Upgrade any modules that are out of date. For more information, see Enterprise modules.

Optional: Uninstall old version Jump to heading #

When you have confirmed that the new HAProxy Enterprise version is performing as needed, you can uninstall the old HAProxy Enterprise version if you want. To uninstall the old version:

nix
sudo apt purge hapee-3.3r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-3.3r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-3.3r1-lb`
sudo yum remove hapee-3.3r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-3.3r1-lb`
sudo yum remove hapee-3.3r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-3.3r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-3.3r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-3.2r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-3.2r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-3.2r1-lb`
sudo yum remove hapee-3.2r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-3.2r1-lb`
sudo yum remove hapee-3.2r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-3.2r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-3.2r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-3.0r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-3.0r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-3.0r1-lb`
sudo yum remove hapee-3.0r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-3.0r1-lb`
sudo yum remove hapee-3.0r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-3.0r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-3.0r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-2.8r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-2.8r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-2.8r1-lb`
sudo yum remove hapee-2.8r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-2.8r1-lb`
sudo yum remove hapee-2.8r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-2.8r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-2.8r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-2.6r1-\*
sudo systemctl restart rsyslog

nix
sudo apt purge hapee-2.6r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-2.6r1-lb`
sudo yum remove hapee-2.6r1-\*
sudo systemctl restart rsyslog

nix
sudo rm -i `rpm -q --configfiles hapee-2.6r1-lb`
sudo yum remove hapee-2.6r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-2.6r1-\*
sudo systemctl restart rsyslog

nix
sudo zypper remove hapee-2.6r1-\*
sudo systemctl restart rsyslog