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-3.0/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-3.0/hapee-lb.sock  user hapee-lb  group hapee  mode 660  level admin  expose-fd listeners

haproxy
global
  stats socket /var/run/hapee-3.0/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.

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:

Set level to one of the following values:

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:

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

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

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

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

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

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

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

nix
echo "show info;show stat" | socat stdio unix-connect:/var/run/hapee-3.0/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:

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

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

Some commands may take an optional payload. To add one to a command, the first line needs to end with the <<\n pattern. The next lines will be treated as the payload and can contain as many lines as needed. To validate a command with a payload, it needs to end with an empty line. For example, in the following add ssl crt-list command, the payload is the line /etc/hapee-3.0/certs/new_certificate.pem [alpn h2] mysite.local.

nix
echo -e "add ssl crt-list /etc/hapee-3.0/certificate-list.txt <<\n/etc/hapee-3.0/certs/new_certificate.pem [alpn h2] mysite.local\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo -e "add ssl crt-list /etc/hapee-3.0/certificate-list.txt <<\n/etc/hapee-3.0/certs/new_certificate.pem [alpn h2] mysite.local\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

As of version 2.9r1, the payload pattern, <<\n by default, can be customized to change the way the payload ends. To end a payload with something other than an empty line, a customized pattern can be set between << and \n. Only 7 characters can be used in addition to <<. Otherwise, the payload will not be parsed correctly. For example, to use a PEM file that contains empty lines and comments:

nix
echo -e "set ssl cert common.pem <<%EOF%\n$(cat common.pem)\n%EOF%\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo -e "set ssl cert common.pem <<%EOF%\n$(cat common.pem)\n%EOF%\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

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.

   apt yum zypper pkg

   nix
   sudo apt-get install socat

   nix
   sudo apt-get install socat

   nix
   sudo yum install socat

   nix
   sudo yum install socat

   nix
   sudo zypper install socat

   nix
   sudo zypper install socat

   nix
   sudo pkg install socat

   nix
   sudo pkg install socat

2. Call the help command:

   nix
   echo "help" | \
        sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

   nix
   echo "help" | \
        sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

   output
   text
   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
   text
   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:

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

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

output
text
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
text
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)
...