HAProxy Enterprise

Manage active/standby clustering (VRRP)

Availability:

  • Available in all supported versions of HAProxy Enterprise Data Plane API
  • Not available in the community edition of HAProxy Data Plane API

Running HAProxy ALOHA?

Active/standby clustering on an ALOHA appliance is set up through its network connection rather than a Keepalived configuration file, and the API manages it through /services/network/connections. See Manage active/standby clustering (VRRP) instead.

Overview Jump to heading

You can use HAProxy Data Plane API to configure the HAProxy Enterprise VRRP module, which is based on Keepalived. Once you enable it, you can:

  • read and change VRRP instances, sync groups, track scripts, and global defaults through the /services/keepalived API endpoints and validate every change before it’s applied.
  • reload the VRRP service automatically.

This tutorial shows you how to enable the feature in the keepalived section of the Data Plane API configuration file, and then how to read and change the VRRP configuration with API calls. To install and set up the VRRP module itself first, see Active/standby clustering.

How Keepalived management works Jump to heading

When the keepalived.config_file option is set, HAProxy Data Plane API:

  1. Runs the start_cmd command at startup to make sure the VRRP service is running.
  2. Parses the Keepalived configuration file and exposes it through the /services/keepalived/configuration endpoints.
  3. Writes each change to a transaction file in transaction_dir. When you commit the transaction, the API runs validate_cmd against the transaction file. If validation fails, the API rejects the change and leaves the active configuration untouched, so you can’t commit an invalid configuration.
  4. Replaces the configuration file, optionally keeps a copy of the previous version in backups_dir, and runs reload_cmd. Reloads are spaced at least reload_delay seconds apart.
  5. Watches the configuration file and re-reads it when it changes on disk, unless file watching is disabled with haproxy.disable_inotify.

To report the runtime state of VRRP instances on the /services/keepalived/state endpoints, the API sends signals to the Keepalived process to make it write a state dump, then reads the dump. It uses getpid_cmd, signal_cmd, and read_dump_cmd to do this.

Tip

The API manages the same configuration file the VRRP module reads. If you’re making a one-off edit on a single server, it’s simpler to change /etc/hapee-extras/hapee-vrrp.cfg and restart the service. The API doesn’t replace the VRRP module, its package, or the active/standby setup itself.

