Reference

set server

On this page

Change a server’s properties.

Description Jump to heading

Use the set server command to change the following properties of a backend server:

Server property Parameter Note
Ready / drain / maintenance state state
IP address (IPv4 or IPv6) addr [port] Use addr (without specifying a port) prior to version 2.4r1.
FQDN fqdn
Weight weight
Health status health
Health check agent status agent
Change the IP address used for server health checks. Optionally change the port. check-addr [port] Available since version 2.4r1.
Port where health check probes are sent check-port
IP address where the health check agent is listening. Optionally change the port. agent-addr [port] Use agent-addr (without specifying a port) prior to version 2.4r1.
Port where the health check agent is listening agent-port Available since version 2.4r1.
Configure SSL on the server. Health check path is not changed by SSL mode. ssl (Deprecated after version 2.5r1. Instead use add-server to create a dynamic server having the desired parameters.)
String that the load-balancer sends to the agent during each health check agent-send

Examples Jump to heading

Following are examples of using the set server command.

Change a server’s state Jump to heading

Use the following state parameters, depending on your goals:

Receive traffic Perform health checks state parameter
Yes Yes ready
No Yes drain
No No maint

Below, we set the server’s state to drain:

nix
echo "set server webservers/s1 state drain" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 state drain" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Change a server’s address and port Jump to heading

Below, we use the addr parameter to change the s1 server’s IP address to 127.0.0.1:

nix
echo "set server webservers/s1 addr 127.0.0.1" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 addr 127.0.0.1" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Below, we change the server’s IP address to 127.0.0.1 and its port to 8081:

nix
echo "set server webservers/s1 addr 127.0.0.1 port 8081" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 addr 127.0.0.1 port 8081" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Change a server’s FQDN Jump to heading

Suppose you’ve specified a fully qualified domain name (FQDN) for the server instead of an IP address, and you’ve added a resolvers parameter to use a resolvers section, as shown below:

haproxy
resolvers mydns
  nameserver dns1 192.168.50.30:53
  accepted_payload_size 8192
backend webservers
  server s1 s1.example.com:8080 check resolvers mydns
haproxy
resolvers mydns
  nameserver dns1 192.168.50.30:53
  accepted_payload_size 8192
backend webservers
  server s1 s1.example.com:8080 check resolvers mydns

You can use the fqdn parameter to change the server’s domain name dynamically:

nix
echo "set server webservers/s1 fqdn s1.example.local" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 fqdn s1.example.local" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Change a server’s weight Jump to heading

The weight parameter changes a server’s weight. The value can be a percentage or an exact number. In the example below, we set the server’s weight to 50% of its current value:

nix
echo "set server webservers/s1 weight 50%" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 weight 50%" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Change active health checks Jump to heading

Use the following health parameters, depending on your goals:

Goal health parameter
Take the server out of the load-balancing rotation. down
Add the server back into the load-balancing rotation. up
Drain traffic. stopping

In the next example, the health parameter sets the server’s health status to down, which takes it out of the load-balancing rotation.

nix
echo "set server webservers/s1 health down" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 health down" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

The check-port parameter changes the port where health check probes are sent:

nix
echo "set server webservers/s1 check-port 8080" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 check-port 8080" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Change agent health checks Jump to heading

In the example below, the agent parameter sets the server’s agent to a new state. You can set either up or down:

nix
echo "set server webservers/s1 agent down" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 agent down" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

The agent-addr parameter changes the IP address where the agent is listening:

nix
echo "set server webservers/s1 agent-addr 192.168.0.11" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 agent-addr 192.168.0.11" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

As of version 2.4r1, optionally, you can append the port parameter to agent-addr to specify a new port for the agent.

nix
echo "set server webservers/s1 agent-port 49999" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 agent-port 49999" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

You can also change the agent port without using the agent-addr parameter by just using the agent-port parameter by itself:

The check-addr parameter changes the IP address used for server health checks. Optionally, add the port parameter to change the port.

nix
echo "set server webservers/s1 check-addr 192.168.0.12 port 49999\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 check-addr 192.168.0.12 port 49999\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

The agent-send parameter changes the string that the load balancer sends to the agent during each health check:

nix
echo "set server webservers/s1 agent-send ping\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 agent-send ping\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Change SSL Jump to heading

Turn SSL ciphering on or off for outgoing server connections (as of version 2.4r1):

nix
echo "set server webservers/s1 ssl on\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "set server webservers/s1 ssl on\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

See also Jump to heading

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

Previous page set rate-limit ssl-sessions global Next page set severity-output
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences