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:
nixhttp://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=1
nixhttp://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:
nixCFGVER=$(curl --silent --user admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
nixCFGVER=$(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:
nixhttp://localhost:5555/v3/services/haproxy/configuration/backends/myservers?version=$CFGVER
nixhttp://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:
outputtextHTTP 202 AcceptedReload-ID: 2026-10-29-0
outputtextHTTP 202 AcceptedReload-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:
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
nixcurl --request GET \--user admin:adminpwd \"http://localhost:5555/v3/services/haproxy/reloads/2026-10-29-0"
outputjson{"id": "2026-10-29-0","reload_timestamp": 1793301215,"status": "succeeded"}
outputjson{"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:
-
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
PUTrequest to theconnectionsendpoint to update theeth1interface to use a smaller/25subnet. We include the interface’s UUID in the requested URL path and we setactivate=1.nixCFGVER=$(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"nixCFGVER=$(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"outputtext{"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": []}}outputtext{"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": []}} -
Make a
POSTrequest to theconnectionsendpoint. This creates a new connection profile, which is a collection of network interface settings. In this example:- The
connectionblock defines the type of connection profile,vlan; its human-readable ID; and interface name. - The
vlanblock sets the numeric ID for the VLAN interface and its parent network interface,eth1. - The
ipv4block 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.
nixCFGVER=$(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"nixCFGVER=$(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"outputtext{"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"}}outputtext{"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"}} - The
-
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.
nixsudo ip addr show
nixsudo ip addr show
outputtext...3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ffaltname enp0s3inet 172.16.100.4/25 scope global eth1valid_lft forever preferred_lft foreverinet6 fe80::a00:27ff:fe8d:c04d/64 scope linkvalid_lft forever preferred_lft forever4: eth1.100@eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ffinet 172.16.100.131/25 scope global eth1.100valid_lft forever preferred_lft forever
outputtext...3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ffaltname enp0s3inet 172.16.100.4/25 scope global eth1valid_lft forever preferred_lft foreverinet6 fe80::a00:27ff:fe8d:c04d/64 scope linkvalid_lft forever preferred_lft forever4: eth1.100@eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000link/ether 08:00:27:8d:c0:4d brd ff:ff:ff:ff:ff:ffinet 172.16.100.131/25 scope global eth1.100valid_lft forever preferred_lft forever
See also Jump to heading
- To create VLANs on HAProxy ALOHA, see VLANs in HAProxy ALOHA.