HAProxy Enterprise Documentation 2.4r1

Dynamic-update

The dynamic-update section lets HAProxy Enterprise pull updated ACL and Map files from a remote server. This allows a cluster of HAProxy Enterprise nodes to stay in sync.

After the Update module is installed, we can list one or more update lines in a dynamic-update section. Each specifies a file to pull from a remote server to the current load balancer node. Be sure to add a module-load directive to the global section of your configuration file to load the Update module.

global
  module-path /opt/hapee-2.4/modules/
  module-load hapee-lb-update.so

dynamic-update
   update id /etc/hapee-2.4/redirects.map url http://10.0.0.1:80/redirects.map  delay 5m  timeout 5s  retries 3  map  log  dontlog-normal

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 map and acl 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.

In the following section we explore several examples that use dynamic-update.

Use a map file for a client redirect

In the following sample, our goal is to redirect clients to another URL, where the URL is chosen based on the client's IP address. We will store the mapping of client IP ranges to their target redirect URLs in a map file. Then, we'll use dynamic update to keep that map file in sync with a remote source.

  1. In a new configuration section named dynamic-update, add one or more update lines that specify from where and how often to download new content. Here is an example that updates the contents of a file at /etc/hapee-2.4/redirects.map from the URL http://10.0.0.1:80/redirects.map:

    dynamic-update
       update id /etc/hapee-2.4/redirects.map map url http://10.0.0.1:80/redirects.map delay 300s
  2. For this example, the contents of this file, /etc/hapee-2.4/redirects.map, are a list of IP subnets and URL paths. Clients will be redirected if their IP address falls within one of these ranges:

    10.0.0.0/8     /maint/maintenance.html
    192.168.0.0/16 /maint/forbidden.html
    0.0.0.0/0        /maint/deny.html
  1. In the following snippet, a frontend references this data using an acl directive and an http-request redirect directive:

    frontend fe_main
       mode http
       bind :80
       acl redirect_needed src,map_ip(/etc/hapee-2.4/redirects.map) -m found
       acl redirect_performed path_beg /maint/
       http-request redirect location %[src,map_ip(/etc/hapee-2.4/redirects.map)] if redirect_needed !redirect_performed

If you do not reference the file you specify in dynamic-update for use in another configuration section, the service will log an error similar to the following:

[ALERT]    (1525) : config : 'update': id '/etc/hapee-2.4/redirects.map' not found in file ./haproxy.cfg at line 22
[ALERT]    (1525) : config : Fatal errors found in configuration.

Use an acl file to allow requests only from approved IP addresses

The following configuration sample details configuring the service to allow HTTP requests from only IP addresses listed in a acl file. This file will be updated on a configured interval via dynamic-update. This example uses the http-request configuration directive to only allow requests from the IPs in the allowed list and deny requests from all other IPs.

  1. In a new configuration section named dynamic-update, add one or more update lines that specify from where and how often to download new content. Here is an example that updates the contents of a file at /etc/hapee-2.4/allowed_ips.acl from the URL http://10.0.0.1:80/allowed_ips.acl:

    dynamic-update
      update id /etc/hapee-2.4/allowed_ips.acl  url http://10.0.0.1:80/allowed_ips.acl  xdelay 1m 5s 1s 10s  timeout 100ms  retries 3  modified  source 192.168.1.2:10000  log
  2. For this example, the contents of this file, /etc/hapee-2.4/allowed_ips.acl, are a list of allowed IP addresses. Requests originating from these IPs will be allowed; requests from all others will be denied.

  3. To use this list of allowed IP addresses, in a listen section add the following:

    listen allow-certain-ips
        server localhost 127.0.0.1:8000
    
        http-request allow if { src -f /etc/hapee-2.4/allowed_ips.acl }
        http-request deny

    This example uses an inline ACL to express that only requests originating from IPs listed in /etc/hapee-2.4/allowed_ips.acl are to be allowed. The rest are to be denied.

If you do not reference the file you specify in dynamic-update for use in another configuration section, the service will log an error similar to the following:

[ALERT]    (1525) : config : 'update': id '/etc/hapee-2.4/allowed_ips.acl' not found in file ./haproxy.cfg at line 22
[ALERT]    (1525) : config : Fatal errors found in configuration.

See also

Dynamic Data Updates

ACLs


Next up

Log-forward