Admin gRPC API

Relevant source files

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

• libadmin/admin.proto
• libadmin/admin.pb.go
• libadmin/admin_grpc.pb.go
• cmd/sshpiperd/main.go
• cmd/sshpiperd-admin/main.go
• cmd/sshpiperd-webadmin/main.go
• cmd/sshpiperd/internal/admin/server_test.go

The Admin gRPC API is a management interface provided by sshpiperd that enables out-of-band inspection and control of active SSH sessions. It allows external administrative tools to retrieve server metadata, list currently piped sessions, terminate specific connections, and live-stream terminal output in real-time.

This API is designed for consumption by specialized clients, including the browser-based sshpiperd-webadmin dashboard and the sshpiperd-admin command-line utility. By exposing these management capabilities over gRPC, the system supports multi-instance aggregation and remote orchestration of the SSH reverse proxy infrastructure.
Sources: libadmin/admin_grpc.pb.go:27-31, README.md:104-110

Architecture Overview

The Admin API follows a client-server architecture where sshpiperd acts as the gRPC server. The service definition is centralized in libadmin, which provides the protobuf definitions and generated Go client/server code.

The diagram shows how the Admin gRPC Server interacts with the internal Session Registry to manage the SSH flows.
Sources: cmd/sshpiperd/main.go:420-435, libadmin/admin.proto:114-124

Service Definition

The core of the management interface is the SshPiperAdmin service, which defines four primary RPC methods:

Method	Type	Description
ServerInfo	Unary	Returns instance ID, version, and uptime metadata.
ListSessions	Unary	Returns a list of all active Session objects.
KillSession	Unary	Terminates a session by ID, closing both upstream and downstream.
StreamSession	Server Streaming	Streams real-time SessionFrame data (Asciicast v2 format).

Sources: libadmin/admin.proto:114-124, libadmin/admin_grpc.pb.go:34-45

Session Data Model

Each active session is represented by a Session message containing connectivity details for both the client (downstream) and the target server (upstream).

message Session {
  string id = 1;
  string downstream_user = 2;
  string downstream_addr = 3;
  string upstream_user = 4;
  string upstream_addr = 5;
  int64 started_at = 6;
  bool streamable = 7;
}

Sources: libadmin/admin.proto:42-53

Server Configuration

The Admin gRPC API is disabled by default and must be explicitly enabled using the --admin-grpc-port flag. Security is a primary concern, as the API allows killing connections and viewing terminal data.

Configuration Flags

Flag	Default	Description
--admin-grpc-address	127.0.0.1	Binding address for the API.
--admin-grpc-port	0	Port for the API; must be non-zero to enable.
--admin-grpc-insecure	false	Disables TLS. Recommended only for trusted networks.
--admin-grpc-tls-cert	""	Path to server PEM certificate.
--admin-grpc-tls-key	""	Path to server PEM private key.
--admin-grpc-tls-cacert	""	CA cert for verifying clients (enables mTLS).

Sources: cmd/sshpiperd/main.go:284-332, README.md:111-120

Security and TLS

The server supports standard TLS and mutual TLS (mTLS). When --admin-grpc-tls-cacert is provided, the server enforces tls.RequireAndVerifyClientCert, ensuring only clients with a certificate signed by the specified CA can connect.
Sources: cmd/sshpiperd/main.go:36-60

Session Streaming (Asciicast v2)

The StreamSession RPC provides real-time terminal output observation. The server encapsulates terminal data into SessionFrame messages, which follow the Asciicast v2 format.

The sequence diagram illustrates the lifecycle of a terminal stream, starting with a header followed by continuous output ("o") or resize ("r") events.
Sources: libadmin/admin.proto:85-112, cmd/sshpiperd-admin/main.go:387-410

Frame Types

1. AsciicastHeader: Sent as the first frame. Contains terminal width, height, and environment variables like TERM.
2. AsciicastEvent: Contains the actual data. kind is usually "o" (output) or "r" (resize). For output, data contains the raw terminal bytes.
   Sources: libadmin/admin.proto:92-112, libadmin/admin.pb.go:377-400

Aggregation and Discovery

Administrative clients like sshpiperd-webadmin often manage multiple sshpiperd instances. The libadmin package provides an Aggregator and a Discovery interface to facilitate this.

• Static Discovery: A simple implementation that takes a list of hardcoded host:port endpoints.
• Aggregator: Handles the logic of connecting to multiple backends, refreshing their ServerInfo caches, and routing requests (like KillSession) to the specific instance hosting a session.

Sources: cmd/sshpiperd-webadmin/main.go:131-140, cmd/sshpiperd-admin/main.go:167-175

Aggregator Refresh Cycle

This flowchart describes the background process used by aggregating clients to maintain a healthy view of the cluster.
Sources: cmd/sshpiperd-webadmin/main.go:68-73, cmd/sshpiperd-webadmin/main.go:146-150

Summary

The Admin gRPC API provides a powerful, secure, and extensible management layer for sshpiperd. By leveraging gRPC and the Asciicast v2 format, it enables sophisticated observability and control of SSH traffic, ranging from simple CLI tools to multi-instance web dashboards. Its support for mTLS ensures that these high-privilege operations remain restricted to authorized administrative entities.