Firmware updates

Learn how to check which version of the firmware you currently have and how to download and install a newer version.

Before you update Jump to heading #

Before performing an update, follow the steps in this section.

Check for breaking changes Jump to heading #

When a new version introduces breaking changes to the configuration syntax, it can cause the haproxy service 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. However, breaking changes are never introduced suddenly. For several versions prior to a breaking change, the upcoming syntax change will prompt a warning, giving you time to address it.

The haproxy service validates its configuration file when it starts or reloads. Follow these steps:

1. Go to the Services tab.

2. Reload the haproxy service to trigger validation.

3. Go to the Logs tab.

4. In the console logs section, look for config : parsing alerts and warnings. The following example output shows an alert for the obsolete tune.chksize parameter and a warning for the option httplog directive.

   console logs
   text
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [NOTICE]   (2664) : haproxy version is 2.5.0-aloha-bb8aa2ca-flx2.14_albva 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [NOTICE]   (2664) : path to executable is /usr/sbin/haproxy 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [ALERT]    (2664) : config : parsing [/tmp/haproxy.conf:2]: option 'tune.chksize' is not supported any more (tune.bufsize is used instead). 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [WARNING]  (2664) : config : parsing [/tmp/haproxy.conf:31] : backend 'webfarm' : 'option httplog' directive is ignored in backends. 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [ALERT]    (2664) : config : Error(s) found in configuration file : /tmp/haproxy.conf 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [ALERT]    (2664) : config : Fatal errors found in configuration. 

   console logs
   text
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [NOTICE]   (2664) : haproxy version is 2.5.0-aloha-bb8aa2ca-flx2.14_albva 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [NOTICE]   (2664) : path to executable is /usr/sbin/haproxy 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [ALERT]    (2664) : config : parsing [/tmp/haproxy.conf:2]: option 'tune.chksize' is not supported any more (tune.bufsize is used instead). 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [WARNING]  (2664) : config : parsing [/tmp/haproxy.conf:31] : backend 'webfarm' : 'option httplog' directive is ignored in backends. 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [ALERT]    (2664) : config : Error(s) found in configuration file : /tmp/haproxy.conf 
   Apr  7 22:34:37 ALOHA1 user.warn  admin[2136]: [ALERT]    (2664) : config : Fatal errors found in configuration. 

   • 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 a future release. Fix both types of conditions before proceeding.

   • HAProxy ALOHA also indicates an invalid haproxy configuration file in the LB Layer7 tab by displaying This configuration is not valid in the notification bar at the bottom of the display.

5. If you run two HAProxy ALOHA instances in active-standby mode, ensure that your current load balancer configuration has been pushed to the standby instance. Go to the Services tab and click the push button next to each service where it is shown.

Check your firmware version Jump to heading #

To obtain the current version of the firmware that you have installed:

1. In the web user interface, go to the Setup tab and find the firmware version number in the System information, where it is labeled Version.

Alternatively:

1. Log in to the HAProxy ALOHA command-line interface.

2. Read the file /usr/share/factory/version to see the version.

   nix
   cat /usr/share/factory/version

   nix
   cat /usr/share/factory/version

   output
   text
   Product: aloha
   Model: albva
   Branch: 17.5
   Version: 17.5.2
   Build: 1707
   Date: 2025-10-29 04:59:47
   URL: http://www.haproxy.com/download/aloha/17.5

   output
   text
   Product: aloha
   Model: albva
   Branch: 17.5
   Version: 17.5.2
   Build: 1707
   Date: 2025-10-29 04:59:47
   URL: http://www.haproxy.com/download/aloha/17.5

   The firmware version number is composed of three digits separated by dots, <major version>.<minor version>.<patch version>. Major and minor versions include new features and bug fixes, while patch versions include only bug fixes.

Check your disk size Jump to heading #

When upgrading the virtual appliance to version 17.5 and newer, ensure that your virtual machine has a disk size of at least 8 GB. Check your hypervisor documentation for how to change your VM’s disk size. Customers who have continuously upgraded their firmware may have never increased their disk size before.

Install the new firmware Jump to heading #

Follow these steps to install the new firmware.

Required upgrade flows Jump to heading #

Some firmware versions require you to upgrade to one or more intermediate versions first, typically because the newest firmware is too large for older HAProxy ALOHA systems to download. The intermediate versions expand the buffer size, allowing your system to download and install the newer firmware. For end-of-life versions for which we no longer provide firmware, you’ll need to do a fresh install of a supported version, since there isn’t an upgrade path for your system.

Follow this migration path to the latest 17.5 version:

Download the firmware Jump to heading #

Follow these steps to download the latest version of the firmware.

