HAProxy Enterprise Documentation 2.4r1

Update Module 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 specified <id>

lb-update status

Shows the module status

lb-update purge <id> [gen_id] [count]

Deletes data from the list of old/invalid patterns for the specified <id>

Two additional parameters are optional for purge:

  • <gen_id>, the pattern generation id

  • <count>, the number of records to purge

If no <gen_id> is specified, unnecessary patterns are deleted in the order in which they were added to the list. The default value for <count> is 1000 and the allowable range is between 1 and 100000.

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

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

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

Use lb-update purge to run a purge task immediately.

$ echo "lb-update purge /etc/hapee-2.4/redirects.map 13 1" | sudo socat stdio unix-connect:/var/run/hapee-2.4/hapee-lb.sock
lb-update: purge  `/etc/hapee-2.4/redirects.map` 13 : all pattern(s) purged!

If, for a particular generation id, there remain additional patterns to purge, the number of remaining patterns is shown:

$ echo "lb-update purge /etc/hapee-2.4/redirects.map 13 100" | sudo socat stdio unix-connect:/var/run/hapee-2.4/hapee-lb.sock
lb-update: purge  `/etc/hapee-2.4/redirects.map` 13 : 100 pattern(s) purged, 200 left!

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

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

 SMP update
   configuration:      /etc/hapee-2.4/hapee-lb.cfg:30
   entry:              /etc/hapee-2.4/redirects.map
   generation id:      256
   url:                http://127.0.0.1:3000/redirects.map
   http status count:  0 44 0 0 0
   last modified:      Wed, 29 Mar 2023 19:13:45 GMT
   period/delay:       10s / 5s 10s 5s
   use modified:       no
   reload/retry count: 44 0 0 / 0 0
   reload time:        2023-03-29 19:13:49 / 2023-03-29 19:13:40 / <NEVER>
   download time:      2023-03-29 19:13:49 / <NEVER>
   next update in:     4s
   purging id(s):      #1000 0:20 1:23 2:23 4:23 6:22 8:20 11:20 16:17 253:16
      block size:       1
      interval:         1h

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.

generation id

The current pattern generation id. The set of patterns from the next download will be associated with this id.

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.

last modified

The modification time of the item.

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.

purging id(s):

The number of purgeable patterns specified by their pattern generation id. If the purge operation is configured to run on an interval (instead of on the next download), the task ids for each purge are listed as well (only one task id is listed if all purge operations run under the common task #1000).

Each set of patterns and purgeable tasks are listed by <pattern generation id>:<count of patterns to purge>.

Two additional fields may appear under purging id(s):

  • block size: Indicates the maximum number of patterns to purge at one time.

  • interval: Indicates how often the purge task will run. This is present only if the purge operation is configured to run on an interval.

Next up

Real-time Dashboard