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
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.
-
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
-
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
-
-
In the HAProxy ALOHA web UI, select the Tools tab, then upload your map files in /etc/haproxy/extra/ through the File Manager.
-
To load the Update module, select the LB Layer 7 tab, then add the following line to the
global
section.global module-load update.so
-
Use your map files through
map
converters infrontend
orbackend
sections.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)]
-
Create a
dynamic-update
section.Specify the paths to the local map files as the
id
.dynamic-update update id
/etc/haproxy/extra/forbid.mapurlhttp://15.236.163.114/forbid.map delay 1m timeout 5s retries 3 map logupdate id/etc/haproxy/extra/routes.mapurlhttp://15.236.163.114/routes.map xdelay 1m 1m 100ms 5m timeout 5s retries 3 map logWe won't include the
dontlog-normal
directive so that we can check in the logs that the files are correctly updated. -
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.
-
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 HAProxy ALOHA.
-
Check in the Logs tab that the files were successfully updated.
Check the update status through the CLI
If you can access the instance through SSH, or click Launch a terminal in the web UI's Tools tab, you can also run the following CLI command.
$ echo lb-update status | sudo socat stdio /var/run/haproxy.stat
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 |
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 |
|
use modified | Whether the time from the |
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:
- lb-update force-update <id>
-
Forces the update of the specified <id> (id is what you specified on the
upload
line after theid
parameter in the configuration). - lb-update list
-
Lists configured entries.
How the Update module works
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.
Update module directive syntax
The Update configuration section, dynamic-update
, can contain one or several update
directives.
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
id
<id>
Value
Description
<id>
Name of the file initially loaded from
map
oracl
directives.Uses an absolute path.
url
<url>
Value
Description
<url>
Endpoint from which to download updates.
Optional parameters
delay
<delay>
Download interval.
Value
Description
Default
Minimum
<delay>
Specifies the period between each attempt to download new data.
5m
1ms
xdelay
<delay start next retry>
Value | Description | Default | Minimum |
---|---|---|---|
| Specifies the period between each attempt to download new data. | 5m | 1ms |
| First download delay. | 10s | 100ms |
| This parameter is ignored, but mandatory (it is only kept for compatibility with other parameters). | 10s | 100ms |
| Sets the delay before the next attempt after a download has failed. Attempts to download 3 times, then waits until | 5s | 100ms |
modified
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
<addr>[:<port>]
Sets the source address for outgoing connections.
Value | Description | Default | Requiredness |
---|---|---|---|
| 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 number. May be useful in some very specific contexts. Port ranges are not supported. | 0 HAProxy ALOHA will select a free port. | Optional |
map
Reads the downloaded file as a map file. By default, HAProxy ALOHA reads the file as an ACL file.
tls-ticket-keys
Reads the downloaded file as a TLS ticket keys file. By default, HAProxy ALOHA reads the file as an ACL file.
timeout
<tmout>
Value
Description
Default
<tmout>
Connection timeout to the download server.
5s
retries
<nb>
Value
Description
<nb>
Number of times the Update module will try to connect to the download server.
log
Logs errors.
dontlog-normal
Does not log successful updates.
param*
A list of TLS server
parameters.
Optional TLS server
parameters
You can also specify additional HAProxy ALOHA configuration parameters available for the server
directive.
Parameter | Description |
---|---|
| Sets the string describing the list of cipher algorithms to negotiate during the SSL/TLS handshake with the server. |
| Designates a PEM file containing both the required certificates and any associated private keys. |
| Enforces SSLv3 only on SSL connections instantiated from this listener. |
| Enforces TLSv1.0 only on SSL connections instantiated from this listener. |
| Enforces TLSv1.1 only on SSL connections instantiated from this listener. |
| Enforces TLSv1.2 only on SSL connections instantiated from this listener. |
| Disables support for SSLv3 on any sockets instantiated from the listener when SSL is supported. |
| Disables support for TLSv1.0 on any sockets instantiated from the listener when SSL is supported. |
| Disables support for TLSv1.1 on any sockets instantiated from the listener when SSL is supported. |
| Disables support for TLSv1.2 on any sockets instantiated from the listener when SSL is supported. |
| Disables stateless session resumption (RFC 5077 TLS Ticket extension) and enforces stateful session resumption. |
|
|
| Only takes effect if you set
|
Next up
Network