The Update module (lb-update) allows HAProxy to update periodically the contents of acl and map files without reloading HAProxy.

How the Update module works

At startup, HAProxy loads the content of map or acl from a designated file.

If there is an update directive set up to update this content, HAProxy downloads the new content from a specified URL after the designated period of time.

  • HAProxy updates the content of the map or acl only after the file downloads correctly.

  • If HAProxy cannot connect to the server over the designated time, it retries for a set number of times before it stops.

Note

The content of the downloaded file replaces the existing content.

Load the Update module in HAProxy

  1. In ALOHA, browse to the LB Layer 7 tab to edit the HAProxy configuration file.

  2. Create (or update) a global section at the top of the file with the content below:

    global
  module-load  /usr/libexec/haproxy/update.so

Configure the Update module

Once enabled, the Update module creates a new HAProxy configuration section called dynamic-update.

This section can contain a single type of directive, named update, as below:

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

With the following parameters:

id <id>

The file name initially loaded from map or acl; it uses the absolute file path.

url <url>

The location from which to download the file

delay <delay>

The download period (default: 5m).

timeout <tmout>

The connection timeout to the download server (default: 5s).

retries <nb>

The number of tries to connect to the download server.

map

Reads the downloaded file as a map file. By default, HAProxy reads the file as an acl file.

Additional parameters

You can also apply other HAProxy configuration parameters available for the server directive:

ciphers

Sets the string describing the list of cipher algorithms to negotiate 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 forces the use of stateful session resumption.

verify

Is available only when support for OpenSSL was built in.

  • If set to 'none', HAProxy does not request the client certificate (default). In other cases, a client certificate is requested.

  • If you set verify to 'required' and the client does not provide a certificate after the request, HAProxy aborts the handshake; it would succeed only if the parameter is set to 'optional'.

verifyhost

Is available only when support for OpenSSL was built in, and only takes effect if you also specify verify to 'required'.

  • When set, HAProxy checks the hostnames in the subject and subjectAlternateNames of the certificate provided by the server. If none of the hostnames in the certificate match the specified hostname, HAProxy aborts the handshake.

  • The hostnames in the server-provided certificate may include wildcards. Supported in default-server: No

Configuration example

To deliver redirect URLs based on client IP address:

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

    frontend fe_main
   bind 10.0.0.2:80
   mode http
   http-request redirect location %[src,map_ip(forbid.map)] if { src,map_ip(forbid.map) -m found }

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

  • Contents of the file forbid.map with a list of subnets and associated redirection:

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