HAProxy Enterprise Documentation 1.7r2

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.7/hapee-lb.sock
# lb-update configured entries
# id: next update
/etc/hapee-1.7/redirects.map: 4m49s

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

$ echo "lb-update force-update /etc/hapee-1.7/redirects.map" | sudo socat stdio /var/run/hapee-1.7/hapee-lb.sock
lb-update: force-update `/etc/hapee-1.7/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.7/hapee-lb.sock
 lb-update module status
------------------------------------------------------------------------------
 initialized:          yes

 SMP update
   configuration:      /etc/hapee-1.7/hapee-lb.cfg:30
   entry:              /etc/hapee-1.7/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.