Known issues

  • Keep each section’s opening brace on the same line as the section name, as in vrrp_instance vrrp_1 {. The VRRP module accepts either style, but the API fails to read a file that puts the brace on the next line, which leaves the endpoints disabled.
  • Keep a global_defs section in your VRRP configuration file. Keepalived doesn’t require the section, but the API’s parser does.

Install and configure Jump to heading

Install the module and enable API management before you make any API calls. This section covers how to enable management, the configuration version you must send with every change, and how the API reports the result of a change.

Enable Keepalived management Jump to heading

To enable Keepalived management in HAProxy Data Plane API:

  1. Install and configure the VRRP module as described in Active/standby clustering. Make sure the hapee-extras-vrrp service is running.

  2. Create the directories that hold transactions and backups:

    sh
    sudo mkdir -p /etc/hapee-extras/keepalived/transactions \
    /etc/hapee-extras/keepalived/backups
    sh
    sudo mkdir -p /etc/hapee-extras/keepalived/transactions \
    /etc/hapee-extras/keepalived/backups
  3. Edit /etc/hapee-extras/dataplaneapi.yml and add a keepalived section at the top level of the file:

    dataplaneapi.yml
    yaml
    keepalived:
    config_file: /etc/hapee-extras/hapee-vrrp.cfg
    start_cmd: /usr/bin/sudo -n /usr/bin/systemctl start hapee-extras-vrrp
    reload_cmd: /usr/bin/sudo -n /usr/bin/systemctl reload hapee-extras-vrrp
    restart_cmd: /usr/bin/sudo -n /usr/bin/systemctl restart hapee-extras-vrrp
    stop_cmd: /usr/bin/sudo -n /usr/bin/systemctl stop hapee-extras-vrrp
    status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp
    getpid_cmd: /usr/bin/pgrep hapee-vrrp
    signal_cmd: /usr/bin/sudo -n /bin/kill
    read_dump_cmd: /usr/bin/sudo -n /bin/cat
    validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'
    reload_delay: 5
    transaction_dir: /etc/hapee-extras/keepalived/transactions
    backups_dir: /etc/hapee-extras/keepalived/backups
    backups_number: 10
    dataplaneapi.yml
    yaml
    keepalived:
    config_file: /etc/hapee-extras/hapee-vrrp.cfg
    start_cmd: /usr/bin/sudo -n /usr/bin/systemctl start hapee-extras-vrrp
    reload_cmd: /usr/bin/sudo -n /usr/bin/systemctl reload hapee-extras-vrrp
    restart_cmd: /usr/bin/sudo -n /usr/bin/systemctl restart hapee-extras-vrrp
    stop_cmd: /usr/bin/sudo -n /usr/bin/systemctl stop hapee-extras-vrrp
    status_cmd: /usr/bin/systemctl --quiet is-active hapee-extras-vrrp
    getpid_cmd: /usr/bin/pgrep hapee-vrrp
    signal_cmd: /usr/bin/sudo -n /bin/kill
    read_dump_cmd: /usr/bin/sudo -n /bin/cat
    validate_cmd: /bin/sh -c '/opt/hapee-extras/sbin/hapee-vrrp --config-test -f "$KEEPALIVED_TRANSACTION_FILE"'
    reload_delay: 5
    transaction_dir: /etc/hapee-extras/keepalived/transactions
    backups_dir: /etc/hapee-extras/keepalived/backups
    backups_number: 10

    In this example:

    • config_file points to the VRRP module’s configuration file. Setting it enables the /services/keepalived endpoints.
    • start_cmd, reload_cmd, restart_cmd, and stop_cmd control the hapee-extras-vrrp service through systemd.
    • status_cmd returns a zero exit code when the service is running.
    • getpid_cmd, signal_cmd, and read_dump_cmd let the API trigger and read Keepalived state dumps for the /services/keepalived/state endpoints. The API calls signal_cmd as <signal_cmd> -s <SIGNAL> <PID>, so the command must accept the -s flag like kill.
    • validate_cmd checks the candidate configuration before the API commits it. The API sets the KEEPALIVED_TRANSACTION_FILE environment variable to the path of the file to validate.
    • reload_delay is the minimum number of seconds between two reloads.
    • transaction_dir, backups_dir, and backups_number store in-progress transactions and keep the last 10 committed configurations.

    Info

    If HAProxy Data Plane API runs as root, you can drop the /usr/bin/sudo -n prefixes. Otherwise, grant the API’s user password-less sudo rights for these commands.

  4. Restart HAProxy Data Plane API:

    sh
    sudo systemctl restart hapee-extras-dataplaneapi
    sh
    sudo systemctl restart hapee-extras-dataplaneapi
  5. Verify that the API can read the Keepalived configuration:

    sh
    curl --request GET \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v3/services/keepalived/configuration/vrrp_instances"
    sh
    curl --request GET \
    --user admin:adminpwd \
    "http://127.0.0.1:5555/v3/services/keepalived/configuration/vrrp_instances"
    output
    json
    [
    {
    "interface": "eth0",
    "name": "vrrp_1",
    "priority": 101,
    "state": "MASTER",
    "virtual_router_id": 51,
    "virtual_ipaddresses": [
    { "address": "172.17.0.200" }
    ]
    }
    ]
    output
    json
    [
    {
    "interface": "eth0",
    "name": "vrrp_1",
    "priority": 101,
    "state": "MASTER",
    "virtual_router_id": 51,
    "virtual_ipaddresses": [
    { "address": "172.17.0.200" }
    ]
    }
    ]

Tip

You can set every option in this section from the command line instead, by prefixing its name with --keepalived- and replacing underscores with dashes. For example, --keepalived-config-file. A command-line argument takes precedence over the configuration file. Note that the command-line argument for read_dump_cmd is --keepalived-readdump-cmd. See the CLI reference.

Get the configuration version Jump to heading

You must send the current configuration version with every change, either in the version parameter or by using a transaction. The API uses the version for optimistic concurrency control, so if someone else has changed the configuration since you read it, your change is rejected instead of overwriting their change.

Keepalived keeps its own version, separate from the HAProxy configuration version, and no endpoint reports it, so read the # _version line from the raw configuration before each write:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
output
text
18
output
text
18

The value increments with every write, so you must read it again before your next change. If you leave the version out, the API refuses the change with no version or transaction specified, use one; if the version you provide is stale, you’ll get mismatching version.

Known issue

No endpoint returns the current version number. Reading the # _version line from the raw configuration is currently the only reliable way to get the value.

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.

Use a transaction Jump to heading

A transaction groups several changes into one commit, and you only need the version once, when you open it. Read the version, open the transaction, make your changes inside it, and commit them together:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
TXID=$(curl -s -u admin:adminpwd -X POST \
--header "Content-Type: application/json" \
-d "{\"version\": $CFGVER}" \
"http://localhost:5555/v3/services/keepalived/transactions?version=$CFGVER" \
| sed -n 's/.*"id":"\([^"]*\)".*/\1/p')
curl --request POST \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "vrrp_2",
"interface": "eth0",
"state": "backup",
"virtual_router_id": 52,
"priority": 90,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}' \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances?transaction_id=$TXID"
curl --request PUT \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{"force_reload": true}' \
"http://localhost:5555/v3/services/keepalived/transactions/$TXID"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
TXID=$(curl -s -u admin:adminpwd -X POST \
--header "Content-Type: application/json" \
-d "{\"version\": $CFGVER}" \
"http://localhost:5555/v3/services/keepalived/transactions?version=$CFGVER" \
| sed -n 's/.*"id":"\([^"]*\)".*/\1/p')
curl --request POST \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "vrrp_2",
"interface": "eth0",
"state": "backup",
"virtual_router_id": 52,
"priority": 90,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}' \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances?transaction_id=$TXID"
curl --request PUT \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{"force_reload": true}' \
"http://localhost:5555/v3/services/keepalived/transactions/$TXID"
output (transaction start)
json
{
"_version": 4,
"id": "06049a29-47e7-4e73-b984-3b4f398dcda5",
"status": "in_progress"
}
output (transaction start)
json
{
"_version": 4,
"id": "06049a29-47e7-4e73-b984-3b4f398dcda5",
"status": "in_progress"
}
output (add inside the transaction, then commit)
text
HTTP 202
HTTP 202 {"_version": 4, "id": "06049a29-47e7-4e73-b984-3b4f398dcda5", "status": "success"}
output (add inside the transaction, then commit)
text
HTTP 202
HTTP 202 {"_version": 4, "id": "06049a29-47e7-4e73-b984-3b4f398dcda5", "status": "success"}

