HAProxy ALOHA Documentation 13.5

Agent Checks

An agent check is one where HAProxy ALOHA connects to an agent program running on a backend server. In response to the agent check probe, the agent program sends back a string of ASCII text that triggers a change in the load balancer. The change could be:

  • put the server into the down state

  • put the server into the up state

  • put the server into maintenance mode

  • take the server out of maintenance mode

  • change the server's weight

  • change the server's maxconn setting

Create an agent program

An agent program can be written in any programming language, as long as it allows you to listen on a TCP port. When the program detects that HAProxy ALOHA has connected, it should return a string of ASCII text that makes a change to the load balancer or keeps it at its current state.

The program can send back any of the following commands:

Example text

Effect on the load balancer


Marks the server as down.


Marks the server as up.


Puts the server into maintenance mode.


Takes the server out of maintenance mode.


Changes the server's weight to half its current value.


Changes the server's maxconn value to 30.

Below is n program written in the Go programming language. It returns the string 50%\n if the server's CPU idle time is less than 10, which would indicate it is near to maxing out its CPU. Otherwise, it returns the string 100%\n. Notice that the string should end with a line feed character (\n):

package main

import (

func main() {
    server := tcp_server.New(":9999")

    server.OnNewClient(func(c *tcp_server.Client) {
        fmt.Println("Client connected")
        cpuIdle, err := getIdleTime()

        if err != nil {

        if cpuIdle < 10 {
            // Set server weight to half
        } else {



func getIdleTime() (float64, error) {
    before, err := cpu.Get()
    if err != nil {
        return 0, err
    time.Sleep(time.Duration(1) * time.Second)
    after, err := cpu.Get()
    if err != nil {
        return 0, err
    total := float64(after.Total - before.Total)
    cpuIdle := float64(after.Idle-before.Idle) / total * 100
    return cpuIdle, nil

Configure the servers

Configure your servers to send agent checks.

HAProxy ALOHA sends an agent-based check probe every five seconds to a program listening at at port 8080.

backend servers
   server server1 check  weight 100  agent-check  agent-addr  agent-port 8080  agent-inter 5s  agent-send ping\n

Use the following parameters on each server line to enable agent-based checks:




Enables agent-based system checking.


Enables agent checks for the server.


Identifies the IP address where the agent is listening.


Identifies the port where the agent is listening.


Defines the interval between checks.


A string that HAProxy ALOHA sends to the agent upon connection. Be sure to end it with a newline character.

Next up