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:
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.
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.
nixcurl --request GET \--user admin:admin \"http://localhost:5555/v3/services/network/connections"
nixcurl --request GET \--user admin:admin \"http://localhost:5555/v3/services/network/connections"
outputjson[{"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": []}}...]
outputjson[{"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
PUTrequest to theconnectionsendpoint. Send the JSON body for the specific connection profile that you got from calling theconnectionsendpoint withGET, but change theipv4.address-dataarray to include your new address. - Prior to making the
PUTrequest, you must first capture the currentversionin an environment variable (CFGVERin this example) and use the value as a URL parameter. - Include the connection profile’s
uuidin the URL path, here2bbae9d0-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:
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": "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"
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": "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"
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": "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": []}}
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": "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
PUTrequest to theconnectionsendpoint. Send the JSON body for the specific connection profile that you got from calling theconnectionsendpoint withGET, but change theipv4.address-dataarray to remove your unwanted address. - Prior to making the
PUTrequest, you must first capture the currentversionin an environment variable (CFGVERin this example) and use the value as a URL parameter. - Include the connection profile’s
uuidin the URL path, here2bbae9d0-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:
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": "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"
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": "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"
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": "192.168.56.46","prefix": 24}],"gateway": "192.168.56.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": "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
- To set a static IP address on an HAProxy ALOHA server, see IP addresses in HAProxy ALOHA.