メインコンテンツまでスキップ

routerctl doctor — ランタイム健全性診断

routerctl doctor は読み取り専用のチェックを一通り実行し、いまこの routerd が 家庭ゲートウェイとして機能しているかを報告します。ホスト状態は変更しません。 運用者・CI・監視エージェント・下流ツール（Prometheus exporter、Web Console、 LLM 補助診断など）から使われることを想定しています。

使い方​

# 全エリア実行（既定）
routerctl doctor

# 単一エリア
routerctl doctor dns

# ホストコマンドを使わない（リソース status のみ）
routerctl doctor --no-host

# 機械可読出力
routerctl doctor -o json
routerctl doctor -o yaml

オプションは diagnose と共通: --config, --state-file, --no-host / --host, -o / --output, --timeout。

エリア​

エリアチェック内容
wanEgressRoutePolicy と HealthCheck のリソース status、IPv4 / IPv6 のデフォルト経路（ip -4/-6 route show default）。
dnsDNSResolver のリソース status、dig @127.0.0.1 での A レコード応答プローブ。
dsliteDSLiteTunnel のリソース status、AFTR FQDN の AAAA プローブ、tunnel device の存在（ip link show）。
dhcpv6-pdDHCPv6PrefixDelegation の status（Bound、委任 prefix）。PD 未取得時は設計上 WARN（壊れている IPv6 を LAN に出さない）。
natNAT44Rule のリソース status、nft list table ip routerd_nat の存在。
firewallFirewallZone / FirewallPolicy の status、nft list table inet routerd_filter の存在と input チェインの policy drop（無いと permissive）。
rollback1 つ以上の世代が保存されていて routerctl rollback --to が使えること。
disk/var/lib/routerd と /run/routerd の容量。90% 以上 or 256 MiB 未満で WARN、98% 以上 or 64 MiB 未満で FAIL。
mgmt管理用 interface の存在（ManagementAccess または FirewallZone role=mgmt から推定）。WebConsole の bind 先（0.0.0.0 / :: は WARN/FAIL）。

各チェックは pass / warn / fail / skip（該当リソース/シグナルが無い）のいずれかを返します。

JSON 出力契約​

routerctl doctor -o json は安定した機械可読インターフェースです。形:

{
  "summary": {
    "overall": "pass",      // "pass" | "warn" | "fail" | "skip"
    "pass": 7,
    "warn": 1,
    "fail": 0,
    "skip": 2
  },
  "checks": [
    {
      "area":   "dns",                          // 上記エリア表のいずれか
      "name":   "DNSResolver/lan-resolver",     // 人間可読の対象名
      "status": "warn",                         // "pass" | "warn" | "fail" | "skip"
      "detail": "phase=Degraded,waiting=...",   // 任意
      "remedy": "wait for or repair dependency wan-pd" // 任意
    }
    // ...
  ]
}

保証内容:

  • summary.overall は checks[].status の最悪値（fail > warn > unknown/skip > pass）。
  • summary.pass/warn/fail/skip は整数件数で、合計は len(checks)。
  • checks[].status は pass, warn, fail, skip のいずれか（他の値は出ない）。
  • checks[].area はエリア表の識別子のいずれか。集合は安定。
  • checks[].name は人間可読。厳密な形にパターンマッチしないこと。
  • detail / remedy は任意のフリーフォーム文字列で、運用者向け。

終了コード​

  • 0 — fail が 1 件も無い（pass / warn / skip は失敗扱いではない）。
  • 非0 — fail が 1 件以上。routerctl doctor || alert のように使えます。

warn は exit code を非0 にしません（例: 起動直後で DHCPv6-PD がまだ Bound でない、など情報的なもの）。 厳しめのゲートが欲しい場合はエリアを絞ってください（routerctl doctor wan は wan の fail でだけ非0）。

安定性​

JSON の形、エリア識別子、status の enum は v1alpha1 の運用者向け契約です。今後のバージョンで エリアやオプショナルフィールドが追加されることはありますが、既存エリア名や status 値は v1alpha1 の minor 間で改名・再用途化しません。

関連項目​