Webadmin HTTP API
Relevant source files
The following files were used as context for generating this wiki page:
The Webadmin HTTP API is the core communication layer for the sshpiperd-webadmin component. It serves as an aggregator and proxy, exposing a browser-friendly RESTful interface and a JSON API that interacts with one or more sshpiperd instances via their internal gRPC admin endpoints.
The primary purpose of this API is to provide a unified dashboard for managing distributed SSH proxy instances. It allows administrators to list live SSH sessions across a cluster, view real-time terminal output through Server-Sent Events (SSE), and terminate active connections. By decoupling the administrative interface from the core sshpiperd daemon, it enables management from restricted network zones and centralized control over multiple piper deployments.
Sources: cmd/sshpiperd-webadmin/main.go:5-12, README.md:120-130
System Architecture
The Webadmin HTTP API operates as a middle tier between the frontend web interface and the backend sshpiperd daemons. It utilizes an aggregator to maintain connections to various gRPC endpoints.
Data Flow Overview
The following diagram illustrates how a user request flows through the Webadmin component to reach the underlying sshpiperd instances.
The Webadmin server dials gRPC endpoints (managed by libadmin) and translates these responses into JSON for the frontend.
Sources: cmd/sshpiperd-webadmin/main.go:120-145, examples/webadmin/README.md:46-55
API Endpoints
The HTTP API is structured under the /api/v1/ prefix. It provides endpoints for system metadata, instance status, and session management.
Endpoint Summary
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/version | Returns the webadmin version and allow-kill capability status. |
GET | /api/v1/instances | Lists all reachable sshpiperd instances and their metadata. |
GET | /api/v1/sessions | Aggregates and returns all live SSH sessions from all instances. |
DELETE | /api/v1/sessions/:instance/:id | Terminates a specific SSH session on a specific instance. |
GET | /api/v1/sessions/:instance/:id/stream | Provides a real-time SSE stream of terminal output. |
Sources: cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:105-235, cmd/sshpiperd-webadmin/main.go:150-155
Session Management
The API allows for granular control over active pipes. When a session is requested, the aggregator queries all connected gRPC backends defined in the SshPiperAdmin service.
Configuration and Security
The HTTP API is configured via command-line flags or environment variables. It supports both insecure plaintext communication and mutual TLS (mTLS) for backend gRPC connections.
Command Line Configuration
| Flag | Env Var | Default | Description |
|---|---|---|---|
--address | SSHPIPERD_WEBADMIN_ADDRESS | 127.0.0.1 | HTTP listening address. |
--port | SSHPIPERD_WEBADMIN_PORT | 8080 | HTTP listening port. |
--sshpiperd | SSHPIPERD_WEBADMIN_ENDPOINTS | - | Comma-separated list of gRPC host:port. |
--allow-kill | SSHPIPERD_WEBADMIN_ALLOW_KILL | true | Enables/disables session termination via API. |
--insecure | SSHPIPERD_WEBADMIN_INSECURE | true | Use plaintext gRPC for backends. |
Sources: cmd/sshpiperd-webadmin/main.go:50-110
Security Logic
The API includes a "Read-Only" mode. If allow-kill is set to false, the DELETE endpoints are effectively disabled, and the UI reflects this state by hiding or disabling interaction elements. For secure production environments, the API should be configured with --tls-cacert, --tls-cert, and --tls-key to authenticate itself to sshpiperd admin endpoints.
Sources: cmd/sshpiperd-webadmin/main.go:148-155, cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:108-112
Data Models
The API uses data structures defined in libadmin/admin.proto for internal processing before serializing them to JSON.
Session Object
The session object represents an active pipe between a downstream client and an upstream server.
| Field | Type | Description |
|---|---|---|
id | string | Unique session identifier (UUID). |
downstream_user | string | Username used by the client. |
downstream_addr | string | IP/address of the client. |
upstream_user | string | Username used to connect to target. |
upstream_addr | string | Address of the target SSH server. |
started_at | int64 | Unix timestamp of session start. |
streamable | bool | Indicates if terminal recording/streaming is available. |
Sources: libadmin/admin.pb.go:183-210
Terminal Streaming (SSE)
Real-time terminal monitoring is implemented via Server-Sent Events. The API streams SessionFrame messages which are mirrors of the asciicast v2 format.
The frontend uses the EventSource API to consume these frames and renders them using xterm.js.
Sources: libadmin/admin.pb.go:379-410, cmd/sshpiperd-webadmin/internal/httpapi/web/src/app.js:450-510
Summary
The Webadmin HTTP API provides a powerful, centralized management layer for sshpiperd clusters. By abstracting the complex gRPC interactions with individual proxy instances into a simple REST and SSE-based JSON API, it enables the creation of rich administrative dashboards and automation scripts for monitoring and controlling SSH traffic in real-time.