FAQs

Troubleshooting

Legitimate visitors are getting "Too Many Requests" or "Forbidden"

  1. Open Admin > Traffic Guard and find the visitor's IP under Recent Events or Top Blocked IPs; click through to the IP detail page.
  2. Read the Signals column. Common causes are a shared office or campus NAT address exceeding the rate limits (rate_exceeded_hard), a browser extension or app with a bot-like user agent (bot_ua_pattern), or a broad user-agent block rule (ua_rule_block).
  3. Fix accordingly: add the address or range to the IP Allowlist, add an allow rule for the client in User-Agent Rules, raise the affected limit or thresholds in Configuration, or switch back to Normal mode.
  4. If the IP is currently banned, lift the ban on its detail page (Global Admin only).

I banned or throttled myself and cannot reach the admin

Bans apply to admin pages too, and a banned IP cannot lift its own ban. Options:

  • Log in from another address (a phone on mobile data, for example) and lift the ban on /admin/traffic-guard/ip/{your-ip}.
  • Wait for the ban to expire; automatic bans last one hour by default.
  • Mark the ban as lifted in the database:
UPDATE tg_bans SET unbanned_at = NOW() WHERE ip_address = '203.0.113.5' AND unbanned_at IS NULL;

Then add your own address to the allowlist so it cannot happen again. Rate limiting itself never applies to /admin paths, so only a ban can lock you out.

Every visitor seems to share one IP, or my proxy's IP is being banned

Omeka S is behind a reverse proxy, load balancer or CDN and REMOTE_ADDR is the proxy's address. Enable Trust X-Forwarded-For header for client IP on the Settings page, but only if the proxy sets or sanitises that header; see the reverse proxy section in Configuration. Lift any ban on the proxy address afterwards.

Nothing is being logged and the dashboard counters stay at zero

  • Check the status bar reads Protection ON. If it reads OFF, enable the module in Settings.
  • Allowed requests are not logged unless Log allowed requests too is on, so a quiet site legitimately shows zeros in Allowed (24h).
  • If you are testing from a local network, your address is exempt through Automatically skip checks for private/loopback IP ranges. Turn that off temporarily, or test from a public address.
  • Look in the PHP error log for lines starting with [TrafficGuard]. Any error inside the guard is logged there and the request is allowed through.

A new user-agent rule does not seem to apply

Rules are cached in memory per PHP worker and the cache is cleared when you add or delete a rule from the Rules page. If you changed tg_ua_rules directly in the database, restart PHP-FPM or Apache so every worker reloads the rules. Also check that rule priority: an allow rule with a lower number than your block rule wins.

A regular expression rule was rejected as invalid

Patterns are wrapped in /.../i by the module, so do not include the delimiters yourself, and escape any forward slash as \/. Test the expression with a PCRE tester before adding it.

The purge job never runs, or stays at "starting"

The purge is dispatched through Omeka's background job runner. If jobs in general are stuck, check Admin > Jobs and the phpcli_path value in config/local.config.php; Omeka needs a working PHP CLI path to launch jobs. Once jobs run, the purge job log reports how many rows it deleted.

The tg_events table is very large

  • Lower Log retention (days) and run Purge Old Logs from the dashboard. Each run deletes at most 500,000 rows; run it again if needed.
  • Turn off Log allowed requests too.
  • Schedule the purge regularly; see Purging Logs.

Saving the Configure form on the Modules page changed settings I did not touch

The short form at Admin > Modules > Traffic Guard > Configure does not include Log allowed requests too or Events per page, and saving it resets them to off and 50. Use Admin > Traffic Guard > Settings instead, which has every setting.

I set the auto-ban duration to 0 expecting permanent bans

Automatic bans always have a duration; the minimum stored value is 60 seconds, so 0 becomes a one-minute ban. Permanent bans can only be placed manually from the IP detail page with a duration of 0 hours.

Googlebot or another search engine is being throttled

The built-in bot list does not include the major search engines, but they can still trip rate limits on a large site. Add an allow rule with a low priority number for Googlebot, bingbot and any other crawler you want exempt, or allowlist their published IP ranges.

Does the module affect performance?

Each inspected request performs a handful of small indexed queries: an allowlist read, a ban lookup, one upsert plus one read on the counter table, and an insert when a throttle or block decision is logged. Allowlisted and admin requests skip nearly all of this. Disabling the module removes the overhead entirely.

Log in for Support