Module nginx

Nous proposons un module nginx qui expose redirection.io directement dans votre configuration nginx. L'utilisation de ce module est l'un des moyens conseillés pour intégrer redirection.io dans votre infrastructure.

Comme alternative au déploiement utilisant le mode "reverse proxy", le module nginx redirection.io est un moyen rapide d'intégrer redirection.io dans votre infrastructure existante. Ce module dynamique se greffe simplement sur la boucle de requête et de réponse de nginx et interroge de manière synchrone une API TCP de l'agent installé localement dès qu'une requête arrive. Lorsqu'une requête HTTP(s) entrante arrive, elle est traitée par le serveur web nginx, dans lequel le module natif de redirection.io s'insère de manière très rapide et performante :

Installation du module

Distributions basées sur Debian et APT

Si vous utilisez une distribution Linux basée sur Debian ou APT et que vous souhaitez installer libnginx-mod-redirectionio, veuillez utiliser les commandes suivantes :

Sélectionnez votre distribution

Dans les étapes suivantes, veuillez utiliser les bonnes valeurs, en fonction de la version de votre distribution :

Debian 13 (Trixie)

repository source url: trixie main

Debian 12 (Bookworm)

repository source url: bookworm main

Debian 11 (Bullseye)

repository source url: bullseye main

Ubuntu 24.04 LTS (Noble Numbat)

repository source url: noble main

Ubuntu 22.04 LTS (Jammy Jellyfish)

repository source url: jammy main

Installez le paquet apt-transport-https :

sudo apt-get install apt-transport-https

Importez la clé de notre dépôt apt :

sudo mkdir -p /etc/apt/keyrings
wget -qO- https://packages.redirection.io/gpg.key | sudo tee /etc/apt/keyrings/redirectionio-archive-keyring.asc

Ajoutez l'URL de notre dépôt Debian :

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

Mettez à jour le cache apt et installez le module nginx de redirection.io :
```
sudo apt update && sudo apt install libnginx-mod-redirectionio
```
Une fois le module installé, redémarrez le service nginx, par exemple :
```
sudo systemctl restart nginx
```

C'est terminé ! redirection.io est installé et opérationnel. Vous pouvez poursuivre avec la configuration nginx de redirection.io et devriez voir des logs apparaître en quelques minutes 🎉

Distributions basées sur Red Hat et RPM

Si vous utilisez une distribution Linux de type Red Hat/CentOS et que vous souhaitez installer libnginx-mod-redirectionio, veuillez utiliser les commandes suivantes :

Importez la clé de signature :

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

Ajoutez notre dépôt RPM :

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

Installez le module nginx de redirection.io :
```
sudo yum install libnginx-mod-redirectionio
```
Une fois le module installé, redémarrez le service nginx, par exemple :
```
sudo systemctl restart nginx
```

C'est terminé ! redirection.io est installé et opérationnel. Vous pouvez poursuivre avec la configuration nginx de redirection.io et devriez voir des logs apparaître en quelques minutes 🎉

Rôle Ansible

Un rôle Ansible redirectionio.nginx_module est disponible. Vous pouvez l'installer via Ansible Galaxy :

ansible-galaxy install redirectionio.nginx_module

Ce rôle installe le module nginx redirection.io et s'assure que vous utilisez les bons emplacements de dépôts selon votre système d'exploitation. Il supporte les distributions Linux basées sur Debian et RHEL.

Configuration

L'activation de redirection.io consiste uniquement à déclarer la clé du projet dans le VirtualHost ou le nœud de configuration dans lequel vous souhaitez activer redirection.io.

Par exemple, cela peut être dans votre directive serveur principale :

http {
    ...
    redirectionio_project_key MA_CLE_DE_PROJET_ICI;
    ...
}

Ou dans un Virtualhost :

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

    ...
    redirectionio_project_key MA_CLE_DE_PROJET_ICI;
    ...
}

Ou même dans un bloc location :

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

    ...

    location /some-path/ {
        redirectionio_project_key MA_CLE_DE_PROJET_ICI;
    }

    ...
}

