Supported versions

Apache version

DataDome supports the last two stable versions for Apache.
You can find the release strategy for Apache on this website.

The module is compatible with stable versions 2.2 and above.

Operating systems

The module is compatible with the following Operating Systems:

• Debian 9+
• Ubuntu 18+
• Centos 6+

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 the Server-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.

Settings

"\.(avi|avif|bmp|css|eot|flac|flv|gif|gz|ico|jpeg|jpg|js|json|less|map|mka|mkv|mov|mp3|mp4|mpeg|mpg|ogg|ogm|opus|otf|png|svg|svgz|swf|ttf|wav|webm|webp|woff|woff2|xml|zip)$"

Upgrade guide

To upgrade, recompile and reinstall the module from the latest package:

wget https://package.datadome.co/linux/DataDome-Apache-latest.tgz
tar -zxvf DataDome-Apache-latest.tgz
cd DataDome-ApacheDome-*
make prepare && make && sudo make install

Refer to the Apache changelog for release notes.

- DomeURIRegexExclusion="/health|/heartbeat|\.(avi|avif|bmp|css|eot|flac|flv|gif|gz|ico|jpeg|jpg|js|json|less|map|mka|mkv|mov|mp3|mp4|mpeg|mpg|ogg|ogm|opus|otf|png|svg|svgz|swf|ttf|wav|webm|webp|woff|woff2|xml|zip)$"
+ DomeURIRegexExclusion="/health|/heartbeat"

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

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

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 or 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?

Apache is able to conditionally disable the module based on incoming request characteristics such as query parameters, IP addresses, or hostnames with regular expressions:

• 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 %{REMOTE_ADDR} ^127\.0\.0\.2$ [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 %{REMOTE_ADDR} ^127\.0\.0\.2$ [OR]
RewriteCond %{REMOTE_ADDR} ^192\.168\.0\. [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>

<<If "%{REMOTE_ADDR} =~ /^127\.0\.0\.1/ || %{REMOTE_ADDR} =~ /^192\.168\.0\./">
  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