# 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)
  - [Docker attach 交互命令](#docker-attach-交互命令)
  - [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
```

TLS/SSH 所需的本地开发证书和密钥可以通过脚本生成：

```bash
bash scripts/generate-certs.sh
```

已有 `certs/` 时使用 `--force` 覆盖。脚本生成的 `certs/tls` 和 `certs/ssh` 文件名与本仓库 compose 默认配置一致。

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 --summary-only
```

Docker 镜像的 `entrypoint.sh` 会把 stdout/stderr 重定向到 `logs/client/*.stdout.log` 和 `logs/client/*.stderr.log`。因此 `docker attach` 后可以输入交互命令，但命令响应和收到的 PDU 仍然主要从日志文件查看：

```bash
tail -f logs/client/*.stdout.log
tail -f logs/client/*.stderr.log
```

### Docker attach 交互命令

如果 debug client 已经通过 compose 启动，可以 attach 到容器后输入命令：

```bash
docker attach --sig-proxy=false <rtr-debug-client-container>
```

脱离 attach 会话时使用 `Ctrl-P` 后接 `Ctrl-Q`，避免 `Ctrl-C` 直接停止客户端进程。

可用交互命令如下：

| 命令 | 作用 |
| --- | --- |
| `help` | 显示可用命令列表。 |
| `state` | 打印当前客户端状态，包括 `session_id`、`serial`、`refresh/retry/expire`、输出模式、自动轮询状态等。 |
| `version` | 查看当前 RTR 协议版本。 |
| `version <n>` | 修改后续查询使用的 RTR 协议版本，例如 `version 2`。 |
| `reset` | 发送 Reset Query，通常用于让 server 重新下发完整数据集。 |
| `serial` | 使用当前已记录的 `session_id` 和 `serial` 发送 Serial Query。需要客户端已经从 EndOfData 中拿到状态。 |
| `serial <session_id> <serial>` | 显式指定参数发送 Serial Query，例如 `serial 31320 156`。 |
| `timeout` | 查看当前读取 PDU 的超时时间。 |
| `timeout <secs>` | 修改读取 PDU 的超时时间。超时只打印提示，连接保持打开。 |
| `poll` | 查看当前自动轮询间隔、来源、refresh hint、错误状态和暂停状态。 |
| `poll <secs>` | 修改自动轮询间隔。 |
| `poll pause` | 暂停自动轮询。 |
| `poll resume` | 恢复自动轮询。 |
| `output` | 查看当前输出模式，以及 summary 模式下跳过的 payload PDU 数量。 |
| `output verbose` | 打印所有收到的 PDU，包括 IPv4 Prefix、IPv6 Prefix、Router Key、ASPA 等 payload PDU。 |
| `output summary` | 只打印摘要，跳过 payload PDU 详情。compose 默认使用该模式。 |
| `quit` / `exit` | 退出客户端进程。 |

常用调试流程：

```text
output verbose
reset
state
serial
```

### 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 目录，复用 `rtr-client.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 能力一致。