Den Linux-Agenten installieren

Ein Befehl installiert den Agenten, und diese Seite ist das, was darin passiert: zuerst die Nutzungsbedingungen, dann was geprüft wird, bevor etwas geschrieben wird, jede Frage und was ein Enter beantwortet, die Umgebungsvariablen und Flags eines unbeaufsichtigten Rollouts, eine Installation von Hand, und ein Host ohne systemd.

Installation

Ein Befehl, als root. Er liest die aktuelle Version aus den öffentlichen Metadaten, lädt mit Ihrem Key den Build für Ihre Architektur, prüft ihn gegen SHA256SUMS, installiert ihn nach /usr/local/bin/reportedip-agent und richtet danach den Host ein.

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

Der Key steht in der Umgebung, weil er zweimal gebraucht wird, einmal für den lizenzierten Download und einmal für die Registrierung des Hosts, und zweimal einfügen ist die Art, wie ein Key in falscher Form in einer Shell-History landet. Lassen Sie die Variable weg, dann fragt das Skript nach dem Key, mit abgeschaltetem Echo des Terminals, damit er nicht im Scrollback stehen bleibt. Die Abfrage liest das Terminal und nicht die Standardeingabe, denn in der Form oben ist die Standardeingabe das Skript selbst, und ob sich dieses Terminal überhaupt öffnen lässt, ist gleichzeitig die Prüfung, ob jemand da ist, den man fragen kann: ein Lauf aus cron, aus einer systemd-Unit oder aus einem Automatisierungswerkzeug hat kein Terminal, wird nicht gefragt und bricht mit der Zeile ab, die die Variable nennt. Das Skript ist bewusst POSIX-sh: es muss auf Hosts laufen, auf denen bash nicht die Standard-Shell ist. Es bricht mit genanntem Grund und ohne Installation ab, wenn es nicht als root läuft, wenn die Plattform nicht Linux ist, wenn die Architektur weder amd64 noch arm64 ist, wenn weder curl noch wget existiert und wenn sha256sum fehlt.

Die beiden Abrufwege sind absichtlich getrennt. Die Versions-Metadaten werden ohne Key geholt, die lizenzierten Dateien mit Key, damit der Key nie an ein Umleitungsziel geht, das nur öffentliche Metadaten ausliefert. Aus der Prüfsummendatei wird nur die Zeile Ihrer eigenen Architektur geprüft, denn die Datei listet auch die andere.

Was install prüft, bevor es schreibt

Drei Dinge werden geprüft, bevor das erste Byte auf der Platte landet, in der Reihenfolge, in der ein Fehler am günstigsten zu finden ist. Zuerst die Argumente, denn ein Tippfehler in einem Flag ist auf jedem Host derselbe Fehler und hat nichts damit zu tun, was diese Maschine kann: ein kaputtes --notify-email legte früher erst die Verzeichnisse an und wurde danach abgelehnt. Dann der Host, ausgegeben als benannter Block, denn wer das hier startet, soll erfahren, dass der Agent auf diesem Host nicht laufen kann, bevor er losgeschickt wird, einen Key zu suchen. Dann die Fragen des nächsten Abschnitts. Zuletzt der Key, weil das der einzige Schritt ist, der einen Netzzugriff kostet, und weil ein gerade eingegebener Key sofort gegen den Server gehalten werden soll.

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

Jede Zeile trägt eine von drei Marken. ok ist erfüllt, warn fehlt und hält den Lauf nicht auf, und STOP ist die einzige Marke, die je bedeutet, dass die Installation hier geendet hat. Hart ist nur systemd, und es wird an /run/systemd/system abgelesen, dem Verzeichnis, das systemd als pid 1 anlegt, und nicht am Vorhandensein von systemctl: ein Container-Image kann das Binary tragen, ohne den Manager je zu starten, und genau dieser Host bekam früher eine vollständige Installation, die nie starten konnte. Ein fehlendes Firewall-Backend wird als warn gemeldet und hält nichts auf, denn Report-only ist eine unterstützte Betriebsart des Agenten, und die Zeile nennt das Paket, das zu installieren ist, apt install ipset iptables oder apt install nftables. Der Key geht an verify-key, bevor die Config geschrieben wird, und bewusst ohne Install-ID: eine Probe darf keine Registry-Zeile für einen Host zurücklassen, der vielleicht nie installiert wird. Nur ein 401 oder ein 403 hält den Lauf auf, und dann liegt nichts auf der Platte. Alles andere, ein DNS-Fehler, ein Proxy, eine noch nicht geöffnete Firewall, druckt eine Zeile und die Installation läuft weiter, denn eine Installation ohne Netz ist legitim und der Sync-Lauf versucht es von selbst erneut. Was install.sh selbst schon vorher ablehnt, steht weiter oben.

