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

ansible-playbook -i inventory fail2ban-proxmox.yml

2. List current banned IPs

ansible-playbook -i inventory fail2ban-proxmox.yml -e "f2b_ipset_name=fail2ban" -t list_banned

3. Unban a specific IP

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