Aggregator & Broadcaster Service
Relevant source files
The following files were used as context for generating this wiki page:
The Aggregator & Broadcaster Service is a management layer within the sshpiper ecosystem designed to centralize the monitoring and control of multiple sshpiperd instances. At its core, individual sshpiperd daemons expose an Admin gRPC API that provides real-time data about active SSH pipes. The sshpiperd-webadmin component acts as an aggregator, connecting to these distributed gRPC endpoints to present a unified view through a web UI and JSON HTTP API.
This service allows administrators to perform critical management tasks across a cluster, including listing live sessions, viewing terminal output (via asciicast streaming), and terminating specific connections. It is intentionally decoupled from the main proxy logic to allow for restricted network access and dedicated management hosting.
Sources: cmd/sshpiperd-webadmin/main.go:1-12, README.md:120-134
System Architecture
The architecture consists of a distributed set of sshpiperd nodes (Broadcasters) and a central sshpiperd-webadmin server (Aggregator).
Data Flow Overview
The diagram shows how multiple sshpiperd instances broadcast their state to a central aggregator which serves the final user interface.
Sources: cmd/sshpiperd-webadmin/main.go:1-15, libadmin/admin.proto:11-23
Admin gRPC API (Broadcaster)
Each sshpiperd instance can optionally enable its admin interface by specifying an --admin-grpc-port. When enabled, the instance acts as a broadcaster, responding to management queries.
Key RPC Methods
| Method | Request | Response | Description |
|---|---|---|---|
ServerInfo | ServerInfoRequest | ServerInfoResponse | Returns the unique ID, version, and uptime of the daemon. |
ListSessions | ListSessionsRequest | ListSessionsResponse | Returns a list of all currently active piped SSH sessions. |
KillSession | KillSessionRequest | KillSessionResponse | Terminates both downstream and upstream connections for a specific ID. |
StreamSession | StreamSessionRequest | stream SessionFrame | Streams real-time terminal output in asciicast v2 format. |
Sources: libadmin/admin.proto:11-23, libadmin/admin.pb.go:420-435
Security and TLS
The admin API supports several security modes:
- Plaintext: Enabled via
--admin-grpc-insecure. Only recommended for trusted local networks. - Standard TLS: Requires
--admin-grpc-tls-certand--admin-grpc-tls-key. - Mutual TLS (mTLS): Enforced by providing
--admin-grpc-tls-cacert, requiring clients to present a certificate signed by the specified CA.
Sources: cmd/sshpiperd/main.go:21-47, cmd/sshpiperd/main.go:343-370
The Aggregator Service
The Aggregator component in sshpiperd-webadmin manages the lifecycle of connections to various sshpiperd endpoints. It uses a Discovery mechanism to locate instances and maintains a background refresh loop to keep server information current.
Aggregator Logic and State
The aggregator performs periodic polling of the configured endpoints to detect health changes and update the session cache.
The sequence diagram illustrates the background refresh loop that maintains the registry of active sshpiperd nodes.
Sources: cmd/sshpiperd-webadmin/internal/aggregator/aggregator.go:21-65, cmd/sshpiperd-webadmin/main.go:110-120
Configuration Parameters
| Flag / Env Var | Default | Description |
|---|---|---|
--sshpiperd | N/A | Address of a sshpiperd gRPC endpoint. Can be repeated. |
--refresh-interval | 30s | How often to refresh the discovered endpoint list and cache. |
--allow-kill | true | Enables or disables session termination via the API/UI. |
Sources: cmd/sshpiperd-webadmin/main.go:66-100
Session Streaming and Management
One of the most complex features of the service is the real-time streaming of SSH terminal output. This is achieved by wrapping session data into asciicast v2 frames.
Streaming Data Structures
The data is transmitted as a stream of SessionFrame messages, which can contain either a header (terminal dimensions/metadata) or an event (output data/resizes).
This class diagram represents the structure of the data frames used for live terminal monitoring.
Sources: libadmin/admin.proto:74-106, libadmin/admin.pb.go:264-300
HTTP/SSE Forwarding
The webadmin server converts the gRPC stream into a browser-friendly Server-Sent Events (SSE) stream. When a user requests a session stream via /api/v1/sessions/{instance}/{id}/stream, the Aggregator:
- Identifies the correct
sshpiperdinstance. - Opens a gRPC
StreamSessioncall. - Marshals
SessionFrameobjects into JSON. - Flushes them to the HTTP response as SSE events (e.g.,
event: o,event: r).
Sources: cmd/sshpiperd-webadmin/internal/httpapi/httpapi.go:210-255
Conclusion
The Aggregator & Broadcaster Service provides a robust management framework for sshpiper. By leveraging gRPC for internal communication and SSE/HTTP for the frontend, it enables scalable, real-time monitoring of SSH traffic across distributed proxy nodes. The separation of the webadmin tool ensures that management traffic can be isolated from the high-performance SSH proxying path, maintaining the security and stability of the core system.