The Update module allows HAProxy to update the contents of ACL and map files periodically by polling a URL. At startup, HAProxy loads the map or ACL values from the designated local file. An update directive instructs HAProxy to download new values from the specified URL after a specified delay. This allow multiple load balancers to be kept in sync.

HAProxy updates the content of the map or ACL only if the file was properly downloaded. If HAProxy cannot connect to the server within the timeout period, it retries a configured number of times before quitting.

Note

The contents of the downloaded file replace the existing contents.

Install the Update module

  1. Install the Update module: apt install hapee-1.8r1-lb-update (or yum install depending on your platform of choice).

  2. In the global section of your configuration, add the following line:

    module-load hapee-lb-update.so
  3. Once enabled, the Update module creates a new HAProxy configuration section named dynamic-update. This section can contain one or more update directives. The following example shows how to periodically update a file named forbid.map by polling the URL for changes every 300 seconds:

    dynamic-update
       update id /etc/haproxy/forbid.map map url http://10.0.0.1:80/forbid.map delay 300s
    
    frontend fe_main
        bind 10.0.0.2:80
        mode http
        acl maintenance_required src,map_ip(/etc/haproxy/forbid.map) -m found
        http-request redirect location src,map_ip(/etc/haproxy/forbid.map) if maintenance_required
  4. Add the map or ACL file, such as a forbid.map, that contains your initial values, such as:

    10.0.0.0/8     /maint/maintenance.html
    192.168.0.0/16 /maint/forbiden.html
    0.0.0.0        /maint/deny.html

Configuration Parameters

A dynamic-update section may contain one or more update directives. Its syntax is:

update id <id> url <url> [delay <delay>] [timeout <tmout>] [retries <nb>] [map]

The following table describes each argument:

Directive

Description

id <id> (required)

The absolute file path of the local file you want to keep updated.

url <url> (required)

The URL where the file can be downloaded.

delay <delay>

The period to wait between downloads. It defaults to five minutes (5m).

timeout <tmout>

The connection timeout to the download server. It defaults to five seconds (5s).

retries <nb>

The number of tries to establish a connection to the download server. It defaults to 3.

map

Informs that the downloaded file must be interpreted as a map file. By default, the file is interpreted as an ACL file.

tsl-ticket-keys

Sets the TLS ticket keys file from which to load the keys.

log

Enables logging using the log server specified in the global section of the configuration.

dontlog-normal

Disables logging for successful updates.

HAProxy Runtime API

The following Runtime API commands are available:

lb-update list

Returns the list of update lines in the configuration file.

lb-update status

Shows the module status.

lb-update force-update <id>

Launches an immediate update for the selected <id>.