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.


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:

  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 by polling the URL for changes every 300 seconds:

       update id /etc/haproxy/ map url delay 300s
    frontend fe_main
        mode http
        acl maintenance_required src,map_ip(/etc/haproxy/ -m found
        http-request redirect location src,map_ip(/etc/haproxy/ if maintenance_required
  4. Add the map or ACL file, such as a, that contains your initial values, such as:     /maint/maintenance.html /maint/forbiden.html        /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:



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.


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


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


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


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