Apache module - Developer documentation | Documentation
Apache module
We provide an Apache module, which exposes redirection.io right in your Apache configuration. Using this module is one of the advised ways of integrating redirection.io in your infrastructure.
We also provide a nginx module for nginx users.
As an alternative to the deployment using the "reverse proxy" mode, the redirection.io Apache module is a quick way to integrate redirection.io in your existing infrastructure. This dynamic module just hooks in the Apache request and response loop, and synchronously queries a tcp API of the locally installed agent whenever a request arrives. When an incoming HTTP(s) request arrives, it is handled by the Apache webserver, which redirection.io's native module hooks in, in a very fast and performant way:
Please note that the Apache module requires a redirection.io agent instance to be available on your infrastructure, so please also setup the redirection.io agent.
Installing the module [Permalink to this section](/content/documentation/developer-documentation/apache-module#installing-the-module "Permalink to this section"/index.html)
Debian and APT-based distributions [Permalink to this section](/content/documentation/developer-documentation/apache-module#debian-and-apt-based-distributions "Permalink to this section"/index.html)
If you use a Debian or APT-based Linux distribution and want to install libapache2-mod-redirectionio, please use the following commands:
- Select your distribution Debian 13 (Trixie)Debian 12 (Bookworm)Debian 11 (Bullseye)Ubuntu 24.04 LTS (Noble Numbat)Ubuntu 22.04 LTS (Jammy Jellyfish)
- Install the
apt-transport-httpspackage:
sudo apt-get install apt-transport-https
```
3. Import our apt repository key:
```bash
sudo mkdir -p /etc/apt/keyrings
wget -qO- https://packages.redirection.io/gpg.key | sudo tee /etc/apt/keyrings/redirectionio-archive-keyring.asc
```
4. Add our Debian repository url:
```bash
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/redirectionio-archive-keyring.asc] https://packages.redirection.io/deb/stable/3 trixie main" | sudo tee -a /etc/apt/sources.list.d/packages_redirection_io_deb.list > /dev/null
```
5. Update the apt cache and install redirection.io's Apache module:
```bash
sudo apt update && sudo apt install libapache2-mod-redirectionio
```
6. Once the module is installed, restart the apache2 service, for instance:
```bash
sudo systemctl restart apache2
```
You're done! redirection.io is installed, up and running. You can go on with [redirection.io's Apache configuration](/content/documentation/developer-documentation/apache-module#configuration/index.html) and should see some logs within minutes 🎉
### Red Hat and RPM-based distributions [Permalink to this section](/content/documentation/developer-documentation/apache-module#red-hat-and-rpm-based-distributions "Permalink to this section"/index.html)
Our Apache module is available for Centos 7, Centos 8, RHEL 7, RHEL 8 up to the release 2.8.0. From the release 2.9.0 and later, only Centos 9 stream is supported. However, you may still [compile the redirection.io Apache module for your distribution](/content/documentation/developer-documentation/apache-module#using-the-apache-module-with-a-non-standard-apache2-install/index.html)
If you use a Red Hat/CentOS-like Linux distribution and want to install `libapache2-mod-redirectionio`, please use the following commands:
1. Import the signature key:
```bash
sudo rpm --import https://packages.redirection.io/gpg.key
```
2. Add our RPM repository:
```bash
sudo yum-config-manager --add-repo https://packages.redirection.io/rpm/stable/3/centos_9
```
3. Install redirection.io's Apache module:
```bash
sudo yum install libapache2-mod-redirectionio
```
4. Once the module is installed, restart the apache2 service, for instance:
```bash
sudo systemctl restart apache2
```
### Ansible role [Permalink to this section](/content/documentation/developer-documentation/apache-module#ansible-role "Permalink to this section"/index.html)
A [`redirectionio.apache_module` Ansible role is available](https://galaxy.ansible.com/redirectionio/apache_module/). You may install it using Ansible Galaxy:
```bash
ansible-galaxy install redirectionio.apache_module
```
Basically, this role installs the redirection.io Apache module and makes sure you use the right repository locations, depending on your host operating system.
## Configuration [Permalink to this section](/content/documentation/developer-documentation/apache-module#configuration "Permalink to this section"/index.html)
Enabling the redirection.io is as simple as declaring the project key in the Virtualhost or configuration node where you want to enable redirection.io.
You can find the project key
[in the "instances" screen of the manager](/content/manager/index.html) (click on the "Setup on your website" > "Setup on your infrastructure" button).
For instance, this can be in a Virtualhost:
```apacheconf
<VirtualHost *:8080>
DocumentRoot /path/to/root
ServerName example.org
# ...
RedirectionioProjectKey "SOME_PROJECT_KEY_HERE"
# ...
</VirtualHost>
```
Or even in a Location:
```apacheconf
<VirtualHost *:8080>
DocumentRoot /path/to/root
ServerName example.org
# ...
<LocationMatch "^/some-path">
RedirectionioProjectKey "SOME_PROJECT_KEY_HERE"
</LocationMatch>
# ...
</VirtualHost>
```
The `RedirectionioProjectKey` can either be double-quoted or not (eg., `SOME_PROJECT_KEY_HERE` or `"SOME_PROJECT_KEY_HERE").
## Module configuration directives [Permalink to this section](/content/documentation/developer-documentation/apache-module#module-configuration-directives "Permalink to this section"/index.html)
The `libapache2-mod-redirectionio` enables several configuration directives, which can be used wherever the `RedirectionioProjectKey`is used:
### Redirectionio [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectionio "Permalink to this section"/index.html)
- **Syntax:** `Redirectionio` "on" | "off"
- **Default:** `Redirectionio "off"`
- **Context:** `VirtualHost, Location, LocationMatch`
This directive enables or disables redirection.io for requests matching the current context. By default, redirection.io is disabled, but is automatically enabled when the directive `RedirectionioProjectKey` is set in a node of the configuration.
Using `Redirectionio "off"` can hence be useful to disable redirection.io in a particular location:
```apacheconf
<VirtualHost *:8080>
DocumentRoot /path/to/root
ServerName example.org
RedirectionioProjectKey "SOME_PROJECT_KEY_HERE"
# ...
<LocationMatch "^/some-path">
Redirectionio "off"
</LocationMatch>
# ...
</VirtualHost>
```
### RedirectionioProjectKey [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectionioprojectkey "Permalink to this section"/index.html)
- **Syntax:** `RedirectionioProjectKey` "some_key"
- **Default:** `none`
- **Context:** `VirtualHost, Location, LocationMatch`
Sets the redirection.io project key to use for requests matching the current context. When set, this directive automatically turns the `Redirectionio` directive on.
### RedirectionioLogs [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectioniologs "Permalink to this section"/index.html)
- **Syntax:** `RedirectionioLogs` "on" | "off"
- **Default:** `RedirectionioLogs "on"`
- **Context:** `VirtualHost, Location, LocationMatch`
This directive enables or disables logs collection for the current matching context (however, please note that logs will only be sent if both the `Redirectionio` directive and `RedirectionioLogs` are set to `on`. In other terms, setting `RedirectionioLogs` to `on` with `Redirectionio` set to `off` won't collect any logs).
### RedirectionioPass [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectioniopass "Permalink to this section"/index.html)
- **Syntax:** `RedirectionioPass` "tcp://ip:port" | "unix:///path"
- **Default:** `RedirectionioPass "tcp://127.0.0.1:10301"`
- **Context:** `VirtualHost, Location, LocationMatch`
This directive specifies the location of the `redirectionio-agent` backend that the Apache module must use for matching requests. In a traditional setup, the agent is simply available at `127.0.0.1:10301`. If you expose the agent through a file, then the value of the `RedirectionioPass` directive can, for instance, be of the form `unix:///var/run/redirectionio.sock`.
This directive also allows to set some connection pool management options:
```apacheconf
RedirectionioPass "tcp://127.0.0.1:10301" min_conns=1 keep_conns=10 max_conns=100 timeout=100
```
All the settings `min_conns`, `keep_conns`, `max_conns` and `timeout` are optional:
- **min_conns** (default `1`): this is the minimal number of tcp connections that are permanently established between the Apache2 module and the redirection.io agent. If these connections do not exist, they are created, even if no HTTP request is handled by the Apache2 server.
- **max_conns** (default `100`): this is the maximal number of tcp connections that can be established between the Apache2 module and the redirection.io agent at a given time. If all the connections are currently in used, the module will wait for the `timeout` duration, then log an error and let the request pass without handling it.
- **keep_conns** (default `10`): this is the minimal number of tcp connections to be kept alive once they have been created.
- **timeout** (default `100`): this is the duration, in milliseconds, while the Apache2 module will wait for a response from the agent. The redirection.io agent is very performant and, even with hundreds of thousands of rules, should always send a response much faster than this timeout value (usually in less than 1ms), but this setting ensures that, even in very hard load contexts, the agent call will not block the request for too long.
For example, with `min_conns=1 keep_conns=10 max_conns=100 timeout=50`:
- `1` connection is established between Apache2 and the agent when Apache2 is started;
- Apache2 will create up to `100` connections to the agent (of course, it reuses available connections);
- if many connections were created and are no more useful, they will be released, but Apache2 will keep `10` connections alive;
- Apache2 will wait max. for `50` milliseconds for a response from the redirection.io agent.
### RedirectionioRuleIdsHeader [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectionioruleidsheader "Permalink to this section"/index.html)
- **Syntax:** `RedirectionioRuleIdsHeader` "on" | "off"
- **Default:** `RedirectionioRuleIdsHeader "off"`
- **Context:** `VirtualHost, Location, LocationMatch`
If this setting is enabled, a response header named `X-RedirectionIo-RuleIds` will be added to the response. Its value will contain the list of the redirection.io rule ids applied to this response, separated by the `;` character.
### RedirectionioScheme [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectionioscheme "Permalink to this section"/index.html)
- **Syntax:** `RedirectionioScheme` "http" | "https"
- **Default:** `none`
- **Context:** `VirtualHost, Location, LocationMatch`
This directive allows to force the scheme to use when matching the request. This is useful if you have defined rules using a URL trigger with an absolute URL value (containing a scheme, a domain name, etc.), but you want to use the same rules in a VirtualHost with another scheme.
Imagine, for example, a VirtualHost listening https traffic only, using a project in which rules are defined using the `http://` scheme: URLs would never be matched, as no rule uses the `https://` scheme. In this case, setting the `RedirectionioScheme` value to `http` will force the module to match with this scheme, not the real request scheme.
### RedirectionioSetHeader [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectioniosetheader "Permalink to this section"/index.html)
- **Syntax:** `RedirectionioSetHeader` X-Custom-Header-Name HeaderValue;
- **Default:** `none`
- **Context:** `VirtualHost, Location, LocationMatch`
This directive allows to pass the request to the redirection.io module by adding a request header filled with a given value. The value passed to the header can be an Apache variable, eg.:
```apacheconf
RedirectionioSetHeader X-GeoIP-Country-Code $(GEOIP_COUNTRY_CODE);
```
This can be useful to pass variables from the Apache context to the redirection.io agent, that can be used in redirection rules using the [request header trigger](/content/documentation/user-documentation/triggers-and-markers-reference#the-header-trigger/index.html).
### RedirectionioTrustedProxies [Permalink to this section](/content/documentation/developer-documentation/apache-module#redirectioniotrustedproxies "Permalink to this section"/index.html)
- **Syntax:** `RedirectionioTrustedProxies` 127.0.0.1,172.18.0.0/24;
- **Default:** `none`
- **Context:** `VirtualHost, Location, LocationMatch`
This directive is used by the module to restrict which proxies are trusted before evaluating the `X-Forwarded-*` headers. This is in particular useful when using the IP Address trigger, in order to ensure that the evaluated IP address is valid and has not been forged.
The Apache module is opensource and [available on our github account](https://github.com/redirectionio/libapache2-mod-redirectionio).
## Questions and answers & troubleshooting [Permalink to this section](/content/documentation/developer-documentation/apache-module#questions-and-answers-troubleshooting "Permalink to this section"/index.html)
### Are there any drawbacks to using the Apache module instead of the "reverse proxy" mode? [Permalink to this section](/content/documentation/developer-documentation/apache-module#are-there-any-drawbacks-to-using-the-apache-module-instead-of-the-reverse-proxy-mode "Permalink to this section"/index.html)
While this approach is interesting - because it means few changes to the infrastructure layout and the requests flow in your stack - it can be sometimes challenging to setup:
- first, Apache modules are tied to very specific versions of Apache. We distribute pre-compiled modules for officially distribution-provided versions of Apache, but we cannot distribute our module for each and every version of Apache available. In other words, the users of custom Apache installs will have to compile the Apache module themselves
- the Apache request management flow is not a quiet journey 🙂 In other words, depending on which modules are installed, unexpected behaviors may appear, and there is no way to guarantee that our module will perfectly integrate in your Apache install. For example, there might be incompatibilities with other modules
- Apache modules are developed using the C language, which does not guarantee memory-safety. The redirection.io agent itself, and the opensource libredirectionio underlying library, are Rust-based binaries
- updating a dynamic module requires a restart of the server, which is not always something that you want to do
- last and not least, using the redirection.io Apache module means that, for each and every request, a synchronous TCP call is performed from the Apache process to the redirection.io agent. We offer [several tweaking directives](/content/documentation/developer-documentation/apache-module#redirectioniopass/index.html) to maintain a connection pool, and it will perfectly work on reasonable traffic websites, but it can become a bit challenging to properly configure in highly demanding environments
This is why we usually recommend to [rather use the reverse proxy mode](/content/documentation/agent-documentation/the-agent-as-a-reverse-proxy/index.html). However, the Apache module is a perfectly convenient, supported, and fully tested way to use redirection.io if you wish so.
### The module logs `500` errors that I think did not happen [Permalink to this section](/content/documentation/developer-documentation/apache-module#the-module-logs-500-errors-that-i-think-did-not-happen "Permalink to this section"/index.html)
The Apache module is designed to log the exact request and response flow, as it is handled internally by the Apache server. This means that, if the module logs a `500` error, it is because the Apache server internally handled the request with a `500` response code, even if the client did not actually receive this `500` response.
There can be several reasons for this:
- the most common one is that the HTTP requests was cancelled by the client before the Apache server could send the response, and that the Apache server internally handled this as a `500` error (because, for example, a fastcgi module returned an error). These `500` errors are also visible in the access logs.
- or the real response sent to the client was modified by another module after the redirection.io module logged the request.
The redirection.io module logs the response code as Apache itself logs it. In some cases, it can be disturbing to see `500` errors in the redirection.io logs and can be annoying as it can pollute the logs and make it harder to find the real errors. If you want to avoid this, we rather advise to [install the redirection.io agent in "reverse proxy" mode](/content/documentation/agent-documentation/the-agent-as-a-reverse-proxy/index.html), which is not affected by this issue.
## Using the Apache module with a non-standard Apache2 install [Permalink to this section](/content/documentation/developer-documentation/apache-module#using-the-apache-module-with-a-non-standard-apache2-install "Permalink to this section"/index.html)
Our Apache module is one of the recommended ways of integrating redirection.io in Web stacks. We distribute our Apache module for many distributions, which should cover most of the production cases. However, it may happen that your hosting provider or provisioning solution installs a custom version of Apache, in non-standard paths or with incompatible dependencies.
This section will guide you through the steps to get our Apache module work with your Apache2 install, whatever its setup.
If you are fluent with Docker, this compilation process is also available as [a Dockerfile on our Github account](https://github.com/redirectionio/docker-example/blob/master/apache-module-custom/services/apache/Dockerfile).
### Download and build the libredirectionio library [Permalink to this section](/content/documentation/developer-documentation/apache-module#download-and-build-the-libredirectionio-library "Permalink to this section"/index.html)
The [libredirectionio library](https://github.com/redirectionio/libredirectionio) is a [Rust](https://www.rust-lang.org/) library that processes redirects and filtering from rules created using redirection.io. This library is used in our various proxies, and specifically in the Apache2 module.
1. Install Rust compilation tools:
```bash
# Debian-based distribution
apt install autoconf build-essential curl wget unzip
curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y
apt install cargo wget unzip
# RedHat-based distribution
yum install -y epel-release yum-utils curl
yum -y groupinstall 'Development Tools'
curl https://sh.rustup.rs -sSf | sh
```
2. Get the libredirectionio library sources:
```bash
cd /tmp
wget -O libredirectionio-master.zip https://github.com/redirectionio/libredirectionio/archive/master.zip
unzip libredirectionio-master.zip
cd libredirectionio-master
```
3. And build the library:
```bash
autoreconf -i && \
./configure && \
make clean && \
make && \
make install
```
If the compilation is successful (it might be long), you should get a `target/release/libredirectionio.so` static library.
### Download and build the module source [Permalink to this section](/content/documentation/developer-documentation/apache-module#download-and-build-the-module-source "Permalink to this section"/index.html)
The [redirection.io's Apache module is available](https://github.com/redirectionio/libapache2-mod-redirectionio) as an opensource project in [our github account](https://github.com/redirectionio).
1. First, install some compilation tools and utilities:
```bash
# Debian-based distribution
apt install gawk
# RedHat-based distribution
yum install gcc gawk wget unzip
```
2. Ensure that `apxs` is installed on your system. [`apxs`](https://httpd.apache.org/docs/current/en/programs/apxs.html) (also known as "APache eXtenSion tool") is a tool for building and installing extension modules for the Apache server:
```bash
which apxs
```
If this command does not return the full path of `apxs`, you need to install it. This depends on your distribution, but basically you can get `apxs` using one of the following commands:
```bash
# Debian-based distribution
apt install apache2-dev
# RedHat-based distribution
yum install httpd-devel
# Amazon Linux
yum install httpd24-devel
```
3. Download the module:
```bash
cd /tmp
wget -O libapache2-mod-redirectionio-master.zip https://github.com/redirectionio/libapache2-mod-redirectionio/archive/master.zip
```
4. Then, build the module:
```bash
unzip libapache2-mod-redirectionio-master.zip
cd libapache2-mod-redirectionio-master
autoreconf -i
./configure
make clean
make
sudo make install
```
### Install the module in the right path [Permalink to this section](/content/documentation/developer-documentation/apache-module#install-the-module-in-the-right-path "Permalink to this section"/index.html)
Installing the module should be quite straightforward in most cases:
```bash
make install
```
If this works, you're all set, congratulations! However, this step can fail if your Apache2 install does not use your distribution's standard Apache directories. In this case, you must copy the module to the appropriate folder.
1. First, find the modules folder. This can be done by inspecting the apache configuration:
```bash
/path/to/your/apache -V | grep SERVER_CONFIG_FILE
# should display someting like: SERVER_CONFIG_FILE="/etc/apache-custom/httpd.conf"
# which means the config file is "/etc/apache-custom/httpd.conf"
```
Use `cat` to show the content of this file: you should notice several `LoadModule` directives, for instance `LoadModule auth_basic_module lib/apache-custom/mod_auth_basic.so`.
This means that the modules path is in `/etc/apache-custom/lib/apache-custom/`. Hurra 🎉
2. Move the module in this folder:
```bash
# change the module permissions
chmod 644 ./src/mod_redirectionio.so
# then, copy it to the right location
# (of course, use the path that you have found above)
sudo mv ./src/mod_redirectionio.so /etc/apache-custom/lib/apache-custom/
```
3. Load the module in Apache - for this, add a `LoadModule` directive in `httpd.conf`, something like:
```apache
LoadModule redirectionio_module lib/apache-custom/mod_redirectionio.so
```
You may also want to add this line in a separate file, to keep track of your own changes. Most of the time, the main Apache2 configuration file includes other files (for example, `IncludeOptional /etc/apache-custom/conf.d/*.conf`) \- so feel free to add your own!
4. restart Apache, and you're done!
```bash
sudo systemctl restart apache2.service
```
You can check that the module fully works by completing its [configurations steps in the VirtualHost](/content/documentation/developer-documentation/apache-module#configuration/index.html).
This page has been updated on Apr 16, 2026
Can't find your answer?
[Contact our support](/content/contact/index.html)