Traffic Guard has two places to change settings:
- Admin > Traffic Guard > Settings (
/admin/traffic-guard/settings): every setting, including the per-mode rate limits and risk score thresholds. This is the page to use. - Admin > Modules > Traffic Guard > Configure: a short form with the most common toggles only. Saving this form resets Log allowed requests to off and Events per page to 50, because those fields are not on it.
General settings
All settings are global (there are no per-site settings).
| Setting | Default | Description |
|---|---|---|
| Enable Traffic Guard protection | On | Master switch. When off, no request is inspected, counted or logged. |
| Protection Mode | Normal | Selects which column of rate limits, thresholds and signal weights is active: Normal, Elevated or Under Attack. See Protection Modes. |
| Automatically ban IPs that reach the block threshold | On | When a request scores at or above the block threshold, the IP is banned for the auto-ban duration. |
| Auto-ban duration (hours) | 1 | How long automatic bans last. Half-hour steps are accepted. The stored value is never less than 60 seconds, so entering 0 gives a one-minute ban, not a permanent one. Permanent bans can only be created manually. |
| Automatically skip checks for private/loopback IP ranges | On | Requests from private (RFC 1918), loopback and other reserved ranges bypass every check. |
| Trust X-Forwarded-For header for client IP | Off | Use the first address in X-Forwarded-For as the client IP. Enable only behind a reverse proxy you control; see below. |
| Log allowed requests too | Off | Also write allowed requests to the event log. This adds one database insert per request. |
| Log retention (days) | 30 | Event rows older than this are deleted by the purge job. 0 keeps events forever. |
| Events per page in admin dashboard | 50 | Page size for the Recent Events table on the dashboard (minimum 10). |
Rate limits
Maximum requests per IP per 60-second window, for each endpoint category and protection mode. Exceeding a limit does not block on its own; it adds a risk signal that is combined with the others (see Risk Scoring).
| Category | Paths | Normal | Elevated | Under Attack |
|---|---|---|---|---|
| All public | Everything not matched below | 120 | 80 | 40 |
| Search | /s/{site}/search |
20 | 10 | 5 |
API (/api/*) |
/api/... |
60 | 40 | 20 |
| Item/Media pages | /s/{site}/item..., /s/{site}/item-set..., /s/{site}/media... |
80 | 50 | 25 |
Admin paths (/admin/...) are never counted or rate limited.
Risk score thresholds
Scores run from 0 to 100. A request scoring at or above Throttle score receives HTTP 429; at or above Block score it receives HTTP 403 and, if auto-ban is on, the IP is banned.
| Threshold | Normal | Elevated | Under Attack |
|---|---|---|---|
| Throttle score | 40 | 30 | 20 |
| Block score | 70 | 55 | 40 |
Running behind a reverse proxy
If Omeka S sits behind nginx, Apache, a load balancer or a CDN, every request arrives from the proxy's address and the real client IP is in the X-Forwarded-For header. Without Trust X-Forwarded-For, all visitors would share one counter and the proxy IP could be banned.
Turn the setting on only when both are true:
- All traffic reaches Omeka S through a proxy you control.
- The proxy overwrites or sanitises
X-Forwarded-Forso clients cannot inject their own value.
On a server with a direct public address, leave it off: a client could otherwise spoof its IP with a forged header and evade limits or bans. Only the first (leftmost) address in the header is used, and it must be a valid IP or the module falls back to REMOTE_ADDR.
Permissions
| Action | Site Admin | Global Admin |
|---|---|---|
| View dashboard, IP detail, rules and settings pages | Yes | Yes |
| Save settings | Yes | Yes |
| Add and delete user-agent rules and allowlist entries | Yes | Yes |
| Run the log purge job | Yes | Yes |
| Ban an IP or lift a ban | No | Yes |
Editors, reviewers, authors and researchers cannot see the Traffic Guard pages. The Configure form on the Modules page follows Omeka's own rule and is available to Global Admins.