Dynamic data updates

You can regularly update the contents of ACL files, map files, or TLS ticket key files loaded in memory without reloading HAProxy ALOHA thanks to the Update module (lb-update).

At startup, HAProxy ALOHA loads the contents of static files. Then, at a set interval, it downloads updates from a given endpoint. The content of the downloaded files replaces the existing content in memory.

In a cluster, each instance checks for changes independently.

Update the contents of ACL files, map files, or TLS ticket key files Jump to heading #

In this example, we will update two map files every minute. One map file will be updated 100 milliseconds after HAProxy ALOHA starts or reloads, then every minute.

1. Create key/value pair map files with a text editor.

   • Create the file forbid.map, that contains a list of subnets and associated redirections:

     10.0.0.0/8     /maintenance.html
     192.168.0.0/16 /forbidden.html
     0.0.0.0        /deny.html

     10.0.0.0/8     /maintenance.html
     192.168.0.0/16 /forbidden.html
     0.0.0.0        /deny.html

   • Create the file routes.map, that contains a list of domain names and associated HAProxy ALOHA backends:

     www.example.com     webservers
     api.example.com     apiservers
     static.example.com  cacheservers

     www.example.com     webservers
     api.example.com     apiservers
     static.example.com  cacheservers

2. In the HAProxy ALOHA web UI, select the Tools tab. Then upload your map files in /etc/haproxy/extra/ through the File Manager.

   

3. To load the Update module, select the LB Layer7 tab. Then add the following line to the global section. Create the global section if it does not exist.

   HAProxy ALOHA >= 16.5 HAProxy ALOHA <= 16.0

   haproxy
   global
     module-load hapee-lb-update.so

   haproxy
   global
     module-load hapee-lb-update.so

   haproxy
   global
     module-load update.so

   haproxy
   global
     module-load update.so

4. Use your map files through map converters in frontend or backend sections.

   haproxy
   frontend fe_main
     bind *:80
     mode http
     http-request redirect location %[src,map_ip(/etc/haproxy/extra/forbid.map)] if { src,map_ip(/etc/haproxy/extra/forbid.map) -m found }
     use_backend %[req.hdr(host),map(/etc/haproxy/extra/routes.map,webservers)]

   haproxy
   frontend fe_main
     bind *:80
     mode http
     http-request redirect location %[src,map_ip(/etc/haproxy/extra/forbid.map)] if { src,map_ip(/etc/haproxy/extra/forbid.map) -m found }
     use_backend %[req.hdr(host),map(/etc/haproxy/extra/routes.map,webservers)]

   You can access a map file by using the map converter or one of its variants, such as map_ip. Its first argument is the absolute path to the map file. Its second argument sets a default value and is optional.

5. Create a dynamic-update section.

   Specify the paths to the local map files as the id.

   haproxy
   dynamic-update
     update id /etc/haproxy/extra/forbid.map url http://15.236.163.114/forbid.map delay 1m timeout 5s retries 3 map log
     update id /etc/haproxy/extra/routes.map url http://15.236.163.114/routes.map xdelay 1m 1m 100ms 5m timeout 5s retries 3 map log

   haproxy
   dynamic-update
     update id /etc/haproxy/extra/forbid.map url http://15.236.163.114/forbid.map delay 1m timeout 5s retries 3 map log
     update id /etc/haproxy/extra/routes.map url http://15.236.163.114/routes.map xdelay 1m 1m 100ms 5m timeout 5s retries 3 map log

   We won’t include the dontlog-normal directive so that we can check in the logs that the files are correctly updated.

6. Optionally, update a map, ACL, or TLS session ticket from an HTTPS URL. Follow the same steps as for a non-secure endpoint, above, but add the ssl parameter to the update directive.

   haproxy
   dynamic-update
     update id /etc/hapee-3.1/redirects.map map url https://192.168.0.1:80/redirects.map delay 5m ssl

   haproxy
   dynamic-update
     update id /etc/hapee-3.1/redirects.map map url https://192.168.0.1:80/redirects.map delay 5m ssl

7. Click OK and then Apply to save the changes.

8. To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

9. Upload updated versions of your map files to an endpoint through an FTP client or any other means.

   For example, upload your map files to http://15.236.163.114/forbid.map, and http://15.236.163.114/routes.map.

10. Reload the haproxy service from the Services tab.

    In our example, the contents of the static forbid.map and routes.map files will be replaced in memory with the contents of the http://15.236.163.114/forbid.map and http://15.236.163.114/routes.map files, respectively, every minute.

    routes.map is updated 100 milliseconds after you reload HAProxy ALOHA.

11. Check in the Logs tab that the files were successfully updated.

    

Check the update status through the CLI Jump to heading #

If you can access the instance through SSH, you can also run the following CLI command:

nix
echo lb-update status | sudo socat stdio /var/run/haproxy.stat

nix
echo lb-update status | sudo socat stdio /var/run/haproxy.stat

output
text
lb-update module status
------------------------------------------------------------------------------
initialized:          yes
SMP update
  configuration:      /var/state/haproxy.run:5
  entry:              /etc/haproxy/extra/forbid.map
  generation id:      0 1
  count:              3 0 / 3
  url:                http://15.236.163.114/forbid.map
  http status count:  0 17 0 0 0 / 0
  period/delay:       1m / 5s 10s 5s
  use modified:       no
  reload/retry count: 17 0 0 / 0 0
  reload time:        2021-09-09 10:53:11 / <NEVER> / <NEVER>
  download time:      2021-09-09 10:53:11 / <NEVER>
  next update in:     53s

output
text
lb-update module status
------------------------------------------------------------------------------
initialized:          yes
SMP update
  configuration:      /var/state/haproxy.run:5
  entry:              /etc/haproxy/extra/forbid.map
  generation id:      0 1
  count:              3 0 / 3
  url:                http://15.236.163.114/forbid.map
  http status count:  0 17 0 0 0 / 0
  period/delay:       1m / 5s 10s 5s
  use modified:       no
  reload/retry count: 17 0 0 / 0 0
  reload time:        2021-09-09 10:53:11 / <NEVER> / <NEVER>
  download time:      2021-09-09 10:53:11 / <NEVER>
  next update in:     53s

Description of the lb-update status output.

Other available CLI commands are as follows:

How the Update module works Jump to heading #

At startup, HAProxy ALOHA loads the content of map files or ACL files from a designated file.

If there is an update directive set up to update this content, HAProxy ALOHA downloads the new content from a given endpoint after the designated period of time.

• HAProxy ALOHA updates the content of the map files or ACL files only after the file downloads correctly.
• If HAProxy ALOHA cannot connect to the server, it retries the number of times you specify.

The content of the downloaded file replaces the existing content in memory.

Update directive syntax Jump to heading #

The Update module’s configuration section, dynamic-update, can contain one or several update directives.

haproxy
update id <id> url <url> [delay <delay> | xdelay <delay start next retry>] [timeout <tmout>] [retries <nb>] [modified | xmodified ] [source <addr>[:<port>]] [log] [dontlog-normal] [map] [purge <count> [<interval> [<id>]]] [tls-ticket-keys] [param*]

haproxy
update id <id> url <url> [delay <delay> | xdelay <delay start next retry>] [timeout <tmout>] [retries <nb>] [modified | xmodified ] [source <addr>[:<port>]] [log] [dontlog-normal] [map] [purge <count> [<interval> [<id>]]] [tls-ticket-keys] [param*]

The following arguments are required:

The following arguments are optional:

You can also specify additional TLS parameters:

The options checksum and modified are mutually exclusive. If you define them at the same time, the option modified automatically switches off and a warning message prints when the load balancer starts.