Tutorials

Bind to an address

On this page

In your load balancer configuration, a frontend listens for and receives connections from clients. A bind line in a frontend defines the IP address and port on which to listen.

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

List binds Jump to heading

To get a list of existing binds in the www frontend, make a GET request to the binds endpoint.

Pass the name of the frontend, www, as part of the URL path.

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds"
output
json
[
  {
    "name": "http",
    "port": 80
  }
]
output
json
[
  {
    "name": "http",
    "port": 80
  }
]

Pass the name of the frontend, www, as a query string parameter.

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/binds?frontend=www"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/binds?frontend=www"
output
json
{
  "_version": 99,
  "data": [
    {
      "name": "http",
      "port": 80
    }
  ]
}
output
json
{
  "_version": 99,
  "data": [
    {
      "name": "http",
      "port": 80
    }
  ]
}

List a specific bind Jump to heading

To get information about a specific bind, add its name to the GET call.

Pass the name of the frontend, www, and the name of the bind, https, as part of the URL path.

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds/https"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds/https"
output
json
{
  "address": "*",
  "alpn": "h2",
  "name": "https",
  "port": 443,
  "ssl": true,
  "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
}
output
json
{
  "address": "*",
  "alpn": "h2",
  "name": "https",
  "port": 443,
  "ssl": true,
  "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
}

Pass the name of the bind, https, as part of the URL path and the name of the frontend, www, as a query string parameter.

nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/binds/https?frontend=www"
nix
curl -X GET \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/binds/https?frontend=www"
output
json
{
  "_version": 99,
  "data": {
    "address": "*",
    "alpn": "h2",
    "name": "https",
    "port": 443,
    "ssl": true,
    "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
  }
}
output
json
{
  "_version": 99,
  "data": {
    "address": "*",
    "alpn": "h2",
    "name": "https",
    "port": 443,
    "ssl": true,
    "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
  }
}

Add a bind Jump to heading

Add a bind to the www frontend by making a POST request to the binds endpoint. Send the fields to set in the body of the request. Note that prior to making the POST request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request:

Pass the name of the frontend, www, as part of the URL path.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
     "name": "https",
     "address": "*",
     "port": 443,
     "alpn": "h2",
     "ssl": true,
     "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
     "name": "https",
     "address": "*",
     "port": 443,
     "alpn": "h2",
     "ssl": true,
     "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
  }' \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds?version=$CFGVER"

Pass the name of the frontend, www, as a query string parameter.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
     "name": "https",
     "address": "*",
     "port": 443,
     "alpn": "h2",
     "ssl": true,
     "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/binds?frontend=www&version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
  --user admin:adminpwd \
  -H "Content-Type: application/json" \
  -d '{
     "name": "https",
     "address": "*",
     "port": 443,
     "alpn": "h2",
     "ssl": true,
     "ssl_certificate": "/etc/haproxy/ssl/cert.pem"
  }' \
  "http://localhost:5555/v2/services/haproxy/configuration/binds?frontend=www&version=$CFGVER"

Replace a bind Jump to heading

To make changes to a bind, you replace it entirely. To replace an existing bind, make a PUT request to the binds endpoint. Note that 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 in your request. In this case, we are updating the bind named https:

Pass the name of the frontend, www, and the name of the bind, https, as part of the URL path.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X PUT \
   --user admin:adminpwd \
   -H "Content-Type: application/json" \
    -d '{
      "address":"*",
      "alpn":"h2",
      "name":"https",
      "port":8443,
      "ssl":true,
      "ssl_certificate":"/etc/haproxy/ssl/cert.pem"
    }' \
   "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds/https?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X PUT \
   --user admin:adminpwd \
   -H "Content-Type: application/json" \
    -d '{
      "address":"*",
      "alpn":"h2",
      "name":"https",
      "port":8443,
      "ssl":true,
      "ssl_certificate":"/etc/haproxy/ssl/cert.pem"
    }' \
   "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds/https?version=$CFGVER"

Pass the name of the bind, https, as part of the URL path and the name of the frontend, www, as a query string parameter.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X PUT \
   --user admin:adminpwd \
   -H "Content-Type: application/json" \
    -d '{
      "address":"*",
      "alpn":"h2",
      "name":"https",
      "port":8443,
      "ssl":true,
      "ssl_certificate":"/etc/haproxy/ssl/cert.pem"
    }' \
   "http://localhost:5555/v2/services/haproxy/configuration/binds/https?frontend=www&version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X PUT \
   --user admin:adminpwd \
   -H "Content-Type: application/json" \
    -d '{
      "address":"*",
      "alpn":"h2",
      "name":"https",
      "port":8443,
      "ssl":true,
      "ssl_certificate":"/etc/haproxy/ssl/cert.pem"
    }' \
   "http://localhost:5555/v2/services/haproxy/configuration/binds/https?frontend=www&version=$CFGVER"

Delete a bind Jump to heading

To delete a bind, use the DELETE method. Note that prior to making the DELETE request, you must first capture the current version in an environment variable (CFGVER in this example) and use the value in your request:

Pass the name of the frontend, www, and the name of the bind, https, as part of the URL path.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds/https?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v3/services/haproxy/configuration/frontends/www/binds/https?version=$CFGVER"

Pass the name of the bind, https, as part of the URL path and the name of the frontend, www, as a query string parameter.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/binds/https?frontend=www&version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X DELETE \
  --user admin:adminpwd \
  "http://localhost:5555/v2/services/haproxy/configuration/binds/https?frontend=www&version=$CFGVER"

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

Previous page Manage frontends Next page Manage backends
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences