add backend

Add a dynamic backend.

You can add, publish, unpublish, and delete dynamic backends at runtime without performing a reload.

To ensure that named defaults sections are available to dynamic backends, they’re kept in memory. If you don’t use dynamic backends, you can save memory by disabling this feature. To purge defaults sections from memory, set the global directive tune.defaults.purge.

This command requires a CLI level of admin. Note that this operation is supported only on a CLI connection running in experimental mode (experimental-mode on). This operation is still in development and may change in the future.

Description Jump to heading #

A backend inherits its settings from the defaults section specified with the from argument (for example, backend mybackend from mydefaults). If the defaults section doesn’t specify a mode, set one using the mode argument. The add backend command only adds the backend to the load balancer’s runtime memory and not to the load balancer configuration saved on disk.

Initially, the backend is unavailable to receive traffic. To make it available for traffic, use publish backend. Add servers to the backend using add server. If a server is configured for health checks, the health checks are active as soon as the server is added to the backend, even if the backend hasn’t yet been published.

If you target a backend with the default_backend or use_backend directive in a frontend and then you disable or unpublish that backend, it’ll be skipped as a default backend. However, you can force the load balancer to use the backend if you set the force-be-switch directive.

Examples Jump to heading #

In this example, we add a dynamic backend named mybackend1 using defaults from section mydefaults.

Here’s the defaults section mydefaults:

haproxy
defaults mydefaults
  timeout http-request 5s
  timeout connect 5s                                                                                                                                                                          timeout client 30s                                                                                                                                                                          timeout server 10s

haproxy
defaults mydefaults
  timeout http-request 5s
  timeout connect 5s                                                                                                                                                                          timeout client 30s                                                                                                                                                                          timeout server 10s

The defaults section doesn’t specify the mode, so we include the mode argument in the add backend command. Be sure to turn on experimental mode.

nix
echo "experimental-mode on; add backend mybackend1 mode http from mydefaults" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "experimental-mode on; add backend mybackend1 mode http from mydefaults" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

output
text
New backend registered.

output
text
New backend registered.

Here’s the resulting backend:

haproxy
backend mybackend1 from mydefaults
  mode http

haproxy
backend mybackend1 from mydefaults
  mode http

Add a backend, server, and map file entry Jump to heading #

In the following example, we add a backend, a server, and a map file entry that directs traffic to the new backend. Then we publish the backend so it becomes available for use in the load balancer. For a tutorial on map files, see Map files.

Before we make any changes, our example load balancer configuration starts off like this:

• In the global section, we enable the HAProxy Runtime API at port 9999.
• There’s a defaults section named mydefaults.
• There’s a frontend named myfrontend1.
• The use_backend directive reads a map file to determine the correct backend to use based on the requested URL path. The map file is virtual, meaning it exists in memory, and starts off empty.
• If there isn’t a match in the map file for the requested URL path, the default_backend directive targets traffic to the backend named webservers.

Here’s the configuration file:

haproxy
global
  stats socket ipv4@127.0.0.1:9999 level admin
defaults mydefaults
  log global
  mode http
  option httplog
  option dontlognull
  timeout connect 10m
  timeout client  10m
  timeout server  10m
frontend myfrontend1
  bind :80
  use_backend %[path,map_beg(virt@paths.map)]
  default_backend webservers
 
backend webservers
  server web1 127.0.0.1:8080

haproxy
global
  stats socket ipv4@127.0.0.1:9999 level admin
defaults mydefaults
  log global
  mode http
  option httplog
  option dontlognull
  timeout connect 10m
  timeout client  10m
  timeout server  10m
frontend myfrontend1
  bind :80
  use_backend %[path,map_beg(virt@paths.map)]
  default_backend webservers
 
backend webservers
  server web1 127.0.0.1:8080

To add our dynamic backend and make the other changes, follow these steps:

1. Add a dynamic backend using the add backend command. The backend is named mybackend1 and uses defaults from section mydefaults.

   nix
   echo "experimental-mode on; add backend mybackend1 from mydefaults" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "experimental-mode on; add backend mybackend1 from mydefaults" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

2. Add a server using the add server command.

   nix
   echo "add server mybackend1/web1 172.16.0.12:8080 check port 8080" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "add server mybackend1/web1 172.16.0.12:8080 check port 8080" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

3. Enable the server using the enable server command.

   nix
   echo "enable server mybackend1/web1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "enable server mybackend1/web1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

4. Enable health checks for the server using the enable health command.

   nix
   echo "enable health mybackend1/web1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "enable health mybackend1/web1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

5. Make the backend available for traffic using the publish backend command.

   nix
   echo "publish backend mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "publish backend mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

6. Add an entry to the map file.

   nix
   echo "add map virt@paths.map /test mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "add map virt@paths.map /test mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

The backend is available to accept traffic, and the map file has been updated with an entry that routes requests for the URL path /test to the new backend. Note that both the dynamic backend and the virtual map file reside only in memory in the running load balancer process. They do not exist in the configuration file on disk.

Delete backend, server, and map file entry Jump to heading #

In the following example, we delete the server, backend, and map entry. Use these commands:

1. Put the server into maintenance mode. This command marks the server as “DOWN” for maintenance. The load balancer stops sending checks to this server while it’s in this state.

   nix
   echo "set server mybackend1/web1 state maint" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "set server mybackend1/web1 state maint" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

2. Wait for the server to be removable and then remove it. A server is removable when it no longer has any active or idle connections.

   nix
   echo "wait 2s srv-removable mybackend1/web1; del server mybackend1/web1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "wait 2s srv-removable mybackend1/web1; del server mybackend1/web1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

3. Unpublish the backend.

   nix
   echo "unpublish backend mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "unpublish backend mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

4. Wait for the backend to be removable and then delete it.

   nix
   echo "experimental-mode on; wait 2s be-removable mybackend1; del backend mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "experimental-mode on; wait 2s be-removable mybackend1; del backend mybackend1" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

5. Delete the map file entry.

   nix
   echo "del map virt@paths.map /test" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "del map virt@paths.map /test" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

See also Jump to heading #

• del backend
• del map
• del server
• experimental mode
• publish backend
• set server
• unpublish backend
• wait
• To target a specific backend, see Use conditionals to forward traffic to different backends.
• To direct traffic to a backend even when disabled or unpublished, use the force-be-switch directive.
• If you don’t use dynamic backends, consider setting tune.defaults.purge.