Jose
752db2b57f
All checks were successful
ansible-lint / Ansible Lint (push) Successful in 13s
Gitleaks Scan / gitleaks (push) Successful in 5s
Markdown Lint / markdown-lint (push) Successful in 5s
ai-reviews / Review PR (pull_request) Successful in 37s
PR check / Gitleaks (pull_request) Successful in 5s
PR check / lint tests (pull_request) Successful in 15s
PR check / labeler (pull_request) Successful in 2s
PR check / handle_failures (pull_request) Has been skipped
PR check / handle_success (pull_request) Successful in 1s
This commit addresses the formatting issues in the table and adds a code block for the 'list_banned' task to improve readability and clarity.
111 lines
3.8 KiB
Markdown
111 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 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
|