ansible_role_proxmox_provision/meta/fail2ban.md

# 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         |
|-------------------------|---------------------------------|-----------------|
| `f2b_bantime`           | Ban per tentativi falliti       | `600s`          |
| `f2b_findtime`          | Finestra per contare fallimenti | `1200s`         |
| `f2b_maxretry`          | Tentativi prima del ban         | `5`             |
| `f2b_bantime_increment` | Abilita ban incrementale        | `true`          |
| `f2b_bantime_factor`    | Fattore aumento ban             | `2`             |
| `f2b_bantime_max`       | Durata massima del ban          | `7d`            |
| `f2b_recidive_bantime`  | Ban per recidiva                | `3600`          |
| `f2b_recidive_findtime` | Finestra recidiva               | `86400`         |
| `f2b_recidive_maxretry` | Tentativi recidiva              | `3`             |
| `f2b_ipset_name`        | Nome IPSet per IP bannati       | `f2b-blacklist` |
| `f2b_unban_ip`          | IP da sbloccare                 | `""`            |

> 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