From efe48c0e590e9a7537d61879da84b49134d6f4f6 Mon Sep 17 00:00:00 2001
From: Michael Reber <michael.reber@swissmakers.ch>
Date: Wed, 21 Jan 2026 18:08:40 +0100
Subject: [PATCH] Update docs and mention nftables vs iptables

---
 README.md                      | 40 +++++++++++++++++++++++++++++++
 deployment/container/README.md | 43 ++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)

diff --git a/README.md b/README.md
index c6aad0f..c394695 100644
--- a/README.md
+++ b/README.md
@@ -896,6 +896,46 @@ journalctl -u fail2ban-ui.service -f
 3. Add remote server via SSH or API agent
 4. Verify server connection status
 
+#### Fail2Ban Banaction Configuration (nftables vs iptables)
+
+**Symptoms:** Fail2Ban fails to ban IPs with errors like:
+- `Extension multiport revision 0 not supported, missing kernel module?`
+- `iptables v1.8.11 (nf_tables): RULE_INSERT failed (No such file or directory)`
+- `Error starting action Jail('jail-name')/iptables-multiport: 'Script error'`
+
+**Cause:** Modern Linux distributions (Rocky Linux 9+, RHEL 9+, Fedora 36+, Debian 12+) use **nftables** as the default firewall backend instead of legacy iptables. When Fail2Ban is configured to use `iptables-multiport` or `iptables-allports`, it attempts to use legacy iptables modules that are not available in nftables-based systems.
+
+**Solution:**
+
+1. **For nftables-based systems (Rocky Linux 9+, RHEL 9+, Fedora 36+, Debian 12+):**
+   - Navigate to **Settings** → **Fail2Ban Settings**
+   - Change **Banaction** from `iptables-multiport` to `nftables-multiport`
+   - Change **Banaction Allports** from `iptables-allports` to `nftables-allports`
+   - Save settings and reload Fail2Ban
+
+2. **For systems using firewalld (Rocky Linux / Red Hat):**
+   - If your system uses `firewalld` as the firewall management tool, you can use:
+     - **Banaction**: `firewallcmd-multiport`
+     - **Banaction Allports**: `firewallcmd-allports`
+   - Alternatively, you can still use `nftables-multiport` if firewalld is configured to use nftables backend (which is the default in RHEL 9+)
+
+3. **Verify your system's firewall backend:**
+   ```bash
+   # Check if using nftables
+   iptables --version
+   # Output: iptables v1.8.11 (nf_tables) indicates nftables backend
+   
+   # Check if firewalld is active
+   systemctl status firewalld
+   ```
+
+**Note:** The Fail2Ban UI provides all common banaction options in the Settings dropdown, including:
+- `nftables-multiport` / `nftables-allports` (for nftables-based systems)
+- `firewallcmd-multiport` / `firewallcmd-allports` (for firewalld-based systems)
+- `iptables-multiport` / `iptables-allports` (for legacy iptables systems)
+
+After changing the banaction, Fail2Ban will automatically reload and apply the new configuration.
+
 #### OIDC Authentication Issues
 
 **Symptoms:** Cannot login, redirected to provider but authentication fails
diff --git a/deployment/container/README.md b/deployment/container/README.md
index d2b5243..695142a 100644
--- a/deployment/container/README.md
+++ b/deployment/container/README.md
@@ -10,6 +10,7 @@ A comprehensive guide for building and deploying Fail2Ban UI using containers (D
 - [Volume Mounts](#volume-mounts)
 - [Configuration](#configuration)
 - [Docker Compose](#docker-compose)
+- [Fail2Ban Banaction Configuration](#fail2ban-banaction-configuration)
 - [SELinux Configuration](#selinux-configuration)
 - [Troubleshooting](#troubleshooting)
 
@@ -361,6 +362,44 @@ See `docker-compose-allinone.example.yml` in the project root for the complete c
 
 ---
 
+## Fail2Ban Banaction Configuration
+
+### nftables vs iptables
+
+Modern Linux distributions (Rocky Linux 9+, RHEL 9+, Fedora 36+, Debian 12+) use **nftables** as the default firewall backend instead of legacy iptables. When Fail2Ban is configured to use `iptables-multiport` or `iptables-allports`, it may fail with errors like:
+
+- `Extension multiport revision 0 not supported, missing kernel module?`
+- `iptables v1.8.11 (nf_tables): RULE_INSERT failed (No such file or directory)`
+
+**Solution:** Configure Fail2Ban to use nftables-based actions:
+
+1. Access the Fail2Ban UI web interface
+2. Navigate to **Settings** → **Fail2Ban Settings**
+3. Change **Banaction** from `iptables-multiport` to `nftables-multiport`
+4. Change **Banaction Allports** from `iptables-allports` to `nftables-allports`
+5. Save settings (Fail2Ban will automatically reload)
+
+### firewalld (Rocky Linux / Red Hat)
+
+For systems using `firewalld` as the firewall management tool (common on Rocky Linux and Red Hat Enterprise Linux), you can use:
+
+- **Banaction**: `firewallcmd-multiport`
+- **Banaction Allports**: `firewallcmd-allports`
+
+Alternatively, if firewalld is configured to use the nftables backend (default in RHEL 9+), you can use `nftables-multiport` / `nftables-allports` as described above.
+
+**Verify your system's firewall backend:**
+```bash
+# Check if using nftables
+iptables --version
+# Output: iptables v1.8.11 (nf_tables) indicates nftables backend
+
+# Check if firewalld is active
+systemctl status firewalld
+```
+
+---
+
 ## SELinux Configuration
 
 If SELinux is enabled on your system, you must apply the required SELinux policies to allow the container to communicate with Fail2Ban.
@@ -406,6 +445,10 @@ You should see:
 
 ## Troubleshooting
 
+### Fail2Ban Cannot Ban IPs (nftables/firewalld Issues)
+
+If Fail2Ban fails to ban IPs with errors related to iptables or multiport extensions, see the [Fail2Ban Banaction Configuration](#fail2ban-banaction-configuration) section above for detailed solutions.
+
 ### UI Not Accessible
 
 **Symptoms:** Cannot access web interface