Was er fragt, und was ein Enter beantwortet

Vier Fragen, und nur nach dem, was er nicht bekommen hat: der Key, die Adresse, an die ein kaputter Zustand gemailt wird, ob ein Treffer der Community-Liste verworfen oder nur protokolliert wird, und ob dieser Host auch das sperrt, was er in seinen eigenen Logs findet. Ein Lauf, der alle vier Werte als Flags oder als Umgebungsvariablen mitbekommen hat, wird nichts gefragt, und genau so läuft ein unbeaufsichtigter Rollout, weder langsamer noch gesprächiger als vorher. Alles, was der Installer selbst herausfinden kann, die SSH-Ports, die Log-Quellen, das Firewall-Backend, findet er heraus, statt zu fragen.

  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

Der Key wird mit abgeschaltetem Echo des Terminals gelesen, bleibt also aus dem Scrollback heraus und steht in keiner Zeile der Ausgabe. Bei den anderen drei Fragen ist ein Enter eine gültige Antwort und nimmt jedes Mal den Default: keine Mailadresse, mode: drop, lokale Sperren an. Ein Host, der mit drei Enter eingerichtet wurde, verwirft also, was die Community-Liste nennt, und sperrt, was er in seinen eigenen Logs findet, und dafür ist der Agent da. Sicher macht das nicht die Antwort, sondern die Whitelist: die Adressen dieses Hosts, die Sitzung, in der die Installation läuft, RFC1918 und alles in whitelist.conf werden in keinem Modus geblockt und in keinem Modus gemeldet, und reportedip-agent whitelist add wirkt ohne Sync. Die letzten zwei Fragen stehen im einfachen Installationsweg und nicht hinter einem Flag, weil es die zwei Werte sind, die entscheiden, ob der Host überhaupt etwas tut, und weil der Unterschied in systemctl status nicht zu sehen ist.

reportedip-agent install --expert, oder REPORTEDIP_EXPERT=1, fragt den Rest. Acht Gruppen, jede hinter einem [y/N]-Tor, das ein Enter überspringt, und innerhalb einer Gruppe zeigt jeder Wert seinen Default in Klammern: der Feed samt Firewall-Backend, die Eskalationsleiter, die Erkennungsschwellen, die Schwelle einer einzelnen Event-Quelle, die Betriebsgrenzen samt Logging, die Mail-Zustellung einschließlich eines SMTP-Servers für einen Host ohne lokalen MTA, die Ports der ssh-Liste und die erkannten Log-Quellen, wo eine herausgenommen und eine von der Erkennung verpasste hinzugefügt werden kann. Jede Antwort wird gegen den Bereich geprüft, den der Konfigurationsparser akzeptiert, bevor sie geschrieben werden kann, eine 0 bei min_hits kommt also als 0 is outside 1 to 10000 zurück und wird erneut gefragt, und die fertige Konfiguration läuft danach durch dieselbe Prüfung, die der Agent beim Lesen der Datei macht. Damit ist eine Fehlerklasse unmöglich: eine Antwort, die einen registrierten Host mit einem Agenten hinterlässt, der nicht startet. Die Ban-Gruppe gibt die Leiter aus, die sie gerade gebaut hat, time_minutes 45 mit escalate 3 und max_time_minutes 20160 antwortet also mit 45 min, 135 min, 405 min, 1215 min, 3645 min, 10935 min, 14 d (ceiling). mode und ban.enabled werden nicht ein zweites Mal gefragt, die sind oben beantwortet. Ein Expertenlauf, der jede Gruppe überspringt, schreibt byteweise dieselbe Datei wie ein einfacher. Keine Frage bietet den Expertenmodus an, er ist über das Flag und die Variable erreichbar und sonst nicht, und ohne Terminal ist er ein Fehler und kein stiller Rückfall auf den einfachen Weg.

