swissmakers/fail2ban-ui repository overview

⁠Fail2Ban UI Container Deployment Guide

A guide for deploying Fail2Ban UI using Docker/Podman.

⁠Table of Contents

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

⁠Quick Start

⁠Using Pre-built Image

Pull the official image with podman from Docker Hub (default):

podman pull swissmakers/fail2ban-ui:latest
# or with Docker:
docker pull swissmakers/fail2ban-ui:latest

Alternative: Pull from Swissmakers registry (fallback):

podman pull registry.swissmakers.ch/infra/fail2ban-ui:latest
docker pull registry.swissmakers.ch/infra/fail2ban-ui:latest

⁠Running the Container

⁠Basic Run Command (for a local fail2ban connection - fail2ban on host)

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 \
  swissmakers/fail2ban-ui:latest

⁠Custom Port Configuration and using only remote fail2ban (over ssh)

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 \
  swissmakers/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 (reqired for local fail2ban connector only)

• 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 (reqired for local fail2ban connector only)

• 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

⁠/var/log - Log Files (reqired for local fail2ban connector only)

• Host Path: /var/log
• Container Path: /var/log
• Purpose: Read access to system logs for automatically logpath-tests on jail enabe
• Permissions: Read-Only (:ro)
• Note: If test fails, jail is auto-disabled to prevent fail2ban daemon errors

⁠Optional Volumes

⁠GeoLite2-Country.mmdb - GeoIP Database

• Host Path: /path/to/your/GeoIPFolder
• Container Path: e.g. /usr/share/GeoIP paht must match the settings in the UI.
• Purpose: Only needed if you want to use the MaxMind provider.
• Permissions: Read-Only (:ro)
• Note: Fail2Ban UI uses the built-in ip-api.com by default, which requires no local database

⁠Volume Summary Table

*Required only if managing a local Fail2Ban instance. Not needed for remote-only deployments.

⁠Configuration

⁠Environment Variables

