HAProxy Enterprise Documentation 2.5r1

Update Module Reference

The dynamic-update section uses the following syntax:

    update id <id> url <url> [delay <delay> | xdelay <delay start next retry>] [timeout <timeout>] [retries <nb>] [modified | xmodified ] [source <addr>[:<port>]] [log] [dontlog-normal] [map] [purge <count> [<interval> [<id>]]] [tls-ticket-keys] [param*]

with the following parameters:



id <id>

<id> is the file name initially loaded by map or acl. The module uses the absolute file path. The file must exist when HAProxy Enterprise starts.

url <url>

<url> is where the file can be downloaded.

delay <delay>

<delay> is the download period; by default, its value is 5 minutes (5m). The minimum allowable delay is 1ms.

xdelay <delay start next retry>

xdelay provides more fine-tunable delay configuration than delay. xdelay settings are defined as follows:

  • <delay> specifies the period between each attempt to download new data. Default: 5m

  • <start> specifies the initial (first) download delay. Default: 5s

  • <next> is not used in this module and its value is not important. However, its value must be present. This is to maintain the compatibility of xdelay parameters with other lb-update-like modules. Default: 10s

  • <retry> determines the delay for the next attempt if the download fails. Default: 5s

If after three attempts, the new version of the data can not be downloaded, the download is canceled until the next time interval defined by <delay>.

timeout <timeout>

<timeout> is the connection timeout to the download server; by default its value is 5 seconds (5s).

retries <nb>

<nb> is the number of tries to establish a connection to the download server. This defaults to the global retries value (3 if not otherwise specified).


If set, enables the use of the time from the Last-Modified response HTTP header, i.e. checking whether or not to update the data using the If-Modified-Since request HTTP header.


The same as modified except that the file modification time is set immediately after reading the file status.

source <addr>[:<port>]

Set the source address for outgoing connections.

  • <addr> is the IPv4 address HAProxy Enterprise will bind to before connecting to a server. The default value of means that the system will select the most appropriate address to reach its destination.

  • <port> is an optional port. It is normally not needed but may be useful in some very specific contexts. The default value of zero means the system will select a free port. Note that port ranges are not supported.


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


Disables logging for successful updates.


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


The module allows you to delete patterns in one of the following two ways:

  • when downloading the next set of data, old patterns are deleted

  • as a separate purge task that works independently of the data download (It is temporarily stopped during the download of new data.)

You can use purge by providing only its <count> parameter to use the first method of purging:

purge <count>

Or you can provide two additional (optional) parameters <interval> and <id> to use the second method of purging:

purge <count> [<inverval> [<id>]]

purge settings are defined as follows:

  • <count> is the number of old and/or invalid patterns that can be purged at once. Allowed values for that parameter are between 1 and 100000. The default is 1000.

  • <interval> is the frequency for calling the pattern purging task. The value is set in milliseconds (if not specified by another time unit). If you specify the interval as 0, the task will be executed as quickly as possible. When setting the interval to 0, it is not recommended to purge a large group at once (a <count> of 100 is the optimal number for interval 0).

    <interval> has no default, so a value must be specified.

  • <id> assigns a specific id to the purge task. You can use <id> to group certain purging tasks, or you can assign each operation its own task. The default is 1000, which means that all purging operations will be performed in the common task which has an id of 1000.


Specifies that the downloaded file is a TLS ticket keys file (instead of an acl file).

param (additional server parameters)

A list of other server parameters. Useful to configure special SSL features. Available parameters are: ciphers, crt, force-sslv3, force-tlsv10, force-tlsv11, force-tlsv12, no-sslv3, no-tlsv10, no-tlsv11, no-tlsv12, no-tls-tickets, verify, verifyhost You can also apply any of the configuration parameters available to the server directive.

Next up

Update Module Runtime API