Installer l'agent Linux

Une seule commande installe l'agent, et cette page est ce qui se passe à l'intérieur : d'abord les conditions d'utilisation, puis ce qui est vérifié avant que quoi que ce soit ne soit écrit, chaque question et ce que répond la touche Entrée, les variables d'environnement et les options d'un déploiement sans intervention, une installation à la main, et un hôte sans systemd.

Installation

Une commande, en root. Elle lit la version actuelle dans les métadonnées publiques, télécharge avec votre clé la version compilée pour votre architecture, la vérifie contre SHA256SUMS, l'installe dans /usr/local/bin/reportedip-agent puis configure l'hôte.

curl -fsSL https://reportedip.com/agent/install.sh | REPORTEDIP_KEY=<YOUR-KEY> sh

La clé passe par l'environnement parce qu'elle sert deux fois, une fois pour le téléchargement sous licence et une fois pour enregistrer l'hôte, et la coller deux fois est la façon dont une clé finit sous une forme erronée dans un historique de shell. Omettez la variable et le script demande la clé, avec l'écho du terminal coupé pour qu'elle ne reste pas dans le défilement. La question lit le terminal et non l'entrée standard, car sous la forme ci-dessus l'entrée standard est le script lui-même, et pouvoir ouvrir ce terminal est en même temps le test de savoir s'il y a quelqu'un à qui demander : une exécution depuis cron, depuis une unité systemd ou depuis un outil d'automatisation n'a pas de terminal, n'est pas interrogée et s'arrête sur la ligne qui nomme la variable. Le script est volontairement du sh POSIX : il doit tourner sur des hôtes où bash n'est pas le shell par défaut. Il s'arrête avec une raison nommée et n'installe rien s'il n'est pas lancé en root, si la plateforme n'est pas Linux, si l'architecture n'est ni amd64 ni arm64, si ni curl ni wget n'existe, et si sha256sum manque.

Les deux voies de téléchargement sont volontairement séparées. Les métadonnées de version sont récupérées sans la clé, les fichiers sous licence avec la clé, de sorte que la clé ne part jamais vers une cible de redirection qui ne sert que des métadonnées publiques. Dans le fichier de sommes, seule la ligne de votre architecture est vérifiée, car le fichier liste aussi l'autre.

Ce que install vérifie avant d'écrire

Trois choses sont vérifiées avant que le premier octet n'atteigne le disque, dans l'ordre où une erreur est la moins chère à trouver. Les arguments d'abord, car une faute de frappe dans une option est la même erreur sur tous les hôtes et n'a rien à voir avec ce que cette machine sait faire : un --notify-email mal formé créait auparavant les répertoires d'abord et n'était refusé qu'ensuite. Puis l'hôte, affiché comme un bloc nommé, car celui qui lance ceci doit apprendre que l'agent ne peut pas tourner ici avant d'être envoyé chercher une clé. Puis les questions de la section suivante. La clé en dernier, parce que c'est la seule étape qui coûte un aller-retour réseau et parce qu'une clé tout juste saisie doit être soumise au serveur tout de suite.

requirements:
  ok   systemd      running as pid 1
  ok   firewall     ipset and iptables found, nft as well; auto takes ipset, set backend: nftables in the config if this host's rules live in nftables

Chaque ligne porte une des trois marques. ok est satisfaite, warn manque et n'arrête pas l'exécution, et STOP est la seule marque qui signifie que l'installation s'est arrêtée là. Seul systemd est bloquant, et il est lu sur /run/systemd/system, le répertoire que systemd crée quand il est pid 1, et non sur la présence de systemctl : une image de conteneur peut porter le binaire sans jamais lancer le gestionnaire, et c'est exactement l'hôte qui recevait une installation complète incapable de démarrer. Un moteur de pare-feu manquant est signalé comme warn et n'arrête rien, car le mode signalement seul est une façon prise en charge de faire tourner l'agent, et la ligne nomme le paquet à installer, apt install ipset iptables ou apt install nftables. La clé est soumise à verify-key avant que la configuration soit écrite, et volontairement sans identifiant d'installation : une sonde ne doit pas laisser derrière elle une ligne de registre pour un hôte qui ne sera peut-être jamais installé. Seuls un 401 ou un 403 arrêtent l'exécution, et alors rien n'est sur le disque. Tout le reste, un échec DNS, un proxy, un pare-feu pas encore ouvert, affiche une ligne et l'installation continue, car une installation sans réseau est légitime et la synchronisation réessaie d'elle-même. Ce que install.sh refuse lui-même avant tout cela est indiqué plus haut.