1. Obtain your credentials for accessing HAProxy ALOHA downloads. You can create a new support ticket in the HAProxy Technologies Customer Portal to request your credentials.

   For virtual appliances, when updating to a new major version (for example 13.0, 14.0, 15.0), you will be given a new license key to install prior to the update. This will prevent the appliance from starting in evaluation mode. The new license will appear as invalid until you update the firmware. Licenses for hardware appliances are valid for all firmware versions.

2. Browse to the website https://www.haproxy.com/download/aloha/. To access one of the version folders, you’ll need to enter your credentials.

3. Inside the target version folder, find the .bin file with the highest number and download it. The virtual appliance and hardware appliance use different files.

   Appliance type	File to download
   virtual appliance	file with albva prefix
   hardware appliance	file with alb<MODEL> prefix

You can update the HAProxy ALOHA firmware via user interface or the command line.

Install the firmware in the UI Jump to heading #

If you run two HAProxy ALOHA instances in active-standby mode, then updating one at a time is preferable to avoid downtime. Start with the standby instance, then once completed switch it into active mode so that you can update the current active instance.

To update the standby instance:

1. Export and save the existing configuration by going to the Setup tab, and in the Configuration section, click Export.

2. Begin the update by going to the Setup tab, and in the Firmware section, click Choose File to select the .bin file.

3. Click Update next to the .bin file name. The new version is added to the Next boot image list and selected. You could also roll back to a previous version.

4. Click Update next to the Next boot image list.

5. Click Reboot.

6. Promote the standby instance to be the active instance:

   • From the Services tab, click the Setup icon on the network service line.

   • Update the vrrp prio number to be greater than the current primary instance’s value. This will configure the VRRP group so that the system with the higher priority number will become the new primary instance, avoiding network disruptions during the firmware update process.

   • Click OK then Close.

     The standby becomes the new active instance and handles the traffic. We recommend monitoring HAProxy ALOHA until you are confident that it is functioning correctly.

     You can still swap the active and standby back by lowering the instance’s vrrp prio number to its original value. You can also revert by following the steps in the Roll back section below.

To update the other HAProxy ALOHA instance:

1. Go to the Setup tab, and in the Firmware section, click Choose File to upload the .bin file.

2. Click Update.

3. Click Reboot.

4. If you are running two HAProxy ALOHA instances, you can change the original standby instance to be on standby again:

   • On the standby instance, go to the Services tab, click the Setup icon on the network service line.

   • Lower the vrrp prio number to the value before the update.

   • Click OK then Close.

     At this stage, HAProxy ALOHA has been updated to the new firmware. During this update, the load balancer configuration may have been migrated to use newer keywords if older keywords were obsoleted.

     However, these configuration changes won’t persist after a reboot. To make them persist, go to the Setup tab and click Save in the Configuration section. Do this when you are confident that you won’t need to roll back the firmware.

Upload and install the firmware in the CLI with scp or Winscp Jump to heading #

If you run two HAProxy ALOHA instances in active-standby mode, then updating one at a time is preferable to avoid downtime. Start with the standby instance, then once completed switch it into active mode so that you can update the current active instance. The text editor available in ALOHA via the CLI is vi.

On the host machine:

1. Download the updated firmware binary file as outlined in Download the firmware.

2. Copy the updated firmware binary file to /tmp on the standby ALOHA instance using scp or Winscp:

   nix
   scp example-firmware-file.bin admin@FIRST_ALOHA_IP:/tmp

   nix
   scp example-firmware-file.bin admin@FIRST_ALOHA_IP:/tmp

3. Copy the updated firmware binary file to /tmp on the other ALOHA instance using scp or Winscp:

   nix
   scp example-firmware-file.bin admin@OTHER_ALOHA_IP:/tmp

   nix
   scp example-firmware-file.bin admin@OTHER_ALOHA_IP:/tmp

Log in to the standby ALOHA instance:

1. Become the root user.

   nix
   sudo su

   nix
   sudo su

2. In the /etc/config.rc file, update the vrrp prio number to be greater than the current primary instance’s value. For example:

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 100

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 100

3. Apply the change with:

   nix
   service network restart

   nix
   service network restart

4. Install the firmware using update-boot-image; replace example-firmware-file.bin with the name of the file:

   nix
   update-boot-image /tmp/example-firmware-file.bin

   nix
   update-boot-image /tmp/example-firmware-file.bin

5. Ensure the changes are saved:

   nix
   config save

   nix
   config save

The standby becomes the new active instance and handles the traffic. You can still swap the active and standby back by lowering the instance’s vrrp prio number to its original value. We recommend monitoring HAProxy ALOHA until you are confident that it is functioning correctly before moving on to the next steps.

Log in to the other ALOHA instance:

1. Become the root user.

   nix
   sudo su

   nix
   sudo su

2. Install the firmware using update-boot-image; replace example-firmware-file.bin with the name of the file:

   nix
   update-boot-image /tmp/example-firmware-file.bin

   nix
   update-boot-image /tmp/example-firmware-file.bin

