mysql

Documentation

Overview

Package mysql implements MySQL protocol support for the database access.

It has the following components:

• Proxy. Runs inside Teleport proxy and proxies connections from MySQL clients to appropriate Teleport database services over reverse tunnel.

• Engine. Runs inside Teleport database service, accepts connections coming from proxy over reverse tunnel and proxies them to MySQL databases.

Protocol --------

MySQL protocol consists of two phases, connection phase and command phase.

The proxy component implements the connection phase in order to be able to get client's x509 certificate which contains all the auth and routing information in it:

https://dev.mysql.com/doc/internals/en/connection-phase.html
https://dev.mysql.com/doc/internals/en/ssl-handshake.html
https://dev.mysql.com/doc/internals/en/connection-phase-packets.html

The engine component plugs into the command phase and interperts all protocol messages flying through it:

https://dev.mysql.com/doc/internals/en/command-phase.html

MySQL protocol is server-initiated meaning the first "handshake" packet is sent by MySQL server, as such the proxy (which acts as a server) has a separate listener for MySQL clients.

Connection sequence diagram:

mysql proxy

|                        |
| <--- HandshakeV10 ---  |
|                        |
| - HandshakeResponse -> |
|                        |

------- TLS upgrade -------- engine

|                        |                      |
|                        | ----- connect -----> |
|                        |                      |
|                        |               ---- authz ----            MySQL
|                        |                      |                     |
|                        |                      | ----- connect ----> |
|                        |                      |                     |
|                        | <------- OK -------- |                     |
|                        |                      |                     |
| <-------- OK --------- |                      |                     |
|                        |                      |                     |

------------------------------ Command phase ----------------------------

|                        |                      |                     |
| ----------------------------- COM_QUERY --------------------------> |
| <---------------------------- Response ---------------------------- |
|                        |                      |                     |
| ----------------------------- COM_QUIT ---------------------------> |
|                        |                      |                     |

Index

• Constants
• Variables
• func FetchMySQLVersion(ctx context.Context, database types.Database) (string, error)
• func MakeTestClient(config common.TestClientConfig) (*client.Conn, error)
• func MakeTestClientWithoutTLS(addr string, routeToDatabase tlsca.RouteToDatabase) (*client.Conn, error)
• func NewEngine(ec common.EngineConfig) common.Engine
• type Engine
  • func (e *Engine) ActivateUser(ctx context.Context, sessionCtx *common.Session) error
  • func (e *Engine) DeactivateUser(ctx context.Context, sessionCtx *common.Session) error
  • func (e *Engine) DeleteUser(ctx context.Context, sessionCtx *common.Session) error
  • func (e *Engine) HandleConnection(ctx context.Context, sessionCtx *common.Session) error
  • func (e *Engine) InitializeConnection(clientConn net.Conn, _ *common.Session) error
  • func (e *Engine) SendError(err error)
• type Proxy
  • func (p *Proxy) HandleConnection(ctx context.Context, clientConn net.Conn) (err error)
• type TestServer
  • func NewTestServer(config common.TestServerConfig, opts ...TestServerOption) (svr *TestServer, err error)
  • func (s *TestServer) Close() error
  • func (s *TestServer) ConnsClosed() bool
  • func (s *TestServer) Port() string
  • func (s *TestServer) QueryCount() uint32
  • func (s *TestServer) Serve() error
  • func (s *TestServer) UserEventsCh() <-chan UserEvent
• type TestServerOption
  • func WithServerVersion(serverVersion string) TestServerOption
• type UserEvent

Constants

const (
	// DefaultServerVersion is advertised to MySQL clients during handshake.
	//
	// Some clients may refuse to work with older servers (e.g. MySQL
	// Workbench requires > 5.5).
	DefaultServerVersion = "8.0.0-Teleport"
)

Variables

var TestQueryResponse = &mysql.Result{
	InsertId:     1,
	AffectedRows: 0,
}

TestQueryResponse is what test MySQL server returns to every query.

Functions

func FetchMySQLVersion

func FetchMySQLVersion(ctx context.Context, database types.Database) (string, error)

FetchMySQLVersion connects to MySQL database and tries to read the handshake packet and return the version. In case of error the message returned by the database is propagated in returned error.

func MakeTestClient

func MakeTestClient(config common.TestClientConfig) (*client.Conn, error)

MakeTestClient returns MySQL client connection according to the provided parameters.

func MakeTestClientWithoutTLS

func MakeTestClientWithoutTLS(addr string, routeToDatabase tlsca.RouteToDatabase) (*client.Conn, error)

