HAProxy's Update module allows HAProxy to update periodically the contents of ACL and MAP from a file without reloading HAProxy.

At startup, HAProxy loads the content of map or acl from the designated file. If there is an update directive set up to update this content, HAProxy downloads the new content from the specified URL after a specified period of time.

Note

The content of the downloaded file replaces the existing content.

  • 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 time defined in <tmout>, it retries for the number of times defined in <nb> before it quits.

Tip

HAProxy Enterprise only: This module requires an active HAProxy Enterprise subscription. Please contact us if you would like to learn more or begin a free trial.

Install the Update module

  • Install the Send Metrics module as follows, depending on your platform:

    $ sudo apt install hapee-1.8r2-lb-update

    or

    $ sudo yum install hapee-1.8r2-lb-update

Configure the Update module

  • In the global section of HAProxy's configuration file /etc/hapee-1.8r2/hapee-lb.conf, add or uncomment the line below:

    global
    module-load  hapee-lb-update.so

Once enabled, the lb-update module creates a new HAProxy configuration section named dynamic-update.

This section can contain a single type of directive, called update, as follows:

dynamic-update
    update id <id> url <url> [delay <delay>] [timeout <tmout>] [retries <nb>] [map]

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

timeout <tmout>

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

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.

log

Provides log for the module, using the log server specified in the "global" section of the configuration file.

dontlog-normal

Disables logging for successful updates

Additional parameters

You can also apply the following HAProxy configuration parameters to the server directive. See the section Server and default-server options for the complete list of parameters.

Parameter

Description

ciphers

Sets the string describing the list of cipher algorithms that is negotiated during the SSL/TLS handshake with the server.

crt

Is available only when support for OpenSSL was built in. It designates a PEM file containing both the required certificates and any associated private keys.

force-sslv3

Enforces use of SSLv3 only on SSL connections instantiated from this listener.

force-tlsv10

Enforces use of TLSv1.0 only on SSL connections instantiated from this listener.

force-tlsv11

Enforces use of TLSv1.1 only on SSL connections instantiated from this listener.

force-tlsv12

Enforces use of TLSv1.2 only on SSL connections instantiated from this listener.

no-sslv3

Is available only when support for OpenSSL was built in. It disables support for SSLv3 on any sockets instantiated from the listener when SSL is supported.

no-tlsv10

Is available only when support for OpenSSL was built in. It disables support for TLSv1.0 on any sockets instantiated from the listener when SSL is supported.

no-tlsv11

Is available only when support for OpenSSL was built in. It disables support for TLSv1.1 on any sockets instantiated from the listener when SSL is supported.

no-tlsv12

Is available only when support for OpenSSL was built in. It disables support for TLSv1.2 on any sockets instantiated from the listener when SSL is supported.

no-tls-tickets

Is available only when support for OpenSSL was built in. It disables the stateless session resumption (RFC 5077 TLS Ticket extension) and force to use stateful session resumption.

verify

Is available only when support for OpenSSL was built in. If set to 'none', client certificate is not requested (default). In other cases, a client certificate is requested. If the client does not provide a certificate after the request and if 'verify' is set to 'required', then the handshake is aborted, while it would have succeeded if set to 'optional'.

verifyhost

Is available only when support for OpenSSL was built in, and only takes effect if 'verify required' is also specified. When set, the hostnames in the subject and subjectAlternateNames of the certificate provided by the server are checked. If none of the hostnames in the certificate match the specified hostname, the handshake is aborted. The hostnames in the server-provided certificate may include wildcards. Supported in default-server: No

Runtime API

API

Description

lb-update list

Returns the list of update lines in the configuration file

lb-update force-update <id>

Launches an immediate update for the selected <id>

lb-update status

Shows the module status

Configuration example

The following example delivers redirect URLs based on the client IP address:

HAProxy's configuration frontend, with a map definition and a dynamic-update section to define how to update the map:

frontend fe_main
    bind 10.0.0.2:80
    mode http
    acl maintenance_required src,map_ip(/etc/haproxy/forbid.map) -m found
    http-request redirect location src,map_ip(/etc/haproxy/forbid.map) if maintenance_required

dynamic-update
    update id /etc/haproxy/forbid.map map url http://10.0.0.1:80/forbid.map delay 300s

Content of the file/etc/haproxy/forbid.map with a list of subnets and associated redirection:

10.0.0.0/8     /maint/maintenance.html
192.168.0.0/16 /maint/forbiden.html
0.0.0.0        /maint/deny.html