3. Ensure the changes are saved:

   nix
   config save

   nix
   config save

Once done, you can change the original standby instance to be on standby again by editing the /etc/config.rc file and lowering the vrrp prio number to the value before the update. To do so, log back in to the first ALOHA instance:

1. Become the root user.

   nix
   sudo su

   nix
   sudo su

2. In the /etc/config.rc file, update the vrrp prio number back to its original value. For example:

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 1

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 1

3. Apply changes:

   nix
   service network restart

   nix
   service network restart

4. Ensure the changes are saved:

   nix
   config save

   nix
   config save

Install the firmware in the CLI from a host machine with cat and ssh Jump to heading #

If you run two HAProxy ALOHA instances in active-standby mode, then updating one at a time is preferable to avoid downtime. Start with the standby instance, then once completed switch it into active mode so that you can update the current active instance. The text editor available in ALOHA via the CLI is vi.

Log in to the standby ALOHA instance:

1. In the /etc/config.rc file, update the vrrp prio number to be greater than the current active instance’s value. For example:

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 100

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 100

2. Apply the change with:

   nix
   service network restart

   nix
   service network restart

3. Ensure the changes are saved:

   nix
   config save

   nix
   config save

On the host machine:

1. Download the updated firmware binary file as outlined in Download the firmware.

2. Concatenate and redirect the contents of the updated firmware binary file to the standby instance to run the update-boot-image process.

   nix
   cat example-firmware-file.bin | ssh admin@FIRST_ALOHA_IP 'sudo update-boot-image -'

   nix
   cat example-firmware-file.bin | ssh admin@FIRST_ALOHA_IP 'sudo update-boot-image -'

3. Ensure the changes are saved.

   nix
   ssh admin@ALOHA_IP 'config save'

   nix
   ssh admin@ALOHA_IP 'config save'

4. The standby becomes the new active instance and handles the traffic. We recommend monitoring HAProxy ALOHA until you are confident that it is functioning correctly before moving on to the next step. You can still swap the active and standby back by lowering the instance’s vrrp prio number to its original value.

5. Concatenate and redirect the contents of the updated firmware binary file to the other ALOHA instance to run the update-boot-image process.

   nix
   cat example-firmware-file.bin | ssh admin@OTHER_ALOHA_IP 'sudo update-boot-image -'

   nix
   cat example-firmware-file.bin | ssh admin@OTHER_ALOHA_IP 'sudo update-boot-image -'

6. Ensure the changes are saved.

   nix
   ssh admin@OTHER_ALOHA_IP 'config save'

   nix
   ssh admin@OTHER_ALOHA_IP 'config save'

Once the new firmware has been installed on all ALOHA instances, you can change the original standby instance to be on standby again by editing the /etc/config.rc file and lowering the vrrp prio number to the value before the update. To do so, log back in to the first ALOHA instance:

1. Become the root user.

   nix
   sudo su

   nix
   sudo su

2. In the /etc/config.rc file, update the vrrp prio number back to its original value. For example:

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 1

   config.rc
   text
   service network eth0
     ######### Interface eth0
     ip autoconfig
     ip address 192.168.0.200/255.255.255.0
     ip route default 192.168.0.1
     vrrp inst default prio 1

3. Ensure the changes are saved:

   nix
   config save

   nix
   config save

4. Apply changes:

   nix
   service network restart

   nix
   service network restart

Validate the haproxy configuration file Jump to heading #

As before, validate the LB Layer7 haproxy service configuration file. Conditions noted as warnings in the configuration file could become alerts (fatal errors) in a future release.

1. Go to the Services tab.

2. Reload the haproxy service to trigger validation.

3. Go to the Logs tab.

4. In the console logs section, look for config : parsing alerts and warnings. Fix both types of conditions before proceeding.

5. Ensure changes are saved.

   nix
   sudo config save

   nix
   sudo config save

Update additional modules Jump to heading #

If you previously installed any additional modules, then you should update them too to be compatible with version 17.5 of the firmware. Module updates may also contain new features and bug fixes.

Follow these links to find instructions for updating each of the modules:

• Data Plane API (Management package)
• Web Application Firewall (Security package)

Roll back an update Jump to heading #

A rollback won’t revert the load balancer configuration if you have saved it on the Setup tab. In rare cases, it may be incompatible with the older firmware.

By default, HAProxy ALOHA stores two firmware images:

• The current running firmware.
• The firmware that was running before the last update.

Follow these steps to revert to the firmware that was running before the last update:

1. On the Setup tab, scroll down to the Firmware section.

2. Look for the Next boot image list. The box checked indicates the currently running firmware.

   

3. Check the other box pointing to the previous image you want to rollback to.

4. Click Update next to the Next boot image list.

5. Click Reboot in the Firmware section.