diff --git a/meta/fail2ban.md b/meta/fail2ban.md
new file mode 100644
index 0000000..3db95c8
--- /dev/null
+++ b/meta/fail2ban.md
@@ -0,0 +1,94 @@
+# Fail2Ban Integration with Proxmox Firewall
+
+This Ansible playbook deploys and configures **Fail2Ban** on a Proxmox VE environment, integrating it with the **Proxmox firewall** for cluster-aware IP banning. It supports both single-node and clustered Proxmox setups.
+
+---
+
+## Features
+
+- Detects Proxmox VE installation.
+- Checks cluster filesystem (`pmxcfs`) and quorum before modifying firewall.
+- Detects cluster membership via `corosync.conf`.
+- Installs and configures Fail2Ban with:
+  - SSH protection
+  - Proxmox GUI / AD login protection
+  - Progressive ban escalation (recidive jail)
+- Deploys a **cluster-aware Fail2Ban action** (`proxmox-fw`) for Proxmox firewall integration.
+- Ensures safe firewall updates without affecting Corosync ports (5404/5405).
+- Supports single-node Fail2Ban using `iptables-multiport`.
+- Enables and starts the Fail2Ban service.
+- Provides tasks to list or manually unban IPs in the cluster.
+
+---
+
+## Requirements
+
+- **Proxmox VE** (any supported version)
+- **Ansible** ≥ 2.9
+- Root or sudo access on target nodes
+- Proxmox firewall enabled for cluster-wide banning (optional, but recommended)
+
+---
+
+## Variables
+
+The playbook uses the following variables (can be defined in a `vars` file or inventory group vars):
+
+| Variable | Description | Default / Notes |
+|----------|-------------|----------------|
+| `f2b_bantime` | Default ban time for repeated failures | e.g., `600s` |
+| `f2b_findtime` | Time window to check failures | e.g., `1200s`|
+| `f2b_maxretry` | Maximum retries before ban | e.g., `5` |
+| `f2b_bantime_increment` | Incremental ban time (recidive) | e.g., `true` |
+| `f2b_bantime_factor` | Factor for incremental ban | e.g., `2` |
+| `f2b_bantime_max` | Maximum ban time | e.g., `7d` |
+| `f2b_recidive_bantime` | Ban time for recidive jail | e.g., `3600` |
+| `f2b_recidive_findtime` | Findtime for recidive jail | e.g., `86400` |
+| `f2b_recidive_maxretry` | Max retry for recidive jail | e.g., `3` |
+| `f2b_ipset_name` | Name of Proxmox IPSet used for banned IPs | e.g., `f2b-blacklist` |
+| `f2b_unban_ip` | Optional IP to unban manually | Leave undefined if not needed |
+
+> All `clustered` and `pmxcfs_running` checks default to `false` to prevent errors on non-clustered or single-node setups.
+
+---
+
+## Usage
+
+### 1. Apply the playbook
+
+```bash
+ansible-playbook -i inventory fail2ban-proxmox.yml
+```
+
+### 2. List current banned IPs
+
+```bash
+ansible-playbook -i inventory fail2ban-proxmox.yml -e "f2b_ipset_name=fail2ban" -t list_banned
+```
+
+### 3. Unban a specific IP
+
+```bash
+ansible-playbook -i inventory fail2ban-proxmox.yml -e "f2b_unban_ip=1.2.3.4"
+```
+
+## How It Works
+
+- Detects Proxmox – ensures the playbook runs only on Proxmox VE hosts.
+- Cluster safety checks – verifies /etc/pve/.members and corosync.conf for quorum.
+- Installs Fail2Ban – ensures /etc/fail2ban/jail.local exists and applies configuration.
+- Cluster-aware action – for clustered nodes, Fail2Ban bans are added to Proxmox firewall and compiled immediately (pve-firewall compile).
+- Single-node fallback – uses iptables-multiport for nodes not in a cluster.
+- Corosync protection – prevents firewall rules from dropping cluster communication ports (5404/5405).
+
+## Notes & Safety
+
+- The playbook does not copy jail.conf, only manages jail.local.
+- Firewall rules for clustered nodes are only modified if quorum exists.
+- pve-firewall compile is called safely (>/dev/null 2>&1 || true) to prevent playbook failure on minor compilation warnings.
+- Manual unban is supported via f2b_unban_ip variable.
+- Always verify that the Proxmox firewall is enabled when using cluster-wide bans.
+
+## License
+
+MIT License
\ No newline at end of file