Configuring the Linux Agent

Every key of /etc/reportedip-agent/config.yaml with its default and its range, the detection thresholds per source, the ban ladder, the operating limits, the mail that arrives when something is wrong, and which change takes effect on the next sync, on a restart, or within a minute.

Configuration

One file, one whitelist, one state directory. What the installer writes is already correct for the host; most installations only ever change two things, the value of mode and whether local banning is on.

Every key of config.yaml

Only api_key is required. Every other key has the default below, and a key you leave out keeps that default. A value outside its range is an error that names the key, never a silent clamp. Dotted names below are nesting, ban.enabled is enabled: indented under ban:.

A complete file that parses, with every block a normal host uses:

# /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

Detection limits, per source

A threshold is a pair: how many hits, inside how many minutes. It is the same idea as maxretry and findtime of a fail2ban jail. Three levels decide which pair applies to one event source, and the first one with an answer wins.

The key under thresholds is the event source from that table, not the source type from sources. Both numbers have to be at least 1. One thresholds block, one entry per source you want to change:

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

Raising a threshold makes the agent quieter and lets slow attackers through. Lowering it is the direction that costs something: below about three hits in an hour on a mail or web source you will eventually report a customer with a wrong password in their mail client, and a report is public within the community.

One input is not configurable. An address with a ban history needs fewer hits than an unknown one: one previous ban counts a line double, two count it triple, then five and nine. The weight is cut to the threshold of its event source, so a tenth ban does not turn a single line into a report.

Ban limits

Five values in the ban block, each in the unit its key names. They apply only to addresses the agent found in your own logs. The community list has no ban time at all, it is replaced wholesale on every feed pass. With the defaults an address that keeps coming back is banned for 30 minutes, then 2 hours, 8 hours, 32 hours and 128 hours, and after that for the cap of 7 days.

# 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

Operating limits

These bound what the agent itself may consume. They are not tuning knobs for detection, and the two worth changing are the queue size and the disk floor.

Below the disk floor the agent stops writing new reports to the queue, records the condition and mails it, and keeps detecting and blocking. A full /var is worse than a missed report.

Limits that do not come from the file

Four numbers are not settings on the host. They come from your account and the agent asks for them, which is why an upgrade takes effect without anyone editing a file.

Mail when something is wrong

What is mailed is a state and not an event, so a feed that fails every hour is one message and not twenty-four. The agent tracks eleven states, remembers when each was last mailed so a restart does not start over, and sends an all-clear when one is over.

The mail carries the hostname, the version, the name of the state, a short sentence with numbers and the command to look with. Never a log line, never an IP address, never a path. At most one mail per state within notify.cooldown_hours. Stopping the agent sends exactly one mail naming what this host stops doing; a reboot and a restart send none, which is what keeps the self update quiet.

install writes the notify block, so the address is one flag at setup time rather than an edit afterwards. An existing configuration is never changed, not even by an 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

Three delivery paths, in the order the agent tries them. Without notify.email none of them runs.

# 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

Run reportedip-agent doctor after configuring this. Its mail section says whether a mail could really leave the host, which is a different question from whether the configuration parses. A missing recipient is named on every run and is not counted as a fault.

When a change takes effect

The agent reads its configuration at start, does not watch the file and has no reload signal. Which command you need depends on which part you touched.

# 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

Last updated: 30. September 2026 · Maintained by the ReportedIP team