Ohne Terminal wird nichts gefragt, und das ist die Lage von cron, einer systemd-Unit, eines Automatisierungswerkzeugs und von CI. Ein Detail sollten Sie dort kennen: < /dev/null allein macht einen Lauf nicht nicht-interaktiv, denn das Controlling-Terminal überlebt eine umgeleitete Standardeingabe. setsid entfernt es, und genau das tun diese Aufrufer.

Was der Installer wirklich tut

Alles hier ist idempotent. Derselbe Befehl auf einem Host, der den Agenten schon hat, aktualisiert die Binärdatei und lässt die Konfiguration genau so, wie sie war.

1. Zeigt die Nutzungsbedingungen und nimmt ein yes entgegen, außer REPORTEDIP_ACCEPT_TERMS=1 ist gesetzt. Ohne Terminal und ohne die Variable endet das Skript hier, vor der Frage nach dem Key und vor jedem Download.
2. Liest https://reportedip.com/agent/latest ohne Key und holt die Version daraus. Diese Datei ist dasselbe JSON, das der Agent selbst für Updates abfragt.
3. Lädt reportedip-agent_linux_<arch> und SHA256SUMS mit dem Header X-Key in ein temporäres Verzeichnis, das bei jedem Beenden gelöscht wird.
4. Prüft die Prüfsumme und installiert bei einer Abweichung nichts.
5. Installiert die Binärdatei mit Modus 0755 nach /usr/local/bin/reportedip-agent und gibt die gerade abgelegte Version aus.
6. Startet reportedip-agent.service neu, wenn diese Unit gerade aktiv ist. Das ist bei einem Upgrade wichtig: der Watch-Daemon würde sonst bis zum nächsten Reboot den alten Code weiterlaufen lassen. Die Sync-Unit ist ein Oneshot und nimmt die neue Binärdatei beim nächsten Start von allein.
7. Führt die Host-Einrichtung aus, es sei denn, REPORTEDIP_NO_SETUP=1 ist gesetzt oder /etc/reportedip-agent/config.yaml existiert schon. Im zweiten Fall sagt er das und lässt die Konfiguration in Ruhe.

Die Host-Einrichtung ist der Schritt, der Dateien schreibt, und sie ist dasselbe wie sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install. Der Reihe nach, sobald Nutzungsbedingungen, Flags, Anforderungen und Fragen erledigt sind:

