# RTR Client 使用说明

本文说明仓库内三类 RTR Client 的用途、启动方式和验证命令：

- `deploy/client`: 本仓库自带的 `rtr_debug_client`，适合做 RTR 协议调试、连通性检查和单次查询。
- `deploy/frr`: FRR 作为黑盒 RTR Client，适合验证真实路由软件是否能消费 server 下发的 VRP。
- `deploy/bird`: BIRD 作为黑盒 RTR Client，适合验证 TCP 或 SSH transport 下的 RPKI/ROA/ASPA 数据导入。

以下命令默认从仓库根目录执行。

## 目录

- [前置条件](#前置条件)
- [rtr_debug_client](#rtr_debug_client)
  - [TCP](#tcp)
  - [TLS/mTLS](#tlsmtls)
  - [SSH](#ssh)
  - [多客户端压测](#多客户端压测)
- [FRR Client](#frr-client)
- [BIRD Client](#bird-client)
  - [TCP](#tcp-1)
  - [SSH](#ssh-1)
- [如何判断 Client 正常](#如何判断-client-正常)

## 前置条件

先启动 RTR Server。TCP 模式是最常用的本地验证方式：

```bash
./deploy/server/build-run.sh up --mode tcp
```

如果要测试 TLS 或 SSH，需要先启动对应 server 模式，并准备匹配的证书或 SSH key：

```bash
./deploy/server/build-run.sh up --mode tls
./deploy/server/build-run.sh up --mode ssh
```

Client 连接地址不要求固定在某个 Docker 网络里。`deploy/client` 的 TCP/TLS/SSH 模式分别通过 `RPKI_RTR_TCP_SERVER_ADDR`、`RPKI_RTR_TLS_SERVER_ADDR`、`RPKI_RTR_SSH_SERVER_ADDR` 指定 server 地址。`deploy/bird` 通过 `RPKI_BIRD_RPKI_HOST`/`RPKI_BIRD_RPKI_PORT` 指定 TCP server 地址，通过 `RPKI_BIRD_SSH_RPKI_HOST`/`RPKI_RTR_SSH_PORT` 指定 SSH server 地址。示例 compose 里的默认值只是为了和本仓库 server compose 直接联调。

`deploy/frr` 示例默认连接 `127.0.0.1:323`，可以通过 `RPKI_FRR_RPKI_HOST`/`RPKI_FRR_RPKI_PORT` 覆盖。

## rtr_debug_client

`rtr_debug_client` 是本仓库提供的调试客户端。它会发起 RTR Reset Query 或 Serial Query，并打印 server 返回的 PDU 摘要。Docker 配置默认执行：

```text
<server_addr> <protocol_version> reset --keep-after-error --summary-only
```

### TCP

```bash
./deploy/client/build-run.sh up --mode tcp
./deploy/client/build-run.sh logs --mode tcp
./deploy/client/build-run.sh down --mode tcp
```

默认连接 `rpki-rtr:323`，协议版本默认是 `2`。可以通过 `deploy/client/.env` 或环境变量覆盖：

```bash
RPKI_RTR_TCP_SERVER_ADDR=10.0.0.12:323 \
RPKI_RTR_PROTOCOL_VERSION=2 \
./deploy/client/build-run.sh up --mode tcp
```

### TLS/mTLS

```bash
./deploy/client/build-run.sh up --mode tls
./deploy/client/build-run.sh logs --mode tls
./deploy/client/build-run.sh down --mode tls
```

TLS 模式默认读取 `certs/tls` 下的示例证书，并使用 `localhost` 作为 server name。常用变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `RPKI_RTR_TLS_SERVER_ADDR` | `rpki-rtr:324` | TLS RTR server 地址 |
| `RPKI_RTR_TLS_SERVER_NAME` | `localhost` | 必须匹配 server 证书 SAN dNSName |
| `RPKI_RTR_TLS_CA_CERT_PATH` | `/app/certs/client-ca.crt` | 容器内 CA 证书路径 |
| `RPKI_RTR_TLS_CLIENT_CERT_PATH` | `/app/certs/client-good.crt` | 容器内 client 证书路径 |
| `RPKI_RTR_TLS_CLIENT_KEY_PATH` | `/app/certs/client-good.key` | 容器内 client 私钥路径 |
| `RPKI_RTR_TLS_CERTS_HOST_DIR` | `../../certs/tls` | 宿主机 TLS 证书目录 |

### SSH

```bash
./deploy/client/build-run.sh up --mode ssh
./deploy/client/build-run.sh logs --mode ssh
./deploy/client/build-run.sh down --mode ssh
```

SSH 模式默认连接 `rpki-rtr-ssh:22`，使用 key 认证，并校验 server public key。常用变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `RPKI_RTR_SSH_SERVER_ADDR` | `rpki-rtr:22` | SSH RTR server 地址 |
| `RPKI_RTR_SSH_USERNAME` | `rpki-rtr` | SSH 用户名 |
| `RPKI_RTR_CLIENT_KEYS_VOLUME` | `../../certs/ssh:/app/certs:ro` | 宿主机 SSH key 目录挂载 |
| `RPKI_RTR_CLIENT_KEY_PATH` | `/app/certs/rtr-client.key` | 容器内 client 私钥 |
| `RPKI_RTR_SSH_SERVER_PUBKEY_PATH` | `/app/certs/ssh_host_rsa_key.pub` | 容器内 server public key |

### 多客户端压测

`--clients multi` 会启动 5 个 TCP debug client，用于观察并发连接、client report 和 server 连接统计。

```bash
./deploy/client/build-run.sh up --mode tcp --clients multi
./deploy/client/build-run.sh logs --mode tcp --clients multi
./deploy/client/build-run.sh down --mode tcp --clients multi
```

## FRR Client

FRR 示例用于验证标准路由软件能否通过 RTR over TCP 从 server 获取前缀验证数据。

启动：

```bash
docker compose --env-file deploy/frr/.env -f deploy/frr/docker-compose.yml up -d
```

默认连接 `127.0.0.1:323`。可以通过环境变量覆盖：

```bash
RPKI_FRR_RPKI_HOST=10.0.0.12 \
RPKI_FRR_RPKI_PORT=323 \
docker compose --env-file deploy/frr/.env -f deploy/frr/docker-compose.yml up -d
```

验证连接和数据：

```bash
docker exec -it frr-rpki-client vtysh -c "show rpki configuration"
docker exec -it frr-rpki-client vtysh -c "show rpki cache-connection"
docker exec -it frr-rpki-client vtysh -c "show rpki prefix-table"
```

停止：

```bash
docker compose --env-file deploy/frr/.env -f deploy/frr/docker-compose.yml down
```

FRR 容器启动时会读取 `deploy/frr/frr.conf.template`，并生成 `/etc/frr/frr.conf`。模板中的 RTR cache 配置为：

```text
rpki cache tcp ${RPKI_FRR_RPKI_HOST} ${RPKI_FRR_RPKI_PORT} preference ${RPKI_FRR_RPKI_PREFERENCE}
```

如果需要调整 polling、timeout、BGP router-id 等其他 FRR 配置，可以修改 `deploy/frr/frr.conf.template`，或在 compose 中挂载自己的模板和 entrypoint。

## BIRD Client

BIRD 示例用于验证 BIRD 3.x 对 RTR v2、ROA 和 ASPA 的导入情况。容器启动后会周期性输出 RPKI 协议状态和表项摘要。

### TCP

启动：

```bash
docker compose --env-file deploy/bird/.env -f deploy/bird/docker-compose.yml up -d --build
```

查看日志：

```bash
docker logs -f bird-rpki-client
```

停止：

```bash
docker compose --env-file deploy/bird/.env -f deploy/bird/docker-compose.yml down
```

默认连接 `rpki-rtr:323`。可以通过环境变量覆盖：

```bash
RPKI_BIRD_RPKI_HOST=10.0.0.12 \
RPKI_BIRD_RPKI_PORT=323 \
docker compose --env-file deploy/bird/.env -f deploy/bird/docker-compose.yml up -d --build
```

### SSH

先启动 server SSH 模式：

```bash
./deploy/server/build-run.sh up --mode ssh
```

再启动 BIRD SSH client：

```bash
docker compose --env-file deploy/bird/.env \
  -f deploy/bird/docker-compose.yml \
  -f deploy/bird/docker-compose.ssh.yml \
  up -d --build
```

查看日志：

```bash
docker logs -f bird-rpki-client
```

SSH 模式默认读取 `certs/ssh` 目录下的 key，并使用 `bird.conf.ssh.template` 生成运行时配置。关键默认值：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `RPKI_BIRD_SSH_RPKI_HOST` | `rpki-rtr` | SSH RTR server 主机名 |
| `RPKI_RTR_SSH_PORT` | `22` | SSH RTR server 端口 |
| `RPKI_BIRD_SSH_CERTS_HOST_DIR` | `../../certs/ssh` | 宿主机 SSH 证书和 key 目录 |

## 如何判断 Client 正常

- `rtr_debug_client`: 日志中能看到 Reset Query 成功、EndOfData 和 payload 统计。
- FRR: `show rpki cache-connection` 显示已连接，`show rpki prefix-table` 有 VRP 条目。
- BIRD: 日志中 RPKI protocol 状态为 `up`，ROA/ASPA 表项摘要不为空。

如果 client 无法连接，优先检查：

- server 是否按对应 transport 启动。
- client 配置的 server 地址是否从当前容器或主机可达。
- TLS 的 server name 是否匹配证书 SAN。
- SSH 的用户名、client key 和 server public key 是否匹配。
- `RPKI_RTR_PROTOCOL_VERSION` 或 BIRD 配置中的 `min version`/`max version` 是否和 server 能力一致。