La directive redirectionio_project_key peut être entourée de guillemets doubles ou non (ex., MA_CLE_DE_PROJET_ICI ou "MA_CLE_DE_PROJET_ICI").

Directives de configuration du module

Le paquet libnginx-mod-redirectionio active plusieurs directives de configuration, qui peuvent être utilisées partout où redirectionio_project_key est utilisé :

redirectionio

Syntaxe : redirectionio on | off;
Défaut : redirectionio off;
Contexte : http, server, server if, location, location if

Cette directive active ou désactive redirection.io pour les requêtes correspondant au contexte actuel. Par défaut, redirection.io est désactivé, mais il est automatiquement activé lorsque la directive redirectionio_project_key est définie dans un nœud de la configuration.

L'utilisation de redirectionio off peut donc être utile pour désactiver redirection.io dans une location particulière :

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

    ...

    location /some-path/ {
        redirectionio off;
    }

    ...
}

redirectionio_project_key

Syntaxe : redirectionio_project_key une_cle;
Défaut : aucune
Contexte : http, server, server if, location, location if

Définit la clé de projet redirection.io à utiliser pour les requêtes correspondant au contexte actuel. Lorsqu'elle est définie, cette directive active automatiquement la directive redirectionio.

redirectionio_logs

Syntaxe : redirectionio_logs on | off;
Défaut : redirectionio_logs on;
Contexte : http, server, server if, location, location if

