Versions supported

🚧
This DataDome module is supported with HAProxy versions 2.6 and higher as it needs HttpClient to call DataDome API.
Due to a bug in HaProxy LUA implementation, the following specific minor versions are not compatible: 2.6.7, 2.7.0.

Get HAProxy with LUA through package manager

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.6.8-1ppa1~jammy 2023/01/24 - https://haproxy.org/
Status: long-term supported branch - will stop receiving fixes around Q2 2027.
Known bugs: http://www.haproxy.org/bugs/bugs-2.6.8.html
Running on: Linux 5.15.0-1028-aws #32-Ubuntu SMP Mon Jan 9 12:28:07 UTC 2023 x86_64

You can validate LUA Version using

$ haproxy -vv
HAProxy version 2.6.8-1ppa1~jammy 2023/01/24 - https://haproxy.org/
Status: long-term supported branch - will stop receiving fixes around Q2 2027.
[...]
Built with Lua version : Lua 5.3.6
[...]

Configuration

You need to follow the steps below:

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

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.
Update your HAProxy configuration file by replacing <PATH> with the actual path where you placed the file, and setting the different blocks needed:
Add the txn.dummyX variable in the frontend to protect
Add the request/response hook as in the example below

global
    [...]
    lua-load <PATH>/datadome.lua
    set-var proc.Datadome_key str("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
    http-request set-var(txn.dummy1) var(txn.dd.x_datadome_request_headers)
    http-request set-var(txn.dummy2) var(txn.dd.x_datadome_headers)
    http-request set-var(txn.dummy3) var(txn.dd.x_datadome_response)
    http-request set-var(txn.dummy4) var(txn.dd.body)
    http-request set-var(txn.dummy5) 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 server the "blocked page"
backend failure_backend
    mode http
    http-request    use-service     lua.failure_service

Settings

Settings	Description	Default Value	Required	File
DataDome_Key (*haproxy.cfg)	Your DataDome Server Side License Key - Available inside our dashboard		Yes	haproxy.cfg
Endpoint	URL of the closest endpoint. More info here	api.datadome.co	Optional	datadome.lua
Timeout	API request timeout for reused connections in ms	150ms	Optional	datadome.lua

FAQ

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

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.

Exclude pages 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