A small HTTP service that runs bundled with a Fail2ban in one container. It exposes a JSON REST API.
1.9K
fail2ban-ui-agent is a small HTTP service that runs bundled with a Fail2ban service in one container. It exposes a JSON REST API secured by a shared secret so Fail2ban-UI can drive the same operations as local or SSH connectors do (jails, filters, ban/unban, reload, logpath checks, and callbacks via a poller).
Remote control plane for Fail2ban on a single host, consumed by Fail2ban-UI’s Agent-Connector.
The agent does not replace Fail2ban; it requires a working fail2ban daemon and appropriate permissions to manage jails and configuration files. In the following image the agent is already bundled with a fail2ban instance together.
Overview
X-F2B-Token (see Section 3).PUT /v1/callback/config. The agent persists them (under fail2ban-ui-agent.id in the Fail2ban config tree). A poller compares jail state over time and POSTs changes (bans or unbans) to Fail2ban-UI’s /api/ban and /api/unban API secured with the X-Callback-Secret.IMPORTANT: The poller-based callback path is the only supported model for agent connectors; please do not try to copy ui-custom-action scripts on agent-managed hosts.
Base URL is http(s)://<host>:<AGENT_PORT> (default port 9700 unless overridden).
| Scope | Requirement |
|---|---|
/v1/* | Header X-F2B-Token: <AGENT_SECRET> must match the agent’s configured secret (constant-time compare on the server). |
/healthz, /readyz | No token required by default |
Responses are JSON. Errors typically include an "error" string and appropriate HTTP status codes.
| Method | Path | Purpose |
|---|---|---|
GET | /healthz | Liveness / health JSON |
GET | /readyz | Readiness when the supervisor reports healthy |
All of the following require X-F2B-Token.
Callback configuration
| Method | Path | Purpose |
|---|---|---|
PUT | /v1/callback/config | Body: serverId, callbackUrl, callbackSecret, optional callbackHostname -> persisted for the poller |
Fail2ban service actions
| Method | Path | Purpose |
|---|---|---|
POST | /v1/actions/reload | Reload Fail2ban configuration |
POST | /v1/actions/restart | Restart Fail2ban (with fallbacks where applicable) |
Jails
| Method | Path | Purpose |
|---|---|---|
GET | /v1/jails | List jails from fail2ban-client (runtime-oriented) |
GET | /v1/jails/all | Broader jail listing for "Manage jails" UI |
GET | /v1/jails/{jail} | Banned IPs / counts for a jail |
POST | /v1/jails/{jail}/ban | Ban an IP |
POST | /v1/jails/{jail}/unban | Unban an IP |
GET | /v1/jails/{jail}/config | Read jail config (with .local / .conf fallback semantics) |
PUT | /v1/jails/{jail}/config | Write jail config |
POST | /v1/jails | Create jail |
DELETE | /v1/jails/{name} | Delete jail |
POST | /v1/jails/update-enabled | Map of jail name -> enabled flag |
POST | /v1/jails/test-logpath | Test log path pattern |
POST | /v1/jails/test-logpath-with-resolution | Resolve %(var)s style log paths then test |
GET | /v1/jails/check-integrity | jail.local presence / managed / legacy UI-action markers |
POST | /v1/jails/ensure-structure | Ensure managed jail.local; optional JSON content |
Filters
| Method | Path | Purpose |
|---|---|---|
GET | /v1/filters | List filter names |
GET | /v1/filters/{name} | Read filter config |
PUT | /v1/filters/{name} | Write filter .local |
POST | /v1/filters | Create filter |
DELETE | /v1/filters/{name} | Delete filter .local |
POST | /v1/filters/test | Run fail2ban-regex-style test |
NOTE: Filter names that contain slashes must be URL-encoded in the path (as implemented in Fail2ban-UI’s connector).
| Variable | Default | Description |
|---|---|---|
AGENT_BIND_ADDRESS | 0.0.0.0 | Listen address |
AGENT_PORT | 9700 | Listen port |
AGENT_SECRET | (empty) | Required to start the API server |
AGENT_TLS_CERT_FILE / AGENT_TLS_KEY_FILE | (empty) | Set both to serve HTTPS on AGENT_PORT |
AGENT_FAIL2BAN_CONFIG_DIR | /etc/fail2ban | Fail2ban configuration root |
AGENT_FAIL2BAN_RUN_DIR | /var/run/fail2ban | Runtime directory (socket path context) |
AGENT_LOG_ROOT | /var/log | Used for logpath tests / resolution |
AGENT_HEALTH_INTERVAL | 30s | Supervisor check interval |
AGENT_HEALTH_AUTO_RELOAD | true | Auto-reload Fail2ban on repeated failures |
AGENT_HEALTH_AUTO_RESTART | true | Auto-restart Fail2ban when reload is not enough |
AGENT_HEALTH_MAX_RETRIES | 3 | Supervisor retry budget |
Callback poller
| Variable | Default | Description |
|---|---|---|
| (persisted file) | — | Primary source after PUT /v1/callback/config |
AGENT_CALLBACK_URL | — | Optional override (env wins over file when set) |
AGENT_CALLBACK_SECRET | — | Optional override |
AGENT_CALLBACK_SERVER_ID | — | Optional override |
AGENT_CALLBACK_HOSTNAME | — | Optional override |
AGENT_CALLBACK_POLL_INTERVAL | 4s | Poll interval; 0 disables the poller |
Persisted callback file path: ${AGENT_FAIL2BAN_CONFIG_DIR}/fail2ban-ui-agent.id.
Content type
Image
Digest
sha256:d657d773a…
Size
36.2 MB
Last updated
about 2 months ago
docker pull swissmakers/fail2ban-ui-agent