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

Add docker compose example and update the documentation to it

Browse Source
This commit is contained in:
Michael Reber
2025-12-01 13:26:42 +01:00
parent 65b56b3461
commit 272e112ac9
5 changed files with 558 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Dockerfile
View File

@@ -51,7 +51,7 @@ ENV CONTAINER=true
# Persist config data # Persist config data
VOLUME ["/config"] VOLUME ["/config"]
# Expose UI port # Expose UI port (default: 8080, can be changed via PORT environment variable)
EXPOSE 8080 EXPOSE 8080
# Run the application as non-root (currently not possible because of fail2ban running as privileged) # Run the application as non-root (currently not possible because of fail2ban running as privileged)

97
README.md
View File

@@ -244,13 +244,16 @@ Comprehensive settings management for alerts, advanced banning, and system prefe
#### Method 1: Container Deployment (Recommended for Production) #### Method 1: Container Deployment (Recommended for Production)
**Pull the official image:** **Option A: Using Pre-built Image**
```bash
podman pull registry.swissmakers.ch/infra/fail2ban-ui:latest
```
**Run the container:** Pull and run the official image:
```bash ```bash
# Pull the image
podman pull registry.swissmakers.ch/infra/fail2ban-ui:latest
# or with Docker:
docker pull registry.swissmakers.ch/infra/fail2ban-ui:latest
# Run the container
podman run -d \ podman run -d \
--name fail2ban-ui \ --name fail2ban-ui \
--network=host \ --network=host \
@@ -262,7 +265,74 @@ podman run -d \
registry.swissmakers.ch/infra/fail2ban-ui:latest registry.swissmakers.ch/infra/fail2ban-ui:latest
``` ```
**📖 [Complete Container Deployment Guide](./deployment/container/README.md)** **Option B: Build from Source**
Build your own container image:
```bash
# Clone the repository
git clone https://github.com/swissmakers/fail2ban-ui.git
cd fail2ban-ui
# Build the image
sudo podman build -t fail2ban-ui:latest .
# or with Docker:
sudo docker build -t fail2ban-ui:latest .
# Run the container
sudo podman run -d \
--name fail2ban-ui \
--network=host \
-v /opt/podman-fail2ban-ui:/config:Z \
-v /etc/fail2ban:/etc/fail2ban:Z \
-v /var/log:/var/log:ro \
-v /var/run/fail2ban:/var/run/fail2ban \
-v /usr/share/GeoIP:/usr/share/GeoIP:ro \
fail2ban-ui:latest
```
**Option C: Using Docker Compose**
For easier management, use Docker Compose:
```bash
# Copy the example file
cp docker-compose.example.yml docker-compose.yml
# Edit docker-compose.yml to customize (e.g., change PORT)
# Then start:
docker-compose up -d
```
**Custom Port Configuration**
Change the default port (8080) using the `PORT` environment variable:
```bash
podman run -d \
--name fail2ban-ui \
--network=host \
-e PORT=3080 \
-v /opt/podman-fail2ban-ui:/config:Z \
-v /etc/fail2ban:/etc/fail2ban:Z \
-v /var/log:/var/log:ro \
-v /var/run/fail2ban:/var/run/fail2ban \
-v /usr/share/GeoIP:/usr/share/GeoIP:ro \
registry.swissmakers.ch/infra/fail2ban-ui:latest
```
Access the web interface at `http://localhost3080`.
**Volume Mounts Explained**
| Volume | Required | Purpose |
|--------|----------|---------|
| `/config` | ✅ Yes | Stores SQLite database, application settings, and SSH keys for remote connections |
| `/etc/fail2ban` | ✅ Yes* | Access to Fail2Ban configuration files (jails, filters, actions) |
| `/var/run/fail2ban` | ✅ Yes* | Access to Fail2Ban control socket for local management |
| `/var/log` | ⚠️ Optional | Read-only access to system logs for filter testing |
| `/usr/share/GeoIP` | ⚠️ Optional | Read-only access to GeoIP databases for geographic analysis |
*Required only if managing a local Fail2Ban instance. Not needed for remote-only deployments.
**📖 [Complete Container Deployment Guide](./deployment/container/README.md)** - Detailed documentation including volume descriptions, SELinux configuration, and troubleshooting.
#### Method 2: Systemd Service (Standalone) #### Method 2: Systemd Service (Standalone)
@@ -284,7 +354,7 @@ go build -o fail2ban-ui ./cmd/server/main.go
1. **Access the Web Interface** 1. **Access the Web Interface**
- Navigate to `http://localhost:8080` (or your configured port) - Navigate to `http://localhost:8080` (or your configured port)
- Default port: `8080` (configurable in settings) - Default port: `8080` (configurable via `PORT` environment variable or in UI settings)
2. **Add Your First Server** 2. **Add Your First Server**
- **Local Server**: Enable the local connector if Fail2Ban runs on the same host - **Local Server**: Enable the local connector if Fail2Ban runs on the same host
@@ -301,8 +371,17 @@ go build -o fail2ban-ui ./cmd/server/main.go
### Deployment Guides ### Deployment Guides
- **[Container Deployment](./deployment/container/README.md)**: Complete guide for containerized deployments - **[Container Deployment Guide](./deployment/container/README.md)**:
- **[Systemd Service Setup](./deployment/systemd/README.md)**: Standalone installation and service configuration - Building container images from source
- Running containers with Docker/Podman
- Volume mount explanations (required vs optional)
- Custom port configuration via `PORT` environment variable
- Docker Compose examples
- SELinux configuration
- Troubleshooting common issues
- **[Systemd Service Setup](./deployment/systemd/README.md)**: Standalone installation and service configuration for non-containerized deployments
- **[SELinux Configuration](./deployment/container/SELinux/)**: Security policies for SELinux-enabled systems - **[SELinux Configuration](./deployment/container/SELinux/)**: Security policies for SELinux-enabled systems
### Configuration ### Configuration

