Network

Manage VLANs

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 manage VLANs on your load balancer. 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

Add a VLAN interface Jump to heading

To add a VLAN interface:

  1. Modify your existing network interface to use only a portion of the IP address space so that VLAN traffic can use another portion. The IP range should match the settings on your network switch.

    Below, we make a PUT request to the connections endpoint to update the eth1 interface to use a smaller /25 subnet. We include the interface’s UUID in the requested URL path and we set 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 '{
        "802-3-ethernet": {
          "auto-negotiate": true
        },
        "connection": {
          "id": "ethernet-eth1",
          "interface-name": "eth1",
          "type": "802-3-ethernet",
          "uuid": "2bbae9d0-8d49-434b-a80b-a62404e96c6b"
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.4",
              "prefix": 25
            }
          ],
          "gateway": "172.16.100.1",
          "method": "manual",
          "route-data": []
        },
        "ipv6": {
          "address-data": [],
          "method": "disabled",
          "route-data": []
        }
      }' \
      "http://localhost:5555/v3/services/network/connections/2bbae9d0-8d49-434b-a80b-a62404e96c6b?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 '{
        "802-3-ethernet": {
          "auto-negotiate": true
        },
        "connection": {
          "id": "ethernet-eth1",
          "interface-name": "eth1",
          "type": "802-3-ethernet",
          "uuid": "2bbae9d0-8d49-434b-a80b-a62404e96c6b"
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.4",
              "prefix": 25
            }
          ],
          "gateway": "172.16.100.1",
          "method": "manual",
          "route-data": []
        },
        "ipv6": {
          "address-data": [],
          "method": "disabled",
          "route-data": []
        }
      }' \
      "http://localhost:5555/v3/services/network/connections/2bbae9d0-8d49-434b-a80b-a62404e96c6b?version=$CFGVER&activate=1"
    output
    text
    {
      "802-3-ethernet": {
        "auto-negotiate": true
      },
      "connection": {
        "id": "ethernet-eth1",
        "interface-name": "eth1",
        "type": "802-3-ethernet",
        "uuid": "2bbae9d0-8d49-434b-a80b-a62404e96c6b"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.4",
            "prefix": 25
          }
        ],
        "gateway": "172.16.100.1",
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      }
    }
    output
    text
    {
      "802-3-ethernet": {
        "auto-negotiate": true
      },
      "connection": {
        "id": "ethernet-eth1",
        "interface-name": "eth1",
        "type": "802-3-ethernet",
        "uuid": "2bbae9d0-8d49-434b-a80b-a62404e96c6b"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.4",
            "prefix": 25
          }
        ],
        "gateway": "172.16.100.1",
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      }
    }

  2. 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, vlan; its human-readable ID; and interface name.
    • The vlan block sets the numeric ID for the VLAN interface and its parent network interface, eth1.
    • The ipv4 block defines the IP address to assign to the VLAN interface. Here, we use a range that won’t collide with non-VLAN traffic on the same parent interface, 172.16.100.131/25.
    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": "vlan-100",
          "interface-name": "vlan-100",
          "type": "vlan"
        },
        "vlan": {
          "id": 100,
          "parent": "eth1"
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.131",
              "prefix": 25
            }
          ],
          "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": "vlan-100",
          "interface-name": "vlan-100",
          "type": "vlan"
        },
        "vlan": {
          "id": 100,
          "parent": "eth1"
        },
        "ipv4": {
          "address-data": [
            {
              "address": "172.16.100.131",
              "prefix": 25
            }
          ],
          "method": "manual",
          "route-data": []
        }
      }' \
      "http://localhost:5555/v3/services/network/connections?version=$CFGVER&activate=1"
    output
    text
    {
      "connection": {
        "id": "vlan-100",
        "interface-name": "eth1.100",
        "type": "vlan",
        "uuid": "72389ae2-6009-4013-94f2-1b43ba5e1734"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.131",
            "prefix": 25
          }
        ],
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      },
      "vlan": {
        "id": 100,
        "parent": "eth1"
      }
    }
    output
    text
    {
      "connection": {
        "id": "vlan-100",
        "interface-name": "eth1.100",
        "type": "vlan",
        "uuid": "72389ae2-6009-4013-94f2-1b43ba5e1734"
      },
      "ipv4": {
        "address-data": [
          {
            "address": "172.16.100.131",
            "prefix": 25
          }
        ],
        "method": "manual",
        "route-data": []
      },
      "ipv6": {
        "address-data": [],
        "method": "disabled",
        "route-data": []
      },
      "vlan": {
        "id": 100,
        "parent": "eth1"
      }
    }

  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 the VLAN interface Jump to heading

The VLAN interface should have been assigned to the physical interface, for example VLAN 100 on physical interface eth1. To check this, use the ip command to verify that the MAC addresses (the link/ether value) for the physical interface and its VLAN network are the same.

Below, we verify that the MAC addresses are the same on eth1 and eth1.100. Both show matching link/ether values of 08:00:27:8d:c0:4d.

nix
sudo ip addr show
nix
sudo ip addr show
output
text
...
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
   link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ff
   altname enp0s3
   inet 172.16.100.4/25 scope global eth1
      valid_lft forever preferred_lft forever
   inet6 fe80::a00:27ff:fe8d:c04d/64 scope link
      valid_lft forever preferred_lft forever
4: eth1.100@eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
   link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ff
   inet 172.16.100.131/25 scope global eth1.100
      valid_lft forever preferred_lft forever
output
text
...
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
   link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ff
   altname enp0s3
   inet 172.16.100.4/25 scope global eth1
      valid_lft forever preferred_lft forever
   inet6 fe80::a00:27ff:fe8d:c04d/64 scope link
      valid_lft forever preferred_lft forever
4: eth1.100@eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
   link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ff
   inet 172.16.100.131/25 scope global eth1.100
      valid_lft forever preferred_lft forever

See also Jump to heading

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

Previous page Network devices Next page Active/standby clustering
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences