Network

Manage link aggregation / link bonding

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 join multiple network interfaces to form a single, unified interface. You’ll call the API endpoint /services/network/connections. Reasons to do this include:

  • increased throughput (802.3ad)
  • redundancy in case one of the links fails (active-backup)

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 bonded interfaces for increased throughput Jump to heading

To bond two network interfaces together in 802.3ad mode:

  1. Create a new interface that will serve as the bonded interface. Below, we make a POST request to the connections endpoint. This creates a new connection profile, which is a collection of network interface settings. In this example:

    • The connection block defines the type of connection profile, bond; its human-readable ID; and interface name.
    • The bond section defines bonding options. To set up IEEE 802.3ad (LACP) Dynamic link aggregation, set the 802.3ad mode. We set the primary interface to eth1. Refer to the bonding modes section for more information.
    • The ipv4 block defines the IP address to assign to the bond interface.
    • Set the URL parameter activate=1.
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0",
          "interface-name": "bond0",
          "type": "bond"
        },
        "bond": {
          "options": {
            "mode": "802.3ad"
          }
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.5",
              "prefix": 24
            }
          ],
          "method": "manual",
          "route-data": []
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0",
          "interface-name": "bond0",
          "type": "bond"
        },
        "bond": {
          "options": {
            "mode": "802.3ad"
          }
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.5",
              "prefix": 24
            }
          ],
          "method": "manual",
          "route-data": []
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    output
    text
    {
      "bond": {
        "options": {
          "mode": "802.3ad"
        }
      },
      "connection": {
        "id": "bond0",
        "interface-name": "bond0",
        "type": "bond",
        "uuid": "46a7ddbc-266e-4ff5-af71-2ea37cae9a80"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.5",
            "prefix": 24
          }
        ],
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      }
    }
    output
    text
    {
      "bond": {
        "options": {
          "mode": "802.3ad"
        }
      },
      "connection": {
        "id": "bond0",
        "interface-name": "bond0",
        "type": "bond",
        "uuid": "46a7ddbc-266e-4ff5-af71-2ea37cae9a80"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.5",
            "prefix": 24
          }
        ],
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      }
    }

  2. Indicate which interfaces to bond by replacing their connection profiles with new profiles that set connection.slave-type to bond and connection.master to bond0. For example, here we make two POST requests to the connections endpoint to replace the eth1 and eth2 profiles:

    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth1",
          "interface-name": "eth1",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth2",
          "interface-name": "eth2",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth1",
          "interface-name": "eth1",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth2",
          "interface-name": "eth2",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    output
    text
    {
      "connection": {
        "id": "bond0-eth1",
        "interface-name": "eth1",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "c68553ad-9309-4a39-8248-699034bdb3c6"
      }
    }
    {
      "connection": {
        "id": "bond0-eth2",
        "interface-name": "eth2",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "66d43b38-9851-4f1a-9293-1a4fe56fccfa"
      }
    }
    output
    text
    {
      "connection": {
        "id": "bond0-eth1",
        "interface-name": "eth1",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "c68553ad-9309-4a39-8248-699034bdb3c6"
      }
    }
    {
      "connection": {
        "id": "bond0-eth2",
        "interface-name": "eth2",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "66d43b38-9851-4f1a-9293-1a4fe56fccfa"
      }
    }

  3. 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 bonded interfaces for active-backup Jump to heading

