HAProxy config tutorials

Programs

Available since

  • HAProxy 2.0
  • HAProxy Enterprise 2.0r1
  • HAProxy ALOHA 11.5

Add the program section to specify an external program that should run as a child process under the load balancer process.

Configure an external program Jump to heading

A program section in your configuration contains a set of directives that define the program to be run, its command-line options and flags, as well as user, group, and restart options.

Below, we run the echo command to print Hello World! to standard out when the load balancer starts. Note that this requires you to enable master-worker mode.

haproxy
global
master-worker
program echo
command echo "Hello, World!"
haproxy
global
master-worker
program echo
command echo "Hello, World!"

Here’s a functionally equivalent example that sets the user and group directives:

haproxy
program echo
command echo "Hello, World!"
user hapee-lb
group hapee
haproxy
program echo
command echo "Hello, World!"
user hapee-lb
group hapee

When you restart the load balancer, you can see that the echo command execute then exit without error. You can use the program section to execute long-running programs that live alongside the load balancer too. Programs will restart and reload when the load balancer does, unless you specify no option start-on-reload.

After restarting the service, the echo program’s output displays:

output
bash
[NOTICE] 324/184322 (3330) : New program 'echo' (3351) forked
[NOTICE] 324/184322 (3330) : New worker #1 (3352) forked
systemd[1]: Started Load Balancer.
Hello, World!
[ALERT] 324/184322 (3330) : Current program 'echo' (3351) exited with code 0 (Exit)
output
bash
[NOTICE] 324/184322 (3330) : New program 'echo' (3351) forked
[NOTICE] 324/184322 (3330) : New worker #1 (3352) forked
systemd[1]: Started Load Balancer.
Hello, World!
[ALERT] 324/184322 (3330) : Current program 'echo' (3351) exited with code 0 (Exit)

Example Jump to heading

A common way to use this feature is to start long-running programs that augment the load balancer functionality; therefore, it makes sense to tie them to the lifetime of the load balancer’s process. For example, you can start Stream Processing Offload Agent programs such as the Traffic Mirror agent:

haproxy
global
master-worker
program mirror
command spoa-mirror --runtime 0 --mirror-url http://test.local
haproxy
global
master-worker
program mirror
command spoa-mirror --runtime 0 --mirror-url http://test.local

Note that all flags that follow the program’s name are passed directly to the program.

Add a user and group Jump to heading

You can also specify a user and group to use when executing the command:

haproxy
global
master-worker
program mirror
command spoa-mirror --runtime 0 --mirror-url http://test.local
user oca
group users
haproxy
global
master-worker
program mirror
command spoa-mirror --runtime 0 --mirror-url http://test.local
user oca
group users

Disable program restarts Jump to heading

By default, the load balancer stops and recreates child programs at reload. To disable this, add the no option start-on-reload directive to a program section:

haproxy
global
master-worker
program mirror
command spoa-mirror --runtime 0 --mirror-url http://test.local
user oca
group users
no option start-on-reload
haproxy
global
master-worker
program mirror
command spoa-mirror --runtime 0 --mirror-url http://test.local
user oca
group users
no option start-on-reload

See also Jump to heading

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