HAProxy Enterprise Documentation 13.0

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.

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

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
    • 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
  2. In the HAProxy ALOHA WUI, select the Tools tab, then upload your map files in /etc/haproxy/extra/ through the File Manager.

    https://cdn.haproxy.com/documentation/aloha/latest/assets/upload-map-file-84fd07874c0faf71073031dac739d48cf4965386d8bfab2f93fc3103522c8c4d.png
  3. 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
  4. Use your map files through map converters in frontend or backend 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)]

    Note

    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.

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

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

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

    https://cdn.haproxy.com/documentation/aloha/latest/assets/dynamic-updates-log-94d8a899a515c7c69cc907e458a0ee927a8dc179c4e66f174c44d017b7514abd.png

Check the update status through the CLI

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

admin@ALOHA1:~$ 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 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:

lb-update force-update <id>

Forces the update of the specified <id> (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

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.

Note

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

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 or acl 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

<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

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

<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

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

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-tlsv12

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.


Next up

High Availability