fail2ban-ui/deployment/container/README.md

Fail2Ban UI Container Deployment Guide

A comprehensive guide for building and deploying Fail2Ban UI using containers (Docker/Podman).

Table of Contents

• Quick Start
• Building the Container Image
• Running the Container
• Volume Mounts
• Configuration
• Docker Compose
• SELinux Configuration
• Troubleshooting

---

Quick Start

Using Pre-built Image

Pull the official 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 \
  --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 \
  registry.swissmakers.ch/infra/fail2ban-ui:latest

Access the web interface at http://localhost:8080 (or your configured port).

---

Building the Container Image

Prerequisites

• Docker or Podman installed
• Git (to clone the repository)

Build Steps

1. Clone the repository:

   git clone https://github.com/swissmakers/fail2ban-ui.git
   cd fail2ban-ui
   

2. Build the image:

   # 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:

   podman images fail2ban-ui
   # or
   docker images fail2ban-ui
   

Build Options

You can customize the build with additional flags:

# 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

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:

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:

podman start fail2ban-ui

Stop the container:

podman stop fail2ban-ui

View logs:

podman logs -f fail2ban-ui

Remove the container:

podman stop fail2ban-ui
podman rm fail2ban-ui

Execute commands inside the container:

podman exec -it fail2ban-ui /bin/bash

---

Volume Mounts

The Fail2Ban UI container requires several volume mounts to function properly. Below is a detailed explanation of each volume:

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:

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:

docker-compose up -d

View logs:

docker-compose logs -f

Stop:

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/:

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:

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

semodule -l | grep fail2ban

You should see:

• fail2ban-container-ui
• fail2ban-container-client

---

Troubleshooting

UI Not Accessible

Symptoms: Cannot access web interface

Solutions:

1. Check if container is running:

   podman ps | grep fail2ban-ui
   

2. Check container logs:

   podman logs fail2ban-ui
   

3. Verify port is not blocked by firewall:

   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:

   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

Symptoms: Empty dashboard, no servers visible

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

Symptoms: Cannot connect to remote server

Solutions:

1. Verify SSH key authentication works from the host:

   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)
   • File system ACLs on /etc/fail2ban for configuration file access
   • See the main README for recommended setup with service account and ACLs

3. Check SSH keys location:

   • 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:

   ls -Z /opt/podman-fail2ban-ui
   ls -Z /etc/fail2ban
   

2. Apply correct SELinux context:

   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:

   ls -la /opt/podman-fail2ban-ui/fail2ban-ui.db
   

2. Verify database integrity:

   podman exec -it fail2ban-ui sqlite3 /config/fail2ban-ui.db "PRAGMA integrity_check;"
   

3. Backup and recreate if corrupted:

   cp /opt/podman-fail2ban-ui/fail2ban-ui.db /opt/podman-fail2ban-ui/fail2ban-ui.db.backup
   

---

Contact & Support

For issues, contributions, or feature requests, visit our GitHub repository:
🔗 GitHub Issues

For enterprise support, visit:
🔗 Swissmakers GmbH