Apache module

We provide an Apache module, which exposes redirection.io right in your Apache configuration. Using this module is the preferred way 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 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

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 9 (Stretch)
    repository source url: deb https://packages.redirection.io/deb stretch main
    Debian 10 (Buster)
    repository source url: deb https://packages.redirection.io/deb buster main
    Ubuntu 16.04 (Xenial Xerus)
    repository source url: deb https://packages.redirection.io/deb xenial main
    Ubuntu 18.04 LTS (Bionic Beaver)
    repository source url: deb https://packages.redirection.io/deb bionic main
    Ubuntu 18.10 (Cosmic Cuttlefish)
    repository source url: deb https://packages.redirection.io/deb cosmic main
    Ubuntu 19.04 (Disco Dingo)
    repository source url: deb https://packages.redirection.io/deb disco main
    Ubuntu 19.10 (Eoan Ermine)
    repository source url: deb https://packages.redirection.io/deb eoan main
    Ubuntu 20.04 LTS (Focal Fossa)
    repository source url: deb https://packages.redirection.io/deb focal 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 stretch 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, simply reload the apache2 service, for instance:

    sudo systemctl reload apache2
    

You're done! redirection.io is installed, up and running. You can go on with redirection.io's 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/centos_7
    config manager: yum-config-manager
    package manager: yum
    Centos 6
    repository url: https://packages.redirection.io/rpm/centos_6
    config manager: yum-config-manager
    package manager: yum
    Fedora 29
    repository url: https://packages.redirection.io/rpm/fedora_29
    config manager: dnf config-manager
    package manager: dnf
    Fedora 28
    repository url: https://packages.redirection.io/rpm/fedora_28
    config manager: dnf config-manager
    package manager: dnf
    RHEL 7
    repository url: https://packages.redirection.io/rpm/centos_7
    config manager: yum-config-manager
    package manager: yum
    RHEL 6
    repository url: https://packages.redirection.io/rpm/centos_6
    config manager: yum-config-manager
    package manager: yum
  2. Import the signature key:

    wget -qO- https://packages.redirection.io/gpg.key -O /tmp/redirectionio-gpg.key && sudo rpm --import /tmp/redirectionio-gpg.key && rm /tmp/redirectionio-gpg.key
    
  3. Add our RPM repository:

    sudo yum-config-manager --add-repo https://packages.redirection.io/rpm/centos_7
  4. Install redirection.io's Apache module:

    sudo yum install libapache2-mod-redirectionio
  5. Once the module is installed, simply reload the apache2 service, for instance:

    sudo systemctl reload apache2
    

You're done! redirection.io is installed, up and running. You can go on with redirection.io's 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.

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.

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 provisionning solution installs a custom version of Apache, in non-standard paths or with incompatible dependencies.

This page will guide you through the steps to get our Apache module work with your Apache2 install, whatever its setup.

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 build-essential gawk wget unzip
    
    # 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 https://github.com/redirectionio/libapache2-mod-redirectionio/archive/v0.3.2.zip
    
  4. Then, simply build the module:

    unzip v0.3.2.zip
    cd libapache2-mod-redirectionio-0.3.2
    make
    

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/.libs/mod_redirectionio.so
    
    # then, copy it to the right location
    # (of course, use the path that you have found above)
    sudo mv ./src/.libs/mod_redirectionio.so /etc/apache-custom/lib/apache-custom/
    
    
  3. Load the module in Apache - for this, simply 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. reload Apache, and you're done!

    sudo systemctl reload apache2.service
    

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

Can't find your answer?