🚧

Supported versions

This DataDome module is supported with HAProxy 2.8+ as it requires a built-in HTTP client to call DataDome's Protection API.

Installation

If you already have HAProxy binary with Lua support, you can skip this section.

You can check HAProxy version by running

$ haproxy -v
HAProxy version 2.8.10-f28885f 2024/06/14 - https://haproxy.org/
Status: long-term supported branch - will stop receiving fixes around Q2 2028.
Known bugs: http://www.haproxy.org/bugs/bugs-2.8.10.html
Running on: Linux 5.15.0-1066-aws #72~20.04.1-Ubuntu SMP Thu Jul 18 10:41:27 UTC 2024 x86_64

You can validate Lua support using

$ haproxy -vv
HAProxy version 2.8.10-f28885f 2024/06/14 - https://haproxy.org/
[...]
Built with Lua version : Lua 5.4.7
[...]

Configuration

You need to follow the steps below:

1. Download the latest DataDome module from this link here and extract it in your HAProxy configuration directory.
   The archive includes the following files:

• datadome.lua: a Lua script that handles the transformation of the HTTP request
• core/helper.lua: Lua scripts to manipulate strings and HTTP Requests
• haproxy.cfg: Example file of a working configuration

2. Edit the HAProxy configuration file and set DATADOME_SERVERSIDE_API_KEY with your own API server key provided by DataDome. You can find this key inside our dashboard.
3. Update your HAProxy configuration file by replacing <PATH> with the actual path where you placed the file, and setting the different blocks needed:
4. Add the txn.placeholderX variable in the frontend to protect
5. Add the request/response hook as in the example below

global
    [...]
    httpclient.timeout.connect 150ms
    httpclient.retries 0
    # Edit Path here
    lua-load <PATH>/datadome.lua "DATADOME_SERVERSIDE_API_KEY" # Set your serverside key here
    
    [...]

# Example of frontend which will be protected
frontend http
    [...]
    # Insert these lines on each frontend you want to protect
    # This is required to allow the lua code to store temporary values from the DataDome API
    http-request set-var(txn.placeholder1) var(txn.dd.x_datadome_request_headers)
    http-request set-var(txn.placeholder2) var(txn.dd.x_datadome_headers)
    http-request set-var(txn.placeholder3) var(txn.dd.x_datadome_response)
    http-request set-var(txn.placeholder4) var(txn.dd.body)
    http-request set-var(txn.placeholder5) var(txn.dd.error)
    
    # Here check uri is not in exclusion path
		acl excluded_files path_reg -i .\.(avi|flv|mka|mkv|mov|mp4|mpeg|mpg|mp3|flac|ogg|ogm|opus|wav|webm|webp|bmp|gif|ico|jpeg|jpg|png|svg|svgz|swf|eot|otf|ttf|woff|woff2|css|less|jsf|js|map)$
    
    http-request lua.Datadome_request_hook if !excluded_files
    http-response lua.Datadome_response_hook
    
    # Insert this line before all default_backend / use_backend directives
    use_backend failure_backend if { var(txn.dd.status) -m str blocked }
    default_backend [...]

# Backend to serve the "challenged page"
backend failure_backend
    mode http
    http-request    use-service     lua.failure_service

🚧

Keep the failure_backend declaration first

HAProxy is using backends in the order they are defined in the configuration file.

backend failure_backend should remain first in order to be used by HAProxy when a request is blocked by DataDome. If not, blocked requests will be let through and reach the backend you defined in priority.

All of these rules are evaluated in their declaration order, and the first one which matches will
assign the backend. (HAProxy Reference documentation)

Settings

FAQ

How can I have DataDome response status in the log?

• For each request protected by DataDome, the txn.dd.x_datadome_response contains the value of the HTTP response API
• If there is an issue in the call to Datadome, the variable txn.dd.error contains the error code and details.
• the main errors are as follow:
  • 400 - Bad Request (Invalid DataDome Key ?)
  • 504 - API Server times out
  • 503 - Invalid response from API Server

How can I get Bot Name, RuleType and Bot/Human flags in my application?

It is possible to specify a Log-Format to log the returned Datadome Headers
Some headers returned by the API are:

• X-DataDome-botname
• X-DataDome-ruletype
• X-DataDome-isbot
• X-DataDome-requestid
• ...
  and can be logged using the method lua.ddHeaders as follow

log-format "X-DataDome-botname: %{+Q}[lua.ddHeaders(X-DataDome-botname)] | X-DataDome-family: %{+Q}[lua.ddHeaders(X-DataDome-ruletype)] | X-DataDome-isbot: %{+Q}[lua.ddHeaders(X-DataDome-isbot)] | %{+Q}[lua.ddHeaders(X-DataDome-requestid)]"

You can find more information here.

How can I exclude files from DataDome protection?

In the Haproxy configuration, option to call DataDome is managed by an HAProxy ACL.
Default ACL is as follow

acl excluded_files path_reg -i .\.(avi|flv|mka|mkv|mov|mp4|mpeg|mpg|mp3|flac|ogg|ogm|opus|wav|webm|webp|bmp|gif|ico|jpeg|jpg|png|svg|svgz|swf|eot|otf|ttf|woff|woff2|css|less|jsf|js|map)$

It can be completed by custom rules / other ACLs