# Fail2ban 安装与 `fail2ban-client` 命令使用手册

本手册基于 **Ubuntu 24.04** 环境，结合 UFW 防火墙，详细说明 Fail2ban 的安装、配置以及 `fail2ban-client` 的常用命令。

---

## 1. Fail2ban 安装

### 1.1 通过 APT 安装
```bash
sudo apt update
sudo apt install fail2ban -y
```

### 1.2 验证服务状态
安装完成后，服务会自动启动：
```bash
sudo systemctl status fail2ban
```
- 如果未启动，可手动启动：`sudo systemctl start fail2ban`
- 设置开机自启：`sudo systemctl enable fail2ban`

---

## 2. 配置 Fail2ban（使用 UFW 作为封禁后端）

### 2.1 创建自定义配置文件
**不要直接修改 `/etc/fail2ban/jail.conf`**，因为包更新会覆盖它。应创建 `jail.local`：
```bash
sudo nano /etc/fail2ban/jail.local
```

### 2.2 基础配置示例
将以下内容粘贴到 `jail.local` 中：
```ini
[DEFAULT]
# 封禁时间（1小时）
bantime = 1h
# 检测时间窗口（10分钟）
findtime = 10m
# 最大失败尝试次数
maxretry = 5

# 关键：使用 UFW 执行封禁
banaction = ufw

# 白名单（保护自己的IP不被封禁）
# 格式：用空格分隔多个IP或CIDR
ignoreip = 127.0.0.1/8 ::1 你的.公网.IP

# 启用 SSH 防护
[sshd]
enabled = true
```

> **注意**：将 `你的.公网.IP` 替换为你的实际 IP。

### 2.3 重启 Fail2ban 使配置生效
```bash
sudo systemctl restart fail2ban
```

### 2.4 确认 UFW 已开启
启用 UFW 前，先放行 SSH 端口：
```bash
sudo ufw allow ssh
sudo ufw enable
sudo ufw status verbose
```

---

## 3. `fail2ban-client` 常用命令

`fail2ban-client` 是与 Fail2ban 服务交互的命令行工具。

### 3.1 查看整体状态
```bash
sudo fail2ban-client status
```
输出示例：
```
Status
|- Number of jail:	1
`- Jail list:	sshd
```

### 3.2 查看特定监狱（Jail）的详细信息
```bash
sudo fail2ban-client status sshd
```
输出示例：
```
Status for the jail: sshd
|- Filter
|  |- Currently failed: 0
|  |- Total failed:     123
|  `- File list:        /var/log/auth.log
`- Actions
   |- Currently banned: 3
   |- Total banned:     15
   `- Banned IP list:   91.92.40.239 27.49.238.44 176.65.139.183
```

### 3.3 查看所有监狱的被封禁 IP（汇总）
```bash
sudo fail2ban-client banned
```
输出格式类似：
```
{
    "sshd": ["91.92.40.239", "27.49.238.44"]
}
```

### 3.4 手动封禁 IP
```bash
sudo fail2ban-client set <监狱名> banip <IP地址>
```
示例：
```bash
sudo fail2ban-client set sshd banip 203.0.113.5
```

### 3.5 手动解封 IP
```bash
sudo fail2ban-client set <监狱名> unbanip <IP地址>
```
示例：
```bash
sudo fail2ban-client set sshd unbanip 203.0.113.5
```

### 3.6 重载配置（修改配置后无需重启服务）
```bash
sudo fail2ban-client reload
```
若只想重载特定监狱：
```bash
sudo fail2ban-client reload sshd
```

### 3.7 查看 Fail2ban 日志（含封禁记录）
```bash
sudo grep "Ban" /var/log/fail2ban.log
```
或实时监控：
```bash
sudo tail -f /var/log/fail2ban.log | grep "Ban"
```

### 3.8 测试配置文件语法
```bash
sudo fail2ban-client -t
```

### 3.9 前台运行调试（用于测试）
```bash
sudo fail2ban-client -f start
```
按 `Ctrl+C` 停止。

---

## 4. 封禁策略调整

### 4.1 修改封禁时长
在 `jail.local` 的 `[DEFAULT]` 或具体监狱中修改 `bantime`：
- `bantime = 1h`（1小时）
- `bantime = 86400`（24小时，单位为秒）
- 设为 `-1` 表示永久封禁。

### 4.2 修改失败次数阈值
`maxretry` 决定在 `findtime` 内失败多少次触发封禁。

### 4.3 添加白名单
在 `ignoreip` 中添加 IP 或网段，用空格分隔。

### 4.4 封禁其他服务（如 HTTP）
可以启用 `[nginx-http-auth]` 等监狱，只需在 `jail.local` 中添加：
```ini
[nginx-http-auth]
enabled = true
port    = http,https
logpath = /var/log/nginx/error.log
```

---

## 5. 常见问题排查

### 5.1 Fail2ban 未生效
- 检查日志路径是否正确（如 `/var/log/auth.log`）。
- 确认 `enabled = true` 已设置。
- 查看服务日志：`sudo journalctl -u fail2ban -f`

### 5.2 封禁后仍可访问
- 确认 `banaction = ufw` 配置正确。
- 检查 UFW 是否启用：`sudo ufw status`
- 查看防火墙实际规则：`sudo iptables -L -n | grep DROP` 或 `sudo nft list ruleset`

### 5.3 误封自己的 IP
- 立即解封：`sudo fail2ban-client set sshd unbanip 你的IP`
- 并检查 `ignoreip` 是否正确配置。

---

## 6. 卸载 Fail2ban
```bash
sudo apt remove fail2ban -y
sudo apt autoremove -y
```

---

## 附录：常用命令速查表

| 目的             | 命令                                           |
| :------------- | :------------------------------------------- |
| 查看所有监狱状态       | `sudo fail2ban-client status`                |
| 查看某监狱详情（含封禁IP） | `sudo fail2ban-client status sshd`           |
| 查看所有被封禁IP      | `sudo fail2ban-client banned`                |
| 手动封禁IP         | `sudo fail2ban-client set sshd banip <IP>`   |
| 手动解封IP         | `sudo fail2ban-client set sshd unbanip <IP>` |
| 重载配置           | `sudo fail2ban-client reload`                |
| 查看封禁日志         | `sudo grep "Ban" /var/log/fail2ban.log`      |
| 测试配置           | `sudo fail2ban-client -t`                    |

---

本手册适用于 Ubuntu 24.04 + UFW 环境，按照以上步骤即可快速部署并管理 Fail2ban。如有其他需求，可参考官方文档或社区资源。