HAProxy ALOHA

Manage active/standby clustering (VRRP)

This page applies to:

  • HAProxy ALOHA 17.0 and newer
  • Does not apply to HAProxy Enterprise

Running HAProxy Enterprise?

HAProxy Enterprise uses its own Keepalived configuration rather than the network connection, and the API manages it through /services/keepalived. See Manage active/standby clustering (VRRP).

You can use HAProxy Data Plane API to configure active/standby clustering using the VRRP protocol. You’ll call the API endpoint /services/network/connections.

Getting and setting the version parameter Jump to heading

When making a POST, PUT, or DELETE API call, you must add the version URL parameter. For example:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1

The version parameter must match the load balancer’s current configuration version. This is because the Data Plane API uses optimistic concurrency control, or optimistic locking, to manage its transactions. This ensures that if multiple entities modify a resource that the changes are applied correctly. The APIv3 examples in this section make a GET request to /v3/services/haproxy/configuration/version immediately before making a call to update a resource to retrieve the version and populate the CFGVER environment variable for the URL version parameter as is shown in the following command:

nix
CFGVER=$(curl --silent --user admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
nix
CFGVER=$(curl --silent --user admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)

You will then use the value of the environment variable to populate the version parameter in the endpoint URL. An example URL may look like this. Note the environment variable reference, $CFGVER:

nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER
nix
http://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER

Response codes and reloads Jump to heading

Inside a transaction, a change is written to the transaction instead of the configuration file, so nothing reaches the file until you commit, and the commit answers 202 Accepted.

When a change needs a reload, the API applies it in the background. By default it writes your change, schedules the reload, and answers 202 Accepted with a Reload-ID header:

output
text
HTTP 202 Accepted
Reload-ID: 2026-10-29-0
output
text
HTTP 202 Accepted
Reload-ID: 2026-10-29-0

To wait for the reload before returning, add force_reload=true to the request. The status code then reports the outcome directly, and no reload ID comes back:

Request Default With force_reload=true
POST, to create 202 Accepted 201 Created
PUT, to replace 202 Accepted 200 OK
DELETE 202 Accepted 204 No Content

The code reflects what the request did: a create answers 201 Created because it made a resource, a replace answers 200 OK because it changed an existing one, and a delete answers 204 No Content because there is nothing left to return.

Some changes, such as adding a server to a backend, are applied through the HAProxy Runtime API instead of a reload. Those answer 201 Created without waiting for a reload.

To follow a scheduled reload, you can pass the ID from the Reload-ID header to the reloads endpoint of the service:

nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
output
json
{
"id": "2026-10-29-0",
"reload_timestamp": 1793301215,
"status": "succeeded"
}
output
json
{
"id": "2026-10-29-0",
"reload_timestamp": 1793301215,
"status": "succeeded"
}

The reloads endpoints are /services/haproxy/reloads, /services/keepalived/reloads, and /services/gslb/reloads, each with an /{id} variant. Inside a transaction, a change is written to the transaction instead of the configuration file, which means nothing reaches the file until you commit, and the commit returns 202 Accepted.

Configure the active server Jump to heading

The interface you add VRRP to must already have a static IPv4 address. Without a static IP address, adding VRRP to an interface will fail. This tutorial uses 192.168.56.45 on the active server and 192.168.56.46 on the standby server.

Follow these steps to configure the active load balancer.

  1. Decide on a Virtual Router Identifier (VRID) for the cluster. The VRID can be any number between 1 and 255. It is a unique identifier that is the same on the active and standby servers. It allows the servers to share a virtual router and virtual IP address.

    Do not use a VRID already in use. To list VRIDs already in use, on the load balancer run the following command, specifying the network interface you’ll use, here eth0:

    nix
    sudo tcpdump -vvvenns0 -c 5 -i eth0 vrrp | grep -o "vrid [0-9]*"
    nix
    sudo tcpdump -vvvenns0 -c 5 -i eth0 vrrp | grep -o "vrid [0-9]*"
    output
    text
    [...]
    5 packets captured
    6 packets received by filter
    0 packets dropped by kernel
    vrid 161
    vrid 155
    output
    text
    [...]
    5 packets captured
    6 packets received by filter
    0 packets dropped by kernel
    vrid 161
    vrid 155

    If the output from the command does not contain any lines with a vrid, you do not have any VRIDs already in use, and they are all available.

  2. Make a GET request to the connections endpoint to see the network interface’s properties. This returns the interface’s connection profile. From this, get its UUID.

    nix
    curl --request GET \
    --user admin:admin \
    "http://localhost:5555/v3/services/network/connections"
    nix
    curl --request GET \
    --user admin:admin \
    "http://localhost:5555/v3/services/network/connections"
    output
    text
    [
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "46c50848-a49c-4b27-975a-9b53ef16fa6c"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.45",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    }
    }
    ]
    output
    text
    [
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "46c50848-a49c-4b27-975a-9b53ef16fa6c"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.45",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    }
    }
    ]
  3. Modify your existing network interface, such as eth0, by making a PUT request to the connections endpoint. Below, we enable VRRP on the eth0 interface by sending the JSON we received from the GET request, but with the addition of the vrrp section:

    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl --request PUT \
    --user admin:admin \
    --header "Content-Type: application/json" \
    -d '{
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "46c50848-a49c-4b27-975a-9b53ef16fa6c"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.45",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "192.168.56.100"
    ],
    "priority": 101,
    "version": "v2",
    "no-address": true,
    "password": "aloha"
    }
    ]
    }' \
    "http://localhost:5555/v3/services/network/connections/46c50848-a49c-4b27-975a-9b53ef16fa6c?version=$CFGVER&activate=1"
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl --request PUT \
    --user admin:admin \
    --header "Content-Type: application/json" \
    -d '{
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "46c50848-a49c-4b27-975a-9b53ef16fa6c"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.45",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "192.168.56.100"
    ],
    "priority": 101,
    "version": "v2",
    "no-address": true,
    "password": "aloha"
    }
    ]
    }' \
    "http://localhost:5555/v3/services/network/connections/46c50848-a49c-4b27-975a-9b53ef16fa6c?version=$CFGVER&activate=1"

    In this example:

    • Include the connection profile’s UUID in the requested URL path. Here, it’s 46c50848-a49c-4b27-975a-9b53ef16fa6c.

    • Set the URL parameter activate=1.

    • Add a vrrp section to define VRRP options. Here we’re setting:

      • id: The VRID determined previously.
      • instance: The VRRP instance name.
      • ipv4-addresses: One or more virtual IP addresses. The new address(es) should fall within the interface’s IP subnet but shouldn’t already be assigned to any server.
      • priority: The VRRP instance default priority. Set it to 101 for the active server.
      • version: Set version to v2.
      • no-address: Set this to true to enable more than 20 virtual IP addresses. It implements the virtual_ipaddress_excluded directive in the underlying VRRP configuration.
      • password: The VRRP instance authentication password. All cluster members must set the same password.
    output
    text
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "46c50848-a49c-4b27-975a-9b53ef16fa6c"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.45",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "172.16.24.235"
    ],
    "no-address": true,
    "password": "aloha",
    "priority": 101,
    "version": "v2"
    }
    ]
    }
    output
    text
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "46c50848-a49c-4b27-975a-9b53ef16fa6c"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.45",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "172.16.24.235"
    ],
    "no-address": true,
    "password": "aloha",
    "priority": 101,
    "version": "v2"
    }
    ]
    }
  4. Enable the VRRP service on the load balancer.

    Enabling the service after the API calls avoids an error about a missing group directive, because the connection profile now defines the VRID.

  5. To make your changes persistent after a reboot, either:

    • From the HAProxy ALOHA UI, click the Setup tab. Then click Save under Configuration.
    • Connect to the HAProxy ALOHA server and execute config save.

