Reference

del backend

On this page

Available since

  • HAProxy 3.4

Delete a dynamic backend.

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

This operation is allowed only for TCP and HTTP proxies.

Resolve the following issues before attempting to delete a backend:

  • You can’t remove a backend if it is explicitly referenced by configuration elements such as use_backend or in sample expressions.
  • Some proxy options are incompatible with runtime deletion, for example, the deprecated dispatch or option transparent.
  • You can’t remove a backend if there is a stick-table declared in it.
  • You can’t remove a backend if QUIC servers are present in it.
  • Wait for streams to disconnect before deleting the backend. To display details for a stream, use the show sess command.

Follow these steps before deleting a backend:

  • Use the wait (wait be-removable) command to ensure the prerequisites above are satisfied. The be-removable condition for the wait command was added in HAProxy 3.4.
  • Delete servers that use the backend using del server.
  • Unpublish the backend using unpublish backend.

Note that this command only removes it from the load balancer’s runtime memory and not from the configuration file on disk.

Examples Jump to heading

In this example, we precede the del backend command with the wait command to ensure all prerequisites are met before proceeding.

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
output
text
Backend deleted.
output
text
Backend deleted.

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

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

Previous page del acl Next page del map
© 2026 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences