Using the nginx module with a non-standard nginx install

Our nginx module is one of the recommended ways of integrating redirection.io in Web stacks. We distribute our nginx 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 nginx, in non-standard paths or with incompatible dependencies.

This page will guide you through the steps to get our nginx module work with your custom nginx install, whatever its setup. The only requirement is the nginx version, which must at least be NGINX 1.9.11.

Download and build the module

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

  1. First, install some compilation tools and utilities:

    apt install nginx build-essential gawk wget unzip libssl-dev libpcre3-dev libzip-dev libxml2-dev libxslt-dev libgd-dev libgeoip-dev libperl-dev
    
  2. Retrieve redirection.io module sources (pick the last release from our repository):

    cd /tmp
    wget https://github.com/redirectionio/libnginx-mod-redirectionio/archive/v0.5.0.zip
    unzip v0.5.0.zip
    
  3. Identify the Nginx version of your system:

    nginx -v
    # displays:
    #   nginx version: nginx/1.15.8
    

    This means that the nginx version is "1.15.8"

  4. Get nginx sources for this version (of course, use the right version number, from the above command):

    cd /tmp
    wget http://nginx.org/download/nginx-1.15.8.tar.gz
    tar -xzvf nginx-1.15.8.tar.gz
    cd nginx-1.15.8
    
  5. Then, simply build the module:

    # retrieve your local nginx configure options
    export NGINX_CONFIGURE_ARGUMENTS=`nginx -V 2>&1 | grep 'configure arguments:' | cut -d\  -f3-`
    
    # run configure (use the module version downloaded above)
    eval "./configure $NGINX_CONFIGURE_ARGUMENTS --add-dynamic-module=/tmp/libnginx-mod-redirectionio-0.5.0"
    
    # build the module
    make -j modules
    

Install and load the module in nginx

Installing the module should be quite straightforward in most cases - you simply have to move the compiled file to the right folder.

Usually, the following command should show the nginx modules directory location:

nginx -V 2>&1 | gawk 'match($0,/--modules-path=(\S+?)/,a) {print a[1]}'
# should display something like:
#   /usr/lib/nginx/modules

Then, simply move the module in this folder (of course, use the directory name returned by the command above):

sudo mv objs/ngx_http_redirectionio_module.so /usr/lib/nginx/modules/

Last step, you now have to load the module in nginx - for this, simply add a load_module directive in nginx.conf, something like:

load_module modules/ngx_http_redirectionio_module.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 nginx configuration file includes module files (for example, include /etc/nginx/modules-enabled/*.conf;) - so feel free to create your own /etc/nginx/modules-enabled/mod-http-redirectionio.conf config file.

Restart nginx, and you're done!

sudo systemctl restart nginx.service

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

Can't find your answer?