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-3.0-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-3.0/hapee-lb.cfg" "PIDFILE=/run/hapee-3.0-lb.pid"
   EnvironmentFile=/etc/default/hapee-3.0-lb
   ExecStart=/opt/hapee-3.0/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
   ExecReload=/opt/hapee-3.0/sbin/hapee-lb -c -f $CONFIG
   ExecReload=/bin/sh -c 'echo "show servers state" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock > /tmp/my-state-file'
   ExecReload=/bin/kill -USR2 $MAINPID
   KillMode=mixed
   Type=notify

   nix
   [Service]
   Environment="CONFIG=/etc/hapee-3.0/hapee-lb.cfg" "PIDFILE=/run/hapee-3.0-lb.pid"
   EnvironmentFile=/etc/default/hapee-3.0-lb
   ExecStart=/opt/hapee-3.0/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
   ExecReload=/opt/hapee-3.0/sbin/hapee-lb -c -f $CONFIG
   ExecReload=/bin/sh -c 'echo "show servers state" | sudo socat stdio unix-connect:/var/run/hapee-3.0/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-3.0-lb

   nix
   sudo systemctl daemon-reload
   sudo systemctl restart hapee-3.0-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-3.0-lb

   nix
   sudo systemctl reload hapee-3.0-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-3.0-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-3.0/hapee-lb.cfg" "PIDFILE=/run/hapee-3.0-lb.pid"
   EnvironmentFile=/etc/default/hapee-3.0-lb
   ExecStart=/opt/hapee-3.0/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
   ExecReload=/opt/hapee-3.0/sbin/hapee-lb -c -f $CONFIG
   ExecReload=/bin/sh -c 'echo "show servers state webservers" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock > /tmp/webservers'
   ExecReload=/bin/sh -c 'echo "show servers state apiservers" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock > /tmp/apiservers'
   ExecReload=/bin/kill -USR2 $MAINPID
   KillMode=mixed
   Type=notify

   nix
   [Service]
   Environment="CONFIG=/etc/hapee-3.0/hapee-lb.cfg" "PIDFILE=/run/hapee-3.0-lb.pid"
   EnvironmentFile=/etc/default/hapee-3.0-lb
   ExecStart=/opt/hapee-3.0/sbin/hapee-lb -Ws -f $CONFIG -p $PIDFILE $OPTIONS
   ExecReload=/opt/hapee-3.0/sbin/hapee-lb -c -f $CONFIG
   ExecReload=/bin/sh -c 'echo "show servers state webservers" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock > /tmp/webservers'
   ExecReload=/bin/sh -c 'echo "show servers state apiservers" | sudo socat stdio unix-connect:/var/run/hapee-3.0/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-3.0-lb

   nix
   sudo systemctl restart hapee-3.0-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-3.0-lb

   nix
   sudo systemctl reload hapee-3.0-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 #

• get weight
• set weight