swissmakers/fail2ban-ui

Fail2Ban UI容器部署指南

使用Docker/Podman部署Fail2Ban UI的指南。

目录

• 快速开始
• 运行容器
• 卷挂载
• 配置
• Docker Compose
• SELinux配置
• 故障排除

快速开始

使用预构建镜像

使用podman从Docker Hub拉取官方镜像（默认）：

bash
podman pull swissmakers/fail2ban-ui:latest
# 或使用Docker：
docker pull swissmakers/fail2ban-ui:latest

备选：从Swissmakers registry拉取（备用）：

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

运行容器

基本运行命令（用于本地Fail2Ban连接 - Fail2Ban在主机上）

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

自定义端口配置并仅使用远程Fail2Ban（通过SSH）

可以使用PORT环境变量更改默认端口（8080）：

bash
podman run -d \
  --name fail2ban-ui \
  --network=host \
  -e PORT=8436 \
  -v /opt/podman-fail2ban-ui:/config:Z \
  swissmakers/fail2ban-ui:latest

通过http://localhost:8436访问Web界面。

容器管理

启动容器：

bash
podman start fail2ban-ui

停止容器：

bash
podman stop fail2ban-ui

查看日志：

bash
podman logs -f fail2ban-ui

删除容器：

bash
podman stop fail2ban-ui
podman rm fail2ban-ui

在容器内执行命令：

bash
podman exec -it fail2ban-ui /bin/bash

---

卷挂载

Fail2Ban UI容器需要几个卷挂载才能正常运行。以下是每个卷的详细说明：

必需卷

/config - 配置和数据库存储

• 主机路径： /opt/podman-fail2ban-ui（或您偏好的位置）
• 容器路径： /config
• 用途： 存储SQLite数据库（fail2ban-ui.db）、应用设置和远程服务器连接的SSH密钥
• 权限： 读写
• SELinux上下文： SELinux启用系统需要:Z标志
• 内容：
  • fail2ban-ui.db - 包含服务器配置和封禁事件的SQLite数据库
  • .ssh/ - 用于远程服务器连接的SSH密钥目录
  • 应用配置文件

/etc/fail2ban - Fail2Ban配置目录（仅本地Fail2Ban连接器需要）

• 主机路径： /etc/fail2ban
• 容器路径： /etc/fail2ban
• 用途： 访问Fail2Ban配置文件（jails、filters、actions）
• 权限： 读写（配置管理所需）
• SELinux上下文： SELinux启用系统需要:Z标志
• 注意： 管理本地Fail2Ban实例时需要

/var/run/fail2ban - Fail2Ban套接字目录（仅本地Fail2Ban连接器需要）

• 主机路径： /var/run/fail2ban
• 容器路径： /var/run/fail2ban
• 用途： 访问Fail2Ban控制套接字（fail2ban.sock）
• 权限： 读写
• SELinux上下文： 不需要（tmpfs）
• 注意： 本地Fail2Ban管理所需

/var/log - 日志文件（仅本地Fail2Ban连接器需要）

• 主机路径： /var/log
• 容器路径： /var/log
• 用途： 读取系统日志以在启用jail时自动进行logpath测试
• 权限： 只读（:ro）
• 注意： 如果测试失败，jail将自动禁用以防止Fail2Ban守护程序错误

可选卷

GeoLite2-Country.mmdb - GeoIP数据库

• 主机路径： /path/to/your/GeoIPFolder
• 容器路径： 例如/usr/share/GeoIP（路径必须与UI中的设置匹配）
• 用途： 仅在需要使用MaxMind提供程序时需要
• 权限： 只读（:ro）
• 注意： Fail2Ban UI默认使用内置的ip-api.com，无需本地数据库

卷摘要表

*仅在管理本地Fail2Ban实例时需要。远程部署不需要。

---

配置

环境变量

首次启动配置

启动容器后，访问Web界面并配置第一个Fail2Ban服务器：

1. 访问Web界面

   • 导航至http://localhost:8080（或您配置的端口）

2. 添加第一个服务器

   • 进入设置 → 管理服务器
   • 本地服务器：如果Fail2Ban在同一主机上运行，启用本地连接器
   • 远程服务器：通过SSH或API代理连接添加

