Module nginx

Nous fournissons un module nginx, qui expose redirection.io directement dans votre configuration nginx. L'utilisation de ce module est l'une des méthodes conseillées pour intégrer redirection.io dans votre infrastructure.

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'intègre, de manière très rapide et performante :

une requête entrante est interceptée par le module nginx de redirection.io

Installation du module

Distributions Debian et basées sur APT

Si vous utilisez une distribution Linux Debian ou basée sur 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 12 (Bookworm)

URL source du dépôt: bookworm main

Debian 11 (Bullseye)

URL source du dépôt: bullseye main

Debian 10 (Buster)

URL source du dépôt: buster main

Ubuntu 24.04 LTS (Noble Numbat)

URL source du dépôt: noble main

Ubuntu 22.04 LTS (Jammy Jellyfish)

URL source du dépôt: jammy main

Ubuntu 20.04 LTS (Focal Fossa)

URL source du dépôt: focal main

Installez le paquet apt-transport-https :

sudo apt-get install apt-transport-https

Importez notre clé de 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 notre URL de 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/2 bookworm 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 fait ! redirection.io est installé et opérationnel. Vous pouvez poursuivre avec la configuration nginx de redirection.io et devriez voir des logs en quelques minutes 🎉

Distributions Red Hat et basées sur 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/2/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 fait ! redirection.io est installé et opérationnel. Vous pouvez poursuivre avec la configuration nginx de redirection.io et devriez voir des logs en quelques minutes 🎉

Rôle Ansible

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

ansible-galaxy install redirectionio.nginx_module

Ce rôle installe le module nginx de redirection.io et s'assure que vous utilisez les bons emplacements de dépôt, en fonction du système d'exploitation de votre hôte. Il prend en charge les distributions Linux basées sur Debian et RHEL.

Configuration

L'activation de redirection.io est aussi simple que de déclarer la clé de projet dans le Virtualhost ou le nœud de configuration où vous souhaitez activer redirection.io.

Par exemple, cela peut se trouver dans votre directive serveur principale :

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

Ou dans un Virtualhost :

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

Ou même dans un répertoire :

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

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

La redirectionio_project_key peut être entre guillemets doubles ou non (par exemple, SOME_PROJECT_KEY_HERE ou "SOME_PROJECT_KEY_HERE").

Directives de configuration du module

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

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 un emplacement particulier :

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 some_key;
Défaut : none
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. Une fois 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 de correspondance actuel (cependant, veuillez noter que les logs ne seront envoyés que si les directives redirectionio et redirectionio_logs sont toutes deux définies sur on. En d'autres termes, définir redirectionio_logs sur on avec redirectionio 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'redirectionio-agent que le module nginx doit utiliser pour les requêtes correspondantes. Dans une configuration traditionnelle, l'agent n'est disponible qu'à 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.

À partir de la version 2.2.0, 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 optionnels :

min_conns (par défaut 0) : c'est le nombre minimal de connexions TCP qui sont é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 (par défaut 10) : c'est le nombre maximal de connexions TCP qui peuvent être établies entre le module nginx et l'agent redirection.io à un moment donné. Si toutes les connexions sont actuellement utilisées, le module attendra la durée timeout, puis enregistrera une erreur et laissera la requête passer sans la traiter.
keep_conns (par défaut 10) : c'est le nombre minimal de connexions TCP à maintenir actives une fois qu'elles ont été créées.
timeout (par défaut 100) : c'est 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 1 ms), 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 lorsque nginx est démarré ;
nginx créera jusqu'à 100 connexions à 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 : none
Contexte : http, server, server if, location, location if
Disponible depuis : 2.0.0

Cette directive permet de forcer le schéma à utiliser lors de la correspondance de la requête. Ceci est utile si vous avez défini des règles utilisant un déclencheur d'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 en utilisant le schéma http:// : les URL ne seraient jamais mises en correspondance, car aucune règle n'utilise le schéma https://. Dans ce cas, définir la valeur redirectionio_scheme à http forcera le module à effectuer la correspondance avec ce schéma, et non le schéma réel de la requête.

redirectionio_host

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

Cette directive permet de forcer l'hôte à utiliser lors de la correspondance de la requête. Ceci est utile si vous avez défini des règles utilisant des déclencheurs d'URL avec des valeurs d'URL absolues (contenant un schéma, un nom de domaine, etc.), et 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
Disponible depuis : 2.0.0

Si ce paramètre est activé, un en-tête de réponse nommé X-RedirectionIo-RuleIds sera ajouté à la réponse. Sa valeur contiendra la liste des identifiants des 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 : none
Contexte : http, server, server if, location, location if
Disponible depuis : 2.2.0

Cette directive permet de passer la requête au module redirection.io en ajoutant un en-tête de requête rempli d'une valeur donnée. La valeur passée à l'en-tête peut être une variable nginx, par exemple :

redirectionio_set_header X-GeoIP-Country-Code $geoip_data_country_code;

Ceci peut être utile pour passer des variables du contexte nginx à l'agent redirection.io, qui peuvent être utilisées dans les règles de redirection via le trigger d'en-tête de requête.

redirectionio_trusted_proxies

Syntaxe : redirectionio_trusted_proxies 127.0.0.1,172.18.0.0/24;
Défaut : none
Contexte : http, server, server if, location, location if
Disponible depuis : 2.3.0

Cette directive est utilisée par le module pour restreindre les proxys considérés comme fiables avant d'évaluer les en-têtes X-Forwarded-*. Ceci est particulièrement utile lors de l'utilisation du déclencheur d'adresse IP, afin de s'assurer 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 proxys qui doivent être considérés comme fiables (il peut s'agir d'une notation CIDR pour les sous-réseaux).

Dépannage

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 de nginx par défaut fournie par la distribution. Pour charger un module nginx, il doit être compatible binaire avec la version de nginx installée.

Si vous tentez 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 compatible binaire 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 "Utilisation du module nginx avec une installation nginx non standard" ci-dessous.

La commande de rechargement/redémarrage de nginx ne fonctionne pas et renvoie des erreurs `unknown directive "redirectionio_project_key"`

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

Veuillez vérifier que votre fichier de configuration nginx principal (généralement /etc/nginx/nginx.conf) contient une ligne pour inclure les modules nginx activés (par exemple, 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 (encore une fois), et tout devrait rentrer dans l'ordre.

Le module redirige vers un mauvais domaine, ou vers 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é comme un proxy inverse, etc.

Par défaut, nginx générera un en-tête Location de redirection 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 sur un serveur nginx écoutant en http (pas https) sur le domaine internal sur le port 8080, l'en-tête Location des redirections sera de la forme Location: http://internal:8080, ce qui n'est évidemment pas ce que vous voulez.

Dans ces cas, 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/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 d'organisation, pour déléguer les permissions aux bonnes équipes, etc.)

Dans ce cas, une première solution peut être d'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 :

mapper les 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 surchargés.

Dans d'autres configurations de projet, vous voudrez toujours utiliser plusieurs projets redirection.io, à des fins de permissions, sans la possibilité de segmenter en fonction du 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 'KEY TO BE USED BY DEFAULT';
      
    location /fr/ {
      redirectionio_project_key 'KEY FOR THE fr region PROJECT';
    }

    location /uk/ {
      redirectionio_project_key 'KEY FOR THE uk region PROJECT';
    }

    location /us/ {
      redirectionio_project_key 'KEY FOR THE us region PROJECT';
    }
    
    ...
}

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

Utilisation du module nginx avec une installation nginx non standard

Notre module nginx est l'une des méthodes recommandées pour intégrer redirection.io dans les piles 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 fournisseur d'hébergement ou votre solution de provisionnement installe une version personnalisée de nginx, dans des chemins non standard ou avec des dépendances incompatibles.

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

Télécharger et construire 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 avec redirection.io. Cette bibliothèque est utilisée dans nos divers proxys, et spécifiquement dans le module nginx.

Installez les outils de compilation Rust :

# Distribution basée sur Debian
apt install autoconf build-essential curl wget unzip
curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain 1.76.0 -y

apt install cargo wget unzip

# Distribution basée sur Red Hat
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

Obtenez 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 construisez 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 construire le code source du module

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

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

# Distribution basée sur Debian
apt install nginx gawk libssl-dev libpcre3-dev libzip-dev libxml2-dev libxslt-dev libgd-dev libgeoip-dev libperl-dev

# Distribution basée sur Red Hat
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 de 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 de votre système :
```
nginx -v
# affiche :
#   nginx version: nginx/1.18.0
```
Cela signifie que la version de nginx est "1.18.0".
Obtenez les sources de nginx pour cette version (bien sûr, utilisez le bon numéro de version, à partir de la commande ci-dessus) :
```
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, construisez le module :

# récupérez vos options de configuration nginx locales
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"

# construisez le module
make -j modules

Installer et charger le module dans nginx

L'installation du module devrait être assez simple dans la plupart des cas - il suffit de déplacer le fichier compilé vers le bon dossier.

Généralement, la commande suivante devrait 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 dossier (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 nginx.conf, quelque chose comme :

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 nginx principal inclut des fichiers de module (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 le tour est joué !

sudo systemctl restart nginx.service

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

Cette page a été mise à jour le 30 juin 2025

Vous ne trouvez pas votre réponse ?

Contactez notre support