rpki/docs/rtr-admin-api.md

RTR Admin API

本文档描述 RTR server 当前提供的 HTTP 管理接口。

启用方式

Admin API 默认关闭。设置 RPKI_RTR_ADMIN_ADDR 后启用：

RPKI_RTR_ADMIN_ADDR=127.0.0.1:8323
RPKI_RTR_ADMIN_TOKEN=change-me

如果在 Docker 中需要从宿主机访问，容器内建议监听：

RPKI_RTR_ADMIN_ADDR=0.0.0.0:8323
RPKI_RTR_ADMIN_TOKEN=change-me

并在 compose 中映射端口：

ports:
  - "8323:8323"

安全规则：

• RPKI_RTR_ADMIN_ADDR 为空时，不启动 Admin API。
• 非 loopback 地址，例如 0.0.0.0:8323，必须配置 RPKI_RTR_ADMIN_TOKEN，否则 admin server 会拒绝启动。
• 设置 token 后，请求必须带 Authorization: Bearer <token>。

通用 Headers

Authorization: Bearer change-me
Content-Type: application/json

GET 请求不需要 Content-Type。

GET /admin/rtr/health

用于检查 Admin API 是否可达，以及当前启用了哪些管理能力。

curl http://127.0.0.1:8323/admin/rtr/health \
  -H "Authorization: Bearer change-me"

响应示例：

{
  "status": "ok",
  "config_api": true,
  "source_reload_api": true,
  "slurm_api": true,
  "logs_api": true
}

GET /admin/rtr/logs/tail

实时读取 RTR 服务日志，效果类似 tail -f。默认读取 stdout 日志，先返回最近 200 行，然后持续输出新增内容。

curl -N "http://127.0.0.1:8323/admin/rtr/logs/tail?stream=stdout&lines=200&follow=true" \
  -H "Authorization: Bearer change-me"

Query 参数：

参数	默认值	说明
stream	stdout	可选 stdout 或 stderr。
lines	200	首次返回的历史行数，范围会限制在 1..=5000。
follow	true	true 时保持连接并持续输出新增日志；false 时只返回当前 tail 内容。

日志文件路径按容器 entrypoint 的规则解析：

• 目录：RPKI_RTR_LOG_DIR，默认 /app/logs。
• 文件名前缀：RPKI_RTR_LOG_NAME，未设置时使用 HOSTNAME，再未设置时为 rpki-rtr。
• stdout 文件：<name>.stdout.log。
• stderr 文件：<name>.stderr.log。

GET /admin/rtr/config

查询当前运行中的 runtime 配置。

curl http://127.0.0.1:8323/admin/rtr/config \
  -H "Authorization: Bearer change-me"

响应示例：

{
  "status": "ok",
  "config": {
    "max_delta": 10,
    "prune_delta_by_snapshot_size": true,
    "source_refresh_interval_seconds": 300,
    "runtime_report_interval_seconds": 300,
    "report_history_limit": 10,
    "strict_ccr_validation": false,
    "timezone": "Asia/Shanghai",
    "timing": {
      "refresh": 3600,
      "retry": 600,
      "expire": 7200
    }
  }
}

POST /admin/rtr/config

运行中动态修改 RTR server 的部分 runtime 配置。请求体是 JSON object，支持部分更新，只需要传要修改的字段。

字段	类型	说明
max_delta	integer	每个 RTR 版本最多保留的 delta 条数，必须 >= 1。
prune_delta_by_snapshot_size	boolean	是否按 snapshot wire size 裁剪 delta window。
source_refresh_interval_seconds	integer	CCR/SLURM source refresh 间隔，单位秒，必须 >= 1。
runtime_report_interval_seconds	integer	rtr-runtime-*.json 周期写入间隔，单位秒，必须 >= 1。
report_history_limit	integer	每类 report 文件滚动保留数量，必须 >= 1。
strict_ccr_validation	boolean	是否严格校验 CCR 中的非法 VRP/VAP，影响下一次 source refresh。
timezone	string	IANA 时区名，例如 Asia/Shanghai、UTC、Europe/London。
timing.refresh	integer	RTR EndOfData refresh，单位秒。
timing.retry	integer	RTR EndOfData retry，单位秒。
timing.expire	integer	RTR EndOfData expire，必须大于 refresh 和 retry。

示例：

curl -X POST http://127.0.0.1:8323/admin/rtr/config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer change-me" \
  -d '{"max_delta": 6}'

成功响应：

