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    

Nginx Setup

DataDome Nginx module detect and protect against bot activity

Before the regular Nginx 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 Nginx continue the regular process.
The module has been developed to protect user experience as if any error was to occur during the process or if the timeout was reached, the module would automatically disable its blocking process and allow those hits.

Compatibility

This module is compatible with nginx >= 1.5.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

1.a Install from repository

If you don't use 3rd party modules for Nginx you can use the Nginx DataDome repository.
We provide nginx 1.11.13 with DataDome Module builtin as a static module.

1.b Install from source

You can install DataDome Nginx module from the source as describe below:

# Get the NGINX source
nginx -v
wget http://nginx.org/download/nginx-1.11.13.tar.gz #Replace with the correct version
tar -xzvf nginx-1.*.tar.gz
cd nginx-*

# Build DataDome Module
rm -f DataDome-Nginx-latest.tgz
wget https://package.datadome.co/linux/DataDome-Nginx-latest.tgz
tar -zxvf DataDome-Nginx-latest.tgz
./configure --add-dynamic-module=/path/to/NginxDome
make

# add the following configuration to the head of nginx.conf
load_module modules/ngx_http_data_dome_auth_module.so;
load_module modules/ngx_http_data_dome_shield_module.so;
load_module modules/ngx_http_data_dome_upstream_dynamic_servers_module.so;
# Get the NGINX source
nginx -v
wget http://nginx.org/download/nginx-1.11.5.tar.gz #Replace with the correct version
tar -xzvf nginx-1.*.tar.gz
cd nginx-*

# Build DataDome Module
rm -f DataDome-Nginx-latest.tgz
wget https://package.datadome.co/linux/DataDome-Nginx-latest.tgz
tar -zxvf DataDome-Nginx-latest.tgz
./configure --add-module=/path/to/NginxDome
make

1.c build as package (DEB/RPM)

You can package nginx with DataDome module as a dynamic or a static package.

apt-get install dpkg-dev
apt-get build-dep nginx
apt-get source nginx
cd nginx-1.10.1
wget https://package.datadome.co/linux/DataDome-Nginx-latest.tgz
tar -zxvf DataDome-Nginx-latest.tgz
mv DataDome-Nginx-*/ DataDome-Nginx-master
vi debian/rules 
# dynamyc module: add --add-dynamic-module=NginxDome-master in the common_configure_flags
# static module: add --add-module=NginxDome-master in the common_configure_flags
dpkg-source --commit
dpkg-buildpackage -rfakeroot -uc -us
sudo dpkg -i ../nginx_1.10.1-1~jessie_amd64.deb ../nginx-module-datadome_1.10.1-1~jessie_amd64.deb
wget https://package.datadome.co/linux/DataDome-Nginx-latest.tgz
tar -zxvf DataDome-Nginx-latest.tgz
yumdownloader --source nginx
yum-builddep nginx
vi rpmbuil/SPECS/nginx.spec
# add --add-module=/path/DataDome-Nginx-2XX/ in COMMON_CONFIGURE_ARGS section
rpmbuild -ba ~/rpmbuild/SPECS/nginx.spec
sudo yum install ~/rpmbuild/RPMS/x86_64/nginx-1.10.1-1.el7.centos.ngx.x86_64.rpm

2. Configuration

in nginx.conf, add the following settings. You can select the best API Server endpoint

http {
    [...]
    
      resolver 8.8.8.8;

      upstream datadome {
          dd_server api.datadome.co:443;
          keepalive 10;
      }
}

in each virtual host conf file, set the Key provided by DataDome in data_dome_shield_key:

server {
  [...]

  data_dome_auth @datadome;

  location = @datadome {
    data_dome_shield_key "KEYPROVIDEBYDATDOME";
    proxy_pass https://datadome/validate-request/;
    proxy_method POST;
    proxy_http_version 1.1;
    proxy_set_header Connection "keep-alive";
    proxy_set_header Content-Type "application/x-www-form-urlencoded";
    proxy_set_body $data_dome_request_body;
    proxy_ignore_client_abort on;
    proxy_connect_timeout 150ms;
    proxy_read_timeout 50ms;
  }
}

Settings

setting
description
required
Default

data_dome_shield_key

your DataDome License key

yes

dd_server

hostname of the API Server

optional

api.datadome.co

data_dome_auth_uri_regex

processes only matching URIs

optional

data_dome_auth_uri_regex_exclusion

ignores all matching URIs

optional

exclude static asset

proxy_connect_timeout

timeout set for the initial opening connection

optional

150ms

proxy_read_timeout

timeout set for regular API calls

optional

50ms

FAQ

Can I disable DataDome on a specific location?

You can disable DataDome for specified location by add command below

data_dome_auth off;

By default, the module is in auto mode.

Can I disable DataDome dynamically with a variable (Lua for instance)?

You can set a variable to disable dynamically the DataDome module.

# disable datadome
set $is_datadome_enabled off;
# enable datadome
# set $is_datadome_enabled @datadome

data_dome_auth $is_datadome_enabled;

Can I activate DataDome for internal call?

The module doesn't call the API server for internal request. You can switch it on by command bellow::

data_dome_auth_pass_internal_redirect on;

Can I change refresh DNS record time?

If you use dd_server, you can change refresh time from default 1 hours by command bellow:

resolver 8.8.8.8;

upstream datadome {
  dd_server api.datadome.co:443 refresh_in=2h;
  keepalive 10;
}

Can I disable or enable the module on IP range?

The easy way is doing this by ngx_http_geo_module.

You can find an example bellow that disable DataDome module for request from IP addresses 192.168.0.0/24

http {
    ....
    geo $is_datadome_enabled {
        default        '@datadome';

        192.168.0.0/24 'off';
    }
    ....
    server {
        ....
        data_dome_auth $is_datadome_enabled;
        ....
    }
}

Can I add DataDome response status in the log?

You can add the DataDome API Response code in logs. Possible value are 200, 403, or 5xx in case of timeout or connexion error

http {
    ....
    log_format datadome '$request $datadome_status';
    access_log /var/log/nginx/datadome.log datadome;
    ....
    server {
        ....
        data_dome_auth @datadome;
        data_dome_auth_set $datadome_status $upstream_status;
        ....
    }
}

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.

Header
Description
Values

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:

http {
    ....
    log_format datadome '$request $http_x_datadome_isbot $datadome_response_time';
    access_log /var/log/nginx/datadome.log datadome;
    ....
    server {
        ....
        data_dome_auth @datadome;
        data_dome_auth_set $datadome_response_time $upstream_response_time;
        ....
    }
}

Nginx Setup

DataDome Nginx module detect and protect against bot activity