Inside a transaction, a change carries the transaction_id parameter instead of version. Nothing reaches the configuration file until the commit, and a change that fails validation leaves the file as it was.

Tasks Jump to heading

Once management is enabled, use these requests to read and change the configuration. For the full list of methods and parameters, see the API specification for HAProxy Data Plane API and Keepalived.

List VRRP instances Jump to heading

To list the VRRP instances, make a GET request to the vrrp_instances endpoint.

nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances"
output
json
[
{
"interface": "eth0",
"name": "vrrp_1",
"priority": 101,
"state": "MASTER",
"virtual_router_id": 51,
"virtual_ipaddresses": [
{ "address": "172.17.0.200" }
]
}
]
output
json
[
{
"interface": "eth0",
"name": "vrrp_1",
"priority": 101,
"state": "MASTER",
"virtual_router_id": 51,
"virtual_ipaddresses": [
{ "address": "172.17.0.200" }
]
}
]

List a specific VRRP instance Jump to heading

To read a specific VRRP instance, you can specify its name in the GET call to the vrrp_instances endpoint.

nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2"
output
json
{
"interface": "eth0",
"name": "vrrp_2",
"priority": 90,
"state": "BACKUP",
"virtual_router_id": 52,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}
output
json
{
"interface": "eth0",
"name": "vrrp_2",
"priority": 90,
"state": "BACKUP",
"virtual_router_id": 52,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}

