Programs

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
text
[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
text
[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 #

• For complete details on the program section, see the Programs reference.