Web Terminal & Host Control
Relevant source files
The following files were used as context for generating this wiki page:
The Web Terminal and Host Control module provides a browser-based PTY shell, file management, and real-time system monitoring for the HX-ProxyGroup server. This system allows administrators to execute shell commands, manage files, and observe host metrics directly through the management panel.
The feature operates as a local PTY shell on the server rather than an SSH client. In production environments, a dedicated systemd helper creates a root PTY, granting authorized administrators root-equivalent command execution. The terminal is disabled by default and requires multi-factor authentication (MFA) to function.
Sources: SECURITY.md:43-52, web/src/pages/terminal-page.tsx:288-295
System Architecture
The architecture consists of the React-based frontend, a Go control plane, and an optional privileged terminal helper. The frontend communicates with the control plane via WebSockets for the terminal session and REST/SSE for file management and metrics.
Interaction Flow
The following diagram illustrates the connection process and data flow between the browser, the control plane, and the PTY:
The terminal service uses a Unix socket to communicate with the privileged helper in production to validate the control-plane peer via SO_PEERCRED.
Sources: SECURITY.md:73-81, web/src/pages/terminal-page.tsx:180-220, cmd/hx-proxygroupd/main.go:34-42
Terminal Session Management
The system manages terminal sessions using WebSockets for bidirectional communication.
Security Constraints
- Authentication: Requires a configured, authenticated administrator session.
- MFA: Mandatory TOTP second factor with recent step-up verification.
- Session Limits: Maximum of two concurrent sessions per server; two-hour absolute session limit.
- Auditing: The system records session open/close audit records, though it excludes command contents or secrets from these logs.
- Isolation: The PTY environment minimizes exported variables and excludes control-plane environment variables.
Sources: SECURITY.md:55-65, web/src/pages/terminal-page.tsx:75-105
Terminal UI Features
The frontend uses xterm.js to render the terminal. Key features include:
- Automatic Reconnection: Implements exponential backoff with jitter if the network connection drops.
- CWD Tracking: Scans for OSC 7 escape sequences to synchronize the current working directory between the shell and the file manager panel.
- Input Batching: Batches printable input for approximately 12ms to reduce latency on weak networks, while control characters flush immediately.
Sources: web/src/pages/terminal-page.tsx:23-28, web/src/pages/terminal-page.tsx:150-170, SECURITY.md:68-71
File Management
The File Manager provides REST endpoints for interacting with the host filesystem. In production, these operations are executed by the privileged helper to allow the panel to view and modify files outside the control plane's sandbox (e.g., /root or /home).
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/v1/terminal/files | GET | Lists directory entries or stats a specific file path. |
/api/v1/terminal/files | POST | Uploads a file via multipart form to the specified path. |
/api/v1/terminal/files/mkdir | POST | Creates a new directory. |
/api/v1/terminal/files/remove | POST | Deletes a file or an empty directory. |
Sources: internal/api/terminal_files.go:49-160, web/src/lib/api.ts:285-315
Constraints
- Path Validation: All paths must be absolute and are cleaned via
filepath.Cleanto prevent relative path traversal. - Upload Limits: Uploads are capped at a specific size (e.g., 256 MiB in production).
- Listing Limits: Directory listings are capped (e.g., 5000 entries) to prevent memory exhaustion.
- Timeouts: Each file operation has a 30s timeout.
Sources: internal/api/terminal_files.go:21-35, SECURITY.md:82-87
Host Monitoring (Ops Page)
The "运维" (Ops) sub-tab provides real-time visibility into host resources. It polls system data at regular intervals (default 3 seconds) using the control plane's system endpoints.
Monitored Metrics
- CPU: Individual core count and total system usage percentage.
- Memory: Total, used, and cached memory, including Swap usage.
- Load: System load averages for 1, 5, and 15-minute intervals.
- Network: Real-time download (RX) and upload (TX) rates.
- Storage: Disk usage per mount point, including filesystem types and percentage used.
- Processes: CPU and RSS memory usage for the
hx-proxygroupd(control plane) andmihomo(data plane) processes.
Sources: web/src/components/terminal/ops-page.tsx:43-110, web/src/lib/api.ts:160-195
Configuration
The terminal and its helper are configured via environment variables and command-line flags during daemon startup.
| Flag / Variable | Default | Description |
|---|---|---|
HX_PROXYGROUP_TERMINAL | 1 | Enables/disables the terminal feature (0 to disable). |
HX_PROXYGROUP_TERMINAL_HISTORY | 1 | Enables/disables shell command history persistence. |
--terminal-socket | /run/hx-proxygroup/terminal.sock | Path to the Unix socket for the root helper. |
--terminal-shell | (System Default) | The shell executable to launch (e.g., /bin/bash). |
--terminal-max-sessions | 2 | Maximum concurrent PTY sessions allowed. |
Sources: SECURITY.md:52-60, cmd/hx-proxygroupd/main.go:88-100, cmd/hx-proxygroupd/main.go:390-405
Conclusion
The Web Terminal & Host Control module integrates low-level system administration into the web management interface. By combining PTY streaming, file management, and host metrics while enforcing strict MFA and privileged helper validation, it provides a powerful yet secure tool for server maintenance. Adminstrators should disable the feature when not in use to minimize the residual risk of authorized but damaging command execution.
Sources: SECURITY.md:89-94