To bond two network interfaces together in active-backup mode:

  1. Create a new interface that will serve as the bonded interface. Below, we make a POST request to the connections endpoint. This creates a new connection profile, which is a collection of network interface settings. In this example:

    • The connection block defines the type of connection profile, bond; its human-readable ID; and interface name.
    • The bond section defines bonding options. To enable failover with one active interface at a time, set the active-backup mode. We set the primary interface to eth1. Refer to the bonding modes section for more information.
    • The ipv4 block defines the IP address to assign to the bond interface.
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0",
          "interface-name": "bond0",
          "type": "bond"
        },
        "bond": {
          "options": {
            "mode": "active-backup",
            "primary": "eth1"
          }
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.5",
              "prefix": 24
            }
          ],
          "method": "manual",
          "route-data": []
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0",
          "interface-name": "bond0",
          "type": "bond"
        },
        "bond": {
          "options": {
            "mode": "active-backup",
            "primary": "eth1"
          }
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.5",
              "prefix": 24
            }
          ],
          "method": "manual",
          "route-data": []
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    output
    text
    {
      "bond": {
        "options": {
          "mode": "active-backup",
          "primary": "eth1"
        }
      },
      "connection": {
        "id": "bond0",
        "interface-name": "bond0",
        "type": "bond",
        "uuid": "32dae57b-6e51-4722-aa5e-ff92fb338d20"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.5",
            "prefix": 24
          }
        ],
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      }
    }
    output
    text
    {
      "bond": {
        "options": {
          "mode": "active-backup",
          "primary": "eth1"
        }
      },
      "connection": {
        "id": "bond0",
        "interface-name": "bond0",
        "type": "bond",
        "uuid": "32dae57b-6e51-4722-aa5e-ff92fb338d20"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.5",
            "prefix": 24
          }
        ],
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      }
    }

  2. Indicate which interfaces to bond by replacing their connection profiles with new profiles that set connection.slave-type to bond and connection.master to bond0. For example, here we make two POST requests to the connections endpoint to replace the eth1 and eth2 profiles:

    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth1",
          "interface-name": "eth1",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth2",
          "interface-name": "eth2",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    nix
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth1",
          "interface-name": "eth1",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    CFGVER=$(curl -s -u admin:admin http://localhost:5555/v3/services/haproxy/configuration/version)
    curl -X POST \
      --user admin:admin \
      -H "Content-Type: application/json" \
      -d '{
        "connection": {
          "id": "bond0-eth2",
          "interface-name": "eth2",
          "type": "802-3-ethernet",
          "slave-type": "bond",
          "master": "bond0"
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    output
    text
    {
      "connection": {
        "id": "bond0-eth1",
        "interface-name": "eth1",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "c68553ad-9309-4a39-8248-699034bdb3c6"
      }
    }
    {
      "connection": {
        "id": "bond0-eth2",
        "interface-name": "eth2",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "66d43b38-9851-4f1a-9293-1a4fe56fccfa"
      }
    }
    output
    text
    {
      "connection": {
        "id": "bond0-eth1",
        "interface-name": "eth1",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "c68553ad-9309-4a39-8248-699034bdb3c6"
      }
    }
    {
      "connection": {
        "id": "bond0-eth2",
        "interface-name": "eth2",
        "master": "bond0",
        "slave-type": "bond",
        "type": "802-3-ethernet",
        "uuid": "66d43b38-9851-4f1a-9293-1a4fe56fccfa"
      }
    }

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

Verify your setup Jump to heading

To verify, connect to your HAProxy ALOHA server and call ip address show to show network interfaces. The bond0 interface should show the MASTER and MULTICAST labels. The eth1 and eth2 interfaces should show the SLAVE and MULTICAST labels.

nix
ip address show
nix
ip address show
output
text
3: eth1: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP group default qlen 1000
    link/ether 00:0c:29:a1:4c:5a brd ff:ff:ff:ff:ff:ff
4: eth2: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP group default qlen 1000
    link/ether 00:0c:29:a1:4c:5a brd ff:ff:ff:ff:ff:ff permaddr 00:0c:29:a1:4c:64
7: bond0: <BROADCAST,MULTICAST,MASTER,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether 00:0c:29:a1:4c:5a brd ff:ff:ff:ff:ff:ff
    inet 172.16.100.5/24 scope global bond0
       valid_lft forever preferred_lft forever
    inet6 fe80::20c:29ff:fea1:4c5a/64 scope link 
       valid_lft forever preferred_lft forever
output
text
3: eth1: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP group default qlen 1000
    link/ether 00:0c:29:a1:4c:5a brd ff:ff:ff:ff:ff:ff
4: eth2: <BROADCAST,MULTICAST,SLAVE,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master bond0 state UP group default qlen 1000
    link/ether 00:0c:29:a1:4c:5a brd ff:ff:ff:ff:ff:ff permaddr 00:0c:29:a1:4c:64
7: bond0: <BROADCAST,MULTICAST,MASTER,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000
    link/ether 00:0c:29:a1:4c:5a brd ff:ff:ff:ff:ff:ff
    inet 172.16.100.5/24 scope global bond0
       valid_lft forever preferred_lft forever
    inet6 fe80::20c:29ff:fea1:4c5a/64 scope link 
       valid_lft forever preferred_lft forever

Reference Jump to heading

In this section, we describe available options.

Bond options Jump to heading

The following table shows options that the bond.options object supports.

Option Description
downdelay <ms> The bonding delay check in ms (default: 1000).
mode <mode> The bonding mode (default:active-backup).
primary <iface> The primary slave for current bond.
updelay <ms> The bonding delay check in ms (default: 1000).

Bonding modes Jump to heading

The following table shows which bonding modes are supported.

Mode number Mode code Description
O balance-rr Select output interfaces in a round-robin fashion.
1 active-backup Failover mode with one active interface at a time.
2 balance-xor

Transmit based on MAC address. The default policy is a source+destination MAC address algorithm. You can select alternate transmit policies through the xmit_hash_policy bond option. Set the xmit_hash_policy option to one of the following policies:

  • layer2: Use the destination MAC address.
  • layer3+4: When available, use source and destination IPs and ports.
3 broadcast Not supported.
4 802.3ad

You can bundle several physical ports to form a single logical channel through the Link Aggregation Control Protocol (LACP), which is part of the IEEE specification 802.3ad.

Prerequisites:

  • Ethtool support in drivers to retrieve the speed and duplex of each slave.
  • A switch that supports IEEE 802.3ad Dynamic link aggregation.
5 balance-tlb

Transmit load balancing. The outgoing interface is selected based on interface load.

Prerequisites:

  • Ethtool support in drivers to retrieve the speed and duplex of each slave.
6 balance-alb Adaptive load balancing; balance-tlb mode with a reception load balancing mode made using the ARP protocol.

See also Jump to heading

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

Previous page IP addresses Next page Network devices
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences