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.9/hapee-lb.sock
.
haproxy
globalstats socket /run/haproxy/admin.sock user haproxy group haproxy mode 660 level admin
haproxy
globalstats socket /run/haproxy/admin.sock user haproxy group haproxy mode 660 level admin
haproxy
globalstats socket /var/run/hapee-2.9/hapee-lb.sock user hapee-lb group hapee mode 660 level admin expose-fd listeners
haproxy
globalstats socket /var/run/hapee-2.9/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.cfghaproxy
globalstats socket ipv4@127.0.0.1:9999 level admin expose-fd listeners
haproxy.cfg, hapee-lb.cfghaproxy
globalstats 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.cfghaproxy
globalstats socket ipv4@*:9999 level admin expose-fd listeners
haproxy.cfg, hapee-lb.cfghaproxy
globalstats 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:
nix
echo "help" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
nix
echo "help" | sudo socat stdio unix-connect:/var/run/hapee-2.9/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-2.9/hapee-lb.sock
nix
echo "show info;show stat" | socat stdio unix-connect:/var/run/hapee-2.9/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-2.9/hapee-lb.sockprompt> show cli leveladmin> operator> show cli leveloperator> quit
nix
sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sockprompt> show cli leveladmin> operator> show cli leveloperator> 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-2.9/certs/new_certificate.pem [alpn h2] mysite.local
.
nix
echo -e "add ssl crt-list /etc/hapee-2.9/certificate-list.txt <<\n/etc/hapee-2.9/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-2.9/certificate-list.txt <<\n/etc/hapee-2.9/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:
-
Install the
socat
package.nixsudo apt-get install socatnixsudo apt-get install socatnixsudo yum install socatnixsudo yum install socatnixsudo zypper install socatnixsudo zypper install socatnixsudo pkg install socatnixsudo pkg install socat -
Call the
help
command:nixecho "help" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.socknixecho "help" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sockoutputtextThe following commands are valid at this level:abort ssl ca-file <cafile> : abort a transaction for a CA fileabort ssl cert <certfile> : abort a transaction for a certificate fileabort ssl crl-file <crlfile> : abort a transaction for a CRL fileadd acl [@<ver>] <acl> <pattern> : add an acl entryadd map [@<ver>] <map> <key> <val> : add a map entry (payload supported instead of key/val)...outputtextThe following commands are valid at this level:abort ssl ca-file <cafile> : abort a transaction for a CA fileabort ssl cert <certfile> : abort a transaction for a certificate fileabort ssl crl-file <crlfile> : abort a transaction for a CRL fileadd acl [@<ver>] <acl> <pattern> : add an acl entryadd 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
outputtext
The following commands are valid at this level:abort ssl ca-file <cafile> : abort a transaction for a CA fileabort ssl cert <certfile> : abort a transaction for a certificate fileabort ssl crl-file <crlfile> : abort a transaction for a CRL fileadd acl [@<ver>] <acl> <pattern> : add an acl entryadd map [@<ver>] <map> <key> <val> : add a map entry (payload supported instead of key/val)...
outputtext
The following commands are valid at this level:abort ssl ca-file <cafile> : abort a transaction for a CA fileabort ssl cert <certfile> : abort a transaction for a certificate fileabort ssl crl-file <crlfile> : abort a transaction for a CRL fileadd acl [@<ver>] <acl> <pattern> : add an acl entryadd map [@<ver>] <map> <key> <val> : add a map entry (payload supported instead of key/val)...
Do you have any suggestions on how we can improve the content of this page?