HAProxy ALOHA

Manage IP addresses

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 list, add, or remove static IP addresses from 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.

List static IP addresses Jump to heading

To list the static IP addresses assigned to a network interface, make a GET request to the connections endpoint. This returns a list of connection profiles, which are collections of network interface settings.

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

Add a static IP address Jump to heading

To add a static IP address:

  • Make a PUT request to the connections endpoint. Send the JSON body for the specific connection profile that you got from calling the connections endpoint with GET, but change the ipv4.address-data array to include your new address.
  • Prior to making the PUT request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value as a URL parameter.
  • Include the connection profile’s uuid in the URL path, here 2bbae9d0-8d49-434b-a80b-a62404e96c6b.
  • Set the URL parameter activate=1.

Below, we add two IP addresses on the eth1 interface: 192.168.56.46 and 192.168.56.47:

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": "192.168.56.46",
"prefix": 24
},
{
"address": "192.168.56.47",
"prefix": 24
}
],
"gateway": "192.168.56.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": "192.168.56.46",
"prefix": 24
},
{
"address": "192.168.56.47",
"prefix": 24
}
],
"gateway": "192.168.56.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": "192.168.56.47",
"prefix": 24
},
{
"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
{
"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": "192.168.56.47",
"prefix": 24
},
{
"address": "192.168.56.46",
"prefix": 24
}
],
"gateway": "192.168.56.1",
"method": "manual",
"route-data": []
},
"ipv6": {
"address-data": [],
"method": "disabled",
"route-data": []
}
}

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.

Remove a static IP address Jump to heading

To remove a static IP address:

  • Make a PUT request to the connections endpoint. Send the JSON body for the specific connection profile that you got from calling the connections endpoint with GET, but change the ipv4.address-data array to remove your unwanted address.
  • Prior to making the PUT request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value as a URL parameter.
  • Include the connection profile’s uuid in the URL path, here 2bbae9d0-8d49-434b-a80b-a62404e96c6b.
  • Set the URL parameter activate=1.

Below, we have removed an IP addresses, 192.168.56.47, leaving only 192.168.56.46 in the address-data array:

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": "192.168.56.46",
"prefix": 24
}
],
"gateway": "192.168.56.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": "192.168.56.46",
"prefix": 24
}
],
"gateway": "192.168.56.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": "192.168.56.46",
"prefix": 24
}
],
"gateway": "192.168.56.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": "192.168.56.46",
"prefix": 24
}
],
"gateway": "192.168.56.1",
"method": "manual",
"route-data": []
},
"ipv6": {
"address-data": [],
"method": "disabled",
"route-data": []
}
}

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.

See also Jump to heading

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