• Erkennt den SSH-Port aus sshd -T, aus SSH_CONNECTION und aus den lauschenden sshd-Prozessen und nimmt die Vereinigung der drei. Findet er nichts, bricht er ab und fragt nach --ssh-port, statt 22 anzunehmen.
• Entscheidet, welche der fünf Feed-Listen konfiguriert werden. ssh und edge sind immer an. mail, web und ftp kommen dazu, wenn eine passende Unit aktiv ist oder ein passender Port lauscht. Ein Host ohne Webserver bekommt also keine Web-Liste. Ein Port zählt nur, wenn ihn von außen etwas erreichen könnte: ein Socket, der allein auf 127.0.0.1 oder ::1 gebunden ist, ist keine Angriffsfläche und wird auch nicht als eine behandelt. Das ist der Unterschied zwischen einem Mailserver und einem lokalen Zusteller, der nur Mail von der eigenen Maschine annimmt, und der Unterschied zwischen einem Nameserver und dem Stub-Resolver, der auf einem normalen Debian-Host 127.0.0.53:53 hält.
• Erkennt die Log-Quellen und schreibt sie ausdrücklich in die Config. Erkannt wird einmal, zur Installationszeit, und das Ergebnis bleibt in der Datei: ein Dienst, der für eine Wartung gestoppt ist, darf eine Quelle nie stillschweigend abschalten. Auf einem Host mit Control Panel werden die Pro-Site-Globs des Panels und die Standardlogs des Webservers beide konfiguriert und nicht nur das erste der beiden. Das sind nicht zwei Blicke auf denselben Verkehr: eine Anfrage, die keinen virtuellen Host mit eigenem access_log erreicht, landet im Standardlog, und genau das produziert ein Scanner, der Adressen statt Hostnamen abklappert. Auf einem gemessenen Produktionshost waren das 20.453 Zeilen von 466 verschiedenen Adressen an einem einzigen Tag. Jedes vorhandene Standardlog wird genommen, denn nginx vor Apache ist das gewöhnliche Panel-Layout und beide schreiben ihr eigenes, und ein leeres zählt auch, denn ein Log ist leer, bis jemand klopft. /var/log/apache2/other_vhosts_access.log bleibt bewusst draußen: seine Zeilen beginnen mit dem virtuellen Host, die Adresse steht also im zweiten Feld, während der Detektor das erste liest, und eine Quelle, die nichts melden kann, während doctor den Host gesund nennt, ist schlimmer als keine Quelle.
• Ruft verify-key auf und gibt Ihre Rolle und die heute verbrauchten Reports gegen das Tageslimit aus. Das ist die letzte der drei Prüfungen und sie läuft, bevor das erste Verzeichnis angelegt wird, ein falscher Key kostet also nichts auf der Platte. Ein 401 oder 403 hier heißt, der Key ist falsch, und das ist der eine Fehler, der sofort behoben werden sollte.
• Legt /etc/reportedip-agent und /var/lib/reportedip-agent an, das zweite mit Modus 0700, und korrigiert den Modus eines Verzeichnisses, das schon da war.
• Schreibt /etc/reportedip-agent/config.yaml mit Modus 0600. mode und ban.enabled tragen die Antworten aus den Fragen oben, und wenn nichts mitgegeben und nichts getippt wurde, ist das mode: drop und ban.enabled: true, also die zwei Werte, die die Frage oben als ihren Default gedruckt hat. Die zwei Zeilen nach der Datei sagen in Worten, was der Host jetzt tut, denn der Unterschied ist in systemctl status nicht zu sehen. Eine bestehende Config wird nie überschrieben: ein zweiter Lauf fragt nichts und sagt the key was ignored because the config already exists; edit api_key in /etc/reportedip-agent/config.yaml to change it, und liest beide Schalter aus der Datei zurück, die er behalten hat, kann also it says mode: drop and ban.enabled: true, so that is what this host does; nothing here changed either value sagen. Löschen Sie die Datei nicht, um eine frische Installation zu bekommen, es sei denn, Sie wollen diese zwei Entscheidungen verlieren; schieben Sie sie stattdessen beiseite.
• Schreibt die Auto-Whitelist ins State-Verzeichnis: die Adresse, von der Ihre SSH-Sitzung kam, plus jede Interface-Adresse des Hosts. Die Sitzungsadresse eines früheren Laufs bleibt erhalten, damit ein zweiter Lauf aus einer anderen Sitzung nicht die Adresse entfernt, auf die der erste sich verlassen hat. Interface-Adressen werden bei jedem Lauf neu ermittelt, damit eine entfernte Adresse nicht hängen bleibt.
• Erzeugt die Install-ID, eine zufällige UUID v4 in /var/lib/reportedip-agent/install-id. Das ist ab dann die Identität dieses Servers gegenüber der API, und sie bleibt diese Identität, auch wenn der Hostname daneben mitgeht.
• Warnt vor drei Dingen, die er nicht für Sie beheben kann: einer nftables-Tabelle inet reportedip, die das dokumentierte Shell-Skript hinterlassen hat, gleich welches Backend gilt; auf einem frischen Host vor ipset-Sets namens rip-*, die nicht der Agent angelegt hat, meist dasselbe Skript aus einem Cron-Job, dessen Whitelist vor dem ersten Sync übernommen und dessen Job abgeschaltet sein muss; und einem nginx, der Cloudflare-Header liest, ohne set_real_ip_from zu setzen. Die Web-Quelle würde dann Cloudflare-Adressen zählen statt der des Besuchers.
• Schreibt die drei systemd-Units nach /etc/systemd/system, führt daemon-reload aus, aktiviert reportedip-agent-sync.service und aktiviert und startet reportedip-agent-sync.timer sowie reportedip-agent.service.
• Wenn die Units stehen, ruft er verify-key ein zweites Mal auf, jetzt mit der Install-ID, was den Host registriert, und gibt Rolle und die heutigen Reports noch einmal aus. Ein 401 oder 403 an dieser Stelle beendet den Lauf mit Exit 1: der Host ist installiert, zu korrigieren ist api_key in der Config.