Add a VRRP instance Jump to heading

Add a VRRP instance by making a POST request to the vrrp_instances endpoint, sending the fields you want 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:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request POST \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "vrrp_2",
"interface": "eth0",
"state": "backup",
"virtual_router_id": 52,
"priority": 90,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}' \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request POST \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "vrrp_2",
"interface": "eth0",
"state": "backup",
"virtual_router_id": 52,
"priority": 90,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}' \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances?version=$CFGVER"
output
text
HTTP 202
output
text
HTTP 202
body
json
{
"interface": "eth0",
"name": "vrrp_2",
"priority": 90,
"state": "BACKUP",
"virtual_router_id": 52,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}
body
json
{
"interface": "eth0",
"name": "vrrp_2",
"priority": 90,
"state": "BACKUP",
"virtual_router_id": 52,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}

By default, the API applies the change in the background: it answers 202 Accepted with a Reload-ID header, rewrites the configuration file, and keeps a copy in backups_dir. The version increments with every write. Read it again before the next change.

To wait for the reload instead, add force_reload=true to the query string. The same request then answers 201 Created. The delete example shows the parameter in place.

Send state in lowercase in the request body (master or backup). The API and the configuration file both use uppercase in the response and on disk (MASTER, BACKUP). A missing version returns no version or transaction specified, use one, and a stale one returns mismatching version.

Replace a VRRP instance Jump to heading

To change a VRRP instance, replace it entirely by making a PUT request to the vrrp_instances endpoint with the instance name in the path. The body must include the name.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request PUT \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "vrrp_2",
"interface": "eth0",
"state": "backup",
"virtual_router_id": 52,
"priority": 95,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}' \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request PUT \
--user admin:adminpwd \
--header "Content-Type: application/json" \
-d '{
"name": "vrrp_2",
"interface": "eth0",
"state": "backup",
"virtual_router_id": 52,
"priority": 95,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}' \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2?version=$CFGVER"
output
text
HTTP 202
output
text
HTTP 202
body
json
{
"interface": "eth0",
"name": "vrrp_2",
"priority": 95,
"state": "BACKUP",
"virtual_router_id": 52,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}
body
json
{
"interface": "eth0",
"name": "vrrp_2",
"priority": 95,
"state": "BACKUP",
"virtual_router_id": 52,
"virtual_ipaddresses": [
{ "address": "172.17.0.201" }
]
}

As with a create, the default answer is 202 Accepted, or 200 OK with force_reload=true, because a replace changes an existing resource.

Delete a VRRP instance Jump to heading

To delete a VRRP instance, make a DELETE request to the vrrp_instances endpoint with the instance name in the path.

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2?version=$CFGVER"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2?version=$CFGVER"
output
text
HTTP 202
output
text
HTTP 202

Add force_reload=true to wait for the reload:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2?version=$CFGVER&force_reload=true"
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/keepalived/configuration/raw | grep -o '_version=[0-9]*' | cut -d= -f2)
curl --request DELETE \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_instances/vrrp_2?version=$CFGVER&force_reload=true"
output
text
HTTP 204
output
text
HTTP 204

The default answer is 202 Accepted, or 204 No Content with force_reload=true, because a delete leaves nothing to return.

Read the sync groups and track scripts Jump to heading

