@iasiv5/dsh-obmc-web 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iasiv5
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# @iasiv5/dsh-obmc-web
+
+在 DSH GUI 里使用 **BMC Web UI**（OpenBMC / bmcweb，AST2700 EVB 实测）。
+host 半身在 DSH web 服务器的 GUI origin 上注册一组同源代理路由，经
+`obmc-web-relay.service`（SSH 本地转发，仅绑 `127.0.0.1`，端口默认
+18443、被占自动顺延）抵达 BMC；client 半身仿照 dsh-surf，在「设置」
+菜单位注册一个 **BMC 控制台** 启动面板：显示隧道状态芯片与当前 BMC
+地址，一键在顶层标签页打开控制台，并支持 BMC IP 变化后的 SSH 自动
+探测与隧道重定向。
+
+> 控制台不放进侧边栏 iframe：公网入口的 dsh-auth-caddy 给所有响应盖了
+> `X-Frame-Options: DENY`，因此面板用 `window.open` 做**顶层导航**（XFO
+> 不约束顶层页面）。登录仍在 BMC 自己的页面里完成，本插件不经手凭据。
+
+```
+浏览器 ── GUI origin (/bmc, /js, /css, /redfish, /login, /logout, /kvm·/console WS)
+   └─ dsh web server (127.0.0.1:3080) ── @iasiv5/dsh-obmc-web host 路由
+        │                                （剥 XFO/HSTS/WWW-Authenticate/frame-ancestors）
+        └─ obmc-web-relay.service (ssh -N -L 127.0.0.1:<relay端口> → $BMC_TARGET)
+             └─ BMC (bmcweb, hash 路由 SPA)
+```
+
+## 面板一览
+
+「设置 → BMC 控制台」从上到下：
+
+- **状态芯片**：整个面板共享一次轮询，每 15s 打一次 `/bmc-status?probe=1`
+  （探测轮进行中改为 2s），实测隧道后显示：隧道在线 / 正在 SSH 探测 /
+  DSH 会话已过期 / 可达但响应异常 / BMC 不可达；保存配置、探测 IP、
+  安装 relay 这类影响隧道的动作完成后会**立即重新探测**，芯片在 1~2s 内
+  跟上动作结果，不必等下一个轮询周期；
+- **当前 BMC IP** 与最近一次探测结果（找到的地址、时间、是否已切换并验证）；
+- **部署配置表单**：五个等宽输入框（SSH 跳板机、SSH 端口、BMC 地址、
+  网段、relay 本地端口），加 保存配置 / 探测 BMC IP / 安装并启动 relay
+  服务 三个动作与 relay 运行状态一行；
+- **打开 BMC Web 控制台**：顶层标签页打开；尚未配置 BMC 地址时置灰。
+
+## 为什么是这些路由
+
+bmcweb 的 SPA 以根绝对路径引用资源与 API（`/js/…`、`/css/…`、`/redfish/…`、
+`/login`、`/logout`；KVM/串口走 `/kvm`、`/console` WebSocket），且路由为
+hash 模式，因此挂在 `/bmc` 前缀下不会与 SPA 内部导航冲突。DSH web 服务器
+按「精确表优先、前缀最长者胜」分发，GUI 自身的路由永远优先；重复注册只
+跳过、不会让插件失败。
+
+## 安装
+
+```bash
+# 任意目录执行即可（dsh plugin 把参数转发给 profile 目录里的 pnpm）
+dsh plugin --profile web add @iasiv5/dsh-obmc-web
+```
+
+然后重启 dsh web。「设置」菜单里会出现 **BMC 控制台** 面板。
+
+本地开发可用 link 方式直装源码：
+
+```bash
+dsh plugin --profile web add link:/path/to/dsh-obmc-web
+```
+
+## 配置
+
+**推荐方式：全部在网页里完成。** 首次安装后打开「设置 → BMC 控制台」，
+展开「部署配置」表单：
+
+1. 填 **SSH 跳板机**（`user@host`；与 BMC 链路网段相通、已配好对本机
+   BatchMode 免密登录的机器）与 SSH 端口；**BMC 地址可以留空**；
+   链路网段、relay 本地端口（默认 18443）均可留空用默认；
+2. 点 **「探测 BMC IP」**——先保存表单，再 SSH 登录跳板机自动发现
+   bmcweb 地址并回填；BMC IP 被 DHCP 改变后，也用同一个按钮（此时显示
+   「重新探测 IP」）重新找回并切换隧道；同一时刻只有一轮探测在跑；
+3. 点 **「安装并启动 relay 服务」**——插件按当前配置生成
+   `~/.config/systemd/user/obmc-web-relay.service`，daemon-reload 并启动，
+   隧道验证通过后报告；若配置的 relay 端口被其他程序占用，会自动顺延到
+   空闲端口并提示。之后升级配置也用同一个按钮。
+
+**保存配置**单独说明：表单立即写入 env 文件并生效；若 BMC 地址或 relay
+端口发生变化且 relay 正在运行，会自动重启 relay 并验证隧道，结果随保存
+响应返回（首次保存、只改跳板机等不影响隧道的编辑不会重启 relay）。
+
+**手动方式（高级）**：配置实际存储在插件与 relay unit 共用的
+`KEY=VALUE` 文件 `~/.config/systemd/user/obmc-relay.env`（可用环境变量
+`OBMC_WEB_ENV` 改位置）。首次启动若文件不存在，插件自动生成一份全注释
+的模板（含说明与文档示例地址）；手改后重启 dsh web 生效。模板见
+`deploy/relay.env.example`；手工安装用的 unit 示例在
+`deploy/obmc-web-relay.service.example`（一般用不着——面板按钮会生成）：
+
+| 键 | 必填 | 说明 |
+|---|---|---|
+| `BMC_TARGET` | 是* | 当前 BMC 地址 `ip:port`，relay unit 的 ExecStart 消费；自动探测会原地改写此行（保留其他键）。表单保存与探测都会补全成 `ip:443`——**手写时请务必带端口**，`ssh -L` 的转发目标需要 `host:port` 形式。*可用「探测 BMC IP」自动发现 |
+| `OBMC_SSH_TARGET` | 探测必填 | 跳板机 SSH 目标 `user@host`（BatchMode 免密）；不配则探测关闭，代理不受影响 |
+| `OBMC_SSH_PORT` | 否 | 跳板机 SSH 端口，默认 22 |
+| `OBMC_SUBNET` | 否 | 探测网段 `a.b.c`；缺省先取 `BMC_TARGET` IP 的 /24，连 BMC IP 都没有时，探测会在跳板机上自动枚举直连 IPv4 网段逐个扫 |
+| `OBMC_RELAY_PORT` | 否 | relay 本地监听端口，默认 18443，需与 relay unit 的 `-L` 参数一致（面板的安装按钮会保持两者同步） |
+
+代码本身不含任何站点相关默认值——你的网络拓扑只活在这份配置里（表单
+和 env 文件是同一份数据的两个入口）。真正必须由人类提供的只有跳板机
+这一项；DSH 自身的 3080、公网反代端口等属于 DSH/网关层，与本插件无关，
+无需在此配置。
+
+## BMC IP 自动探测
+
+BMC 地址常由跳板侧 DHCP 动态分配，可能变化。当隧道目标失联（代理上游
+报错，或 `/bmc-status?probe=1` 实测失败）时，插件自动 SSH 到跳板机定位
+bmcweb 实际地址：先查 dnsmasq 租约表 + ARP 表（单纯换址时亚秒级返回），
+不通再对候选网段做 TCP-443 扫描；候选地址以 `/redfish/v1` 应答做指纹
+校验（200 或 401 都算 bmcweb 在场）。探测网段的确定顺序：配置的
+`OBMC_SUBNET` → `BMC_TARGET` IP 的 /24 → 跳板机自身枚举的直连 IPv4
+网段。找到后写回 env 文件的 `BMC_TARGET` 行、经 user manager 重启
+relay，并通过隧道验证后才报告成功；若 relay unit 尚未安装（首次
+bootstrap），地址仍会写入配置并提示下一步去点「安装并启动 relay
+服务」。SSH 层失败（地址/端口/免密）会透出真实原因，不会伪装成
+「未发现 bmcweb」。触发方式：
+
+- 手动：部署配置里的「探测 BMC IP / 重新探测 IP」按钮（`POST
+  /bmc-status`），不设冷却，但同一时刻仅一轮；
+- 自动：代理上游报错时触发，自带 60s 冷却。
+
+## 安全说明
+
+- 上游仅 `127.0.0.1`（SSH 隧道，端口默认 18443），不新增任何公网监听。
+- 剥掉的响应头：`X-Frame-Options`、`Strict-Transport-Security`、
+  `WWW-Authenticate`（防止 bmcweb 的 401 Basic challenge 弹浏览器原生
+  凭据框；BMC SPA 走 POST /login JSON + cookie），CSP 仅移除
+  `frame-ancestors` 指令；其余（含 Cookie）原样透传。
+- 不在任何地方存储 BMC 凭据；登录在 BMC 自身页面完成。
+- 信任围栏仿照 dsh-better-sidebar 的 trust-fence（Host 必须是 loopback
+  或部署信任的 authority、`Sec-Fetch-Site` 不得为 cross-site、Origin 若有
+  必须与 Host 同 hostname）——这是 DNS-rebinding 防御，不是认证；真正的
+  访问控制由部署在 GUI 前面的既有网关承担。
+- 已知取舍：代理内容与 GUI 同源（bmcweb 需要 Cookie 登录，无法用
+  opaque-origin sandbox）。信任级别等同于在浏览器同站打开 BMC 页面。
+
+## License
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+# dsh-obmc-web bundle patch: mounts the host half (webServer routes) into
+# the profile's plugin tree.
+- insert: [{ id: obmc-web, name: '@iasiv5/dsh-obmc-web' }]

