Before the regular Apache process starts, the module makes a call to one of our Regional Endpoints using a KeepAlive connection.

Depending on the response, the module will either block the query or let Apache proceed with the regular process.
The module has been developed to protect the visitors' user experience: If any error were to occur during the process, or if the timeout is 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 thoroughly tested on the following distributions:

• Debian 6/7/8/9/10/11 (For Debian 9 & 10, the module is compatible with Apache 2.4 only)
• Ubuntu 12/14/16/18/20/22 (For Ubuntu 18 & 20, the module is compatible with Apache 2.4 only)
• 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 which gcc mod_ssl

zypper install make openssl-devel apache2-devel

2. 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, only edit the following required settings:

• set the DomeKey using the License key provided by DataDome
• select the best Regional Endpoints
• adjust the path of the LoadModule for the binary extension mod_datadome_shield.so (the path is output by the "make install" command)

3. Test the config using "configtest"

4. Restart Apache Server

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".

Logging

Debug logging

To enable logging you should update the LogLevel option in the mod_datadome.conf file, 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 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 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

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

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

If you would like to defined it in the module configuration, you have to use the GlobalLog directive. It defines a log shared by the main server configuration and all defined virtual hosts.

FAQ

How can I compile on a custom Apache installation?

In case you are seeing Neigher apxs or apxs2 found, please set configure path, just 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?

In case you need to compile with an OpenSSL installation that is not on a configured path, you can 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.

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 outgoing filtering please allow traffic from your servers to api.datadome.co ports 80 and 443. As we are using a Load Balancer with dynamic IP, you should not create rules based on a static IP.

Can I add custom Header?

The module sets DATA_DOME_IS_URI_REGEX_MATCHED variable to 1 if request has matched and 0 if it 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 or vhost?

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

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

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

    # Other directives here
</VirtualHost

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

You can also 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]

If you would like to enable it for a 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 flags in my application?

DataDome module can inject headers in the HTTP Request that can be read by your application.
You can find more information Here

How can I add Bot information in logs?

Bot informations can be injected in WebServer logs. For instance, to create an access-log file that contains the request URI, 'is it a bot', and the API server response time, you can use the line below:

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

How can I use our corporate proxy?

You can use your corporate proxy with our modules by changing your configuration in mod_datadome.conf:

DomeApiHost proxy-server
DomeApiPort 3128
DomeApiURI http://api.datadome.co/validate-request/

How can I use other headers as source for client IP

If you're using a proxy server or a Load Balancer that adds someHeader that contains the IP of the client, you should insert this value into True-Client-IP or X-Forwarded-For:

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