nginx module

We provide a nginx module, which exposes redirection.io right in your nginx configuration. Using this module is the preferred way of integrating redirection.io in your infrastructure.

We also provide a Apache module. Should your infrastructure use Apache, please rather use this module.

When an incoming HTTP request arrives, it is handled by the nginx 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 nginx module

Installing the module

Debian and APT-based distributions

If you use a Debian or APT-based Linux distribution and want to install libnginx-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 17.10 (Artful Aardvark)
    repository source url: deb https://packages.redirection.io/deb artful main
    Ubuntu 18.04 (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
  2. Install the apt-transport-https package:

    sudo apt-get install apt-transport-https
    
  3. Import our apt repository key:

    sudo apt-key adv --keyserver pgp.mit.edu --recv-keys 24765BBD8E16EB44
    
  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 nginx module:

    sudo apt update && sudo apt install libnginx-mod-redirectionio
    
  6. Once the module is installed, simply reload the nginx service, for instance:

    sudo systemctl reload nginx
    

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

    sudo rpm --import 0x8E16EB44
    
  3. Add our RPM repository:

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

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

    sudo systemctl reload nginx
    

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.nginx_module Ansible role is available. You may install it using Ansible Galaxy:

ansible-galaxy install redirectionio.nginx_module

Basically, this role installs the redirection.io nginx 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.

For instance, this can be in you main server directive:

http {
    ...
    redirectionio_project_key SOME_PROJECT_KEY_HERE;
    ...
}

Or in a Virtualhost:

server {
    server_name example.org;
    root /path/to/root;
    
    ...
    redirectionio_project_key SOME_PROJECT_KEY_HERE;
    ...
}

Or even in a Directory:

server {
    server_name example.org;
    root /path/to/root;
    
    ...

    location /some-path/ {
        redirectionio_project_key SOME_PROJECT_KEY_HERE;
    }
    
    ...
}

The redirectionio_project_key can either be double-quoted or not (eg., SOME_PROJECT_KEY_HERE or "SOME_PROJECT_KEY_HERE").

Module configuration directives

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

redirectionio

  • Syntax: redirectionioon | off;
  • Default: redirectionio off;
  • Context: http, server, server if, location, location if

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 redirectionio_project_key is set in a node of the configuration.

Using redirectionio off can hence be useful to disable redirection.io in a particular location:

server {
    server_name example.org;
    root /path/to/root;
    redirectionio_project_key SOME_PROJECT_KEY_HERE;
    
    ...

    location /some-path/ {
        redirectionio off;
    }
    
    ...
}

redirectionio_project_key

  • Syntax: redirectionio_project_keysome_key;
  • Default: none
  • Context: http, server, server if, location, location if

Sets the redirection.io project key to use for requests matching the current context. When set, this directive automatically turns the redirectionio directive on.

redirectionio_logs

  • Syntax: redirectionio_logson | off;
  • Default: redirectionio_logs on;
  • Context: http, server, server if, location, location if

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 redirectionio_logs are set to on. In other terms, setting redirectionio_logs to on with redirectionio set to off won't collect any logs).

redirectionio_pass

  • Syntax: redirectionio_passip:port | unix:///path;
  • Default: redirectionio_pass 127.0.0.1:10301;
  • Context: http, server, server if, location, location if

This directive specifies the location of the redirectionio-agent backend that the nginx 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 redirectionio_pass directive can, for instance, be of the form unix:///var/run/redirectionio.sock.

Troubleshooting

The nginx reload command does not work and errors unknown directive "redirectionio_project_key"

If nginx fails to reload and complains about an unknown directive redirectionio_project_key, this may indicate that the nginx module has not been correctly loaded in nginx.

Please check that your main nginx configuration file (usually /etc/nginx/nginx.conf) contains a line to include enabled nginx modules (eg. include /etc/nginx/modules-enabled/*.conf;). If this line is missing, you may force loading the module by adding the following line in /etc/nginx/nginx.conf:

load_module modules/ngx_http_redirectionio_module.so;

Then, reload nginx (again), and it should be fine.

Can't find your answer?