unpublish backend

Make a dynamic backend unavailable for use.

Description Jump to heading #

Marks the specified backend as unqualified for future traffic selection. Any use_backend or default_backend directives that reference it are ignored and the next content switching rules are evaluated. While in the unpublished state, server health checks are active. This command requires a CLI level of operator or admin.

You don’t have to remove servers from the backend before you unpublish it, but if you intend to delete the backend, you will have to delete the servers.

Examples Jump to heading #

In this example, we make a backend unavailable for traffic. We have already removed servers by first putting them in maintenance mode using set server and then deleting them using del server.

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

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 #

• add backend
• del backend
• del map
• del server
• experimental mode
• publish backend
• set server
• 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.