Running the Linux Agent

The commands and their exit codes, what the three systemd units do, how status and doctor fit into monitoring, test in place of fail2ban-regex, and the troubleshooting table: symptom, cause, command.

Commands

test, instead of fail2ban-regex

test runs the detector chain over a log file you already have, with the thresholds and the whitelist of this host, and prints which addresses would have crossed a threshold and where in the file. It reports nothing, blocks nothing and writes nothing, so it is safe on a production host and it is the honest way to answer "would this have caught last week's attack".

# A configured source: the type is taken from the config
reportedip-agent test /var/log/auth.log

# Any other file: name the type yourself
reportedip-agent test --type postfix /var/log/mail.log.1

# A rotated log and its successor as one stream, in this order,
# so a window that spans the rotation counts like the daemon saw it.
# A .gz is read inflated.
reportedip-agent test /var/log/mail.log.2.gz /var/log/mail.log.1 /var/log/mail.log

# Every single hit, with line number, address and timestamp
reportedip-agent test --lines /var/log/auth.log

The summary line gives the lines read, how many matched, how many an ignore pattern dropped, how many carried no usable timestamp and how many were skipped as overlong. Then one row per address with its hits, its resets, whether it would have been banned and how often, the time of the first hit, and the threshold that was applied. An address that is on your whitelist is shown with the layer that matched and marked as never banned and never reported, which makes this the fastest way to prove a whitelist entry actually works.

Two things test does not do. It does not guess a format: without --type the file has to be one of the configured source paths, and otherwise it tells you so and lists the valid types. And it does not apply the ban-history weight, so the daemon needs fewer hits for an address with previous bans than this replay suggests.

Running it

Three systemd units, written and enabled by install and brought up to the state of the running version by every sync. Put your own changes into a drop-in under /etc/systemd/system/<unit>.d/, where they survive an update. A unit you edited directly is replaced, the previous version is left beside it as <unit>.bak, and the journal names both.

Both units run with NoNewPrivileges, ProtectHome, PrivateTmp, a locked personality and a restricted set of address families.

systemctl list-timers reportedip-agent-sync.timer
systemctl status reportedip-agent.service --no-pager
journalctl -u reportedip-agent.service -n 50 --no-pager
journalctl -u reportedip-agent-sync.service -n 50 --no-pager
tail -n 100 /var/log/reportedip-agent.log

Exit codes

That makes reportedip-agent status usable as a monitoring check directly, with no wrapper script and no output parsing. status --json prints the same result as a JSON document; the setup for Zabbix, Nagios, Icinga, Checkmk and Prometheus is under Monitoring.

The reputation of this host's own address

The sync run asks the server what it thinks of the address this host reports from, at least once a day and on every run while the condition below is open. If that address is itself listed in the community database, status warns and exits 1. With a confidence of 75 or more the health condition reputation is open as well, with the confidence, the number of reports and the link to the delisting page in its text. It is a warning and not an error, because a listed address is a fact about the network the host lives in and not necessarily about the host: a shared address, a carrier NAT or a neighbour behind the same proxy can put it there. It is still worth a look, because a host that reports from a listed address is what a compromised host looks like from outside. Check what leaves the machine, request the delisting once it is clean, and the condition clears with the next sync after the delisting; there is nothing to reset on the host. Below 75 no health condition is raised: a handful of old reports is honest data and not something an operator can act on, and no feed serves an address at that score.

Bot floods: what the agent does and does not do

A page answered with 200 is never an attack. A flood from thousands of addresses that each ask for an ordinary page once or twice is load, and a rule that counts per address sees one request from each of them and nothing to act on. The agent does not ban such a swarm and is not meant to, because the same lines come from real visitors. It does two things instead: it tells you that a site is being flooded, and it counts the one pattern in the flood that visitors do not produce. The rest belongs in the web server. The article on bot flood detection and countermeasures goes through a worked case with measured numbers.

The volume alarm

The daemon counts every line of every log it reads and keeps a baseline of lines per hour for each of them: a running mean over the full hours of the first week, then an average with a week of memory. When the running hour of a web log, one of the sources web and web-error, reads at least eight times its baseline and at least 20,000 lines, the health state volume opens as a warning. Its text names the loudest site, which is the name of the directory the log lies in and usually the virtual host, and reportedip-agent status shows every loud log. The state clears after a full quiet hour.

Since 0.3.52 the alarm also says who the flood is. While a log is loud, the daemon counts its clients, up to 20,000 addresses, and adds a verdict to the text: one client made most of the lines, and whether a rule counts it; a few clients made most of them; or the lines are spread over many clients, where a rule fits better than bans. The mail carries only that verdict and never an address. reportedip-agent status names the five loudest clients under the log, with their share and ruled=, the number of their lines a rule took. ruled=0 means no rule counts them, and reportedip-agent ban add <address> bans one. The list stays after the flood until the next one starts. The all-clear mail repeats the last state of the alarm with its start, its end and how long it lasted.

