Reference

show servers state

Get a block of data that represents the current state of servers in backends. Use this to store the state in a state file on the filesystem.

Description Jump to heading

This command returns the state of the servers defined in the running load balancer. You would store this data in a file known as a state file, which the load balancer will read during a process reload, ensuring that the state is preserved and reapplied.

Storing server state preserves the servers’ IP addresses, weights, and drain or maintenance mode.

Examples Jump to heading

You can store either one large file that contains the state of all backends or separate files for each backend, depending on how you set the load-server-state-from-file directive.

For these examples, assume we have the following backend sections defined in the configuration:

haproxy
backend webservers
server s1 127.0.0.1:8080 check weight 100
backend apiservers
server s2 127.0.0.1:8081 check weight 100
haproxy
backend webservers
server s1 127.0.0.1:8080 check weight 100
backend apiservers
server s2 127.0.0.1:8081 check weight 100

Store all server states in a single file Jump to heading

Follow these steps to store the state for all backends in a single file.

  1. In your configuration file, add a server-state-file directive to the global section.

    This indicates the name of the file that holds the current state of your servers.

    haproxy
    global
    server-state-file /tmp/my-state-file
    haproxy
    global
    server-state-file /tmp/my-state-file
  2. In a defaults section, set the load-server-state-from-file directive to global, which indicates that the load balancer should load the contents from the file pointed at by the server-state-file directive.

    haproxy
    defaults
    load-server-state-from-file global
    haproxy
    defaults
    load-server-state-from-file global
  3. Edit the load balancer service file.

    • Call sudo systemctl edit --full hapee-2.9-lb, which opens a text editor.
    • Add a new ExecReload line that calls the show servers state Runtime API command. It must be placed before any calls to /bin/kill:
    nix
    [Service]
    Environment="CONFIG=/etc/hapee-2.9/hapee-lb.cfg" "PIDFILE=/run/hapee-2.9-lb.pid"
    EnvironmentFile=/etc/default/hapee-2.9-lb
    ExecStart=/opt/hapee-2.9/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
    ExecReload=/opt/hapee-2.9/sbin/hapee-lb -c -f $CONFIG
    ExecReload=/bin/sh -c 'echo "show servers state" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock > /tmp/my-state-file'
    ExecReload=/bin/kill -USR2 $MAINPID
    KillMode=mixed
    Type=notify
    nix
    [Service]
    Environment="CONFIG=/etc/hapee-2.9/hapee-lb.cfg" "PIDFILE=/run/hapee-2.9-lb.pid"
    EnvironmentFile=/etc/default/hapee-2.9-lb
    ExecStart=/opt/hapee-2.9/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
    ExecReload=/opt/hapee-2.9/sbin/hapee-lb -c -f $CONFIG
    ExecReload=/bin/sh -c 'echo "show servers state" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock > /tmp/my-state-file'
    ExecReload=/bin/kill -USR2 $MAINPID
    KillMode=mixed
    Type=notify
  4. Reload the Systemd unit file and restart the load balancer service:

    nix
    sudo systemctl daemon-reload
    sudo systemctl restart hapee-2.9-lb
    nix
    sudo systemctl daemon-reload
    sudo systemctl restart hapee-2.9-lb
  5. Try changing the weight of a server and then reload the service. Check that the weight was preserved:

    nix
    echo "set weight webservers/s1 50" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "set weight webservers/s1 50" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    sudo systemctl reload hapee-2.9-lb
    nix
    sudo systemctl reload hapee-2.9-lb
    nix
    echo "get weight webservers/s1" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "get weight webservers/s1" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    text
    50 (initial 100)
    output
    text
    50 (initial 100)

Store server states in separate files Jump to heading

Follow these steps to store the state for each backend separately.

  1. In your configuration file, add a server-state-base directive to the global section.

    This indicates the path to the directory where state files will be stored.

    haproxy
    global
    server-state-base /tmp/
    haproxy
    global
    server-state-base /tmp/
  2. In a defaults section, set the load-server-state-from-file directive to local, which indicates that the load balancer should load files from the directory pointed at by the server-state-base directive.

    The files should have the same name as each backend.

    haproxy
    defaults
    load-server-state-from-file local
    haproxy
    defaults
    load-server-state-from-file local
  3. Edit the load balancer service file.

    • Call sudo systemctl edit --full hapee-2.9-lb, which opens a text editor.
    • Add a new ExecReload line that calls the show servers state Runtime API command for each backend for which you want to store state. All of these lines must be placed before any calls to /bin/kill.

    In the example below, we store two state files: /tmp/webservers and /tmp/apiservers:

    nix
    [Service]
    Environment="CONFIG=/etc/hapee-2.9/hapee-lb.cfg" "PIDFILE=/run/hapee-2.9-lb.pid"
    EnvironmentFile=/etc/default/hapee-2.9-lb
    ExecStart=/opt/hapee-2.9/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
    ExecReload=/opt/hapee-2.9/sbin/hapee-lb -c -f $CONFIG
    ExecReload=/bin/sh -c 'echo "show servers state webservers" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock > /tmp/webservers'
    ExecReload=/bin/sh -c 'echo "show servers state apiservers" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock > /tmp/apiservers'
    ExecReload=/bin/kill -USR2 $MAINPID
    KillMode=mixed
    Type=notify
    nix
    [Service]
    Environment="CONFIG=/etc/hapee-2.9/hapee-lb.cfg" "PIDFILE=/run/hapee-2.9-lb.pid"
    EnvironmentFile=/etc/default/hapee-2.9-lb
    ExecStart=/opt/hapee-2.9/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
    ExecReload=/opt/hapee-2.9/sbin/hapee-lb -c -f $CONFIG
    ExecReload=/bin/sh -c 'echo "show servers state webservers" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock > /tmp/webservers'
    ExecReload=/bin/sh -c 'echo "show servers state apiservers" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock > /tmp/apiservers'
    ExecReload=/bin/kill -USR2 $MAINPID
    KillMode=mixed
    Type=notify
  4. Reload the Systemd unit file and restart the load balancer service:

    nix
    sudo systemctl daemon-reload
    nix
    sudo systemctl daemon-reload
    nix
    sudo systemctl restart hapee-2.9-lb
    nix
    sudo systemctl restart hapee-2.9-lb
  5. Try changing the weight of a server and then reload the service. Check that the weight was preserved:

    nix
    echo "set weight webservers/s1 50" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "set weight webservers/s1 50" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    sudo systemctl reload hapee-2.9-lb
    nix
    sudo systemctl reload hapee-2.9-lb
    nix
    echo "get weight webservers/s1" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "get weight webservers/s1" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    text
    50 (initial 100)
    output
    text
    50 (initial 100)
  6. Optional: Set the server-state-file-name directive in a backend to change the filename used to store state for that backend.

    In the example below, the file would normally be named webservers, but is changed to webservers-state. You must update the show servers state command to reflect this.

    haproxy
    backend webservers
    server-state-file-name webservers-state
    haproxy
    backend webservers
    server-state-file-name webservers-state

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?