swissmakers_gmbh/fail2ban-ui
12
1
Fork 0
mirror of https://github.com/swissmakers/fail2ban-ui.git synced 2026-04-11 13:47:05 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update docs for newest features

Browse Source
This commit is contained in:
Michael Reber
2025-11-12 19:32:45 +01:00
parent 0134b7de5e
commit 17f66b8ed4
4 changed files with 199 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
README.md
View File

@@ -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**!

31
deployment/container/README.md
View File

@@ -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)

23
deployment/systemd/README.md
View File

@@ -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 \

7
internal/fail2ban/connector_ssh.go
View File

@@ -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 {