From 94bcbbac5bfdda8df06a4d5909524986518c5028 Mon Sep 17 00:00:00 2001
From: Jose <joseraj@gmail.com>
Date: Sun, 1 Mar 2026 10:23:11 +0100
Subject: [PATCH] =?UTF-8?q?docs=20=F0=9F=93=9D:=20Add=20Fail2Ban=20deploym?=
 =?UTF-8?q?ent=20and=20configuration=20documentation=20for=20Proxmox=20VE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This commit adds a new file `meta/fail2ban.md` containing detailed documentation on how to deploy and configure Fail2Ban on Proxmox VE, including integration with the Proxmox firewall. The documentation aims to provide comprehensive guidance for users looking to enhance their server security by implementing Fail2Ban.
---
 meta/fail2ban.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 meta/fail2ban.md

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