Compatibility

The DataDome module supports:

• Apache 2.2+ and 2.4+

Using the following OS:

• Debian 6+ (For Debian 9+ the module is compatible with Apache 2.4+ only)
• Ubuntu 12+ (For Ubuntu 18+ the module is compatible with Apache 2.4+ only)
• Centos 6+
• SUSE 11

Installation

Requirements

• Server-Side Key available in your DataDome dashboard

Protect your traffic

1. Compile the module:

apt-get install make libssl-dev apache2-dev

yum install make openssl-devel httpd-devel which gcc mod_ssl

zypper install make openssl-devel apache2-devel

Make sure all packages are installed before proceding.

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 in case of a custom path (Apache and/or Openssl) or if apache2-dev/httpd-dev is not available.

2. Keep the output path of mod_datadome_shield.so.
3. Copy docs/mod_datadome.conf to the Apache folder below:

cp docs/mod_datadome.conf /etc/apache2/mods-enabled/

cp docs/mod_datadome.conf /etc/httpd/conf.modules.d/

cp docs/mod_datadome.conf /etc/apache2/conf.d/

4. Open mod_datadome.conf:

• Set the DomeKey using theServer-Side Key available in your DataDome dashboard.
• Adjust the path (from step 2) of LoadModule for mod_datadome_shield.so .

5. Test the configuration:

apachectl -t
# Syntax OK

6. Restart Apache Server:

apachectl -k restart

Congrats! You can now see your traffic in your DataDome dashboard.

Configuration

By default, the configuration is located in mod_datadome.conf.

Refer to the next Settings section for the full list of possible configuration settings.
Contact DataDome support team if you plan to change the default settings.

Settings

🚧

Starting with 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 method

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

🚧

Starting with version 2.46, DomeTimeOut is no more supported

It is replaced by DomeRequestTimeOut which is used as "API request timeout for both new and reused connections in ms".

FAQ

Do you provide a demo?

We provide a Dockerfile with the setup and the configuration to help you to integrate DataDome.

How can I add debug logging?

• Update the LogLevel option in the mod_datadome.conf file :

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

How can I access Log with DataDome information?

• DataDome sets 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: license key was not 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

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

This configuration must be defined in your VirtualHost or Apache configuration file:

• Debian / Ubuntu: /etc/apache2/apache2.conf
• RHEL / Centos: /etc/httpd/conf/httpd.conf
• SUSE: /etc/apache2/httpd.conf

To define it in the module configuration, use the GlobalLog directive. It defines a log shared by the main server configuration and all defined virtual hosts.

How can I add Bot information in logs?

• Enrichment headers can be injected in WebServer logs.
  • Below an example of how to use it:

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

How can I compile on a custom Apache installation?

• In case of Neigher apxs or apxs2 found, please set configure path, set the path in APACHE_BUILD_PATH parameters.

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

How can I compile on a custom OpenSSL installation?

• To compile with an OpenSSL installation that is not on a configured path:
  • use OPENSSL_DIR as a parameter for the Makefile.

make prepare OPENSSL_DIR=/usr/local/openssl
make OPENSSL_DIR=/usr/local/openssl
make install OPENSSL_DIR=/usr/local/openssl

🚧

Avoid mixing OpenSSL versions

We recommend that you use the same OpenSSL version for both Apache and the ApacheDome module.

How can I check if DataDome module is loaded?

• Check if the module is correctly loaded by running apachectl -t -D DUMP_MODULES

What about firewall?

• The DataDome module needs to communicate with the DataDome API servers.
• Please allow traffic from your servers to api.datadome.co ports 80 and 443.
• DataDome use a Load Balancer with dynamic IP: do not create rules based on a static IP.

How can I add a custom header?

• The module sets DATA_DOME_IS_URI_REGEX_MATCHED variable to 1 if request has matched and 0 if it hasn't. To setup a header:

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

How can I enable/disable the module for specified location or vhost?

You can either enable or disable the module for specified locations and virtual hosts by changing the DomeStatus variable:

• To disable the module:

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

<VirtualHost *:80>
    DocumentRoot "/www/example1"
    ServerName www.example.com
    DomeStatus off

    # Other directives here
</VirtualHost

• To enable the module:

DomeStatus off # disabled globally

<Location "/private1">
    DomeStatus on
</Location>

DomeStatus off # disabled globally

<VirtualHost *:80>
    DocumentRoot "/www/example1"
    ServerName www.example.com
    DomeStatus on

    # Other directives here
</VirtualHost

How can I disable the module for specified query params or IP?

• Disable it by setting the 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]

• for a specified condition, 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]

• for Apache 2.4+, use IF directive.

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

How can I use our corporate proxy?

• Use your corporate proxy with our module by changing your configuration in mod_datadome.conf:

# Protocol to connect to the proxy
DomeApiProtocol HTTP

# Proxy hostname or IP
DomeApiHost proxy-server

# Proxy port
DomeApiPort 3128

# DataDome API to connect to DataDome, this will be used by the proxy
# DomeApiURI https://api.datadome.co/validate-request/

How can I use other headers as source for client IP

• If a proxy or a Load Balancer is used and adds someHeader containing client IP, please insert this value into True-Client-IP or X-Forwarded-For:

SetEnvIfNoCase ^someHeader$ ^(.*)$ someHeader=$1
RequestHeader set "True-Client-IP" "%{someHeader}e" env=someHeader