Configure the standby server Jump to heading

Follow these steps to configure the standby load balancer.

  1. Make a GET request to the connections endpoint to see the network interface’s properties. This returns the interface’s connection profile. From this, get its UUID.

    nix
    curl --request GET \
    --user admin:admin \
    "http://localhost:5555/v3/services/network/connections"
    nix
    curl --request GET \
    --user admin:admin \
    "http://localhost:5555/v3/services/network/connections"
    output
    text
    [
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "66a5f56f-449f-413d-9160-7bb6462f3618"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.46",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    }
    }
    ]
    output
    text
    [
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "66a5f56f-449f-413d-9160-7bb6462f3618"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.46",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    }
    }
    ]
  2. Modify your existing network interface, such as eth0, by making a PUT request to the connections endpoint. Below, we enable VRRP on the eth0 interface by sending the JSON we received from the GET request, but with the addition of the vrrp section:

    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl --request PUT \
    --user admin:admin \
    --header "Content-Type: application/json" \
    -d '{
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "66a5f56f-449f-413d-9160-7bb6462f3618"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.46",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "192.168.56.100"
    ],
    "priority": 100,
    "version": "v2",
    "no-address": true,
    "password": "aloha"
    }
    ]
    }' \
    "http://localhost:5555/v3/services/network/connections/66a5f56f-449f-413d-9160-7bb6462f3618?version=$CFGVER&activate=1"
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl --request PUT \
    --user admin:admin \
    --header "Content-Type: application/json" \
    -d '{
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "66a5f56f-449f-413d-9160-7bb6462f3618"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.46",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "192.168.56.100"
    ],
    "priority": 100,
    "version": "v2",
    "no-address": true,
    "password": "aloha"
    }
    ]
    }' \
    "http://localhost:5555/v3/services/network/connections/66a5f56f-449f-413d-9160-7bb6462f3618?version=$CFGVER&activate=1"

    In this example:

    • Include the connection profile’s UUID in the requested URL path. Here, it’s 66a5f56f-449f-413d-9160-7bb6462f3618.

    • Set the URL parameter activate=1.

    • Add a vrrp section to define VRRP options. Here we’re setting:

      • id: The VRID determined previously for the active server.
      • instance: The VRRP instance name.
      • ipv4-addresses: One or more virtual IP addresses. This should be the same set of IP addresses that you set on the active server.
      • priority: The VRRP instance default priority. Set it to 100 for the standby server.
      • version: Set version to v2.
      • no-address: Set this to true to enable more than 20 virtual IP addresses. It implements the virtual_ipaddress_excluded directive in the underlying VRRP configuration.
      • password: The VRRP instance authentication password. All cluster members must set the same password.
    output
    text
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "66a5f56f-449f-413d-9160-7bb6462f3618"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.46",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "192.168.56.100"
    ],
    "no-address": true,
    "password": "aloha",
    "priority": 100,
    "version": "v2"
    }
    ]
    }
    output
    text
    {
    "connection": {
    "id": "ethernet-eth0",
    "interface-name": "eth0",
    "type": "802-3-ethernet",
    "uuid": "66a5f56f-449f-413d-9160-7bb6462f3618"
    },
    "ipv4": {
    "address-data": [
    {
    "address": "192.168.56.46",
    "prefix": 24
    }
    ],
    "gateway": "192.168.56.1",
    "method": "manual",
    "route-data": []
    },
    "ipv6": {
    "address-data": [],
    "method": "disabled",
    "route-data": []
    },
    "vrrp": [
    {
    "id": 130,
    "instance": "default",
    "ipv4-addresses": [
    "192.168.56.100"
    ],
    "no-address": true,
    "password": "aloha",
    "priority": 100,
    "version": "v2"
    }
    ]
    }
  3. Enable the VRRP service on the load balancer.

    Enabling the service after the API calls avoids an error about a missing group directive, because the connection profile now defines the VRID.

  4. To make your changes persistent after a reboot, either:

    • From the HAProxy ALOHA UI, click the Setup tab. Then click Save under Configuration.
    • Connect to the HAProxy ALOHA server and execute config save.

Do you have any suggestions on how we can improve the content of this page? Please leave feedback!