A sync group ties VRRP instances together so that they change state as a unit, and a track script adjusts an instance’s priority based on the result of a command. Read both with a GET request:

nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_sync_groups"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_sync_groups"
output
json
[
{
"group": [
"vrrp_1",
"vrrp_2"
],
"name": "sync_pair"
}
]
output
json
[
{
"group": [
"vrrp_1",
"vrrp_2"
],
"name": "sync_pair"
}
]
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_track_scripts"
nix
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/configuration/vrrp_track_scripts"
output
json
[
{
"fall": 3,
"interval": 2,
"name": "check_gateway",
"rise": 2,
"script": "/bin/true",
"timeout": 1
}
]
output
json
[
{
"fall": 3,
"interval": 2,
"name": "check_gateway",
"rise": 2,
"script": "/bin/true",
"timeout": 1
}
]

In a track script, interval and timeout are seconds, rise and fall are counts, and weight sets how much the script’s result changes the instance’s priority. The example uses /bin/true so that the check always succeeds; use the command that tests what you care about.

To add or change a sync group or a track script, use the same request pattern as a VRRP instance: send the name and its fields in the request body, with version or transaction_id in the query string. In the configuration file, the sections are vrrp_sync_group and vrrp_script.

Read the VRRP state Jump to heading

This section applies to:

  • HAProxy Data Plane API 3.4 and newer

The state endpoints answer questions the configuration can’t: which node holds the virtual IP right now, whether a failover happened, and which node is safe to restart during maintenance. Point monitoring at them to alert on an unexpected failover, and check them before you touch a node so you don’t take down the active one.

The /state endpoint returns one entry per instance with its current state, priority, and virtual IP addresses:

sh
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/state"
sh
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/state"
output (state)
json
[
{
"last_transition": 1793360756.093011,
"name": "vrrp_1",
"priority": 101,
"state": "MASTER",
"vips": [
"172.17.0.200"
]
}
]
output (state)
json
[
{
"last_transition": 1793360756.093011,
"name": "vrrp_1",
"priority": 101,
"state": "MASTER",
"vips": [
"172.17.0.200"
]
}
]

The API caches this summary for 30 seconds, so a state change can take that long to appear. Read /state/full when you need the current dump.

The /state/full endpoint returns the Keepalived state dump for the same instances, which adds the counters that help when you investigate a failover, such as advert_sent, become_master, and release_master:

sh
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/state/full"
sh
curl --request GET \
--user admin:adminpwd \
"http://localhost:5555/v3/services/keepalived/state/full"
output (state/full)
json
{
"json_version": 1,
"v1": [
{
"data": {
"iname": "vrrp_1",
"state": 2,
"base_priority": 101,
"effective_priority": 101,
"vrid": 51,
"vips": [ "172.17.0.200 dev eth0 scope global set" ]
},
"stats": {
"advert_sent": 11,
"become_master": 1,
"release_master": 0
}
}
]
}
output (state/full)
json
{
"json_version": 1,
"v1": [
{
"data": {
"iname": "vrrp_1",
"state": 2,
"base_priority": 101,
"effective_priority": 101,
"vrid": 51,
"vips": [ "172.17.0.200 dev eth0 scope global set" ]
},
"stats": {
"advert_sent": 11,
"become_master": 1,
"release_master": 0
}
}
]
}

In the dump, state is a number: 2 is MASTER. Use /state when you want the state as a word.

Both endpoints work from the state dump that Keepalived writes. The API signals the process to write it with getpid_cmd and signal_cmd, then reads it with read_dump_cmd. If Keepalived isn’t running, or signal_cmd fails, the endpoints report the last dump that was written.

Configure the state dump location Jump to heading

Keepalived writes its JSON state dump to /tmp/keepalived.json by default. If you change the location with the json_file_location directive in the global_defs section of the Keepalived configuration, the API reads the dump from that location instead. Make sure the read_dump_cmd command can read the file at that path.

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