swissmakers/fail2ban-ui Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

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

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

Alternative: Pull from Swissmakers registry (fallback):

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

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

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

bash
podman start fail2ban-ui

Stop the container:

bash
podman stop fail2ban-ui

View logs:

bash
podman logs -f fail2ban-ui

Remove the container:

bash
podman stop fail2ban-ui
podman rm fail2ban-ui

Execute commands inside the container:

bash
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., [***] or your configured port)
     • For reverse proxy setups: Use your TLS-encrypted endpoint (e.g., [***])
     • 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

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.

Important: The Fail2Ban Callback URL must be accessible from all Fail2Ban instances (local and remote) that need to send alerts. If you change the Fail2Ban UI port, ensure the callback URL is updated accordingly.

---

Docker Compose

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

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

bash
docker-compose up -d

View logs:

bash
docker-compose logs -f

Stop:

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

yaml
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

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

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

UI Not Accessible

Symptoms: Cannot access web interface

Solutions:

1. Check if container is running:

   bash
   podman ps | grep fail2ban-ui
   

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

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:

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

   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

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

For enterprise support, visit:
🔗 Swissmakers GmbH