The DataDome Developer Hub

Welcome to the DataDome developer hub. You'll find comprehensive guides and documentation to help you start working with DataDome as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Apache setup

DataDome Apache module detect and protect against bot activity

Before the regular Apache process, the module makes a call to the DataDome API using a keepalive connection.
Depending on the API response, the module will either block the query or let Apache continue the regular process.
The module has been developed to protect the user experience for human visitors: If any error were to occur during the process, or if the timeout are reached, the module will automatically disable its blocking process and allow those hits.

Compatibility

This module is compatible with Apache 2.2 and 2.4

Every new release of the module is strongly tested on the the following distributions:

  • Debian 6/7/8.1
  • Ubuntu 12/14/15
  • Centos 6/7
  • SUSE 11

How to compile

  1. HTTPD headers and libssl files & libraries must be installed on your target system:
apt-get install make libssl-dev apache2-dev # you may need to replace `apache2-dev` with `apache2-threaded-dev` or `apache2-prefork-dev`
yum install make openssl-devel httpd-devel
zypper install make openssl-devel apache2-devel
  1. Download and compile:
rm -f DataDome-Apache-latest.tgz
wget https://package.datadome.co/linux/DataDome-Apache-latest.tgz
tar -zxvf DataDome-Apache-latest.tgz
cd DataDome-ApacheDome-*
make prepare
make
make install # This might required sudo/root access

Please refer to the FAQ below in case you are using a custom path

How to run

  1. Add DataDome config file in Apache module config folder using the example docs/mod_datadome.conf:

    • Debian/Ubuntu: cp docs/mod_datadome.conf /etc/apache2/mods-enabled/
    • RHEL/Centos: cp docs/mod_datadome.conf /etc/httpd/conf.modules.d/
    • SUSE: cp docs/mod_datadome.conf /etc/apache2/conf.d/
  2. In the module config file, edit the only required settings:

    • set the Key using the License key provided by DataDome
    • select the best API Server endpoint
    • adjust the path of the binary extension mod_datadome_shield.so (it is output by the "make install command")
  3. Test the config using "configtest"

  4. Restart Apache Server

Settings

setting
description
required
Default

DomeKey

your DataDome License key

yes

DomeApiHost

API Server hostname
more info here

optional

api.datadome.co

DomeApiPort

port of the API server

optional

443

DomeApiProtocol

protocol for API Server connexion

optional

HTTPS

DomeURIRegex

processes only matching URIs

optional

DomeURIRegexExclusion

ignores all matching URIs

optional

exclude static asset

DomeTimeOut

API request timeout for new connections in ms

optional

100

DomeRequestTimeOut

API request timeout for reused connections in ms

optional

50

From version 2.30, all settings were renamed

The prefix "Dome" was added to all settings to avoid conflict with others modules.

DebugMode deprecated and replaced with standard Apache logging way

Param DebugMode is deprecated (since 2.26 version).
You can use standard Apache logging way.

Logging

Debug loging

To enable logging you should update LogLevel option on apache, for example:

LogLevel error datadome_shield:debug

Configuration for Apache 2.2

On Apache 2.2, LogLevel is not supported for module. You must set LogLevel globally.
Example: LogLevel debug

Access Log with DataDome information

DataDome set two variables that can be added to CustomLog:

  • %{DATA_DOME_STATUS}: status code return from API Server or specific code

    • 200: API Server allow hit
    • 403: API Server disallow hit
    • 502: problem while connecting to API Server
    • 504: timeout while connecting to API Server
    • 700: url is not handle by the module because it doesn't match with regex
    • 701: module was disabled
    • 702: licence key was no setup
    • 703: wrong module configuration
    • 704: API server response hasn't got expected X-DataDomeResponse header
  • %{DATA_DOME_SPENT_TIME}: time in ms spent by the module

For example, you can use the following LogFormat to add DataDome variable at the end:

LogFormat "%h %l %u %t \\"%r\\" %{DATA_DOME_STATUS}e %{DATA_DOME_SPENT_TIME}e" datadome
CustomLog logs/datadome_log datadome

FAQ

How can I compile on a custom Apache installation?

In case you are seing Neigher apxs or apxs2 found, please set configure path, just set path in APACHE_BUILD_PATH parameter

make prepare APACHE_BUILD_PATH=/home/apachebuildpath
make APACHE_BUILD_PATH=/home/apachebuildpath
make install  APACHE_BUILD_PATH=/home/apachebuildpath

Can I check if DataDome module is loaded?

You can check if the module is correctly loaded by running apachectl -t -D DUMP_MODULES

What about firewall?

The DataDome module needs to communicate with our api server. If you have outcoming filtering please allow traffic from your servers to api.datadome.co port 80 an 443. As we are using a loadbalancer with dynamic IP, you should not create rules based on a static IP.

Can I add custom Header?

The module setup DATA_DOME_IS_URI_REGEX_MATCHED variable to 1 if request has matched and 0 if hasn't.
You can use it to setup a header, for example:

Header set X-DD-Regex-Matched "1" env=DATA_DOME_IS_URI_REGEX_MATCHED

Can I disable the module for specified location?

You can disable the module on a specified location by changing the DomeStatus variable:

<Location "/private1">
    DomeStatus off
</Location>

Can I disable the module for specified query params or IP?

You can also disable it by setup DATA_DOME_DISABLE environment variable:

RewriteEngine On
RewriteCond %{QUERY_STRING} REGEX_TO_MATCH_URL [OR]
RewriteCond %{REMOTE_ADDR} ^127\.0\.0\.1$ [OR]
RewriteCond %{HTTP_HOST} ^www\.exemple\.com$
RewriteRule ^(.*)$ - [E=DATA_DOME_DISABLE]

If you would like to enable it for specified condition you can use the following logic:

RewriteEngine On
RewriteRule ^(.*)$ - [E=DATA_DOME_DISABLE]
RewriteCond %{QUERY_STRING}  REGEX_TO_MATCH_URL [OR]
RewriteCond %{REMOTE_ADDR} ^127\.0\.0\.1$ [OR]
RewriteCond %{HTTP_HOST} ^www\.exemple\.com$
RewriteRule ^(.*)$ - [E=!DATA_DOME_DISABLE]

Meanwhile, if you use apache 2.4+, you can use IF directive.

<If "%{QUERY_STRING} =~ /REGEX_TO_MATCH/">
  DomeStatus off
</If>

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

DataDome module can inject headers in the HTTP Request that can be read by your application.
To active this premium feature, please contact DataDome Support.

X-DataDome-isbot

Is it a bot ?

0 -> Human
1 -> Bot
NA -> detection not activated on this segment

X-DataDome-botname

The Bot name

String

X-DataDome-botfamily

The bot family

good_bot / bad_bot / commercial_bot

For example to create a access-log file that contains the request URI, 'is it a bot', and the API server response time, you can use line bellow:

LogFormat "%h %l %u %t \"%r\" %{X-DataDome-isbot}i %{DATA_DOME_SPENT_TIME}e" datadome
CustomLog logs/datadome.log datadome

Apache setup

DataDome Apache module detect and protect against bot activity