Web Admin Dashboard

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js
• cmd/sshpiperd-webadmin/internal/httpapi/web/index.html
• cmd/sshpiperd-webadmin/main.go
• cmd/sshpiperd-webadmin/internal/httpapi/web/README.md
• cmd/sshpiperd/main.go
• README.md
• examples/webadmin/README.md

The Web Admin Dashboard (implemented via sshpiperd-webadmin) is a browser-based management interface designed to aggregate and monitor one or more sshpiperd instances. It connects to the admin gRPC API exposed by sshpiperd to provide real-time visibility into active SSH sessions, live terminal streaming, and session management capabilities.

Sources: cmd/sshpiperd-webadmin/main.go:1-12, README.md:88-105

Architecture Overview

The dashboard operates as a standalone binary that acts as an aggregator. It discovers sshpiperd endpoints, caches server information, and translates gRPC data into a browser-friendly HTTP/JSON API.

Components and Technologies

• Frontend: Hand-rolled vanilla JavaScript using ES module imports, bundled with esbuild.
• Terminal Emulation: Uses xterm.js with the addon-fit for viewing live sessions.
• Aggregator: A Go-based backend that manages connections to multiple gRPC endpoints using libadmin.
• Data Streaming: Uses Server-Sent Events (SSE) to stream live terminal output from sshpiperd to the browser.

Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/README.md:1-15, cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:6-10

Features and Capabilities

Session Monitoring

The dashboard provides a "Live Sessions" table that displays real-time SSH connections piped through the cluster. Users can filter sessions by username, address, or instance ID.

Feature	Description
Instance Listing	Displays reachable instances, their versions, and start times.
Live Streaming	Real-time terminal output via xterm.js for "streamable" sessions.
Session Killing	Ability to terminate specific SSH sessions across the cluster.
Asciicast Recording	Captures live terminal streams into .cast files locally in the browser.
mTLS Support	Secure communication between WebAdmin and sshpiperd using mutual TLS.

Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/index.html:105-156, cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:180-210, cmd/sshpiperd-webadmin/main.go:50-90

Live Terminal Viewer

The viewer component utilizes a <dialog> element to host an xterm.js instance. It connects to an SSE endpoint /api/v1/sessions/:instance/:id/stream to receive terminal frames.

Configuration Options

The sshpiperd-webadmin service is configured via command-line flags or environment variables.

Flag	Env Var	Default	Description
--sshpiperd	SSHPIPERD_WEBADMIN_ENDPOINTS	-	gRPC endpoints of sshpiperd (host:port).
--insecure	SSHPIPERD_WEBADMIN_INSECURE	true	Use plaintext gRPC for connections.
--allow-kill	SSHPIPERD_WEBADMIN_ALLOW_KILL	true	Enable/disable the ability to terminate sessions.
--refresh-interval	SSHPIPERD_WEBADMIN_REFRESH_INTERVAL	30s	Frequency of instance/ServerInfo cache refresh.
--web-static-path	SSHPIPERD_WEBADMIN_WEB_STATIC_PATH	-	Path for custom UI files; empty uses embedded.

Sources: cmd/sshpiperd-webadmin/main.go:50-100, README.md:107-115

Backend API Specification

The Web Admin dashboard interacts with a JSON HTTP API exposed by the Go backend.

Endpoints

• GET /api/v1/version: Returns the backend version and the allow_kill status.
• GET /api/v1/instances: Lists all discovered and reachable sshpiperd instances.
• GET /api/v1/sessions: Aggregates all live sessions from all instances.
• DELETE /api/v1/sessions/:instance/:id: Requests an instance to kill a specific session.
• GET /api/v1/sessions/:instance/:id/stream: Opens an SSE stream for live terminal viewing.

Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:140-148, 220-225, 477

Deployment in sshpiperd

For the dashboard to function, the sshpiperd daemon must be started with the admin gRPC API enabled.

./out/sshpiperd --admin-grpc-port 8222 \
  --admin-grpc-tls-cert server.crt \
  --admin-grpc-tls-key server.key \
  ... <plugin> ...

Sources: README.md:92-97, cmd/sshpiperd/main.go:394-420

Security Considerations

• Authentication: Production deployments should use --admin-grpc-tls-cacert to enforce mutual TLS (mTLS).
• Insecure Mode: Plaintext gRPC (--admin-grpc-insecure) is only recommended for trusted local networks or behind a secure reverse proxy.
• Read-Only Mode: The web dashboard can be set to read-only by passing --allow-kill=false.

Sources: README.md:99-105, cmd/sshpiperd-webadmin/main.go:85-90, cmd/sshpiperd/main.go:420-435

Conclusion

The Web Admin Dashboard provides a centralized, user-friendly interface for managing complex sshpiperd clusters. By leveraging gRPC for internal cluster communication and modern web technologies like SSE and xterm.js for the UI, it enables efficient real-time monitoring and administrative control over secure SSH traffic.