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 / 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