Cette directive active ou désactive la collecte des logs pour le contexte actuel (veuillez toutefois noter que les logs ne seront envoyés que si les directives redirectionio et redirectionio_logs sont toutes deux sur on. En d'autres termes, régler redirectionio_logs sur on alors que redirectionio est sur off ne collectera aucun log).

redirectionio_pass

Syntaxe : redirectionio_pass ip:port | unix:///path;
Défaut : redirectionio_pass 127.0.0.1:10301;
Contexte : http, server, server if, location, location if

Cette directive spécifie l'emplacement de l'agent redirectionio-agent que le module nginx doit utiliser pour le matching des requêtes. Dans une installation traditionnelle, l'agent est uniquement disponible sur 127.0.0.1:10301. Si vous exposez l'agent via un fichier, la valeur de la directive redirectionio_pass peut, par exemple, être de la forme unix:///var/run/redirectionio.sock.

Cette directive permet également de définir des options de gestion du pool de connexions :

redirectionio_pass 127.0.0.1:10301 min_conns=0 keep_conns=10 max_conns=10 timeout=100;

Tous les paramètres min_conns, keep_conns, max_conns et timeout sont facultatifs :

min_conns (défaut 0) : il s'agit du nombre minimal de connexions TCP établies en permanence entre le module nginx et l'agent redirection.io. Si ces connexions n'existent pas, elles sont créées, même si aucune requête HTTP n'est traitée par le serveur nginx.
max_conns (défaut 10) : il s'agit du nombre maximal de connexions TCP pouvant être établies entre le module nginx et l'agent redirection.io à un instant donné. Si toutes les connexions sont actuellement utilisées, le module attendra pendant la durée du timeout, puis enregistrera une erreur et laissera passer la requête sans la traiter.
keep_conns (défaut 10) : il s'agit du nombre minimal de connexions TCP à maintenir actives une fois qu'elles ont été créées.
timeout (défaut 100) : il s'agit de la durée, en millisecondes, pendant laquelle le module nginx attendra une réponse de l'agent. L'agent redirection.io est très performant et, même avec des centaines de milliers de règles, devrait toujours envoyer une réponse bien plus rapidement que cette valeur de timeout (généralement en moins de 1ms), mais ce paramètre garantit que, même dans des contextes de très forte charge, l'appel à l'agent ne bloquera pas la requête trop longtemps.

Par exemple, avec min_conns=1 keep_conns=10 max_conns=100 timeout=50 :

1 connexion est établie entre nginx et l'agent au démarrage de nginx ;
nginx créera jusqu'à 100 connexions vers l'agent (bien sûr, il réutilise les connexions disponibles) ;
si de nombreuses connexions ont été créées et ne sont plus utiles, elles seront libérées, mais nginx maintiendra 10 connexions actives ;
nginx attendra au maximum 50 millisecondes pour une réponse de l'agent redirection.io.

redirectionio_scheme

Syntaxe : redirectionio_scheme http | https;
Défaut : aucun
Contexte : http, server, server if, location, location if

Cette directive permet de forcer le schéma à utiliser lors du matching de la requête. Ceci est utile si vous avez défini des règles utilisant un déclencheur URL avec une valeur d'URL absolue (contenant un schéma, un nom de domaine, etc.), mais que vous souhaitez utiliser les mêmes règles dans un VirtualHost avec un autre schéma.

Imaginez, par exemple, un VirtualHost écoutant uniquement le trafic HTTPS, utilisant un projet dans lequel les règles sont définies avec le schéma http:// : les URL ne correspondraient jamais, car aucune règle n'utilise le schéma https://. Dans ce cas, régler la valeur de redirectionio_scheme sur http forcera le module à effectuer le matching avec ce schéma, et non le schéma réel de la requête.

redirectionio_host

Syntaxe : redirectionio_host some-host;
Défaut : aucun
Contexte : http, server, server if, location, location if

Cette directive permet de forcer l'hôte à utiliser lors du matching de la requête. Ceci est utile si vous avez défini des règles utilisant des déclencheurs URL avec des valeurs d'URL absolues (contenant un schéma, un nom de domaine, etc.), alors que votre VirtualHost utilise un autre nom d'hôte.

redirectionio_add_rule_ids_header

Syntaxe : redirectionio_add_rule_ids_header on | off;
Défaut : redirectionio_add_rule_ids_header off;
Contexte : http, server, server if, location, location if

Si ce paramètre est activé, un header de réponse nommé X-RedirectionIo-RuleIds sera ajouté à la réponse. Sa valeur contiendra la liste des identifiants de règles redirection.io appliquées à cette réponse, séparés par le caractère ;.

redirectionio_set_header

Syntaxe : redirectionio_set_header X-Custom-Header-Name HeaderValue;
Défaut : aucun
Contexte : http, server, server if, location, location if

Cette directive permet de transmettre la requête au module redirection.io en ajoutant un header de requête rempli avec une valeur donnée. La valeur passée au header peut être une variable nginx, par ex. :

redirectionio_set_header X-GeoIP-Country-Code $geoip_data_country_code;

Cela peut être utile pour transmettre des variables du contexte nginx à l'agent redirection.io, qui peuvent ensuite être utilisées dans les règles de redirection via le déclencheur de header de requête.

redirectionio_trusted_proxies

Syntaxe : redirectionio_trusted_proxies 127.0.0.1,172.18.0.0/24;
Défaut : aucun
Contexte : http, server, server if, location, location if

Cette directive est utilisée par le module pour restreindre quels proxies sont de confiance avant d'évaluer les headers X-Forwarded-*. C'est particulièrement utile lors de l'utilisation du déclencheur par adresse IP, afin de garantir que l'adresse IP évaluée est valide et n'a pas été falsifiée.

La valeur à utiliser pour cette directive est une liste séparée par des virgules de toutes les adresses IP des proxies qui doivent être considérés comme de confiance (une notation CIDR peut être utilisée pour les sous-réseaux).

Questions, réponses et dépannage

Y a-t-il des inconvénients à utiliser le module nginx au lieu du mode "reverse proxy" ?

Bien que cette approche soit intéressante - car elle implique peu de changements dans l'architecture de l'infrastructure et le flux de requêtes de votre pile - elle peut parfois s'avérer complexe à mettre en place :

premièrement, les modules dynamiques nginx sont liés à des versions très spécifiques de nginx. Nous distribuons des modules pré-compilés pour les versions de nginx officiellement fournies par les distributions, mais nous ne pouvons pas distribuer notre module pour toutes les versions de nginx existantes. En d'autres termes, les utilisateurs d'installations nginx personnalisées devront compiler le module nginx eux-mêmes.
le flux de gestion des requêtes nginx n'est pas un long fleuve tranquille 🙂 Autrement dit, selon les modules installés, des comportements inattendus peuvent apparaître, et il n'y a aucun moyen de garantir que notre module s'intégrera parfaitement à votre installation nginx. Par exemple, il peut y avoir des incompatibilités avec d'autres modules.
les modules nginx sont développés en langage C, ce qui ne garantit pas la sécurité mémoire. L'agent redirection.io lui-même, ainsi que la bibliothèque sous-jacente open source libredirectionio, sont des binaires basés sur Rust.
la mise à jour d'un module dynamique nécessite un redémarrage du serveur, ce qui n'est pas toujours souhaitable.
enfin et surtout, l'utilisation du module nginx redirection.io signifie que, pour chaque requête, un appel TCP synchrone est effectué du processus nginx vers l'agent redirection.io. Nous proposons plusieurs directives d'ajustement pour maintenir un pool de connexions, et cela fonctionnera parfaitement sur des sites web à trafic raisonnable, mais cela peut devenir un défi à configurer correctement dans des environnements très exigeants.

C'est pourquoi nous recommandons généralement de privilégier le mode reverse proxy. Cependant, le module nginx est un moyen parfaitement pratique, supporté et entièrement testé d'utiliser redirection.io si vous le souhaitez.

Le module ne peut pas être chargé

Nous distribuons notre module nginx pour de nombreuses distributions, ce qui devrait couvrir la plupart des cas de production. Cependant, il existe une limitation : les paquets que nous proposons ne fonctionneront qu'avec la version par défaut de nginx fournie par la distribution. Pour charger un module nginx, celui-ci doit être binaire-compatible avec la version de nginx installée.

Si vous essayez de charger le module nginx de redirection.io avec une version incompatible de nginx, vous devriez obtenir des messages d'erreur tels que :

nginx: [emerg] module "/usr/share/nginx/modules/ngx_http_redirectionio_module.so" version 1018000 instead of 1024000 in /etc/nginx/modules-enabled/50-mod-http-redirectionio.conf:1

Ainsi, si vous avez installé une version plus récente de nginx - soit en la compilant vous-même, soit en utilisant un dépôt de paquets tiers (par exemple le dépôt de paquets nginx) - alors le module que nous fournissons dans notre propre dépôt de paquets n'est pas binaire-compatible avec la version de nginx que vous utilisez.

Dans ce cas, vous devrez compiler le module nginx de redirection.io vous-même, comme décrit dans le chapitre "Utiliser le module nginx avec une installation nginx non standard" ci-dessous.

La commande reload / restart de nginx ne fonctionne pas et affiche l'erreur `unknown directive "redirectionio_project_key"`

Si nginx ne parvient pas à recharger sa configuration et se plaint d'une directive inconnue redirectionio_project_key, cela peut indiquer que le module nginx n'a pas été correctement chargé.

Veuillez vérifier que votre fichier de configuration principal nginx (généralement /etc/nginx/nginx.conf) contient une ligne pour inclure les modules nginx activés (ex : include /etc/nginx/modules-enabled/*.conf;). Si cette ligne est manquante, vous pouvez forcer le chargement du module en ajoutant la ligne suivante dans /etc/nginx/nginx.conf :

load_module modules/ngx_http_redirectionio_module.so;

Ensuite, redémarrez nginx (à nouveau), et tout devrait rentrer dans l'ordre.

Le module redirige vers un mauvais domaine ou un mauvais port

Dans certaines configurations de production, le serveur nginx n'est pas le premier nœud de l'infrastructure - il peut y avoir un Varnish, un proxy Envoy, un nginx frontal configuré en reverse proxy, etc.

Par défaut, nginx génère un header de redirection Location avec le nom de domaine et le numéro de port avec lesquels il a reçu la requête. Cela signifie que si le module nginx de redirection.io s'exécute dans un serveur nginx écoutant en http (non https) sur le domaine internal sur le port 8080, le header de redirection Location sera de la forme Location: http://internal:8080, ce qui n'est évidemment pas ce que vous souhaitez.

Dans ces cas-là, vous pouvez ajouter la directive absolute_redirect off; dans le VirtualHost où le module redirection.io est activé :

server {
    listen 8080;
    server_name internal;
    root /path/to/root;

    absolute_redirect off;

    ...
    redirectionio_project_key SOME_PROJECT_KEY_HERE;
    ...
}

Cela empêchera nginx de réécrire ou de définir le schéma, l'hôte et le port dans les cibles de redirection utilisant des emplacements relatifs. Cela n'affectera pas les règles de redirection que vous avez créées vers d'autres domaines externes.

Choisir dynamiquement la clé de projet à utiliser

Vous pourriez avoir besoin de gérer plusieurs sites web sous le même VirtualHost nginx, tout en souhaitant conserver des projets redirection.io séparés (pour des raisons organisationnelles, pour déléguer les permissions aux bonnes équipes, etc.).

Dans ce cas, une première solution consiste à utiliser une variable nginx pour définir dynamiquement la clé de projet redirection.io à utiliser.

Dans la section http de la configuration nginx, définissez la variable $project_key :

http {
    ...

	map $http_host $project_key {
		default 'KEY TO BE USED BY DEFAULT';
		'example.com' 'KEY FOR THE example.com PROJECT';
		'second-domain.com' 'KEY FOR THE SECOND PROJECT';
		'fr.example.com' 'KEY FOR THE fr.example.com SUB-DOMAIN PROJECT';
	}
}

Et, dans le VirtualHost, utilisez cette variable :

server {
	listen 80 default_server;
	listen [::]:80 default_server;
	server_name _;
    root /path/to/root;

    ...

    redirectionio_project_key $project_key;
}

Cette configuration permet de :

associer des projets redirection.io à des domaines spécifiques
définir un projet redirection.io par défaut à utiliser pour tous les domaines qui ne sont pas explicitement surchargés.

Dans d'autres configurations de projet, vous souhaiterez peut-être utiliser plusieurs projets redirection.io pour des questions de permissions, sans possibilité de segmentation basée sur le nom de domaine. C'est le cas, par exemple, si votre site web utilise des chemins pour les régions géographiques (/uk/, /us/, /fr/, etc.) et si vous souhaitez restreindre l'accès des contributeurs à une seule région.

Dans ce cas, l'utilisation de la variable nginx $http_host ne sera pas pratique, et vous devrez utiliser le bloc location de nginx :

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;
    root /path/to/root;

    # clé de projet par défaut
    redirectionio_project_key 'CLE A UTILISER PAR DEFAUT';

    location /fr/ {
      redirectionio_project_key 'CLE POUR LE PROJET DE LA REGION fr';
    }

    location /uk/ {
      redirectionio_project_key 'CLE POUR LE PROJET DE LA REGION uk';
    }

    location /us/ {
      redirectionio_project_key 'CLE POUR LE PROJET DE LA REGION us';
    }

    ...
}

Si le VirtualHost contenait déjà des directives dans une location / que vous souhaitez toujours utiliser, vous devrez alors répliquer ces directives dans chacun des blocs location.

Utiliser le module nginx avec une installation nginx non standard

Notre module nginx est l'un des moyens recommandés pour intégrer redirection.io dans les stacks Web. Nous distribuons notre module nginx pour de nombreuses distributions, ce qui devrait couvrir la plupart des cas de production. Cependant, il peut arriver que votre hébergeur ou votre solution de déploiement installe une version personnalisée de nginx, dans des chemins non standard ou avec des dépendances incompatibles.

Cette section vous guidera à travers les étapes pour faire fonctionner notre module nginx avec votre installation nginx, quelle que soit sa configuration. La seule contrainte est la version de nginx, qui doit être au moins 1.9.11.

Télécharger et compiler la bibliothèque libredirectionio

La bibliothèque libredirectionio est une bibliothèque Rust qui traite les redirections et le filtrage à partir des règles créées à l'aide de redirection.io. Cette bibliothèque est utilisée dans nos différents proxies, et spécifiquement dans le module nginx.

Installez les outils de compilation Rust :

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

# RedHat-based distribution
yum install -y epel-release yum-utils wget pcre-devel openssl-devel libxslt-devel gd-devel perl-ExtUtils-Embed GeoIP-devel google-perftools-devel httpd httpd-devel curl
yum -y groupinstall 'Development Tools'
curl https://sh.rustup.rs -sSf | sh

Récupérez les sources de la bibliothèque libredirectionio :

cd /tmp
wget -O libredirectionio-master.zip https://github.com/redirectionio/libredirectionio/archive/master.zip
unzip libredirectionio-master.zip
cd libredirectionio-master

Et compilez la bibliothèque :

autoreconf -i && \
./configure && \
make clean && \
make && \
make install

Si la compilation réussit (cela peut être long), vous devriez obtenir une bibliothèque statique target/release/libredirectionio.so.

Télécharger et compiler les sources du module

Le module nginx de redirection.io est disponible en tant que projet Opensource sur notre compte GitHub.

Tout d'abord, installez quelques outils et utilitaires de compilation :

# Debian-based distribution
apt install nginx gawk libssl-dev libpcre3-dev libzip-dev libxml2-dev libxslt-dev libgd-dev libgeoip-dev libperl-dev

# RedHat-based distribution
yum module enable nginx:1.20 # or whatever version of your choice
yum install nginx

Récupérez les sources du module redirection.io (choisissez la dernière version sur notre dépôt) :

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

Identifiez la version de nginx sur votre système :
```
nginx -v
# affiche :
#   nginx version: nginx/1.18.0
```
Cela signifie que la version de nginx est "1.18.0".
Récupérez les sources de nginx pour cette version (bien sûr, utilisez le bon numéro de version obtenu avec la commande précédente) :
```
cd /tmp
wget http://nginx.org/download/nginx-1.18.0.tar.gz
tar -xzvf nginx-1.18.0.tar.gz
cd nginx-1.18.0
```

Ensuite, compilez le module :

# récupérez vos options locales de configuration nginx
export NGINX_CONFIGURE_ARGUMENTS=`nginx -V 2>&1 | grep 'configure arguments:' | cut -d" " -f3- | sed "s/ --with-cc-opt='/ --with-cc-opt='-I\/tmp\/libredirectionio-master\/target /" | sed "s/ --with-ld-opt='/ --with-ld-opt='-L\/tmp\/libredirectionio-master\/target\/release /"`
eval "./configure $NGINX_CONFIGURE_ARGUMENTS --add-dynamic-module=/tmp/libnginx-mod-redirectionio-master"

# compilez le module
make -j modules

Installer et charger le module dans nginx

L'installation du module est généralement assez simple : il vous suffit de déplacer le fichier compilé dans le bon répertoire.

Habituellement, la commande suivante permet d'afficher l'emplacement du répertoire des modules nginx :

nginx -V 2>&1 | gawk 'match($0,/--modules-path=(\S+?)/,a) {print a[1]}'
# devrait afficher quelque chose comme :
#   /usr/lib/nginx/modules

Ensuite, déplacez le module dans ce répertoire (bien sûr, utilisez le nom du répertoire retourné par la commande ci-dessus) :

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

Dernière étape, vous devez maintenant charger le module dans nginx — pour cela, ajoutez une directive load_module dans le fichier nginx.conf, par exemple :

load_module modules/ngx_http_redirectionio_module.so;

Vous pouvez également ajouter cette ligne dans un fichier séparé pour garder une trace de vos propres modifications. La plupart du temps, le fichier de configuration principal de nginx inclut les fichiers de modules (par exemple, include /etc/nginx/modules-enabled/*.conf;) — n'hésitez donc pas à créer votre propre fichier de configuration /etc/nginx/modules-enabled/mod-http-redirectionio.conf.

Redémarrez nginx, et c'est fini !

sudo systemctl restart nginx.service

Vous pouvez vérifier que le module fonctionne parfaitement en terminant ses étapes de configuration dans le VirtualHost.

Cette page a été mise à jour le 16 avr. 2026

Vous ne trouvez pas votre réponse ?

Contactez notre support