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. Should your infrastructure use nginx, please rather use this module.

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:

an incoming request is catched by redirection.io's Apache module

Please note that the Apache module requires a redirection.io agent instance to be available on your infrastructure, so please setup the redirection.io agent first.

Installing the module

Debian and APT-based distributions

If you use a Debian or APT-based Linux distribution and want to install libapache2-mod-redirectionio, please use the following commands:

  1. Select your distribution

    In the next steps, please use the right values, depending on your distribution version:
    Debian 11 (Bullseye)
    repository source url: deb https://packages.redirection.io/deb/stable/2 bullseye main
    Debian 10 (Buster)
    repository source url: deb https://packages.redirection.io/deb/stable/2 buster main
    Debian 9 (Stretch)
    repository source url: deb https://packages.redirection.io/deb/stable/2 stretch main
    Ubuntu 16.04 LTS (Xenial Xerus)
    repository source url: deb https://packages.redirection.io/deb/stable/2 xenial main
    Ubuntu 18.04 LTS (Bionic Beaver)
    repository source url: deb https://packages.redirection.io/deb/stable/2 bionic main
    Ubuntu 18.10 (Cosmic Cuttlefish)
    repository source url: deb https://packages.redirection.io/deb/stable/2 cosmic main
    Ubuntu 19.04 (Disco Dingo)
    repository source url: deb https://packages.redirection.io/deb/stable/2 disco main
    Ubuntu 19.10 (Eoan Ermine)
    repository source url: deb https://packages.redirection.io/deb/stable/2 eoan main
    Ubuntu 20.04 LTS (Focal Fossa)
    repository source url: deb https://packages.redirection.io/deb/stable/2 focal main
    Ubuntu 20.10 (Groovy Gorilla)
    repository source url: deb https://packages.redirection.io/deb/stable/2 groovy_gorilla main
    Ubuntu 21.04 (Hirsute Hippo)
    repository source url: deb https://packages.redirection.io/deb/stable/2 hirsute main

  2. Install the apt-transport-https package:

    sudo apt-get install apt-transport-https

  3. Import our apt repository key:

    wget -q -O - https://packages.redirection.io/gpg.key | sudo apt-key add -

  4. Add our Debian repository url:

    echo "deb https://packages.redirection.io/deb/stable/2 bullseye main" | sudo tee -a /etc/apt/sources.list.d/packages_redirection_io_deb.list

  5. Update the apt cache and install redirection.io's Apache module:

    sudo apt update && sudo apt install libapache2-mod-redirectionio

  6. Once the module is installed, restart the apache2 service, for instance:

    sudo systemctl restart apache2

You're done! redirection.io is installed, up and running. You can go on with redirection.io's Apache configuration and should see some logs within minutes 🎉

Red Hat and RPM-based distributions

If you use a Red Hat/CentOS-like Linux distribution and want to install libapache2-mod-redirectionio, please use the following commands:

  1. Select your distribution

    In the next steps, please use the right values, depending on your distribution version:
    Centos 7
    repository url: https://packages.redirection.io/rpm/stable/2/centos_7
    config manager: yum-config-manager
    package manager: yum
    Centos 8
    repository url: https://packages.redirection.io/rpm/stable/2/centos_8
    config manager: yum-config-manager
    package manager: yum
    RHEL 7
    repository url: https://packages.redirection.io/rpm/stable/2/centos_7
    config manager: yum-config-manager
    package manager: yum
    RHEL 8
    repository url: https://packages.redirection.io/rpm/stable/2/centos_8
    config manager: yum-config-manager
    package manager: yum

  2. Import the signature key:

    sudo rpm --import https://packages.redirection.io/gpg.key

  3. Add our RPM repository:

    sudo yum-config-manager --add-repo https://packages.redirection.io/rpm/stable/2/centos_7

  4. Install redirection.io's Apache module:

    sudo yum install libapache2-mod-redirectionio

  5. Once the module is installed, restart the apache2 service, for instance:

    sudo systemctl restart apache2

