HAProxy Runtime API

Installation

This page describes how to enable and then access the HAProxy Runtime API.

Enable the Runtime API Jump to heading

To enable the Runtime API, add a stats socket directive to the global section of your configuration. You can expose the API as either a UNIX socket, in which case you can access it only from the load balancer server, or as an IP address and port, in which case you can access it remotely.

To configure it as a UNIX socket, set the path where you would like the socket to be created, such as /var/run/hapee-2.8/hapee-lb.sock.

haproxy
global
stats socket /run/haproxy/admin.sock user haproxy group haproxy mode 660 level admin
haproxy
global
stats socket /run/haproxy/admin.sock user haproxy group haproxy mode 660 level admin
haproxy
global
stats socket /var/run/hapee-2.8/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
haproxy
global
stats socket /var/run/hapee-2.8/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners

Or set an IP address and port:

haproxy.cfg, hapee-lb.cfg
haproxy
global
stats socket ipv4@127.0.0.1:9999 level admin expose-fd listeners
haproxy.cfg, hapee-lb.cfg
haproxy
global
stats socket ipv4@127.0.0.1:9999 level admin expose-fd listeners

You can set the IP address to an asterisk to listen on all network interfaces.

Warning

This could inadvertently expose the API on a public IP address where it is available to unauthorized users.

If using this, be sure to block external access to port 9999 with your network firewall.

haproxy.cfg, hapee-lb.cfg
haproxy
global
stats socket ipv4@*:9999 level admin expose-fd listeners
haproxy.cfg, hapee-lb.cfg
haproxy
global
stats socket ipv4@*:9999 level admin expose-fd listeners

The parameters are as follows:

Parameter Description
user Sets the owner of the UNIX socket to the designated system user.
group Sets the group of the UNIX socket to the designated system group.
mode Sets the octal mode used to define permissions on the UNIX socket.
level Restricts the commands that can be issued.
expose-fd listeners Enables you to do a seamless reload of the load balancer when master-worker mode is enabled.

Set level to one of the following values:

Value Description
user Only non-sensitive stats can be read and no changes are allowed.
operator All data can be read and non-sensitive changes are allowed (default).
admin Everything is permitted.

Access the Runtime API Jump to heading

You can send plain text commands to the API. An easy way to try it is by using the Linux echo command and piping the result to socat.

socat stands for “SOcket CAT” and is a versatile networking utility available on Linux. It has the ability to create and manage various types of network connections, and can be used to handle a wide range of tasks involving network data transfer, redirection, and manipulation. Visit the man pages for more information.

When using a UNIX socket, you can also use the API interactively by using socat. If you exposed a UNIX socket, use this format:

bash
echo "help" | sudo socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock
bash
echo "help" | sudo socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock

If you exposed an IP address and port, use this format:

bash
echo "help" | socat stdio tcp4-connect:127.0.0.1:9999
bash
echo "help" | socat stdio tcp4-connect:127.0.0.1:9999

You can send multiple commands at once by separating them with semi-colons:

bash
echo "show info;show stat" | socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock
bash
echo "show info;show stat" | socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock

You can use socat without piping a command to it. Send the prompt command to start a new session with the API. Some commands, such as show cli level, work best in an interactive session because they display information about your history with the API and outside of a session, have no history to show:

bash
sudo socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock
prompt
> show cli level
admin
> operator
> show cli level
operator
> quit
bash
sudo socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock
prompt
> show cli level
admin
> operator
> show cli level
operator
> quit

To see which commands are available, call the help command.

View help when using the UNIX socket Jump to heading

When using the UNIX socket, follow these steps:

  1. Install the socat package.

    bash
    sudo apt-get install socat
    bash
    sudo apt-get install socat
    bash
    sudo yum install socat
    bash
    sudo yum install socat
    bash
    sudo zypper install socat
    bash
    sudo zypper install socat
    bash
    sudo pkg install socat
    bash
    sudo pkg install socat
  2. Call the help command:

    bash
    echo "help" | \
    sudo socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock
    bash
    echo "help" | \
    sudo socat stdio unix-connect:/var/run/hapee-2.8/hapee-lb.sock
    output
    bash
    The following commands are valid at this level:
    abort ssl ca-file <cafile> : abort a transaction for a CA file
    abort ssl cert <certfile> : abort a transaction for a certificate file
    abort ssl crl-file <crlfile> : abort a transaction for a CRL file
    add acl [@<ver>] <acl> <pattern> : add an acl entry
    add map [@<ver>] <map> <key> <val> : add a map entry (payload supported instead of key/val)
    ...
    output
    bash
    The following commands are valid at this level:
    abort ssl ca-file <cafile> : abort a transaction for a CA file
    abort ssl cert <certfile> : abort a transaction for a certificate file
    abort ssl crl-file <crlfile> : abort a transaction for a CRL file
    add acl [@<ver>] <acl> <pattern> : add an acl entry
    add map [@<ver>] <map> <key> <val> : add a map entry (payload supported instead of key/val)
    ...

View help when using a TCP/IP address Jump to heading

When using a TCP/IP address to access the API, you can call the help command:

bash
echo "help" | socat stdio tcp4-connect:127.0.0.1:9999
bash
echo "help" | socat stdio tcp4-connect:127.0.0.1:9999
output
bash
The following commands are valid at this level:
abort ssl ca-file <cafile> : abort a transaction for a CA file
abort ssl cert <certfile> : abort a transaction for a certificate file
abort ssl crl-file <crlfile> : abort a transaction for a CRL file
add acl [@<ver>] <acl> <pattern> : add an acl entry
add map [@<ver>] <map> <key> <val> : add a map entry (payload supported instead of key/val)
...
output
bash
The following commands are valid at this level:
abort ssl ca-file <cafile> : abort a transaction for a CA file
abort ssl cert <certfile> : abort a transaction for a certificate file
abort ssl crl-file <crlfile> : abort a transaction for a CRL file
add acl [@<ver>] <acl> <pattern> : add an acl entry
add map [@<ver>] <map> <key> <val> : add a map entry (payload supported instead of key/val)
...

If this page was useful, please, Leave the feedback.