Administration

Dynamic data updates

On this page

Available since

  • HAProxy ALOHA 13.0

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.

Important

  • Static files are not updated.
  • When you reload HAProxy ALOHA, it will run an outdated version of the static files until their contents are updated in memory. You then might consider updating static files or using the xdelay parameter to update files almost immediately (after 100ms, for example).

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 /forbiden.html
0.0.0.0        /deny.html
      10.0.0.0/8     /maintenance.html
192.168.0.0/16 /forbiden.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.

    upload map file

  3. To load the Update module, select the LB Layer7 tab. Then add the following line to the global section.

    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. Click OK and then Apply to save the changes.

  7. In the Setup tab, click Save under Local Configuration to persist your changes after a reboot.

  8. 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.

  9. 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.

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

    dynamic updates log

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:

Available since

Since HAProxy ALOHA version 13.5 you can also access the instance via Launch a terminal in the web UI’s Tools tab.

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
  url:                http://15.236.163.114/forbid.map
  http status count:  0 17 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
SMP update
  configuration:      /var/state/haproxy.run:6
  entry:              /etc/haproxy/extra/routes.map
  url:                http://15.236.163.114/routes.map
  http status count:  0 16 0 0 0
  period/delay:       1m / 1m 0.100s 5m
  use modified:       no
  reload/retry count: 16 0 0 / 0 0
  reload time:        2021-09-09 10:53:06 / <NEVER> / <NEVER>
  download time:      2021-09-09 10:53:06 / <NEVER>
  next update in:     48s
output
text
lb-update module status
------------------------------------------------------------------------------
initialized:          yes
SMP update
  configuration:      /var/state/haproxy.run:5
  entry:              /etc/haproxy/extra/forbid.map
  url:                http://15.236.163.114/forbid.map
  http status count:  0 17 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
SMP update
  configuration:      /var/state/haproxy.run:6
  entry:              /etc/haproxy/extra/routes.map
  url:                http://15.236.163.114/routes.map
  http status count:  0 16 0 0 0
  period/delay:       1m / 1m 0.100s 5m
  use modified:       no
  reload/retry count: 16 0 0 / 0 0
  reload time:        2021-09-09 10:53:06 / <NEVER> / <NEVER>
  download time:      2021-09-09 10:53:06 / <NEVER>
  next update in:     48s

Description of the lb-update status output.

Value Description
initialized Whether the module was initialized.
configuration Configuration file and line number in which the update item is specified.
entry Item update ID (what is specified after the id parameter in the configuration).
url The item download URL. HTTP and HTTPS are supported.
http status count The download HTTP status code, sorted by status classes 1xx 2xx 3xx 4xx, and 5xx.
period The download period.
delay delay, start, next, and retry values.
use modified Whether the time from the Last-Modified response HTTP header was used to update the data using the If-Modified-Since request HTTP header.
reload count The number of times the update occurred, did not occur because the data did not differ from the current data, or failed because the data was incorrect.
retry count The number of unsuccessful downloads and the number of final unsuccessful downloads. For example, if each download is attempted 3 times (the first number), and if that fails, then the second number is increased by 1. After that, the subsequent download attempt is aborted for the respective cycle and the next attempt starts at the next cycle.
reload time The last time the update occurred, did not occur because the data did not differ from the current data, or failed because the data was incorrect.
next update in Delay before the next download or information about the current download.

Other available CLI commands are as follows:

Command Description
lb-update force-update <id> Forces the update of the specified (<id> is what you specified on the upload line after the id parameter in the configuration).
lb-update list Lists configured entries.

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 module directive syntax Jump to heading

The Update 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] [source <addr>[:<port>]] [log] [dontlog-normal] [map] [tls-ticket-keys] [param*]
haproxy
update id <id> url <url> [delay <delay> | xdelay <delay start next retry>] [timeout <tmout>] [retries <nb>] [modified] [source <addr>[:<port>]] [log] [dontlog-normal] [map] [tls-ticket-keys] [param*]

