Jose
0004d2bd2d
This commit refactors the task names and updates module references in the `fail2ban.yml` file to improve clarity and consistency. It also includes minor text adjustments in `meta/fail2ban.md` to enhance readability and ensure accurate variable descriptions with updated default values.
107 lines
3.8 KiB
Markdown
107 lines
3.8 KiB
Markdown
# 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 i 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
|