rpki/README.client.md

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
  • TCP
  • TLS/mTLS
  • SSH
  • 多客户端压测
• FRR Client
• BIRD Client
  • TCP
  • SSH
• 如何判断 Client 正常

前置条件

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

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

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

./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 配置默认执行：

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

TCP

./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 或环境变量覆盖：

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

./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

./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 连接统计。

./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 获取前缀验证数据。

启动：

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

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

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

验证连接和数据：

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"

停止：

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 配置为：

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

启动：

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

查看日志：

docker logs -f bird-rpki-client

停止：

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

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

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 模式：

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

再启动 BIRD SSH client：

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

查看日志：

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 能力一致。