⁠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

   • Fail2Ban Callback URL: This URL is used by all Fail2Ban instances to send ban alerts back to Fail2Ban UI
     • For local deployments: Use the same port as Fail2Ban UI (e.g., http://127.0.0.1:8080 or your configured port)
     • For reverse proxy setups: Use your TLS-encrypted endpoint (e.g., https://fail2ban.example.com)
     • The callback URL automatically updates when you change the server port (if using the default localhost pattern)
   • Callback URL Secret: Auto-generated 42-character secret for authenticating ban notification requests (viewable in Settings with show/hide toggle)
   • GeoIP Provider: Choose between MaxMind (local database) or Built-in (ip-api.com) - default is Built-in
   • Maximum Log Lines: Configure how many log lines to include in ban notifications (default: 50)
   • Set up email alerts (optional)
   • Configure language preferences
   • Adjust security settings

⁠Docker Compose

For easier management, you can use Docker Compose. Create a docker-compose.yml file:

services:
  fail2ban-ui:
    # Use pre-built image from Docker Hub (default)
    image: swissmakers/fail2ban-ui:latest

    # Alternative: Use Swissmakers registry (fallback)
    # image: registry.swissmakers.ch/infra/fail2ban-ui:latest

    # Or build from source (uncomment to use):
    # build:
    #   context: .
    #   dockerfile: Dockerfile

    container_name: fail2ban-ui
    #privileged: true # needed if you want to use a container-local fail2ban instance (because fail2ban.sock is owned by root)
    # a single all-in-one container is planned, currently you need to use the fail2ban container from linuxserver, see docker-compose-allinone.yml for an example
    network_mode: host

    environment:
      # Change this to use a different port for the web interface (defaults is 8080)
      - PORT=8080

    volumes:
      # Required for fail2ban-ui: Stores SQLite database, application settings, and SSH keys of the fail2ban-ui container
      - /opt/podman-fail2ban-ui:/config:Z
      # Required for fail2ban-ui: Used for testing, that logpath is working, before enabeling a jail. Without this read only access the fail2ban-ui will not be able to enable jails (logpath-test would fail)
      - /var/log:/var/log:ro

      # Required for local fail2ban instance: Fail2Ban configuration directory, needed for managing a local Fail2Ban instance (e.g. on host system) via fail2ban-ui
      - /etc/fail2ban:/etc/fail2ban:Z
      # Required for local fail2ban instance: Fail2Ban socket directory, needed for local Fail2Ban (e.g. on host system) for control via fail2ban-ui
      - /var/run/fail2ban:/var/run/fail2ban

      # Optional: Map MaxMind GeoIP databases (only needed if using MaxMind provider)
      #- /usr/share/GeoIP:/usr/share/GeoIP:ro

    restart: unless-stopped

Start with Docker Compose:

docker-compose up -d

View logs:

docker-compose logs -f

Stop:

docker-compose down

⁠All-in-One Docker Compose Setup

For a complete containerized setup with both Fail2Ban and Fail2Ban UI, use the all-in-one Docker Compose configuration:

services:
  fail2ban:
    image: lscr.io/linuxserver/fail2ban:latest
    container_name: fail2ban
    cap_add:
      # Required for fail2ban container: Allows to manage network interfaces and iptables from the container
      - NET_ADMIN
      # Required for fail2ban container: Allows to create raw sockets (needed for fail2ban.sock)
      - NET_RAW
      # Required for fail2ban container: Allows to run as root (needed to manage network interfaces and raw sockets)
      - SYS_ADMIN
    #privileged: true
    network_mode: host # needed to add iptables rules to the host network
    environment:
      - TZ=Europe/Zurich
      - VERBOSITY=-vv
    volumes:
      # To make sure linuxserver-fail2ban configs are persistent across container restarts (also needed by fail2ban-ui to modify configs)
      - ./fail2ban-config:/config:z
      # Directory that contains fail2ban.sock for communication between fail2ban-ui and fail2ban container
      - ./f2b-run:/var/run/fail2ban:z

      # Log sources for fail2ban container
      - /var/log:/var/log:ro
      - /var/log/httpd:/remotelogs/apache2:ro
    restart: unless-stopped

  fail2ban-ui:
    # Use pre-built image from Docker Hub (default)
    image: swissmakers/fail2ban-ui:latest
    # Alternative: Use Swissmakers registry (fallback)
    # image: registry.swissmakers.ch/infra/fail2ban-ui:latest
    # Or build from source (uncomment to use):
    # image: localhost/fail2ban-ui:dev
    container_name: fail2ban-ui
    privileged: true # needed because the fail2ban-ui container needs to modify the fail2ban config owned by root inside the linuxserver-fail2ban container
    network_mode: host
    environment:
      # Optional: Change this to use a different port for the web interface (defaults is 8080)
      - PORT=3080
      # Optional: Bind to a specific IP address (default: 0.0.0.0)
      # This is useful when running with host networking to prevent exposing
      # the web UI to unprotected networks. Set to a specific IP (e.g., 127.0.0.1
      # or a specific interface IP) to restrict access.
      # - BIND_ADDRESS=127.0.0.1
    volumes:
      # Required for fail2ban-ui: Stores SQLite database, application settings, and SSH keys of the fail2ban-ui container
      - ./config:/config:Z
      # Required for fail2ban-ui: Used for testing, that logpath is working, before enabeling a jail. Without this read only access the fail2ban-ui will not be able to enable jails (logpath-test would fail)
      - /var/log:/var/log:ro
      - /var/log/httpd:/remotelogs/apache2:ro # this mounts the apache2 logs of a RPM based system (e.g. Rocky Linux) to the default location set by linuxserver-fail2ban. (on debian based systems this is /var/log/apache2 and currently hardcoded in the linuxserver-fail2ban container)

      # Required for compose-local fail2ban instance: We mount the same Fail2Ban config as the linuxserver-fail2ban container (under /config/fail2ban to fail2ban-ui can modify configs)
      - ./fail2ban-config/fail2ban:/etc/fail2ban:z
      # Required for compose-local fail2ban instance: Mount the same run directory that contains fail2ban.sock for communication between fail2ban-ui and the linuxserver-fail2ban container
      - ./f2b-run:/var/run/fail2ban:z

    restart: unless-stopped

# Edit docker-compose to customize:
# - PORT environment variable for Fail2Ban UI
# - Timezone (TZ environment variable)
# - Volume paths

# Start both services
docker-compose up -d

Features:

• Combined Setup: Fail2Ban (linuxserver/fail2ban) and Fail2Ban UI in one compose file
• Shared Configuration: Both containers share the same Fail2Ban configuration directory
• Shared Socket: Both containers access the same Fail2Ban control socket
• Network Mode: Uses host network mode for proper iptables integration

Volume Structure:

./fail2ban-config/fail2ban  → /config/fail2ban (fail2ban container)
./fail2ban-config/fail2ban  → /etc/fail2ban (fail2ban-ui container)
./f2b-run                   → /var/run/fail2ban (both containers)
./config                    → /config (fail2ban-ui container)

Important Notes:

• The fail2ban-ui container requires privileged: true to modify Fail2Ban configs owned by root
• Both containers must use network_mode: host for proper networking
• Ensure SELinux labels are correct (:z or :Z flags)

⁠SELinux Configuration (only when using fail2ban-ui with a fail2ban instance on host)

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 (github)

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
   

   Copy

2. Check container logs:

   podman logs fail2ban-ui
   

   Copy

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
   

   Copy

4. Check if Fail2Ban UI process is running inside container:

   podman exec -it fail2ban-ui ps aux | grep fail2ban-ui
   

   Copy

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
   

   Copy

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
   

   Copy

2. Apply correct SELinux context:

   chcon -Rt container_file_t /opt/podman-fail2ban-ui
   

   Copy

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
   

   Copy

2. Verify database integrity:

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

   Copy

3. Backup and recreate if corrupted:

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

   Copy

⁠Contact & Support

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

For enterprise support, visit:
🔗 Swissmakers GmbH⁠