From 17f66b8ed4b2db2fdf07b0b5d2eb0184e1593021 Mon Sep 17 00:00:00 2001 From: Michael Reber Date: Wed, 12 Nov 2025 19:32:45 +0100 Subject: [PATCH] Update docs for newest features --- README.md | 158 ++++++++++++++++++++++++++--- deployment/container/README.md | 31 ++++++ deployment/systemd/README.md | 23 ++++- internal/fail2ban/connector_ssh.go | 7 +- 4 files changed, 199 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 3adb458..6885fd3 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,78 @@ # **Fail2Ban UI** 🚀 **Fail2Ban-UI** is a Swiss-made **web-based management interface** for [Fail2Ban](https://www.fail2ban.org/). -It provides an intuitive dashboard to **monitor, configure, and manage Fail2Ban** in real time. +It provides an intuitive dashboard to **monitor, configure, and manage Fail2Ban** instances in real time, supporting both local and remote Fail2ban servers. Developed by **[Swissmakers GmbH](https://swissmakers.ch)**. ## **✨ Features** +✅ **Multi-Server Management** +- Manage **multiple Fail2ban servers** from a single interface +- Support for **local**, **SSH**, and **API agent** connections +- Add, edit, delete, and configure remote Fail2ban instances +- Switch between servers seamlessly via server selector +- Test connections before saving server configurations + ✅ **Real-time Dashboard** - View **all active Fail2Ban jails** and **banned IPs** in a clean UI -- Displays **live ban events** +- Displays **live ban events** from all configured servers +- **Internal log overview** with ban events stored in SQLite database +- Statistics per server and global overview +- Track ban events with country information and log lines ✅ **Ban & Unban Management** -- **Unban IPs** directly via the UI -- **Search** for banned IPs accross all active jails +- **Unban IPs** directly via the UI (works for local and remote servers) +- **Search** for banned IPs across all active jails +- View ban history with detailed information (IP, jail, hostname, country, logs) ✅ **Fail2Ban Configuration Management** -- **Edit & Save** active Fail2Ban jail/filter configs +- **Edit & Save** active Fail2Ban jail/filter configs (local and remote) +- **Manage Jails**: Enable/disable jails on local and remote servers +- **Filter Debug**: Test filters against log lines using `fail2ban-regex` - Get automatic **email alerts** for specific country-based bans - Configure own SMTP settings for email alerts (STARTTLS only) - Adjust default ban time, find time, and set ignore IPs - Auto-detects changes and prompts for **reload** to apply - Enable debug-mode for detailed module logs +✅ **SSH Remote Management** +- Connect to remote Fail2ban servers via SSH +- Automatic deployment of custom action for ban notifications +- Passwordless sudo support for seamless operation +- Configurable SSH key selection per server +- Test SSH connections before saving + +✅ **API Agent Support** (Future) +- Connect to remote Fail2ban instances via lightweight API agents +- Secure communication using shared secrets +- Push ban notifications from remote servers to the UI + +✅ **Persistent Storage** +- **SQLite database** for storing server configurations and ban events +- All settings and server configurations persist across restarts +- Automatic migration from legacy JSON-based settings + ✅ **Mobile-Friendly & Responsive UI / Fast** - Optimized for **mobile & desktop** - Powered by **Bootstrap 5** - **Go-based backend** ensures minimal resource usage +- Parallel execution for improved performance on remote connections ✅ **Systemd & SELinux Support** - **Run as a systemd service** (Standalone or Container) - **Supports SELinux** for secure execution (also container version) +✅ **Internationalization** +- Multi-language support (English, German, French, Italian, Spanish) +- Easy to add new languages via JSON translation files + ## **📸 Screenshots** Some images from the UI in action: -| Dashboard | Search | Filter Configuration | -|-----------|-------------|--------------------| -| ![Dashboard](./screenshots/0_Dashboard.jpg) | ![Filter Debug](./screenshots/1_Dashboard_search.jpg) | ![Jail Config](./screenshots/3_Dashboard_edit_filter.jpg) | +| Dashboard | Server Management | Filter Debug | +|-----------|-------------------|--------------| +| ![Dashboard](./screenshots/0_Dashboard.jpg) | ![Server Management](./screenshots/1_Dashboard_search.jpg) | ![Filter Debug](./screenshots/3_Dashboard_edit_filter.jpg) | 📌 **More screenshots are found [here](./screenshots/)** @@ -56,7 +91,7 @@ To install and run directly on the system: ```bash git clone https://github.com/swissmakers/fail2ban-ui.git /opt/fail2ban-ui cd /opt/fail2ban-ui -go build -o fail2ban-ui ./cmd/main.go +go build -o fail2ban-ui ./cmd/server/main.go ... ``` @@ -80,11 +115,55 @@ podman run -d \ > **📌 Note:** The container can also be managed as a **systemd service**. +--- + +## **🚀 Getting Started** + +### **First Launch** +1. After starting Fail2Ban-UI, access the web interface at `http://localhost:8080` (or your configured port) +2. You'll be prompted to **add your first Fail2ban server** or **enable the local connector** +3. For local connections: Enable the local connector if Fail2ban is running on the same host +4. For remote connections: Add a new server via SSH or API agent + +### **Adding a Server** + +#### **Local Server** +- The local connector is available by default but **disabled** initially +- Enable it in the server management settings if Fail2ban runs on the same host +- Requires root access or passwordless sudo to the Fail2ban socket + +#### **SSH Server** +1. Go to **Settings** → **Manage Servers** +2. Click **Add Server** +3. Select **SSH** as connection type +4. Fill in: + - **Name**: A descriptive name for this server + - **Host**: IP address or hostname + - **Port**: SSH port (default: 22) + - **SSH User**: Username for SSH connection + - **SSH Key**: Select an SSH key from your `~/.ssh/` directory +5. Click **Test Connection** to verify before saving +6. The UI will automatically deploy the custom action for ban notifications + +**Requirements for SSH connections:** +- SSH key-based authentication (passwordless login) +- Passwordless sudo access to `fail2ban-client` and Fail2ban configuration files +- Network connectivity from UI host to remote server + +#### **API Agent Server** (Future) +- API agent support is planned for future releases +- Will allow connecting to remote Fail2ban instances via a lightweight API service + +--- ## **🔒 Security Considerations** -- Fail2Ban-UI requires **root privileges** to interact with Fail2Ban. + +- Fail2Ban-UI requires **root privileges** or **passwordless sudo** to interact with Fail2Ban sockets. - **Restrict access** using **firewall rules** or a **reverse proxy** with authentication. - Ensure that Fail2Ban logs/configs **aren't exposed publicly**. +- For SSH connections, use **SSH key-based authentication** and restrict SSH access. +- Store SSH keys securely and use strong passphrases. +- The SQLite database contains sensitive information - ensure proper file permissions. For **SELinux users**, apply the **Fail2Ban-UI security policies**: ```bash @@ -95,11 +174,12 @@ semodule -i fail2ban-container-ui.pp semodule -i fail2ban-container-client.pp ``` +--- ## **🛠️ Troubleshooting** ### **UI not accessible?** -- Ensure **port 8080** is open: +- Ensure **port 8080** (or your configured port) is open: ```bash sudo firewall-cmd --add-port=8080/tcp --permanent sudo firewall-cmd --reload @@ -109,6 +189,60 @@ semodule -i fail2ban-container-client.pp journalctl -u fail2ban-ui.service -f ``` +### **No servers configured?** +- On first launch, you need to either: + - Enable the local connector (if Fail2ban runs locally) + - Add a remote server via SSH or API agent +- Go to **Settings** → **Manage Servers** to configure your first server + +### **SSH connection issues?** +- Verify SSH key authentication works manually: + ```bash + ssh -i ~/.ssh/your_key user@remote-host + ``` +- Ensure passwordless sudo is configured: + ```bash + sudo -l + ``` +- Check debug mode in settings for detailed error messages +- Verify the SSH user has access to `/var/run/fail2ban/fail2ban.sock` + +### **Local connector not working?** +- Ensure Fail2ban is running: `sudo systemctl status fail2ban` +- Check socket permissions: `ls -la /var/run/fail2ban/fail2ban.sock` +- Verify the UI has access (runs as root or has sudo permissions) + +### **Database issues?** +- The SQLite database is stored in the application directory +- Check file permissions if you see database errors +- Backup the database before major updates + +--- + +## **📊 Database** + +Fail2Ban-UI uses an embedded **SQLite database** (`fail2ban-ui.db`) to store: +- **Server configurations**: All configured Fail2ban servers (local, SSH, API agent) +- **Application settings**: UI preferences, SMTP settings, etc. +- **Ban events**: Historical ban records with IP, jail, hostname, country, and log lines + +The database is automatically created on first launch and migrated from legacy JSON settings if present. + +--- + +## **🌐 Internationalization** + +Fail2Ban-UI supports multiple languages: +- English (en) +- German (de, de_ch) +- French (fr) +- Italian (it) +- Spanish (es) + +Change the language in **Settings** → **Language**. New languages can be added by creating translation files in `internal/locales/`. + +--- + ## **🤝 Contributing** We welcome **pull requests** and **feature suggestions**! @@ -130,4 +264,4 @@ We welcome **pull requests** and **feature suggestions**! ## **📜 License** Fail2Ban-UI is licensed under **GNU GENERAL PUBLIC LICENSE, Version 3**. -See [`LICENSE`](./LICENSE) for details. \ No newline at end of file +See [`LICENSE`](./LICENSE) for details. diff --git a/deployment/container/README.md b/deployment/container/README.md index 36904d8..f901db9 100644 --- a/deployment/container/README.md +++ b/deployment/container/README.md @@ -2,6 +2,13 @@ A **containerized version of Fail2Ban-UI**, allowing easy deployment for managing Fail2Ban configurations, logs, and bans via a web-based UI. +## **Features** +- **Multi-server management**: Manage multiple Fail2ban servers (local, SSH, API agent) from a single interface +- **SQLite database**: Persistent storage for server configurations and ban events +- **Remote management**: Connect to remote Fail2ban instances via SSH +- **Filter debugging**: Test filters against log lines using `fail2ban-regex` +- **Jail management**: Enable/disable jails on local and remote servers + ## How to Build the Image @@ -67,6 +74,19 @@ Remove the container: podman rm fail2ban-ui ``` +## First Launch & Server Configuration +After starting the container, access the web interface at `http://localhost:8080` (or your configured port). + +**Important:** On first launch, you need to: +1. **Enable the local connector** (if Fail2ban runs on the same host), OR +2. **Add a remote server** via SSH or API agent + +Go to **Settings** → **Manage Servers** in the web UI to configure your first Fail2ban server. + +The UI uses an embedded SQLite database to store all server configurations and ban events. The database is stored in the `/config` volume mount. + +> **Note:** The local Fail2ban service is optional. Fail2Ban-UI can manage remote Fail2ban servers via SSH or API agents without requiring a local Fail2ban installation in the container. + ## Troubleshooting ### UI Not Accessible @@ -80,6 +100,17 @@ podman logs fail2ban-ui podman exec -it fail2ban-ui ps aux ``` +### No Servers Configured +- On first launch, you must add at least one Fail2ban server +- Go to **Settings** → **Manage Servers** in the web UI +- Enable the local connector or add a remote server via SSH + +### SSH Connection Issues +- Verify SSH key authentication works from the host +- Ensure passwordless sudo is configured on the remote server +- Check debug mode in settings for detailed error messages +- The container needs network access to remote SSH servers + ## Contact & Support For issues, contributions, or feature requests, visit our GitHub repository: 🔗 [GitHub Issues](https://github.com/swissmakers/fail2ban-ui/issues) diff --git a/deployment/systemd/README.md b/deployment/systemd/README.md index 088891b..b38a9ca 100644 --- a/deployment/systemd/README.md +++ b/deployment/systemd/README.md @@ -3,7 +3,7 @@ This guide provides two methods to **run Fail2Ban-UI as a systemd service**. 1. Systemd service that starts the local compiled binary. 2. Systemd service that starts the fail2ban-ui container. -## For SELinux enabled systems (needed in bouth cases) +## For SELinux enabled systems (needed in both cases) If SELinux is enabled, you must apply the required SELinux policies to allow Fail2Ban to communicate with the Fail2Ban-UI API via port 8080. Apply the prebuilt SELinux Module with: @@ -22,6 +22,8 @@ Install **Go 1.22+** and required dependencies: ``` Make sure you setup GeoIP and your country database is available under: `/usr/share/GeoIP/GeoLite2-Country.mmdb` +> **Note:** The local Fail2ban service is optional. Fail2Ban-UI can manage remote Fail2ban servers via SSH or API agents without requiring a local Fail2ban installation. + Clone the repository to `/opt/fail2ban-ui`: ```bash sudo git clone https://github.com/swissmakers/fail2ban-ui.git /opt/fail2ban-ui @@ -35,8 +37,8 @@ Save this file as `/etc/systemd/system/fail2ban-ui.service`: ```ini [Unit] Description=Fail2Ban UI -After=network.target fail2ban.service -Requires=fail2ban.service +After=network.target +Wants=fail2ban.service [Service] Type=simple @@ -80,6 +82,17 @@ Stop: sudo systemctl stop fail2ban-ui.service ``` +### First Launch & Server Configuration +After starting the service, access the web interface at `http://localhost:8080` (or your configured port). + +**Important:** On first launch, you need to: +1. **Enable the local connector** (if Fail2ban runs on the same host), OR +2. **Add a remote server** via SSH or API agent + +Go to **Settings** → **Manage Servers** in the web UI to configure your first Fail2ban server. + +The UI uses an embedded SQLite database (`fail2ban-ui.db`) to store all server configurations and ban events. This database is automatically created in the working directory. + ## Running Fail2Ban-UI as a (Systemd controlled) Container This method runs Fail2Ban-UI as a **containerized service** with **automatic startup** and handling through systemd. @@ -110,8 +123,8 @@ Save this file as `/etc/systemd/system/fail2ban-ui-container.service`: ```ini [Unit] Description=Fail2Ban UI (Containerized) -After=network.target fail2ban.service -Requires=fail2ban.service +After=network.target +Wants=fail2ban.service [Service] ExecStart=/usr/bin/podman run --rm \ diff --git a/internal/fail2ban/connector_ssh.go b/internal/fail2ban/connector_ssh.go index 441ecd8..a5964dc 100644 --- a/internal/fail2ban/connector_ssh.go +++ b/internal/fail2ban/connector_ssh.go @@ -422,10 +422,11 @@ func (sc *SSHConnector) TestFilter(ctx context.Context, filterName string, logLi continue } // Use fail2ban-regex: log line as string, filter file path - // Escape the log line for shell safety + // Use sudo -s to run a shell that executes the piped command escapedLine := strconv.Quote(logLine) - cmd := fmt.Sprintf("sudo fail2ban-regex %s %s", escapedLine, strconv.Quote(filterPath)) - out, err := sc.runRemoteCommand(ctx, []string{"sh", "-c", cmd}) + escapedPath := strconv.Quote(filterPath) + cmd := fmt.Sprintf("echo %s | fail2ban-regex - %s", escapedLine, escapedPath) + out, err := sc.runRemoteCommand(ctx, []string{"sudo", "sh", "-c", cmd}) // fail2ban-regex returns success (exit 0) if the line matches // Look for "Lines: 1 lines, 0 ignored, 1 matched" or similar success indicators if err == nil {