Den Linux-Agenten konfigurieren

Jeder Schlüssel von /etc/reportedip-agent/config.yaml mit Standardwert und Wertebereich, die Erkennungsgrenzen pro Quelle, die Eskalationsleiter, die Betriebsgrenzen, die Mail, die ankommt, wenn etwas nicht stimmt, und welche Änderung beim nächsten Sync, bei einem Neustart oder innerhalb einer Minute greift.

Konfiguration

Eine Datei, eine Whitelist, ein State-Verzeichnis. Was der Installer schreibt, passt schon zum Host; die meisten Installationen ändern überhaupt nur zwei Dinge, den Wert von mode und ob lokales Blocken an ist.

Jeder Schlüssel von config.yaml

Pflicht ist nur api_key. Jeder andere Schlüssel hat den Standard aus der Tabelle, und ein Schlüssel, den Sie weglassen, behält diesen Standard. Ein Wert außerhalb seines Bereichs ist ein Fehler, der den Schlüssel nennt, und wird nie stillschweigend gekappt. Punkte in den Namen unten sind Verschachtelung: ban.enabled ist ein enabled:, eingerückt unter ban:.

Eine vollständige Datei, die der Parser annimmt, mit jedem Block, den ein normaler Host benutzt:

# /etc/reportedip-agent/config.yaml   root:root 0600
api_key: "YOUR_API_KEY"
api_url: https://reportedip.com/wp-json/reportedip/v2

log_level: warn              # debug | info | warn | error
log_file: /var/log/reportedip-agent.log
log_max_mb: 10
log_keep: 3
auto_update: true

backend: auto                # auto | ipset | nftables
mode: drop                   # log | drop | off
confidence: 90               # the feed threshold
limit: 50000

lists:                       # ssh, edge and group are always on
  ssh:
    ports: [22]              # written by install from the real listener
  edge: {}
  mail: {}
  web: {}

min_entries:                 # below this many addresses a list is not applied
  ssh: 1000
  mail: 500
  web: 500
  ftp: 500
  edge: 1000

whitelist_file: /etc/reportedip-agent/whitelist.conf

min_hits: 5                  # the global detection pair
window_minutes: 10
web_min_hits: 50             # the web source uses its own
web_window_minutes: 120
dedup_hours: 6
queue_max: 5000
disk_min_mb: 200