Nothing alarms before the baseline holds 24 full hours, so a fresh install stays quiet on its first day. The alarm bans nothing and reports nothing: it makes the flood visible, and what to do about it is your decision. A flood that grows slowly over more than a week lifts the baseline with it, so the factor catches jumps and not ramps. Two keys in config.yaml set the limits; Monitoring shows where the running hour and the baseline appear in status.

volume_factor: 8          # times the usual hour; 0 switches the alarm off, otherwise 2 to 1000
volume_min_lines: 20000   # lines in the running hour, at least; 0 to 100000000

The rule web-query-crawl

The pattern visitors do not produce: GET requests with a query string, answered with 200, without a referer of their own (empty, or a search engine such as Google or Bing), 20 of them inside 60 minutes from one address. That is a client walking calendar filters, attachment ids or faceted listings. The rule ignores static assets, /wp-json/ and /wp-admin/ paths, wp-cron, the ordinary query keys of WordPress, WooCommerce and tracking (p, s, wc-ajax, utm_*, fbclid, gclid and the like), and every line whose user agent declares a crawler (bot, crawler, spider, GPTBot, Ahrefs, Semrush and others). It counts only clients whose user agent starts with Mozilla/, which every browser and every disguised crawler sends, so a tool or crawler that names itself is never counted; the name list covers the crawlers that start with Mozilla/ as well, such as Googlebot.

Since 0.3.50 it also leaves out what a measurement over one week and 36 servers found among its hits, each by shape and not by name: a user agent that names itself as (compatible; Name), carries a token inside the browser bracket (like Gecko; Name) or a contact address; links out of a mail, such as newsletter views and open or click tracking (noti, fluentcrm, mailpoet_*, mc_cid); a cache buster, a number under a short key such as cb, nc, nocache or *_check; a bare flag as the first key, such as ?start_customizing; and wp-cron behind a double slash.

A crawler that says who it is is not banned by this rule. It may be an SEO service the site owner booked, and the place to slow it down is the web server or robots.txt. That is also why there is no allowlist of user agents to keep up to date: the rule counts only clients that pose as browsers. A forged crawler name escapes it on purpose; the scanner and login rules still count such a client. The rule reports nothing, because a crawl is a nuisance and not community data.

It ships simulated: it writes a simulated ban warning to the log and bans nothing. Switch it off, or arm it with an override file. simulate is policy, so arming the rule starts no day of observation; the daemon picks the file up within a minute.

# What the rule would have banned so far
journalctl -u reportedip-agent | grep "simulated ban"

# Switch it off
reportedip-agent rules disable web-query-crawl

# Arm it: real bans instead of simulated ones
cat > /etc/reportedip-agent/rules.d/50-web-query-crawl.yaml <<EOF
format: 1
rules:
  - id: web-query-crawl
    action: {simulate: false}
EOF
reportedip-agent rules check

In the web server

Everything that limits load regardless of who sends it belongs in the web server. Four measures, shown for nginx; adapt the path, the domain and the numbers to your site.

• A limit_req zone with a fixed key for the filter path. A zone per address does nothing against thousands of addresses with one request each. A zone keyed on $server_name caps how many requests per second reach PHP on that path, however many addresses send them.
• A FastCGI cache keyed on the query string. With $request_uri in fastcgi_cache_key, a repeated filter call is answered without PHP. Fewer filter combinations make it work better: rel="nofollow" on filter links and the filter path in robots.txt.
• A 429 for requests without the site's own referer, as an emergency brake. It holds until the bot forges the referer.
• A prefix block of rented networks, after a whois check. A block of a hosting provider can go as a whole. A consumer provider cannot, because one prefix there holds many customers behind carrier-grade NAT.

# http {}
limit_req_zone $server_name zone=filter_all:1m rate=10r/s;

map $http_referer $own_referer {
    default 0;
    "~^https://(www\.)?example\.org/" 1;
}

# server {}
location ^~ /events/ {
    limit_req zone=filter_all burst=20;
    limit_req_status 429;
    if ($own_referer = 0) { return 429; }   # emergency brake, only while it holds
    try_files $uri $uri/ /index.php?$args;
}

# server {}, only after whois names a hosting provider
deny 198.51.100.0/24;

Troubleshooting

One symptom, one likely cause, one command. reportedip-agent doctor and reportedip-agent status between them answer most of these, and they are the first two things support will ask for.

Last updated: 12. November 2026 · Maintained by the ReportedIP team