Network

Manage active/standby clustering (VRRP)

On this page

This page applies to:

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

You can use the 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 -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
nix
CFGVER=$(curl -s -u 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

Configure the active server Jump to heading

Follow these steps to configure the active load balancer.

  1. Enable the VRRP service on the load balancer.

  2. 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.

  3. 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 -X GET \
      --user admin:admin \
      "http://localhost:5555/v3/services/network/connections"
    nix
    curl -X 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
            },
            {
              "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
            },
            {
              "address": "192.168.56.45",
              "prefix": 24
            }
          ],
          "gateway": "192.168.56.1",
          "method": "manual",
          "route-data": []
        },
        "ipv6": {
          "address-data": [],
          "method": "disabled",
          "route-data": []
        }
      }
    ]

  4. 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 -X PUT \
      --user admin:admin \
      -H "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 -X PUT \
      --user admin:admin \
      -H "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"
        }
      ]
    }

  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. Enable the VRRP service on the load balancer.

  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 -X GET \
      --user admin:admin \
      "http://localhost:5555/v3/services/network/connections"
    nix
    curl -X 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": []
        }
      }
    ]

  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 -X PUT \
      --user admin:admin \
      -H "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 -X PUT \
      --user admin:admin \
      -H "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"
        }
      ]
    }

  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?

Previous page VLAN Next page Advanced features
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences