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

Overview

Package sshd provides functionality for SSH daemon connections.

Package sshd implements functionality related to SSH server configuration and handling

Package sshd provides functionality for handling SSH sessions

Package sshd provides functionality for handling SSH connections

Index

• Constants
• Variables
• type OSGSSAPIServer
  • func NewGSSAPIServer(c *config.GSSAPIConfig) (*OSGSSAPIServer, error)
  • func (*OSGSSAPIServer) AcceptSecContext([]byte) ([]byte, string, bool, error)
  • func (*OSGSSAPIServer) DeleteSecContext() error
  • func (*OSGSSAPIServer) VerifyMIC([]byte, []byte) error
• 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 is the message used for keeping SSH connections alive.
	KeepAliveMsg = "keepalive@openssh.com"

	// NotOurRefError represents the error message indicating that the git upload-pack is not our reference
	NotOurRefError = `exit status 128, stderr: "fatal: git upload-pack: not our ref `
)

const (
	// StatusStarting represents the starting status of the SSH server
	StatusStarting status = iota

	// StatusReady represents the ready status of the SSH server
	StatusReady

	// StatusOnShutdown represents the status when the SSH server is shutting down
	StatusOnShutdown

	// StatusClosed represents the closed status of the SSH server
	StatusClosed
)

Variables

var EOFTimeout = 10 * time.Second

EOFTimeout specifies the timeout duration for EOF (End of File) in SSH connections

Types

type OSGSSAPIServer

type OSGSSAPIServer struct {
	ServicePrincipalName string
}

func NewGSSAPIServer

func NewGSSAPIServer(c *config.GSSAPIConfig) (*OSGSSAPIServer, error)

func (*OSGSSAPIServer) AcceptSecContext

func (*OSGSSAPIServer) AcceptSecContext([]byte) ([]byte, string, bool, error)

func (*OSGSSAPIServer) DeleteSecContext

func (*OSGSSAPIServer) DeleteSecContext() error

func (*OSGSSAPIServer) VerifyMIC

func (*OSGSSAPIServer) VerifyMIC([]byte, []byte) error

type Server

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

Server represents an SSH server instance

func NewServer

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

NewServer creates a new instance of Server

func (*Server) ListenAndServe

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

ListenAndServe starts listening for SSH connections and serves them

func (*Server) MonitoringServeMux

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

MonitoringServeMux returns the ServeMux for monitoring endpoints

func (*Server) Shutdown

func (s *Server) Shutdown() error

Shutdown gracefully shuts down the SSH server