Required parameters Jump to heading

id Jump to heading

id <id>

Value Description
<id> Name of the file initially loaded from map or acl directives. Uses an absolute path.

url Jump to heading

url <url>

Value Description
<url> Endpoint from which to download updates.

Optional parameters Jump to heading

delay Jump to heading

delay <delay>

Value Description Default Minimum
<delay> Specifies the period between each attempt to download new data. 5m 1ms

xdelay Jump to heading

xdelay <delay start next retry>

Value Description Default Minimum
<delay> Specifies the period between each attempt to download new data. 5m 1ms
<start> First download delay. 10s 100ms
<next> This parameter is ignored, but mandatory (it is only kept for compatibility with other parameters). 10s 100ms
<retry> Sets the delay before the next attempt after a download has failed. Attempts to download 3 times, then waits until <delay> has elapsed. 5s 100ms

modified Jump to heading

Uses the Last-Modified field from the HTTP header in the response to check whether or not to update data based on the If-Modified-Since request HTTP header value.

source Jump to heading

source <addr>[:<port]

Value Description Default Requiredness
<addr> IPv4 address HAProxy ALOHA will bind to before connecting to a server. 0.0.0.0. HAProxy ALOHA will select the most appropriate address to reach its destination. Mandatory
<port> Port number. May be useful in some very specific contexts. Port ranges are not supported. 0. HAProxy ALOHA will select a free port. Optional

map Jump to heading

Reads the downloaded file as a map file. By default, HAProxy ALOHA reads the file as an ACL file.

tls-ticket-keys Jump to heading

Reads the downloaded file as a TLS ticket keys file. By default, HAProxy ALOHA reads the file as an ACL file.

timeout Jump to heading

timeout <tmout>

Value Description Default
<tmout> Connection timeout to the download server. 5s

retries Jump to heading

retries <nb>

Value Description
<nb> Number of times the Update module will try to connect to the download server.

log Jump to heading

Logs errors.

dontlog-normal Jump to heading

Does not log successful updates.

param* Jump to heading

A list of TLS server parameters.

Optional TLS server parameters Jump to heading

You can also specify additional HAProxy ALOHA configuration parameters available for the server directive.

Value Description
ciphers Sets the string describing the list of cipher algorithms to negotiate during the SSL/TLS handshake with the server.
crt Designates a PEM file containing both the required certificates and any associated private keys.
force-sslv3 Enforces SSLv3 only on SSL connections instantiated from this listener.
force-tlsv10 Enforces TLSv1.0 only on SSL connections instantiated from this listener.
force-tlsv11 Enforces TLSv1.1 only on SSL connections instantiated from this listener.
force-tslv12 Enforces TLSv1.2 only on SSL connections instantiated from this listener.
no-sslv3 Disables support for SSLv3 on any sockets instantiated from the listener when SSL is supported.
no-tlsv10 Disables support for TLSv1.0 on any sockets instantiated from the listener when SSL is supported.
no-tlsv11 Disables support for TLSv1.1 on any sockets instantiated from the listener when SSL is supported.
no-tlsv12 Disables support for TLSv1.2 on any sockets instantiated from the listener when SSL is supported.
no-tls-tickets Disables stateless session resumption (RFC 5077 TLS Ticket extension) and enforces stateful session resumption.
verify If set to none, HAProxy ALOHA does not request the client certificate (default). In other cases, a client certificate is requested. If set to required and the client does not provide a certificate after the request, HAProxy ALOHA aborts the handshake; it would succeed only if the parameter is set to optional.
verifyhost Only takes effect if you set verify to required. When set, HAProxy ALOHA checks the hostnames in the subject and subjectAlternateNames fields of the certificate provided by the server. If none of the hostnames in the certificate match the specified hostname, HAProxy ALOHA aborts the handshake. The hostnames in the server-provided certificate may include wildcards. Not supported in default-server directives.

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

Previous page Administration Next page Factory reset
© 2024 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences