Référence de configuration de l'agent

La configuration par défaut de l'agent se trouve dans le fichier /etc/redirectionio/agent.yml.

Configuration minimale

Après avoir installé l'agent, vous devez modifier ce fichier afin d'insérer le nom de votre instance redirection.io. Voici la configuration minimale :

# name of this instance, mandatory for logging
instance_name: "A UNIQUE NAME"

Référence de configuration

L'agent supporte cependant d'autres clés d'options, détaillées dans les sections ci-dessous.

instance_name

Type : string
Par défaut : -
Cette directive est requise

La directive de configuration instance_name permet de donner un nom unique à cette instance d'agent. Vous devez utiliser un nom unique pour ce paramètre pour tous les agents exécutés pour votre projet. Sinon, l'agent apparaîtra comme "mal configuré" sur le tableau de bord du projet (son nom sera le nom d'hôte du serveur exécutant l'agent), et ses journaux seront ignorés.

Une bonne idée peut être d'utiliser une combinaison du nom d'hôte et de l'environnement de déploiement comme instance_name. De plus, rappelez-vous que vous pouvez utiliser des variables d'environnement n'importe où dans le fichier de configuration.

listen

Type : string
Par défaut : 127.0.0.1:10301
Cette directive est optionnelle

La directive de configuration listen détermine sur quelle interface l'agent écoute. Elle est par défaut à 127.0.0.1:10301 (port 10301 sur l'hôte local), mais peut prendre d'autres valeurs :

/var/run/redirectionio.sock : si vous préférez utiliser un fichier, assurez-vous que l'utilisateur exécutant l'agent (redirectionio, par défaut) a le droit de créer ce fichier
"" : une chaîne vide, si vous voulez que votre agent écoute sur toutes les interfaces réseau, sur le port 10301 (non conseillé)

persist

Type : boolean
Par défaut : true
Cette directive est optionnelle

La directive de configuration persist permet de définir si les règles doivent être stockées sur le disque. Cela permet de redémarrer l'agent avec des règles existantes sans avoir besoin d'appeler le backend de redirection.io, et ajoute bien sûr plus de résilience à votre configuration.

datadir

Type : string
Par défaut : /var/lib/redirectionio
Cette directive est optionnelle

Si la directive persist est activée, datadir définit le répertoire où les règles seront persistées sur le système de fichiers local. Bien sûr, l'utilisateur exécutant redirectionio-agent doit avoir la permission d'écriture sur ce répertoire.

cache

Type : integer
Par défaut : 10000
Cette directive est optionnelle

La directive de configuration cache définit le nombre de versions compilées des règles qui seront stockées en mémoire (RAM). Ce paramètre rend l'agent beaucoup plus rapide, mais peut consommer plus de mémoire sur de très grands jeux de règles s'il est défini à une valeur élevée.

La valeur par défaut est 10000, ce qui devrait utiliser environ 150-200 Mo de mémoire pour un très grand jeu de règles. Il n'est pas nécessaire de définir cette valeur beaucoup plus haut, car l'agent mettra en cache en priorité les chemins fréquemment utilisés.

Vous pouvez complètement désactiver le cache de règles en mémoire, afin de minimiser l'utilisation de la mémoire, en définissant cache: 0

logging

Type : boolean
Par défaut : undefined
Cette directive est optionnelle

Le paramètre logging permet de définir le comportement de journalisation pour cette instance. S'il est défini à "true", l'instance sera marquée comme autorisée à journaliser le trafic. S'il est défini à "false", l'instance ne collectera pas les journaux de trafic. Si ce paramètre n'est pas défini, ou défini avec toute autre valeur que "true" ou "false", il sera géré par la valeur définie dans l'interface graphique du gestionnaire. Sinon, ce paramètre prime sur le comportement de journalisation défini dans l'interface graphique du gestionnaire.

test_mode

Type : boolean
Par défaut : undefined
Cette directive est optionnelle

Le paramètre test_mode permet de définir cette instance en mode "test". Si ce paramètre n'est pas défini, ou défini avec toute autre valeur que "true" ou "false", il sera géré par la valeur définie dans l'interface graphique du gestionnaire. Sinon, ce paramètre prime sur le comportement de journalisation défini dans l'interface graphique du gestionnaire. S'il est activé, la valeur du paramètre "logging" sera forcée à "false".

project_keys

Type : list of strings
Par défaut : []
Cette directive est optionnelle

Le paramètre project_keys permet de précharger l'agent avec certains jeux de règles de projets au démarrage. Si cette directive n'est pas définie, l'agent démarrera avec un jeu de règles vide, et il ne chargera les règles de votre ou vos projets que lorsque la première requête arrivera.

Afin d'éviter que les premières requêtes ne échouent (parce que le jeu de règles ne serait pas chargé à temps), vous pouvez utiliser cette directive de configuration pour définir une liste de clés de projet à charger au démarrage de l'agent.

proxies

Cette section optionnelle permet d'exécuter l'agent en tant que proxy inverse au lieu de le faire fonctionner uniquement comme un serveur. Si cette section est manquante dans le fichier de configuration, l'agent ne fonctionnera tout simplement pas comme un proxy inverse.

Le nœud de configuration proxies est un tableau qui peut contenir une ou plusieurs configurations de proxy inverse. Pour chaque proxy que vous devez définir, utilisez les directives de configuration décrites dans les sections ci-dessous.

Voici un exemple de configuration de proxy :

proxies:
    -
        listen: "127.0.0.1:80"
        forward: "http://localhost:8080/"
        project_key: "SOME_PROJECT_KEY_HERE"
        preserve_host: true

Dans cette configuration, le proxy écoutera le trafic HTTP, ce qui signifie que l'agent inspectera les requêtes qui arrivent avec le schéma http. Par conséquent, une requête sur http://example.com/demo sera considérée comme une requête pour le schéma http, le nom d'hôte example.com et le chemin demo.

Comme l'indicateur preserve_host est défini à true, la requête sera transmise au service backend (à http://localhost:8080/) avec un en-tête de requête Host: example.com.

Veuillez noter que, si le proxy redirection.io est situé derrière un logiciel de terminaison SSL (HAProxy, Varnish, nginx, Envoy, ou tout autre proxy inverse) et reçoit des requêtes qui sont transmises par ce proxy, ces requêtes seront considérées comme des requêtes http, et non https. Cependant, si vous avez correctement configuré la directive trusted_proxies, le proxy intégré de redirectionio-agent fera confiance à l'en-tête Forwarded, s'il est présent, puis se rabattra sur l'en-tête X-Forwarded-Proto, puis utilisera l'URI de la requête.

En d'autres termes, cela signifie que, dans le cas où des requêtes HTTPS sont reçues dans votre infrastructure par un proxy inverse SSL, puis transmises au proxy redirectionio-agent en tant que requêtes http, elles seront toujours considérées comme des requêtes https par le moteur de routage de redirection.io (et elles seront journalisées en tant que requêtes https), tant que le proxy inverse SSL ajoute l'en-tête Forwarded ou X-Forwarded-Proto et que l'adresse IP du proxy inverse est listée dans la directive trusted_proxies.

listen

Type : string
Par défaut : -
Cette directive est requise

L'adresse de l'interface à écouter, sous la forme adresse:port. Les valeurs valides sont, par exemple, 0.0.0.0:80, 0.0.0.0:443 (pour écouter sur toutes les interfaces réseau), 127.0.0.1:8080, etc. Les requêtes HTTP(s) reçues sur cette interface seront analysées et éventuellement transmises à l'adresse forward, si nécessaire.

L'écoute sur un port privilégié peut nécessiter des autorisations supplémentaires, vous devrez donc peut-être exécuter le binaire redirectionio-agent avec un utilisateur disposant des autorisations appropriées.

Lors de l'écoute sur le port 443, vous pouvez vous attendre à des requêtes chiffrées SSL. Dans ce cas, vous devez configurer les directives de configuration tls_cert_file et tls_key_file (voir ci-dessous).

forward

Type : string
Par défaut : -
Cette directive est optionnelle depuis la version 2.6.0. Elle était requise dans les versions précédentes.

L'adresse de l'interface vers laquelle transmettre les requêtes HTTP, sous la forme schéma://adresse:port. Les valeurs valides sont, par exemple, http://127.0.0.1:8080, https://192.168.0.30:443, etc.

Avant la version 2.6.0, cette directive était requise. Depuis la version 2.6.0, elle est optionnelle. Si aucune valeur n'est fournie pour la clé forward (ou si la directive de configuration est complètement supprimée), aucune requête ne sera transmise à un backend. Dans ce cas, l'agent renvoie soit une réponse générée à l'aide d'une règle redirection.io (si une règle correspond à la requête), soit une réponse d'erreur 404, si aucune règle ne correspond.

project_key

Type : string
Par défaut : -
Cette directive est requise

C'est la clé de projet à utiliser pour ce proxy HTTP. Les requêtes HTTP reçues par ce proxy seront comparées au jeu de règles de ce projet redirection.io, et les transformations définies dans les règles (redirections, etc.) exécutées directement au niveau du proxy.

access_log

Type : boolean
Par défaut : false
Cette directive est optionnelle
Disponible depuis : 2.6.0

Si ce paramètre est activé (avec la valeur true), il produira des journaux de requêtes HTTP, avec le niveau info. Les journaux d'accès sont ajoutés sous la forme :

INFO [2023-03-14][14:10:49] [access] 127.0.0.1 "GET /example-request HTTP/1.1" 200 50055 "-" "Demo/1.0.0" 0.032220

Chaque ligne de journal contient respectivement :

le niveau de journal (INFO)
la date (2023-03-14) et l'heure (14:10:49) de la requête
l'adresse IP du client (127.0.0.1)
la méthode HTTP (GET)
l'URL de la requête (/example-request)
la version HTTP utilisée (HTTP/1.1)
le code de statut de la réponse (200)
la taille de la réponse, en octets, y compris les en-têtes HTTP (50055)
le Referer (- si non fourni)
le User-Agent (Demo/1.0.0)
le temps mis pour servir la requête (en secondes avec 6 décimales)

Ces journaux d'accès sont produits dans tous les loggers définis sous la section log du fichier de configuration de l'agent.

add_rule_ids_header

Type : boolean
Par défaut : false
Cette directive est optionnelle
Disponible depuis : 2.2.5

Si ce paramètre est activé (valeur true), un en-tête 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 ;.

allow_invalid_certificates

Type : boolean
Par défaut : false
Cette directive est optionnelle
Disponible depuis : 2.5.2

Si ce paramètre est activé (valeur true), l'agent autorisera le transfert de requêtes vers des backends SSL avec des certificats invalides. Si le backend est un simple backend HTTP, ce paramètre n'a aucun effet. Si le paramètre allow_invalid_certificates est désactivé (c'est-à-dire non défini ou défini à false) et que le backend SSL sert des certificats invalides, le proxy renverra une réponse 503 Service not available.

allow_ipv6_forward

Type : boolean
Par défaut : false
Cette directive est optionnelle
Disponible depuis : 2.6.0

Cette directive permet d'utiliser IPv6 pour le transfert des requêtes vers le backend.

La valeur configurée comme adresse du serveur backend peut être une adresse IPv4, une adresse IPv6 ou un nom d'hôte :

si une adresse IPv4 est utilisée, le routage vers le backend sera effectué en utilisant IPv4
si une adresse IPv6 est utilisée, le routage vers le backend sera effectué en utilisant IPv6
si un nom d'hôte est utilisé, le routage vers le backend sera effectué en utilisant IPv4 ou IPv6, selon la valeur de allow_ipv6_forward :
- si allow_ipv6_forward est false, la résolution DNS sera effectuée en utilisant le champ A, et le routage sera exclusivement effectué en utilisant IPv4
- si allow_ipv6_forward est true, la résolution DNS sera effectuée en utilisant les champs A et AAAA, et le routage sera effectué aléatoirement en utilisant IPv4 ou IPv6

Veuillez noter que cette option est désactivée par défaut, car le support IPv6 est toujours considéré comme expérimental dans le proxy inverse de l'agent redirection.io.

compress

Type : boolean
Par défaut : false
Cette directive est optionnelle
Disponible depuis : 2.5.0

Si ce paramètre est activé (valeur true), le proxy inverse de l'agent enverra des réponses compressées au client, en fonction de la valeur de l'en-tête de requête Accept-Encoding.

Si ce paramètre est désactivé, l'agent renvoie toujours des réponses non compressées.

keep_alive.enabled

Type : boolean
Par défaut : true
Cette directive est optionnelle
Disponible depuis : 2.7.0

Cette directive de configuration permet de définir s'il faut utiliser ou non une connexion HTTP persistante entre le proxy redirection.io et le serveur backend.

Pour désactiver keepalive, définissez la configuration de cette manière :

  keep_alive:
    enabled: false

Lorsque keep_alive est désactivé, une nouvelle connexion au serveur backend sera créée pour chaque requête entrante. Désactiver keep_alive peut aider à résoudre les situations où le backend ne prend pas correctement en charge la réutilisation des mêmes connexions.

override_matching_request_host

Type : string
Par défaut : -
Cette directive est optionnelle
Disponible depuis : 2.3.0

Cette directive permet de forcer le nom d'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.), alors que le proxy reçoit les requêtes en utilisant un autre nom d'hôte.

Veuillez noter que, la plupart du temps, vous devriez préférer l'utilisation de la directive trusted_proxies conjointement avec l'en-tête de requête X-Forwarded-Host correct.

override_matching_request_scheme

Type : string
Par défaut : -
Valeurs possibles : http ou https
Cette directive est optionnelle
Disponible depuis : 2.3.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 une définition de proxy avec un autre schéma.

Imaginez, par exemple, une définition de proxy écoutant uniquement le trafic https, utilisant un projet dans lequel les règles sont définies à l'aide du schéma http:// : les URL ne seraient jamais mises en correspondance, car aucune règle n'utilise le schéma https://. Dans ce cas, la définition de la valeur override_matching_request_scheme à http forcera le module à effectuer la correspondance avec ce schéma, et non le schéma réel de la requête.

Veuillez noter que, la plupart du temps, vous devriez préférer l'utilisation de la directive trusted_proxies conjointement avec l'en-tête de requête X-Forwarded-Scheme correct.

preserve_host

Type : boolean
Par défaut : false
Cette directive est optionnelle

Ce paramètre permet de transmettre l'en-tête Host à la destination de transfert, afin que votre application backend puisse utiliser la valeur du nom d'hôte. La plupart du temps, vous devriez vouloir activer cette option.

Si cette option est désactivée (false), la requête sera transmise au backend forward en utilisant le nom d'hôte défini dans l'adresse forward.

request_body_size_limit

Type : string
Par défaut : 2MiB
Cette directive est optionnelle
Disponible depuis : 2.4.2

Ce paramètre permet de définir une limite pour la taille du corps de la requête. Les valeurs valides sont des chaînes de la forme <nombre><unité>, où <unité> peut être l'une des suivantes : B, KiB, MiB, GiB (unités du système binaire) ou KB, MB, GB, etc. (unités du système décimal). L'<unité> peut être en minuscules.

timeout

Type : int
Par défaut : 0
Cette directive est optionnelle
Disponible depuis : 2.7.0

Cette valeur définit un délai d'attente, en secondes, pour les requêtes transmises au serveur backend. En d'autres termes, si le serveur backend n'envoie pas de réponse dans le délai défini par la valeur de configuration timeout, la connexion backend sera abandonnée et une réponse 504 sera renvoyée au client.

Si la valeur 0 est utilisée, aucun délai d'attente ne sera appliqué, ce qui signifie que la connexion restera active jusqu'à ce que le backend la ferme. Il peut être judicieux de définir une valeur de délai d'attente au cas où votre serveur backend serait très lent. Par exemple, définir timeout: 30 garantira qu'aucune requête ne passera plus de 30 secondes.

tls_cert_file

Type : string
Par défaut : -
Cette directive est optionnelle

Si ce proxy écoute sur le port 443 ou est censé recevoir du trafic https, veuillez définir dans la directive tls_cert_file le chemin absolu vers un fichier de certificat SSL, dans un emplacement lisible par le binaire redirectionio-agent.

tls_key_file

Type : string
Par défaut : -
Cette directive est optionnelle

Si ce proxy écoute sur le port 443 ou est censé recevoir du trafic https, veuillez définir dans la directive tls_key_file le chemin absolu vers un fichier de clé SSL, dans un emplacement lisible par le binaire redirectionio-agent.

trusted_proxies

Type : list of strings
Par défaut : []
Cette directive est optionnelle
Disponible depuis : 2.3.0

Cette directive est utilisée par l'agent pour restreindre les proxys qui sont 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 d'adresses IP de proxys séparées par des virgules qui doivent être considérées comme fiables (il peut également s'agir d'une notation CIDR pour les sous-réseaux). Par exemple :

trusted_proxies: ['192.168.10.7', '192.168.11.0/28']

Cette option est disponible depuis la version 2.3.0.

metrics_server

Type : string
Par défaut : -
Cette directive est optionnelle
Disponible depuis : 2.2.0
Sera déprécié dans : 3.0.0 (remplacé par metrics)

L'adresse de l'interface de surveillance http à écouter, sous la forme adresse:port. Les valeurs valides sont, par exemple, 0.0.0.0:8080 (pour écouter sur toutes les interfaces réseau), 127.0.0.1:8080, etc. Décommenter cette option active un point de terminaison HTTP qui sert un flux JSON contenant des métriques.

Voici un exemple de réponse :

[
    {
        "id": "5e11a6df-3a1a-4f30-ba91-3c79715857d2:60c680c1-3a5b-491f-a3e4-d701a82d64cd",
        "name": "example-com",
        "rules": 4242,
        "milliseconds_since_last_update": 14452,
        "last_update_duration": 325,
        "log_buffer_size": 1233,
        "total_requests": 18279
    },
    {
        "id": "fe75016c-1b78-4e6b-a769-3ecd38c4c4b1:2552637c-1080-4069-960a-07da9eb25bc3",
        "name": "other-example-com",
        "rules": 117392,
        "milliseconds_since_last_update": 13273,
        "last_update_duration": 1581,
        "log_buffer_size": 899,
        "total_requests": 21924
    }
]

Les clés du tableau JSON sont les clés de projet pour les projets redirection.io dont cette instance d'agent a connaissance.

metrics

Lors de l'exécution d'une infrastructure, les opérateurs ont souvent besoin de surveiller le fonctionnement des services et de pouvoir détecter si des problèmes sont sur le point de se produire.

L'agent redirection.io fournit un point de terminaison de surveillance optionnel, qui expose plusieurs métriques destinées à être chargées par votre tableau de bord de surveillance préféré.

Voici un exemple de configuration de métriques :

metrics:
    listen: 127.0.0.1:31401
    format: "prometheus" # "json" or "prometheus"

listen

Type : string
Par défaut : -
Cette directive est optionnelle
Disponible depuis : 2.4.1

Décommenter cette option active un point de terminaison HTTP qui sert un flux JSON contenant des métriques (voir l'option format ci-dessous).

format

Type : string
Par défaut : json
Valeurs possibles : json ou prometheus
Cette directive est optionnelle
Disponible depuis : 2.4.1

Ce paramètre définit le format des données exposées par le point de terminaison de surveillance.

Lorsque le format est défini comme json (qui est la valeur par défaut), une requête sur l'adresse d'écoute des métriques génère une réponse de la forme :

[
    {
        "id": "5e11a6df-3a1a-4f30-ba91-3c79715857d2:60c680c1-3a5b-491f-a3e4-d701a82d64cd",
        "name": "example-com",
        "rules": 4242,
        "milliseconds_since_last_update": 14452,
        "last_update_duration": 325,
        "log_buffer_size": 1233,
        "total_requests": 18279
    },
    {
        "id": "fe75016c-1b78-4e6b-a769-3ecd38c4c4b1:2552637c-1080-4069-960a-07da9eb25bc3",
        "name": "other-example-com",
        "rules": 117392,
        "milliseconds_since_last_update": 13273,
        "last_update_duration": 1581,
        "log_buffer_size": 899,
        "total_requests": 21924
    }
]

Les clés du tableau JSON sont les clés de projet pour les projets redirection.io dont cette instance d'agent a connaissance.

Le format peut également être défini comme prometheus, ce qui expose alors un format compatible avec Prometheus, avec plus d'informations disponibles :

métriques globales de l'agent :
- process_cpu_seconds_total : Temps CPU total utilisateur et système passé, en secondes.
- process_max_fds : Nombre maximal de descripteurs de fichiers ouverts autorisés pour le processus de l'agent.
- process_open_fds : Nombre de descripteurs de fichiers ouverts.
- process_resident_memory_bytes : Taille de la mémoire résidente, en octets.
- process_start_time_seconds : Heure de démarrage du processus depuis l'époque Unix en secondes.
- process_threads : Nombre de threads OS dans le processus.
- process_virtual_memory_bytes : Taille de la mémoire virtuelle en octets.
métriques par projet :
- redirectionio_matching_requests : Nombre de fois qu'une requête correspondante a été exécutée par le routeur
- redirectionio_rules_count : Nombre de règles dans le routeur
- redirectionio_last_update_duration : Durée, en millisecondes, de la dernière mise à jour
- redirectionio_logs_buffer_size : Taille en mémoire du tampon de journaux, en octets
- redirectionio_duration_since_last_update : Durée depuis la dernière mise à jour du routeur, en millisecondes
- redirectionio_duration_since_last_matching_request : Durée depuis la dernière requête de routage, en millisecondes

log

Cette section optionnelle contient des directives pour configurer la journalisation de l'agent. Chaque sous-section est optionnelle et indépendante des autres. Si cette section est manquante dans le fichier de configuration, l'agent ne journalisera pas les erreurs ou les avertissements.

file

Cette sous-section peut contenir des directives pour la journalisation des fichiers.

level

Type : string
Par défaut : info
Cette directive est optionnelle

Ceci fixe la verbosité du journal. Il peut s'agir de debug, info, error.

path

Type : string
Par défaut : -
Cette directive est requise

Chemin du fichier journal dans lequel écrire. Veuillez vous assurer que l'utilisateur exécutant l'agent (redirectionio, par défaut) a le droit de créer ce fichier.

stderr

Utilisez stderr pour afficher les messages de journalisation sur la sortie d'erreur standard.

level

Type : string
Par défaut : info
Cette directive est requise

Ceci fixe la verbosité du journal. Il peut s'agir de debug, info, error.

syslog

Cette sous-section peut contenir des directives pour la journalisation syslog.

network

Type : string
Par défaut : ""
Cette directive est requise

Le type de connexion à utiliser ("", udp ou tcp). Utilisez une chaîne vide ("") pour utiliser un serveur syslog local.

address

Type : string
Par défaut : ""
Cette directive est requise

L'adresse du serveur de journalisation à utiliser. Utilisez une chaîne vide ("") pour utiliser un serveur syslog local. Pour utiliser un serveur distant, ou un serveur fonctionnant sur un port non standard, utilisez une chaîne de la forme adresse:port, par exemple 192.168.0.30:514.

level

Type : string
Par défaut : info
Cette directive est requise

Ceci fixe la verbosité du journal. Il peut s'agir de debug, info, error.

Utiliser les variables d'environnement dans le fichier de configuration

Il est possible d'utiliser des variables d'environnement dans le fichier de configuration, ce qui peut être utile dans des environnements dynamiques comme les déploiements basés sur le cloud :

Voir cet exemple :

instance_name: "${REDIRECTIONIO_INSTANCE_NAME}"
datadir: "${REDIRECTIONIO_APPLICATION_DIR}/rules"
log:
    file:
        level: info
        path: "${REDIRECTIONIO_APPLICATION_DIR}/log/agent.log"

Dans cet exemple, les variables d'environnement REDIRECTIONIO_INSTANCE_NAME et REDIRECTIONIO_APPLICATION_DIR doivent être définies au démarrage de l'agent (bien sûr, vous pouvez utiliser n'importe quel nom pour les variables d'environnement). Si elles ne sont pas définies, les variables seront remplacées par une chaîne vide :

$ redirectionio-agent
level=error msg="[server] The agent is Misconfigured: The 'instance_name' is not defined."

Lorsque les variables d'environnement requises sont définies, elles sont interprétées lors du démarrage de l'agent :

$ export REDIRECTIONIO_INSTANCE_NAME=example-agent
$ export REDIRECTIONIO_APPLICATION_DIR=/tmp/redirectionio
$ redirectionio-agent
level=info msg="redirectionio-agent (version: 2.2.6, build date: 2021-08-05T13:25:14Z)" instance_name=example-agent
...

Si elle est définie, la variable d'environnement spéciale HTTPS_PROXY sera utilisée par l'agent pour acheminer les communications avec les API redirection.io via un proxy https.

Exemple complet

Voici un exemple de configuration complet, à titre de référence :

# Name of this instance, mandatory for logging
instance_name: "A UNIQUE NAME"

# Interface listening. "" for all interfaces (not advised)
# /run/redirectionio.sock or 127.0.0.1:10301
listen: 127.0.0.1:10301
#listen: /run/redirectionio.sock # If you use a file, please make sure that user running the agent has the right to create it

# Whether or not to store rules on the disk.
# This allows to restart the agent with existing rules without the need to call redirection.io's backend
persist: true

# Directory where the rules will be persisted
datadir: /var/lib/redirectionio
  
# This setting allows to define the logging behavior for this instance. If it is set to "true", the instance will
# be marked as allowed to log traffic. If it is set to "false", the instance will not collect traffic logs.
# If this setting is not defined, or defined with any other value than "true" or "false", it will be managed
# by the value defined in the manager graphical interface. Else, this setting takes precedence over the logging
# behavior defined in the manager graphical interface.
logging: true

# This setting allows to set this instance in "test" mode. If this setting is not defined, or defined
# with any other value than "true" or "false", it will be managed by the value defined in the
# manager graphical interface. Else, this setting takes precedence over the logging behavior defined in the
# manager graphical interface. If it is enabled, the value of the "logging" setting will be forced to "false".
test_mode: false

# Number of items to store in memory.
# This makes the agent much faster, but will consume more memory on very large rulesets if this setting is high
# With the default value, a very large ruleset should consume about 150-200 MB of memory
# Set to 0 to disable the cache and minimize memory usage
cache: 10000

# Keys of projects to preload
# This allows to preload the agent with some projects rulesets at startup time
project_keys:
    - "A VALID PROJECT KEY"

# Run the agent as a reverse proxy
# Leave it empty to disable the reverse proxy feature
proxies:
    -
        listen: "0.0.0.0:80"
        forward: "http://127.0.0.1:8080"
        project_key: "A PROJECT KEY"
        preserve_host: true # Preserve host header, defaults to false
        add_rule_ids_header: true # Add a X-RedirectionIo-RuleIds response header, defaults to false
        compress: true # compress the responses, depending on the Accept-encoding header
    -
        listen: "0.0.0.0:443"
        forward: "http://192.168.1.47:80"
        project_key: "A SECOND PROJECT KEY"
        preserve_host: true # Preserve host header
        tls_cert_file: /path/to/ssl/cert.pem
        tls_key_file: /path/to/ssl.key
    -
        listen: "0.0.0.0:9080"
        forward: "https://192.168.1.47:443"
        project_key: "A THIRD PROJECT KEY"
        preserve_host: true
        compress: true
        allow_invalid_certificates: true # allow proxifying requests to the SSL backend, served with invalid certificates
    -
        listen: "127.0.0.1:8080"
        forward: "http://127.0.0.1:8081"
        project_key: "A FOURTH PROJECT KEY"
        preserve_host: true # Preserve host header, defaults to false
        trusted_proxies:
            - "127.0.0.1"
            - "192.168.10.0/28"
    -
        listen: "127.0.0.1:8081"
        forward: "http://127.0.0.1:8090"
        project_key: "A FIFTH PROJECT KEY"
        preserve_host: true # Preserve host header, defaults to false
        override_matching_request_scheme: https
        override_matching_request_host: "example.com"
    -
	    # proxify the incoming requests to the host resolved at "some-other-domain.tld", with this domain as the Host of the request
	    # use for this proxy configuration the same project key as the first proxy defined above
        listen: "127.0.0.1:8083"
        forward: "http://some-other-domain.tld:80"
        project_key: "A PROJECT KEY"
        preserve_host: false
        # enable access logs, to log all the requests
        access_log: true
    -
	    # receive requests on port 8404
	    # return a response built with redirection.io, if a rule matches,
	    # or a 404 otherwise (as no forward is defined)
        listen: "127.0.0.1:8404"
        project_key: "A PROJECT KEY"

# Define the metrics monitoring endpoint configuration. This enables a http endpoint which serves some metrics about the agent
metrics:
    # Where the metrics server should listen, example values: 127.0.0.1:8080, 0.0.0.0:8080, /run/redirectionio-metrics.sock
    listen: 127.0.0.1:31401
    # Metrics format, can either be "json" or "prometheus", defaults to "json"
    format: "prometheus"

# Sets log configuration. Each section is optional and independent of one another.
log:
    file:
        level: debug
        path: /proc/self/fd/2

    stderr:
        level: info

    syslog:
        # pushes to the local syslog
        network: "" # empty string
        address: "" # empty string
        level: info
        tag: redirectionio-agent

Options de ligne de commande de l'agent

L'agent redirection.io prend en charge plusieurs options de ligne de commande :

$ redirectionio-agent --help

Usage of redirectionio-agent:
  --config-file string
        Use this option to explicitly pass a configuration file
  --debug
        Enable debug mode
  --test
        Test config and exit, return non zero exit code if there is an error in the config
  --version
        Show version and exit

Fichier de configuration défini au démarrage

Par défaut, l'agent démarrera en utilisant un fichier de configuration /etc/redirectionio/agent.yml ou $HOME/.redirectionio/agent.yml. Si nécessaire, vous pouvez également passer l'option --config-file pour forcer un fichier de configuration donné :

/usr/bin/redirectionio-agent --config-file /path/to/some/configuration/directory/some-config-file.yml

Niveau de débogage

L'option --debug donne plus de détails sur le comportement de l'agent. Vous pouvez l'utiliser pour dépanner votre installation de l'agent redirection.io :

/usr/bin/redirectionio-agent --debug

Test de configuration

L'option --test permet de tester le fichier de configuration et d'obtenir des informations sur les erreurs de configuration. Cette commande renvoie un code non nul lorsque l'agent n'est pas correctement configuré, vous pouvez donc l'utiliser dans des scripts de provisionnement pour ne redémarrer/recharger l'agent que lorsque la configuration est correctement définie.

/usr/bin/redirectionio-agent --test

time="2021-05-03T12:42:42+00:00" level=info msg="redirectionio-agent (version: 2.2.0, build date: 2021-05-03T12:42:00Z)" instance_name=example-com

Cette option est disponible depuis la version 2.2.0.

Obtenir la version actuelle de l'agent

L'option --version affiche le nom de la version de l'agent redirection.io installé :

/usr/bin/redirectionio-agent --version

2.3.0

Cette option est disponible depuis la version 2.2.0.

Utiliser l'agent derrière un proxy HTTPS

Dans certaines configurations d'entreprise, il peut être compliqué d'obtenir une connexion directe entre l'agent et les API redirection.io. Certaines architectures d'hébergement exigent que les connexions aux services externes passent par un proxy d'entreprise.

L'agent redirection.io est capable d'utiliser un proxy https pour communiquer avec les API redirection.io. Cela peut être fait en utilisant une variable d'environnement HTTPS_PROXY :

HTTPS_PROXY=http://192.168.0.254:8443 /usr/bin/redirectionio-agent

Veuillez noter que la variable d'environnement peut être en minuscules ou en majuscules, les deux fonctionnent. Si vous utilisez un proxy http, utilisez la variable d'environnement HTTP_PROXY.

Cette option est disponible depuis la version 2.2.4.

Ajuster le fichier de service redirectionio-agent

Si vous avez installé l'agent en utilisant nos paquets APT officiels ou nos paquets RPM officiels, vous pourriez avoir besoin de surcharger le fichier de service systemd fourni avec le paquet. Cela peut être fait de manière élégante en utilisant systemctl :

$ sudo systemctl edit redirectionio-agent.service

Dans l'éditeur, collez ce qui suit :

[Service]
Environment="https_proxy=http://192.168.0.254:8443"

Ensuite, redémarrez l'agent, il devrait utiliser le proxy configuré :

$ sudo systemctl restart redirectionio-agent.service

Pour supprimer cette surcharge de service, supprimez le fichier de surcharge :

$ sudo rm -Rf /etc/systemd/system/redirectionio-agent.service.d
$ sudo systemctl daemon-reload
$ sudo systemctl restart redirectionio-agent.service

Si vous avez besoin d'inclure plusieurs variables d'environnement, vous pouvez utiliser la surcharge suivante (où /etc/environment est un fichier contenant les variables d'environnement) :

[Service]
EnvironmentFile=/etc/environment

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

Vous ne trouvez pas votre réponse ?

Contactez notre support