Documentation
¶
Overview ¶
Package sshproxy serves the SSH upgrade endpoints on the API server. It has two roles:
Tunnel endpoint (GET /model/:modeluuid/ssh-tunnel/:tunnelID): machine agents push reverse SSH tunnels to the controller.
Relay endpoint (GET /ssh-relay/:virtualHostname): user SSH sessions, relayed blind by an intermediary such as JIMM, terminate in the embedded SSH server built via TerminatingServerFactory. This lets the intermediary intermediary handle authentication on behalf of a user.
The wire-level upgrade helpers shared with the agent-side dialer live in core/sshproxy, since this package's internal path is only importable from within apiserver.
Index ¶
Constants ¶
const ( // ReasonMissingJWT means no relay JWT was received. ReasonMissingJWT = "missing_jwt" // ReasonDenied means the relay JWT lacked access. ReasonDenied = "denied" // ReasonOverCapacity means the relay was at its connection cap. ReasonOverCapacity = "over_capacity" )
Relay rejection reasons, used as metric label values.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuthenticatedMachineNameKey ¶
type AuthenticatedMachineNameKey struct{}
AuthenticatedMachineNameKey is the context key for the authenticated machine name, set by the apiserver from the request's auth info.
type RelayHandler ¶
type RelayHandler struct {
// contains filtered or unexported fields
}
RelayHandler implements the JIMM relay upgrade endpoint:
GET /ssh-relay/:virtualHostname
JIMM authenticates with a bearer JWT in the Authorization header (the same external-auth flow the API server already supports on HTTP endpoints). After the upgrade, the user's SSH session - relayed blind by JIMM - terminates in the embedded SSH server built here.
The handler is a worker: the apiserver attaches it to its catacomb, so killing it cancels the request contexts of in-flight relays. Each relay watches its request context and closes its hijacked connection when the handler dies, draining the relays on apiserver shutdown (hijacked connections are invisible to http.Server.Shutdown).
func NewRelayHandler ¶
func NewRelayHandler(config RelayHandlerConfig) (*RelayHandler, error)
NewRelayHandler returns a new JIMM relay endpoint handler.
func (*RelayHandler) ServeHTTP ¶
func (h *RelayHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler.
type RelayHandlerConfig ¶
type RelayHandlerConfig struct {
// Logger is used for logging.
Logger logger.Logger
// ServerFactory builds the per-destination terminating SSH server.
ServerFactory TerminatingServerFactory
// MaxConcurrentConnections returns the maximum number of concurrent
// relays served at once. It is read per request so runtime
// controller-config changes take effect without rebuilding the
// handler. Each relay holds a hijacked connection for the life of the
// SSH session, so the cap bounds the connections, goroutines and
// per-connection lookups the endpoint can accumulate. The cap is
// per-endpoint: the relay and jump server count separately.
MaxConcurrentConnections func() int
// SessionDuration observes the duration of each relayed session.
SessionDuration prometheus.Histogram
// Rejections counts rejected relays by reason.
Rejections *prometheus.CounterVec
// Clock is used to time relayed sessions.
Clock clock.Clock
}
RelayHandlerConfig holds the configuration for the JIMM relay endpoint.
func (RelayHandlerConfig) Validate ¶
func (cfg RelayHandlerConfig) Validate() error
Validate checks whether the configuration is valid.
type RelayJWTKey ¶
type RelayJWTKey struct{}
RelayJWTKey is the context key for the relay JWT, set by the apiserver from the request's auth info.
type TerminatingServerFactory ¶
type TerminatingServerFactory interface {
// New returns a terminating SSH server for the destination, with proxy
// handlers and the destination's host key configured.
New(ctx context.Context, destination virtualhostname.Info) (*gliderssh.Server, error)
}
TerminatingServerFactory builds terminating SSH servers for routed destinations. It is satisfied by the factory the SSH server worker outputs.
type TunnelHandler ¶
type TunnelHandler struct {
// contains filtered or unexported fields
}
TunnelHandler implements the model-scoped agent tunnel upgrade endpoint:
GET /model/:modeluuid/ssh-tunnel/:tunnelID
A machine agent dials this endpoint on a new HTTPS connection to one of the controller addresses from its SSH connection request. Authentication happens at the HTTP layer (model-scoped agent-password login, the same mechanism as /logsink). The tunnel ID must be known to this node's tracker.
The handler is a worker: it owns the hijacked tunnel connections until they end, so the apiserver attaches it to its catacomb. Killing the handler closes every live tunnel connection, draining them on apiserver shutdown (hijacked connections are invisible to http.Server.Shutdown).
func NewTunnelHandler ¶
func NewTunnelHandler(config TunnelHandlerConfig) (*TunnelHandler, error)
NewTunnelHandler returns a new agent tunnel endpoint handler.
func (*TunnelHandler) ServeHTTP ¶
func (h *TunnelHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements http.Handler.
type TunnelHandlerConfig ¶
type TunnelHandlerConfig struct {
// Logger is used for logging.
Logger logger.Logger
// Tracker is the local controller node's tunnel tracker. Tunnel IDs
// created on other nodes are rejected, preserving origin controller
// affinity.
Tracker TunnelTracker
}
TunnelHandlerConfig holds the configuration for the agent tunnel endpoint.
func (TunnelHandlerConfig) Validate ¶
func (cfg TunnelHandlerConfig) Validate() error
Validate checks whether the configuration is valid.
type TunnelTracker ¶
type TunnelTracker interface {
// PushTunnel publishes an established network connection for the tunnel
// identified by tunnelID, on behalf of the named machine. The machine
// name must match the machine the tunnel was requested for. The
// returned channel is closed when the pushed connection is closed.
PushTunnel(ctx context.Context, tunnelID, machineName string, conn net.Conn) (<-chan struct{}, error)
}
TunnelTracker accepts reverse tunnel connections pushed by machine agents. It is the same interface exposed by the sshtunneler worker.