Compatibility

DataDome module provides support for HAPEE version 1.7r2 and ALOHA beyond version 9.5.7.
Since version 1.8 of HAPEE, the DataDome module HAProxy should be used.

The same compatibility matrix as HAPEE applies here.

Configuration

Follow the below instructions:

Download the latest DataDome from the following link https://package.datadome.co/linux/DataDome-HAPEE-latest.tgz and unzip it in your HAProxy configuration directory. The archive includes the following files:
- spoe-datadome.conf: the SPOE filter configuration
- datadome.lua: a LUA script that handles the transformation of the HTTP request
Edit the spoe-datadome.conf file and replace DATADOME_API_KEY with your actual API Key
Update your HAProxy configuration file by replacing with the path where you placed the file, and set the different blocks as needed:

global
    [...]
    lua-load <PATH>/datadome.lua 
    [...]

frontend API_http
    [...]
    # Insert these lines on each frontend you want to protect
    filter spoe engine datadome config <PATH>/spoe-datadome.conf
    http-request lua.Datadome_request_hook
    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) -i -m str blocked }

    default_backend [...]

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

# Backend to contact Datadome API
backend spoe-datadome
    mode tcp
    timeout connect 1s
    option tcp-check
    tcp-check connect ssl
    server datadome-spoe1 api-eu-france-1.datadome.co:12346 check ssl verify none

Settings

Settings (File/Section)	Description	Default value
TCP connection to DataDome	Standard HAProxy TCP Backend configuration.	Based on the values in your global and default sections
timeout hello (spoe-datadome.conf)	Timeout for the SPOE for beginning handshake. Should be at least 4 times the latency RTT with DataDome (1 for TCP, 2 for TLS, 1 for SPOE) + 10 ms.	100 ms
timeout idle (spoe-datadome.conf)	Maximum wait time for an agent to close an idle connection. Value must be smaller than the "timeout server" of the SPOE backend.	10 minutes
timeout processing (spoe-datadome.conf)	Maximum wait time for a stream to process an event. A hit is generated if the upper-bound of DataDome latency overhead is reached. You can find the number of connections that timed out by logging the _txn.dd.error variable. On timeout, this variable is set to 1 (see below for other codes)._	50 ms
ACL static_file url_reg	Using HAPEE ACL, no calls will be made to DataDome for static assets by default.	.(js\|css\|jpg\|jpeg\|png\|ico\| gif\|tiff\|svg\|woff\|woff2\|ttf\| eot\|mp4\|otf)$

FAQ

Can I include the DataDome response status in the log?

The specific HAProxy variables are set as follows:

When the interrogation is handled correctly by DataDome, the txn.dd.x_datadome_response will contain the value of the HTTP response API
When there is an issue in the call to DataDome, the variable txn.dd.error will contain the SPOE error code as detailed below:
- The complete code list can be found in the following link: https://www.haproxy.org/download/1.8/doc/SPOE.txt
- The main codes are:
  - 1: A timeout occurred during the event processing
  - 2: An error was triggered during the resource allocation
  - 5: The frame processing has been interrupted by HAProxy
  - 255: An unknown error occurred during the event processing
  - Higher than 256: A SPOP error occurred during the event processing (Refer to SPOE documentation)

Can I get Bot Name, Bot Type and Bot/Human flags in my application?

From version 1.5 of this module, you can log the values of the DataDome headers by configuring your log format.
You can find more information here.

How to exclude pages from DataDome's protection?

In the spoe-datadome.conf file, the option to call DataDome is managed by a HAPEE ACL.
By default, we exclude requests from paths ending by js, css, jpg, jpeg, png, ico, gif, tiff, svg, woff, woff2, ttf, eot, mp4, otf.
You can use the HAPEE ACL rules to specify the requests that will be sent to DataDome.