HAProxy Enterprise Documentation 1.6r2

Update Module Reference

The dynamic-update section uses the following syntax:

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

with the following parameters:

Parameter	Description
`id <id>`	`<id>` is the file name initially loaded by `map` or `acl`; uses the absolute file path
`url <url>`	`<url>` is where the file can be downloaded
`delay <delay>`	`<delay>` is the download period; by default, its value is 5m
`xdelay <delay start next retry>`	`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. It is present only because of 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 5s
`retries <nb>`	`<nb>` is the number of tries to establish a connection to the download server
`modified`	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.
`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 0.0.0.0 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.
`log`	Enables logging for the module using the log server specified in the `global` section of the configuration file.
`dontlog-normal`	Disables logging for successful updates.
`map`	Informs that the downloaded file must be interpreted as a `map` file. By default, the file is interpreted as an `acl` file.
`tls-ticket-keys`	Sets the TLS ticket keys file from which to load the keys.
`param`	A list of other server parameters. Useful to configure special SSL features. You can also apply any of the configuration parameters available to the `server` directive.

Things to know:

ACL and Map files are simple text files. The difference between them is that ACL files contain a single column of data, one value per row, while Map files contain two columns: a key and value per row. By convention, the files have .acl and .map file extensions, respectively.
HAProxy Enterprise updates the contents of a map or acl file only if the file was properly downloaded.
If HAProxy Enterprise cannot connect to the server within the time defined in <timeout>, it retries for the number of times defined in <retries> before it quits.

Runtime API

API	Description
`lb-update list`	Returns the list of `update` lines in the `dynamic-update` section of the configuration file
`lb-update force-update <id>`	Launches an immediate update for the selected `<id>`
`lb-update status`	Shows the module status

Examples

Below are examples of using the Update module's Runtime API commands.

Use lb-update list to display the files that the Update module manages.

$ echo "lb-update list" | sudo socat stdio /var/run/hapee-1.6/hapee-lb.sock
# lb-update configured entries
# id: next update
/etc/hapee-1.6/redirects.map: 4m49s

Use lb-update force-update to update a file immediately.

$ echo "lb-update force-update /etc/hapee-1.6/redirects.map" | sudo socat stdio /var/run/hapee-1.6/hapee-lb.sock
lb-update: force-update `/etc/hapee-1.6/redirects.map`.

Use lb-update status to show the status of the Update module.

 $ echo "lb-update status" | sudo socat stdio /var/run/hapee-1.6/hapee-lb.sock
 lb-update module status
------------------------------------------------------------------------------
 initialized:          yes

 SMP update
   configuration:      /etc/hapee-1.6/hapee-lb.cfg:30
   entry:              /etc/hapee-1.6/redirects.map
   url:                http://127.0.0.1:3000/redirects.map
   http status count:  0 44 0 0 0
   period/delay:       10s / 5s 10s 5s
   use modified:       no
   reload/retry count: 44 0 0 / 0 0
   reload time:        2021-02-15 22:11:48 / <NEVER> / <NEVER>
   download time:      2021-02-15 22:11:48 / <NEVER>
   next update in:     4s

The fields of the lb-update status command are described below:

Field	Description
initialized	Whether the Update module was initialized. Initialization in this case does not mean that the module read the configuration (if any), but only that HAProxy Enterprise called the module initialization function.
configuration	The configuration file and the line number where the `update` directive is specified.
entry	The value of the `update` directive's `id` parameter you used when calling `lb-update force-update`.
url	The item's download URL. HTTP and HTTPS web protocols are supported.
http status count	The download HTTP status counter, sorted by status classes 1xx, 2xx, 3xx, 4xx, and 5xx.
period	The download period. Every so often there will be an attempt to download the data. In case the download cannot be completed within that period, it will be aborted and the data discarded.
delay	Indicates three values: start/next/retry. The <start> value specifies the initial (first) download delay. The <next> value is not used in this module and its value is not important. It is present only because of the compatibility of delay parameters with other lb-update-like modules. If the download fails, <retry> determines the delay for the next attempt. The number of consecutive downloads is 3 (after that the download is canceled until the next time specified by the download period).
use modified	Indicates whether the module uses the time from the Last-Modified response HTTP header to check whether to update the data using the If-Modified-Since request HTTP header.
reload count	Indicates three numbers. The first indicates the number of times the data reload was performed. The second indicates the number of times the data was not reloaded because the data did not differ from the old data. The third indicates the number of times the data reload failed because the data was incorrect.
retry count	Indicates two numbers: the number of unsuccessful downloads and the number of final unsuccessful downloads. For example, if each download is tried 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 time for the next cycle is awaited.
reload time	Indicates the date a reload was last performed, the date when data was not reloaded because the data did not differ from the old data, and the date when the data reload failed because the data was incorrect.
download time	Indicates the date of the last successful download and the date of the last unsuccessful download.
next update in	Indicates the time until the download of new data will be started. Also, if the download is in the process, then it is indicated here.

Next up

Service Discovery

More Versions

HAProxy Products Documentation

Update Module Reference

Runtime API

Examples

Your feedback is important to us!