publish backend

Make a dynamic backend available for use.

Description Jump to heading #

Make the specified backend available to receive traffic. This command requires a CLI level of operator or admin.

Examples Jump to heading #

In this example, we make a backend available for traffic:

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

output
text
Backend published.

output
text
Backend published.

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
• set server
• unpublish backend
• wait