HAProxy ALOHA

Manage VLANs

This page applies to:

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

You can use 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 --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.

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 --request PUT \
    --user admin:admin \
    --header "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 --request PUT \
    --user admin:admin \
    --header "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 --request POST \
    --user admin:admin \
    --header "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 --request POST \
    --user admin:admin \
    --header "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? Please leave feedback!