sources:                     # detected at install time
  - type: sshd
  - type: web
    glob: /var/www/*/log/access.log
  - type: web-error
    path: /var/log/nginx/error.log
  - type: postfix
    path: /var/log/mail.log
  - type: dovecot
    path: /var/log/mail.log
  - type: scan               # the kernel log; adds the port scan rule

thresholds: {}               # per event source overrides, see below

ban:                         # block local finds, not only the feed
  enabled: true
  time_minutes: 30
  max_time_minutes: 10080
  escalate: 4
  memory_hours: 24

notify:
  email: ""                  # empty means no mail
  cooldown_hours: 24
  relay: true                # through reportedip.com, from Professional

Erkennungsgrenzen, pro Quelle

Ein Schwellwert ist ein Paar: wie viele Treffer, innerhalb wie vieler Minuten. Das ist dieselbe Idee wie maxretry und findtime eines fail2ban-Jails. Drei Ebenen entscheiden, welches Paar für eine Ereignisquelle gilt, und die erste mit einer Antwort gewinnt.

Der Schlüssel unter thresholds ist die Ereignisquelle aus dieser Tabelle, nicht der Quelltyp aus sources. Beide Zahlen müssen mindestens 1 sein. Ein thresholds-Block, ein Eintrag pro Quelle, die Sie ändern wollen:

thresholds:
  # A resolver that sees a lot of refused queries: fewer minutes,
  # more hits.
  named:
    hits: 40
    window_minutes: 5
  # A mail server whose customers keep mistyping passwords: SASL a
  # little more forgiving, Dovecot untouched.
  postfix-sasl:
    hits: 6
    window_minutes: 60
  # An exposed SSH port, stricter than the global pair.
  sshd:
    hits: 3
    window_minutes: 10

Ein höherer Schwellwert macht den Agenten stiller und lässt langsame Angreifer durch. Ein niedrigerer ist die Richtung, die etwas kostet: unterhalb von etwa drei Treffern pro Stunde auf einer Mail- oder Web-Quelle melden Sie irgendwann einen Kunden mit einem falschen Passwort im Mailprogramm, und ein Report ist innerhalb der Community öffentlich.

Eine Größe ist nicht konfigurierbar. Eine Adresse mit Bann-Historie braucht weniger Treffer als eine unbekannte: eine frühere Sperre zählt eine Zeile doppelt, zwei dreifach, dann fünffach und neunfach. Das Gewicht wird auf den Schwellwert der jeweiligen Ereignisquelle gekappt, eine zehnte Sperre macht also aus einer einzelnen Zeile keinen Report.

Bann-Grenzen

Fünf Werte im ban-Block, jeder in der im Schlüssel genannten Einheit. Sie gelten nur für Adressen, die der Agent in Ihren eigenen Logs gefunden hat. Die Community-Liste hat überhaupt keine Sperrzeit, sie wird bei jedem Feed-Durchlauf komplett ersetzt. Mit den Standardwerten wird eine Adresse, die wiederkommt, erst 30 Minuten gesperrt, dann 2 Stunden, 8 Stunden, 32 Stunden und 128 Stunden, danach für die Obergrenze von 7 Tagen.

# Careful: a short first ban, a low cap, a long memory.
ban:
  enabled: true
  time_minutes: 10
  max_time_minutes: 1440     # one day
  escalate: 3
  memory_hours: 72

# Strict: a long first ban and a hard escalation.
ban:
  enabled: true
  time_minutes: 60
  max_time_minutes: 43200    # thirty days
  escalate: 6
  memory_hours: 168          # a week

Betriebsgrenzen

Diese Werte begrenzen, was der Agent selbst verbraucht. Sie sind keine Stellschrauben für die Erkennung, und die zwei, die sich zu ändern lohnen, sind die Queue-Größe und die Plattengrenze.

Unterhalb der Plattengrenze reiht der Agent keine neuen Reports ein, notiert den Zustand und mailt ihn, und erkennt und blockt weiter. Ein voll gelaufenes /var ist schlimmer als ein verlorener Report.

Grenzen, die nicht aus der Datei kommen

Vier Zahlen sind keine Einstellung auf dem Host. Sie kommen aus Ihrem Konto, und der Agent fragt sie ab. Deshalb greift ein Upgrade, ohne dass jemand eine Datei bearbeitet.

Mail, wenn etwas nicht stimmt

Gemailt wird ein Zustand und kein Ereignis, ein Feed, der jede Stunde scheitert, ist also eine Nachricht und nicht vierundzwanzig. Der Agent führt elf Zustände, merkt sich, wann jeder zuletzt gemailt wurde, damit ein Neustart nicht von vorn anfängt, und schickt eine Entwarnung, wenn einer vorbei ist.

In der Mail stehen der Hostname, die Version, der Name des Zustands, ein kurzer Satz mit Zahlen und der Befehl zum Nachsehen. Nie eine Logzeile, nie eine IP-Adresse, nie ein Pfad. Höchstens eine Mail pro Zustand innerhalb von notify.cooldown_hours. Ein Anhalten des Agenten schickt genau eine Mail, die nennt, was dieser Host ab dann nicht mehr tut; ein Reboot und ein Neustart schicken keine, und genau das hält das Selbst-Update still.

install legt den notify-Block an, die Adresse ist also ein Flag beim Einrichten und keine Nachbearbeitung. Eine bestehende Konfiguration wird nie geändert, auch nicht von einem Update.

# Arm the mail while the host is being set up
sudo REPORTEDIP_KEY=<YOUR-KEY> reportedip-agent install --notify-email ops@example.org

# The same through the install script, so one line arms a whole
# rollout
curl -fsSL https://reportedip.com/agent/install.sh \
  | REPORTEDIP_ACCEPT_TERMS=1 REPORTEDIP_KEY=<YOUR-KEY> REPORTEDIP_NOTIFY_EMAIL=ops@example.org sh

Drei Zustellwege, in der Reihenfolge, in der der Agent sie versucht. Ohne notify.email läuft keiner davon.

# The default: out through the relay of reportedip.com, so this
# host needs no mail server of its own.
notify:
  email: "ops@example.org"
  cooldown_hours: 24
  relay: true

# Local delivery only, through postfix, exim or msmtp.
notify:
  email: "ops@example.org"
  cooldown_hours: 24
  relay: false

# No local MTA and no relay: your own SMTP.
notify:
  email: "ops@example.org"
  cooldown_hours: 12
  relay: false
  smtp:
    host: mail.example.org
    port: 587
    from: agent@example.org
    user: agent@example.org
    password: "..."
    starttls: true

Führen Sie danach reportedip-agent doctor aus. Der Abschnitt mail sagt, ob eine Mail diesen Host wirklich verlassen kann, und das ist eine andere Frage als die, ob der Parser die Konfiguration annimmt. Ein fehlender Empfänger wird bei jedem Lauf genannt und zählt nicht als Fehler.

Wann eine Änderung greift

Der Agent liest seine Konfiguration beim Start, beobachtet die Datei nicht und hat kein Reload-Signal. Welchen Befehl Sie brauchen, hängt davon ab, welchen Teil Sie angefasst haben.

# The safe sequence after any edit
reportedip-agent status >/dev/null; [ $? -ne 2 ] && echo "config parses"
reportedip-agent sync
systemctl restart reportedip-agent.service
systemctl status reportedip-agent.service --no-pager

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