sshd

README

---

stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Overview

This package is responsible for handling SSH connections.

Since GitLab 13.9, gitlab-shell provides an option to either use OpenSSH to handle connections or utilize an internal implementation. For more information on the internal implementation, see the Why we implemented our own SSHD solution blog post.

The package contains multiple public functions:

• func NewServer for initializing Server.
• func (s *Server) ListenAndServe for listening to new connections and serving them.
• func (s *Server) Shutdown for shutting down the server.
• func (s *Server) MonitoringServeMux that provides monitoring endpoints.

All these functions are used by the main function to initialize and shutdown the server. When a client tries to connect to the server, the following sequence of steps happens:

• When a new connection is accepted by the listener, it's asynchronously handled.
• A new connection is created with a customized server config that allows the server to perform the handshake that verifies the authorized keys via a request to Gitlab Rails. The server is ready to handle sessions via this connection. The reason why we handle the sessions in a loop is the persisting connections: a connection remains open and reused for the future sessions.
• A new session is handled by the channelHandler function passed as a parameter. This function processes requests from the client.
• The client may send env requests in order to set an environment variable but we restrict it to only setting Git protocol version. The client eventually executes a command either via shell or exec requests.
• When the command is executed, we create a command of a particular type. More information on how the commands work can be found here.
• When a command is executed, the session is closed and the error about unsuccessful execution, if such took place, is tracked.
• If a connection has been prematurely closed we block execution until all concurrent sessions are released.

Proxy protocol

The package supports creating a server with PROXY protocol. The go-proxyproto package is used to wrap the basic listener into the one that supports PROXY protocol. PROXY protocol enables us to implement Group IP address restriction via SSH. The policies are configurable.

Configurable OpenSSH alternatives

• LoginGraceTime is implemented via TCP deadlines.
• ClientAliveInterval is implemented via sending keep-alive message periodically.

State machine

The server maintains a state machine to implement:

• Graceful shutdown. When a termination signal has been detected, then a service is being shut down. The status is changed accordingly and no new connections are accepted. A configurable grace period is given in order to allow the ongoing connections to complete. When the period expires, then the top-level context is canceled. That means that all the ongoing HTTP and SSH connections are closed.
• Liveness and readiness probes that help Kubernetes to evaluate the state of the server. If a state is any other than ready (for example, during graceful shutdown), then 502 is returned.

Documentation

Index

• Constants
• Variables
• type Server
  • func NewServer(cfg *config.Config) (*Server, error)
  • func (s *Server) ListenAndServe(ctx context.Context) error
  • func (s *Server) MonitoringServeMux() *http.ServeMux
  • func (s *Server) Shutdown() error

Constants

const (
	KeepAliveMsg   = "keepalive@openssh.com"
	NotOurRefError = `exit status 128, stderr: "fatal: git upload-pack: not our ref `
)

const (
	StatusStarting status = iota
	StatusReady
	StatusOnShutdown
	StatusClosed
)

Variables

var EOFTimeout = 10 * time.Second

Types

type Server

type Server struct {
	Config *config.Config
	// contains filtered or unexported fields
}

func NewServer

func NewServer(cfg *config.Config) (*Server, error)

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(ctx context.Context) error

func (*Server) MonitoringServeMux

func (s *Server) MonitoringServeMux() *http.ServeMux

func (*Server) Shutdown

func (s *Server) Shutdown() error