# IPTables-Management

一个基于 Bash 的中文交互式 IPTables 端口转发管理工具，面向 Debian 12/13。

- 启动时自动做环境自检。
- 仅管理本工具创建的 `MGMT:<UUID>` 规则。
- 支持 TCP / UDP / both，支持 IPv4 / IPv6 / both。
- 在 `FORWARD` 默认策略为 `DROP` 时也会补齐回程放行规则。
- 支持 `iptables-persistent` / `netfilter-persistent save` 持久化。
- 所有写操作通过 `flock` 串行化，降低多实例并发竞争风险。
- 附带单元测试与真实 iptables 集成测试。

## 目录结构

```text
.
├── iptables-forward.sh      # 主入口
├── install.sh               # 创建 /usr/local/bin/iptables-forward 符号链接
├── lib/                     # 业务模块
├── tests/                   # 测试与 mock
└── plan_iptables_forward.md # 实施方案
```

## 运行要求

- Debian 12/13
- Bash 4+
- root 或 sudo
- `iptables`
- `ip6tables`
- `iptables-persistent`（提供 `netfilter-persistent`）

> 首次运行若缺依赖，脚本会列出缺失项并询问是否自动安装。

## 安装

### 直接运行

```bash
sudo ./iptables-forward.sh
```

### 安装到 PATH

```bash
sudo ./install.sh
sudo iptables-forward
```

默认会创建：

```text
/usr/local/bin/iptables-forward -> /path/to/IPTables-Management/iptables-forward.sh
```

若目标路径已存在且不是当前仓库脚本的符号链接，`install.sh` 会拒绝覆盖；`--uninstall` 也只会删除当前脚本创建的链接，避免误删其它文件。

## 使用说明

### 交互模式

```bash
sudo ./iptables-forward.sh
```

主菜单提供：

- 查看所有转发规则
- 添加新的转发规则
- 删除现有转发规则
- 查看系统环境状态
- 立即保存到磁盘
- 退出

主菜单状态行会同时显示环境状态、规则数、持久化可用性与运行态健康；若数据库里存在半残规则，`运行态` 会降级为 `[!]`。

规则列表中的状态列含义：

- `✓`：该条规则对应的 PREROUTING / POSTROUTING / 双向 FORWARD 运行态规则都存在
- `!`：至少缺少一条运行态规则，或仅剩数据库记录

列表表头与内容会按显示宽度对齐，中文与 ASCII 混排时也尽量保持列起始位置一致。

### 批处理模式

用于自动化测试或脚本调用：

```bash
sudo ./iptables-forward.sh --batch add <proto> <listen_port> <target_ip> <target_port> <ipver> [desc]
sudo ./iptables-forward.sh --batch delete <uuid>
sudo ./iptables-forward.sh --batch list
sudo ./iptables-forward.sh --batch save
sudo ./iptables-forward.sh --batch env
```

参数说明：

- `proto`: `tcp` / `udp` / `both`
- `ipver`: `4` / `6` / `both`
- `target_ip`:
  - `ipver=4` 时传单个 IPv4
  - `ipver=6` 时传单个 IPv6
  - `ipver=both` 时传 `IPv4,IPv6`，例如 `127.0.0.1,::1`

示例：

```bash
sudo ./iptables-forward.sh --batch add tcp 8080 192.168.1.100 80 4 "web"
sudo ./iptables-forward.sh --batch add both 5353 127.0.0.1,::1 53 both "dns"
```

成功时标准输出会返回新规则 UUID。

## 存储与持久化

规则元数据默认保存在：

```text
/var/lib/iptables-forward/rules.db
```

格式为一行一条：

```text
uuid=a1b2c3d4|proto=tcp|lport=8080|tip=192.168.1.100|tport=80|ipver=4|desc=web|created=2026-04-17T10:00:00+0800
```

添加/删除规则时会自动调用：

```bash
netfilter-persistent save
```

以便把规则保存到：

```text
/etc/iptables/rules.v4
/etc/iptables/rules.v6
```

## 测试

### 运行全部测试

```bash
tests/run_all.sh
```

### 跳过集成测试

```bash
tests/run_all.sh --skip-integration
```

测试覆盖：

- `tests/test_cli.sh`：入口脚本与安装脚本帮助输出
- `tests/test_install.sh`：安装脚本的 install/uninstall 实际行为与误覆盖保护
- `tests/test_interactive.sh`：交互主菜单的 add/list/delete/save 回归
- `tests/test_common.sh`：输入校验
- `tests/test_storage.sh`：规则存储
- `tests/test_env_check.sh`：环境检查与修复
- `tests/test_rules_unit.sh`：mock iptables 下的增删回滚、双向 FORWARD 规则与并发写保护
- `tests/test_integration.sh`：真实 iptables 生命周期 + `FORWARD=DROP` 下的命名空间端到端 IPv4/IPv6 TCP 转发 + save/reload 持久化回放测试

`tests/test_integration.sh` 的执行策略：

- root 环境下直接执行
- 非 root 但支持 `unshare -Urn` 时，会进入隔离网络命名空间执行
- 两者都不满足时会输出 `SKIP`
- 流量验证会额外创建 client / router / backend 三段临时 veth + netns，并用 Python TCP server 验证 IPv4/IPv6 add / reload / delete 对真实转发流量的影响
- 持久化验证不会直接改写宿主 `/etc/iptables`，而是通过临时 `netfilter-persistent` 包装器把 `save/reload` 落到测试目录中的 `rules.v4` / `rules.v6`

## 手工验收建议

建议按 `plan_iptables_forward.md` 再做以下实机验证：

1. 在干净 Debian 12/13 上首次启动，确认自动安装流程可用。
2. 准备一台实际后端服务主机，验证从第三方主机访问转发端口时流量确实命中目标服务。
3. 重启系统后确认规则仍存在，且菜单中状态仍为健康。
4. 删除规则后再次验证外部访问失败。

## 故障排查

### 1. 提示必须使用 root

脚本必须以 root 执行：

```bash
sudo ./iptables-forward.sh
```

### 2. 自动安装失败

可手动安装依赖后重试：

```bash
sudo apt-get update
sudo apt-get install -y iptables iptables-persistent
```

### 3. 持久化保存失败

确认以下命令可执行：

```bash
command -v netfilter-persistent
sudo netfilter-persistent save
```

### 4. 系统使用 nft 后端

Debian 12/13 默认常见为 `iptables-nft`。本项目不自动切换到 legacy 后端，而是依赖发行版默认配置。

### 5. 其它防火墙工具干扰

若系统启用了 `ufw` 或 `firewalld`，可能覆盖或影响转发规则。脚本会给出黄色警告，但不会自动关闭这些服务。

## 卸载

### 删除 PATH 链接

```bash
sudo ./install.sh --uninstall
```

### 删除脚本管理的规则与状态

```bash
sudo iptables-save | grep -v 'MGMT:' | sudo iptables-restore
sudo ip6tables-save | grep -v 'MGMT:' | sudo ip6tables-restore
sudo netfilter-persistent save
sudo rm -rf /var/lib/iptables-forward
sudo rm -f /etc/sysctl.d/99-iptables-forward.conf
```

### 可选：卸载持久化包

```bash
sudo apt-get remove --purge iptables-persistent
```