Apache
DataDome Apache module detects and protects against bot activity
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
- 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
- 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
- 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/
- 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 extensionmod_datadome_shield.so
(the path is output by the "make install" command)
-
Test the config using "configtest"
-
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 Regional Endpoints |
DomeApiPort | Port of the API server | Optional | 443 |
DomeApiProtocol | Protocol for API Server connexion | Optional | HTTPS |
DomeURIRegex | Processes matching URIs only | Optional | |
DomeURIRegexExclusion | Ignores all matching URIs | Optional | exclude static asset |
DomeTimeOut | API request timeout for new connections in ms Not supported since 2.46 | Optional | 100 |
DomeRequestTimeOut | API request timeout for reused connections in ms Also used for new connections since 2.44 | Optional | 50 |
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>
How can I add Bot information in logs?
Enrichment headers 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. The list of all headers exposed is available in our Log Enrichment page.
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 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
Updated 2 months ago