3. 配置设置

   • Fail2Ban回调URL：所有Fail2Ban实例用于向Fail2Ban UI发送封禁警报的URL
     • 本地部署：使用与Fail2Ban UI相同的端口（例如http://127.0.0.1:8080或您配置的端口）
     • 反向代理设置：使用TLS加密端点（例如https://fail2ban.example.com）
     • 更改服务器端口时，回调URL会自动更新（如果使用默认本地主机模式）
   • 回调URL密钥：用于验证封禁通知请求的自动生成42字符密钥（可在设置中通过显示/隐藏切换查看）
   • GeoIP提供程序：选择MaxMind（本地数据库）或内置（ip-api.com）- 默认是内置
   • 最大日志行数：配置封禁通知中包含的日志行数（默认：50）
   • 设置电子邮件告警（可选）
   • 配置语言偏好
   • 调整安全设置

注意： 本地Fail2Ban服务是可选的。Fail2Ban UI可以通过SSH或API代理管理远程Fail2Ban服务器，无需在容器中安装本地Fail2Ban。

重要： Fail2Ban回调URL必须对所有需要发送警报的Fail2Ban实例（本地和远程）可访问。如果更改Fail2Ban UI端口，请确保回调URL相应更新。

---

Docker Compose

为便于管理，您可以使用Docker Compose。创建docker-compose.yml文件：

yaml
services:
  fail2ban-ui:
    # 使用Docker Hub的预构建镜像（默认）
    image: swissmakers/fail2ban-ui:latest

    # 备选：使用Swissmakers registry（备用）
    # image: registry.swissmakers.ch/infra/fail2ban-ui:latest

    # 或从源码构建（取消注释使用）：
    # build:
    #   context: .
    #   dockerfile: Dockerfile

    container_name: fail2ban-ui
    # privileged: true # 如果需要使用容器本地的fail2ban实例则需要（因为fail2ban.sock归root所有）
    # 计划推出一体化容器，目前需要使用linuxserver的fail2ban容器，详见docker-compose-allinone.yml示例
    network_mode: host

    environment:
      # 更改Web界面端口（默认8080）
      - PORT=8080

    volumes:
      # Fail2Ban UI必需：存储SQLite数据库、应用设置和SSH密钥
      - /opt/podman-fail2ban-ui:/config:Z
      # Fail2Ban UI必需：用于测试logpath是否有效（启用jail前）。没有此只读访问，Fail2Ban UI将无法启用jails（logpath测试会失败）
      - /var/log:/var/log:ro

      # 本地Fail2Ban实例必需：Fail2Ban配置目录，用于通过Fail2Ban UI管理本地Fail2Ban实例（如主机系统）
      - /etc/fail2ban:/etc/fail2ban:Z
      # 本地Fail2Ban实例必需：Fail2Ban套接字目录，用于通过Fail2Ban UI控制本地Fail2Ban（如主机系统）
      - /var/run/fail2ban:/var/run/fail2ban

      # 可选：映射MaxMind GeoIP数据库（仅在使用MaxMind提供程序时需要）
      #- /usr/share/GeoIP:/usr/share/GeoIP:ro

    restart: unless-stopped

使用Docker Compose启动：

bash
docker-compose up -d

查看日志：

bash
docker-compose logs -f

停止：

bash
docker-compose down

一体化Docker Compose设置

要使用Fail2Ban和Fail2Ban UI的完整容器化设置，请使用一体化Docker Compose配置：