package/deploy/obmc-web-relay.service.example

@@ -0,0 +1,22 @@
+[Unit]
+Description=SSH local-forward relay to the BMC Web UI via jump host
+# Local port 18443 -> (over ssh to the jump host) -> BMC $BMC_TARGET
+# Binds loopback only — the DSH GUI's same-origin proxy is the only client.
+# BMC_TARGET can be overridden by relay.env (rewritten in place by the
+# @iasiv5/dsh-obmc-web plugin's SSH discovery when the DHCP-assigned BMC
+# address changes). Install as ~/.config/systemd/user/obmc-web-relay.service
+# — or just click「安装并启动 relay 服务」in the plugin's Settings panel,
+# which generates this unit from the current configuration.
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Environment=BMC_TARGET=192.0.2.10:443
+EnvironmentFile=-%h/.config/systemd/user/obmc-relay.env
+ExecStart=/usr/bin/ssh -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -o BatchMode=yes -N -L 127.0.0.1:18443:${BMC_TARGET} -p 22 user@jump.example.net
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target

package/deploy/relay.env.example

@@ -0,0 +1,38 @@
+# @iasiv5/dsh-obmc-web / obmc-web-relay shared configuration.
+#
+# PREFERRED: you normally do NOT edit this file by hand — open the DSH
+# Settings → BMC 控制台 panel and fill in the 部署配置 form; it writes this
+# file (validated, comments preserved) and can install/restart the relay
+# unit for you. On first plugin start this file is auto-generated as a
+# fully commented template.
+#
+# Location: ~/.config/systemd/user/obmc-relay.env (the plugin side can be
+# moved anywhere with the OBMC_WEB_ENV env var). KEY=VALUE lines; keys the
+# plugin or the relay unit do not know are ignored.
+#
+# The plugin reads this file at dsh web startup; hand edits require a
+# restart (saving from the Settings form applies immediately).
+
+# Current BMC address (ip:port). Consumed by the relay unit's ExecStart and
+# rewritten in place by the plugin's SSH discovery. 192.0.2.x are
+# documentation addresses — replace with your BMC's.
+BMC_TARGET=192.0.2.10:443
+
+# ---- Optional: SSH auto-discovery ---------------------------------------
+# With these set, when the tunnel stops answering the plugin SSHes to the
+# jump host (BatchMode key expected to be already authorized) and re-locates
+# the bmcweb speaker on the link subnet: dnsmasq leases + ARP table first,
+# full TCP-443 sweep as fallback. Without them the proxy still works — it
+# just cannot retarget itself.
+OBMC_SSH_TARGET=user@jump.example.net
+OBMC_SSH_PORT=22
+# Link subnet to sweep; defaults to the BMC target IP's /24, and when even
+# BMC_TARGET is absent the discovery enumerates the jump host's
+# directly-connected IPv4 /24s by itself.
+OBMC_SUBNET=192.0.2
+
+# ---- Optional: relay local port -----------------------------------------
+# Local loopback port the relay forwards; must match the relay unit's -L
+# argument (the Settings form's install button keeps them in sync).
+# Default: 18443.
+#OBMC_RELAY_PORT=18443