Die Umgebungsvariablen von 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 von Hand

Der Einrichtungsschritt ist ein eigener Befehl. Führen Sie ihn aus, wenn REPORTEDIP_NO_SETUP=1 nur die Binärdatei abgelegt hat, wenn die Erkennung etwas geraten hat, das Sie korrigieren wollen, oder wenn ein Rollout jede Frage vorab beantworten muss. Was als Flag mitkommt, wird nicht gefragt: --key, --notify-email, --mode log|drop, --ban und --no-ban, --log-level debug|info|warn|error, --admin-ip, --ssh-port, --accept-terms und --expert für die feineren Fragen. --key funktioniert weiter und druckt eine Zeile, die sagt, dass sein Wert in der Prozessliste steht, wo ihn jeder lokale Benutzer dieses Hosts so lange lesen kann, wie der Lauf dauert; geben Sie den Key stattdessen als REPORTEDIP_KEY mit. sudo löscht die Umgebung per Default, die Variable gehört also vor sudo und nicht dahinter. Auf einem Host, der noch keine Konfiguration hat, beginnt der Lauf mit den Nutzungsbedingungen und geht nur nach einem yes weiter; die Annahme wird mit der Version des Textes und dem Zeitpunkt unter /var/lib/reportedip-agent/terms-accepted festgehalten, und doctor zeigt diese Zeile. Ein Host, der schon eingerichtet ist, wird nicht noch einmal gefragt und bekommt nur die Adresse der Bedingungen genannt.

# 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 nimmt eine einzelne Adresse oder einen CIDR-Bereich und tritt an die Stelle der geratenen Sitzungsadresse. Adressen, die frühere Install-Läufe in die Auto-Whitelist geschrieben haben, bleiben dort stehen. Das lohnt sich immer dann, wenn die SSH-Sitzung nicht repräsentativ ist, denn die geratene Adresse ist das, was am ersten Tag zwischen Ihnen und Ihrer eigenen Blockregel steht. Der ganze Install-Lauf hat eine Frist von fünf Minuten, ein hängendes nft oder systemctl endet also mit einem Fehler und nicht mit einem Prozess, den Sie abbrechen müssen.

Ein Host ohne systemd

install läuft hier nicht. Der Befehl schreibt die systemd-Units und aktiviert sie, also weist er einen Host ab, auf dem systemd nicht PID 1 ist, und schreibt nichts, statt eine Konfiguration zurückzulassen, die nie etwas startet. Beim Binary ist es anders: nichts darin hängt an systemd, und doctor meldet den fehlenden Manager, statt abzubrechen. Was bleibt, ist eine Einrichtung von Hand, und zwei Dinge müssen auf so einem Host eingerichtet werden.

# 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

Der Eintrag für den Reboot ist nicht optional. ipset-Timeouts überleben keinen Reboot, und die Sets selbst auch nicht, ohne einen Sync nach dem Boot kommt der Host also ohne Regeln und ohne wiederhergestellte Sperren hoch. Auf einem systemd-Host deckt das reportedip-agent-sync.service ab, das für multi-user.target aktiviert ist, nach jedem Firewall-Dienst läuft und keinen Zufallsversatz hat. Lassen Sie auf einem Host ohne journald log_file gesetzt, denn stderr führt dort möglicherweise ins Nichts.

Zwei Folgen davon werden leicht übersehen. sync braucht eine /etc/reportedip-agent/config.yaml, die Ihnen niemand geschrieben hat, denn der Befehl, der eine schreibt, ist der Befehl, der hier nicht läuft. Und ohne die Install-ID, die derselbe Befehl erzeugt, hat dieser Host gegenüber der API keine Identität, erscheint also nie unter Agent Servers und hält keine Serverlizenz.

Zuletzt aktualisiert: 30. September 2026 · Betreut vom ReportedIP-Team