First commit

docs/index.en.md

@@ -0,0 +1,60 @@
+# Fail2banActionBanisher
+
+Distributed malicious-host banishing system built on **fail2ban** and
+**iptables**, with event propagation over **MQTT**.
+
+Each node detects and bans locally (fail2ban + iptables), publishes the
+event to a local Mosquitto broker, then relays it to a private **master**
+broker (mTLS). The master centralizes the decision (multi-node
+correlation, global recidive detection, shared reputation) and
+republishes the actions to be executed to all subscribed nodes.
+
+Target machine: **Debian 13 VPS**.
+
+## Architecture (overview)
+
+```
+[node] fail2ban/iptables → local mosquitto (1883) → master mosquitto (8883, TLS)
+                                                              │
+                                                    decision / correlation
+                                                              │
+[node] ◄──────────────── MQTT action (BAN, SYNC_BAN, UNBAN, ...) ◄──────────
+```
+
+A Django dashboard (real-time, WebSocket) runs on every node and on the
+master, with an aggregated multi-node view on the master side.
+
+## Use cases
+
+The master/nodes model doesn't assume any ownership relationship between
+the protected servers — only that they share a common decision authority.
+That makes the architecture relevant beyond a single operator running
+their own VPSes:
+
+- **A set of sites** (several VPSes run by the same operator, each
+  hosting one or more services): an IP attacking one site gets banned
+  everywhere via `SYNC_BAN`, without manual per-site monitoring.
+- **A community** (several independent administrators, each responsible
+  for their own server, who agree to pool their detections): every
+  member keeps their own node and their own local fail2ban — only ban
+  propagation is shared through the common master. No member gets SSH
+  access to another member's server.
+- **An IT services company** managing several clients' sites: a
+  centralized master gives an aggregated view (jail/country counters,
+  per-node history, per-client aliases) without mixing client data —
+  each node only sees its own events, the master sees everything.
+
+In all three cases, a new server joins the set without ever handing out
+SSH access to the others: a single-use [token-based
+enrollment](deployment.en.md#token-based-node-enrollment-recommended) is
+enough — particularly relevant for the community and services-company
+cases, where the servers belong to different parties.
+
+## Where to go next
+
+- [Installation](installation.en.md) — development setup, first
+  production node.
+- [Production deployment](deployment.en.md) — master, token-based node
+  enrollment, databases, reverse proxy, alternatives to systemd.
+- [Reference](reference.en.md) — MQTT topics, master commands, custom
+  fail2ban jails.