yaml
services:
  fail2ban:
    image: lscr.io/linuxserver/fail2ban:latest
    container_name: fail2ban
    cap_add:
      # Fail2Ban容器必需：允许从容器管理网络接口和iptables
      - NET_ADMIN
      # Fail2Ban容器必需：允许创建原始套接字（fail2ban.sock需要）
      - NET_RAW
      # Fail2Ban容器必需：允许以root身份运行（管理网络接口和原始套接字需要）
      - SYS_ADMIN
    # privileged: true
    network_mode: host # 需要将iptables规则添加到主机网络
    environment:
      - TZ=Europe/Zurich
      - VERBOSITY=-vv
    volumes:
      # 确保linuxserver-fail2ban配置在容器重启后持久化（也供fail2ban-ui修改配置）
      - ./fail2ban-config:/config:z
      # 包含fail2ban.sock的目录，用于fail2ban-ui和fail2ban容器之间的通信
      - ./f2b-run:/var/run/fail2ban:z

      # Fail2Ban容器的日志源
      - /var/log:/var/log:ro
      - /var/log/httpd:/remotelogs/apache2:ro
    restart: unless-stopped

  fail2ban-ui:
    # 使用Docker Hub的预构建镜像（默认）
    image: swissmakers/fail2ban-ui:latest
    # 备选：使用Swissmakers registry（备用）
    # image: registry.swissmakers.ch/infra/fail2ban-ui:latest
    # 或从源码构建（取消注释使用）：
    # image: localhost/fail2ban-ui:dev
    container_name: fail2ban-ui
    privileged: true # 需要，因为fail2ban-ui容器需要修改linuxserver-fail2ban容器中root拥有的配置
    network_mode: host
    environment:
      # 可选：更改Web界面端口（默认8080）
      - PORT=3080
      # 可选：绑定到特定IP地址（默认：0.0.0.0）
      # 在使用主机网络时有用，可防止Web UI暴露到未受保护的网络。设置为特定IP（如127.0.0.1或特定接口IP）以限制访问。
      # - BIND_ADDRESS=127.0.0.1
    volumes:
      # Fail2Ban UI必需：存储SQLite数据库、应用设置和SSH密钥
      - ./config:/config:Z
      # Fail2Ban UI必需：用于测试logpath是否有效（启用jail前）。没有此只读访问，Fail2Ban UI将无法启用jails（logpath测试会失败）
      - /var/log:/var/log:ro
      - /var/log/httpd:/remotelogs/apache2:ro # 将RPM系统（如Rocky Linux）的apache2日志挂载到linuxserver-fail2ban的默认位置（Debian系统为/var/log/apache2，目前在linuxserver-fail2ban容器中硬编码）

      # Compose本地Fail2Ban实例必需：挂载与linuxserver-fail2ban容器相同的Fail2Ban配置（/config/fail2ban供fail2ban-ui修改配置）
      - ./fail2ban-config/fail2ban:/etc/fail2ban:z
      # Compose本地Fail2Ban实例必需：挂载包含fail2ban.sock的同一运行目录，用于fail2ban-ui和linuxserver-fail2ban容器之间的通信
      - ./f2b-run:/var/run/fail2ban:z

    restart: unless-stopped

bash
# 编辑docker-compose进行自定义：
# - Fail2Ban UI的PORT环境变量
# - 时区（TZ环境变量）
# - 卷路径

# 启动两个服务
docker-compose up -d

特性：

• 组合设置：Fail2Ban（linuxserver/fail2ban）和Fail2Ban UI在一个compose文件中
• 共享配置：两个容器共享相同的Fail2Ban配置目录
• 共享套接字：两个容器访问相同的Fail2Ban控制套接字
• 网络模式：使用host网络模式以实现正确的iptables集成

卷结构：

./fail2ban-config/fail2ban  → /config/fail2ban（fail2ban容器）
./fail2ban-config/fail2ban  → /etc/fail2ban（fail2ban-ui容器）
./f2b-run                   → /var/run/fail2ban（两个容器）
./config                    → /config（fail2ban-ui容器）

重要注意事项：

• fail2ban-ui容器需要privileged: true以修改root拥有的Fail2Ban配置
• 两个容器必须使用network_mode: host以实现正确的网络功能
• 确保SELinux标签正确（:z或:Z标志）

---

SELinux配置（仅在将fail2ban-ui与主机上的fail2ban实例一起使用时）

如果系统启用了SELinux，必须应用所需的SELinux策略以允许容器与Fail2Ban通信。

应用预构建策略（GitHub）

策略位于./SELinux/：

bash
cd deployment/container/SELinux
semodule -i fail2ban-container-ui.pp
semodule -i fail2ban-container-client.pp

手动编译和安装策略

如果要修改或自行编译SELinux规则：

bash
cd deployment/container/SELinux

# 编译模块
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

验证SELinux策略

bash
semodule -l | grep fail2ban

应显示：

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

---

故障排除

UI无法访问

症状： 无法访问Web界面

解决方法：

1. 检查容器是否运行：

   bash
   podman ps | grep fail2ban-ui
   

2. 检查容器日志：

   bash
   podman logs