{
  "status": "ok",
  "config": {
    "max_delta": 6,
    "prune_delta_by_snapshot_size": true,
    "source_refresh_interval_seconds": 300,
    "runtime_report_interval_seconds": 300,
    "report_history_limit": 10,
    "strict_ccr_validation": false,
    "timezone": "Asia/Shanghai",
    "timing": {
      "refresh": 3600,
      "retry": 600,
      "expire": 7200
    }
  }
}

GET /admin/rtr/slurm/files

列出 RPKI_RTR_SLURM_DIR 下的 SLURM 文件。只返回合法的 *.slurm 和 *.slurm.disabled 文件，不返回 .backup/。

curl http://127.0.0.1:8323/admin/rtr/slurm/files \
  -H "Authorization: Bearer change-me"

响应示例：

{
  "status": "ok",
  "files": [
    {
      "name": "local-policy.slurm",
      "path": "/app/slurm/local-policy.slurm",
      "enabled": true,
      "size_bytes": 168,
      "modified_unix_seconds": 1782100000
    },
    {
      "name": "old-policy.slurm.disabled",
      "path": "/app/slurm/old-policy.slurm.disabled",
      "enabled": false,
      "size_bytes": 168,
      "modified_unix_seconds": 1782100100
    }
  ]
}

GET /admin/rtr/slurm/files/{name}

读取单个 SLURM 文件，前端编辑页面可以直接使用这个接口加载内容。

curl http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm \
  -H "Authorization: Bearer change-me"

响应示例：

{
  "status": "ok",
  "file": {
    "name": "local-policy.slurm",
    "path": "/app/slurm/local-policy.slurm",
    "enabled": true,
    "size_bytes": 168,
    "modified_unix_seconds": 1782100000,
    "content": "{ \"slurmVersion\": 1, \"validationOutputFilters\": { \"prefixFilters\": [], \"bgpsecFilters\": [] }, \"locallyAddedAssertions\": { \"prefixAssertions\": [], \"bgpsecAssertions\": [] } }"
  }
}

POST /admin/rtr/slurm/files

新增或覆盖一个 SLURM 文件。文件名放在请求体中。

{
  "name": "local-policy.slurm",
  "content": "{ \"slurmVersion\": 1, \"validationOutputFilters\": { \"prefixFilters\": [], \"bgpsecFilters\": [] }, \"locallyAddedAssertions\": { \"prefixAssertions\": [], \"bgpsecAssertions\": [] } }",
  "reload": true
}

PUT /admin/rtr/slurm/files/{name}

新增或覆盖指定 SLURM 文件。

curl -X PUT http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer change-me" \
  -d '{
    "content": "{ \"slurmVersion\": 1, \"validationOutputFilters\": { \"prefixFilters\": [], \"bgpsecFilters\": [] }, \"locallyAddedAssertions\": { \"prefixAssertions\": [], \"bgpsecAssertions\": [] } }",
    "reload": true
  }'

DELETE /admin/rtr/slurm/files/{name}

删除指定 SLURM 文件。删除前会先备份。

curl -X DELETE "http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm?reload=true" \
  -H "Authorization: Bearer change-me"

POST /admin/rtr/slurm/files/{name}/disable

将启用文件改名为失效文件：

local-policy.slurm -> local-policy.slurm.disabled

curl -X POST "http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm/disable?reload=true" \
  -H "Authorization: Bearer change-me"

POST /admin/rtr/slurm/files/{name}/enable

将失效文件改名为启用文件：

local-policy.slurm.disabled -> local-policy.slurm

curl -X POST "http://127.0.0.1:8323/admin/rtr/slurm/files/local-policy.slurm.disabled/enable?reload=true" \
  -H "Authorization: Bearer change-me"

POST /admin/rtr/slurm/reload

不修改文件，只立即触发一次 CCR/SLURM source reload。

curl -X POST http://127.0.0.1:8323/admin/rtr/slurm/reload \
  -H "Authorization: Bearer change-me"

SLURM 文件规则

• *.slurm：启用，会被 source refresh 加载。
• *.slurm.disabled：失效，不会被加载。
• .backup/：接口自动生成的备份目录。
• 文件名只能是 basename，不能包含 /、\ 或 ..。
• 文件名只能包含 ASCII 字母、数字、.、_、-。
• 写入内容必须是合法 JSON，并且能被解析为合法 SLURM 文件。
• 单个请求体默认限制为 5 MiB。
• 覆盖、删除前会写入 .backup/ 备份。

错误响应

HTTP 状态码	含义
400 Bad Request	JSON 非法、配置值非法、SLURM 文件名非法、目标文件不存在、reload 失败等。
401 Unauthorized	配置了 token，但请求缺少或使用了错误的 Authorization。
404 Not Found	路径或方法不支持。
413 Payload Too Large	请求体超过限制。