Ce qu'il demande, et ce que répond la touche Entrée

Quatre questions, et seulement sur ce qu'il n'a pas reçu : la clé, l'adresse à laquelle un état défectueux est envoyé par courrier, si une correspondance avec la liste communautaire est rejetée ou seulement journalisé, et si cet hôte bannit aussi ce qu'il attrape dans ses propres journaux. Une exécution qui a reçu les quatre valeurs en options ou en variables d'environnement n'est interrogée sur rien, et c'est ainsi que tourne un déploiement sans intervention, ni plus lent ni plus bavard qu'avant. Tout ce que l'installateur peut trouver lui-même, les ports ssh, les sources de journaux, le moteur de pare-feu, il le trouve au lieu de le demander.

  api key (from your account on https://reportedip.com):
  email for the state mails of this host, Enter for none: ops@example.org
  blocking: the community list is loaded into the kernel either way. What the rules do
            with a match is the question, and this host is set up to deny it: drop is what
            an Enter here writes, so the first sync already stops what the list names.
            log is the other answer, and the one to give for a host you want to watch
            before it denies anything: it counts every match and lets the packet through.
            Neither answer is final. mode: log or mode: drop in the config is one word, and
            the next sync run rebuilds the rules. Your own addresses, the session you are
            sitting in and everything in the whitelist are never blocked in either mode.
  drop or log, Enter for drop:
  local bans: the second switch, and the half that replaces fail2ban. The list above comes
            from the community; this is about the addresses this host catches in its own
            logs, and it is on unless you say otherwise. Every entry has a timeout the
            kernel enforces, so a stopped agent leaves no permanent ban, whitelist add is
            the way out of one, and in mode: log they are recorded and only logged.
  ban what this host finds itself [Y/n]:
  ok   key          accepted, role <your role>, reports today <used>/<limit> (account-wide)
wrote /etc/reportedip-agent/config.yaml (lists [ssh mail web ftp edge], ssh ports [22022], 10 log sources, mode drop)
this host denies every match of the community list and bans what it finds in its own logs
state mails go to ops@example.org; change notify.email in the config to stop or redirect them
units installed; sync timer and log watcher enabled; run: reportedip-agent sync && reportedip-agent status

La clé est lue avec l'écho du terminal coupé, elle reste donc hors du défilement et n'apparaît dans aucune ligne de la sortie. Pour les trois autres questions, la touche Entrée est une réponse valable et prend chaque fois la valeur par défaut : pas d'adresse de courrier, mode: drop, bannissements locaux activés. Un hôte configuré avec trois touches Entrée rejette donc ce que nomme la liste communautaire et bannit ce qu'il trouve dans ses propres journaux, et c'est à cela que sert l'agent. Ce qui rend cela sûr n'est pas la réponse, c'est la liste blanche : les adresses de cet hôte, la session dans laquelle l'installation tourne, RFC1918 et tout ce qui figure dans whitelist.conf ne sont jamais bloqués ni signalés, dans aucun mode, et reportedip-agent whitelist add prend effet sans synchronisation. Les deux dernières questions figurent dans l'installation simple et non derrière une option, parce que ce sont les deux valeurs qui décident si l'hôte fait quelque chose, et parce que la différence est invisible dans systemctl status.

reportedip-agent install --expert, ou REPORTEDIP_EXPERT=1, demande le reste. Huit groupes, chacun derrière une porte [y/N] qu'une touche Entrée saute, et à l'intérieur d'un groupe chaque valeur affiche sa valeur par défaut entre crochets : le flux avec le moteur de pare-feu, l'échelle des bannissements, les seuils de détection, le seuil d'une source d'événements isolée, les limites de fonctionnement avec la journalisation, la remise du courrier y compris un serveur smtp pour un hôte sans MTA local, les ports de la liste ssh, et les sources de journaux détectées, où l'on peut en retirer une et ajouter une que la détection a manquée. Chaque réponse est vérifiée contre la plage que le lecteur de configuration accepte avant de pouvoir être écrite, un 0 pour min_hits revient donc en 0 is outside 1 to 10000 et est redemandé, et la configuration finie passe ensuite par la même validation que l'agent applique en relisant le fichier, ce qui rend impossible une classe de défaut : une réponse qui laisse un hôte enregistré avec un agent qui refuse de démarrer. Le groupe des bannissements affiche l'échelle qu'il vient de construire, time_minutes 45 avec escalate 3 et max_time_minutes 20160 répond donc 45 min, 135 min, 405 min, 1215 min, 3645 min, 10935 min, 14 d (ceiling). mode et ban.enabled ne sont pas redemandés, on y a déjà répondu plus haut. Une exécution experte qui saute chaque groupe écrit octet pour octet le même fichier qu'une simple. Aucune question ne propose le mode expert, il est accessible par l'option et par la variable et par rien d'autre, et sans terminal c'est une erreur et non un retour silencieux à la voie simple.

Sans terminal, rien n'est demandé, et c'est la situation de cron, d'une unité systemd, d'un outil d'automatisation et de l'intégration continue. Un détail y compte : < /dev/null seul ne rend pas une exécution non interactive, car le terminal de contrôle survit à une entrée standard redirigée. setsid le retire, et c'est ce que font ces appelants.

Ce que fait vraiment l'installateur

Tout ce qui suit est idempotent. La même commande sur un hôte qui possède déjà l'agent met à jour le binaire et laisse la configuration exactement telle qu'elle était.

1. Affiche les conditions d'utilisation et attend un yes, sauf si REPORTEDIP_ACCEPT_TERMS=1 est définie. Sans terminal et sans la variable, le script s'arrête ici, avant la clé et avant tout téléchargement.
2. Lit https://reportedip.com/agent/latest sans la clé et en extrait la version. Ce fichier est le même JSON que l'agent interroge lui-même pour les mises à jour.
3. Télécharge reportedip-agent_linux_<arch> et SHA256SUMS avec l'en-tête X-Key dans un répertoire temporaire supprimé sur chaque chemin de sortie.
4. Vérifie la somme de contrôle et n'installe rien en cas d'écart.
5. Installe le binaire en mode 0755 dans /usr/local/bin/reportedip-agent et affiche la version qu'il vient de poser.
6. Redémarre reportedip-agent.service si cette unité est active. C'est important lors d'une mise à jour : le démon de surveillance continuerait sinon à exécuter l'ancien code jusqu'au prochain redémarrage de la machine. L'unité de synchronisation est un oneshot et prend le nouveau binaire d'elle-même au démarrage suivant.
7. Exécute la configuration de l'hôte, sauf si REPORTEDIP_NO_SETUP=1 est définie ou si /etc/reportedip-agent/config.yaml existe déjà. Dans le second cas, il le dit et laisse la configuration tranquille.

La configuration de l'hôte est l'étape qui écrit des fichiers, et c'est la même chose que sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install. Dans l'ordre, une fois passés les conditions d'utilisation, les options, les prérequis et les questions :

• Détecte le port SSH depuis sshd -T, depuis SSH_CONNECTION et depuis les processus sshd à l'écoute, et prend l'union des trois. S'il ne trouve rien, il s'arrête et demande --ssh-port plutôt que de supposer 22.
• Décide lesquelles des cinq listes du flux sont configurées. ssh et edge sont toujours actives. mail, web et ftp s'ajoutent quand une unité correspondante est active ou qu'un port correspondant écoute : un hôte sans serveur web n'obtient donc pas de liste web. Un port ne compte que si quelque chose venu de l'extérieur pourrait l'atteindre : une socket liée uniquement à 127.0.0.1 ou à ::1 n'est pas une surface d'attaque, et elle n'est pas traitée comme telle. C'est la différence entre un serveur de messagerie et un agent de distribution local qui ne prend le courrier que de sa propre machine, et entre un serveur de noms et le résolveur local qui occupe 127.0.0.53:53 sur un hôte Debian ordinaire.
• Détecte les sources de journaux et les écrit explicitement dans la configuration. La détection a lieu une fois, à l'installation, et le résultat reste dans le fichier : un service arrêté pour une maintenance ne doit jamais désactiver une source en silence. Sur un hôte avec panneau de contrôle, les motifs par site du panneau et les journaux par défaut du serveur web sont tous les deux configurés, et pas seulement le premier des deux. Ce ne sont pas deux vues du même trafic : une requête qui n'atteint aucun hôte virtuel doté de son propre access_log tombe dans le journal par défaut, et c'est exactement ce que produit un scanner qui parcourt des adresses au lieu de noms d'hôtes. Sur un hôte de production mesuré, cela représentait 20 453 lignes venant de 466 adresses distinctes en une seule journée. Chaque journal par défaut existant est pris, car nginx devant Apache est la disposition ordinaire d'un panneau et les deux écrivent le leur, et un journal vide compte aussi, puisqu'un journal reste vide jusqu'à ce que quelqu'un frappe. /var/log/apache2/other_vhosts_access.log reste volontairement à l'écart : ses lignes commencent par l'hôte virtuel, l'adresse se trouve donc dans le deuxième champ alors que le détecteur lit le premier, et une source incapable de signaler quoi que ce soit pendant que doctor déclare l'hôte sain est pire que pas de source.
• Appelle verify-key et affiche votre rôle ainsi que les signalements consommés aujourd'hui face à la limite quotidienne. C'est la dernière des trois vérifications et elle a lieu avant la création du premier répertoire, une clé fausse ne coûte donc rien sur le disque. Un 401 ou un 403 ici signifie que la clé est fausse, et c'est le seul défaut à corriger tout de suite.
• Crée /etc/reportedip-agent et /var/lib/reportedip-agent, le second en mode 0700, et corrige le mode d'un répertoire déjà présent.
• Écrit /etc/reportedip-agent/config.yaml en mode 0600. mode et ban.enabled portent les réponses aux questions ci-dessus, et sans rien de passé ni rien de saisi cela donne mode: drop et ban.enabled: true, les deux valeurs que la question ci-dessus a affichées comme sa valeur par défaut. Les deux lignes qui suivent le fichier disent en mots ce que fait l'hôte désormais, car la différence est invisible dans systemctl status. Une configuration existante n'est jamais écrasée : une seconde exécution ne demande rien, relit les deux interrupteurs dans le fichier qu'elle a gardé et peut donc dire it says mode: drop and ban.enabled: true, so that is what this host does; nothing here changed either value. Ne supprimez pas le fichier pour obtenir une installation neuve, sauf si vous acceptez de perdre ces deux décisions ; mettez-le de côté plutôt. La clé passée à cette seconde exécution est ignorée, et elle le dit : the key was ignored because the config already exists; edit api_key in /etc/reportedip-agent/config.yaml to change it.
• Écrit la liste blanche automatique dans le répertoire d'état : l'adresse d'où venait votre session SSH, plus chaque adresse d'interface de l'hôte. L'adresse de session d'une exécution antérieure est conservée, afin qu'une seconde exécution depuis une autre session ne retire pas l'adresse sur laquelle la première comptait. Les adresses d'interface sont redéterminées à chaque exécution, pour qu'une adresse supprimée ne traîne pas.
• Génère l'identifiant d'installation, un UUID v4 aléatoire dans /var/lib/reportedip-agent/install-id. C'est désormais l'identité de ce serveur face à l'API, et elle le reste même si le nom d'hôte voyage à côté d'elle.
• Avertit de trois choses qu'il ne peut pas corriger pour vous : une table nftables inet reportedip laissée par le script shell documenté, quel que soit le moteur ; sur un hôte neuf, des ensembles ipset nommés rip-* que l'agent n'a pas créés, le plus souvent ce même script lancé par une tâche cron, dont il faut reprendre la liste blanche et couper la tâche avant la première synchronisation ; et un nginx qui lit les en-têtes Cloudflare sans set_real_ip_from. La source web compterait alors les adresses de Cloudflare au lieu de celles du visiteur.
• Écrit les trois unités systemd dans /etc/systemd/system, exécute daemon-reload, active reportedip-agent-sync.service, puis active et démarre reportedip-agent-sync.timer et reportedip-agent.service.
• Une fois les unités en place, appelle verify-key une seconde fois, cette fois avec l'identifiant d'installation, ce qui enregistre l'hôte, et affiche de nouveau le rôle et les signalements du jour. Un 401 ou un 403 à ce stade termine l'exécution avec le code de sortie 1 : l'hôte est installé, et c'est api_key dans la configuration qu'il faut corriger.

Les variables d'environnement de install.sh

# Binary only, no host setup: for an image or for Ansible. The
# terms of use are asked before the download, so the variable goes
# here as well.
curl -fsSL https://reportedip.com/agent/install.sh \
  | REPORTEDIP_ACCEPT_TERMS=1 REPORTEDIP_KEY=<YOUR-KEY> REPORTEDIP_NO_SETUP=1 sh

# Later, on the running host, or from your playbook. The key goes
# in the environment and not in an argument, because
# /proc/<pid>/cmdline can be read by every local user of the host.
# sudo clears the environment, so the variable goes in front of it.
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --accept-terms

Installation à la main

L'étape de configuration est une commande à part. Lancez-la quand REPORTEDIP_NO_SETUP=1 n'a posé que le binaire, quand la détection a deviné quelque chose que vous voulez corriger, ou quand un déploiement doit répondre à toutes les questions d'avance. Ce qui est passé en option n'est pas demandé : --key, --notify-email, --mode log|drop, --ban et --no-ban, --log-level debug|info|warn|error, --admin-ip, --ssh-port, --accept-terms, et --expert pour les questions plus fines. --key fonctionne toujours et affiche une ligne disant que sa valeur se trouve dans la liste des processus, où tout utilisateur local de cet hôte peut la lire pendant toute la durée de l'exécution ; passez plutôt la clé comme REPORTEDIP_KEY. sudo efface l'environnement par défaut, la variable se place donc avant sudo et non après. Sur un hôte qui n'a pas encore de configuration, l'exécution commence par les conditions d'utilisation et ne continue qu'après un yes ; l'acceptation est consignée sous /var/lib/reportedip-agent/terms-accepted avec la version du texte et l'heure, et doctor affiche cette ligne. Un hôte déjà configuré n'est pas interrogé de nouveau et reçoit seulement l'adresse des conditions.

# The key goes in the environment. sudo clears the environment by
# default, so the variable belongs in front of sudo; behind it the
# install finds no key and exits 2.
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install

# The detection could not find the SSH port (socket activation,
# a non-standard unit, a port from an include file):
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --ssh-port 2222

# The session address is not where you administer this host from
# (a jump host, a console, a serial connection):
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --admin-ip 203.0.113.0/24

# Arm the state mails at the same time:
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --notify-email ops@example.org

# A rollout that answers everything, so nothing is asked and no
# terminal is needed. Works the same as five environment variables:
# REPORTEDIP_ACCEPT_TERMS, REPORTEDIP_KEY, REPORTEDIP_NOTIFY_EMAIL,
# REPORTEDIP_MODE, REPORTEDIP_BAN
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --accept-terms \
  --notify-email ops@example.org --mode drop --ban

# Everything the four questions do not cover, asked one group at a time:
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --expert

--admin-ip accepte une adresse unique ou une plage CIDR et prend la place de l'adresse de session devinée ; les adresses que des installations précédentes ont écrites dans la liste blanche automatique y restent. Cela vaut la peine dès que la session SSH n'est pas représentative, car l'adresse devinée est ce qui se dresse entre vous et votre propre règle de blocage au premier jour. Toute l'exécution d'installation dispose d'un délai maximal de cinq minutes : un nft ou un systemctl figé se termine donc par une erreur et non par un processus que vous devez interrompre.

Un hôte sans systemd

install ne tourne pas ici. La commande écrit les unités systemd et les active, donc elle refuse un hôte où systemd n'est pas le pid 1 et n'écrit rien, plutôt que de laisser derrière elle une configuration que rien ne démarre jamais. Pour le binaire c'est autre chose : rien en lui ne dépend de systemd, et doctor signale le gestionnaire manquant plutôt que d'échouer. Ce qui reste est une mise en place à la main, et deux choses doivent être préparées sur un tel hôte.

# 1. The feed sync, from cron. Every 15 minutes is safe on any
#    plan: the agent skips a fetch its own plan interval does
#    not allow yet, so nothing is requested too often.
*/15 * * * * root /usr/local/bin/reportedip-agent sync >/dev/null 2>&1
@reboot      root sleep 120 && /usr/local/bin/reportedip-agent sync

# 2. The watch daemon, from your init system. It runs in the
#    foreground, logs to stderr and stops on SIGTERM.
/usr/local/bin/reportedip-agent watch

L'entrée pour le redémarrage n'est pas optionnelle. Les délais d'expiration d'ipset ne survivent pas à un redémarrage, et les ensembles eux-mêmes non plus : sans synchronisation après le démarrage, l'hôte remonte sans règles et sans bannissements restaurés. Sur un hôte systemd, ce chemin est couvert par reportedip-agent-sync.service, activé pour multi-user.target, qui tourne après chaque service de pare-feu et sans décalage aléatoire. Sur un hôte sans journald, laissez log_file défini, car stderr n'y mène peut-être nulle part.

Deux conséquences de cela s'oublient facilement. sync a besoin d'un /etc/reportedip-agent/config.yaml que personne n'a écrit pour vous, car la commande qui en écrit un est celle qui ne tourne pas ici. Et sans l'identifiant d'installation que la même commande génère, cet hôte n'a aucune identité face à l'API, il n'apparaît donc jamais sous Agent Servers et il ne détient aucune licence serveur.

Dernière mise à jour: 30. septembre 2026 · Maintenu par l’équipe ReportedIP