HAProxy Enterprise Documentation 2.5r1

Install the HAProxy Enterprise Runtime API

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

Enable the Runtime API

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 HAProxy Enterprise 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.5/hapee-lb.sock.

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

Or set an IP address and port:

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.

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 you can be issued. Set it to one of the following values:

  • user - only non-sensitive stats can be read and no changes are allowed.

  • operator - [default] all data can be read and non-sensitive changes are allowed.

  • admin - everything is permitted.

expose-fd listeners

Enables you to do a seamless reload of HAProxy Enterprise when master-worker mode is enabled.

Access the Runtime API

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.

If you exposed a UNIX socket, use this format:

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

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

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

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

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

When using a UNIX socket, you can also use the API interactively by using socat, but without piping a command to it. Then 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:

$ sudo socat stdio unix-connect:/var/run/hapee-2.5/hapee-lb.sock
  prompt
  > show cli level
  admin

  > operator

  > show cli level
  operator

  > quit

Next up

HAProxy Enterprise Runtime API tutorials