You're done! redirection.io is installed, up and running. You can go on with redirection.io's Apache configuration and should see some logs within minutes 🎉

Ansible role

A redirectionio.apache_module Ansible role is available. You may install it using Ansible Galaxy:

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. It supports Debian and RHEL-based Linux distributions.

Configuration

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 (click on the "Setup on your infrastructure" button).

For instance, this can be in a Virtualhost:

<VirtualHost *:8080>
  DocumentRoot /path/to/root
  ServerName example.org
    
  # ...

  RedirectionioProjectKey "SOME_PROJECT_KEY_HERE"
  
  # ...
</VirtualHost>

Or even in a Location:

<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

The libapache2-mod-redirectionio enables several configuration directives, which can be used wherever the RedirectionioProjectKeyis used:

Redirectionio

  • 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:

<VirtualHost *:8080>
  DocumentRoot /path/to/root
  ServerName example.org
  RedirectionioProjectKey "SOME_PROJECT_KEY_HERE"
  
  # ...
  
  <LocationMatch "^/some-path">
    Redirectionio "off"
  </LocationMatch>
  
  # ...
</VirtualHost>

RedirectionioProjectKey

  • 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

  • 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

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

As of the release 2.2.0, this directive also allows to set some connection pool management options:

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

  • Syntax: RedirectionioRuleIdsHeader "on" | "off"
  • Default: RedirectionioRuleIdsHeader "off"
  • Context: VirtualHost, Location, LocationMatch
  • Available since: 2.0.0

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

  • Syntax: RedirectionioScheme "http" | "https"
  • Default: none
  • Context: VirtualHost, Location, LocationMatch
  • Available since: 2.0.0

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

  • Syntax: RedirectionioSetHeader X-Custom-Header-Name HeaderValue;
  • Default: none
  • Context: VirtualHost, Location, LocationMatch
  • Available since: 2.2.0

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

RedirectionioSetHeader X-GeoIP-Country-Code $(GEOIP_COUNTRY_CODE);

This can be useful to pass variables from the nginx context to the redirection.io agent, that can be used in redirection rules using the request header trigger.

RedirectionioTrustedProxies

  • Syntax: RedirectionioTrustedProxies 127.0.0.1,172.18.0.0/24;
  • Default: none
  • Context: VirtualHost, Location, LocationMatch
  • Available since: 2.3.0

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 value to use for this directive is a comma-separated list of all the proxies IP addresses that should be trusted (it might be a CIDR notation for subnetworks).

Using the Apache module with a non-standard Apache2 install

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.

Download and build the libredirectionio library

The libredirectionio library is a Rust 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:

    # Debian-based distribution
apt install autoconf build-essential curl wget unzip
curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain 1.54.0 -y

apt install cargo wget unzip

# RedHat-based distribution
curl https://sh.rustup.rs -sSf | sh

  2. Get the libredirectionio library sources:

    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:

    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

The redirection.io's Apache module is available as an Opensource project in our github account.

  1. First, install some compilation tools and utilities:

    # 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 (also known as "APache eXtenSion tool") is a tool for building and installing extension modules for the Apache server:

    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:

    # Debian-based distribution
apt install apache2-dev

# RedHat-based distribution
yum install httpd-devel

# Amazon Linux
yum install httpd24-devel

  3. Download the module:

    cd /tmp
wget -O libapache2-mod-redirectionio-master.zip https://github.com/redirectionio/libapache2-mod-redirectionio/archive/master.zip

  4. Then, build the module:

    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

Installing the module should be quite straightforward in most cases:

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:

    /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 \o/

  2. Move the module in this folder:

    # 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:

    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) - feel free to add your own!

  4. restart Apache, and you're done!

    sudo systemctl restart apache2.service

You can check that the module fully works by completing its configurations steps in the VirtualHost.

This page has been updated on April 13th, 2022.
Can't find your answer?
Contact our support