MakeTestClientWithoutTLS returns a MySQL client connection without setting TLS config to the MySQL client.

func NewEngine

func NewEngine(ec common.EngineConfig) common.Engine

NewEngine create new MySQL engine.

Types

type Engine

type Engine struct {
	// EngineConfig is the common database engine configuration.
	common.EngineConfig
	// contains filtered or unexported fields
}

Engine implements the MySQL database service that accepts client connections coming over reverse tunnel from the proxy and proxies them between the proxy and the MySQL database instance.

Implements common.Engine.

func (*Engine) ActivateUser

func (e *Engine) ActivateUser(ctx context.Context, sessionCtx *common.Session) error

ActivateUser creates or enables the database user.

func (*Engine) DeactivateUser

func (e *Engine) DeactivateUser(ctx context.Context, sessionCtx *common.Session) error

DeactivateUser disables the database user.

func (*Engine) DeleteUser

func (e *Engine) DeleteUser(ctx context.Context, sessionCtx *common.Session) error

DeleteUser deletes the database user.

func (*Engine) HandleConnection

func (e *Engine) HandleConnection(ctx context.Context, sessionCtx *common.Session) error

HandleConnection processes the connection from MySQL proxy coming over reverse tunnel.

It handles all necessary startup actions, authorization and acts as a middleman between the proxy and the database intercepting and interpreting all messages i.e. doing protocol parsing.

func (*Engine) InitializeConnection

func (e *Engine) InitializeConnection(clientConn net.Conn, _ *common.Session) error

InitializeConnection initializes the engine with client connection.

func (*Engine) SendError

func (e *Engine) SendError(err error)

SendError sends an error to connected client in the MySQL understandable format.

type Proxy

type Proxy struct {
	// TLSConfig is the proxy TLS configuration.
	TLSConfig *tls.Config
	// Middleware is the auth middleware.
	Middleware *auth.Middleware
	// Service is used to connect to a remote database service.
	Service common.Service
	// Log is used for logging.
	Log logrus.FieldLogger
	// Limiter limits the number of active connections per client IP.
	Limiter *limiter.Limiter
	// IngressReporter reports new and active connections.
	IngressReporter *ingress.Reporter
	// ServerVersion allows to overwrite the default Proxy MySQL Engine Version. Note that for TLS Routing connection
	// the dynamic service version propagation by ALPN extension will take precedes over Proxy ServerVersion.
	ServerVersion string
}

Proxy proxies connections from MySQL clients to database services over reverse tunnel. It runs inside Teleport proxy service.

Implements common.Proxy.

func (*Proxy) HandleConnection

func (p *Proxy) HandleConnection(ctx context.Context, clientConn net.Conn) (err error)

HandleConnection accepts connection from a MySQL client, authenticates it and proxies it to an appropriate database service.

type TestServer

type TestServer struct {
	// contains filtered or unexported fields
}

TestServer is a test MySQL server used in functional database access tests.

func NewTestServer

func NewTestServer(config common.TestServerConfig, opts ...TestServerOption) (svr *TestServer, err error)

NewTestServer returns a new instance of a test MySQL server.

func (*TestServer) Close

func (s *TestServer) Close() error

Close closes the server listener.

func (*TestServer) ConnsClosed

func (s *TestServer) ConnsClosed() bool

ConnsClosed returns true if all connections has been correctly closed (message COM_QUIT), false otherwise.

func (*TestServer) Port

func (s *TestServer) Port() string

Port returns the port server is listening on.

func (*TestServer) QueryCount

func (s *TestServer) QueryCount() uint32

QueryCount returns the number of queries the server has received.

func (*TestServer) Serve

func (s *TestServer) Serve() error

Serve starts serving client connections.

func (*TestServer) UserEventsCh

func (s *TestServer) UserEventsCh() <-chan UserEvent

UserEventsCh returns channel that receives user activate/deactivate events.

type TestServerOption

type TestServerOption func(*TestServer)

TestServerOption allows to set test server options.

func WithServerVersion

func WithServerVersion(serverVersion string) TestServerOption

WithServerVersion sets the test MySQL server version.

type UserEvent

type UserEvent struct {
	// TeleportUser is the Teleport username.
	TeleportUser string
	// DatabaseUser is the in-database username.
	DatabaseUser string
	// Roles are the user Roles.
	Roles []string
	// Active is whether user activated or deactivated.
	Active bool
}

UserEvent represents a user activation/deactivation event.