489
deployment/container/README.md
View File

@@ -1,57 +1,32 @@
# **Fail2Ban-UI Container** # Fail2Ban UI Container Deployment Guide
A **containerized version of Fail2Ban-UI**, allowing easy deployment for managing Fail2Ban configurations, logs, and bans via a web-based UI. A comprehensive guide for building and deploying Fail2Ban UI using containers (Docker/Podman).
## **Features** ## Table of Contents
- **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
- [Quick Start](#quick-start)
- [Building the Container Image](#building-the-container-image)
- [Running the Container](#running-the-container)
- [Volume Mounts](#volume-mounts)
- [Configuration](#configuration)
- [Docker Compose](#docker-compose)
- [SELinux Configuration](#selinux-configuration)
- [Troubleshooting](#troubleshooting)
## How to Build the Image ---
## Quick Start
### Using Pre-built Image
**Pull the official image:**
```bash ```bash
podman build -t fail2ban-ui --target=standalone-ui . podman pull registry.swissmakers.ch/infra/fail2ban-ui:latest
# or with Docker:
docker pull registry.swissmakers.ch/infra/fail2ban-ui:latest
``` ```
For **Docker**, just replace `podman` with `docker` for every command, e.g.: **Run the container:**
```bash
docker build -t fail2ban-ui --target=standalone-ui .
```
## For SELinux enabled systems
If SELinux is enabled, you must apply the required SELinux policies to allow the container to communicate with Fail2Ban.
The policies are located here: "`./SELinux/`"
Apply the prebuilt SELinux Modules with:
```bash
semodule -i fail2ban-container-ui.pp
semodule -i fail2ban-container-client.pp
```
### Manually Compile and Install SELinux Rules
If you want to change or compile the SELinux rules by yourself run:
```bash
checkmodule -M -m -o fail2ban-container-client.mod fail2ban-container-client.te
semodule_package -o fail2ban-container-client.pp -m fail2ban-container-client.mod
semodule -i fail2ban-container-client.pp
```
## How to Run the Container
Create the needed folder to store the fail2ban-ui config first:
```bash
mkdir /opt/podman-fail2ban-ui
```
Then run the container with the following prompt in background (-d) as test. For a productive container setup please use a systemd service.
```bash ```bash
podman run -d \ podman run -d \
--name fail2ban-ui \ --name fail2ban-ui \
@@ -61,61 +36,425 @@ podman run -d \
-v /var/log:/var/log:ro \ -v /var/log:/var/log:ro \
-v /var/run/fail2ban:/var/run/fail2ban \ -v /var/run/fail2ban:/var/run/fail2ban \
-v /usr/share/GeoIP:/usr/share/GeoIP:ro \ -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
localhost/fail2ban-ui registry.swissmakers.ch/infra/fail2ban-ui:latest
``` ```
### Stop and Remove Container Access the web interface at `http://localhost:8080` (or your configured port).
Stop the running container:
---
## Building the Container Image
### Prerequisites
- Docker or Podman installed
- Git (to clone the repository)
### Build Steps
1. **Clone the repository:**
```bash
git clone https://github.com/swissmakers/fail2ban-ui.git
cd fail2ban-ui
```
2. **Build the image:**
```bash
# Using Podman
podman build -t fail2ban-ui:latest .
# Using Docker
docker build -t fail2ban-ui:latest .
```
> **Note:** The Dockerfile uses a multi-stage build with two stages: `builder` (compiles the Go binary) and `standalone-ui` (final runtime image).
3. **Verify the build:**
```bash
podman images fail2ban-ui
# or
docker images fail2ban-ui
```
### Build Options
You can customize the build with additional flags:
```bash
# Build with a specific tag
podman build -t fail2ban-ui:v1.0.0 .
# Build without cache
podman build --no-cache -t fail2ban-ui:latest .
```
---
## Running the Container
### Basic Run Command
```bash
podman run -d \
--name fail2ban-ui \
--network=host \
-v /opt/podman-fail2ban-ui:/config:Z \
-v /etc/fail2ban:/etc/fail2ban:Z \
-v /var/log:/var/log:ro \
-v /var/run/fail2ban:/var/run/fail2ban \
-v /usr/share/GeoIP:/usr/share/GeoIP:ro \
fail2ban-ui:latest
```
### Custom Port Configuration
You can change the default port (8080) using the `PORT` environment variable:
```bash
podman run -d \
--name fail2ban-ui \
--network=host \
-e PORT=8436 \
-v /opt/podman-fail2ban-ui:/config:Z \
-v /etc/fail2ban:/etc/fail2ban:Z \
-v /var/log:/var/log:ro \
-v /var/run/fail2ban:/var/run/fail2ban \
-v /usr/share/GeoIP:/usr/share/GeoIP:ro \
fail2ban-ui:latest
```
Access the web interface at `http://localhost:8436`.
### Container Management
**Start the container:**
```bash
podman start fail2ban-ui
```
**Stop the container:**
```bash ```bash
podman stop fail2ban-ui podman stop fail2ban-ui
``` ```
Remove the container:
**View logs:**
```bash ```bash
podman logs -f fail2ban-ui
```
**Remove the container:**
```bash
podman stop fail2ban-ui
podman rm fail2ban-ui podman rm fail2ban-ui
``` ```
## First Launch & Server Configuration **Execute commands inside the container:**
After starting the container, access the web interface at `http://localhost:8080` (or your configured port). ```bash
podman exec -it fail2ban-ui /bin/bash
```
**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. ## Volume Mounts
The UI uses an embedded SQLite database to store all server configurations and ban events. The database is stored in the `/config` volume mount. The Fail2Ban UI container requires several volume mounts to function properly. Below is a detailed explanation of each volume:
> **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. ### Required Volumes
#### `/config` - Configuration and Database Storage
- **Host Path:** `/opt/podman-fail2ban-ui` (or your preferred location)
- **Container Path:** `/config`
- **Purpose:** Stores the SQLite database (`fail2ban-ui.db`), application settings, and SSH keys for remote server connections
- **Permissions:** Read/Write
- **SELinux Context:** `:Z` flag required on SELinux-enabled systems
- **Contents:**
- `fail2ban-ui.db` - SQLite database with server configurations and ban events
- `.ssh/` - Directory for SSH keys used for remote server connections
- Application configuration files
#### `/etc/fail2ban` - Fail2Ban Configuration Directory
- **Host Path:** `/etc/fail2ban`
- **Container Path:** `/etc/fail2ban`
- **Purpose:** Access to Fail2Ban configuration files (jails, filters, actions)
- **Permissions:** Read/Write (required for configuration management)
- **SELinux Context:** `:Z` flag required on SELinux-enabled systems
- **Note:** Required if managing local Fail2Ban instance
#### `/var/run/fail2ban` - Fail2Ban Socket Directory
- **Host Path:** `/var/run/fail2ban`
- **Container Path:** `/var/run/fail2ban`
- **Purpose:** Access to Fail2Ban control socket (`fail2ban.sock`)
- **Permissions:** Read/Write
- **SELinux Context:** Not required (tmpfs)
- **Note:** Required for local Fail2Ban management
### Optional Volumes
#### `/var/log` - System Log Files
- **Host Path:** `/var/log`
- **Container Path:** `/var/log`
- **Purpose:** Read access to system logs for filter testing and log analysis
- **Permissions:** Read-Only (`:ro`)
- **SELinux Context:** `:ro` flag prevents SELinux issues
- **Note:** Useful for testing Fail2Ban filters against log files
#### `/usr/share/GeoIP` - GeoIP Database Directory
- **Host Path:** `/usr/share/GeoIP`
- **Container Path:** `/usr/share/GeoIP`
- **Purpose:** Access to GeoIP databases for geographic threat analysis
- **Permissions:** Read-Only (`:ro`)
- **SELinux Context:** `:ro` flag prevents SELinux issues
- **Note:** Optional but recommended for geographic IP analysis features
### Volume Summary Table
| Volume | Required | Read/Write | SELinux Context | Purpose |
|--------|----------|------------|-----------------|---------|
| `/config` | ✅ Yes | Read/Write | `:Z` | Database, settings, SSH keys |
| `/etc/fail2ban` | ✅ Yes* | Read/Write | `:Z` | Fail2Ban configuration files |
| `/var/run/fail2ban` | ✅ Yes* | Read/Write | - | Fail2Ban control socket |
| `/var/log` | ⚠️ Optional | Read-Only | `:ro` | System log files |
| `/usr/share/GeoIP` | ⚠️ Optional | Read-Only | `:ro` | GeoIP databases |
*Required only if managing a local Fail2Ban instance. Not needed for remote-only deployments.
---
## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Port number for the web interface |
| `CONTAINER` | `true` | Automatically set by the container (do not override) |
### First Launch Configuration
After starting the container, access the web interface and configure your first Fail2Ban server:
1. **Access the Web Interface**
- Navigate to `http://localhost:8080` (or your configured port)
2. **Add Your First Server**
- Go to **Settings** → **Manage Servers**
- **Local Server**: Enable the local connector if Fail2Ban runs on the same host
- **Remote Server**: Add via SSH or API agent connection
3. **Configure Settings**
- Set up email alerts (optional)
- Configure language preferences
- Adjust security settings
> **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.
---
## Docker Compose
For easier management, you can use Docker Compose. Create a `docker-compose.yml` file:
```yaml
version: '3.8'
services:
fail2ban-ui:
image: registry.swissmakers.ch/infra/fail2ban-ui:latest
# Or build from source:
# build:
# context: .
# dockerfile: Dockerfile
container_name: fail2ban-ui
network_mode: host
restart: unless-stopped
environment:
- PORT=8436 # Custom port (optional, defaults to 8080)
volumes:
# Required: Configuration and database storage
- /opt/podman-fail2ban-ui:/config:Z
# Required: Fail2Ban configuration directory
- /etc/fail2ban:/etc/fail2ban:Z
# Required: Fail2Ban socket directory
- /var/run/fail2ban:/var/run/fail2ban
# Optional: System logs (read-only)
- /var/log:/var/log:ro
# Optional: GeoIP databases (read-only)
- /usr/share/GeoIP:/usr/share/GeoIP:ro
```
**Start with Docker Compose:**
```bash
docker-compose up -d
```
**View logs:**
```bash
docker-compose logs -f
```
**Stop:**
```bash
docker-compose down
```
---
## SELinux Configuration
If SELinux is enabled on your system, you must apply the required SELinux policies to allow the container to communicate with Fail2Ban.
### Apply Pre-built Policies
The policies are located in `./SELinux/`:
```bash
cd deployment/container/SELinux
semodule -i fail2ban-container-ui.pp
semodule -i fail2ban-container-client.pp
```
### Manually Compile and Install Policies
If you want to modify or compile the SELinux rules yourself:
```bash
cd deployment/container/SELinux
# Compile the module
checkmodule -M -m -o fail2ban-container-client.mod fail2ban-container-client.te
# Package the module
semodule_package -o fail2ban-container-client.pp -m fail2ban-container-client.mod
# Install the module
semodule -i fail2ban-container-client.pp
```
### Verify SELinux Policies
```bash
semodule -l | grep fail2ban
```
You should see:
- `fail2ban-container-ui`
- `fail2ban-container-client`
---
## Troubleshooting ## Troubleshooting
### UI Not Accessible ### UI Not Accessible
- Ensure port **8080 (or custom port)** is **not blocked** by the firewall. (e.g. firewalld)
- Check container logs: **Symptoms:** Cannot access web interface
```bash
podman logs fail2ban-ui **Solutions:**
``` 1. **Check if container is running:**
- Ensure **Fail2Ban UI is running** inside the container: ```bash
```bash podman ps | grep fail2ban-ui
podman exec -it fail2ban-ui ps aux ```
```
2. **Check container logs:**
```bash
podman logs fail2ban-ui
```
3. **Verify port is not blocked by firewall:**
```bash
sudo firewall-cmd --list-ports
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload
```
4. **Check if Fail2Ban UI process is running inside container:**
```bash
podman exec -it fail2ban-ui ps aux | grep fail2ban-ui
```
5. **Verify port configuration:**
- Check if `PORT` environment variable is set correctly
- Check container logs for the actual port being used
### No Servers Configured ### No Servers Configured
- On first launch, you must add at least one Fail2ban server
- Go to **Settings** → **Manage Servers** in the web UI **Symptoms:** Empty dashboard, no servers visible
- Enable the local connector or add a remote server via SSH
**Solutions:**
1. Navigate to **Settings** → **Manage Servers** in the web UI
2. Enable **Local Connector** (if Fail2Ban runs locally)
3. Add remote server via SSH or API agent
4. Verify server connection status
### SSH Connection Issues ### SSH Connection Issues
- Verify SSH key authentication works from the host
- Ensure the SSH user has proper permissions on the remote server: **Symptoms:** Cannot connect to remote server
**Solutions:**
1. **Verify SSH key authentication works from the host:**
```bash
ssh -i /opt/podman-fail2ban-ui/.ssh/your_key user@remote-host
```
2. **Ensure SSH user has proper permissions on remote server:**
- Sudo access for `fail2ban-client` and `systemctl restart fail2ban` (configured via sudoers) - Sudo access for `fail2ban-client` and `systemctl restart fail2ban` (configured via sudoers)
- File system ACLs on `/etc/fail2ban` for configuration file access - File system ACLs on `/etc/fail2ban` for configuration file access
- See the main README for recommended setup with service account and ACLs - See the main README for recommended setup with service account and ACLs
- Check debug mode in settings for detailed error messages
- The container needs network access to remote SSH servers 3. **Check SSH keys location:**
- SSH keys should be placed in `/config/.ssh` directory inside the container - SSH keys should be placed in `/config/.ssh` directory inside the container
- Verify key permissions (should be 600)
4. **Enable debug mode:**
- Go to **Settings** → Enable debug mode for detailed error messages
5. **Verify network connectivity:**
- The container needs network access to remote SSH servers
- Check if using `--network=host` or configure proper port mappings
### Permission Denied Errors
**Symptoms:** Permission errors when accessing Fail2Ban files
**Solutions:**
1. **Check SELinux context on volumes:**
```bash
ls -Z /opt/podman-fail2ban-ui
ls -Z /etc/fail2ban
```
2. **Apply correct SELinux context:**
```bash
chcon -Rt container_file_t /opt/podman-fail2ban-ui
```
3. **Verify volume mount flags:**
- Use `:Z` flag for read/write volumes on SELinux systems
- Use `:ro` flag for read-only volumes
### Database Errors
**Symptoms:** Database-related errors in logs
**Solutions:**
1. **Check database file permissions:**
```bash
ls -la /opt/podman-fail2ban-ui/fail2ban-ui.db
```
2. **Verify database integrity:**
```bash
podman exec -it fail2ban-ui sqlite3 /config/fail2ban-ui.db "PRAGMA integrity_check;"
```
3. **Backup and recreate if corrupted:**
```bash
cp /opt/podman-fail2ban-ui/fail2ban-ui.db /opt/podman-fail2ban-ui/fail2ban-ui.db.backup
```
---
## Contact & Support ## Contact & Support
For issues, contributions, or feature requests, visit our GitHub repository: For issues, contributions, or feature requests, visit our GitHub repository:
🔗 [GitHub Issues](https://github.com/swissmakers/fail2ban-ui/issues) 🔗 [GitHub Issues](https://github.com/swissmakers/fail2ban-ui/issues)

42
docker-compose.example.yml Normal file
View File

@@ -0,0 +1,42 @@
version: '3.8'
services:
fail2ban-ui:
# Use pre-built image from registry
image: registry.swissmakers.ch/infra/fail2ban-ui:latest
# Or build from source (uncomment to use):
# build:
# context: .
# dockerfile: Dockerfile
container_name: fail2ban-ui
network_mode: host
restart: unless-stopped
environment:
# Custom port (optional, defaults to 8080)
# Change this to use a different port for the web interface
- PORT=8080
volumes:
# Required: Configuration and database storage
# Stores SQLite database, application settings, and SSH keys
- /opt/podman-fail2ban-ui:/config:Z
# Required: Fail2Ban configuration directory
# Needed for managing local Fail2Ban instance
- /etc/fail2ban:/etc/fail2ban:Z
# Required: Fail2Ban socket directory
# Needed for local Fail2Ban control socket access
- /var/run/fail2ban:/var/run/fail2ban
# Optional: System logs (read-only)
# Useful for filter testing and log analysis (or if planned to integrate fal2ban directly in this container)
- /var/log:/var/log:ro
# Optional: GeoIP databases (read-only)
# Enables geographic IP analysis features (GeoIP must be installed and configured on the host)
- /usr/share/GeoIP:/usr/share/GeoIP:ro

9
internal/config/settings.go
View File

@@ -486,8 +486,17 @@ func setDefaultsLocked() {
currentSettings.Language = "en" currentSettings.Language = "en"
} }
if currentSettings.Port == 0 { if currentSettings.Port == 0 {
// Check for PORT environment variable first
if portEnv := os.Getenv("PORT"); portEnv != "" {
if port, err := strconv.Atoi(portEnv); err == nil && port > 0 && port <= 65535 {
currentSettings.Port = port
} else {
currentSettings.Port = 8080 currentSettings.Port = 8080
} }
} else {
currentSettings.Port = 8080
}
}
if currentSettings.CallbackURL == "" { if currentSettings.CallbackURL == "" {
currentSettings.CallbackURL = fmt.Sprintf("http://127.0.0.1:%d", currentSettings.Port) currentSettings.CallbackURL = fmt.Sprintf("http://127.0.0.1:%d", currentSettings.Port)
} }