diff options
Diffstat (limited to 'docs/WEBSOCKET.md')
| -rw-r--r-- | docs/WEBSOCKET.md | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/docs/WEBSOCKET.md b/docs/WEBSOCKET.md new file mode 100644 index 0000000..1077637 --- /dev/null +++ b/docs/WEBSOCKET.md @@ -0,0 +1,129 @@ +# WebSocket browser terminal · MAX25-Stack + +Remote operator terminal over WebSocket — same M25/1 session model as `max25-terminal`, via loopback proxy. + +## Architecture + +``` +Browser (PHP + JS) + → httpd reverse-proxy WS /max25-websocket/ws (TLS/wss at edge) + → max25-ws-proxy 127.0.0.1:7326/max25 + → max25d M25/1 TCP 127.0.0.1:7325 +``` + +WebSocket is **not** inside max25d (unlike hyBBX in-process WebSocket). The proxy forwards bytes without protocol translation. + +| Component | Path | +|-----------|------| +| Browser UI | `stacks/web/share/reverse-proxy/docroot/max25-websocket/` | +| Session defaults | `/etc/max25/web-terminal.ini` (see `web-terminal.ini.example`) | +| WebSocket proxy | `max25-ws-proxy` — config `web-proxy.ini` | +| Primary CLI client | `max25-terminal` (unchanged) | + +## Ports + +| Port | Service | +|------|---------| +| **7325** | max25d M25/1 TCP | +| **7326** | WebSocket proxy (loopback; expose via httpd only) | + +## Session defaults (`web-terminal.ini`) + +Copy `share/web-terminal.ini.example` to `/etc/max25/web-terminal.ini` or set `MAX25_WEB_TERMINAL_INI`. + +Values mirror max25d `[modem]` and `[devices] default`. Applied **per WebSocket session** on connect: + +| Key | Source | Meaning | +|-----|--------|---------| +| `device` | `[session]` or max25d `[devices] default` | One device per session (`SET DEVICE`) | +| `callerid` | `[session]` or max25d `[modem]` | `SET CALLERID` if different from daemon | +| `callid` | `[session]` or max25d `[modem]` | `SET CALLID` if different | +| `ax25_ui` | `[session]` or max25d `[modem]` | `SET AX25_UI on\|off` | +| `connect_on_start` | `[session]` | `CONNECT` after setup (default yes) | + +Optional `max25d_ini` under `[max25-web-terminal]` merges missing keys from live max25d config. + +## Browser UI + +### Header + +Live fields: **DEVICE**, **CALLERID**, **CALLID**, **ax25-ui**, **connected**. + +**Device dropdown** lists only ids returned by `GET DEVICES` from max25d. Unknown ids are rejected. + +### Menu (F10 equivalent) + +Non-intrusive **Menu ▾** dropdown plus slash commands: + +| Command | Action | +|---------|--------| +| `/callerid [id]` | `SET CALLERID` | +| `/callid [id]` | `SET CALLID` | +| `/status` | `GET STATUS` | +| `/send <text>` | `SEND` | +| `/monitor [on\|off\|toggle]` | `MONITOR` | +| `/connect` / `/disconnect` | `CONNECT` / `DISCONNECT` | +| `/devices` | `GET DEVICES` (device overview) | +| `/device <id>` | `SET DEVICE` (max25d id only) | +| `/ax25_ui on\|off` | `SET AX25_UI` | +| `/help` | Command list | + +Plain text (no `/`) is sent as **`SEND`** — same as `max25-terminal` Enter. + +### Multiple sessions + +Each browser tab / WebSocket connection is an independent M25/1 client. Same `web-terminal.ini` defaults apply; per-session changes via `/` commands or dropdown. + +## Deploy + +```bash +cmake --install $BUILD --prefix $PREFIX +``` + +Installs: + +- `$PREFIX/bin/max25-ws-proxy` +- `$PREFIX/share/max25/web-proxy.ini.example` +- `$PREFIX/share/max25/web-terminal.ini.example` +- `$PREFIX/share/max25/reverse-proxy/` (httpd snippets + `docroot/`) + +### systemd (proxy) + +Example: `share/max25/max25-ws-proxy.service.example` — run proxy on loopback; point httpd `WS` to `127.0.0.1:7326/max25`. + +### httpd + +See `share/max25/reverse-proxy/{nginx,apache2,lighttpd}.conf.example` — proxy `WS /max25-websocket/ws` to the loopback WebSocket service. + +## Local dev + +```bash +./stacks/web/scripts/dev-server.sh +``` + +Open `http://127.0.0.1:8080/` — requires max25d on TCP 7325 and proxy on 7326. + +## max25-terminal device overview + +CLI client F10 menu: + +| # | Action | +|---|--------| +| 8 | List DEVICES (`GET DEVICES` → RX pane) | +| 7 | Change DEVICE (lists devices first, then prompt) | + +Device list at session start after `CONNECT`. + +## Security + +- Proxy binds **loopback** by default — expose only through httpd + TLS. +- Optional `tcp_password` in `web-proxy.ini` `[upstream]` when max25d `[network] tcp_password` is set. +- No browser-side auth beyond site/httpd policy. + +## Related + +| Doc | Topic | +|-----|-------| +| [MAX25-TERMINAL.md](MAX25-TERMINAL.md) | CLI operator client | +| [MAX25-CLIENT.md](MAX25-CLIENT.md) | M25/1 protocol | +| [stacks/web/README.md](../stacks/web/README.md) | Stack build / smoke | |